ML.GENERATE_EMBEDDING 함수를 사용하여 텍스트 임베딩 생성

이 문서에서는 임베딩 모델을 참조하는 BigQuery ML 원격 모델을 만드는 방법을 설명합니다. 그런 다음 이 모델을 ML.GENERATE_EMBEDDING 함수와 함께 사용하여 BigQuery 표준 테이블의 데이터를 사용해서 텍스트 임베딩을 만듭니다.

지원되는 원격 모델 유형은 다음과 같습니다.

• Vertex AI 임베딩 모델을 통한 원격 모델
• 지원되는 개방형 모델(프리뷰)을 통한 원격 모델

필요한 역할

원격 모델을 만들고 ML.GENERATE_EMBEDDING 함수를 사용하려면 다음 Identity and Access Management (IAM) 역할이 필요합니다.

• BigQuery 데이터 세트, 테이블, 모델을 만들고 사용하기: 프로젝트에 대한 BigQuery 데이터 편집자(roles/bigquery.dataEditor)

• BigQuery 연결을 만들고, 위임하고, 사용하기: 프로젝트에 대한 BigQuery 연결 관리자(roles/bigquery.connectionsAdmin)

  구성된 기본 연결이 없는 경우 CREATE MODEL 문을 실행하는 과정에서 연결을 만들고 설정할 수 있습니다. 이렇게 하려면 프로젝트에 BigQuery 관리자(roles/bigquery.admin)가 있어야 합니다. 자세한 내용은 기본 연결 구성을 참조하세요.

• 연결의 서비스 계정에 권한 부여: Vertex AI 엔드포인트가 포함된 프로젝트에 대한 프로젝트 IAM 관리자(roles/resourcemanager.projectIamAdmin). 이는 모델 이름을 엔드포인트로 지정하여 만드는 원격 모델의 현재 프로젝트입니다. 이는 엔드포인트로 URL을 지정하여 만드는 원격 모델의 URL에서 식별되는 프로젝트입니다.

• BigQuery 작업 만들기: 프로젝트에 대한 BigQuery 작업 사용자(roles/bigquery.jobUser)

이러한 사전 정의된 역할에는 이 문서의 작업을 수행하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 확장하세요.

필수 권한

• 데이터 세트 만들기: bigquery.datasets.create
• 연결을 만들고, 위임하고, 사용하기: bigquery.connections.*
• 서비스 계정 권한 설정: resourcemanager.projects.getIamPolicy 및 resourcemanager.projects.setIamPolicy
• 모델을 만들고 추론을 실행하기:
  • bigquery.jobs.create
  • bigquery.models.create
  • bigquery.models.getData
  • bigquery.models.updateData
  • bigquery.models.updateMetadata
• 테이블 데이터 쿼리: bigquery.tables.getData

커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.

시작하기 전에

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

   Roles required to select or create a project

   • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
   • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.
   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

2. Verify that billing is enabled for your Google Cloud project.

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

   Roles required to enable APIs

   To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

   Enable the APIs

데이터 세트 만들기

리소스를 포함할 BigQuery 데이터 세트를 만듭니다.

콘솔

1. Google Cloud 콘솔에서 BigQuery 페이지로 이동합니다.

   BigQuery로 이동

2. 왼쪽 창에서 탐색기를 클릭합니다.

   

   왼쪽 창이 표시되지 않으면 왼쪽 창 펼치기를 클릭하여 창을 엽니다.

3. 탐색기 창에서 프로젝트 이름을 클릭합니다.

4. 작업 보기 > 데이터 세트 만들기를 클릭합니다.

5. 데이터 세트 만들기 페이지에서 다음을 수행합니다.

   1. 데이터 세트 ID에 데이터 세트 이름을 입력합니다.

   2. 위치 유형으로 리전 또는 멀티 리전을 선택합니다.

      • 리전을 선택한 경우 리전 목록에서 위치를 선택합니다.
      • 멀티 리전을 선택한 경우 멀티 리전 목록에서 미국 또는 유럽을 선택합니다.

   3. 데이터 세트 만들기를 클릭합니다.

bq

1. 새 데이터 세트를 만들려면 --location 플래그와 함께 bq mk 명령어를 실행합니다.

   bq --location=LOCATION mk -d DATASET_ID

   다음을 바꿉니다.

   • LOCATION: 데이터 세트의 위치.
   • DATASET_ID: 사용자가 만들려는 데이터 세트 ID

2. 데이터 세트가 생성되었는지 확인합니다.

   bq ls

연결 만들기

기본 연결이 구성되어 있거나 BigQuery 관리자 역할이 있는 경우 이 단계를 건너뛸 수 있습니다.

원격 모델이 사용할 클라우드 리소스 연결을 만들고 연결의 서비스 계정을 가져옵니다. 이전 단계에서 만든 데이터 세트와 동일한 위치에 연결을 만듭니다.

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

콘솔

1. BigQuery 페이지로 이동합니다.

   BigQuery로 이동

2. 탐색기 창에서 데이터 추가를 클릭합니다.

   

   데이터 추가 대화상자가 열립니다.

3. 필터링 기준 창의 데이터 소스 유형 섹션에서 비즈니스 애플리케이션을 선택합니다.

   또는 데이터 소스 검색 필드에 Vertex AI을 입력할 수 있습니다.

4. 추천 데이터 소스 섹션에서 Vertex AI를 클릭합니다.

5. Vertex AI 모델: BigQuery 제휴 솔루션 카드를 클릭합니다.

6. 연결 유형 목록에서 Vertex AI 원격 모델, 원격 함수, BigLake, Spanner (Cloud 리소스)를 선택합니다.

7. 연결 ID 필드에 연결 이름을 입력합니다.

8. 연결 만들기를 클릭합니다.

9. 연결로 이동을 클릭합니다.

10. 연결 정보 창에서 나중의 단계에 사용할 서비스 계정 ID를 복사합니다.

bq

1. 명령줄 환경에서 연결을 만듭니다.

   bq mk --connection --location=REGION --project_id=PROJECT_ID \
       --connection_type=CLOUD_RESOURCE CONNECTION_ID

   --project_id 매개변수는 기본 프로젝트를 재정의합니다.

   다음을 바꿉니다.

   • REGION: 연결 리전
   • PROJECT_ID: Google Cloud 프로젝트 ID
   • CONNECTION_ID: 연결의 ID

   연결 리소스를 만들면 BigQuery가 고유한 시스템 서비스 계정을 만들고 이를 연결에 연계합니다.

   문제 해결: 다음 연결 오류가 발생하면 Google Cloud SDK를 업데이트하세요.

   Flags parsing error: flag --connection_type=CLOUD_RESOURCE: value should be one of...
   

2. 이후 단계에서 사용할 수 있도록 서비스 계정 ID를 가져와 복사합니다.

   bq show --connection PROJECT_ID.REGION.CONNECTION_ID

   출력은 다음과 유사합니다.

   name                          properties
   1234.REGION.CONNECTION_ID     {"serviceAccountId": "[e-mail]"}
   

Terraform

google_bigquery_connection 리소스를 사용합니다.

참고: Terraform을 사용해서 BigQuery 객체를 만들려면 Cloud Resource Manager API를 사용 설정해야 합니다.

BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

다음 예시에서는 US 리전에 my_cloud_resource_connection이라는 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 {}
}

Google Cloud 프로젝트에 Terraform 구성을 적용하려면 다음 섹션의 단계를 완료하세요.

Cloud Shell 준비

1. Cloud Shell을 실행합니다.

2. Terraform 구성을 적용할 기본 Google Cloud 프로젝트를 설정합니다.

   이 명령어는 프로젝트당 한 번만 실행하면 되며 어떤 디렉터리에서도 실행할 수 있습니다.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   Terraform 구성 파일에서 명시적 값을 설정하면 환경 변수가 재정의됩니다.

디렉터리 준비

각 Terraform 구성 파일에는 자체 디렉터리(루트 모듈이라고도 함)가 있어야 합니다.

1. Cloud Shell에서 디렉터리를 만들고 해당 디렉터리 내에 새 파일을 만드세요. 파일 이름에는 .tf 확장자가 있어야 합니다(예: main.tf). 이 튜토리얼에서는 파일을 main.tf라고 합니다.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. 튜토리얼을 따라 하는 경우 각 섹션이나 단계에서 샘플 코드를 복사할 수 있습니다.

   샘플 코드를 새로 만든 main.tf에 복사합니다.

   필요한 경우 GitHub에서 코드를 복사합니다. 이는 Terraform 스니펫이 엔드 투 엔드 솔루션의 일부인 경우에 권장됩니다.

3. 환경에 적용할 샘플 파라미터를 검토하고 수정합니다.
4. 변경사항을 저장합니다.
5. Terraform을 초기화합니다. 이 작업은 디렉터리당 한 번만 수행하면 됩니다.

   terraform init

   원하는 경우 최신 Google 공급업체 버전을 사용하려면 -upgrade 옵션을 포함합니다.

   terraform init -upgrade

변경사항 적용

1. 구성을 검토하고 Terraform에서 만들거나 업데이트할 리소스가 예상과 일치하는지 확인합니다.

   terraform plan

   필요에 따라 구성을 수정합니다.

2. 다음 명령어를 실행하고 프롬프트에 yes를 입력하여 Terraform 구성을 적용합니다.

   terraform apply

   Terraform에 '적용 완료' 메시지가 표시될 때까지 기다립니다.

3. 결과를 보려면 Google Cloud 프로젝트를 엽니다. Google Cloud 콘솔에서 UI의 리소스로 이동하여 Terraform이 리소스를 만들었거나 업데이트했는지 확인합니다.

참고: Terraform 샘플은 일반적으로 필요한 API가 Google Cloud 프로젝트에서 사용 설정되었다고 가정합니다.

원격 모델 연결의 서비스 계정에 역할 부여

연결의 서비스 계정에 Vertex AI 사용자 역할을 부여해야 합니다.

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

원격 모델을 만들 때 모델 이름을 사용(예: endpoint = 'text-embedding-005')하여 엔드포인트를 지정할 계획이라면 원격 모델을 만들려는 동일한 프로젝트에서 이 역할을 부여합니다.

다른 프로젝트에서 역할을 부여하면 [e-mail] does not have the permission to access resource 오류가 발생합니다.

역할을 부여하려면 다음 단계를 따르세요.

콘솔

1. IAM 및 관리자 페이지로 이동합니다.

   IAM 및 관리자로 이동

2. 액세스 권한 부여를 클릭합니다.

   주 구성원 추가 대화상자가 열립니다.

3. 새 주 구성원 필드에 앞에서 복사한 서비스 계정 ID를 입력합니다.

4. 역할 선택 필드에서 Vertex AI를 선택한 후 Vertex AI 사용자를 선택합니다.

5. 저장을 클릭합니다.

gcloud

gcloud projects add-iam-policy-binding 명령어를 사용합니다.

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

다음을 바꿉니다.

• PROJECT_NUMBER: 프로젝트 번호
• MEMBER: 이전에 복사한 서비스 계정 ID

개방형 모델 배포 방법 선택

지원되는 개방형 모델을 통해 원격 모델을 만드는 경우 CREATE MODEL 문에서 Vertex AI Model Garden 또는 Hugging Face 모델 ID를 지정하여 원격 모델을 만드는 동시에 개방형 모델을 자동으로 배포할 수 있습니다. 또는 먼저 오픈 모델을 수동으로 배포한 다음 CREATE MODEL 문에서 모델 엔드포인트를 지정하여 원격 모델과 함께 해당 오픈 모델을 사용할 수 있습니다. 자세한 내용은 개방형 모델 배포를 참고하세요.

BigQuery ML 원격 모델 만들기

원격 모델을 만듭니다.

새로운 개방형 모델

프리뷰

이 제품 또는 기능에는 서비스별 약관의 일반 서비스 약관 섹션에 있는 'GA 이전 제공 서비스 약관'이 적용됩니다. GA 이전 제품 및 기능은 '있는 그대로' 제공되며 지원이 제한될 수 있습니다. 자세한 내용은 출시 단계 설명을 참조하세요.

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 (
     {HUGGING_FACE_MODEL_ID = 'HUGGING_FACE_MODEL_ID' |
        MODEL_GARDEN_MODEL_NAME = 'MODEL_GARDEN_MODEL_NAME'}
     [, HUGGING_FACE_TOKEN = 'HUGGING_FACE_TOKEN' ]
     [, MACHINE_TYPE = 'MACHINE_TYPE' ]
     [, MIN_REPLICA_COUNT = MIN_REPLICA_COUNT ]
     [, MAX_REPLICA_COUNT = MAX_REPLICA_COUNT ]
     [, RESERVATION_AFFINITY_TYPE = {'NO_RESERVATION' | 'ANY_RESERVATION' | 'SPECIFIC_RESERVATION'} ]
     [, RESERVATION_AFFINITY_KEY = 'compute.googleapis.com/reservation-name' ]
     [, RESERVATION_AFFINITY_VALUES = RESERVATION_AFFINITY_VALUES ]
     [, ENDPOINT_IDLE_TTL = ENDPOINT_IDLE_TTL ]
   );

   다음을 바꿉니다.

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

     Google Cloud 콘솔에서 연결 세부정보를 확인하고 연결 ID에 표시되는 정규화된 연결 ID의 마지막 섹션에 있는 값을 복사하여 이 값을 확인할 수 있습니다. 예를 들어 projects/myproject/locations/connection_location/connections/myconnection입니다.

   • HUGGING_FACE_MODEL_ID: 지원되는 Hugging Face 모델의 모델 ID를 지정하는 STRING 값(provider_name/model_name 형식). 예: deepseek-ai/DeepSeek-R1 Hugging Face Model Hub에서 모델 이름을 클릭한 다음 모델 카드 상단에서 모델 ID를 복사하여 모델 ID를 가져올 수 있습니다.
   • MODEL_GARDEN_MODEL_NAME: 지원되는 Vertex AI Model Garden 모델의 모델 ID와 모델 버전을 지정하는 STRING 값입니다. 형식은 publishers/publisher/models/model_name@model_version입니다. 예를 들면 publishers/openai/models/gpt-oss@gpt-oss-120b입니다. Vertex AI Model Garden에서 모델 카드를 클릭한 다음 모델 ID 필드에서 모델 ID를 복사하여 모델 ID를 가져올 수 있습니다. 모델 카드의 버전 필드에서 복사하여 기본 모델 버전을 가져올 수 있습니다. 사용할 수 있는 다른 모델 버전을 보려면 모델 배포를 클릭한 다음 리소스 ID 필드를 클릭합니다.
   • HUGGING_FACE_TOKEN: 사용할 Hugging Face 사용자 액세스 토큰을 지정하는 STRING 값입니다. HUGGING_FACE_MODEL_ID 옵션의 값을 지정한 경우에만 이 옵션의 값을 지정할 수 있습니다.

     토큰에는 최소한 read 역할이 있어야 하지만 범위가 더 넓은 토큰도 허용됩니다. 이 옵션은 HUGGING_FACE_MODEL_ID 값으로 식별되는 모델이 Hugging Face 액세스 제한 또는 비공개 모델인 경우 필요합니다.

     일부 게이트 모델은 액세스 권한이 부여되기 전에 서비스 약관에 명시적으로 동의해야 합니다. 이 약관에 동의하려면 다음 단계를 따르세요.

     1. Hugging Face 웹사이트에서 모델 페이지로 이동합니다.
     2. 모델의 서비스 약관을 찾아 검토합니다. 서비스 계약 링크는 일반적으로 모델 카드에 있습니다.
     3. 페이지에 표시되는 약관에 동의합니다.
   • MACHINE_TYPE: Vertex AI에 모델을 배포할 때 사용할 머신 유형을 지정하는 STRING 값입니다. 지원되는 머신 유형에 대한 자세한 내용은 머신 유형을 참고하세요. MACHINE_TYPE 옵션의 값을 지정하지 않으면 모델의 Vertex AI Model Garden 기본 머신 유형이 사용됩니다.
   • MIN_REPLICA_COUNT: Vertex AI 엔드포인트에 모델을 배포할 때 사용되는 최소 머신 복제본 수를 지정하는 INT64 값입니다. 서비스는 엔드포인트의 추론 로드에 따라 복제본 수를 늘리거나 줄입니다. 사용되는 복제본 수는 MIN_REPLICA_COUNT 값보다 낮지 않고 MAX_REPLICA_COUNT 값보다 높지 않습니다. MIN_REPLICA_COUNT 값은 [1, 4096] 범위 내에 있어야 합니다. 기본값은 1입니다.
   • MAX_REPLICA_COUNT: Vertex AI 엔드포인트에 모델을 배포할 때 사용되는 최대 머신 복제본 수를 지정하는 INT64 값입니다. 서비스는 엔드포인트의 추론 로드에 따라 복제본 수를 늘리거나 줄입니다. 사용되는 복제본 수는 MIN_REPLICA_COUNT 값보다 낮지 않고 MAX_REPLICA_COUNT 값보다 높지 않습니다. MAX_REPLICA_COUNT 값은 [1, 4096] 범위 내에 있어야 합니다. 기본값은 MIN_REPLICA_COUNT 값입니다.
   • RESERVATION_AFFINITY_TYPE: 배포된 모델이 예측을 제공할 때 Compute Engine 예약을 사용하여 가상 머신 (VM) 가용성을 보장하는지 여부를 결정하고 모델이 사용 가능한 모든 예약의 VM을 사용하는지 아니면 특정 예약의 VM만 사용하는지 지정합니다. 자세한 내용은 Compute Engine 예약 선호도를 참고하세요.

     Vertex AI와 공유된 Compute Engine 예약만 사용할 수 있습니다. 자세한 내용은 예약 사용 허용을 참고하세요.

     지원되는 값은 다음과 같습니다.

     • NO_RESERVATION: 모델이 Vertex AI 엔드포인트에 배포되면 예약이 사용되지 않습니다. NO_RESERVATION을 지정하면 예약 어피니티를 지정하지 않는 것과 동일한 효과가 있습니다.
     • ANY_RESERVATION: Vertex AI 모델 배포가 현재 프로젝트에 있거나 프로젝트와 공유되고 자동 사용을 위해 구성된 Compute Engine 예약의 가상 머신 (VM)을 사용합니다. 다음 자격을 충족하는 VM만 사용됩니다.
       • MACHINE_TYPE 값으로 지정된 머신 유형을 사용합니다.
       • 원격 모델을 만드는 BigQuery 데이터 세트가 단일 리전인 경우 예약은 동일한 리전에 있어야 합니다. 데이터 세트가 US 멀티 리전에 있는 경우 예약은 us-central1 리전에 있어야 합니다. 데이터 세트가 EU 멀티 리전에 있는 경우 예약은 europe-west4 리전에 있어야 합니다.

       사용 가능한 예약의 용량이 충분하지 않거나 적합한 예약이 없는 경우 시스템은 리소스 요구사항을 충족하기 위해 주문형 Compute Engine VM을 프로비저닝합니다.

     • SPECIFIC_RESERVATION: Vertex AI 모델 배포가 RESERVATION_AFFINITY_VALUES 값에 지정된 예약의 VM만 사용합니다. 이 예약은 구체적으로 타겟팅된 사용을 위해 구성되어야 합니다. 지정된 예약에 충분한 용량이 없으면 배포가 실패합니다.
   • RESERVATION_AFFINITY_KEY: 문자열 compute.googleapis.com/reservation-name입니다. RESERVATION_AFFINITY_TYPE 값이 SPECIFIC_RESERVATION인 경우 이 옵션을 지정해야 합니다.
   • RESERVATION_AFFINITY_VALUES: 다음 형식으로 Compute Engine 예약의 전체 리소스 이름을 지정하는 ARRAY<STRING> 값입니다.
     
     projects/myproject/zones/reservation_zone/reservations/reservation_name

     예를 들면 RESERVATION_AFFINITY_values = ['projects/myProject/zones/us-central1-a/reservations/myReservationName']입니다.

     Google Cloud 콘솔의 예약 페이지에서 예약 이름과 영역을 확인할 수 있습니다. 자세한 내용은 예약 보기를 참고하세요.

     RESERVATION_AFFINITY_TYPE 값이 SPECIFIC_RESERVATION인 경우 이 옵션을 지정해야 합니다.

   • ENDPOINT_IDLE_TTL: Vertex AI 엔드포인트에서 개방형 모델이 자동으로 배포 취소되는 비활성 기간을 지정하는 INTERVAL 값입니다.

     자동 배포 해제를 사용 설정하려면 390분 (6.5시간)에서 7일 사이의 간격 리터럴 값을 지정합니다. 예를 들어 8시간 동안 유휴 상태가 되면 모델이 배포 해제되도록 하려면 INTERVAL 8 HOUR를 지정합니다. 기본값은 390분 (6시간 30분)입니다.

     모델 비활성은 모델에서 다음 작업 중 하나가 실행된 후 경과된 시간으로 정의됩니다.

     • CREATE MODEL 문을 실행합니다.
     • DEPLOY_MODEL 인수가 TRUE로 설정된 ALTER MODEL 문을 실행합니다.
     • 모델 엔드포인트에 추론 요청을 전송합니다. 예를 들어 ML.GENERATE_EMBEDDING 또는 ML.GENERATE_TEXT 함수를 실행합니다.

     이러한 각 작업은 비활성 타이머를 0으로 재설정합니다. 재설정은 작업을 실행하는 BigQuery 작업이 시작될 때 트리거됩니다.

     모델이 배포 해제된 후 모델에 전송된 추론 요청은 오류를 반환합니다. 모델 메타데이터를 비롯한 BigQuery 모델 객체는 변경되지 않습니다. 추론에 모델을 다시 사용하려면 모델에서 ALTER MODEL 문을 실행하고 DEPLOY_MODEL 옵션을 TRUE로 설정하여 모델을 재배포해야 합니다.

배포된 개방형 모델

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 = 'https://ENDPOINT_REGION-aiplatform.googleapis.com/v1/projects/ENDPOINT_PROJECT_ID/locations/ENDPOINT_REGION/endpoints/ENDPOINT_ID'
   );

   다음을 바꿉니다.

   • 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_REGION: 개방형 모델이 배포되는 리전입니다.
   • ENDPOINT_PROJECT_ID: 개방형 모델이 배포된 프로젝트입니다.
   • ENDPOINT_ID: 개방형 모델에서 사용하는 HTTPS 엔드포인트의 ID입니다. 온라인 예측 페이지에서 개방형 모델을 찾아 ID 필드의 값을 복사하여 엔드포인트 ID를 가져올 수 있습니다.

다른 모든 모델

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: 사용할 임베딩 모델의 이름입니다. 자세한 내용은 ENDPOINT를 참고하세요.

     지정한 Vertex AI 모델은 원격 모델을 만드는 위치에서 사용할 수 있어야 합니다. 자세한 내용은 위치를 참조하세요.

텍스트 임베딩 생성

테이블 열 또는 쿼리의 텍스트 데이터를 사용하여 ML.GENERATE_EMBEDDING 함수로 텍스트 임베딩을 생성합니다.

일반적으로 텍스트 전용 사용 사례에는 텍스트 임베딩 모델을 사용하고 교차 모달 검색 사용 사례에는 멀티모달 임베딩 모델을 사용합니다. 여기서 텍스트 및 시각적 콘텐츠의 임베딩은 동일한 시맨틱 공간에서 생성됩니다.

Vertex AI 텍스트

Vertex AI 텍스트 임베딩 모델을 통해 원격 모델을 사용하여 텍스트 임베딩을 생성합니다.

SELECT *
FROM ML.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  {TABLE PROJECT_ID.DATASET_ID.TABLE_NAME | (CONTENT_QUERY)},
  STRUCT(FLATTEN_JSON AS flatten_json_output,
    TASK_TYPE AS task_type,
    OUTPUT_DIMENSIONALITY AS output_dimensionality)
);

다음을 바꿉니다.

• PROJECT_ID: 프로젝트 ID
• DATASET_ID: 모델이 포함된 데이터 세트의 ID
• MODEL_NAME: 임베딩 모델을 통한 원격 모델의 이름
• TABLE_NAME: 삽입할 텍스트가 포함된 테이블의 이름. 이 테이블에는 이름이 content인 열이 있어야 합니다. 또는 별칭을 사용하여 다른 이름의 열을 사용할 수 있습니다.
• CONTENT_QUERY: 결과에 content라는 STRING 열이 포함된 쿼리
• FLATTEN_JSON: 임베딩을 별도의 열로 파싱할지 여부를 나타내는 BOOL 값. 기본값은 TRUE입니다.
• TASK_TYPE: 모델이 더 나은 품질의 임베딩을 생성할 수 있도록 의도된 다운스트림 애플리케이션을 지정하는 STRING 리터럴. TASK_TYPE은 다음 값을 허용합니다.
  • RETRIEVAL_QUERY: 지정된 텍스트가 검색 또는 가져오기 설정의 쿼리임을 지정
  • RETRIEVAL_DOCUMENT: 지정된 텍스트가 검색 또는 가져오기 설정의 문서임을 지정

    이 태스크 유형을 사용할 때 임베딩 품질을 개선하기 위해 쿼리 문에 문서 제목을 포함하면 유용합니다. 문서 제목은 title 또는 별칭이 title로 지정된 열에 있어야 합니다. 예를 들면 다음과 같습니다.

          SELECT *
          FROM
            ML.GENERATE_EMBEDDING(
              MODEL mydataset.embedding_model,
              (SELECT abstract as content, header as title, publication_number
              FROM mydataset.publications),
              STRUCT(TRUE AS flatten_json_output, 'RETRIEVAL_DOCUMENT' as task_type)
          );
          

    입력 쿼리에서 제목 열을 지정하면 모델에 전송되는 요청 본문의 title 필드가 채워집니다. 다른 작업 유형을 사용할 때 title 값을 지정하면 해당 입력이 무시되고 삽입 결과에 영향을 미치지 않습니다.

  • SEMANTIC_SIMILARITY: 지정된 텍스트를 시맨틱 텍스트 유사성(STS)에 사용하도록 지정
  • CLASSIFICATION: 임베딩이 분류에 사용되도록 지정
  • CLUSTERING: 클러스터링에 임베딩을 사용하도록 지정
  • QUESTION_ANSWERING: 임베딩이 질문 답변에 사용되도록 지정
  • FACT_VERIFICATION: 사실 확인에 임베딩을 사용하도록 지정
  • CODE_RETRIEVAL_QUERY: 임베딩이 코드 검색에 사용되도록 지정
• OUTPUT_DIMENSIONALITY: 임베딩을 생성할 때 사용할 차원 수를 지정하는 INT64 값입니다. 예를 들어 256 AS output_dimensionality를 지정하면 ml_generate_embedding_result 출력 열에 각 입력 값에 대한 임베딩이 256개 포함됩니다.

  gemini-embedding-001 모델을 사용하는 원격 모델의 경우 OUTPUT_DIMENSIONALITY 값은 [1, 3072] 범위 내에 있어야 합니다. 기본값은 3072입니다. text-embedding 또는 text-multilingual-embedding 모델을 사용하는 원격 모델의 경우 OUTPUT_DIMENSIONALITY 값은 [1, 768] 범위 내에 있어야 합니다. 기본값은 768입니다.

  text-embedding 모델을 통해 원격 모델을 사용하는 경우 text-embedding 모델 버전은 text-embedding-004 이상이어야 합니다. text-multilingual-embedding 모델을 통해 원격 모델을 사용하는 경우 text-multilingual-embedding 모델 버전이 text-multilingual-embedding-002 이상이어야 합니다.

예: 테이블에 텍스트 삽입

다음 예시는 text_data 테이블의 content 열을 삽입하는 요청을 보여줍니다.

SELECT *
FROM
  ML.GENERATE_EMBEDDING(
    MODEL `mydataset.embedding_model`,
    TABLE mydataset.text_data,
    STRUCT(TRUE AS flatten_json_output, 'CLASSIFICATION' AS task_type)
  );

서술형

프리뷰

이 제품 또는 기능에는 서비스별 약관의 일반 서비스 약관 섹션에 있는 'GA 이전 제공 서비스 약관'이 적용됩니다. GA 이전 제품 및 기능은 '있는 그대로' 제공되며 지원이 제한될 수 있습니다. 자세한 내용은 출시 단계 설명을 참조하세요.

참고: 이 기능에 대한 의견을 제공하거나 지원을 요청하려면 [e-mail]으로 문의하세요.

개방형 임베딩 모델을 통해 원격 모델을 사용하여 텍스트 임베딩을 생성합니다.

SELECT *
FROM ML.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  {TABLE PROJECT_ID.DATASET_ID.TABLE_NAME | (CONTENT_QUERY)},
  STRUCT(FLATTEN_JSON AS flatten_json_output)
);

다음을 바꿉니다.

• PROJECT_ID: 프로젝트 ID
• DATASET_ID: 모델이 포함된 데이터 세트의 ID
• MODEL_NAME: 임베딩 모델을 통한 원격 모델의 이름
• TABLE_NAME: 삽입할 텍스트가 포함된 테이블의 이름. 이 테이블에는 이름이 content인 열이 있어야 합니다. 또는 별칭을 사용하여 다른 이름의 열을 사용할 수 있습니다.
• CONTENT_QUERY: 결과에 content라는 STRING 열이 포함된 쿼리
• FLATTEN_JSON: 임베딩을 별도의 열로 파싱할지 여부를 나타내는 BOOL 값. 기본값은 TRUE입니다.

Vertex AI 멀티모달

Vertex AI 멀티모달 임베딩 모델을 통해 원격 모델을 사용하여 텍스트 임베딩을 생성합니다.

SELECT *
FROM ML.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  {TABLE PROJECT_ID.DATASET_ID.TABLE_NAME | (CONTENT_QUERY)},
  STRUCT(FLATTEN_JSON AS flatten_json_output，
  OUTPUT_DIMENSIONALITY AS output_dimensionality)
);

다음을 바꿉니다.

• PROJECT_ID: 프로젝트 ID
• DATASET_ID: 모델이 포함된 데이터 세트의 ID
• MODEL_NAME: multimodalembedding@001 모델에 대한 원격 모델의 이름
• TABLE_NAME: 삽입할 텍스트가 포함된 테이블의 이름. 이 테이블에는 이름이 content인 열이 있어야 합니다. 또는 별칭을 사용하여 다른 이름의 열을 사용할 수 있습니다.
• CONTENT_QUERY: 결과에 content라는 STRING 열이 포함된 쿼리
• FLATTEN_JSON: 임베딩을 별도의 열로 파싱할지 여부를 나타내는 BOOL. 기본값은 TRUE입니다.
• OUTPUT_DIMENSIONALITY: 임베딩을 생성할 때 사용할 차원 수를 지정하는 INT64 값입니다. 유효한 값은 128, 256, 512, 1408입니다. 기본값은 1408입니다. 예를 들어 256 AS output_dimensionality를 지정하면 ml_generate_embedding_result 출력 열에 각 입력 값에 대한 임베딩이 256개 포함됩니다.

예: 임베딩을 사용하여 의미론적 유사성 순위 지정

다음 예에서는 영화 리뷰 모음을 삽입하고 VECTOR_SEARCH 함수를 사용하여 '이 영화는 평범했습니다'라는 리뷰와의 코사인 거리에 따라 순서를 지정합니다. 거리가 짧을수록 시맨틱 유사성이 높습니다.

벡터 검색 및 벡터 색인에 대한 자세한 내용은 벡터 검색 소개를 참고하세요.

CREATE TEMPORARY TABLE movie_review_embeddings AS (
  SELECT *
  FROM
    ML.GENERATE_EMBEDDING(
      MODEL `bqml_tutorial.embedding_model`,
      (
        SELECT "This movie was fantastic" AS content
        UNION ALL
        SELECT "This was the best movie I've ever seen!!" AS content
        UNION ALL
        SELECT "This movie was just okay..." AS content
        UNION ALL
        SELECT "This movie was terrible." AS content
      ),
      STRUCT(TRUE AS flatten_json_output)
    )
);

WITH average_review_embedding AS (
  SELECT ml_generate_embedding_result
  FROM
    ML.GENERATE_EMBEDDING(
      MODEL `bqml_tutorial.embedding_model`,
      (SELECT "This movie was average" AS content),
      STRUCT(TRUE AS flatten_json_output)
    )
)
SELECT
  base.content AS content,
  distance AS distance_to_average_review
FROM
  VECTOR_SEARCH(
    TABLE movie_review_embeddings,
    "ml_generate_embedding_result",
    (SELECT ml_generate_embedding_result FROM average_review_embedding),
    distance_type=>"COSINE",
    top_k=>-1
  )
ORDER BY distance_to_average_review;

결과는 다음과 같습니다.

+------------------------------------------+----------------------------+
| content                                  | distance_to_average_review |
+------------------------------------------+----------------------------+
| This movie was just okay...              | 0.062789813467745592       |
| This movie was fantastic                 |  0.18579561313064263       |
| This movie was terrible.                 |  0.35707466240930985       |
| This was the best movie I've ever seen!! |  0.41844932504542975       |
+------------------------------------------+----------------------------+

다음 단계

• 텍스트 및 이미지 임베딩을 사용하여 텍스트-이미지 시맨틱 검색을 수행하는 방법 알아보기
• 시맨틱 검색 및 검색 증강 생성(RAG)에 텍스트 임베딩을 사용하는 방법 알아보기