Azure OpenAICompatible with Milvus 2.6.x

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

임베딩 모델 선택

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

모델	크기	최대 토큰	설명
TEXT-임베딩-3-SMALL	기본값: 1,536(1536 이하의 치수 크기로 잘릴 수 있음)	8,191	비용에 민감하고 확장 가능한 시맨틱 검색에 이상적이며, 더 낮은 가격대에 강력한 성능을 제공합니다.
텍스트 임베딩-3-대형	기본값: 3,072(3072 이하의 크기 크기로 잘릴 수 있음)	8,191	향상된 검색 정확도와 더 풍부한 의미 표현이 필요한 애플리케이션에 가장 적합합니다.
텍스트 임베딩-ADA-002	수정됨: 1,536(잘림을 지원하지 않음)	8,191	레거시 파이프라인 또는 이전 버전과의 호환성이 필요한 시나리오에 적합한 이전 세대 모델입니다.

3세대임베딩 모델(텍스트 임베딩-3)은 dim 파라미터를 통해 임베딩 크기 축소를 지원합니다. 일반적으로 임베딩 크기가 클수록 컴퓨팅, 메모리, 스토리지 측면에서 비용이 더 많이 듭니다. 치수 수를 조정할 수 있으면 전체 비용과 성능을 더 잘 제어할 수 있습니다. 각 모델에 대한 자세한 내용은 임베딩을 참조하세요.

자격 증명 구성

Milvus는 임베딩을 요청하기 전에 Azure OpenAI 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에 Azure OpenAI 호출에 사용할 키 알려주기

   동일한 파일에서 Azure OpenAI 공급자가 사용하려는 레이블을 가리키도록 합니다.

   function:
     textEmbedding:
       providers:
         azure_openai:
           credential: apikey_dev      # ← choose any label you defined above
           resource_name:  # Your azure openai resource name
           # url: # Your azure openai embedding url
   

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

옵션 2: 환경 변수

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

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

변수	필수	설명
MILVUSAI_AZURE_OPENAI_API_KEY	Yes	각 Milvus 컨테이너 내에서 Azure OpenAI 키를 사용할 수 있도록 설정합니다 (Azure OpenAI의 키가 milvus.yaml 에 있는 경우 무시됨).
MILVUSAI_AZURE_OPENAI_RESOURCE_NAME	예	Azure OpenAI 서비스 리소스를 생성할 때 정의한 Azure OpenAI 리소스 이름입니다.

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

# docker-compose.yaml (standalone service section)
standalone:
  # ... other configurations ...
  environment:
    # ... other environment variables ...
    # Set the environment variable pointing to the Azure OpenAI API key inside the container
    MILVUSAI_AZURE_OPENAI_API_KEY: <MILVUSAI_AZURE_OPENAI_API_KEY>
    MILVUSAI_AZURE_OPENAI_RESOURCE_NAME: <MILVUSAI_AZURE_OPENAI_RESOURCE_NAME>

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=1536)

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

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

# Define embedding function specifically for Azure OpenAI provider
text_embedding_function = Function(
    name="azopenai",                                # 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
        "provider": "azure_openai",                 # Embedding provider name (must be "azure_openai")
        "model_name": "zilliz-text-embedding-3-small",      # Model should be set to the deployment name you chose when you deployed the embedding model
        # Optional parameters (only specify if necessary):
        # "url": "https://{resource_name}.openai.azure.com/" # Optional: Your Azure OpenAI service endpoint
        # "credential": "apikey_dev",               # Optional: Credential label specified in milvus.yaml
        # "dim": "1536",                            # Optional: Shorten the output vector dimension
        # "user": "user123",                        # Optional: identifier for API tracking
    }
)

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

다음 단계

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