# Chat Completions

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

此 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 整合](https://privstation-docs.apmic.ai/latest/privai-400/tool-calling-與-mcp-整合.md)。  
Chat Completions API 支援在單一請求中指定**單一或多個 filesets** 進行 RAG 問答：

- 透過 `fileset_ids` 傳入一個或多個 fileset ID

- `fileset_id` 為舊版欄位，已棄用（deprecated），僅保留向後相容性，**不建議使用**

- 請勿同時傳入 `fileset_id` 與 `fileset_ids`

- 若 `fileset_ids` 為空陣列 `[]`，視為未指定 fileset，系統不會執行 RAG

- 若 `fileset_ids` 僅包含單一元素，效果等同於單一 fileset 查詢

```bash
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 &lt;your-api-key> |
| Content-Type | application/json |

---

### Request Payload

#### 基本 Request Payload 範例（單一 Fileset）

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

```json
{
  "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）

```json
{
  "fileset_ids": [],
  "messages": [
    {
      "role": "user",
      "content": "What is APMIC?"
    }
  ],
  "model": "ace-1-24b-reasoning-v1",
  "stream": false
}
```

#### 根據檔案進行對話

`content` 可包含 `file` 區塊，系統會在推論前將該檔案的解析結果帶入訊息。`quality` 為選填，可為 `HQ` / `LQ` / `STD`；指定的品質必須已有解析結果，否則回傳錯誤（見下方「錯誤情境」）。

```json
{
  "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`）。圖片會原樣轉送給模型。

```json
{
  "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
}
```

:::warning[⚠️]

需選用支援圖片輸入的模型，否則會回傳 `CHAT_004`；單次請求的圖片數量超過模型上限則回傳 `CHAT_005`。詳見「錯誤代碼說明-Chat」章節。

:::

#### 在訊息中以 ReferenceFile 標籤帶入檔案內容

除了使用 `type: "file"` 內容區塊外，也可以在純文字 `content`、`text` 區塊或 `prompt` 欄位中直接放入自閉合標籤，系統會在推論前將該標籤替換成對應檔案的內容：

```text
<ReferenceFile file_id="b0d1bdbc-4f94-40b0-9358-68c579c99e8c" quality="STD" />
```

- `file_id`：必填

- `quality`：選填，可選 `HQ` / `LQ` / `STD`

- 僅支援自閉合寫法（以 `/>` 結尾）

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

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

:::info[💡]

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 連線方式

#### 範例

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

:::warning[⚠️]

**注意**：`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` 時出現。

```json
{
  "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 註解行，請直接忽略。

```text
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 範例

```json
{
  "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）

```json
{
  "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`：

```json
{
  "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`：

```text
<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

```text
<NO_PROMPT>
```

**不使用任何系統提示**。`prompt` 的內容必須**只有**這個 token（也可寫成 `<NO_SYSTEM_PROMPT>`），模型只會收到 `messages` 本身（含呼叫端自帶的 system 訊息），適合測試模型未套用系統提示時的原始行為。此模式下即使指定 fileset，檢索結果也不會放入提示中（`referenced_chunks` 仍會回傳）。

#### IGNORE_SYSTEM_PROMPT

```text
<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 與資料隔離」章節）

---

### 錯誤情境

錯誤回應採統一格式：

```json
{
  "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](https://privstation-docs.apmic.ai/latest/privai-400/錯誤代碼說明-chat.md) |

欄位型別不符、`messages` 的 `role` 不是 `system` / `user` / `assistant`、MCP Tool 定義格式錯誤（例如缺少 `server_label` 或 `server_url`、同時提供 `authorization` 與 `headers.Authorization`）時，回傳 422 Validation Error。使用 MCP Tool 時，MCP server URL 格式錯誤或無法連線會讓請求失敗；工具執行失敗或逾時則不會讓請求失敗，而是以 `Tool error: ...` 交回模型。
