Retrieve API は、Agent Storage のナレッジベースからコンテンツを取得します。ベクトル取得、全文取得、ハイブリッド取得をサポートしています。再ランキング戦略を設定することで、複数の取得パスからの結果をどのように融合し、ランキングするかを制御できます。
前提条件
ナレッジベースを作成し、ドキュメントをインポート済みであること。ドキュメントのステータスは
Completedである必要があります。PendingまたはIndexingステータスのドキュメントは取得できません。ナレッジベースでサブスペースが有効になっている場合、コンテンツを取得する際に
subspaceを渡す必要があります。
取得設定の優先度
Retrieve API の取得設定 (retrievalConfiguration) は、次の優先順位で有効なパラメーターを決定します:
| 優先度 | ソース | 説明 |
| 1 (最高) | Retrieve API パラメーター | 現在のリクエストで渡される retrievalConfiguration。そのリクエストに対してのみ有効です。 |
| 2 | ナレッジベースレベルの設定 | ナレッジベースの作成時に設定します。UpdateKnowledgeBase を使用していつでも変更できます。 |
| 3 (最低) | システムのデフォルト値 | ベクトル取得と全文取得のハイブリッド取得で、WEIGHT 加重融合 (ベクトル 0.7 : 全文 0.3) を使用し、20 件の結果を返します。 |
最もシンプルな取得リクエストでは、knowledgeBaseName と retrievalQuery のみを渡します。この場合、システムはナレッジベースの設定またはシステムのデフォルト値を使用します。
取得タイプ
| タイプ | 説明 | シナリオ |
DENSE_VECTOR | セマンティック類似性に基づくベクトル取得。 | セマンティック理解が必要な要件を自然言語で記述する場合に使用します。例えば、「インストール方法」は「デプロイメント手順」にマッチします。 |
FULL_TEXT | キーワード一致に基づく全文取得。 | 正確なキーワード、固有名詞、または識別子を入力する場合に使用します。 |
ベクトル取得と全文取得は互いに補完し合います。ベクトル取得はセマンティック理解に効果的であり、全文取得は完全一致に効果的です。両方の取得タイプを有効にし、再ランキングを使用して結果を融合することを推奨します。ハイブリッド取得を行うには、searchType で両方のタイプを渡します。
再ランキング戦略
再ランキングは、ベクトル取得と全文取得の結果を融合してランキングし、最終的な結果を返します。
WEIGHT (加重融合)
ベクトル取得と全文取得のスコアを比率で重み付けします。WEIGHT はシステムのデフォルト戦略です。2 つの取得パスの貢献度を詳細に制御する必要がある場合に使用します。デフォルトの選択肢として推奨されます。
| パラメーター | タイプ | デフォルト値 | 説明 |
denseVectorSearchWeight | double | 0.7 | ベクトル取得の重み。 |
fullTextSearchWeight | double | 0.3 | 全文取得の重み。 |
RRF (reciprocal rank fusion)
複数の取得パスからの結果を、それぞれのランクの逆数で重み付けして融合します。RRF は追加のモデル呼び出しを必要とせず、低レイテンシーで安定した結果を提供します。
| パラメーター | タイプ | デフォルト値 | 説明 |
denseVectorSearchWeight | double | 1.0 | ベクトル取得の重み。 |
fullTextSearchWeight | double | 1.0 | 全文取得の重み。 |
k | int | 60 | RRF アルゴリズムのパラメーター。0 より大きい必要があります。 |
次の例のように RRF を設定します:
{
"rerankingConfiguration": {
"type": "RRF",
"numberOfResults": 5,
"rrfConfiguration": {
"denseVectorSearchWeight": 0.6,
"fullTextSearchWeight": 0.4,
"k": 20
}
}
}MODEL (モデル再ランキング)
gte-rerank-v2 などの再ランキングモデルを呼び出して、候補結果を再ランキングします。この戦略は最高のランキング品質を提供しますが、レイテンシーと計算コストが増加します。
| パラメーター | タイプ | デフォルト値 | 説明 |
provider | string | bailian | 再ランキングモデルのプロバイダー。現在、Bailian のみがサポートされています。 |
model | string | gte-rerank-v2 | 再ランキングモデル名。 |
戦略の推奨事項
| シナリオ | 推奨戦略 |
| レイテンシーに敏感な一般的なシナリオ。 | RRF |
| ベクトル取得と全文取得の比率を詳細に制御する必要がある場合。 | WEIGHT |
| 最高のランキング品質が必要で、追加のレイテンシーが許容できる場合。 | MODEL |
メタデータフィルタリング
filter パラメーターを使用して、取得時にメタデータ条件で結果をフィルタリングし、候補範囲を絞り込みます。フィルターフィールドは、ナレッジベースの作成時に metadata を使用して定義する必要があります。演算子の完全なリストについては、「Retrieve Knowledge API」をご参照ください。
比較演算子
| 演算子 | 記号 | 説明 | 適用可能な型 |
equals | = | 等しい。 | すべての型 |
notEquals | ≠ | 等しくない。 | すべての型 |
greaterThan | > | より大きい。 | long, double, date |
greaterThanOrEquals | ≥ | 以上。 | long, double, date |
lessThan | < | より小さい。 | long, double, date |
lessThanOrEquals | ≤ | 以下。 | long, double, date |
セットおよび一致演算子
| 演算子 | 説明 | 適用可能な型 |
in | 値が指定されたセット内にある。 | すべての型 |
notIn | 値が指定されたセット内にない。 | すべての型 |
startsWith | 文字列のプレフィックスに一致する。 | string |
stringContains | 文字列に含まれるテキストに一致する。 | string |
listContains | リストフィールドに指定された要素が含まれている。 | list |
論理結合演算子
| 演算子 | 説明 |
andAll | すべての条件を満たす必要がある。 |
orAll | いずれかの条件を満たせばよい。 |
notAll | いずれの条件も満たされません。 |
andAll、orAll、notAll はネストをサポートしており、複雑な結合フィルターロジックを構築できます。
フィルターの例
カテゴリが "technology" または "science"、スコアが 60 以上、かつタイトルが中国語の「製品」で始まるドキュメントを照会します:
{
"filter": {
"andAll": [
{"in": {"key": "category", "value": ["technology", "science"]}},
{"greaterThanOrEquals": {"key": "score", "value": 60}},
{"startsWith": {"key": "title", "value": "产品"}}
]
}
}orAll を使用して OR ロジックを実装し、ステータスが「active」またはスコアが 90 より大きいドキュメントをクエリします:
{
"filter": {
"orAll": [
{"equals": {"key": "status", "value": "active"}},
{"greaterThan": {"key": "score", "value": 90}}
]
}
}取得の実行
取得テキスト
ビジネス要件がある場合は、チケットを送信するか、Tablestore 技術交流グループ 36165029092 に参加してテクニカルサポートにご連絡ください。textには、最大 128 文字を含めることができます。この制限を超えたリクエストはエラーを返します。
フィルターフィールドは、ナレッジベースの作成時にメタデータとして定義する必要があります。そうしないと、フィルター条件は有効になりません。
RRF パラメーター
kは 0 より大きい必要があります。そうしないと、VALIDATION_ERRORが返されます。PendingまたはIndexingステータスのドキュメントは取得できません。ステータスがCompletedになるまで待ってください。ナレッジベースでサブスペースが有効になっている場合は、
subspaceを渡す必要があります。そうしないと、エラーが返されます。
コンソール
コンソール
Agent Storage コンソールにログインし、対象のナレッジベースを開き、左側のナビゲーションウィンドウで [取得テスト] をクリックし、次のように取得結果を検証します:
[コンテンツ] 入力ボックスに取得テキストを入力します。ナレッジベースでサブスペースが有効になっている場合は、サブスペース名も入力します。
[検索タイプ] で、[ベクトル取得] または [全文取得] を選択します。
[ベクトル TopK]、[全文 TopK]、[再ランキング TopK] を設定します。デフォルト値のままでもかまいません。
[再ランキング戦略] を選択します:モデル、重み、または RRF。重みを選択した場合は、ベクトル取得と全文取得の重みを設定できます。デフォルト値のままでもかまいません。
ナレッジベースがメタデータフィールドを定義している場合は、メタデータフィルター条件を追加します。
[取得の実行] をクリックします。[取得されたチャンク] で、一致したチャンクのコンテンツ、ソース、および関連性スコアを表示します。
最初のテストでは、デフォルトのパラメーターを使用してください。対象のコンテンツが取得できることを確認した後、TopK と再ランキング戦略を徐々に調整してください。
SDK
Python
Python
最小限の例:取得パラメーターを渡しません。リクエストは、ナレッジベースレベルの設定またはシステムのデフォルト値を使用します。
from tablestore_agent_storage import AgentStorageClient
client = AgentStorageClient(
api_key="<your-api-key>",
ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
ots_instance_name="<instance-name>",
)
resp = client.retrieve({
"knowledgeBaseName": "product_docs_kb",
"retrievalQuery": {"type": "TEXT", "text": "What are the installation steps for the product?"}
})
for r in resp["data"]["retrievalResults"]:
print(f"[{r['score']:.4f}] {r['content'][:80]}...")完全な例:リクエストで取得パラメーターを設定して、ナレッジベースレベルの設定をオーバーライドします。
resp = client.retrieve({
"knowledgeBaseName": "product_docs_kb",
"subspace": ["default"],
"retrievalQuery": {"type": "TEXT", "text": "What are the installation steps for the product?"},
"retrievalConfiguration": {
"searchType": ["DENSE_VECTOR", "FULL_TEXT"],
"denseVectorSearchConfiguration": {"numberOfResults": 10},
"fullTextSearchConfiguration": {"numberOfResults": 10},
"rerankingConfiguration": {
"type": "RRF",
"numberOfResults": 5,
"rrfConfiguration": {
"denseVectorSearchWeight": 0.6,
"fullTextSearchWeight": 0.4,
"k": 60
}
},
"filter": {
"andAll": [
{"in": {"key": "category", "value": ["プロダクトドキュメント"]}}
]
}
}
})
for result in resp["data"]["retrievalResults"]:
print(f"[score={result['score']:.4f}] {result['content'][:100]}...")
print(f" source: {result['ossKey']}, chunkId: {result['chunkId']}")モデルクラスを使用してリクエストを構築すると、IDE のコード補完と型チェックが向上します。
from tablestore_agent_storage import AgentStorageClient
from tablestore_agent_storage.models import (
RetrieveRequest, RetrievalQuery, RetrievalQueryType
)
client = AgentStorageClient(
api_key="<your-api-key>",
ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
ots_instance_name="<instance-name>",
)
resp = client.retrieve(RetrieveRequest(
knowledge_base_name="product_docs_kb",
retrieval_query=RetrievalQuery(
text="What are the installation steps for the product?",
type=RetrievalQueryType.TEXT
)
))TypeScript
import { AgentStorageClient } from '@tablestore/agent-storage';
const client = new AgentStorageClient({
apiKey: '<your-api-key>',
endpoint: 'https://<instance>.<region>.ots.aliyuncs.com',
instanceName: '<instance-name>',
});
const resp = await client.retrieve({
knowledgeBaseName: 'product_docs_kb',
retrievalQuery: { type: 'TEXT', text: 'What are the installation steps for the product?' },
});
for (const r of resp.data.retrievalResults) {
console.log(`[${r.score.toFixed(4)}] ${r.content.slice(0, 80)}...`);
}API
Retrieve を呼び出して取得を実行します。リクエストフィールド、レスポンスフィールド、およびフィルター演算子の詳細については、「Retrieve Knowledge API」をご参照ください。
取得のチューニング
numberOfResults パラメーターの関係
取得プロセスには 3 つの numberOfResults 設定があります。これらの関係を理解することがチューニングの鍵となります:
denseVectorSearchConfiguration.numberOfResults = N1 ← ベクトル取得の再現数
fullTextSearchConfiguration.numberOfResults = N2 ← 全文取得の再現数
rerankingConfiguration.numberOfResults = N3 ← 再ランキング後の最終的な返却数N1 と N2 は候補プールサイズを決定します。値を大きくすると再現率は向上しますが、計算コストも増加します。
N3 は最終的に返される結果の数を決定します。通常、N3 < N1 かつ N3 < N2 です。
(推奨) まず N1 = N2 = 20、N3 = 5~10 から始め、実際の結果に基づいて値を徐々に調整します。
取得タイプの選択
| シナリオ | 推奨される取得タイプ | 説明 |
| 自然言語で質問する場合。 | DENSE_VECTOR + FULL_TEXT | ベクトル取得はセマンティクスを捉え、全文取得はキーワードの一致を保証します。 |
| 正確なキーワードまたは識別子を入力してください。 | FULL_TEXT を優先します。 | ベクトル取得は完全一致には敏感ではありません。 |
| 純粋なセマンティック理解のシナリオ。 | DENSE_VECTOR を優先します。 | 例えば、「インストール方法」は「デプロイメント手順」にマッチします。 |
メタデータフィルターの使用に関する推奨事項
フィルターは取得前に候補範囲を絞り込むため、検索精度とパフォーマンスの両方が向上します。
フィルターフィールドは、ナレッジベースの作成時にメタデータとして定義する必要があります。ランタイムで追加することはできません。
日付範囲のフィルタリングには、
string型ではなくdate型を使用して、範囲比較演算子をサポートするようにしてください。