AI.GENERATE_TABLE 함수를 사용하여 구조화된 데이터 생성

이 문서에서는 Gemini Pro 1.5, Gemini Flash 1.5 또는 Gemini Flash 2.0 모델을 사용하여 구조화된 데이터를 생성한 후 SQL 스키마를 사용하여 모델의 응답 형식을 지정하는 방법을 보여줍니다.

다음 작업을 완료하면 됩니다.

• 호스팅된 Vertex AI Gemini 1.5 또는 2.0 모델을 나타내는 BigQuery ML 원격 모델을 만듭니다.
• AI.GENERATE_TABLE 함수와 함께 모델을 사용하여 표준 테이블의 데이터를 기반으로 구조화된 데이터를 생성합니다.

필수 권한

• 연결을 만들려면 다음 Identity and Access Management(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

연결 만들기

클라우드 리소스 연결을 만들고 연결의 서비스 계정을 가져옵니다.

다음 옵션 중 하나를 선택합니다.

# 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 사용자 역할을 부여합니다.

원격 모델을 만들 때 엔드포인트를 URL(예: endpoint = 'https://us-central1-aiplatform.googleapis.com/v1/projects/myproject/locations/us-central1/publishers/google/models/gemini-1.5-flash')로 지정할 계획이라면 URL에 지정한 동일한 프로젝트에서 이 역할을 부여합니다.

원격 모델을 만들 때 모델 이름을 사용(예: 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 `PROJECT_ID.REGION.CONNECTION_ID`
   OPTIONS (ENDPOINT = 'ENDPOINT');

   다음을 바꿉니다.

   • PROJECT_ID: 프로젝트 ID입니다.
   • DATASET_ID: 모델을 포함할 데이터 세트의 ID입니다. 이 데이터 세트는 사용 중인 연결과 동일한 위치에 있어야 합니다.
   • MODEL_NAME: 모델의 이름
   • REGION: 연결에 사용되는 리전
   • CONNECTION_ID: BigQuery 연결의 ID

     콘솔에서 연결 세부정보를 볼 때 이 값은 연결 ID에 표시되는 정규화된 연결 ID의 마지막 섹션에 있는 값입니다(예: projects/myproject/locations/connection_location/connections/myconnection). Google Cloud

   • ENDPOINT: 사용할 Gemini 모델의 이름입니다. 지원되는 모델은 다음과 같습니다.
     • gemini-2.0-flash-001
     • gemini-1.5-flash-001
     • gemini-1.5-flash-002
     • gemini-1.5-pro-001
     • gemini-1.5-pro-002
     자세한 내용은 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: [0.0,1.0] 범위의 FLOAT64 값은 토큰이 선택될 확률을 결정하는 데 도움이 됩니다. 임의성이 낮은 응답을 위해서는 낮은 값을 지정하고 임의성이 높은 응답을 위해서는 높은 값을 지정합니다. 기본값은 0.95입니다.
• STOP_SEQUENCES: 지정한 문자열이 모델의 응답에 포함된 경우 이 문자열을 제거하는 ARRAY<STRING> 값입니다. 문자열은 대소문자까지 정확히 일치합니다. 기본값은 빈 배열입니다.
• SAFETY_SETTINGS: 응답을 필터링하도록 콘텐츠 안전 기준을 구성하는 ARRAY<STRUCT<STRING AS category, STRING AS threshold>> 값입니다. 구조체의 첫 번째 요소는 피해 카테고리를 지정하고 구조체의 두 번째 요소는 해당하는 차단 기준을 지정합니다. 모델은 이러한 설정을 위반하는 콘텐츠를 필터링합니다. 각 카테고리는 한 번만 지정할 수 있습니다. 예를 들어 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 값은 CREATE TABLE 문에 사용된 것과 유사한 SQL 스키마 정의여야 합니다. 지원되는 데이터 유형은 다음과 같습니다.
  • INT64
  • FLOAT64
  • BOOL
  • STRING
  • ARRAY
  • STRUCT

  Gemini 1.5 모델의 경우 반환 값이 반올림된 숫자가 아닐 것이라고 확신하는 경우에만 FLOAT64 데이터 유형을 지정합니다. 이러한 모델은 반올림된 숫자의 경우 FLOAT64 값 대신 INT64 값을 반환할 수 있습니다(예: 2.0 대신 2). 이로 인해 쿼리에서 파싱 오류가 발생할 수 있습니다.

  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<STRING>, sentiment STRING" AS output_schema와 유사한 output_schema 값을 지정할 수도 있습니다.

예시

다음 예는 테이블에서 프롬프트 데이터를 가져와 모델의 응답 형식을 지정하는 SQL 스키마를 제공하는 요청을 보여줍니다.

SELECT
*
FROM
AI.GENERATE_TABLE( MODEL `mydataset.gemini_model`,
  TABLE `mydataset.mytable`,
  STRUCT("keywords ARRAY<STRING>, 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<street_address STRING, city STRING, state STRING, zip_code STRING>, age INT64, is_married BOOL, name STRING, phone_number ARRAY<STRING>, weight_in_pounds FLOAT64"
        AS output_schema, 8192 AS max_output_tokens));