埋め込み関数の概要Compatible with Milvus 2.6.x

MilvusのFunctionモジュールを使用すると、外部のエンベッディングサービスプロバイダ（OpenAI、AWS Bedrock、Google Vertex AIなど）を自動的に呼び出すことで、生のテキストデータをベクトルエンベッディングに変換することができます。Milvusは、プロバイダーへのリクエストの送信、エンベッディングの受信、コレクションへの保存をすべて行います。セマンティック検索では、クエリベクトルではなく、生のクエリデータのみを提供する必要があります。Milvusはインジェストに使用したのと同じモデルでクエリベクトルを生成し、保存されたベクターと比較し、最も関連性の高い結果を返します。

制限

• Functionモジュールが埋め込む入力フィールドは常に値を含んでいなければなりません。

• Functionモジュールはコレクションスキーマで明示的に定義されたフィールドのみを処理します。

• 埋め込む入力フィールドはVARCHAR 型でなければなりません。

• Functionモジュールは入力フィールドを次のように埋め込むことができる：

  • FLOAT_VECTOR

  • INT8_VECTOR

  BINARY_VECTOR 、FLOAT16_VECTOR 、BFLOAT16_VECTOR への変換はサポートされていません。

サポートされる埋め込みサービスプロバイダ

プロバイダー	代表的なモデル	埋め込みタイプ	認証方法
OpenAI	テキスト埋め込み	FLOAT_VECTOR	APIキー
Azure OpenAI	デプロイメントベース	FLOAT_VECTOR	APIキー
ダッシュスコープ	テキスト埋め込み-v3	FLOAT_VECTOR	APIキー
ベッドロック	amazon.titan-embed-text-v2	FLOAT_VECTOR	AK/SKペア
バーテックスAI	テキスト埋め込み-005	FLOAT_VECTOR	GCPサービスアカウントJSONクレデンシャル
Voyage AI	voyage-3, voyage-lite-02	FLOAT_VECTOR /INT8_VECTOR	APIキー
Cohere	エンベデッド-英語-v3.0	FLOAT_VECTOR /INT8_VECTOR	APIキー
シリコンフロー	BAAI/bge-large-zh-v1.5	FLOAT_VECTOR	APIキー
ハギングフェイス	TEI提供モデル	FLOAT_VECTOR	オプションのAPIキー

機能概要

以下の図は、Milvusにおける本機能の動作を示しています。

1. テキストを入力する：Milvusに生データ（文書など）を入力する。

2. 埋め込みデータを生成する：MilvusのFunctionモジュールは自動的に設定されたモデルプロバイダを呼び出し、生データをベクトル埋め込みデータに変換します。

3. 埋め込みデータを保存します：生成された埋め込みデータはMilvusコレクション内の明示的に定義されたベクトルフィールドに格納されます。

4. テキストクエリユーザはMilvusにテキストクエリを送信する。

5. セマンティック検索：Milvusは内部でクエリをベクトルの埋め込みに変換し、格納された埋め込みに対して類似検索を行い、関連する結果を取得します。

6. 結果を返す：Milvusはトップマッチの結果をアプリケーションに返します。

埋め込み機能の概要

認証情報の設定

Milvusでエンベッディング機能を使用する前に、Milvusにアクセスするためのエンベッディングサービスクレデンシャルを設定します。

Milvusでは2つの方法で埋め込みサービスの認証情報を提供することができます：

• 設定ファイル(milvus.yaml)：

  このトピックの例では、milvus.yaml を使用して推奨される設定を示します。

• 環境変数：

  環境変数: 環境変数を使用したクレデンシャルの設定の詳細については、エンベッディングサービスプロバイダのドキュメント（OpenAIやAzure OpenAI など）を参照してください。

以下の図は、Milvus設定ファイル(milvus.yaml)を介してクレデンシャルを設定し、Milvus内でFunctionを呼び出すプロセスを示しています。

クレデンシャル設定のオーバーフロー

ステップ 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" と、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)

// java

// nodejs

// go

# restful

ステップ 2: スキーマへの埋め込み関数の追加

MilvusのFunctionモジュールは、スカラーフィールドに格納された生データを自動的にエンベッディングに変換し、明示的に定義されたベクトルフィールドに格納します。

以下の例では、スカラーフィールド"document" をエンベッディングに変換するFunctionモジュール(openai_embedding)を追加し、結果のベクトルを先に定義した"dense" ベクトルフィールドに格納しています。

# 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	埋め込む生データを含むスカラーフィールド。現在、このパラメータは1つのフィールド名しか受け付けない。	["document"]
output_field_names	生成された埋め込みデータを格納するベクトルフィールド。現在、このパラメータは1つのフィールド名のみを受け付ける。	["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：データの挿入

コレクションとインデックスを設定したら、生データを挿入する準備ができた。このプロセスでは、生のテキストを提供するだけでよい。先ほど定義した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.'},
])

// 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

検索およびクエリ操作の詳細については、「基本的なベクトル検索と クエリ」を参照してください。

よくある質問

milvus.yamlで認証情報を設定する方法と環境変数で認証情報を設定する方法の違いは何ですか？

どちらの方法も機能しますが、milvus.yaml を使用するのが、クレデンシャルの一元管理とすべてのプロバイダーにわたる一貫したクレデンシャル命名を提供するため、推奨されるアプローチです。環境変数を使用する場合、変数名はエンベッディングサービスプロバイダによって異なるため、各プロバイダの専用ページを参照して、必要な特定の環境変数名を理解してください（たとえば、OpenAIや Azure OpenAIなど）。

関数定義でクレデンシャルパラメータを指定しなかった場合はどうなりますか？

Milvusはこのような順序でクレデンシャルを解決します：

1. まず、milvus.yaml ファイルでそのプロバイダ用に設定されたデフォルトのクレデンシャルを探します。
2. milvus.yamlにデフォルトのクレデンシャルが存在しない場合、（設定されていれば）環境変数にフォールバックします。
3. milvus.yaml のクレデンシャルも環境変数も設定されていない場合、milvusはエラーを投げます。

エンベッディングが正しく生成されているかどうかの確認方法は？

以下の方法で確認できます：

1. ベクターフィールドにデータが含まれているかどうか、挿入後にコレクションに問い合わせる。
2. ベクトルフィールドの長さが期待される次元と一致しているか確認する。
3. 単純な類似検索を実行し、埋め込みが意味のある結果を生成していることを確認する。

類似性検索を実行するとき、生のテキストではなくクエリーベクトルを使用できますか？

はい、生テキストの代わりに事前に計算されたクエリベクトルを類似性検索に使用することができます。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
)

// java

// nodejs

// go

# restful