知識儲存服務快速入門,4行代碼跑通RAG檢索 - Tablestore

得益於完善的預設策略設計，最簡情境下只需4 行核心代碼即可完成從建立知識庫到語義檢索的全過程，無需部署任何伺服器。

前置準備

已開通Table Store服務。
說明
當前知識儲存服務支援的地區：華北2（北京）、華東2（上海）、華東1（杭州）、華南1（深圳）、中國香港、新加坡。
已完成 OSS 授權。知識庫需要讀寫 OSS Bucket 的許可權，通過以下連結一鍵授權：授權Table Store讀寫 OSS。
已安裝 Python SDK：
```
pip install tablestore-agent-storage
```

初始化用戶端

將以下代碼中的 AccessKey、Tablestore Endpoint、Tablestore 執行個體名稱、OSS Endpoint 和 Bucket 名稱替換為實際值。

說明

OSS Bucket和Tablestore執行個體必須在同一地區。

from tablestore_agent_storage import AgentStorageClient

client = AgentStorageClient(
    access_key_id="<your-access-key-id>",
    access_key_secret="<your-access-key-secret>",
    ots_endpoint="https://<instance-name>.<region-id>.ots.aliyuncs.com",
    ots_instance_name="<your-instance-name>",
    oss_endpoint="https://oss-<region-id>.aliyuncs.com",
    oss_bucket_name="<your-bucket-name>"
)

4 行代碼跑通 RAG 檢索

使用預設配置時，核心邏輯只需要少量代碼即可完成。

# 1. 建立知識庫
client.create_knowledge_base({"knowledgeBaseName": "product_docs_kb"})

# 2. 上傳文檔
resp = client.upload_documents({"knowledgeBaseName": "product_docs_kb", "documents": [{"filePath": "/path/to/file.pdf"}]})

# 3. 等待索引完成
import time
doc_id = resp["data"]["documentDetails"][0]["docId"]
while True:
    data = client.get_document({"knowledgeBaseName": "product_docs_kb", "docId": doc_id}).get("data") or []
    if data and data[0]["status"] == "completed":
        break
    time.sleep(5)

# 4. 檢索
results = client.retrieve({"knowledgeBaseName": "product_docs_kb", "retrievalQuery": {"type": "TEXT", "text": "你的問題"}})

說明

上述代碼僅展示核心邏輯。文檔索引為非同步過程，處理時間受文檔大小、類型等因素影響，可能從數秒到分鐘層級不等。實際業務中文檔匯入和檢索通常是獨立流程，無需等待索引完成。完整可運行樣本請參考文件管理。

分步驟端到端樣本

步驟一：建立知識庫

不傳配置時，Embedding 預設使用百鍊 text-embedding-v4（1024 維），檢索預設使用向量 + 全文混合檢索。更多配置選項參見知識庫管理員。

client.create_knowledge_base({"knowledgeBaseName": "product_docs_kb"})

步驟二：上傳文檔

SDK 自動將本地檔案上傳至 OSS 並添加到知識庫。更多上傳方式參見文件管理。

resp = client.upload_documents({
    "knowledgeBaseName": "product_docs_kb",
    "documents": [{"filePath": "/path/to/file.pdf"}]
})
doc_id = resp["data"]["documentDetails"][0]["docId"]

文檔上傳後，系統需要一定時間完成解析、切片和向量化。處理時間取決於文檔大小和數量，通常在幾秒到幾分鐘之間。文檔狀態變為 Completed 後才能被檢索到，可通過 get_document 介面查詢狀態。詳細的狀態流轉和輪詢方法參見查詢文檔狀態。

步驟三：檢索

文檔索引完成後，調用 Retrieve 介面執行語義檢索。檢索結果按相關性得分降序排列，每個結果包含切片原文和中繼資料，可直接作為 LLM 的上下文輸入。檢索策略配置參見檢索和排序。

results = client.retrieve({
    "knowledgeBaseName": "product_docs_kb",
    "retrievalQuery": {"type": "TEXT", "text": "產品的安裝步驟是什麼"}
})
for r in results["data"]["retrievalResults"]:
    print(f"[{r['score']:.4f}] {r['content'][:80]}...")

步驟四：清理資源（可選）

重要

刪除知識庫會同時刪除其下所有文檔和切片資料，此操作無法復原。

client.delete_knowledge_base({"knowledgeBaseName": "product_docs_kb"})