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

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​

KeyValue
Request MethodPOST
acceptapplication/json
AuthorizationBearer <your-api-key>
Content-Typeapplication/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​

FieldTypeDetailRequired
modelstring指定對話的 LLM 模型,可用值請以「取得所有模型」API 查詢true
messagesarray對話的內容列表,與 OpenAI 的格式相容。每則 content 可為純字串,或由 text / file / image_url 內容區塊組成的陣列。角色與排列規則見下方「messages 格式」。true
fileset_idsarray[string]指定一個或多個 fileset id 進行 RAG;建議最多 5 個,但不強制限制。不可與 fileset_id 同時使用。若為空陣列 [],視為未指定 fileset,不執行 RAG。false
fileset_idstring已棄用,請改用 fileset_ids。uuid,指定單一 Knowledge Base。false
prompt_idstringuuid,指定對話所使用的 Prompt。不可與 prompt 同時提供,否則回傳 VAL_003。false
streamboolean是否以串流(SSE)輸出false
toolsarrayMCP Tool 定義列表,為選填欄位(僅支援 MCP Tool,欄位見下方「MCP Tool」)。省略 type 的元素視為 MCP Tool。false

Other Fields​

FieldTypeDetailRequired
promptstring直接輸入 Prompt 內容,支援 ReferenceFile 標籤與 Special Token(見下方 Advanced Prompt Overrides)。不可與 prompt_id 同時提供,否則回傳 VAL_003。false
reference_formatstring引用格式,目前僅可為 APMIC。控制回覆中 ReplyWithReference 引用標籤的處理方式:未提供時會移除標籤、保留標籤內文字;設為 APMIC 時則保留標籤,供前端解析引用來源(見下方「行內引用」)。false
include_previousinteger≥ 0。RAG 命中段落後,額外把「同一份檔案中序號在其之前」的 N 個相鄰段落一併帶入 context。行為與「資料參考搜尋」API 相同。false
include_afterinteger≥ 0。RAG 命中段落後,額外把「同一份檔案中序號在其之後」的 N 個相鄰段落一併帶入 context。false
search_kwargsobject進階檢索調校參數,一般情境不需調整。可用鍵為 k(每個 fileset 取回的候選段落數)、n(rerank 後保留的段落數)、distance_score_threshold、rerank_score_threshold,各鍵說明同「資料參考搜尋」API 的 search_kwargs。false
return_summaryboolean是否在回應中產生並回傳本次對話的摘要。true:系統會以近期的歷史訊息加上本次對話產生摘要並回傳;false:不產生摘要。false
with_summarystringauto 或 force,設定如何處理 summary。auto:由模型判斷本輪是否與先前對話相關,相關時才將摘要帶入 Context Window;force:一律將摘要帶入 Context Window。若未提供 summary,此參數無作用。false
summarystring前次對話的摘要內容字串(通常為上一次回應的 summary)false

messages 格式​

messages 中每則訊息的 role 可為 system、user、assistant(其他值回傳 422 Validation Error):

role欄位說明
systemcontent(必填)額外的系統指示。所有 system 訊息會合併後接在 PrivAI 的系統提示之後,位置不影響排列規則。
usercontent(必填)使用者訊息。content 可為字串,或 text / file / image_url 區塊陣列。
assistantcontent(必填)模型先前的回覆。

排列規則(不含 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"
}

欄位說明​

FieldTypeDetailRequired
typestring固定為 mcp,可省略false
server_labelstringMCP server 的識別名稱,會作為工具名稱的前綴(見「Tool Calling 與 MCP 整合」章節)true
server_urlstring外部 MCP server 的 URL,必須以 http:// 或 https:// 開頭true
server_descriptionstringMCP server 的描述說明(與 Responses API 相容而保留)false
allowed_toolsarray[string]白名單,只暴露清單中的工具給模型。留空或不提供時,會暴露該 MCP server 的所有工具。工具名稱可先用「探索 MCP 工具」API 查詢。false
authorizationstring存取 MCP server 用的授權憑證;系統會將此值原樣放入連線 headers 的 Authorization(例如需要 Bearer 時請自行帶上 Bearer 前綴)。false
headersobject連線 MCP server 時附帶的自訂 HTTP headers。false
require_approvalstring工具呼叫是否需要額外核准;目前僅可為 neverfalse
⚠️

注意: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​

FieldDetail
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_tokensOutput Token
usage.prompt_tokensPrompt Token
usage.total_tokensToken 總數
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)等欄位。

FieldDetail
referenced_chunks[].idchunk 的唯一識別值;即行內引用標籤 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_indexchunk 在該檔案內的序號(從 0 起算)
referenced_chunks[].metadata.chunk_rolematch:命中段落;before / after:由 include_previous / include_after 帶入的相鄰段落(相鄰段落不帶分數欄位)
referenced_chunks[].metadata.start_indexchunk 起始位置
referenced_chunks[].metadata.end_indexchunk 結束位置
referenced_chunks[].metadata._distance向量檢索的餘弦距離,數值越小越接近;僅由全文檢索命中的 chunk 不會有此欄位
referenced_chunks[].metadata.score向量相似度分數,範圍 [0..1],數值越高越好;僅由全文檢索命中的 chunk 不會有此欄位
referenced_chunks[].metadata.relevance_scorererank 後正規化的相關性分數(0~1)
referenced_chunks[].metadata.rerank_logitreranker 原始 logit
referenced_chunks[].page_contentchunk 內容
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_calls delta)依 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 欄位說明​

FieldDetail
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 CodeHTTP Status情境
VAL_003422同時提供 prompt 與 prompt_id
VAL_004422messages 排列不符合規則
VAL_005400同時提供 fileset_id 與 fileset_ids
PROMPT_001404prompt_id 指定的 Prompt 不存在
FILE_002404file 區塊或 ReferenceFile 標籤指定的檔案不存在
FILE_007 / FILE_010404指定檔案在所選 quality 沒有解析結果 / 解析結果為空
FILESET_001404指定的 fileset 不存在
FILESET_006409指定的 fileset 不是 completed 或 partial_failed 狀態
CHAT_001 ~ CHAT_006413 / 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: ... 交回模型。