RAG 查詢（知識庫）

POST /v1/rag/query

直接查詢專案知識庫，回傳最相關的段落，不經過 LLM 生成。

適合自己控制 Prompt 組合，或只需要語義搜尋結果的場景。

請求

POST /v1/rag/query
Authorization: Bearer sk-your-api-key
Content-Type: application/json

{
  "query": "退款申請需要哪些文件？",
  "top_k": 5,
  "min_similarity": 0.6,
  "rag_retrieval_strategy": "hybrid",
  "rag_rerank_enabled": true,
  "source_ids": ["doc-id-1", "doc-id-2"]
}

請求欄位

欄位	類型	必填	說明
query	string	✓	查詢文字
top_k	number		回傳的段落數，預設 5
min_similarity	number		最低相似度門檻，0.0 – 1.0，預設 0.0
rag_retrieval_strategy	string		檢索策略（見下方說明）
rag_rerank_enabled	boolean		是否對結果進行 Rerank，預設 false
source_ids	string[]		限定搜尋範圍：只在這些文件 ID 中搜尋

檢索策略

策略	說明
dense	純向量（語義）搜尋，預設
sparse	BM25 關鍵字搜尋
hybrid	結合向量和關鍵字搜尋，通常最準確

回應

{
  "success": true,
  "code": 0,
  "message": "OK",
  "data": {
    "results": [
      {
        "document_id": "doc-id-1",
        "chunk_id": "chunk-uuid",
        "title": "退款政策.pdf",
        "content": "申請退款需提交購買憑證和身份證明文件...",
        "score": 0.9234,
        "metadata": {
          "page": 3,
          "section": "退款流程"
        }
      }
    ],
    "query": "退款申請需要哪些文件？",
    "total": 1
  }
}

回應欄位

欄位	類型	說明
results[].document_id	string	來源文件 ID
results[].chunk_id	string	段落 ID
results[].title	string	文件名稱
results[].content	string	段落文字內容
results[].score	number	相似度分數（或 Rerank 後的分數）
results[].metadata	object	段落的自訂 metadata
total	number	符合條件的總段落數

注意

• 查詢前必須先上傳文件並等待狀態變為 ready
• 需要 source.read 權限