跳至主要内容
版本:PrivStation 4.0.0
Markdown 原文

上傳檔案

在 PrivAI 中,所有上傳的檔案都會集中儲存在系統的 Storage 中,並透過唯一的檔案 ID 管理。這些檔案可以被組織成不同的 Fileset,作為 RAG 模型回答問題時的知識來源。
你可以:

  • 上傳 PDF、圖片、Word、純文字、Markdown、HTML、試算表、CSV 等格式的文件

  • 將多個檔案歸入一個 Fileset,形成主題式知識集合

  • 針對指定 Fileset 進行問答、查詢與語意檢索

這樣的設計讓你能靈活地重複利用同一份文件,並根據業務需求建立不同的知識範圍。

curl -X 'POST' \
'http://127.0.0.1:8000/v1/files?purpose=user_data' \
-H 'accept: application/json' \
-H "Authorization: Bearer $PRIVAI_API_KEY" \
-H 'Content-Type: multipart/form-data' \
-F 'file=@company_policy.pdf;type=application/pdf' \
-F 'metadata={"source":"internal_policy","language":"zh-Hant"}' \
-F 'instant_parse={"parsing_mode":"HQ"}'

Request Headers​

KeyValue
Request MethodPOST
acceptapplication/json
AuthorizationBearer $PRIVAI_API_KEY
Content-Typemultipart/form-data

Query Parameters​

FieldTypeNoteRequired
idstringuuid,指定檔案 ID;若沒有指定則由系統自動產生。指定的 ID 已存在時回傳 FILE_003(409)false
purposestring(與 OpenAI 相容而保留)false

Request Body(multipart/form-data)​

FieldTypeNoteRequired
filebinary要上傳的檔案,支援格式見下方「支援的檔案格式」true
metadatastringJSON 物件字串,使用者自訂的描述資訊,內容必須是 JSON 物件false
instant_parsestringJSON 物件字串,指定上傳後立即觸發解析,格式同「單一檔案轉換」的 Request Payload,例如 {"parsing_mode":"HQ"}。parsing_mode 僅可為 HQ 或 FAST,亦可帶 webhook_url。未帶此欄位時不會解析,各解析品質的 parsing_state 維持 draftfalse

支援的檔案格式​

系統依上傳檔案的 MIME type 判斷格式;若 multipart 中該檔案的 Content-Type 為 application/octet-stream,系統會改依副檔名推斷。建議如上方範例以 ;type= 明確指定 MIME type。

分類MIME Type
PDFapplication/pdf
圖片image/png、image/jpeg
Wordapplication/msword(.doc)、application/vnd.openxmlformats-officedocument.wordprocessingml.document(.docx)
純文字text/html、text/plain、text/markdown
試算表application/vnd.openxmlformats-officedocument.spreadsheetml.sheet(.xlsx)、application/vnd.ms-excel(.xls)、application/vnd.oasis.opendocument.spreadsheet(.ods)、application/vnd.ms-excel.sheet.binary.macroenabled.12(.xlsb)
CSVtext/csv

若上傳非以上類型,回傳 FILE_001 Unsupported media type(415)。其他限制詳見「PrivAI 使用限制」章節。

自動識別 QA 題庫檔​

若上傳的檔案為 .xlsx(application/vnd.openxmlformats-officedocument.spreadsheetml.sheet),且第一個工作表的標題列第一欄為 question、第二欄為 answer,系統會自動將其識別為 QA 題庫檔,filetype 會記為內部型別 application/x-privai-qa,後續依 QA 題庫檔的方式進行切割與索引。此行為為自動判斷、無法手動關閉。

  • 只有 .xlsx 會進行此判斷,.xls、.ods、.xlsb 不會。

  • 欄名需完全相符(小寫 question、answer),且必須位於 A、B 兩欄。

  • 下載此類檔案的原始檔時,Content-Type 會還原為標準 .xlsx(詳見「下載檔案」章節)。

Response Body​

{
"object": "file",
"id": "ce7f0171-8993-4e5d-961d-fad6b93400c3",
"filename": "company_policy.pdf",
"filetype": "application/pdf",
"bytes": 582328,
"metadata": {
"parsed_results": {
"HQ": {
"parsing_state": "draft"
},
"LQ": {
"parsing_state": "draft"
}
},
"fail_detail": [],
"source": "internal_policy",
"language": "zh-Hant"
},
"purpose": "user_data",
"created_at": "2025-12-03T06:41:10.144174Z",
"expires_at": null
}

Field Explanation
回傳「檔案物件」章節列表內容。HTTP Status 為 200。

  • 回應內容為檔案建立當下的狀態。即使帶了 instant_parse,回應中的 parsing_state 仍可能顯示 draft;請改用「取得單一檔案資料」API 查詢最新解析狀態,或在 instant_parse 中帶 webhook_url 接收解析結果。

  • PDF/圖片的 parsed_results 會有 HQ 與 LQ 兩組;其餘格式只有一組 STD。

  • 使用者自訂的 metadata 會與系統欄位(parsed_results、fail_detail)合併回傳。

常見錯誤代碼​

Error CodeHTTP Status情境
FILE_001415檔案格式不在支援清單中
FILE_003409以 id 指定的檔案 ID 已存在
—422metadata 不是 JSON 物件,或 instant_parse 格式錯誤(例如 parsing_mode 不是 HQ/FAST)

身份驗證錯誤(AUTH_001~AUTH_003)詳見「錯誤代碼說明-身份驗證類」章節;檔案相關錯誤碼完整說明請參考 錯誤代碼說明-檔案管理類。