すべてのプロダクト
Search
ドキュメントセンター

Tablestore:取得とランキング

最終更新日:Oct 22, 2026

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 つの取得パスの貢献度を詳細に制御する必要がある場合に使用します。デフォルトの選択肢として推奨されます。

パラメータータイプデフォルト値説明
denseVectorSearchWeightdouble0.7ベクトル取得の重み。
fullTextSearchWeightdouble0.3全文取得の重み。

RRF (reciprocal rank fusion)

複数の取得パスからの結果を、それぞれのランクの逆数で重み付けして融合します。RRF は追加のモデル呼び出しを必要とせず、低レイテンシーで安定した結果を提供します。

パラメータータイプデフォルト値説明
denseVectorSearchWeightdouble1.0ベクトル取得の重み。
fullTextSearchWeightdouble1.0全文取得の重み。
kint60RRF アルゴリズムのパラメーター。0 より大きい必要があります。

次の例のように RRF を設定します:

{
  "rerankingConfiguration": {
    "type": "RRF",
    "numberOfResults": 5,
    "rrfConfiguration": {
      "denseVectorSearchWeight": 0.6,
      "fullTextSearchWeight": 0.4,
      "k": 20
    }
  }
}

MODEL (モデル再ランキング)

gte-rerank-v2 などの再ランキングモデルを呼び出して、候補結果を再ランキングします。この戦略は最高のランキング品質を提供しますが、レイテンシーと計算コストが増加します。

パラメータータイプデフォルト値説明
providerstringbailian再ランキングモデルのプロバイダー。現在、Bailian のみがサポートされています。
modelstringgte-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}}
    ]
  }
}

取得の実行

  • 取得テキスト text には、最大 128 文字を含めることができます。この制限を超えたリクエストはエラーを返します。

    ビジネス要件がある場合は、チケットを送信するか、Tablestore 技術交流グループ 36165029092 に参加してテクニカルサポートにご連絡ください。
  • フィルターフィールドは、ナレッジベースの作成時にメタデータとして定義する必要があります。そうしないと、フィルター条件は有効になりません。

  • 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 型を使用して、範囲比較演算子をサポートするようにしてください。