버텍스 AICompatible with Milvus 2.6.x

구글 클라우드 버텍스 AI는 텍스트 임베딩 모델을 위해 특별히 설계된 고성능 서비스입니다. 이 가이드에서는 효율적인 텍스트 임베딩 생성을 위해 Milvus와 함께 구글 클라우드 버텍스 AI를 사용하는 방법을 설명합니다.

Vertex AI는 다양한 사용 사례에 맞는 여러 임베딩 모델을 지원합니다:

• gemini-embedding-001(영어, 다국어 및 코드 작업 전반에 걸친 최첨단 성능)

• text-embedding-005(최신 텍스트 임베딩 모델)

• text-multilingual-embedding-002(최신 다국어 텍스트 임베딩 모델)

자세한 내용은 버텍스 AI 텍스트 임베딩 모델을 참조하세요.

전제 조건

Vertex AI를 구성하기 전에 다음 요구 사항을 충족하는지 확인하세요:

• Milvus 버전 2.6 이상 실행 - 배포가 최소 버전 요구 사항을 충족하는지 확인합니다.

• Google Cloud 서비스 계정 만들기 - 최소한 'Vertex AI 사용자' 또는 기타 특정 역할이 필요할 수 있습니다. 자세한 내용은 서비스 계정 만들기를 참조하세요.

• 서비스 계정의 JSON 키 파일 다운로드 - 이 자격 증명 파일을 서버 또는 로컬 컴퓨터에 안전하게 저장합니다. 자세한 내용은 서비스 계정 키 만들기를 참조하세요.

자격 증명 구성

Milvus가 Vertex AI를 호출하려면 먼저 GCP 서비스 계정 JSON 키에 액세스해야 합니다. 두 가지 방법을 지원하므로 배포 및 운영 요구 사항에 따라 하나를 선택하세요.

옵션	우선순위	최적 대상
구성 파일 (milvus.yaml)	높음	클러스터 전체, 영구 설정
환경 변수 (MILVUSAI_GOOGLE_APPLICATION_CREDENTIALS)	낮음	컨테이너 워크플로우, 빠른 테스트

옵션 1: 구성 파일(권장 및 우선순위 높음)

Milvus는 항상 동일한 공급자에 대한 환경 변수보다 milvus.yaml 에 선언된 자격 증명을 선호합니다.

1. JSON 키 Base64 인코딩

   cat credentials.json | jq . | base64
   

2. 다음에서 자격 증명을 선언합니다. milvus.yaml

   # milvus.yaml
   credential:
     gcp_vertex:                      # arbitrary label
       credential_json: |
         <YOUR_BASE64_ENCODED_JSON>
   

3. 자격 증명을 Vertex AI 제공자에 바인딩합니다.

   # milvus.yaml
   function:
     textEmbedding:
       providers:
         vertexai:
           credential: gcp_vertex      # must match the label above
           url: <optional: custom Vertex AI endpoint>
   

   나중에 키를 교체해야 하는 경우 환경이나 컨테이너를 변경할 필요 없이 credential_json 에서 Base64 문자열을 업데이트하고 Milvus를 다시 시작하면 됩니다.

옵션 2: 환경 변수

배포 시점에 시크릿을 주입하는 것을 선호하는 경우 이 방법을 사용하세요. Milvus는 milvus.yaml 에 일치하는 항목이 없는 경우에만 env-vars로 되돌아갑니다.

임베딩 기능 사용

Vertex AI가 구성되면 다음 단계에 따라 임베딩 함수를 정의하고 사용하세요.

1단계: 스키마 필드 정의

임베딩 함수를 사용하려면 특정 스키마로 컬렉션을 만듭니다. 이 스키마에는 최소 3개의 필수 필드가 포함되어야 합니다:

• 컬렉션의 각 엔티티를 고유하게 식별하는 기본 필드.

• 임베드할 원시 데이터를 저장하는 스칼라 필드.

• 함수가 스칼라 필드에 대해 생성할 벡터 임베딩을 저장하기 위해 예약된 벡터 필드.

from pymilvus import MilvusClient, DataType, Function, FunctionType, CollectionSchema, FieldSchema

# Assume you have connected to Milvus
# client = MilvusClient(uri="http://localhost:19530")

# 1. Create Schema
schema = MilvusClient.create_schema()

# 2. Add fields
schema.add_field("id", DataType.INT64, is_primary=True, auto_id=False)
schema.add_field("document", DataType.VARCHAR, max_length=9000) # Store text data
# IMPORTANT: Set dim to match the output dimension of the model and parameters
schema.add_field("dense_vector", DataType.FLOAT_VECTOR, dim=768) # Store embedding vectors (example dimension)

2단계: 스키마에 임베딩 함수 추가하기

Milvus의 함수 모듈은 스칼라 필드에 저장된 원시 데이터를 임베딩으로 자동 변환하여 명시적으로 정의된 벡터 필드에 저장합니다.

# 3. Define Vertex AI embedding function
text_embedding_function = Function(
    name="vert_func",                           # Unique identifier for this embedding function
    function_type=FunctionType.TEXTEMBEDDING,   # Indicates a text embedding function
    input_field_names=["document"],             # Scalar field(s) containing text data to embed
    output_field_names=["dense_vector"],        # Vector field(s) for storing embeddings
    params={                                    # Vertex AI specific parameters (function-level)
        "provider": "vertexai",                 # Must be set to "vertexai"
        "model_name": "text-embedding-005",     # Required: Specifies the Vertex AI model to use
        "projectid": "your-gcp-project-id",     # Required: Your Google Cloud project ID
        # Optional parameters (include these only if necessary):
        # "location": "us-central1",            # Optional: Vertex AI service region (default us-central1)
        # "task": "DOC_RETRIEVAL",              # Optional: Embedding task type (default DOC_RETRIEVAL)
        # "dim": 768                            # Optional: Output vector dimension (1-768)
    }
)

# Add the configured embedding function to your existing collection schema
schema.add_function(text_embedding_function)

파라미터	설명	필수?	예제 값
provider	임베딩 모델 공급자. "vertexai"로 설정합니다.	예	"vertexai"
model_name	사용할 버텍스 AI 임베딩 모델을 지정합니다.	예	"text-embedding-005"
projectid	Google 클라우드 프로젝트 ID입니다.	예	"your-gcp-project-id"
location	Vertex AI 서비스를 위한 리전입니다. 현재 Vertex AI 임베딩은 주로 us-central1을 지원합니다. 기본값은 us-central1입니다.	No	"us-central1"
task	임베딩 결과에 영향을 미치는 임베딩 작업 유형을 지정합니다. 허용되는 값은 다음과 같습니다: DOC_RETRIEVAL(기본값), CODE_RETRIEVAL(005만 지원), STS(의미론적 텍스트 유사성).	No	"DOC_RETRIEVAL"
dim	출력 임베딩 벡터의 차원입니다. 1에서 768 사이의 정수를 사용할 수 있습니다. 참고: 지정한 경우 스키마에서 벡터 필드의 크기가 이 값과 일치하는지 확인하세요.	No	768

다음 단계

임베딩 함수를 구성한 후 함수 개요에서 인덱스 구성, 데이터 삽입 예제 및 시맨틱 검색 작업에 대한 추가 지침을 참조하세요.