ナレッジの保存と検索チューニングのベストプラクティス - Tablestore

ナレッジベースの設計、ドキュメント管理、検索チューニングに関する実践的な推奨事項です。このガイドでは、一般的なエラーのクイックリファレンスと、不可逆的な操作のリストも紹介します。

ナレッジベースの設計

埋め込みモデルの選択

埋め込みモデルは、ベクトル検索のセマンティックな理解能力を決定します。これは、ナレッジベースを作成する上で最も重要な決定事項です。埋め込みモデルは後から変更できないためです。

シナリオ	推奨事項
一般的な中国語および英語のシナリオ	`text-embedding-v4` (1024 ディメンション) を推奨します。セマンティックな理解と検索パフォーマンスのバランスが取れています。
既存の自社モデル	`custom` モードを使用してモデルを統合し、一貫した技術スタックを維持します。
ディメンションの選択	ディメンションが高いほどセマンティックな表現は豊かになりますが、ストレージと計算コストも増加します。ほとんどのシナリオでは、1024 ディメンションを推奨します。

メタデータスキーマの設計

メタデータフィールドはナレッジベースの作成時に定義され、後から追加または削除することはできません。スキーマを設計する際は、以下の原則に従ってください。

事前の計画：カテゴリ、時間、作成者、バージョン、部署など、結果をフィルタリングするための潜在的なディメンションをすべて特定し、作成時に定義します。
正しいデータ型の選択：日付には (string ではなく) date 型を、数値には long または double を使用することで、greaterThanOrEquals のような演算子を使用した範囲フィルタリングが可能になります。
説明
date 型でサポートされている形式は次のとおりです：yyyy-MM-dd、yyyy-MM-dd HH:mm:ss、yyyy-MM-dd HH:mm:ss.SSS、yyyyMMdd HHmmss、yyyy-MM-dd'T'HH:mm:ss。
フィールド数の制限：サービスは最大 200 フィールドまでサポートしていますが、実際に必要なフィールドのみを定義することを推奨します。
合計サイズ制限の遵守：1つのドキュメントのすべてのメタデータキーと値の合計サイズは 4 KB を超えることはできません。メタデータに大きなテキストブロックを保存することは避けてください。

サブスペースの計画

シナリオ	ソリューション	理由
同種のデータを持つマルチテナント SaaS	サブスペース	共有の埋め込み設定により管理オーバーヘッドが削減され、テナント間の検索が可能になります。
異種のデータを持つ異なる事業部門	複数のナレッジベース	事業部門が異なると、異なる埋め込みモデルやメタデータスキーマが必要になる場合があります。
テナント数が非常に多い (10,000 以上)	サブスペース	過剰な数のナレッジベースを作成することは避けてください。サブスペースには数量制限がありません。

ドキュメント管理

ドキュメントの一括インポート

1 回の AddDocuments API 呼び出しには、最大 10 件のドキュメントを含めることができます。一括インポートには、以下を推奨します。

バッチでのアップロード：各バッチに 10 件のドキュメントを含め、AddDocuments API を連続して呼び出します。
同時実行の制御：レート制限を避けるため、QPS 制限内に収まるようにしてください。
非同期での待機：すべてのバッチをアップロードした後、各バッチの完了を待つのではなく、すべてのドキュメントのステータスを一度にポーリングします。
エラーの処理：各ドキュメントの status を個別に確認します。ステータスが failed のドキュメントについては、理由をログに記録し、問題を修正して再試行してください。

OSS ファイルの準備

ナレッジベースサービスが OSS バケットに対する読み取りおよび書き込み権限を持っていることを確認してください。手順については、「クイックスタート」ガイドの前提条件をご参照ください。
個々のファイルは 50 MB を超えてはなりません。
inclusionFilters と exclusionFilters を使用して、OSS ディレクトリからドキュメントを一括でインポートします。ワイルドカード (*) は、*.pdf や *report* のように、フィルターの先頭と末尾でサポートされています。

ドキュメントステータスのポーリング

ドキュメントをアップロードした後のステータスのポーリングは、システムが自動的にインデックスを作成するため、通常は不要です。インデックス作成が完了したことを確認する必要がある場合は、エクスポネンシャルバックオフ戦略を使用してください。

パラメーター	推奨値
初期間隔	3 秒
バックオフ係数	2 (毎回倍増：3 s → 6 s → 12 s → ...)
最大間隔	30 秒
終了条件	`status` が `Completed` または `failed` になった場合。

ドキュメントの処理時間は、ファイルのサイズ、種類、数量によって異なります。小さなファイルは通常数秒で処理されますが、大きなファイルや一括インポートには数分かかる場合があります。待機時間が不確実な場合、エクスポネンシャルバックオフ戦略は固定間隔よりも効率的です。短いタスクを迅速に完了させ、長時間実行されるタスクを頻繁にポーリングしてリソースを無駄にしません。

検索チューニング

検索タイプの選択

シナリオ	推奨タイプ	説明
自然言語での質問	`DENSE_VECTOR` と `FULL_TEXT` を使用したハイブリッド検索	ベクトル検索はセマンティックな意味を捉え、全文検索はキーワードのマッチを保証します。
正確なキーワードや識別子での検索	`FULL_TEXT` を優先	ベクトル検索は、完全一致には向いていません。
純粋なセマンティック検索のシナリオ	`DENSE_VECTOR` を優先	例えば、「how to install」のようなクエリを「deployment steps」というタイトルのドキュメントとマッチさせる場合などです。

再ランキング戦略の選択

戦略	利点	欠点	シナリオ
WEIGHT	各検索方法の貢献度をきめ細かく制御できます。	手動でのパラメーターチューニングが必要です。	特に、いずれかの検索方法を明確に優先したい場合に、デフォルトの選択肢として推奨されます。
RRF	追加のモデル呼び出しを回避するため、低レイテンシーで一貫したパフォーマンスが得られます。	クエリとドキュメントの相互作用情報を使用できません。	汎用的なシナリオ。
MODEL	最高のランキング品質。	レイテンシーと計算コストが増加します。	ランキング品質が最優先されるシナリオ。

`numberOfResults` のチューニング

検索パイプラインには、3 つの numberOfResults パラメーターが関与します。

N1 (denseVectorSearchConfiguration.numberOfResults)：ベクトル検索からの結果数。
N2 (fullTextSearchConfiguration.numberOfResults)：全文検索からの結果数。
N3 (rerankingConfiguration.numberOfResults)：再ランキング後の最終的な結果数。

N1 と N2 は候補プールのサイズを決定し、N3 は最終的な結果数を決定します。推奨される初期設定は、N1 = 20、N2 = 20、N3 = 5–10 です。

メタデータフィルターの使用

フィルターは検索前に候補プールを絞り込み、精度とパフォーマンスの両方を向上させます。
フィルタリングに使用するフィールドは、ナレッジベースの作成時にメタデータスキーマで定義する必要があります。
日付範囲のフィルタリングには、date 型を使用して範囲比較を有効にします。

一般的なエラー

エラーコード	説明	一般的な原因	解決策
`INVALID_PARAMETER`	パラメーターの検証に失敗しました	フィールドの型が不一致、長さを超過、または必須フィールドが欠落しています。	リクエストパラメーターが API 仕様に準拠しているか確認してください。
`NOT_FOUND`	リソースが見つかりません	ナレッジベース名に誤りがあるか、リソースが削除されています。	リソース名と ID が存在することを確認してください。
`BAD_REQUEST`	不正なリクエストです	無効な JSON 形式です。	リクエストボディの JSON 形式を確認してください。
`VALIDATION_ERROR`	ビジネス検証に失敗しました	`RRF` の `k` の値が 0 であるか、他の検索パラメーターが無効です。	パラメーター値が許容範囲内であることを確認してください。
HTTP 200 + `SUCCESS`、しかしドキュメントのステータスは `failed`	リクエストは成功しましたが、ドキュメントの処理に失敗しました。	メタデータの形式が一致しない (例：不正な日付形式)。	`documentDetails` 配列内の各項目の `status` を確認してください。

説明

AddDocuments、DeleteDocuments、および UpdateChunks のレスポンスでは、HTTP 200 ステータスと code: SUCCESS は、すべての項目が正常に処理されたことを保証するものではありません。各項目には独自の status フィールドがあるため、個別に確認する必要があります。

日付形式

メタデータの date 型は、以下の形式をサポートしています。

形式	例
`yyyy-MM-dd`	`2026-01-22`
`yyyy-MM-dd HH:mm:ss`	`2026-01-22 10:00:59`
`yyyy-MM-dd HH:mm:ss.SSS`	`2026-01-22 10:00:59.123`
`yyyyMMdd HHmmss`	`20260122 100059`
`yyyy-MM-dd'T'HH:mm:ss`	`2026-01-22T10:00:59`

サポートされていない日付形式を使用すると、AddDocuments API の実行中にドキュメントの status が failed に設定されます。

不可逆的な操作

以下の操作は元に戻すことができません。

操作	影響	回復方法
DeleteKnowledgeBase	ナレッジベースと、関連するすべてのドキュメントおよびチャンクデータを削除します。	回復不可
DeleteDocuments	指定されたドキュメントと、そのすべてのチャンクを削除します。	回復不可
embeddingConfiguration	作成後に変更することはできません。	ナレッジベースを削除して再作成してください。
メタデータスキーマ	フィールド定義は、作成後に追加または削除することはできません。	ナレッジベースを削除して再作成してください。
サブスペース設定	作成後に変更することはできません。	ナレッジベースを削除して再作成してください。
UpdateDocument メタデータ	この操作は、既存のすべてのメタデータ値を上書きします。	完全なメタデータオブジェクトを再送信してください。