Voyage AICompatible with Milvus 2.6.x

本主題描述如何在 Milvus 設定和使用 Voyage AI 嵌入功能。

選擇嵌入模型

Milvus 支援 Voyage AI 提供的嵌入模型。以下是目前可用的嵌入模型，以供快速參考：

模型名稱	尺寸	最大代幣	說明
voyage-3-large	1,024 (預設)、256、512、2,048	32,000	最佳的通用和多語言檢索品質。
航程-3	1,024	32,000	最佳化的一般用途與多語言檢索品質。詳情請參閱部落格文章。
voyage-3-lite	512	32,000	針對延遲與成本進行最佳化。詳情請參閱部落格文章。
voyage-code-3	1,024 (預設)、256、512、2,048	32,000	針對代碼擷取進行最佳化。詳情請參閱部落格文章。
voyage-finance-2	1,024	32,000	針對財務擷取與 RAG 最佳化。詳情請參閱部落格文章。
法律-2	1,024	16,000	針對法律檢索和 RAG 最佳化。同時改善了所有領域的效能。詳情請參閱部落格文章。
航程碼-2	1,536	16,000	針對代碼擷取進行最佳化 (比其他替代方案優異 17%) / 上一代代碼嵌入。詳情請參閱部落格文章。

詳情請參閱文字嵌入模型。

設定憑證

Milvus 必須知道您的 Voyage AI API 金鑰，才能請求嵌入。Milvus 提供兩種配置憑證的方法：

• 設定檔案 (建議使用)：將 API 金鑰儲存在milvus.yaml ，以便每次重新啟動和節點都會自動擷取。

• 環境變數：在部署時注入金鑰 - 最適合 Docker Compose。

在以下兩種方法中選擇一種--配置檔案在裸機和虛擬機器上較容易維護，而 env-var 路線則適合容器工作流程。

選項 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 服務呼叫使用哪個金鑰

   在同一個檔案中，將 Voyage AI 提供者指向您希望它使用的標籤。

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

   這樣，Milvus 傳送給 Voyage AI embeddings endpoint 的每個請求都會綁定特定的 key。

選項 2：環境變數

當您使用 Docker Compose 執行 Milvus，並希望不在檔案和影像中洩露秘密時，請使用此方法。

只有在milvus.yaml 中找不到提供者的金鑰時，Milvus 才會使用環境變數。

變數	需要	說明
MILVUSAI_VOYAGEAI_API_KEY	是	您有效的 Voyage AI API 金鑰。

在您的docker-compose.yaml檔案中，設定MILVUSAI_VOYAGEAI_API_KEY 環境變數。

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

environment: 區塊只會將金鑰注入 Milvus 容器，而不會碰觸您的主機作業系統。詳情請參考使用 Docker Compose 設定 Milvus。

使用嵌入功能

一旦配置了憑證，請按照以下步驟定義和使用嵌入函數。

步驟 1：定義模式欄位

若要使用嵌入函式，請建立具有特定模式的集合。此模式必須包含至少三個必要欄位：

• 唯一識別集合中每個實體的主要欄位。

• 儲存要嵌入的原始資料的標量欄位。

• 預留向量欄位，用來儲存函式將為標量欄位產生的向量嵌入。

以下範例定義了一個模式，其中一個標量欄位"document" 用來儲存文字資料，另一個向量欄位"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.
schema.add_field("dense", DataType.FLOAT_VECTOR, dim=1024)

步驟 2：在模式中加入嵌入函數

Milvus 中的 Function 模組會自動將儲存在標量欄位中的原始資料轉換為嵌入資料，並將其儲存在明確定義的向量欄位中。

下面的範例新增了一個 Function 模組 (voya)，將標量欄位"document" 轉換為嵌入，將產生的向量儲存到之前定義的"dense" 向量欄位中。

定義好嵌入函數後，將它加入集合模式。這會指示 Milvus 使用指定的 embedding 函式來處理和儲存文字資料的 embeddings。

# Define embedding function specifically for embedding model provider
text_embedding_function = Function(
    name="voya",                                  # 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": "voyageai",                   # Must be set to "voyageai"
        "model_name": "voyage-3-large",                 # Specifies the embedding model to use
        # Optional parameters:
        # "credential": "apikey_dev",      # Optional: Credential label specified in milvus.yaml
        # "url": "https://api.voyageai.com/v1/embeddings",     # Defaults to the official endpoint if omitted
        # "dim": "1024"                           # Output dimension of the vector embeddings after truncation
        # "truncation": "true"                    # Whether to truncate the input texts to fit within the context length. Defaults to true.
    }
)

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

下一步

配置完嵌入函數後，請參閱函數概觀，以獲得關於索引配置、資料插入範例和語意搜尋作業的其他指引。