OpenAICompatible with Milvus 2.6.x

모델을 선택하고 OpenAI API 키로 Milvus를 구성하여 Milvus에 OpenAI 임베딩 모델을 사용하세요.

임베딩 모델 선택하기

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

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

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

자격 증명 구성

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

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

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

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

옵션 2: 환경 변수

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

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

변수	필수	설명
MILVUSAI_OPENAI_API_KEY	Yes	각 Milvus 컨테이너 내에서 OpenAI 키를 사용할 수 있도록 설정합니다 ( milvus.yaml 에 OpenAI 키가 있는 경우 무시됨).

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

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

environment: 블록은 Milvus 컨테이너에만 키를 주입하며 호스트 OS는 그대로 유지합니다. 자세한 내용은 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.
# For instance, OpenAI's text-embedding-3-small model outputs 1536-dimensional vectors.
schema.add_field("dense", DataType.FLOAT_VECTOR, dim=1536)

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

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

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

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

# Define embedding function (example: OpenAI provider)
text_embedding_function = Function(
    name="openai_embedding",                        # Unique identifier for this embedding function
    function_type=FunctionType.TEXTEMBEDDING,       # Type of embedding function
    input_field_names=["document"],                 # Scalar field to embed
    output_field_names=["dense"],                   # Vector field to store embeddings
    params={                                        # Provider-specific configuration (highest priority)
        "provider": "openai",                       # Embedding model provider
        "model_name": "text-embedding-3-small",     # Embedding model
        # Optional parameters:
        # "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 embedding function to your schema
schema.add_function(text_embedding_function)

다음 단계

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