RAG 查詢（知識庫）

POST /v1/rag/query

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

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

查詢使用專案設定的 Embedding 模型，不允許在請求中覆寫。若需更換 Embedding 模型，請在 Dashboard 修改專案設定並等待文件重新處理完成。

請求

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

{
  "query": "Kubernetes pod CrashLoopBackOff 排除步驟",
  "top_k": 5,
  "min_similarity": 0.6,
  "rag_retrieval_strategy": "hybrid",
  "rag_rerank_enabled": true,
  "rag_rerank_strategy": "cross_encoder",
  "rag_query_expansion": false,
  "rerank_model_id": "baai/bge-reranker-v2-m3",
  "source_ids": ["019373a01a2b7c3d4e5f6a7b8c9d0e1f"]
}

請求欄位

欄位	類型	必填	說明
query	string	✓	查詢文字（1–10000 字元）
top_k	number		回傳的段落數（1–20），預設使用專案設定
min_similarity	number		最低相似度門檻，0.0–1.0，預設使用專案設定
rag_retrieval_strategy	string		檢索策略（見下方說明），預設使用專案設定
rag_rerank_enabled	boolean		是否啟用 Rerank，預設使用專案設定
rag_rerank_strategy	string		Rerank 策略：cross_encoder、llm_based，預設使用專案設定
rag_query_expansion	boolean		是否啟用查詢擴展，預設使用專案設定
rerank_model_id	string		指定 Rerank 模型 ID，預設使用專案設定
source_ids	string[]		限定搜尋範圍：只在這些文件 ID 中搜尋

檢索策略

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

回應

{
  "success": true,
  "code": 1000,
  "message": "Success",
  "data": {
    "query": "Kubernetes pod CrashLoopBackOff 排除步驟",
    "results": [
      {
        "content": "pod 出現 CrashLoopBackOff 時，先用 kubectl logs 查看容器日誌…",
        "similarity": 0.9234,
        "source": {
          "document_id": "019373a01a2b7c3d4e5f6a7b8c9d0e1f",
          "name": "ops-runbook.pdf",
          "mime_type": "application/pdf",
          "file_size": 102400
        }
      }
    ],
    "config": {
      "embedding_model_id": "openai/text-embedding-3-small",
      "rerank_model_id": "baai/bge-reranker-v2-m3",
      "top_k": 5,
      "min_similarity": 0.6,
      "retrieval_strategy": "hybrid",
      "rerank_enabled": true,
      "rerank_strategy": "cross_encoder",
      "query_expansion": false
    },
    "elapsed_time": {
      "total": 342,
      "expansion": 0,
      "retrieval": 198,
      "rerank": 128,
      "assembly": 16
    }
  }
}

回應欄位

欄位	類型	說明
query	string	原始查詢文字
results[].content	string	段落文字內容
results[].similarity	number	相似度分數（或 Rerank 後的分數），0.0–1.0
results[].source.document_id	string	來源文件 ID
results[].source.name	string	文件名稱
results[].source.mime_type	string	文件 MIME 類型
results[].source.file_size	number	文件大小（bytes）
config	object	此次查詢實際使用的 RAG 參數設定
elapsed_time.total	number	總耗時（ms）
elapsed_time.expansion	number	查詢擴展耗時（ms）
elapsed_time.retrieval	number	向量檢索耗時（ms）
elapsed_time.rerank	number	重排序耗時（ms）
elapsed_time.assembly	number	結果組裝耗時（ms）

錯誤碼

錯誤碼	HTTP	說明
1105	403	權限不足
1306	404	RAG 資料來源不存在
1006	409	文件正在建立索引，稍後再試
1603	500	向量搜尋失敗

所需權限

需要 query.search 權限。