使用 AI.GENERATE_TABLE 函式產生結構化資料

本文件說明如何使用 Gemini 模型產生結構化資料，然後使用 SQL 結構定義格式化模型的回應。

如要這樣做，請完成下列工作：

• 在任何一般可用或預先發布的 Gemini 模型上建立 BigQuery ML 遠端模型。
• 使用模型搭配 AI.GENERATE_TABLE 函式，根據標準表格中的資料產生結構化資料。

所需權限

• 如要建立連結，您必須具備下列身分與存取權管理 (IAM) 角色的成員資格：

  • roles/bigquery.connectionAdmin

• 如要將權限授予連線的服務帳戶，您必須具備下列權限：

  • resourcemanager.projects.setIamPolicy

• 如要使用 BigQuery ML 建立模型，您需要具備下列 IAM 權限：

  • bigquery.jobs.create
  • bigquery.models.create
  • bigquery.models.getData
  • bigquery.models.updateData
  • bigquery.models.updateMetadata

• 如要執行推論，您需要具備下列權限：

  • bigquery.tables.getData 在桌上
  • 模型的 bigquery.models.getData
  • bigquery.jobs.create

事前準備

1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Go to project selector

2. Make sure that billing is enabled for your Google Cloud project.

3. Enable the BigQuery, BigQuery Connection, and Vertex AI APIs.

   Enable the APIs

建立資料集

建立 BigQuery 資料集來容納資源：

建立連線

如果您已設定具備適當權限的預設連線，可以略過這個步驟。

為遠端模型建立Cloud 資源連線，並取得連線的服務帳戶。請在與您在上一個步驟中建立的資料集相同的位置建立連線。

選取下列選項之一：

# This queries the provider for project information.
data "google_project" "default" {}

# This creates a cloud resource connection in the US region named my_cloud_resource_connection.
# Note: The cloud resource nested object has only one output field - serviceAccountId.
resource "google_bigquery_connection" "default" {
  connection_id = "my_cloud_resource_connection"
  project       = data.google_project.default.project_id
  location      = "US"
  cloud_resource {}
}

授予服務帳戶存取權

為連線的服務帳戶授予 Vertex AI 使用者角色。

如果您打算在建立遠端模型時，將端點指定為網址 (例如 endpoint = 'https://us-central1-aiplatform.googleapis.com/v1/projects/myproject/locations/us-central1/publishers/google/models/gemini-1.5-flash')，請在網址中指定的專案中授予這個角色。

如果您打算在建立遠端模型時，使用模型名稱指定端點 (例如 endpoint = 'gemini-1.5-flash')，請在您打算建立遠端模型的專案中授予這個角色。

在其他專案中授予角色會導致 bqcx-1234567890-xxxx@gcp-sa-bigquery-condel.iam.gserviceaccount.com does not have the permission to access resource 錯誤。

如要授予角色，請按照下列步驟操作：

gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/aiplatform.user' --condition=None

建立 BigQuery ML 遠端模型

1. 前往 Google Cloud 控制台的「BigQuery」頁面。

   前往 BigQuery

2. 使用 SQL 編輯器建立遠端模型：

   CREATE OR REPLACE MODEL
   `PROJECT_ID.DATASET_ID.MODEL_NAME`
   REMOTE WITH CONNECTION {DEFAULT | `PROJECT_ID.REGION.CONNECTION_ID`}
   OPTIONS (ENDPOINT = 'ENDPOINT');

   請依指示取代下列項目：

   • PROJECT_ID：您的專案 ID
   • DATASET_ID：包含模型的資料集 ID。這個資料集必須位於與您使用的連線相同的位置
   • MODEL_NAME：模型名稱
   • REGION：連線使用的區域
   • CONNECTION_ID：BigQuery 連線的 ID

     在 Google Cloud 控制台查看連線詳細資料時，這是連線 ID 中顯示的完整限定連線 ID 最後一個部分的值，例如 projects/myproject/locations/connection_location/connections/myconnection

   • ENDPOINT：要使用的 Gemini 模型名稱。詳情請參閱 ENDPOINT。

產生結構化資料

使用遠端模型搭配 AI.GENERATE_TABLE 函式，並使用來自資料表欄的提示資料，產生結構化資料：

SELECT *
FROM AI.GENERATE_TABLE(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  [TABLE `PROJECT_ID.DATASET_ID.TABLE_NAME` / (PROMPT_QUERY)],
  STRUCT(TOKENS AS max_output_tokens, TEMPERATURE AS temperature,
  TOP_P AS top_p, STOP_SEQUENCES AS stop_sequences,
  SAFETY_SETTINGS AS safety_settings,
  OUTPUT_SCHEMA AS output_schema)
);

請依指示取代下列項目：

• PROJECT_ID：您的專案 ID。
• DATASET_ID：包含模型的資料集 ID。
• MODEL_NAME：模型名稱。
• TABLE_NAME：包含提示的資料表名稱。這個資料表必須有一個名為 prompt 的資料欄，或者您可以使用別名來使用名稱不同的資料欄。
• PROMPT_QUERY：產生提示資料的 GoogleSQL 查詢。提示值本身可從資料欄中提取，也可以將其指定為結構體值，並包含任意數量的字串和資料欄名稱子欄位。例如：SELECT ('Analyze the sentiment in ', feedback_column, 'using the following categories: positive, negative, neutral') AS prompt。
• TOKENS：INT64 值，可設定回覆中可產生的符記數量上限。這個值必須介於 [1,8192] 的範圍內。如要取得較短的回覆，請指定較低的值；如要取得較長的回覆，請調高此值。預設為 128。
• TEMPERATURE：範圍為 [0.0,2.0] 的 FLOAT64 值，用於控制選取符記時的隨機程度。預設為 1.0。

  如果您想藉由提示生成更具確定性、較不具開放性和創意性的回覆，建議調低 temperature 的值。另一方面，如果 temperature 的值較高，則可能產生較多元或有創意的結果。temperature 的 0 值為確定值，表示系統一律會選取可能性最高的回覆。

• TOP_P：範圍內的 FLOAT64 值 [0.0,1.0] 有助於判斷符記的選取機率。如要取得較不隨機的回覆，請指定較低的值；如要取得較隨機的回覆，請調高此值。預設為 0.95。
• STOP_SEQUENCES：如果模型回應中包含指定字串，則會移除該字串的 ARRAY 值。字串比對時會完全相符，包括大小寫。預設為空陣列。
• SAFETY_SETTINGS：用於設定內容安全門檻以篩選回應的 ARRAY> 值。結構體中的第一個元素會指定危害類別，而結構體中的第二個元素會指定相應的封鎖門檻。模型會過濾違反這些設定的內容。每個類別只能指定一次。舉例來說，您無法同時指定 STRUCT('HARM_CATEGORY_DANGEROUS_CONTENT' AS category, 'BLOCK_MEDIUM_AND_ABOVE' AS threshold) 和 STRUCT('HARM_CATEGORY_DANGEROUS_CONTENT' AS category, 'BLOCK_ONLY_HIGH' AS threshold)。如果特定類別沒有安全設定，系統會使用 BLOCK_MEDIUM_AND_ABOVE 安全設定。

  支援的類別如下：

  • HARM_CATEGORY_HATE_SPEECH
  • HARM_CATEGORY_DANGEROUS_CONTENT
  • HARM_CATEGORY_HARASSMENT
  • HARM_CATEGORY_SEXUALLY_EXPLICIT

  支援的門檻如下：

  • BLOCK_NONE (受限)
  • BLOCK_LOW_AND_ABOVE
  • BLOCK_MEDIUM_AND_ABOVE (預設)
  • BLOCK_ONLY_HIGH
  • HARM_BLOCK_THRESHOLD_UNSPECIFIED

  詳情請參閱「有害內容類別」和「如何設定內容篩選器」。

• OUTPUT_SCHEMA：指定模型回應格式的 STRING 值。output_schema 值必須是 SQL 結構定義，類似於 CREATE TABLE 陳述式中使用的結構定義。支援的資料類型如下：
  • INT64
  • FLOAT64
  • BOOL
  • STRING
  • ARRAY
  • STRUCT

  針對 Gemini 1.5 模型，只有在您確定傳回值不會是捨入值時，才指定 FLOAT64 資料類型。這些模型有時會傳回 INT64 值，而不是 FLOAT64 值來表示整數，例如 2 而非 2.0，這可能會導致查詢中發生剖析錯誤。

  使用 output_schema 引數根據表格中的提示產生結構化資料時，請務必瞭解提示資料，以便指定適當的結構定義。

  舉例來說，假設您要分析來自下列欄位的資料表中的電影評論內容：

  • movie_id
  • review
  • 提示

  接著，您可以執行類似以下的查詢，建立提示文字：

  UPDATE mydataset.movie_review
  SET prompt = CONCAT('Extract the key words and key sentiment from the text below: ', review)
  WHERE review IS NOT NULL;

  您可以指定類似 "keywords ARRAY, sentiment STRING" AS output_schema 的 output_schema 值。

範例

以下範例顯示要求從資料表取得提示資料，並提供 SQL 結構定義來設定模型回應格式：

SELECT
*
FROM
AI.GENERATE_TABLE( MODEL `mydataset.gemini_model`,
  TABLE `mydataset.mytable`,
  STRUCT("keywords ARRAY, sentiment STRING" AS output_schema));

以下範例顯示要求從查詢中取得提示資料，並提供 SQL 結構定義來設定模型回應格式：

SELECT *
FROM
  AI.GENERATE_TABLE(
    MODEL `mydataset.gemini_model`,
    (
      SELECT
        'John Smith is a 20-year old single man living at 1234 NW 45th St, Kirkland WA, 98033. He has two phone numbers 123-123-1234, and 234-234-2345. He is 200.5 pounds.'
          AS prompt
    ),
    STRUCT("address STRUCT, age INT64, is_married BOOL, name STRING, phone_number ARRAY, weight_in_pounds FLOAT64"
        AS output_schema, 8192 AS max_output_tokens));