# 上傳檔案

![](https://privstation-docs.apmic.ai/img/notion/334e2f87a4f2.png)

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

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

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

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

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

```bash
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 |
| --- | --- |
| PDF | `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

```json
{
  "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**  
回傳「[檔案物件](https://privstation-docs.apmic.ai/latest/privai-400/檔案物件.md)」章節列表內容。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`）詳見「錯誤代碼說明-身份驗證類」章節；檔案相關錯誤碼完整說明請參考 [錯誤代碼說明-檔案管理類](https://privstation-docs.apmic.ai/latest/privai-400/錯誤代碼說明-檔案管理類.md)。
