ベクトル類似度マッチング

API Reference / ナレッジAPI / ベクトル類似度マッチング

ベクトル類似度マッチング

最終更新日：約6時間後

クエリテキストに基づき、エージェント / ワークフローに紐付けられたナレッジベースから最も関連性の高いナレッジチャンクを検索し、チャンクの内容、ソースドキュメント、類似度スコアを返します。独自の RAG 構築、検索精度のテスト、ナレッジヒット率の調査などに利用できます。

インターフェースの注意事項

検索対象は、エージェント / ワークフローの公開済みバージョンに紐付けられたナレッジベースです。

本インターフェースは読み取り専用で、エージェント、ワークフロー、ナレッジベースを変更することはありません。

1 回のリクエストで指定できる data_ids は最大 10 件です。超過するとエラーコード 40332 が返ります。

リクエストメソッド

POST

リクエストURL

https://api-${endpoint}.gptbots.ai/v1/vector/match

リクエスト認証

認証方法の説明についてはAPI Overviewをご参照ください。

リクエスト

リクエスト例

例 1：指定したナレッジベースを検索する

curl -X POST 'https://api-${endpoint}.gptbots.ai/v1/vector/match' \ -H 'Authorization: Bearer ${API Key}' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "返品ポリシーについて教えてください。", "group_ids": ["6616e3f3d9d5cf1d5b6c8a21"], "top_k": 5, "doc_correlation": 0.5 }'

                      
                      curl -X POST 'https://api-${endpoint}.gptbots.ai/v1/vector/match' \
-H 'Authorization: Bearer ${API Key}' \
-H 'Content-Type: application/json' \
-d '{
    "prompt": "返品ポリシーについて教えてください。",
    "group_ids": ["6616e3f3d9d5cf1d5b6c8a21"],
    "top_k": 5,
    "doc_correlation": 0.5
}'

このコードブロックをポップアップで表示

例 2：指定ドキュメントに限定し、再ランク付けを有効にする

curl -X POST 'https://api-${endpoint}.gptbots.ai/v1/vector/match' \ -H 'Authorization: Bearer ${API Key}' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "返品ポリシーについて教えてください。", "data_ids": ["6616e4a2d9d5cf1d5b6c8a35", "6616e4a2d9d5cf1d5b6c8a36"], "top_k": 3, "embedding_rate": 0.8, "rerank_version": "BGE-Rerank" }'

                      
                      curl -X POST 'https://api-${endpoint}.gptbots.ai/v1/vector/match' \
-H 'Authorization: Bearer ${API Key}' \
-H 'Content-Type: application/json' \
-d '{
    "prompt": "返品ポリシーについて教えてください。",
    "data_ids": ["6616e4a2d9d5cf1d5b6c8a35", "6616e4a2d9d5cf1d5b6c8a36"],
    "top_k": 3,
    "embedding_rate": 0.8,
    "rerank_version": "BGE-Rerank"
}'

このコードブロックをポップアップで表示

リクエストヘッダー

フィールド	タイプ	説明
Authorization	Bearer ${API Key}	認証には `Authorization: Bearer ${API Key}` を使用してください。トークンはAPIキーページから取得できます。
Content-Type	application/json	データの形式は `application/json` を設定してください。

リクエストボディ

フィールド	タイプ	必須	説明
prompt	string	はい	ナレッジベースの内容とベクトル類似度マッチングを行うクエリテキストまたはキーワード。
top_k	int	はい	類似度が最も高い上位 K 件のチャンクを返します。有効範囲：[1,50]。
group_ids	array	いいえ	検索対象を限定するナレッジベース ID。 1 つ以上の ID が指定された場合、それらの和集合内で検索します； null または未指定の場合、すべてのナレッジベースを検索します；空配列 ([]) の場合、ナレッジベースは検索されません。
data_ids	array	いいえ	検索対象を限定するドキュメント ID。1 回のリクエストで最大 10 件まで指定でき、超過するとエラーコード 40332 が返ります。 1 つ以上の ID が指定された場合、それらの和集合内で検索します； null または未指定の場合、ドキュメントによる限定は行いません；空配列 ([]) の場合、ドキュメントは検索されません；ドキュメント ID はドキュメントリストの取得インターフェースで取得できます。検索できるのは AVAILABLE 状態のドキュメントのみです。
embedding_rate	float	いいえ	`キーワード`検索と`意味`検索の重み付け比率。範囲：[0,1]、デフォルトは 1。 0 の場合、キーワードのみで検索； 1 の場合、意味のみで検索； 0.4 の場合、キーワード 40%、意味 60%。
doc_correlation	float	いいえ	ナレッジ関連性スコアのしきい値。これを下回るチャンクは返されません。スコアが高いほど関連性が高くなりますが、しきい値が高すぎると利用可能なチャンクが得られない場合があります。有効範囲：[0.1,0.95]。
rerank_version	string	いいえ	ナレッジ再ランク付けモデルの名称。指定すると再ランク付けが有効になり、候補チャンクを並べ替えて検索精度を高めます。次のいずれかを選択：BGE-Rerank、Jina-reranker-v2-base-multilingual、Jina-colbert-v2、BCE-Rerank。

group_ids と data_ids の組み合わせ

group_ids	data_ids	検索範囲
未指定 / null	未指定 / null	すべてのナレッジベース
指定	未指定 / null	指定したナレッジベース内のすべてのドキュメント
未指定 / null	指定	指定したドキュメント
指定	指定	両者の和集合
[]	[]	結果なし

推奨される使い方

ナレッジベース全体を対象に RAG 検索する場合：group_ids のみを指定し、data_ids は指定しません。

特定のドキュメントに限定する場合：data_ids を 1 回あたり 10 件以内に分けてリクエストします。

[] を「すべて」の意味で使わないでください。[] は「検索しない」を意味します。

レスポンス

レスポンス例

{ "total": 2, "list": [ { "content": "お届け日から 7 日以内であれば、未開封の商品は理由を問わず返品を申請できます……", "data_id": "6616e4a2d9d5cf1d5b6c8a35", "document_name": "アフターサービスポリシー.pdf", "score": 0.87 }, { "content": "返送料はお客様のご負担となります。ただし品質上の問題がある場合を除きます……", "data_id": "6616e4a2d9d5cf1d5b6c8a35", "document_name": "アフターサービスポリシー.pdf", "score": 0.79 } ] }

                      
                      {
  "total": 2,
  "list": [
    {
      "content": "お届け日から 7 日以内であれば、未開封の商品は理由を問わず返品を申請できます……",
      "data_id": "6616e4a2d9d5cf1d5b6c8a35",
      "document_name": "アフターサービスポリシー.pdf",
      "score": 0.87
    },
    {
      "content": "返送料はお客様のご負担となります。ただし品質上の問題がある場合を除きます……",
      "data_id": "6616e4a2d9d5cf1d5b6c8a35",
      "document_name": "アフターサービスポリシー.pdf",
      "score": 0.79
    }
  ]
}

このコードブロックをポップアップで表示

成功時のレスポンス

フィールド	タイプ	説明
total	int	返されたチャンクの件数です。
list	JSON Array	チャンクのリストです。類似度の高い順に並びます。
content	string	チャンクの内容です。
data_id	string	チャンクが属するドキュメントの ID です。
document_name	string	チャンクが属するドキュメントの名称です。
score	float	類似度スコアです。高いほど関連性が高くなります。

エラー時のレスポンス

フィールド	タイプ	説明
code	Int	エラーコードです。
message	String	エラー詳細内容です。

エラーコード

HTTP ステータス	コード	メッセージ	対処方法
400	40000	不正なパラメータです	必須パラメータと値の範囲（top_k は [1,50]、embedding_rate は [0,1]、doc_correlation は [0.1,0.95]）を確認してください。
401	40127	開発者認証に失敗しました	API Key が正しいか、該当のエージェント / ワークフローのものかを確認してください。
403	40332	クエリで指定できるドキュメントは最大10件までです	1 回のリクエストの data_ids は 10 件以内にし、分割してリクエストするか、group_ids でナレッジベースを指定してください。
—	20059	エージェントが削除されました	対象のエージェント / ワークフローが存在するか確認してください。

よくある質問

Q1: 「ナレッジベースリストの取得」「ドキュメントリストの取得」は正常なのに、本インターフェースが 403 を返すのはなぜですか？

A: data_ids が 10 件を超えている可能性が高いです（エラーコード 40332）。リスト系のインターフェースには件数制限がありませんが、本インターフェースにはあります。data_ids の件数を減らすか、group_ids でナレッジベースを指定してください。

Q2: 結果が空（total が 0）の場合、どう調査すればよいですか？

A: 次の順に確認してください：group_ids または data_ids に空配列 [] を指定していないか；doc_correlation のしきい値が高すぎないか；対象ドキュメントが AVAILABLE 状態か；ナレッジベースがエージェント / ワークフローの公開済みバージョンに紐付けられているか。