# PrivAI 使用限制

本章說明 PrivAI 4.0.0 API 目前的使用限制。

### 1. 檔案上傳

#### 1.1 支援的檔案格式

系統依上傳時 multipart 欄位的 `Content-Type`（MIME 類型）判斷檔案格式；若 `Content-Type` 為 `application/octet-stream`，才會改以副檔名推斷。不在下表中的格式會被拒絕（`FILE_001`，HTTP 415）。

| 類別 | 副檔名 | MIME 類型 |
| --- | --- | --- |
| PDF | `.pdf` | `application/pdf` |
| 圖片 | `.png`、`.jpg` ／ `.jpeg` | `image/png`、`image/jpeg` |
| Word 文件 | `.doc`、`.docx` | `application/msword`、`application/vnd.openxmlformats-officedocument.wordprocessingml.document` |
| 文字 ／ 網頁 | `.txt`、`.md`、`.html` | `text/plain`、`text/markdown`、`text/html` |
| 試算表 | `.xlsx`、`.xls`、`.ods`、`.xlsb` | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`、`application/vnd.ms-excel`、`application/vnd.oasis.opendocument.spreadsheet`、`application/vnd.ms-excel.sheet.binary.macroenabled.12` |
| CSV | `.csv` | `text/csv` |

**補充說明：**

- 上傳時請帶入正確的 `Content-Type`。

- `.xlsx` 檔案若第一欄標題為 `question`、第二欄標題為 `answer`，系統會將其視為問答集檔案，`filetype` 會記錄為 `application/x-privai-qa`。

- 部署環境（例如前端反向代理）可能另有單一請求的大小限制，請洽系統管理員確認。

#### 1.2 掃描檔與圖片辨識

系統會自動辨識 PDF 與圖片中的文字。請注意：

- 影像品質、傾斜、手寫字跡與複雜表格會影響辨識準確度。

- 頁數較多的文件辨識時間較長。解析為非同步作業，可透過「取得單一檔案資料」API 查詢進度。

- 解析作業逾時即中止；逾時的檔案可重新呼叫「單一檔案轉換」API 發起解析。

解析模式與自動切換機制詳見「分頁策略 ＆ 文件解析模式優化策略 (PDF)」章節。

### 2. 知識版本 Commit

- Commit 處理逾時的 Fileset 會被標示為 `failed`，之後可重新 Commit。

- 只有狀態為 `completed` 或 `partial_failed` 的知識版本可用於資料參考搜尋與 Chat Completions；其他狀態會回傳 HTTP 409。

### 3. 問答集生成

- 單一檔案可送入問答集生成的內容有長度上限，超過上限時的處理方式由 `on_oversize` 參數決定：

    - `fail`：直接回傳錯誤 `QA_003`。

    - `split`：系統自動將內容切成多段分別生成，再合併結果。

- `target_amount`（每 500 字預計生成的問答數）可設定範圍為 1–3。

詳見「問答集生成」章節。

### 4. 對話（Chat Completions）

- **對話歷史範圍**：每次請求中，系統只會採用本次提問之前最近的部分 user ／ assistant 訊息作為對話歷史與摘要的依據。較早的內容不會納入，若有需要請於新訊息中重述關鍵資訊。

- **訊息順序**：`messages`（不含 `system`）必須以 `user` 開始，`user` 與 `assistant` 交替出現，並以 `user` 結尾，否則回傳 `VAL_004`。

- **工具類型**：`tools` 僅支援 MCP 類型（連線外部 MCP server）。

詳見「Chat Completions」與「Tool Calling 與 MCP 整合」章節。

### 5. 報告生成（Beta）

- 報告生成為長時間的非同步作業，所需時間依章節數量與資料量而定。

- 單一章節生成失敗時，系統會自動重試；仍失敗時，該章節內容會標示為「本章生成失敗」，其餘章節照常產出。

- 若所有章節皆生成失敗，或章節整合重試後仍失敗，該份報告會標示為 `failed`，可重新發起生成。

- 模板填充失敗時，系統會自動重試。

- 報告模板解析所產生的 HTML 中引用的圖片連結，有效期為 **48 小時**。

- 匯出的 PDF 會以檔案物件形式儲存，可透過「下載檔案」API 取得。

詳見「報告生成」章節。

### 6. API 查詢

- 列表類 API 單次最多回傳 **10,000** 筆資料（`limit` 範圍 1–10000，預設 10000）。資料量較大時請使用分頁參數逐批取得，詳見「分頁策略 ＆ 文件解析模式優化策略 (PDF)」章節。
