ML.GENERATE_EMBEDDING 함수를 사용하여 이미지 임베딩 생성
이 문서에서는 Vertex AI 임베딩 모델을 참조하는 BigQuery ML 원격 모델을 만드는 방법을 설명합니다.
그런 다음 이 모델을 ML.GENERATE_EMBEDDING 함수와 함께 사용하여 BigQuery 객체 테이블의 데이터를 사용해서 이미지 임베딩을 만듭니다.
필요한 역할
원격 모델을 만들고 임베딩을 생성하려면 다음 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에서 식별되는 프로젝트입니다.- 원격 모델을 사용하여 객체 테이블의 비정형 데이터를 분석하고 객체 테이블에서 사용하는 Cloud Storage 버킷이 Vertex AI 엔드포인트와 다른 프로젝트에 있는 경우 객체 테이블에서 사용하는 Cloud Storage 버킷에 대한 스토리지 관리자( - roles/storage.admin) 권한도 있어야 합니다.
- BigQuery 작업 만들기: 프로젝트에 대한 BigQuery 작업 사용자( - roles/bigquery.jobUser)
이러한 사전 정의된 역할에는 이 문서의 작업을 수행하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 확장하세요.
필수 권한
- 데이터 세트 만들기: bigquery.datasets.create
- 연결을 만들고, 위임하고, 사용하기:
    bigquery.connections.*
- 서비스 계정 권한 설정: resourcemanager.projects.getIamPolicy및resourcemanager.projects.setIamPolicy
- 객체 테이블 만들기: bigquery.tables.create및bigquery.tables.update
- 모델 만들기 및 추론 실행:
    - bigquery.jobs.create
- bigquery.models.create
- bigquery.models.getData
- bigquery.models.updateData
- bigquery.models.updateMetadata
 
커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.
시작하기 전에
- 
  
   
   
     
   
  
   
   
     
   
  
 
   
 
 
  
    
    
      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 theresourcemanager.projects.createpermission. Learn how to grant roles.
 
- 
  
   
   
  
   
   
  
 
  
    Verify that billing is enabled for your Google Cloud project. 
- 
  
   
   
  
   
   
  
 
 
  
  
    
      Enable the BigQuery, BigQuery Connection, Cloud Storage, 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 theserviceusage.services.enablepermission. Learn how to grant roles.
데이터 세트 만들기
리소스를 포함할 BigQuery 데이터 세트를 만듭니다.
콘솔
- Google Cloud 콘솔에서 BigQuery 페이지로 이동합니다. 
- 왼쪽 창에서 탐색기를 클릭합니다.  - 왼쪽 창이 표시되지 않으면 왼쪽 창 펼치기를 클릭하여 창을 엽니다. 
- 탐색기 창에서 프로젝트 이름을 클릭합니다. 
- 작업 보기 > 데이터 세트 만들기를 클릭합니다. 
- 데이터 세트 만들기 페이지에서 다음을 수행합니다. - 데이터 세트 ID에 데이터 세트 이름을 입력합니다. 
- 위치 유형으로 리전 또는 멀티 리전을 선택합니다. - 리전을 선택한 경우 리전 목록에서 위치를 선택합니다.
- 멀티 리전을 선택한 경우 멀티 리전 목록에서 미국 또는 유럽을 선택합니다.
 
- 데이터 세트 만들기를 클릭합니다. 
 
bq
연결 만들기
기본 연결이 구성되어 있거나 BigQuery 관리자 역할이 있는 경우 이 단계를 건너뛸 수 있습니다.
원격 모델이 사용할 클라우드 리소스 연결을 만들고 연결의 서비스 계정을 가져옵니다. 이전 단계에서 만든 데이터 세트와 동일한 위치에 연결을 만듭니다.
다음 옵션 중 하나를 선택합니다.
콘솔
- BigQuery 페이지로 이동합니다. 
- 탐색기 창에서 데이터 추가를 클릭합니다.   - 데이터 추가 대화상자가 열립니다. 
- 필터링 기준 창의 데이터 소스 유형 섹션에서 비즈니스 애플리케이션을 선택합니다. - 또는 데이터 소스 검색 필드에 - Vertex AI을 입력할 수 있습니다.
- 추천 데이터 소스 섹션에서 Vertex AI를 클릭합니다. 
- Vertex AI 모델: BigQuery 제휴 솔루션 카드를 클릭합니다. 
- 연결 유형 목록에서 Vertex AI 원격 모델, 원격 함수, BigLake, Spanner (Cloud 리소스)를 선택합니다. 
- 연결 ID 필드에 연결 이름을 입력합니다. 
- 연결 만들기를 클릭합니다. 
- 연결로 이동을 클릭합니다. 
- 연결 정보 창에서 나중의 단계에 사용할 서비스 계정 ID를 복사합니다. 
bq
- 명령줄 환경에서 연결을 만듭니다. - 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... 
- 이후 단계에서 사용할 수 있도록 서비스 계정 ID를 가져와 복사합니다. - bq show --connection PROJECT_ID.REGION.CONNECTION_ID - 출력은 다음과 유사합니다. - name properties 1234.REGION.CONNECTION_ID {"serviceAccountId": "connection-1234-9u56h9@gcp-sa-bigquery-condel.iam.gserviceaccount.com"}
Terraform
google_bigquery_connection 리소스를 사용합니다.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
다음 예시에서는 US 리전에 my_cloud_resource_connection이라는 Cloud 리소스 연결을 만듭니다.
Google Cloud 프로젝트에 Terraform 구성을 적용하려면 다음 섹션의 단계를 완료하세요.
Cloud Shell 준비
- Cloud Shell을 실행합니다.
- 
    Terraform 구성을 적용할 기본 Google Cloud 프로젝트를 설정합니다. 이 명령어는 프로젝트당 한 번만 실행하면 되며 어떤 디렉터리에서도 실행할 수 있습니다. export GOOGLE_CLOUD_PROJECT=PROJECT_ID Terraform 구성 파일에서 명시적 값을 설정하면 환경 변수가 재정의됩니다. 
디렉터리 준비
각 Terraform 구성 파일에는 자체 디렉터리(루트 모듈이라고도 함)가 있어야 합니다.
- 
    Cloud Shell에서 디렉터리를 만들고 해당 디렉터리 내에 새 파일을 만드세요. 파일 이름에는 .tf확장자가 있어야 합니다(예:main.tf). 이 튜토리얼에서는 파일을main.tf라고 합니다.mkdir DIRECTORY && cd DIRECTORY && touch main.tf 
- 
    튜토리얼을 따라 하는 경우 각 섹션이나 단계에서 샘플 코드를 복사할 수 있습니다. 샘플 코드를 새로 만든 main.tf에 복사합니다.필요한 경우 GitHub에서 코드를 복사합니다. 이는 Terraform 스니펫이 엔드 투 엔드 솔루션의 일부인 경우에 권장됩니다. 
- 환경에 적용할 샘플 파라미터를 검토하고 수정합니다.
- 변경사항을 저장합니다.
- 
    Terraform을 초기화합니다. 이 작업은 디렉터리당 한 번만 수행하면 됩니다.
    terraform init 원하는 경우 최신 Google 공급업체 버전을 사용하려면 -upgrade옵션을 포함합니다.terraform init -upgrade 
변경사항 적용
- 
    구성을 검토하고 Terraform에서 만들거나 업데이트할 리소스가 예상과 일치하는지 확인합니다.
    terraform plan 필요에 따라 구성을 수정합니다. 
- 
    다음 명령어를 실행하고 프롬프트에 yes를 입력하여 Terraform 구성을 적용합니다.terraform apply Terraform에 '적용 완료' 메시지가 표시될 때까지 기다립니다. 
- 결과를 보려면 Google Cloud 프로젝트를 엽니다. Google Cloud 콘솔에서 UI의 리소스로 이동하여 Terraform이 리소스를 만들었거나 업데이트했는지 확인합니다.
서비스 계정에 액세스 권한 부여
연결의 서비스 계정에 Vertex AI 사용자 및 스토리지 객체 뷰어 역할을 부여합니다.
원격 모델을 만들 때 엔드포인트를 URL(예: endpoint = 'https://us-central1-aiplatform.googleapis.com/v1/projects/myproject/locations/us-central1/publishers/google/models/gemini-2.0-flash')로 지정할 계획이라면 URL에 지정한 동일한 프로젝트에서 이 역할을 부여합니다.
원격 모델을 만들 때 모델 이름을 사용(예: endpoint = 'gemini-2.0-flash')하여 엔드포인트를 지정할 계획이라면 원격 모델을 만들려는 동일한 프로젝트에서 이 역할을 부여합니다.
다른 프로젝트에서 역할을 부여하면 bqcx-1234567890-wxyz@gcp-sa-bigquery-condel.iam.gserviceaccount.com does not have the permission to access resource 오류가 발생합니다.
이러한 역할을 부여하려면 다음 단계를 수행합니다.
콘솔
- IAM 및 관리자 페이지로 이동합니다. 
- 추가를 클릭합니다. - 주 구성원 추가 대화상자가 열립니다. 
- 새 주 구성원 필드에 앞에서 복사한 서비스 계정 ID를 입력합니다. 
- 역할 선택 필드에서 Vertex AI를 선택한 후 Vertex AI 사용자를 선택합니다. 
- 다른 역할 추가를 클릭합니다. 
- 역할 선택 필드에서 Cloud Storage를 선택한 후 스토리지 객체 뷰어를 선택합니다. 
- 저장을 클릭합니다. 
gcloud
gcloud projects add-iam-policy-binding 명령어를 사용합니다.
gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/aiplatform.user' --condition=None gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/storage.objectViewer' --condition=None
다음을 바꿉니다.
- PROJECT_NUMBER: 역할을 부여할 프로젝트의 프로젝트 번호
- MEMBER: 이전에 복사한 서비스 계정 ID
객체 테이블 만들기
Cloud Storage에서 이미지를 이동하지 않고 분석하려면 객체 테이블을 만드세요.
객체 테이블을 만들려면 다음 안내를 따르세요.
SQL
CREATE EXTERNAL TABLE 문을 사용합니다.
- Google Cloud 콘솔에서 BigQuery 페이지로 이동합니다. 
- 쿼리 편집기에서 다음 문을 입력합니다. - CREATE EXTERNAL TABLE `PROJECT_ID.DATASET_ID.TABLE_NAME` WITH CONNECTION {`PROJECT_ID.REGION.CONNECTION_ID`| DEFAULT} OPTIONS( object_metadata = 'SIMPLE', uris = ['BUCKET_PATH'[,...]], max_staleness = STALENESS_INTERVAL, metadata_cache_mode = 'CACHE_MODE'); - 다음을 바꿉니다. - PROJECT_ID: 프로젝트 ID입니다.
- DATASET_ID: 생성한 데이터 세트의 ID입니다.
- TABLE_NAME: 객체 테이블의 이름입니다.
- REGION: 연결이 포함된 리전 또는 멀티 리전입니다.
- CONNECTION_ID: 만든 연결의 ID입니다.- Google Cloud 콘솔에서 연결 세부정보를 볼 때 이는 연결 ID에 표시되는 정규화된 연결 ID의 마지막 섹션에 있는 값입니다(예: - projects/myproject/locations/connection_location/connections/myconnection).- 기본 연결을 사용하려면 - PROJECT_ID.REGION.CONNECTION_ID가 포함된 연결 문자열 대신- DEFAULT를 지정합니다.
- BUCKET_PATH: 이미지가 포함된 Cloud Storage 버킷의 경로이며- ['gs://bucket_name/[folder_name/]*']형식입니다.- 사용하는 Cloud Storage 버킷은 모델을 만들고 - ML.GENERATE_EMBEDDING함수를 호출하려는 동일한 프로젝트에 있어야 합니다. 객체 테이블에서 사용하는 Cloud Storage 버킷이 포함된 프로젝트가 아닌 다른 프로젝트에서- ML.GENERATE_EMBEDDING함수를 호출하려면- service-A@gcp-sa-aiplatform.iam.gserviceaccount.com서비스 계정에 버킷 수준에서 스토리지 관리자 역할을 부여해야 합니다.
- STALENESS_INTERVAL: 캐시된 메타데이터가 객체 테이블에 대한 작업에서 사용되는지 여부와 작업이 사용하기 위해 캐시된 메타데이터가 작업에서 사용되려면 얼마나 최신이어야 하는지를 지정합니다. 메타데이터 캐싱 고려사항에 대한 자세한 내용은 성능을 위한 메타데이터 캐싱을 참조하세요.- 메타데이터 캐싱을 사용 중지하려면 0을 지정합니다. 이 값이 기본값입니다. - 메타데이터 캐싱을 사용 설정하려면 30분에서 7일 사이의 간격 리터럴 값을 지정합니다. 예를 들어 4시간 비활성 간격의 경우 - INTERVAL 4 HOUR를 지정합니다. 이 값을 사용하면 지난 4시간 이내에 새로고침된 경우 테이블에 대한 작업이 캐시된 메타데이터를 사용합니다. 캐시된 메타데이터가 이보다 오래된 경우 작업이 대신 Cloud Storage에서 메타데이터를 검색합니다.
- CACHE_MODE: 메타데이터 캐시를 자동 또는 수동으로 새로고침할지 지정합니다. 메타데이터 캐싱 고려사항에 대한 자세한 내용은 성능을 위한 메타데이터 캐싱을 참조하세요.- 시스템 정의 간격(일반적으로 30~60분)으로 메타데이터 캐시를 새로고침하려면 - AUTOMATIC으로 설정합니다.- 지정한 일정에 따라 메타데이터 캐시를 새로고침하려면 - MANUAL로 설정합니다. 이 경우- BQ.REFRESH_EXTERNAL_METADATA_CACHE시스템 프로시져를 호출하여 캐시를 새로고침할 수 있습니다.- STALENESS_INTERVAL이 0보다 큰 값으로 설정된 경우- CACHE_MODE를 설정해야 합니다.
 
- 실행을 클릭합니다. 
쿼리를 실행하는 방법에 대한 자세한 내용은 대화형 쿼리 실행을 참조하세요.
bq
bq mk 명령어를 사용합니다.
bq mk --table \ --external_table_definition=BUCKET_PATH@REGION.CONNECTION_ID \ --object_metadata=SIMPLE \ --max_staleness=STALENESS_INTERVAL \ --metadata_cache_mode=CACHE_MODE \ PROJECT_ID:DATASET_ID.TABLE_NAME
다음을 바꿉니다.
- BUCKET_PATH: 이미지가 포함된 Cloud Storage 버킷의 경로이며- ['gs://bucket_name/[folder_name/]*']형식입니다.- 사용하는 Cloud Storage 버킷은 모델을 만들고 - ML.GENERATE_EMBEDDING함수를 호출하려는 동일한 프로젝트에 있어야 합니다. 객체 테이블에서 사용하는 Cloud Storage 버킷이 포함된 프로젝트가 아닌 다른 프로젝트에서- ML.GENERATE_EMBEDDING함수를 호출하려면- service-A@gcp-sa-aiplatform.iam.gserviceaccount.com서비스 계정에 버킷 수준에서 스토리지 관리자 역할을 부여해야 합니다.
- REGION: 연결이 포함된 리전 또는 멀티 리전입니다.
- CONNECTION_ID: 만든 연결의 ID입니다.- Google Cloud 콘솔에서 연결 세부정보를 볼 때 이는 연결 ID에 표시되는 정규화된 연결 ID의 마지막 섹션에 있는 값입니다(예: - projects/myproject/locations/connection_location/connections/myconnection).
- STALENESS_INTERVAL: 캐시된 메타데이터가 객체 테이블에 대한 작업에서 사용되는지 여부와 작업이 사용하기 위해 캐시된 메타데이터가 작업에서 사용되려면 얼마나 최신이어야 하는지를 지정합니다. 메타데이터 캐싱 고려사항에 대한 자세한 내용은 성능을 위한 메타데이터 캐싱을 참조하세요.- 메타데이터 캐싱을 사용 중지하려면 0을 지정합니다. 이 값이 기본값입니다. - 메타데이터 캐싱을 사용 설정하려면 30분에서 7일 사이의 간격 리터럴 값을 지정합니다. 예를 들어 4시간 비활성 간격의 경우 - INTERVAL 4 HOUR를 지정합니다. 이 값을 사용하면 지난 4시간 이내에 새로고침된 경우 테이블에 대한 작업이 캐시된 메타데이터를 사용합니다. 캐시된 메타데이터가 이보다 오래된 경우 작업이 대신 Cloud Storage에서 메타데이터를 검색합니다.
- CACHE_MODE: 메타데이터 캐시를 자동 또는 수동으로 새로고침할지 지정합니다. 메타데이터 캐싱 고려사항에 대한 자세한 내용은 성능을 위한 메타데이터 캐싱을 참조하세요.- 시스템 정의 간격(일반적으로 30~60분)으로 메타데이터 캐시를 새로고침하려면 - AUTOMATIC으로 설정합니다.- 지정한 일정에 따라 메타데이터 캐시를 새로고침하려면 - MANUAL로 설정합니다. 이 경우- BQ.REFRESH_EXTERNAL_METADATA_CACHE시스템 프로시져를 호출하여 캐시를 새로고침할 수 있습니다.- STALENESS_INTERVAL이 0보다 큰 값으로 설정된 경우- CACHE_MODE를 설정해야 합니다.
- PROJECT_ID: 프로젝트 ID입니다.
- DATASET_ID: 생성한 데이터 세트의 ID입니다.
- TABLE_NAME: 객체 테이블의 이름입니다.
모델 만들기
- Google Cloud 콘솔에서 BigQuery 페이지로 이동합니다. 
- 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: 만든 연결의 ID입니다.- Google Cloud 콘솔에서 연결 세부정보를 볼 때 이는 연결 ID에 표시되는 정규화된 연결 ID의 마지막 섹션에 있는 값입니다(예: - projects/myproject/locations/connection_location/connections/myconnection).
- ENDPOINT: 사용할 임베딩 LLM(이 경우- multimodalembedding@001)- 원격 모델을 만들 때 URL을 엔드포인트로 지정하는 경우(예: - endpoint = 'https://us-central1-aiplatform.googleapis.com/v1/projects/myproject/locations/us-central1/publishers/google/models/multimodalembedding@001') URL에 지정한 프로젝트가 연결에 Vertex AI 사용자 역할을 부여한 프로젝트인지 확인합니다. 서비스 계정을 찾습니다- multimodalembedding@001모델은 원격 모델을 만드는 위치에서 사용할 수 있어야 합니다. 자세한 내용은 위치를 참조하세요.
 
이미지 임베딩 생성
객체 테이블의 이미지 데이터를 사용하여 ML.GENERATE_EMBEDDING 함수로 이미지 임베딩을 생성합니다.
SELECT * FROM ML.GENERATE_EMBEDDING( MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`, TABLE `PROJECT_ID.DATASET_ID.TABLE_NAME`, STRUCT(FLATTEN_JSON AS flatten_json_output, OUTPUT_DIMENSIONALITY AS output_dimensionality) );
다음을 바꿉니다.
- PROJECT_ID: 모델 또는 테이블이 포함된 프로젝트
- DATASET_ID: 모델 또는 테이블이 포함된 데이터 세트
- MODEL_NAME:- multimodalembedding@001모델에 대한 원격 모델의 이름
- TABLE_NAME: 삽입할 이미지가 포함된 객체 테이블의 이름
- FLATTEN_JSON: 임베딩을 별도의 열로 파싱할지 여부를 나타내는- BOOL값. 기본값은- TRUE입니다.
- OUTPUT_DIMENSIONALITY: 임베딩을 생성할 때 사용할 차원 수를 지정하는- INT64값입니다. 유효한 값은- 128,- 256,- 512,- 1408입니다. 기본값은- 1408입니다. 예를 들어- 256 AS output_dimensionality를 지정하면- ml_generate_embedding_result출력 열에 각 입력 값에 대한 임베딩이 256개 포함됩니다.
예
다음 예시는 images 객체 테이블의 이미지 임베딩을 만드는 방법을 보여줍니다.
SELECT * FROM ML.GENERATE_EMBEDDING( MODEL `mydataset.embedding_model`, TABLE `mydataset.images`, STRUCT(TRUE AS flatten_json_output, 512 AS output_dimensionality) );
다음 단계
- 텍스트 및 이미지 임베딩을 사용하여 텍스트-이미지 시맨틱 검색을 수행하는 방법 알아보기
- 시맨틱 검색 및 검색 증강 생성(RAG)에 텍스트 임베딩을 사용하는 방법 알아보기