# 更新知識版本

此 API 用於更新指定 Fileset 的檔案清單（`file_ids`）、Metadata 與名稱。  
你可以透過此操作，以傳入的內容**完全取代**原有 Fileset 的檔案清單、Metadata 與名稱（不是部分合併）。  
**Key Constraints：**

- 當 Fileset 狀態為 `queued`、`processing`、`completed` 時，僅能傳入與現有完全相同的 `file_ids` 集合（無法新增或移除檔案），否則回傳 `FILESET_004`（409）；但仍可更新 `metadata` 與 `name`。

- 當 Fileset 狀態為 `draft`、`failed`、`partial_failed`、`cancelled` 時，可完整替換 `file_ids`、`metadata`、`name`。

- 也就是說，已 commit 完成的 Fileset 並非完全不可變，只是不能更換所包含的檔案。如需變更檔案內容，請以「複製知識版本」API 建立複本，或建立新的 Fileset 後重新 Commit。

```bash
curl -X 'PUT' \
  'http://127.0.0.1:8000/v1/filesets/{fileset_id}' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $PRIVAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "file_ids": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "8871d153-e495-41a0-a862-289095802781"
    ],
    "metadata": {
      "tag": ["policy", "operation", "draft"]
    },
    "name": "Company Policy Files v2.0"
  }'
```

#### Request Headers

| Key | Value |
| --- | --- |
| Request Method | PUT |
| accept | application/json |
| Authorization | `Bearer $PRIVAI_API_KEY` |
| Content-Type | application/json |

#### Path Parameters

| Field | Type | Note | Required |
| --- | --- | --- | --- |
| fileset_id | string | uuid | true |

#### Request Payload

```json
{
  "file_ids": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "8871d153-e495-41a0-a862-289095802781"
  ],
  "metadata": {
    "tag": ["policy", "operation", "draft"]
  },
  "name": "Company Policy Files v2.0"
}
```

**Field Explanation**

| Field | Type | Detail | Required |
| --- | --- | --- | --- |
| file_ids | array | File ID（uuid）列表，會取代原有的檔案清單。狀態為 `queued`／`processing`／`completed` 時必須與現有集合相同 | true |
| metadata | object | 使用者自訂的描述資訊，會整個取代原有的 metadata。若要保留原有欄位，請先以「取得單一知識版本資料」API 取得後一併傳入 | true |
| name | string | Fileset 的名稱 | true |

#### Response Body

```json
{
  "object": "fileset",
  "id": "a1ecdb5d-e2a5-4aec-8925-b0648a5c0e21",
  "name": "Company Policy Files v2.0",
  "metadata": {
    "tag": ["policy", "operation", "draft"],
    "embedding_model": null,
    "parsing_mode": null
  },
  "state": "draft",
  "created_at": "2025-01-01T00:00:00.000Z",
  "committed_at": null,
  "updated_at": "2025-01-01T00:05:00.000Z",
  "file_counts": {
    "draft": 1,
    "queued": 0,
    "processing": 0,
    "completed": 0,
    "failed": 0,
    "total": 1
  }
}
```

**Field Explanation**  
回傳「[知識版本物件](https://privstation-docs.apmic.ai/latest/privai-400/知識版本物件.md)」章節列表內容。`metadata.embedding_model`、`metadata.parsing_mode` 為系統欄位，由系統依最近一次 commit 帶出。

#### 常見錯誤代碼

| Error Code | HTTP Status | 情境 |
| --- | --- | --- |
| FILESET_001 | 404 | 指定的 Fileset 不存在 |
| FILESET_004 | 409 | Fileset 狀態為 `queued`／`processing`／`completed`，且傳入的 `file_ids` 與現有集合不同；回應中帶 `state` |
| FILESET_007 | 409 | 同一個 Fileset 同時被其他請求修改（版本衝突），請重新取得後再試 |
| FILE_009 | 404 | `file_ids` 中有不存在的檔案，回應中的 `file_ids` 列出找不到的 ID |
| — | 422 | 缺少必填欄位，或 `metadata` 不是物件 |

身份驗證錯誤（`AUTH_001`～`AUTH_003`）詳見「錯誤代碼說明-身份驗證類」章節；知識版本相關錯誤碼完整說明請參考 [錯誤代碼說明-知識版本管理類](https://privstation-docs.apmic.ai/latest/privai-400/錯誤代碼說明-知識版本管理類.md)。
