PrivAI 使用限制
本章說明 PrivAI 4.0.0 API 目前的使用限制。
1. 檔案上傳
1.1 支援的檔案格式
系統依上傳時 multipart 欄位的 Content-Type(MIME 類型)判斷檔案格式;若 Content-Type 為 application/octet-stream,才會改以副檔名推斷。不在下表中的格式會被拒絕(FILE_001,HTTP 415)。
| 類別 | 副檔名 | MIME 類型 |
|---|---|---|
.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)」章節。