# 上傳檔案

PrivAI 的檔案是集中式的管理，所有的檔案都會建立在 Storage 內，並透過唯一鍵取得。並可以透過將檔案們匯入資料集，並針對這些資料內容進行問答。

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

你可以：

- 上傳 PDF、Word、TXT 等格式的文件

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

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

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

```javascript
curl -X 'POST' \
  'http://127.0.0.1:8000/v1/files?purpose=user_data&id={id}' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <your-api-key>' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@Atomic Habits: An Easy & Proven Way to Build Good Habits & Break Bad Ones.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 &lt;your-api-key> |
| Content-Type | multipart/form-data |

#### Query Parameters

| **Field** | **Type** | **Note** | **Required** |
| --- | --- | --- | --- |
| id | string | uuid，指定 ID，若沒有指定則由系統自動產生 | false |
| purpose | string | (與 OpenAI 相容而保留) | false |

#### Request Body

| **Field** | **Type** | **Note** | **Required** |
| --- | --- | --- | --- |
| file | binary | .pdf, .doc, .docx, .txt, .html | true |
| metadata | string | object，使用者自訂的描述資訊 | false |
| instant_parse | string | object，是否立即轉換檔案，並指定轉換模式。

若指定 parse，系統會更新對應 parsing mode 的 parsed_results.&lt;mode>.parsing_state。

未啟動解析時，預設為 draft。 | false |

#### Response Body

```javascript
{
  "object": "file",
  "id": "ce7f0171-8993-4e5d-961d-fad6b93400c3",
  "filename": "勞動基準法 版本_113071500.pdf",
  "filetype": "application/pdf",
  "bytes": 582328,
  "metadata": {
    "parsed_results": {
      "HQ": {
        "parsing_state": "draft"
      },
      "LQ": {
        "parsing_state": "draft"
      }
    },
    "fail_detail": []
  },
  "purpose": "user_data",
  "created_at": "2025-12-03T06:41:10.144174Z",
  "expires_at": null
}
```

**Field Explanation**

回傳「檔案物件」章節列表內容。
