跳至主要内容
版本:PrivStation 4.0.0
Markdown 原文

問答集生成

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

  • 取得檔案的解析內容(尚未解析的檔案會先以 HQ 模式解析,因此 Fileset 不需要先 commit)

  • 由 LLM 從內容中擷取可能的問題點(如定義、規則、流程),生成問題與參考答案

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

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

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​

KeyValue
Request MethodPOST
acceptapplication/json
AuthorizationBearer $PRIVAI_API_KEY
Content-Typeapplication/json

Query Parameters​

FieldTypeNoteRequired
fileset_idstringuuid,來源 Filesettrue

Request Payload​

{
"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

FieldTypeDetailRequired
model_namestring用來產生問答集的 LLM 模型,省略時使用系統預設模型。可用模型可由「取得所有模型」API 查詢false
extract_model_namestring用來將生成結果整理為結構化問答的模型,僅支援非 thinking 模型;省略時使用系統預設模型false
temperaturefloat控制生成文字的隨機性,範圍 0.0–1.0false
target_amountinteger可用值 1、2、3。每次呼叫模型時要求「至少」產生的 QA 數量;內容足夠時模型可能產生更多false
on_oversizestring單一檔案內容過長時的處理方式,可用值 fail、split。詳見下方說明false

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

  • fail:回傳 QA_003(400),整個請求中止,其他檔案即使已處理成功也不會產生 QA 檔案。

  • split:將內容切成多段(段落間有重疊)分別生成後合併,target_amount 會套用到每一段。

Response Body​

Status Code:201 Created(所有檔案皆成功時)

{
"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

FieldTypeDescription
objectstring固定為 file
idstring (uuid)產生的 QA 檔案 ID
filenamestring檔名,格式 QA_{fileset_id}.xlsx
filetypestring固定為 application/x-privai-qa
bytesinteger檔案大小(bytes)
metadataobject含 source_fileset_id(來源 Fileset ID)
purposestring(與 OpenAI 相容而保留),固定為 user_data
created_attimestamp建立時間
expires_attimestamp | null(與 OpenAI 相容而保留)
failed_file_idsarray | null生成失敗的來源檔案 ID 列表
error_messagestring | null有檔案失敗時的說明文字,無失敗時為 null
⚠️

部分檔案失敗時,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,每列一組問答:

questionanswer
Customer's name?Mr Bean
Booking NumberB32VO3

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

常見錯誤代碼​

Error CodeHTTP Status情境
FILESET_001404指定的 Fileset 不存在
FILESET_005400Fileset 內沒有任何檔案
QA_001400所有檔案皆未能產生 QA pairs(內容為空、全部失敗,或 Fileset 內只有 QA 題庫檔)
QA_003400on_oversize=fail 且有檔案內容過長,整批處理中止
—422temperature 超出 0.0–1.0、target_amount 不是 1–3 的整數,或 on_oversize 不是 fail/split

QA_002 不會以錯誤格式(error_code)回傳,僅出現在部分失敗時的 error_message 說明中(見上方提醒)。身份驗證錯誤(AUTH_001~AUTH_003)請參考「錯誤代碼說明-身份驗證類」章節;問答集生成相關錯誤碼完整說明請參考 錯誤代碼說明-問答集生成類。