OpenAI

원문 보기 위키 갱신 2026.10.08

Milvus 2.6.x와 호환돼요.

모델을 선택하고 Milvus를 OpenAI API 키로 구성해 OpenAI 임베딩 모델을 Milvus와 함께 사용해요.

출처: Milvus 문서

본문

임베딩 모델 선택 (Choose an embedding model)

Milvus는 OpenAI가 제공하는 모든 임베딩 모델을 지원해요. 현재 사용 가능한 OpenAI 임베딩 모델은 다음과 같아요.

모델 이름	차원	최대 토큰	설명
text-embedding-3-small	기본값: 1,536 (1,536 미만 크기로 줄일 수 있음)	8,191	비용에 민감하고 확장 가능한 시맨틱 검색에 이상적 — 낮은 가격에 강력한 성능을 제공해요.
text-embedding-3-large	기본값: 3,072 (3,072 미만 크기로 줄일 수 있음)	8,191	향상된 검색 정확도와 더 풍부한 시맨틱 표현이 필요한 애플리케이션에 최적이에요.
text-embedding-ada-002	고정: 1,536 (줄일 수 없음)	8,191	이전 세대 모델로, 레거시 파이프라인이나 하위 호환이 필요한 시나리오에 적합해요.

3세대 임베딩 모델(text-embedding-3)은 dim 파라미터로 임베딩 크기를 줄이는 것을 지원해요. 일반적으로 더 큰 임베딩은 컴퓨팅, 메모리, 저장소 관점에서 더 비싸요. 차원 수를 조정할 수 있게 되면 전체 비용과 성능을 더 잘 제어할 수 있어요. 각 모델에 대한 자세한 내용은 Embedding models와 OpenAI 발표 블로그를 참고하세요.

자격 증명 구성 (Configure credentials)

Milvus는 임베딩을 요청하기 전에 OpenAI API 키를 알고 있어야 해요. Milvus는 자격 증명을 구성하는 두 가지 방법을 제공해요.

설정 파일 (권장): milvus.yaml에 API 키를 저장하면 매번 재시작하고 모든 노드가 자동으로 가져와요.
환경 변수: 배포 시점에 키를 주입해요. Docker Compose에 이상적이에요.

아래 두 가지 방법 중 하나를 선택하세요. 설정 파일은 베어메탈과 VM에서 관리하기 쉽고, 환경 변수 방식은 컨테이너 워크플로우에 잘 맞아요.

같은 제공자에 대한 API 키가 설정 파일과 환경 변수 양쪽에 있다면 Milvus는 항상 milvus.yaml의 값을 사용하고 환경 변수는 무시해요.

옵션 1: 설정 파일 (권장 & 우선순위 높음)

API 키를 milvus.yaml에 넣어 두세요. Milvus는 시작 시 읽고, 같은 제공자에 대한 환경 변수를 덮어써요.

credential: 아래에 키를 선언해요.

하나 또는 여러 API 키를 나열할 수 있어요. 각각 나중에 참조할 라벨을 지어 주세요.

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

이곳에 API 키를 넣으면 재시작해도 유지되고, 라벨만 바꿔 키를 전환할 수 있어요.

OpenAI 호출에 사용할 키를 Milvus에 알려 주세요.

같은 파일에서 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는 건드리지 않아요. 자세한 내용은 Configure Milvus with Docker Compose를 참고하세요.

임베딩 함수 사용 (Use embedding function)

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

1단계: 스키마 필드 정의

임베딩 함수를 사용하려면 특정 스키마로 컬렉션을 만들어요. 이 스키마에는 최소 세 가지 필드가 필요해요.

컬렉션의 각 엔티티를 고유하게 식별하는 기본 필드
임베딩할 원본 데이터를 저장하는 스칼라 필드
함수가 스칼라 필드에 대해 생성한 벡터 임베딩을 저장하기 위해 예약된 벡터 필드

다음 예시는 텍스트 데이터를 저장할 스칼라 필드 "document" 하나와 Function 모듈이 생성할 임베딩을 저장할 벡터 필드 "dense" 하나를 가진 스키마를 정의해요. 벡터 차원(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의 Function 모듈은 스칼라 필드에 저장된 원본 데이터를 자동으로 임베딩으로 변환하고, 명시적으로 정의된 벡터 필드에 저장해요.

아래 예시는 스칼라 필드 "document"를 임베딩으로 변환하고, 결과 벡터를 앞서 정의한 "dense" 벡터 필드에 저장하는 Function 모듈(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)

다음 단계 (Next steps)

임베딩 함수를 구성한 뒤에는 Function Overview를 참고해 인덱스 구성, 데이터 삽입 예시, 시맨틱 검색 연산에 대한 추가 지침을 확인해요.

더 알아보기 (Learn more)

Embedding models — OpenAI 임베딩 모델 상세
Embedding Function Overview — 임베딩 함수 구성과 사용