Embedding Function 개요 (Embedding Function Overview)

원문 보기 위키 갱신 2026.10.09

Milvus 2.6.x와 호환돼요.

Milvus의 Function 모듈은 외부 임베딩 서비스 제공자(예: OpenAI, AWS Bedrock, Google Vertex AI 등)를 자동으로 호출해 원시 텍스트 데이터를 벡터 임베딩으로 변환할 수 있게 해줘요. Function 모듈을 사용하면 임베딩 API와 수동으로 연동할 필요가 없어요. Milvus가 제공자에게 요청을 보내고, 임베딩을 받고, 컬렉션에 저장하는 전체 과정을 처리해요. 시맨틱 검색에서는 쿼리 벡터가 아닌 원시 쿼리 데이터만 제공하면 돼요. Milvus가 데이터 수집에 사용한 것과 같은 모델로 쿼리 벡터를 생성하고, 저장된 벡터와 비교해 가장 관련성 높은 결과를 반환해요.

출처: Milvus 문서

본문

제한 사항 (Limits)

Function 모듈이 임베딩하는 입력 필드는 항상 값을 포함해야 해요. null이 제공되면 모듈이 오류를 발생시켜요.
Function 모듈은 컬렉션 스키마에 명시적으로 정의된 필드만 처리해요. 동적 필드에는 임베딩을 생성하지 않아요.
임베딩할 입력 필드는 VARCHAR 타입이어야 해요.
Function 모듈은 입력 필드를 다음 타입으로 임베딩할 수 있어요.

FLOAT_VECTOR

INT8_VECTOR

BINARY_VECTOR, FLOAT16_VECTOR, BFLOAT16_VECTOR로의 변환은 지원되지 않아요.

지원되는 임베딩 서비스 제공자 (Supported embedding service providers)

제공자	대표 모델	임베딩 타입	인증 방법
OpenAI	text-embedding-3-*	`FLOAT_VECTOR`	API key
Azure OpenAI	Deployment-based	`FLOAT_VECTOR`	API key
DashScope	text-embedding-v3	`FLOAT_VECTOR`	API key
Yandex Cloud	Yandex Cloud AI Studio text vectorization models	`FLOAT_VECTOR`	API key
Bedrock	amazon.titan-embed-text-v2	`FLOAT_VECTOR`	AK/SK pair
Vertex AI	text-embedding-005	`FLOAT_VECTOR`	GCP service account JSON credential
Voyage AI	voyage-3, voyage-lite-02	`FLOAT_VECTOR` / `INT8_VECTOR`	API key
Cohere	embed-english-v3.0	`FLOAT_VECTOR` / `INT8_VECTOR`	API key
SiliconFlow	BAAI/bge-large-zh-v1.5	`FLOAT_VECTOR`	API key
Hugging Face TEI	Any TEI-served model	`FLOAT_VECTOR`	Optional API key
Hugging Face	Models served through `hf-inference` for feature extraction	`FLOAT_VECTOR`	API key

작동 방식 (How it works)

다음 다이어그램은 Milvus에서 Function이 작동하는 방식을 보여 줘요.

입력 텍스트 (Input text): 사용자가 원시 데이터(예: 문서)를 Milvus에 삽입해요.
임베딩 생성 (Generate embeddings): Milvus 내의 Function 모듈이 구성된 모델 제공자를 자동으로 호출해 원시 데이터를 벡터 임베딩으로 변환해요.
임베딩 저장 (Store embeddings): 결과 임베딩은 Milvus 컬렉션 내 명시적으로 정의된 벡터 필드에 저장돼요.
쿼리 텍스트 (Query text): 사용자가 텍스트 쿼리를 Milvus에 제출해요.
시맨틱 검색 (Semantic search): Milvus는 내부적으로 쿼리를 벡터 임베딩으로 변환하고, 저장된 임베딩에 대해 유사도 검색을 수행해 관련 결과를 검색해요.
결과 반환 (Return results): Milvus는 가장 일치하는 결과를 애플리케이션에 반환해요.

자격 증명 구성 (Configure credentials)

Milvus에서 임베딩 함수를 사용하기 전에 Milvus 접근을 위한 임베딩 서비스 자격 증명을 구성해요.

Milvus는 두 가지 방법으로 임베딩 서비스 자격 증명을 제공할 수 있게 해줘요.

구성 파일 (milvus.yaml): 이 주제의 예시는 milvus.yaml을 사용한 권장 설정을 보여 줘요.
환경 변수: 환경 변수를 통한 자격 증명 구성에 대한 자세한 내용은 임베딩 서비스 제공자 문서(예: OpenAI 또는 Azure OpenAI)를 참고하세요.

다음 다이어그램은 Milvus 구성 파일(milvus.yaml)로 자격 증명을 구성한 뒤 Milvus 내에서 Function을 호출하는 과정을 보여 줘요.

1단계: Milvus 구성 파일에 자격 증명 추가 (Step 1)

milvus.yaml 파일에서 접근해야 하는 각 제공자의 항목으로 credential 블록을 편집해요.

# milvus.yaml credential store section
# This section defines all your authentication credentials for external embedding providers
# Each credential gets a unique name (e.g., aksk1, apikey1) that you'll reference elsewhere
credential:
  # For AWS Bedrock or services using access/secret key pairs
  # 'aksk1' is just an example name - you can choose any meaningful identifier
  aksk1:                       
    access_key_id: <YOUR_AK>      
    secret_access_key: <YOUR_SK>  
  
  # For OpenAI, Voyage AI, or other API key-based services
  # 'apikey1' is a custom name you choose to identify this credential  
  apikey1:                     
    apikey: <YOUR_API_KEY>        
  
  # For Google Vertex AI using service account credentials
  # 'gcp1' is an example name for your Google Cloud credentials
  gcp1:                        
    credential_json: <BASE64_OF_JSON>

2단계: 제공자 설정 구성 (Step 2)

같은 구성 파일(milvus.yaml)에서 function 블록을 편집해 임베딩 서비스 호출에 Milvus가 사용할 키를 알려줘요.

function:
  textEmbedding:
    providers:
      openai:                         # calls OpenAI
        credential: apikey1           # Reference to the credential label
        # url:                        # (optional) custom url

      bedrock:                        # calls AWS Bedrock
        credential: aksk1             # Reference to the credential label
        region: us-east-2

      vertexai:                       # calls Google Vertex AI
        credential: gcp1              # Reference to the credential label
        # url:                        # (optional) custom url

      tei:                            # Built-in Tiny Embedding model
        enable: true                  # Whether to enable TEI model service

Milvus 구성을 적용하는 방법에 대한 자세한 내용은 Configure Milvus on the Fly를 참고하세요.

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

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

1단계: 스키마 필드 정의 (Step 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.
# For dense vector, data type can be FLOAT_VECTOR or INT8_VECTOR
schema.add_field("dense", DataType.FLOAT_VECTOR, dim=1536)

2단계: 스키마에 임베딩 함수 추가 (Step 2)

Milvus의 Function 모듈은 스칼라 필드에 저장된 원시 데이터를 임베딩으로 자동 변환하고 이를 명시적으로 정의된 벡터 필드에 저장해요.

아래 예시는 스칼라 필드 "document"를 임베딩으로 변환하고 결과 벡터를 앞서 정의한 "dense" 벡터 필드에 저장하는 Function 모듈(openai_embedding)을 추가해요.

# 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
        # "credential": "apikey1",            # Optional: Credential label
        # Optional parameters:
        # "dim": "1536",       # Optionally shorten the vector dimension
        # "user": "user123"    # Optional: identifier for API tracking
    }
)

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

파라미터	설명	예시 값
`name`	Milvus 내 임베딩 함수의 고유 식별자.	`"openai_embedding"`
`function_type`	사용하는 함수의 타입. 텍스트 임베딩의 경우 값을 `FunctionType.TEXTEMBEDDING`으로 설정해요. 참고: Milvus는 이 파라미터에 `FunctionType.BM25`(스파스 임베딩 변환용)와 `FunctionType.RERANK`(재순위화용)를 허용해요. 자세한 내용은 Full Text Search와 Decay Ranker Overview를 참고하세요.	`FunctionType.TEXTEMBEDDING`
`input_field_names`	임베딩할 원시 데이터를 담은 스칼라 필드. 현재 이 파라미터는 필드 이름 하나만 허용해요.	`["document"]`
`output_field_names`	생성된 임베딩을 저장하는 벡터 필드. 현재 이 파라미터는 필드 이름 하나만 허용해요.	`["dense"]`
`params`	임베딩 구성을 담은 딕셔너리. 참고: `params` 내 파라미터는 임베딩 모델 제공자에 따라 달라져요.	`{...}`
`provider`	임베딩 모델 제공자.	`"openai"`
`model_name`	사용할 임베딩 모델을 지정해요.	`"text-embedding-3-small"`
`credential`	`milvus.yaml`의 최상위 `credential:` 섹션에 정의된 자격 증명의 라벨. 제공되면 Milvus가 일치하는 키 쌍 또는 API 토큰을 가져와 서버 쪽에서 요청에 서명해요. 생략하면(`None`) Milvus가 `milvus.yaml`에서 대상 모델 제공자에 대해 명시적으로 구성된 자격 증명으로 대체해요. 라벨을 알 수 없거나 참조된 키가 없으면 호출이 실패해요.	`"apikey1"`
`dim`	출력 임베딩의 차원 수. OpenAI 3세대 모델의 경우 의미 정보의 큰 손실 없이 비용과 지연 시간을 줄이기 위해 전체 벡터를 줄일 수 있어요. 자세한 내용은 OpenAI announcement blog post를 참고하세요. 참고: 벡터 차원을 줄이면 스키마의 `add_field` 메서드에 지정된 벡터 필드의 `dim` 값이 임베딩 함수의 최종 출력 차원과 일치하는지 확인하세요.	`"1536"`
`user`	API 사용량 추적을 위한 사용자 수준 식별자.	`"user123"`

텍스트-벡터 변환이 필요한 여러 스칼라 필드를 가진 컬렉션의 경우, 각 함수에 고유한 이름과 output_field_names 값이 있는지 확인하면서 컬렉션 스키마에 별도의 함수를 추가해요.

3단계: 인덱스 구성 (Step 3)

필요한 필드와 내장 함수가 있는 스키마를 정의한 뒤 컬렉션의 인덱스를 설정해요. 이 과정을 단순화하려면 index_type으로 AUTOINDEX를 사용해요. 이 옵션을 사용하면 Milvus가 데이터 구조에 따라 가장 적합한 인덱스 타입을 선택하고 구성해줘요.

# Prepare index parameters
index_params = client.prepare_index_params()

# Add AUTOINDEX to automatically select optimal indexing method
index_params.add_index(
    field_name="dense",
    index_type="AUTOINDEX",
    metric_type="COSINE" 
)

4단계: 컬렉션 생성 (Step 4)

이제 정의된 스키마와 인덱스 파라미터를 사용해 컬렉션을 만들어요.

# Create collection named "demo"
client.create_collection(
    collection_name='demo', 
    schema=schema, 
    index_params=index_params
)

5단계: 데이터 삽입 (Step 5)

컬렉션과 인덱스를 설정한 뒤 원시 데이터를 삽입할 준비가 됐어요. 이 과정에서는 원시 텍스트만 제공하면 돼요. 앞서 정의한 Function 모듈이 각 텍스트 항목에 대한 스파스 벡터를 자동으로 생성해요.

# Insert sample documents
client.insert('demo', [
    {'id': 1, 'document': 'Milvus simplifies semantic search through embeddings.'},
    {'id': 2, 'document': 'Vector embeddings convert text into searchable numeric data.'},
    {'id': 3, 'document': 'Semantic search helps users find relevant information quickly.'},
])

6단계: 벡터 검색 수행 (Step 6)

데이터 삽입 후 원시 쿼리 텍스트로 시맨틱 검색을 수행해요. Milvus가 쿼리를 임베딩 벡터로 자동 변환하고, 유사도를 기준으로 관련 문서를 검색해 가장 일치하는 결과를 반환해요.

# Perform semantic search
results = client.search(
    collection_name='demo', 
    data=['How does Milvus handle semantic search?'], # Use text query rather than query vector
    anns_field='dense',   # Use the vector field that stores embeddings
    limit=1,
    output_fields=['document'],
)

print(results)

# Example output:
# data: ["[{'id': 1, 'distance': 0.8821347951889038, 'entity': {'document': 'Milvus simplifies semantic search through embeddings.'}}]"]

검색과 쿼리 작업에 대한 자세한 내용은 Basic Vector Search와 Query를 참고하세요.

FAQ

milvus.yaml에서 자격 증명을 구성하는 것과 환경 변수의 차이는 무엇인가요?

두 방법 모두 동작하지만, milvus.yaml을 사용하는 것이 중앙 집중식 자격 증명 관리와 모든 제공자에 걸친 일관된 자격 증명 이름을 제공하므로 권장 접근 방식이에요. 환경 변수를 사용할 때는 변수 이름이 임베딩 서비스 제공자에 따라 달라지므로, 필요한 특정 환경 변수 이름을 이해하려면 각 제공자의 전용 페이지를 참고하세요(예: OpenAI 또는 Azure OpenAI).

함수 정의에 credential 파라미터를 지정하지 않으면 어떻게 되나요?

Milvus는 다음 자격 증명 해석 순서를 따라요.

먼저 milvus.yaml 파일에서 해당 제공자에 대해 구성된 기본 자격 증명을 찾아요.
milvus.yaml에 기본 자격 증명이 없으면 환경 변수로 대체해요(구성된 경우).
milvus.yaml 자격 증명도 환경 변수도 구성되지 않았으면 Milvus가 오류를 발생시켜요.

임베딩이 올바르게 생성되고 있는지 어떻게 확인하나요?

다음으로 확인할 수 있어요.

삽입 후 컬렉션을 쿼리해 벡터 필드에 데이터가 있는지 확인.
벡터 필드 길이가 예상 차원과 일치하는지 확인.
간단한 유사도 검색을 수행해 임베딩이 의미 있는 결과를 생성하는지 확인.

유사도 검색 시 원시 텍스트 대신 쿼리 벡터를 사용할 수 있나요?

네, 유사도 검색에 원시 텍스트 대신 미리 계산된 쿼리 벡터를 사용할 수 있어요. Function 모듈이 원시 텍스트 쿼리를 임베딩으로 자동 변환하지만, 검색 작업의 data 파라미터에 벡터 데이터를 직접 제공할 수도 있어요. 참고: 제공하는 쿼리 벡터의 차원 크기는 Function 모듈이 생성한 벡터 임베딩의 차원 크기와 일치해야 해요.

예시:

# Using raw text (Function module converts automatically)
results = client.search(
    collection_name='demo', 
    data=['How does Milvus handle semantic search?'],
    anns_field='dense',
    limit=1
)

# Using pre-computed query vector (must match stored vector dimensions)
query_vector = [0.1, 0.2, 0.3, ...]  # Must be same dimension as stored embeddings
results = client.search(
    collection_name='demo', 
    data=[query_vector],
    anns_field='dense',
    limit=1
)

더 알아보기 (Learn more)

Basic Vector Search — 기본 벡터 검색
Query — 쿼리 작업
Full Text Search — 전문 검색
Decay Ranker Overview — Decay Ranker 개요
Milvus 공식 문서 — 임베딩 관련 자료