檔案物件
| Field | Detail |
|---|---|
| object | 物件類型,固定為 file |
| id | 檔案的唯一鍵,UUID |
| filename | 原始檔案名稱 |
| filetype | 檔案種類(MIME type),包含 application/pdf、image/png、image/jpeg、application/msword、application/vnd.openxmlformats-officedocument.wordprocessingml.document、text/html、text/plain、text/markdown、application/vnd.openxmlformats-officedocument.spreadsheetml.sheet、application/vnd.ms-excel、application/vnd.oasis.opendocument.spreadsheet、application/vnd.ms-excel.sheet.binary.macroenabled.12、text/csv,以及 QA 題庫檔的內部型別 application/x-privai-qa |
| bytes | 檔案大小(bytes) |
| metadata | 儲存與檔案相關的額外資訊,包含系統欄位 parsed_results、fail_detail,以及上傳時使用者自訂的欄位 |
metadata.parsed_results | 檔案在不同解析品質下的結果。PDF/圖片類檔案會有 HQ 與 LQ 兩組結果;其餘檔案類型(Word、HTML、純文字、Markdown、試算表、CSV、QA 題庫檔)僅有單一 STD 結果。FAST 是觸發解析時 parsing_mode 參數的值,不會出現在 parsed_results 的 key 中 |
metadata.parsed_results.[mode].parsing_state | 該解析品質下的轉換狀態,包含 draft、queued、parsing、completed、failed。其中 [mode] 為 HQ、LQ 或 STD |
metadata.parsed_results.[mode].character_count | 該解析品質下抽取出的字元數量 |
metadata.parsed_results.[mode].page_count | 該解析品質下解析到的總頁數(僅 HQ/LQ) |
metadata.parsed_results.[mode].failed_page_numbers | 該解析品質下解析失敗的頁碼列表(僅 HQ/LQ) |
metadata.fail_detail | 檔案解析失敗的錯誤歷史(陣列,最新的在最前面)。每筆包含 timestamp、error_type、error_message,並可能包含 reason、step、extra |
| purpose | (與 OpenAI 相容而保留) |
| created_at | 檔案上傳、建立的時間 |
| expires_at | (與 OpenAI 相容而保留) |
補充說明:
-
File 物件本身不使用單一
state欄位表示整體狀態。若需判斷檔案解析進度,請查看metadata.parsed_results中各解析品質對應的parsing_state。 -
同一個檔案可能在不同解析品質下有不同結果,應分別查看各品質狀態,而非以單一欄位統一表示。
-
parsing_state為draft時,該解析品質只會回傳parsing_state,不含character_count等欄位。 -
GET /v1/files與GET /v1/files/{file_id}會省略值為 null 的欄位,因此這兩個 API 的回應中不會出現expires_at。 -
used_quality不會出現在GET /v1/files或GET /v1/files/{file_id}的 File 物件中。該欄位僅會出現在 Fileset File 物件(見 取得單一知識版本的檔案列表),用來表示檔案在特定 Fileset commit 流程中實際採用的解析品質。