跳至主要内容

Documents API

上傳文件​

POST /v1/documents​

使用 multipart/form-data 上傳文件。支援 PDF、DOCX、TXT、Markdown、HTML，檔案大小上限 50MB。

POST /v1/documents
Authorization: Bearer sk-your-api-key
Content-Type: multipart/form-data

Form Fields：

欄位類型必填說明
filefile✓文件二進位內容
chunk_strategystring切分策略：fixed、recursive、semantic、sentence、hierarchical、llm，預設 recursive
chunk_sizenumber每個段落最大字元數（100–4000）
chunk_overlapnumber相鄰段落重疊字元數（0–500）
chunk_model_idstringllm 策略使用的模型 ID
chunk_separatorsstring分隔符 JSON 陣列字串
chunk_min_sentencesnumbersentence 策略的最小句子數
chunk_max_sentencesnumbersentence 策略的最大句子數
chunk_semantic_thresholdnumbersemantic 策略的切分門檻（0.0–1.0）
chunk_parent_sizenumberhierarchical 策略的父區塊大小
chunk_child_sizenumberhierarchical 策略的子區塊大小
metadatastring自訂 metadata（JSON 字串）

回應：

{
  "success": true,
  "code": 1000,
  "message": "Success",
  "data": {
    "id": "0196abcd12347abc8def0123456789ab",
    "name": "product_manual.pdf",
    "source_type": "document",
    "mime_type": "application/pdf",
    "file_size": 1048576,
    "embedding_status": "pending",
    "chunk_count": 0,
    "is_active": true,
    "chunk_strategy": "recursive",
    "chunk_size": 500,
    "chunk_overlap": 50,
    "created_at": "2026-05-08T12:00:00Z"
  }
}

embedding_status 初始為 pending，EMW 處理後變為 processing → completed。

列出文件​

GET /v1/documents​

查詢參數：

參數類型說明
searchstring按文件名稱搜尋
statusstring篩選狀態：pending / processing / completed / failed
pagenumber頁碼，預設 1
page_sizenumber每頁筆數，預設 20

取得文件詳情​

GET /v1/documents/{doc_id}​

刪除文件​

DELETE /v1/documents/{doc_id}​

刪除後無法復原。向量資料、原始檔案、Markdown 轉換版本都會一起移除。

停用文件​

PATCH /v1/documents/{doc_id}/deactivate​

從 Qdrant 刪除向量，保留原始檔案。文件不再參與 RAG 搜尋。

啟用文件​

PATCH /v1/documents/{doc_id}/activate​

重新將文件排入 Embedding 佇列，建立新的處理任務。

更新切分設定​

PATCH /v1/documents/{doc_id}/chunking​

PATCH /v1/documents/019373a01a2b7c3d4e5f6a7b8c9d0e1f/chunking
Authorization: Bearer sk-your-api-key
Content-Type: multipart/form-data

Form 參數與上傳時的 chunk_* 欄位相同。僅更新設定，不會自動重新索引，需手動觸發 Reindex。

重新索引​

POST /v1/documents/{doc_id}/reindex​

刪除 Qdrant 中的舊向量後重新排入處理佇列。

限制：

  • 文件必須為啟用狀態（is_active = true）
  • 已在處理中的文件不可重複觸發

查看段落​

GET /v1/documents/{doc_id}/chunks​

查詢參數：

參數類型說明
pagenumber頁碼
page_sizenumber每頁筆數

回應：

{
  "success": true,
  "code": 1000,
  "message": "Success",
  "data": {
    "document": { "...文件基本資訊..." },
    "chunks": [
      {
        "chunk_id": "abc-123",
        "chunk_index": 0,
        "content": "第一章：產品概述...",
        "topics": ["產品", "功能"],
        "is_active": true,
        "created_at": "2026-05-08T12:05:00Z"
      }
    ],
    "stats": {
      "db_chunk_count": 5,
      "qdrant_chunk_count": 5,
      "is_consistent": true
    },
    "validated": true,
    "warnings": []
  }
}

下載原始檔案​

GET /v1/documents/{doc_id}/file​

回傳原始二進位檔案，支援 HTTP Range Headers 分段下載。

Response Headers：

  • Content-Type：原始文件 MIME type
  • Content-Length：檔案大小
  • Content-Disposition：attachment; filename="原檔名"
  • Accept-Ranges：bytes

Range 請求回傳 206 Partial Content。

下載 Markdown 版本​

GET /v1/documents/{doc_id}/file/md​

回傳文件解析後的 Markdown 文字。若原檔就是 Markdown 則直接回傳；否則回傳 EMW 轉換後的版本。EMW 尚未完成轉換前回傳 404。

錯誤碼​

錯誤碼HTTP說明
1310404文件不存在
1606400不支援的檔案格式
1605413文件大小超過 50MB
1405409文件已存在
1510400已達 RAG 文件數量上限
1504400儲存空間達到上限

所需權限​

操作所需權限
讀取文件列表、詳情、下載source.read
上傳、管理、刪除文件source.write