Chat Completions

此 API 用於與語言模型(LLM)進行聊天推論,可搭配指定的 Prompt、Fileset(作為知識來源)與模型進行 RAG 生成;若需在推論過程中引用特定檔案內容,可透過 messages 指定檔案進行生成。
對話摘要(Summary)功能:支援自動或強制將上一輪摘要帶入 Context Window,以提升長對話的記憶能力與準確度。
messages 的 content 除了純文字外,也支援 text、file、image_url 等內容區塊,可用於檔案問答與圖片(多模態 / VLM)輸入。
此外,PrivAI 的 Chat Completions API 也支援透過 tools 欄位提供工具定義,讓模型在推理過程中可視需求呼叫外部工具,以擴展 AI Agent 的能力。
tools 為選填欄位,目前僅支援 MCP Tool,並支援傳入與 Responses API tools 欄位相容的 MCP Tool 定義格式,由 PrivAI 連線外部 MCP server 並代為執行工具。
本階段 MCP 僅支援 remote MCP / MCP connector,也就是透過 Streamable HTTP 連接的外部 MCP server,並同時支援 Stream 與 Non-Stream 模式。完整說明請參考 Tool Calling 與 MCP 整合。
Chat Completions API 支援在單一請求中指定單一或多個 filesets 進行 RAG 問答:
-
透過
fileset_ids傳入一個或多個 fileset ID -
fileset_id為舊版欄位,已棄用(deprecated),僅保留向後相容性,不建議使用 -
請勿同時傳入
fileset_id與fileset_ids -
若
fileset_ids為空陣列[],視為未指定 fileset,系統不會執行 RAG -
若
fileset_ids僅包含單一元素,效果等同於單一 fileset 查詢
curl -X 'POST' \
'http://127.0.0.1:8000/v1/chat/completions' \
-H 'accept: application/json' \
-H "Authorization: Bearer $PRIVAI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"fileset_ids": [
"01a51c51-8a07-46df-b1fc-1c6e6461b44f",
"13db6bfa-6f92-4d75-9d3c-9edeb4f8d1d2"
],
"messages": [
{
"role": "user",
"content": "What is APMIC?"
}
],
"model": "ace-1-24b-reasoning-v1",
"prompt_id": "6afecc03-ef73-4aa9-8ea6-88098047f3a2",
"return_summary": true,
"stream": true,
"summary": "Previous context about AI technology...",
"with_summary": "auto"
}'
Request Headers
| Key | Value |
|---|---|
| Request Method | POST |
| accept | application/json |
| Authorization | Bearer <your-api-key> |
| Content-Type | application/json |
Request Payload
基本 Request Payload 範例(單一 Fileset)
{
"fileset_ids": ["01a51c51-8a07-46df-b1fc-1c6e6461b44f"],
"messages": [
{
"role": "user",
"content": "What is APMIC?"
}
],
"model": "ace-1-24b-reasoning-v1",
"prompt_id": "6afecc03-ef73-4aa9-8ea6-88098047f3a2",
"return_summary": true,
"stream": true,
"summary": "Previous context about AI technology...",
"with_summary": "auto"
}
舊版寫法 "fileset_id": "01a51c51-8a07-46df-b1fc-1c6e6461b44f" 仍可使用,效果與上例相同,但已棄用。
使用多個 Filesets 進行 RAG
{
"fileset_ids": [
"01a51c51-8a07-46df-b1fc-1c6e6461b44f",
"13db6bfa-6f92-4d75-9d3c-9edeb4f8d1d2",
"ae3f1c0f-3d6d-4c2c-8fd8-2fbf65e8d991"
],
"messages": [
{
"role": "user",
"content": "Please summarize APMIC and its products."
}
],
"model": "ace-1-24b-reasoning-v1",
"prompt_id": "6afecc03-ef73-4aa9-8ea6-88098047f3a2",
"stream": false
}
fileset_ids 為空陣列(不做 RAG)
{
"fileset_ids": [],
"messages": [
{
"role": "user",
"content": "What is APMIC?"
}
],
"model": "ace-1-24b-reasoning-v1",
"stream": false
}
根據檔案進行對話
content 可包含 file 區塊,系統會在推論前將該檔案的解析結果帶入訊息。quality 為選填,可為 HQ / LQ / STD;指定的品質必須已有解析結果,否則回傳錯誤(見下方「錯誤情境」)。
{
"fileset_ids": ["01a51c51-8a07-46df-b1fc-1c6e6461b44f"],
"messages": [
{
"role": "user",
"content": [
{
"type": "file",
"file": {
"file_id": "b0d1bdbc-4f94-40b0-9358-68c579c99e8c",
"quality": "STD"
}
},
{
"type": "text",
"text": "What is APMIC?"
}
]
}
],
"model": "ace-1-24b-reasoning-v1",
"prompt_id": "6afecc03-ef73-4aa9-8ea6-88098047f3a2",
"return_summary": true,
"stream": true,
"summary": "Previous context about AI technology...",
"with_summary": "auto"
}
傳入圖片進行對話(多模態 / VLM)
content 可包含 image_url 區塊,url 支援 https 連結或 data URL(data:image/png;base64,...)。detail 為選填(auto / low / high)。圖片會原樣轉送給模型。
{
"messages": [
{
"role": "user",
"content": [
{
"type": "image_url",
"image_url": {
"url": "data:image/png;base64,iVBORw0KGgo...",
"detail": "auto"
}
},
{
"type": "text",
"text": "這張圖片的內容是什麼?"
}
]
}
],
"model": "ace-1-24b-reasoning-v1",
"stream": false
}
需選用支援圖片輸入的模型,否則會回傳 CHAT_004;單次請求的圖片數量超過模型上限則回傳 CHAT_005。詳見「錯誤代碼說明-Chat」章節。
在訊息中以 ReferenceFile 標籤帶入檔案內容
除了使用 type: "file" 內容區塊外,也可以在純文字 content、text 區塊或 prompt 欄位中直接放入自閉合標籤,系統會在推論前將該標籤替換成對應檔案的內容:
<ReferenceFile file_id="b0d1bdbc-4f94-40b0-9358-68c579c99e8c" quality="STD" />
-
file_id:必填 -
quality:選填,可選HQ/LQ/STD -
僅支援自閉合寫法(以
/>結尾)
{
"messages": [
{
"role": "user",
"content": "請根據這份文件回答問題:<ReferenceFile file_id=\"b0d1bdbc-4f94-40b0-9358-68c579c99e8c\" quality=\"STD\" /> APMIC 是什麼?"
}
],
"model": "ace-1-24b-reasoning-v1",
"stream": false
}
使用 MCP Tool
{
"messages": [
{
"role": "user",
"content": "請幫我使用 deepwiki 查詢某個專案說明"
}
],
"model": "ace-1-24b-reasoning-v1",
"tools": [
{
"type": "mcp",
"server_label": "deepwiki",
"server_url": "https://example-mcp-server.com/mcp",
"require_approval": "never"
}
],
"stream": true
}
Field Explanation
| Field | Type | Detail | Required |
|---|---|---|---|
| model | string | 指定對話的 LLM 模型,可用值請以「取得所有模型」API 查詢 | true |
| messages | array | 對話的內容列表,與 OpenAI 的格式相容。每則 content 可為純字串,或由 text / file / image_url 內容區塊組成的陣列。角色與排列規則見下方「messages 格式」。 | true |
| fileset_ids | array[string] | 指定一個或多個 fileset id 進行 RAG;建議最多 5 個,但不強制限制。不可與 fileset_id 同時使用。若為空陣列 [],視為未指定 fileset,不執行 RAG。 | false |
| fileset_id | string | 已棄用,請改用 fileset_ids。uuid,指定單一 Knowledge Base。 | false |
| prompt_id | string | uuid,指定對話所使用的 Prompt。不可與 prompt 同時提供,否則回傳 VAL_003。 | false |
| stream | boolean | 是否以串流(SSE)輸出 | false |
| tools | array | MCP Tool 定義列表,為選填欄位(僅支援 MCP Tool,欄位見下方「MCP Tool」)。省略 type 的元素視為 MCP Tool。 | false |
Other Fields
| Field | Type | Detail | Required |
|---|---|---|---|
| prompt | string | 直接輸入 Prompt 內容,支援 ReferenceFile 標籤與 Special Token(見下方 Advanced Prompt Overrides)。不可與 prompt_id 同時提供,否則回傳 VAL_003。 | false |
| reference_format | string | 引用格式,目前僅可為 APMIC。控制回覆中 ReplyWithReference 引用標籤的處理方式:未提供時會移除標籤、保留標籤內文字;設為 APMIC 時則保留標籤,供前端解析引用來源(見下方「行內引用」)。 | false |
| include_previous | integer | ≥ 0。RAG 命中段落後,額外把「同一份檔案中序號在其之前」的 N 個相鄰段落一併帶入 context。行為與「資料參考搜尋」API 相同。 | false |
| include_after | integer | ≥ 0。RAG 命中段落後,額外把「同一份檔案中序號在其之後」的 N 個相鄰段落一併帶入 context。 | false |
| search_kwargs | object | 進階檢索調校參數,一般情境不需調整。可用鍵為 k(每個 fileset 取回的候選段落數)、n(rerank 後保留的段落數)、distance_score_threshold、rerank_score_threshold,各鍵說明同「資料參考搜尋」API 的 search_kwargs。 | false |
| return_summary | boolean | 是否在回應中產生並回傳本次對話的摘要。true:系統會以近期的歷史訊息加上本次對話產生摘要並回傳;false:不產生摘要。 | false |
| with_summary | string | auto 或 force,設定如何處理 summary。auto:由模型判斷本輪是否與先前對話相關,相關時才將摘要帶入 Context Window;force:一律將摘要帶入 Context Window。若未提供 summary,此參數無作用。 | false |
| summary | string | 前次對話的摘要內容字串(通常為上一次回應的 summary) | false |
messages 格式
messages 中每則訊息的 role 可為 system、user、assistant(其他值回傳 422 Validation Error):
| role | 欄位 | 說明 |
|---|---|---|
system | content(必填) | 額外的系統指示。所有 system 訊息會合併後接在 PrivAI 的系統提示之後,位置不影響排列規則。 |
user | content(必填) | 使用者訊息。content 可為字串,或 text / file / image_url 區塊陣列。 |
assistant | content(必填) | 模型先前的回覆。 |
排列規則(不含 system 訊息),不符合時回傳 VAL_004:
-
第一則必須是
user -
user與assistant必須交替出現 -
最後一則必須是
user
PrivAI 只會把最後一則 user 訊息與 system 訊息送入模型。更早的對話歷史僅用於判斷相關性與產生摘要,不會直接放入 Context Window。若需要延續多輪對話的脈絡,請搭配下方的摘要機制(return_summary / summary / with_summary)。
多 Filesets 的 RAG 行為
當請求中指定 fileset 時,系統會以最後一則 user 訊息的文字作為查詢,依下列規則執行 RAG:
| 情境 | 行為 |
|---|---|
僅提供 fileset_id(已棄用) | 視為只含一個元素的 fileset_ids |
fileset_ids 長度為 1 | 對單一 fileset 檢索並 rerank |
fileset_ids 長度大於 1 | 同時對所有 filesets 執行 RAG 檢索,合併取回的 chunks,並對合併後的 chunks 進行 rerank,取最相關的 chunks 放入 context window |
fileset_ids 為 [] | 視為未指定 fileset,不做 RAG |
同時提供 fileset_id 與 fileset_ids | 視為無效請求,回傳 400(VAL_005) |
補充說明:
-
每個 fileset 都必須存在且為
completed或partial_failed狀態;任一 fileset 不符合時,整個 request 會失敗(FILESET_001/FILESET_006) -
檢索會同時進行向量檢索與全文檢索,再由 reranker 統一排序
-
有執行 RAG 時,回應會額外帶
referenced_chunks
tools
tools 為選填欄位,用於提供模型在推理過程中可使用的工具定義。當模型根據使用者輸入、系統提示與工具描述判斷需要額外工具協助時,可於推理過程中觸發工具呼叫。
tools 目前僅支援 MCP Tool,並支援傳入與 Responses API tools 欄位相容的 MCP Tool 定義格式。
說明
-
tools可省略 -
當未提供
tools時,系統將以一般聊天 / RAG 模式進行推論 -
當提供
tools時,模型可視需求選擇是否呼叫工具 -
同一請求中可包含多個 MCP Tool 定義
-
tools同時支援 Stream 與 Non-Stream 模式 -
模型呼叫工具時,PrivAI 會自動執行工具並把結果交回模型,重複直到模型產生最終回覆
MCP Tool
MCP Tool 用於透過 MCP(Model Context Protocol)整合外部工具與資源,使模型可在推理過程中存取更多外部能力。PrivAI 支援於 Chat Completions API 的 tools 欄位中傳入 MCP Tool 定義。
本階段支援範圍
-
支援與 Responses API
tools欄位相容的 MCP Tool 定義格式 -
僅支援 remote MCP / MCP connector
-
僅支援透過 Streamable HTTP 連接的外部 MCP server(
server_url必須以http://或https://開頭)
本階段不支援
-
local MCP server
-
SSE 型態的 MCP server
-
非 HTTP 型態的 MCP 連線方式
範例
{
"type": "mcp",
"server_label": "deepwiki",
"server_url": "https://example-mcp-server.com/mcp",
"allowed_tools": ["read_wiki_structure"],
"authorization": "Bearer <mcp-server-token>",
"require_approval": "never"
}
欄位說明
| Field | Type | Detail | Required |
|---|---|---|---|
| type | string | 固定為 mcp,可省略 | false |
| server_label | string | MCP server 的識別名稱,會作為工具名稱的前綴(見「Tool Calling 與 MCP 整合」章節) | true |
| server_url | string | 外部 MCP server 的 URL,必須以 http:// 或 https:// 開頭 | true |
| server_description | string | MCP server 的描述說明(與 Responses API 相容而保留) | false |
| allowed_tools | array[string] | 白名單,只暴露清單中的工具給模型。留空或不提供時,會暴露該 MCP server 的所有工具。工具名稱可先用「探索 MCP 工具」API 查詢。 | false |
| authorization | string | 存取 MCP server 用的授權憑證;系統會將此值原樣放入連線 headers 的 Authorization(例如需要 Bearer 時請自行帶上 Bearer 前綴)。 | false |
| headers | object | 連線 MCP server 時附帶的自訂 HTTP headers。 | false |
| require_approval | string | 工具呼叫是否需要額外核准;目前僅可為 never | false |
注意:authorization 與 headers 中的 Authorization 不可同時提供。兩者擇一即可;同時帶入會回傳 422 Validation Error。
補充說明
-
PrivAI 會在平台內部處理 MCP client 邏輯
-
PrivAI 會將 MCP Tool 定義轉換為底層模型系統可理解的 native tool spec
-
對開發者而言,只需於
tools中傳入 MCP Tool 定義即可使用
Response Body
當 stream=false 時,系統會於完成模型推理、RAG 檢索與必要的工具呼叫後,一次性回傳完整回應。
若使用 tools:
-
若模型未選擇呼叫工具,回應行為與一般聊天相同
-
若模型呼叫 MCP Tool,PrivAI 會先完成工具執行,再將結果交回模型,回傳最後一輪的回覆。工具執行失敗(包含逾時)時,錯誤訊息會以
Tool error: ...的形式交回模型,由模型決定如何回覆,不會讓整個請求失敗
若本次請求有使用 fileset_ids(或 fileset_id)並取得參考段落,response 會額外回傳 referenced_chunks,表示最終經 rerank 後、真正放入 context window 的 chunks;未執行 RAG 或沒有任何段落時不會出現此欄位。summary 僅在 return_summary=true 時出現。
{
"id": "chatcmpl-9e9ddff2-78c7-4de9-8995-f5f99647c6bf",
"choices": [
{
"finish_reason": "stop",
"index": 0,
"logprobs": null,
"message": {
"content": "\n\nAPMIC (Accelerate Private Machine Intelligence Company) is a Taiwan-based AI software company specializing in natural language understanding and generation ...",
"refusal": null,
"role": "assistant",
"annotations": null,
"audio": null,
"function_call": null,
"tool_calls": null,
"reasoning_content": "\nOkay, the user asked about APMIC. Let me start by recalling what I know.\n...\n"
}
}
],
"created": 1761980000,
"model": "ace-1-24b-reasoning-v1",
"object": "chat.completion",
"service_tier": null,
"system_fingerprint": null,
"usage": {
"completion_tokens": 1000,
"prompt_tokens": 1500,
"total_tokens": 3000,
"completion_tokens_details": null,
"prompt_tokens_details": null
},
"summary": "User asked about what's APMIC. ...",
"referenced_chunks": [
{
"id": "c6c92ac0-745a-43b6-aa30-53f2c9ff57aa",
"metadata": {
"__APMICTextSplitter__h1": "...",
"file_id": "25468ceb-bf0a-44c5-9c9b-13cd4241ccef",
"fileset_id": "7d7765de-faa9-4771-8c9c-ca49d844ce92",
"filename": "example.pdf",
"filetype": "application/pdf",
"file_chunk_index": 3,
"chunk_role": "match",
"start_index": 0,
"end_index": 0,
"_distance": 0.7495614886283875,
"score": 0.25043851137161255,
"relevance_score": 0.5205078125,
"rerank_logit": 0.82177734375
},
"page_content": "...",
"type": "Document"
}
]
}
Response Field Explanation
| Field | Detail |
|---|---|
| id | 對話紀錄的唯一鍵 |
| choices[] | LLM 回覆列表 |
choices[].finish_reason | 結束原因,例如 stop |
choices[].index | (與 OpenAI 相容而保留) |
choices[].logprobs | (與 OpenAI 相容而保留) |
choices[].message | 推論結果 |
choices[].message.content | 推論結果的文字內容 |
choices[].message.refusal | (與 OpenAI 相容而保留) |
choices[].message.role | (與 OpenAI 相容而保留) |
choices[].message.annotations | (與 OpenAI 相容而保留) |
choices[].message.audio | (與 OpenAI 相容而保留) |
choices[].message.function_call | (與 OpenAI 相容而保留) |
choices[].message.tool_calls | 工具呼叫資訊(與 OpenAI 相容而保留)。MCP Tool 由 PrivAI 在內部執行完畢後才回傳最後一輪的回覆,因此一般為 null;串流模式下可在各輪的 delta 中看到模型發出的 tool_calls |
choices[].message.reasoning_content | 思考過程的 Token(僅推理模型) |
| created | 對話建立的時間 |
| model | 對話使用的模型(與請求的 model 相同) |
| object | (與 OpenAI 相容而保留) |
| service_tier | (與 OpenAI 相容而保留) |
| system_fingerprint | (與 OpenAI 相容而保留) |
| usage | 用量統計物件 |
usage.completion_tokens | Output Token |
usage.prompt_tokens | Prompt Token |
usage.total_tokens | Token 總數 |
usage.completion_tokens_details | (與 OpenAI 相容而保留) |
usage.prompt_tokens_details | (與 OpenAI 相容而保留) |
| summary | 本次對話結束後生成的摘要內容;僅在 return_summary=true 時出現 |
| referenced_chunks | 最終經 rerank 後、實際放入 context window 的 chunks;未執行 RAG 或沒有任何段落時不會出現 |
Referenced Chunk 結構說明
referenced_chunks 中每個元素的結構與「資料參考搜尋」API 的回應相同,metadata 中的 fileset_id 標示該 chunk 來自哪一個 fileset。metadata 的實際欄位依檔案格式而異,也可能包含切分器附加的章節資訊(例如 __APMICTextSplitter__h1)等欄位。
| Field | Detail |
|---|---|
referenced_chunks[].id | chunk 的唯一識別值;即行內引用標籤 chunk_ids 所指的 ID |
referenced_chunks[].metadata.file_id | 該 chunk 所屬的原始檔案 ID |
referenced_chunks[].metadata.fileset_id | 該 chunk 所屬的 fileset ID |
referenced_chunks[].metadata.filename | 原始檔名 |
referenced_chunks[].metadata.filetype | 原始檔案類型(MIME type) |
referenced_chunks[].metadata.file_chunk_index | chunk 在該檔案內的序號(從 0 起算) |
referenced_chunks[].metadata.chunk_role | match:命中段落;before / after:由 include_previous / include_after 帶入的相鄰段落(相鄰段落不帶分數欄位) |
referenced_chunks[].metadata.start_index | chunk 起始位置 |
referenced_chunks[].metadata.end_index | chunk 結束位置 |
referenced_chunks[].metadata._distance | 向量檢索的餘弦距離,數值越小越接近;僅由全文檢索命中的 chunk 不會有此欄位 |
referenced_chunks[].metadata.score | 向量相似度分數,範圍 [0..1],數值越高越好;僅由全文檢索命中的 chunk 不會有此欄位 |
referenced_chunks[].metadata.relevance_score | rerank 後正規化的相關性分數(0~1) |
referenced_chunks[].metadata.rerank_logit | reranker 原始 logit |
referenced_chunks[].page_content | chunk 內容 |
referenced_chunks[].type | 固定為 Document |
Stream Response
當 stream=true 時,回應為 Server-Sent Events(Content-Type: text/event-stream)。每個事件為一行 data: 加上一個 chat.completion.chunk JSON,串流以 data: [DONE] 結束。連線期間可能收到以 : 開頭的 keep-alive 註解行,請直接忽略。
data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":"APMIC"},"finish_reason":null}],...}
data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],...}
data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[],"summary":"...","referenced_chunks":[...]}
data: [DONE]
-
模型輸出片段(含
reasoning_content、模型呼叫 MCP 工具時的tool_callsdelta)依 OpenAI 格式逐步回傳。 -
使用 MCP Tool 時,每一輪模型輸出之後,PrivAI 會為每個工具呼叫回傳一個
role = "tool"的 chunk,表示工具輸出結果,接著繼續串流下一輪模型輸出。 -
若本次請求有取得參考段落,或
return_summary=true且有產生回覆內容,系統會在結束前額外送出一個最後的 chunk,其choices為空陣列[],並帶referenced_chunks與 / 或summary。兩者皆無時不會送出此 chunk。
Tool Response Chunk 範例
{
"id": "chatcmpl-c2a1273b-12a0-4486-a0aa-4ef2c8013b27",
"choices": [
{
"delta": {
"content": "...",
"function_call": null,
"refusal": null,
"role": "tool",
"tool_calls": null,
"tool_call_id": "chatcmpl-tool-5513b91b1af44f6c91d89ec6aed1eb7c",
"tool_call_index": 1
},
"finish_reason": null,
"index": 0,
"logprobs": null
}
],
"created": 1772010876,
"model": "ace-2-27b",
"object": "chat.completion.chunk",
"service_tier": null,
"system_fingerprint": null,
"usage": null
}
最後一個 Stream Chunk 範例(含 summary 與 referenced_chunks)
{
"id": "chatcmpl-final-123",
"choices": [],
"created": 1772010999,
"model": "ace-1-24b-reasoning-v1",
"object": "chat.completion.chunk",
"service_tier": null,
"system_fingerprint": null,
"usage": null,
"summary": "User asked about APMIC and related products...",
"referenced_chunks": [
{
"id": "c6c92ac0-745a-43b6-aa30-53f2c9ff57aa",
"metadata": {
"file_id": "25468ceb-bf0a-44c5-9c9b-13cd4241ccef",
"fileset_id": "7d7765de-faa9-4771-8c9c-ca49d844ce92",
"filename": "example.pdf",
"filetype": "application/pdf",
"file_chunk_index": 3,
"chunk_role": "match",
"start_index": 0,
"end_index": 0,
"_distance": 0.7495614886283875,
"score": 0.25043851137161255,
"relevance_score": 0.5205078125,
"rerank_logit": 0.82177734375
},
"page_content": "...",
"type": "Document"
}
]
}
串流中的錯誤
-
在第一個 chunk 送出之前發生的錯誤(例如參數驗證、fileset 狀態、RAG 檢索失敗、模型拒絕請求、MCP server 連線失敗),會以一般 HTTP 錯誤回應(非 200)回傳,格式與 Non-Stream 相同。
-
串流開始之後才發生的錯誤,HTTP 狀態維持 200,系統會送出一個帶有頂層
error物件的事件,接著送出data: [DONE]結束串流。error的格式與 OpenAI SDK 相容,可被 SDK 轉為APIError:
{
"error": {
"message": "Failed to process the request. Please refer to the API documentation.",
"type": "ChatUpstreamError",
"code": "CHAT_006",
"error_code": "CHAT_006",
"error_message": "Failed to process the request. Please refer to the API documentation.",
"upstream_status": 500,
"upstream_message": "..."
}
}
Stream Chunk 欄位說明
| Field | Detail |
|---|---|
| object | 固定為 chat.completion.chunk |
choices[].delta.role | 為 tool 時,表示此 chunk 為 MCP 工具輸出 |
choices[].delta.content | 模型輸出片段;role 為 tool 時為工具輸出內容(工具失敗時為 Tool error: ...) |
choices[].delta.tool_call_id | 對應原始工具呼叫的識別值 |
choices[].delta.tool_call_index | 對應原始工具呼叫在該輪 tool_calls 中的 index |
| summary | 若啟用摘要功能,會在最後一個 chunk 回傳 |
| referenced_chunks | 若有進行 RAG 並取得段落,會在最後一個 chunk 回傳最終使用的 referenced chunks |
行內引用(reference_format)
有執行 RAG 時,模型會用 ReplyWithReference 標籤標註依據知識庫內容回答的句子,chunk_ids 對應 referenced_chunks[].id:
<ReplyWithReference chunk_ids="['075c2289-a577-4bf1-9cab-e6c8d2c09e94']">CaiGunn 的成功案例包括……</ReplyWithReference>
-
未提供
reference_format:系統會移除這些標籤,只保留標籤內的文字(Stream 與 Non-Stream 皆同)。 -
reference_format: "APMIC":保留標籤,供前端解析並對應到referenced_chunks顯示引用來源。 -
chunk_ids屬性值為單引號字串組成的列表文字,並非嚴格的 JSON,解析時請注意。
Advanced Prompt Overrides
為了讓進階使用者更靈活測試底層模型的行為,prompt 欄位(以及 prompt_id 所指向的 Prompt 內容)支援以下 Special Token,可用來跳過或取代 PrivAI 預設的系統提示。這項設計適合進行模型對比、真實語言測試、精準調參等進階應用。
NO_PROMPT
<NO_PROMPT>
不使用任何系統提示。prompt 的內容必須只有這個 token(也可寫成 <NO_SYSTEM_PROMPT>),模型只會收到 messages 本身(含呼叫端自帶的 system 訊息),適合測試模型未套用系統提示時的原始行為。此模式下即使指定 fileset,檢索結果也不會放入提示中(referenced_chunks 仍會回傳)。
IGNORE_SYSTEM_PROMPT
<IGNORE_SYSTEM_PROMPT>你是一位專業的客服人員,請用繁體中文簡短回答。
忽略 PrivAI 預設的系統提示,改以 token 之後的文字作為完整的系統提示,適合完全自定義輸入。若有指定 fileset 且內容中沒有 {context} 佔位符,系統會自動在最後附加參考資料;也可以自行在提示中放入 {context} 決定參考資料的位置。
摘要機制
-
摘要來源:摘要需由當次 request 主動帶入(
summary),目前系統不會自動儲存或延續先前對話摘要 -
歷史訊息:產生摘要與判斷相關性時,會使用
messages中近期的歷史訊息;file + text的混合訊息或單純assistant + user的互動皆算作一輪對話 -
使用情境:
-
若第一次對話將
return_summary設定為false,則第二次對話即使將with_summary設定為force,因無前次摘要紀錄,將不會有任何摘要被帶入(除非手動填寫summary欄位)。 -
使用 MCP Tool 時,摘要只會在模型產生最終回覆後產生一次。
-
注意事項
-
tools為選填欄位 -
tools目前僅支援 MCP Tool -
MCP Tool 僅支援 remote MCP / MCP connector,且僅支援透過 HTTP URL(Streamable HTTP)連接的外部 MCP server
-
MCP Tool 的
authorization與headers中的Authorization不可同時提供 -
Stream 與 Non-Stream 模式皆支援
tools -
prompt與prompt_id不可同時使用 -
fileset_id與fileset_ids不可同時使用;fileset_ids建議最多 5 個,但不強制限制 -
多 filesets 模式下,若任一 fileset 發生錯誤,整個 request 會失敗
-
Chat Completions API 的租戶範圍與資料隔離規則仍依既有 API Key / Tenant Scope 生效;若工具流程中涉及 PrivAI 內部資源,仍應遵循既有租戶限制(見「Tenant Scope 與資料隔離」章節)
錯誤情境
錯誤回應採統一格式:
{
"error_code": "FILESET_006",
"error_message": "Cannot use fileset. Please refer to the API documentation.",
"fileset_id": "01a51c51-8a07-46df-b1fc-1c6e6461b44f",
"state": "processing"
}
| Error Code | HTTP Status | 情境 |
|---|---|---|
VAL_003 | 422 | 同時提供 prompt 與 prompt_id |
VAL_004 | 422 | messages 排列不符合規則 |
VAL_005 | 400 | 同時提供 fileset_id 與 fileset_ids |
PROMPT_001 | 404 | prompt_id 指定的 Prompt 不存在 |
FILE_002 | 404 | file 區塊或 ReferenceFile 標籤指定的檔案不存在 |
FILE_007 / FILE_010 | 404 | 指定檔案在所選 quality 沒有解析結果 / 解析結果為空 |
FILESET_001 | 404 | 指定的 fileset 不存在 |
FILESET_006 | 409 | 指定的 fileset 不是 completed 或 partial_failed 狀態 |
CHAT_001 ~ CHAT_006 | 413 / 415 / 502 | 查詢過長、embedding / reranker 服務失敗、模型不支援圖片、圖片過多、其他上游錯誤,詳見 錯誤代碼說明-Chat |
欄位型別不符、messages 的 role 不是 system / user / assistant、MCP Tool 定義格式錯誤(例如缺少 server_label 或 server_url、同時提供 authorization 與 headers.Authorization)時,回傳 422 Validation Error。使用 MCP Tool 時,MCP server URL 格式錯誤或無法連線會讓請求失敗;工具執行失敗或逾時則不會讓請求失敗,而是以 Tool error: ... 交回模型。