Voyage AICompatible with Milvus 2.6.x

이 항목에서는 Milvus에서 Voyage AI 임베딩 기능을 구성하고 사용하는 방법에 대해 설명합니다.

임베딩 모델 선택

Milvus는 Voyage AI에서 제공하는 임베딩 모델을 지원합니다. 아래는 현재 사용 가능한 임베딩 모델을 빠르게 참조할 수 있습니다:

모델 이름	크기	최대 토큰	설명
VOYAGE-3-LARGE	1,024(기본), 256, 512, 2,048	32,000	최고의 범용 및 다국어 검색 품질.
VOYAGE-3	1,024	32,000	범용 및 다국어 검색 품질에 최적화되어 있습니다. 자세한 내용은 블로그 게시물을 참조하세요.
VOYAGE-3-LITE	512	32,000	지연 시간 및 비용에 최적화되었습니다. 자세한 내용은 블로그 게시물을 참조하세요.
voyage-code-3	1,024(기본값), 256, 512, 2,048	32,000	코드 검색에 최적화되어 있습니다. 자세한 내용은 블로그 게시물을 참조하세요.
voyage-finance-2	1,024	32,000	재무 검색 및 RAG에 최적화되었습니다. 자세한 내용은 블로그 게시물을 참조하세요.
VOYAGE-LAW-2	1,024	16,000	법률 검색 및 RAG에 최적화되었습니다. 또한 모든 도메인에서 성능이 향상되었습니다. 자세한 내용은 블로그 게시물을 참조하세요.
voyage-code-2	1,536	16,000	코드 검색에 최적화(대안 대비 17% 개선) / 이전 세대의 코드 임베딩. 자세한 내용은 블로그 게시물을 참조하세요.

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

자격 증명 구성

Milvus는 임베딩을 요청하기 전에 Voyage AI API 키를 알고 있어야 합니다. Milvus는 두 가지 방법으로 자격 증명을 구성할 수 있습니다:

• 구성 파일(권장): API 키를 milvus.yaml 에 저장하여 재시작할 때마다 노드가 자동으로 가져옵니다.

• 환경 변수: 배포 시점에 키를 주입하는 방법(Docker Compose에 이상적).

아래 두 가지 방법 중 하나를 선택하세요. 구성 파일은 베어메탈 및 가상 머신에서 유지 관리가 더 쉬운 반면, 환경 변수 경로는 컨테이너 워크플로우에 적합합니다.

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

API 키를 milvus.yaml; Milvus는 시작 시 키를 읽고 동일한 공급자에 대한 모든 환경 변수를 재정의합니다.

1. **아래에 키를 선언하세요. credential:

   하나 또는 여러 개의 API 키를 나열할 수 있으며, 각 키에 나중에 참조할 레이블을 지정할 수 있습니다.

   # milvus.yaml
   credential:
     apikey_dev:            # dev environment
       apikey: <YOUR_DEV_KEY>
     apikey_prod:           # production environment
       apikey: <YOUR_PROD_KEY>    
   

   여기에 API 키를 넣으면 재시작 시에도 지속되며 레이블을 변경하는 것만으로 키를 전환할 수 있습니다.

2. Milvus에 서비스 호출에 사용할 키 알려주기

   동일한 파일에서 Voyage AI 제공업체가 사용하려는 레이블을 가리키세요.

   function:
     textEmbedding:
       providers:
         voyageai:
           credential: apikey_dev      # ← choose any label you defined above
           # url: https://api.voyageai.com/v1/embeddings   # (optional) custom url
   

   이렇게 하면 Milvus가 Voyage AI 임베딩 엔드포인트로 보내는 모든 요청에 특정 키가 바인딩됩니다.

옵션 2: 환경 변수

Docker Compose로 Milvus를 실행하고 파일과 이미지에서 비밀을 유지하려는 경우 이 방법을 사용하세요.

Milvus는 milvus.yaml 에서 공급자에 대한 키를 찾을 수 없는 경우에만 환경 변수로 되돌아갑니다.

변수	필수	설명
MILVUSAI_VOYAGEAI_API_KEY	Yes	유효한 Voyage AI API 키입니다.

docker-compose.yaml 파일에서 MILVUSAI_VOYAGEAI_API_KEY 환경 변수를 설정합니다.

# docker-compose.yaml (standalone service section)
standalone:
  # ... other configurations ...
  environment:
    # ... other environment variables ...
    # Set the environment variable pointing to the Voyage AI API key inside the container
    MILVUSAI_VOYAGEAI_API_KEY: <MILVUSAI_VOYAGEAI_API_KEY>

environment: 블록은 호스트 OS는 그대로 둔 채 Milvus 컨테이너에만 키를 삽입합니다. 자세한 내용은 Docker Compose로 Milvus 구성을 참조하세요.

임베딩 기능 사용

자격 증명이 구성되면 다음 단계에 따라 임베딩 함수를 정의하고 사용하세요.

1단계: 스키마 필드 정의

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

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

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

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

다음 예에서는 텍스트 데이터를 저장하는 스칼라 필드( "document" ) 1개와 함수 모듈에서 생성할 임베딩을 저장하는 벡터 필드( "dense" ) 1개가 있는 스키마를 정의합니다. 선택한 임베딩 모델의 출력과 일치하도록 벡터 차원(dim)을 설정하는 것을 잊지 마세요.

from pymilvus import MilvusClient, DataType, Function, FunctionType

# Initialize Milvus client
client = MilvusClient(
    uri="http://localhost:19530",
)

# Create a new schema for the collection
schema = client.create_schema()

# Add primary field "id"
schema.add_field("id", DataType.INT64, is_primary=True, auto_id=False)

# Add scalar field "document" for storing textual data
schema.add_field("document", DataType.VARCHAR, max_length=9000)

# Add vector field "dense" for storing embeddings.
# IMPORTANT: Set dim to match the exact output dimension of the embedding model.
schema.add_field("dense", DataType.FLOAT_VECTOR, dim=1024)

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

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

아래 예는 스칼라 필드 "document" 를 임베딩으로 변환하여 결과 벡터를 앞서 정의한 "dense" 벡터 필드에 저장하는 함수 모듈(voya)을 추가한 것입니다.

임베딩 함수를 정의한 후에는 컬렉션 스키마에 추가합니다. 이렇게 하면 Milvus가 지정된 임베딩 함수를 사용하여 텍스트 데이터의 임베딩을 처리하고 저장하도록 지시합니다.

# Define embedding function specifically for embedding model provider
text_embedding_function = Function(
    name="voya",                                  # 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 field(s) for storing embeddings
    params={                                      # Provider-specific embedding parameters (function-level)
        "provider": "voyageai",                   # Must be set to "voyageai"
        "model_name": "voyage-3-large",                 # Specifies the embedding model to use
        # Optional parameters:
        # "credential": "apikey_dev",      # Optional: Credential label specified in milvus.yaml
        # "url": "https://api.voyageai.com/v1/embeddings",     # Defaults to the official endpoint if omitted
        # "dim": "1024"                           # Output dimension of the vector embeddings after truncation
        # "truncation": "true"                    # Whether to truncate the input texts to fit within the context length. Defaults to true.
    }
)

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

다음 단계

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