上傳檔案

在 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
| Key | Value |
|---|---|
| Request Method | POST |
| accept | application/json |
| Authorization | Bearer $PRIVAI_API_KEY |
| Content-Type | multipart/form-data |
Query Parameters
| Field | Type | Note | Required |
|---|---|---|---|
| id | string | uuid,指定檔案 ID;若沒有指定則由系統自動產生。指定的 ID 已存在時回傳 FILE_003(409) | false |
| purpose | string | (與 OpenAI 相容而保留) | false |
Request Body(multipart/form-data)
| Field | Type | Note | Required |
|---|---|---|---|
| file | binary | 要上傳的檔案,支援格式見下方「支援的檔案格式」 | true |
| metadata | string | JSON 物件字串,使用者自訂的描述資訊,內容必須是 JSON 物件 | false |
| instant_parse | string | JSON 物件字串,指定上傳後立即觸發解析,格式同「單一檔案轉換」的 Request Payload,例如 {"parsing_mode":"HQ"}。parsing_mode 僅可為 HQ 或 FAST,亦可帶 webhook_url。未帶此欄位時不會解析,各解析品質的 parsing_state 維持 draft | false |
支援的檔案格式
系統依上傳檔案的 MIME type 判斷格式;若 multipart 中該檔案的 Content-Type 為 application/octet-stream,系統會改依副檔名推斷。建議如上方範例以 ;type= 明確指定 MIME type。
| 分類 | MIME Type |
|---|---|
application/pdf | |
| 圖片 | image/png、image/jpeg |
| Word | application/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) |
| CSV | text/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 Code | HTTP Status | 情境 |
|---|---|---|
| FILE_001 | 415 | 檔案格式不在支援清單中 |
| FILE_003 | 409 | 以 id 指定的檔案 ID 已存在 |
| — | 422 | metadata 不是 JSON 物件,或 instant_parse 格式錯誤(例如 parsing_mode 不是 HQ/FAST) |
身份驗證錯誤(AUTH_001~AUTH_003)詳見「錯誤代碼說明-身份驗證類」章節;檔案相關錯誤碼完整說明請參考 錯誤代碼說明-檔案管理類。