CohereCompatible with Milvus 2.6.x

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

임베딩 모델 선택하기

Milvus는 Cohere에서 제공하는 임베딩 모델을 지원합니다. 아래는 현재 사용 가능한 임베딩 모델입니다:

모델 이름	치수	최대 토큰	설명
임베드-영어-V3.0	1,024	512	텍스트를 분류하거나 임베딩으로 변환할 수 있는 모델입니다. 영어로만 제공됩니다.
embed-multilingual-v3.0	1,024	512	다국어 분류 및 임베딩을 지원합니다. 지원되는 언어는 여기에서 확인하세요.
embed-english-light-v3.0	384	512	embed-english-v3.0 의 더 작고 빠른 버전. 기능은 거의 비슷하지만 훨씬 빠릅니다. 영어만 지원됩니다.
embed-multilingual-light-v3.0	384	512	embed-multilingual-v3.0 의 더 작고 빠른 버전. 기능은 거의 비슷하지만 훨씬 빠릅니다. 여러 언어를 지원합니다.
embed-english-v2.0	4,096	512	텍스트를 분류하거나 임베딩으로 전환할 수 있는 이전 임베딩 모델입니다. 영어만 지원.
embed-english-light-v2.0	1,024	512	embed-english-v2.0의 더 작고 빠른 버전. 기능은 거의 비슷하지만 훨씬 빠릅니다. 영어로만 제공됩니다.
embed-multilingual-v2.0	768	256	다국어 분류 및 임베딩을 지원합니다. 지원되는 언어는 여기를 참조하세요.

자세한 내용은 Cohere의 임베드 모델을 참조하세요.

자격 증명 구성

Milvus는 임베딩을 요청하기 전에 Cohere 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. 밀버스에게 OpenAI 호출에 사용할 키를 알려주세요.

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

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

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

옵션 2: 환경 변수

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

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

변수	필수	설명
MILVUSAI_COHERE_API_KEY	Yes	유효한 Cohere API 키입니다.

docker-compose.yaml 파일에서 MILVUSAI_COHERE_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_COHERE_API_KEY: <MILVUSAI_COHERE_API_KEY>

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

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

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

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

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

# Define embedding function specifically for embedding model provider
text_embedding_function = Function(
    name="cohere_func",                                 # 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 (function-level)
        "provider": "cohere",                           # Must be set to "cohere"
        "model_name": "embed-english-v3.0",             # Specifies the embedding model to use
        # Optional parameters:
        # "credential": "apikey_dev",               # Optional: Credential label specified in milvus.yaml
        # "url": "https://api.cohere.com/v2/embed",     # Defaults to the official endpoint if omitted
        # "truncate": "NONE",                           # Specifies how the API will handle inputs longer than the maximum token length.
    }
)

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

다음 단계

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