임베딩 함수 개요Compatible with Milvus 2.6.x

Milvus의 함수 모듈을 사용하면 외부 임베딩 서비스 제공업체(예: OpenAI, AWS Bedrock, Google Vertex AI 등)를 자동으로 호출하여 원시 텍스트 데이터를 벡터 임베딩으로 변환할 수 있습니다. 함수 모듈을 사용하면 더 이상 임베딩 API와 수동으로 인터페이스할 필요가 없습니다. Milvus는 제공업체에 요청을 보내고, 임베딩을 받고, 컬렉션에 저장하는 전체 프로세스를 처리합니다. 시맨틱 검색의 경우, 쿼리 벡터가 아닌 원시 쿼리 데이터만 제공하면 됩니다. Milvus는 수집에 사용한 것과 동일한 모델로 쿼리 벡터를 생성하고 저장된 벡터와 비교하여 가장 연관성이 높은 결과를 반환합니다.

제한

• 함수 모듈이 임베드하는 모든 입력 필드에는 항상 값이 포함되어야 하며, null이 제공되면 모듈에서 오류를 발생시킵니다.

• 함수 모듈은 컬렉션 스키마에 명시적으로 정의된 필드만 처리하며, 동적 필드에 대한 임베딩은 생성하지 않습니다.

• 임베드할 입력 필드는 VARCHAR 유형이어야 합니다.

• 함수 모듈은 입력 필드를 다음에 임베드할 수 있습니다:

  • FLOAT_VECTOR

  • INT8_VECTOR

  BINARY_VECTOR, FLOAT16_VECTOR, 또는 BFLOAT16_VECTOR 로의 변환은 지원되지 않습니다.

지원되는 임베딩 서비스 제공업체

공급자	일반적인 모델	임베딩 유형	인증 방법
OpenAI	텍스트 임베딩-3-*	FLOAT_VECTOR	API 키
Azure OpenAI	배포 기반	FLOAT_VECTOR	API 키
DashScope	텍스트 임베딩-v3	FLOAT_VECTOR	API 키
Bedrock	amazon.titan-embed-text-v2	FLOAT_VECTOR	AK/SK 쌍
버텍스 AI	text-embedding-005	FLOAT_VECTOR	GCP 서비스 계정 JSON 자격 증명
Voyage AI	보야지-3, 보야지-라이트-02	FLOAT_VECTOR / INT8_VECTOR	API 키
Cohere	embed-english-v3.0	FLOAT_VECTOR / INT8_VECTOR	API 키
SiliconFlow	BAAI/bge-large-zh-v1.5	FLOAT_VECTOR	API 키
허깅 페이스	모든 TEI 지원 모델	FLOAT_VECTOR	선택적 API 키

작동 방식

다음 다이어그램은 Milvus에서 함수가 작동하는 방식을 보여줍니다.

1. 텍스트 입력: 사용자가 Milvus에 원시 데이터(예: 문서)를 삽입합니다.

2. 임베딩 생성: Milvus의 함수 모듈은 구성된 모델 공급자를 자동으로 호출하여 원시 데이터를 벡터 임베딩으로 변환합니다.

3. 임베딩 저장: 결과 임베딩은 Milvus 컬렉션 내에 명시적으로 정의된 벡터 필드에 저장됩니다.

4. 쿼리 텍스트: 사용자가 Milvus에 텍스트 쿼리를 제출합니다.

5. 시맨틱 검색: Milvus는 내부적으로 쿼리를 벡터 임베딩으로 변환하고 저장된 임베딩에 대해 유사성 검색을 수행한 후 관련 결과를 검색합니다.

6. 결과 반환: Milvus는 가장 일치하는 결과를 애플리케이션에 반환합니다.

임베딩 기능 개요

자격 증명 구성

Milvus에서 임베딩 기능을 사용하기 전에 Milvus 액세스를 위한 임베딩 서비스 자격 증명을 구성하세요.

Milvus에서는 두 가지 방법으로 임베딩 서비스 자격 증명을 제공할 수 있습니다:

• 구성 파일 (milvus.yaml):

  이 항목의 예제에서는 milvus.yaml 를 사용하여 권장 설정을 보여줍니다.

• 환경 변수:

  환경 변수를 통한 자격 증명 구성에 대한 자세한 내용은 임베딩 서비스 제공업체의 설명서(예: OpenAI 또는 Azure OpenAI)를 참조하세요.

다음 다이어그램은 Milvus 구성 파일(milvus.yaml)을 통해 자격 증명을 구성한 다음 Milvus 내에서 함수를 호출하는 과정을 보여줍니다.

자격 증명 구성 오버플로

1단계: Milvus 구성 파일에 자격 증명 추가하기

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단계: 공급자 설정 구성

동일한 구성 파일(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 구성을 적용하는 방법에 대한 자세한 내용은 Milvus 즉시 구성을 참조하세요.

임베딩 기능 사용

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.
# For dense vector, data type can be FLOAT_VECTOR or INT8_VECTOR
schema.add_field("dense", DataType.FLOAT_VECTOR, dim=1536)

// java

// nodejs

// go

# restful

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

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

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

// java

// nodejs

// go

# restful

파라미터	설명	예제 값
name	Milvus 내 임베딩 함수에 대한 고유 식별자입니다.	"openai_embedding"
function_type	사용된 함수의 유형입니다. 텍스트 임베딩의 경우 값을 FunctionType.TEXTEMBEDDING 로 설정합니다. 참고: Milvus는 이 파라미터로 FunctionType.BM25 (스파스 임베딩 변환의 경우) 및 FunctionType.RERANK (재랭킹의 경우)를 허용합니다. 자세한 내용은 전체 텍스트 검색 및 감쇠 랭커 개요를 참조하세요.	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 발표 블로그 게시물을 참조하세요. 참고: 벡터 차원을 단축하는 경우, 벡터 필드에 대한 스키마의 add_field 메서드에 지정된 dim 값이 임베딩 함수의 최종 출력 차원과 일치하는지 확인하세요.	"1536"
user	API 사용량 추적을 위한 사용자 수준 식별자입니다.	"user123"

3단계: 인덱스 구성

필요한 필드와 기본 제공 함수로 스키마를 정의한 후에는 컬렉션의 인덱스를 설정합니다. 이 과정을 간소화하기 위해 AUTOINDEX 을 index_type 으로 사용하면 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" 
)

// java

// nodejs

// go

# restful

4단계: 컬렉션 생성

이제 정의한 스키마 및 인덱스 파라미터를 사용하여 컬렉션을 생성합니다.

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

// java

// nodejs

// go

# restful

5단계: 데이터 삽입

컬렉션과 인덱스를 설정했으면 이제 원시 데이터를 삽입할 준비가 되었습니다. 이 과정에서는 원시 텍스트만 제공하면 됩니다. 앞서 정의한 함수 모듈은 각 텍스트 항목에 해당하는 스파스 벡터를 자동으로 생성합니다.

# 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.'},
])

// java

// nodejs

// go

# restful

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.'}}]"]

// java

// nodejs

// go

# restful

검색 및 쿼리 작업에 대한 자세한 내용은 기본 벡터 검색 및 쿼리를 참조하세요.

FAQ

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

두 가지 방법 모두 작동하지만, 중앙 집중식 자격 증명 관리와 모든 공급업체에서 일관된 자격 증명 이름을 제공하기 때문에 milvus.yaml 을 사용하는 것이 권장됩니다. 환경 변수를 사용하는 경우 임베딩 서비스 제공업체에 따라 변수 이름이 다르므로 각 제공업체의 전용 페이지를 참조하여 필요한 특정 환경 변수 이름(예: OpenAI 또는 Azure OpenAI)을 파악하세요.

함수 정의에 자격 증명 매개변수를 지정하지 않으면 어떻게 되나요?

Milvus는 다음과 같은 자격 증명 확인 순서를 따릅니다:

1. 먼저 milvus.yaml 파일에서 해당 공급자에 대해 구성된 기본 자격 증명을 찾습니다.
2. milvus.yaml에 기본 자격 증명이 없는 경우 환경 변수(구성된 경우)로 되돌아갑니다.
3. milvus.yaml 자격 증명이나 환경 변수가 모두 구성되지 않은 경우 Milvus는 오류를 발생시킵니다.

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

다음 방법으로 확인할 수 있습니다:

1. 삽입 후 컬렉션을 쿼리하여 벡터 필드에 데이터가 포함되어 있는지 확인합니다.
2. 벡터 필드 길이가 예상 차원과 일치하는지 확인
3. 임베딩이 의미 있는 결과를 생성하는지 확인하기 위해 간단한 유사성 검색을 수행합니다.

유사도 검색을 수행할 때 원시 텍스트가 아닌 쿼리 벡터를 사용할 수 있나요?

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

예시:

# 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
)

// java

// nodejs

// go

# restful