# 問答集生成

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

此 API 用於根據指定的 Fileset，自動生成問答集（QA Pairs），並輸出為標準格式的 QA 檔案，供後續人工校對、prompt 測試，或加入 Fileset 作為知識來源使用。  
系統會依序處理 Fileset 中的每個檔案：

- 取得檔案的解析內容（尚未解析的檔案會先以 `HQ` 模式解析，因此 Fileset 不需要先 commit）

- 由 LLM 從內容中擷取可能的問題點（如定義、規則、流程），生成問題與參考答案

- 將所有檔案的結果彙整為一份 `.xlsx` QA 檔案，儲存為一筆 File 並回傳該檔案資訊

Fileset 中原本就是 QA 題庫檔（`application/x-privai-qa`）的檔案會被略過。此 API 為同步處理，會等所有檔案生成完畢才回應，檔案較多或較大時需要較長時間。

```bash
curl -X 'POST' \
  'http://127.0.0.1:8000/v1/qa/generate?fileset_id={fileset_id}' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $PRIVAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "temperature": 0.7,
    "target_amount": 1,
    "on_oversize": "fail"
  }'
```

#### Request Headers

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

#### Query Parameters

| Field | Type | Note | Required |
| --- | --- | --- | --- |
| fileset_id | string | uuid，來源 Fileset | true |

#### Request Payload

```json
{
  "model_name": "ace-1-24b-reasoning-v1",
  "extract_model_name": "ace-1-24b-reasoning-v1",
  "temperature": 0.7,
  "target_amount": 1,
  "on_oversize": "fail"
}
```

**Field Explanation**

| Field | Type | Detail | Required |
| --- | --- | --- | --- |
| model_name | string | 用來產生問答集的 LLM 模型，省略時使用系統預設模型。可用模型可由「取得所有模型」API 查詢 | false |
| extract_model_name | string | 用來將生成結果整理為結構化問答的模型，僅支援非 thinking 模型；省略時使用系統預設模型 | false |
| temperature | float | 控制生成文字的隨機性，範圍 0.0–1.0 | false |
| target_amount | integer | 可用值 1、2、3。每次呼叫模型時要求「至少」產生的 QA 數量；內容足夠時模型可能產生更多 | false |
| on_oversize | string | 單一檔案內容過長時的處理方式，可用值 `fail`、`split`。詳見下方說明 | false |

**on_oversize 說明**  
單一檔案的解析文字過長時：

- `fail`：回傳 `QA_003`（400），**整個請求中止**，其他檔案即使已處理成功也不會產生 QA 檔案。

- `split`：將內容切成多段（段落間有重疊）分別生成後合併，`target_amount` 會套用到每一段。

#### Response Body

**Status Code：201 Created**（所有檔案皆成功時）

```json
{
  "object": "file",
  "id": "792b40a2-8128-4a08-b5fc-517f040108fc",
  "filename": "QA_b9f375f8-048f-4d5a-a3ec-63b7f062f074.xlsx",
  "filetype": "application/x-privai-qa",
  "bytes": 4925,
  "metadata": {
    "source_fileset_id": "b9f375f8-048f-4d5a-a3ec-63b7f062f074"
  },
  "purpose": "user_data",
  "created_at": "2025-01-01T01:20:00.000Z",
  "expires_at": null,
  "failed_file_ids": [],
  "error_message": null
}
```

**Field Explanation**

| Field | Type | Description |
| --- | --- | --- |
| object | string | 固定為 `file` |
| id | string (uuid) | 產生的 QA 檔案 ID |
| filename | string | 檔名，格式 `QA_{fileset_id}.xlsx` |
| filetype | string | 固定為 `application/x-privai-qa` |
| bytes | integer | 檔案大小（bytes） |
| metadata | object | 含 `source_fileset_id`（來源 Fileset ID） |
| purpose | string | (與 OpenAI 相容而保留)，固定為 `user_data` |
| created_at | timestamp | 建立時間 |
| expires_at | timestamp \| null | (與 OpenAI 相容而保留) |
| failed_file_ids | array \| null | 生成失敗的來源檔案 ID 列表 |
| error_message | string \| null | 有檔案失敗時的說明文字，無失敗時為 null |

:::warning[⚠️]

**部分檔案失敗時，HTTP 狀態碼為 400，但 Response Body 仍是上方的成功格式**。此時 QA 檔案已成功建立（`id` 可用），只是不含失敗檔案的內容；`failed_file_ids` 列出失敗的來源檔案，`error_message` 為 `Some files failed to generate QA pairs. Please refer to the API documentation.`。請以 `failed_file_ids`／`error_message` 判斷是否有部分失敗，不要只依狀態碼判斷整體成敗，以免遺漏已產生的 QA 檔案。

:::

#### QA 檔案格式

產生的 QA 檔案是一般的 File，可透過「下載檔案」API（`file_type=raw_file`）下載為 `.xlsx`，也可以加入 Fileset 後 Commit，作為知識來源使用。檔案第一列為標題 `question`、`answer`，每列一組問答：

| question | answer |
| --- | --- |
| Customer's name? | Mr Bean |
| Booking Number | B32VO3 |

問答內容以來源文件的主要語言生成；系統可能會將中文內容轉換為台灣繁體用字。

#### 常見錯誤代碼

| Error Code | HTTP Status | 情境 |
| --- | --- | --- |
| FILESET_001 | 404 | 指定的 Fileset 不存在 |
| FILESET_005 | 400 | Fileset 內沒有任何檔案 |
| QA_001 | 400 | 所有檔案皆未能產生 QA pairs（內容為空、全部失敗，或 Fileset 內只有 QA 題庫檔） |
| QA_003 | 400 | `on_oversize=fail` 且有檔案內容過長，整批處理中止 |
| — | 422 | `temperature` 超出 0.0–1.0、`target_amount` 不是 1–3 的整數，或 `on_oversize` 不是 `fail`／`split` |

`QA_002` 不會以錯誤格式（`error_code`）回傳，僅出現在部分失敗時的 `error_message` 說明中（見上方提醒）。身份驗證錯誤（`AUTH_001`～`AUTH_003`）請參考「錯誤代碼說明-身份驗證類」章節；問答集生成相關錯誤碼完整說明請參考 [錯誤代碼說明-問答集生成類](https://privstation-docs.apmic.ai/latest/privai-400/錯誤代碼說明-問答集生成類.md)。
