> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/build/agent-ops/evaluations/trace-timeline.md).

# 對話詳情與執行時間軸

在 AI 助理監控的對話詳情頁，用執行時間軸、完整對話紀錄與用量面板，查出一則回覆為什麼慢、為什麼答錯、花了多少 Credit

每一則 Agent 回覆在「<mark style="color:blue;">AgentOps</mark>」→「<mark style="color:blue;">AI 助理監控</mark>」→「<mark style="color:blue;">對話紀錄</mark>」都有一筆紀錄；點最右側的「<mark style="color:blue;">詳情</mark>」進入**對話詳情**頁。這一頁把一次回覆從收到訊息到送出答案的每個步驟攤開來，是排查「為什麼慢」「為什麼答錯」「為什麼這麼貴」的主要畫面。

| 想知道                        | 看哪一區                                                           |
| -------------------------- | -------------------------------------------------------------- |
| 這幾秒花在哪、哪一步是瓶頸              | [執行時間軸](#trace-timeline)                                       |
| 模型實際看到了什麼（系統提示、記憶、檢索結果）    | [執行時間軸](#trace-timeline) 的 LLM 步驟、[完整對話紀錄](#full-conversation) |
| 工具有沒有被呼叫、回了什麼              | [執行時間軸](#trace-timeline) 的工具步驟                                 |
| Token、Credit、Prompt 快取省了多少 | [用量與效能面板](#usage-panels)                                       |
| 要把這筆紀錄交給工程師或留存稽核           | [匯出](#export)                                                  |

## 頁面結構 <a href="#page-layout" id="page-layout"></a>

頁首有「<mark style="color:blue;">上一筆紀錄</mark>」／「<mark style="color:blue;">下一筆紀錄</mark>」（依目前列表的順序切換）、「<mark style="color:blue;">複製連結</mark>」與「<mark style="color:blue;">匯出</mark>」。往下依序是：

1. <mark style="color:blue;">**基本資訊**</mark>：用戶輸入訊息、輸出訊息、AI 助理、LLM、用戶、來源、回應時間、使用者反饋等；排程執行的紀錄另有排程名稱與狀態。
2. <mark style="color:blue;">**識別資訊**</mark>：記錄 ID、對話 ID、對話平台 ID、AI 助理 ID、用戶訊息 ID、機器人訊息 ID（排程執行另有排程 ID），每個都可複製，方便回報問題時對照。
3. <mark style="color:blue;">**完整對話紀錄**</mark>：送給模型的完整上下文與模型回覆。
4. <mark style="color:blue;">**執行時間軸**</mark>：每個步驟的耗時、Token 與 Credit。
5. **用量與效能面板**：對話文字統計、Credit 消耗統計、LLM 呼叫明細、處理時間分析、串流效能指標、字數使用統計。
6. <mark style="color:blue;">**品質評分詳情**</mark>、<mark style="color:blue;">**參考資料**</mark>、<mark style="color:blue;">**錯誤訊息**</mark>**與**<mark style="color:blue;">**加入 FAQ**</mark>：見 [AI 客服品質管理](/serve/ai-quality-guide.md) 與 [對話紀錄加入 FAQ](/build/agent-ops/add-to-faq.md)。

## 執行時間軸 <a href="#trace-timeline" id="trace-timeline"></a>

標題下方會先告訴你「這 N 秒花在哪？」，右側圖例標示三種顏色：<mark style="color:blue;">LLM</mark>、<mark style="color:blue;">工具</mark>，以及紅框的<mark style="color:blue;">瓶頸</mark>。時間軸依發生順序列出每個步驟，每一步顯示<mark style="color:blue;">耗時</mark>、<mark style="color:blue;">Token</mark>與<mark style="color:blue;">Credit</mark>；耗時最長的步驟會以紅框標成瓶頸，並預設展開。點任一步驟可「<mark style="color:blue;">展開詳情</mark>」／「<mark style="color:blue;">收合詳情</mark>」。

### 步驟類型 <a href="#step-types" id="step-types"></a>

| 步驟                                              | 內容                                                                                                                                                                                                                                        | 排查重點                                                                  |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| <mark style="color:blue;">前處理（N 步）</mark>       | 分派延遲、服務初始化、載入訊息、載入上下文、等待附件、輸入處理、檢索準備等階段，收合成一組，展開可看「<mark style="color:blue;">前處理階段明細</mark>」                                                                                                                                              | 等待附件或分派延遲偏長時，問題不在模型而在前置作業                                             |
| <mark style="color:blue;">檢索</mark>             | 知識庫向量化（Embedding）與檢索                                                                                                                                                                                                                      | 檢索慢通常是知識庫過大或 Reranker 設定                                              |
| <mark style="color:blue;">第 N 輪</mark> LLM      | Agent 模式下每一次模型呼叫算一輪。顯示<mark style="color:blue;">輸入</mark>來源（來自使用者訊息／來自工具結果／來自上一輪 LLM）、<mark style="color:blue;">決策</mark>（直接回覆／呼叫 N 個工具／繼續至第 N 輪 LLM）、<mark style="color:blue;">LLM 請求與回應</mark>的送出與接收時間、本輪的輸入／輸出 Token 與合計、Credit（含快取折抵） | 輪數太多代表 Agent 反覆呼叫工具；單輪耗時長則是模型本身慢                                      |
| <mark style="color:blue;">工具執行詳情</mark>         | 工具名稱、<mark style="color:blue;">狀態</mark>（成功／失敗／逾時）、<mark style="color:blue;">輸入</mark>參數、<mark style="color:blue;">輸出</mark>結果、API 工具的<mark style="color:blue;">請求 URL</mark>，以及結果送到哪裡（第 N 輪 LLM 或最終回覆）                                   | 工具失敗或逾時、回傳內容不如預期，直接在這裡看                                               |
| <mark style="color:blue;">Hook 執行紀錄</mark>      | 這則訊息經過的<mark style="color:blue;">輸入 Hook</mark>／<mark style="color:blue;">輸出 Hook</mark>與處置結果                                                                                                                                             | 回覆被遮罩或攔截時，看是哪一條 Hook 做的，詳見 [Hook 執行紀錄](/build/hook/execution-logs.md) |
| <mark style="color:blue;">Guardrail 評估結果</mark> | 安全防護的判定動作（`NONE` 代表放行、`BLOCKED` 代表攔截）                                                                                                                                                                                                     | 回覆被擋下時先看這裡                                                            |
| <mark style="color:blue;">後處理操作</mark>          | 儲存回覆、排程評估、更新用量等收尾動作                                                                                                                                                                                                                       | 一般很短，偏長代表系統負載                                                         |

### 查看模型看到的內容 <a href="#payload-views" id="payload-views"></a>

展開 LLM 步驟的「<mark style="color:blue;">LLM 請求與回應</mark>」，可以用三種檢視切換送給模型的內容：

* <mark style="color:blue;">分類</mark>：把請求拆成<mark style="color:blue;">系統提示詞</mark>、<mark style="color:blue;">對話歷史</mark>、<mark style="color:blue;">長期記憶</mark>、<mark style="color:blue;">檢索結果</mark>、<mark style="color:blue;">工具回傳結果</mark>、<mark style="color:blue;">目前使用者訊息</mark>、<mark style="color:blue;">可用工具</mark>與<mark style="color:blue;">其他</mark>，每類標示項數。要確認「知識庫有沒有撈到正確段落」「記憶有沒有帶進去」就看這裡。
* <mark style="color:blue;">格式化</mark>：依角色（系統／使用者／助理／工具）逐則顯示。
* <mark style="color:blue;">原始</mark>：未經整理的原始內容。

每個區塊右上角有「<mark style="color:blue;">複製</mark>」，可把該段內容複製給工程師。

{% hint style="info" %}
時間軸只在這則回覆有留下追蹤資料時顯示；較舊的紀錄或部分回答模式只會有基本資訊與用量面板。
{% endhint %}

## 完整對話紀錄 <a href="#full-conversation" id="full-conversation"></a>

「<mark style="color:blue;">完整對話紀錄</mark>」以對話形式呈現這次模型呼叫的全部內容，每則訊息標示角色 <mark style="color:blue;">System</mark>／<mark style="color:blue;">User</mark>／<mark style="color:blue;">Assistant</mark>／<mark style="color:blue;">Tool</mark>，並以標籤標出它在這次回覆中的用途：

| 標籤                                    | 意思                                                     |
| ------------------------------------- | ------------------------------------------------------ |
| <mark style="color:blue;">系統提示</mark> | 角色指令與平台組出的系統提示詞                                        |
| <mark style="color:blue;">長期記憶</mark> | 持久記憶或跨對話檢索帶進來的內容，見 [Agent 的記憶](/build/agent.md#memory) |
| <mark style="color:blue;">歷史對話</mark> | 同一段對話中較早的往返                                            |
| <mark style="color:blue;">本輪輸入</mark> | 使用者這一次送出的訊息                                            |
| <mark style="color:blue;">模型回覆</mark> | 模型這一次的輸出                                               |

長訊息預設截斷，點「<mark style="color:blue;">展開全文</mark>」看完整內容、「<mark style="color:blue;">收合</mark>」收起。完整對話紀錄與執行時間軸互相連結：在時間軸點「<mark style="color:blue;">查看來源</mark>」會跳到對應的訊息，在對話紀錄點「<mark style="color:blue;">回到使用者訊息</mark>」則回到時間軸起點。

## 用量與效能面板 <a href="#usage-panels" id="usage-panels"></a>

### 對話文字統計 <a href="#token-usage" id="token-usage"></a>

這則回覆各環節的 <mark style="color:blue;">Token 用量</mark>：<mark style="color:blue;">向量化</mark>、<mark style="color:blue;">圖片向量化</mark>（只在有使用圖片搜尋時顯示）、<mark style="color:blue;">重排序</mark>、<mark style="color:blue;">LLM 輸入</mark>、<mark style="color:blue;">LLM 輸出</mark>、<mark style="color:blue;">LLM Cache 建立</mark>、<mark style="color:blue;">LLM Cache 讀取</mark>，以及 <mark style="color:blue;">Token 總計</mark>。Cache 讀取的 Token 是從 Prompt 快取命中的部分，以優惠費率計費。

### Credit 消耗統計 <a href="#credit-cost" id="credit-cost"></a>

同樣的環節換算成 <mark style="color:blue;">Credits</mark>，加總為 <mark style="color:blue;">Credit 總計</mark>；下方的「<mark style="color:blue;">已透過 Prompt 快取節省</mark>」是平台自動啟用 Prompt 快取後，這則回覆相較未命中快取少付的 Credit。計費規則見 [Credits 額度](/others/credits.md)。

### LLM 呼叫明細 <a href="#llm-call-breakdown" id="llm-call-breakdown"></a>

Agent 模式下每一次 LLM 呼叫的<mark style="color:blue;">序號</mark>、<mark style="color:blue;">耗時</mark>與 Token，各欄加總約等於上方統計（允許進位誤差）。輪數多、每輪 Token 都高時，可考慮縮短角色指令或限制 [最大迭代次數](/build/agent/custom-max-tokens.md)。

### 處理時間分析 <a href="#processing-time" id="processing-time"></a>

| 項目                                                                              | 說明                                         |
| ------------------------------------------------------------------------------- | ------------------------------------------ |
| <mark style="color:blue;">附件處理</mark>                                           | 對話附件上傳與解析的時間                               |
| <mark style="color:blue;">向量化</mark>／<mark style="color:blue;">重排序</mark>       | 知識庫檢索的兩個階段                                 |
| <mark style="color:blue;">AI 模型推理</mark>                                        | LLM 推理與生成回覆的完整過程                           |
| <mark style="color:blue;">系統開銷</mark>                                           | 完整回覆耗時扣除上述階段後的剩餘時間：系統初始化、請求驗證、Agent 工作流準備等 |
| <mark style="color:blue;">核心處理時間</mark>／<mark style="color:blue;">完整回覆耗時</mark> | 前者是各處理階段的加總，後者是使用者實際等待的時間                  |

### 串流效能指標與系統效能瀑布圖 <a href="#streaming-metrics" id="streaming-metrics"></a>

| 指標                                                                                  | 說明                                                                                                                                      |
| ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">First Token Time</mark>                                   | 從 LLM 開始生成到吐出第一個 Token 的時間，反映模型啟動速度                                                                                                     |
| <mark style="color:blue;">First Token From Request</mark>                           | 從送出請求到收到第一個 Token 的總延遲，含前處理、檢索、向量化，是使用者感受到的「等多久才開始出字」                                                                                   |
| <mark style="color:blue;">生成速度</mark>                                               | 串流期間平均每秒生成的 Token 數（TPS），越高越流暢                                                                                                          |
| <mark style="color:blue;">總生成時間</mark>／<mark style="color:blue;">生成 Token 總數</mark> | 完整回應的生成時間與 Token 數                                                                                                                      |
| <mark style="color:blue;">效能狀態</mark>                                               | 依 First Token 延遲與生成速度綜合判定為<mark style="color:blue;">優秀</mark>／<mark style="color:blue;">良好</mark>／<mark style="color:blue;">需要優化</mark> |

「<mark style="color:blue;">系統效能瀑布圖</mark>」把各階段依時間先後畫成橫條，<mark style="color:blue;">總耗時</mark>為全長，一眼看出哪一段最長；想看每一步的細節再到 [執行時間軸](#trace-timeline)。

### 字數使用統計 <a href="#words-usage" id="words-usage"></a>

<mark style="color:blue;">輸入字數</mark>、<mark style="color:blue;">輸出字數</mark>與<mark style="color:blue;">字數總計</mark>，對應 Agent「使用分析」分頁的對話字數。

## 匯出 <a href="#export" id="export"></a>

頁首「<mark style="color:blue;">匯出</mark>」下拉有三種格式，皆直接下載到瀏覽器，不經過匯出請求：

| 格式                                            | 內容                           | 用途                                                               |
| --------------------------------------------- | ---------------------------- | ---------------------------------------------------------------- |
| <mark style="color:blue;">匯出 JSON</mark>      | 這筆紀錄的完整資料，含基本資訊、識別資訊、追蹤步驟與用量 | 交給工程師重現問題、匯入自己的分析工具                                              |
| <mark style="color:blue;">匯出 Markdown</mark>  | 同樣內容整理成可閱讀的 Markdown         | 貼進工單或會議紀錄                                                        |
| <mark style="color:blue;">匯出 Credit 稽核</mark> | 這筆回覆逐筆交易的 Credit 對照 Excel    | 對帳與稽核。此匯出是逐筆交易紀錄，不含「已透過 Prompt 快取節省」這類推導值；紀錄沒有 Credit 稽核資料時選項會停用 |

{% hint style="info" %}
要一次匯出多筆對話紀錄，請回到「<mark style="color:blue;">對話紀錄</mark>」列表用篩選條件後按「<mark style="color:blue;">匯出</mark>」，由 [匯出請求](/build/agent-ops/evaluations.md#export-requests) 在背景產生 Excel。
{% endhint %}

## 排查範例 <a href="#troubleshooting-examples" id="troubleshooting-examples"></a>

* **使用者抱怨「等很久才開始回」**：先看串流效能指標的 First Token From Request；再到執行時間軸找紅框瓶頸——若落在前處理的「等待附件」或「檢索」，問題在前置作業而非模型。
* **Agent 答錯但知識庫明明有資料**：展開 LLM 步驟的「分類」檢視，看<mark style="color:blue;">檢索結果</mark>有沒有撈到正確段落；沒有就回頭用 [搜尋測試](/build/knowledge-base/test-search-result.md) 調整知識庫，有撈到但答錯就修角色指令。
* **這一題怎麼花了這麼多 Credit**：看 LLM 呼叫明細的輪數與每輪輸入 Token；輪數多代表工具反覆呼叫，可檢查工具描述或限制最大迭代次數。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/build/agent-ops/evaluations/trace-timeline.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.