このチュートリアルでは、AgentStorage Python SDK を使用して最初のナレッジベースを構築します。AgentStorage は Tablestore のナレッジストレージサービスです。ローカルドキュメントのアップロードから非同期インデックス作成、検索までの最小限のエンドツーエンドワークフローを完了します。
前提条件
AgentStorage インスタンスを作成し、そのインスタンス名とエンドポイントを取得していること。ナレッジベースはこのインスタンスに作成されます。
AgentStorage インスタンスと同じリージョンに Object Storage Service (OSS) バケットを作成し、Tablestore に OSS への読み取りおよび書き込み権限を付与していること。
AccessKey ID と AccessKey Secret を所有していること。本番環境では、RAM ユーザーまたは一時的な認証情報を使用してください。
テスト用のローカル PDF、Word、Markdown、またはテキストファイルを用意していること。
ステップ 1:SDK のインストール
次のコマンドを実行して、AgentStorage Python SDK をインストールします。
pip install tablestore-agent-storageステップ 2:クライアントの作成
前提条件の AccessKey ペア、インスタンス、およびバケット情報を使用して AgentStorageClient を作成します。ステップ 2 から 5 の Python スニペットは 1 つのスクリプトを形成します。 これらを同じファイルに追加するか、同じセッションで実行して、client や doc_id などの共有変数が定義された状態を維持します。
from tablestore_agent_storage import AgentStorageClient
import time
client = AgentStorageClient(
access_key_id="<AccessKey ID>",
access_key_secret="<AccessKey Secret>",
ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
ots_instance_name="<instance-name>",
oss_endpoint="https://oss-<region>.aliyuncs.com",
oss_bucket_name="<bucket-name>",
)プレースホルダーを実際の値に置き換えます。 ots_endpoint の <instance> サブドメインと ots_instance_name の <instance-name> の値は、同じインスタンス名です。 OSS バケットがインスタンスと同じリージョンにあるため、2 つの <region> プレースホルダーは同じ値を取ります。
ステップ 3:ナレッジベースの作成とドキュメントのアップロード
このステップでは、2つの呼び出しが行われます。create_knowledge_base はナレッジベースを作成し、upload_documents はローカルドキュメントをナレッジベースにインポートします。
まず、product_docs_kb という名前のナレッジベースを作成します:
client.create_knowledge_base({
"knowledgeBaseName": "product_docs_kb",
"description": "Product documentation knowledge base",
})次に、ローカルドキュメントをアップロードし、ステップ 4 でインデックス作成の進行状況を追跡するために使用するドキュメント ID を保存します。
response = client.upload_documents({
"knowledgeBaseName": "product_docs_kb",
"documents": [{"filePath": "/path/to/product-guide.pdf"}],
})
doc_id = response["data"]["documentDetails"][0]["docId"]SDK は、まずローカルファイルを OSS にアップロードし、次に非同期インポートタスクを送信します。ナレッジベースの作成時に検索設定が指定されていないため、サービスはデフォルト設定を使用します。
ステップ 4:ドキュメントが検索可能になるまで待機
インポートタスクは非同期で実行されます。ドキュメントのステータスが pending または indexing の間は、ドキュメントを取得できません。次のコードを使用して 5 秒ごとにドキュメントのステータスをポーリングします。ステータスが completed に変わるまで、次のステップに進まないでください:
deadline = time.time() + 300
while time.time() < deadline:
response = client.get_document({
"knowledgeBaseName": "product_docs_kb",
"docId": doc_id,
})
document = response["data"][0]
status = document["status"]
if status == "completed":
break
if status == "failed":
raise RuntimeError(document.get("message", "Document processing failed"))
time.sleep(5)
else:
raise TimeoutError("Timed out waiting for document indexing")本番環境では、バックオフを使用してポーリングし、全体的なタイムアウトを設定し、failed ステータスを処理します。
ステップ 5:検索の実行
ドキュメントが検索可能になったら、テキスト質問に関連するコンテンツをナレッジベースに問い合わせます。
response = client.retrieve({
"knowledgeBaseName": "product_docs_kb",
"retrievalQuery": {
"type": "TEXT",
"text": "What are the installation steps for the product?",
},
})
for item in response["data"]["retrievalResults"]:
print(f"[{item['score']:.4f}] {item['content'][:120]}")成功すると、スクリプトは取得されたチャンクごとに、角括弧で囲まれた関連性スコアと、それに続くチャンクコンテンツの最初の 120 文字を 1 行で出力します。ドキュメントのステータスが completed で、検索クエリによってドキュメントからスコア付けされたチャンクが返される場合、ナレッジベースはインデックス化され、検索可能になります。これらのステップにより、生のドキュメントからチャンクのインデックス化、関連コンテンツの検索に至るまでの AgentStorage ワークフローが完了します。取得された結果は、検索拡張生成 (RAG) アプリケーションのためのエビデンスチャンクであり、モデルによって生成された最終的な回答ではありません。
次のステップ
ナレッジストレージサービスの詳細については、「ナレッジストレージサービス」をご参照ください。
OSS ファイルまたはディレクトリのインポートについては、「ドキュメント管理」をご参照ください。
ハイブリッド検索と再ランキングの調整については、「検索とランキング」をご参照ください。
TypeScript、コマンドラインインターフェイス (CLI) の使用については、「Agent Storage SDK」、「コマンドラインツール」をご参照ください。