> 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.md).

# 自動評估與 Agent 監控

AgentOps 自動化測試與評測：以測試案例評估回應品質，透過 Agent 監控查看效能、成本與使用者讚／倒讚回饋。

## 自動評估 <a href="#auto-evaluation" id="auto-evaluation"></a>

自動評估功能讓您能夠使用預先建立的測試資料集，自動化測試 Agent 的回應品質。系統會將測試問題發送給 Agent，比對實際回應與預期回應，產生詳細的評估報告。

### 進入自動評估 <a href="#access-auto-evaluation" id="access-auto-evaluation"></a>

進入左側功能欄的「<mark style="color:blue;">AgentOps</mark>」，點選「<mark style="color:blue;">自動化測試</mark>」。

頁面顯示所有評估記錄，包含評測名稱、測試集、Agent、成功率、平均秒數與建立時間。

### 建立並執行測試 <a href="#create-and-run-test" id="create-and-run-test"></a>

1. 確認已建立測試資料集（參考 [測試資料集管理](/build/agent-ops/test-datasets.md)）
2. 點擊「<mark style="color:blue;">建立評估</mark>」按鈕
3. 填寫名稱、描述，選擇測試集、AI 助理與評測模型
4. 點擊「<mark style="color:blue;">確認</mark>」，系統會先跳出「<mark style="color:blue;">確認評測費用</mark>」視窗，列出這次評估的預估 Credits 與目前餘額
5. 確認無誤後點擊「<mark style="color:blue;">確認並開始評測</mark>」，系統會自動執行所有測試案例；要調整設定則點「<mark style="color:blue;">返回修改</mark>」

也可以透過 API 建立測試集、執行評估並讀取結果，例如在調整 Agent 設定後由您自己的系統自動重跑同一份測試集；端點、所需權限與 Credit 計算見 API 文件的[評估與測試集](https://docs.maiagent.ai/api/api-reference/ping-gu-he-ce-shi-ji)。

{% hint style="info" %}
評估執行時間取決於測試案例數量，通常 50 個測試案例約需 2-3 分鐘。
{% endhint %}

### 使用自訂評估指標 <a href="#custom-evaluation-metrics" id="custom-evaluation-metrics"></a>

除了內建指標，您也可以用自然語言定義團隊自己的評分準則。例如，客服主管小麥想確認客服助理是否保持禮貌且有同理心；她建立「客服語氣」指標、寫下判斷準則並設定通過門檻。評估完成後，她便能在結果中查看每個案例的「客服語氣」分數，找出需要調整的回覆。

{% stepper %}
{% step %}
建立評估時，完成名稱、測試集、Agent 及評測模型等基本設定。
{% endstep %}

{% step %}
在「<mark style="color:blue;">自訂指標</mark>」區域點選「<mark style="color:blue;">新增自訂指標</mark>」，輸入容易辨識的指標名稱與評估準則。
{% endstep %}

{% step %}
依團隊的品質標準調整通過門檻，再點選「<mark style="color:blue;">確認</mark>」，在費用確認視窗點「<mark style="color:blue;">確認並開始評測</mark>」開始評估。
{% endstep %}
{% endstepper %}

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-92abd700ffd6e9610bbafe2d50e8e347b29fc8e0%2Fevaluation-multi-turn-settings.png?alt=media" alt="建立評估視窗的多輪對話設定"><figcaption><p>切換至多輪對話後，可設定最大輪數、最少輪數、三種評估指標、模擬語言與自訂指標</p></figcaption></figure>

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-d56c6a2a2384f1f8aab3561aa424ae4364d3f37e%2Fevaluation-custom-metric.png?alt=media" alt="建立評估視窗中的自訂指標設定"><figcaption><p>以自然語言設定客服語氣的評估準則</p></figcaption></figure>

### 安全類指標 <a href="#safety-metrics" id="safety-metrics"></a>

建立單輪評估時，「<mark style="color:blue;">安全類指標</mark>」區提供四個選用的 guardrail 指標，適合金融、醫療等合規場景；分數方向一律「越高越好」（越高代表越沒有該類問題）：

| 指標                                      | 檢查什麼                  |
| --------------------------------------- | --------------------- |
| <mark style="color:blue;">PII 洩漏</mark> | 回覆是否洩漏個人識別資訊          |
| <mark style="color:blue;">角色違規</mark>   | 回覆是否偏離角色指令設定的身分與範圍    |
| <mark style="color:blue;">濫用</mark>     | 助理是否被用於非預期用途          |
| <mark style="color:blue;">避免專業建議</mark> | 回覆是否避免提供醫療、法律、金融等專業建議 |

{% hint style="info" %}
系統以不分英文大小寫的方式比對名稱：單輪評估的自訂指標不可與 15 個內建指標的英文名稱重複，多輪評估不可與 Turn Faithfulness、Turn Relevancy、Conversation Completeness 重複。內建指標清單見技術手冊的 [回覆評估與監測結果](https://docs.maiagent.ai/tech/advanced-genai-tech/evaluation#evaluation-metrics)。若名稱衝突，請改用能表達團隊判斷目的的名稱。
{% endhint %}

### 評估多輪對話 <a href="#multi-turn-evaluation" id="multi-turn-evaluation"></a>

多輪評估適合檢查需要來回確認的任務。以退貨客服為例，品質管理員小美希望 Agent 先詢問訂單編號，再確認退貨原因並說明後續安排；她建立多輪測試案例，寫下情境與預期結果後執行評估。完成後，她可展開對話逐字稿，檢查每一輪回覆與知識庫檢索內容，而不是只看最後一句答案。

{% stepper %}
{% step %}
先到「<mark style="color:blue;">測試集</mark>」開啟目標測試集，在多輪測試案例中新增情境、預期結果與模擬使用者人設。
{% endstep %}

{% step %}
回到「<mark style="color:blue;">自動化測試</mark>」並點選「<mark style="color:blue;">建立評估</mark>」，切換到「<mark style="color:blue;">多輪對話</mark>」。
{% endstep %}

{% step %}
選擇測試集、Agent 與評測模型，設定最大輪數、評估指標及模擬語言後開始評估。至少須啟用一項評估指標。若案例需要跨多輪持續守住某個條件（例如「全程不透露內部價格」），可另外設定 <mark style="color:blue;">最少輪數</mark>：即使預期結果已達成，模擬使用者仍會至少對話到這個輪數；最少輪數不可大於最大輪數。停止規則與預設值見下方 [設定最少輪數與最大輪數](#min-and-max-turns)。

評估執行時，Agent 為每個案例產生回答所用的模型 tokens 與檢索資源會依對話費率扣點，歸在該次評估底下，見 [Credits 計費制度](/others/credits.md#model-rates)。
{% endstep %}

{% step %}
評估完成後開啟結果，點選個別案例展開詳細內容，再查看各指標分數、對話逐字稿，以及每一輪的「<mark style="color:blue;">檢索內容</mark>」。單一案例失敗時，該案例會個別顯示錯誤，不會遮蔽其他案例的結果。
{% endstep %}
{% endstepper %}

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-123f84448a9ae205a2a7adcc1f96b8a63ceaf02d%2Fevaluation-multi-turn-results.png?alt=media" alt="已完成多輪評估展開案例後的指標、逐字稿與檢索內容"><figcaption><p>展開案例可逐輪核對 Agent 回覆與該輪取用的知識庫內容</p></figcaption></figure>

執行中的多輪評估若不需繼續，可在評估詳情點選「<mark style="color:blue;">取消評測</mark>」並確認。系統會在目前案例處理完畢後停止後續案例；已完成的分數與逐字稿仍會保留，狀態顯示為「<mark style="color:blue;">部分完成</mark>」，尚未處理的案例顯示為「<mark style="color:blue;">待評估</mark>」。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-926b7035060aac6e77573489d86fb8297fab864f%2Fevaluation-multi-turn-cancel.png?alt=media" alt="取消多輪評估後的部分完成狀態"><figcaption><p>取消後保留已完成案例，尚未處理的案例維持待評估</p></figcaption></figure>

#### 設定最少輪數與最大輪數 <a href="#min-and-max-turns" id="min-and-max-turns"></a>

多輪評估的一輪＝模擬使用者發話一次，加上 Agent 的一次回覆。<mark style="color:blue;">最大輪數</mark> 決定對話最多進行幾輪，<mark style="color:blue;">最少輪數</mark> 決定至少要進行幾輪，才可以因為「預期結果已達成」而結束。

以金融客服為例，品質管理員希望確認 Agent 在顧客換句話連續追問時，始終不透露內部優惠利率。若只用最大輪數，Agent 第 1 輪拒絕後，系統就可能判定「預期結果已達成」而結束，實際上只測到一輪。她在建立評估時把最大輪數設為 5、最少輪數設為 3；這個案例至少會進行 3 輪，Agent 必須連續三次守住，結果才有參考價值。

每位模擬使用者準備發話前，系統依下列順序判斷是否結束對話：

1. 已達最大輪數：結束。最大輪數永遠優先。
2. 尚未達最少輪數：繼續下一輪，這時不判斷預期結果。
3. 已達最少輪數：判斷預期結果，已達成就結束，未達成就繼續，直到最大輪數。

| 欄位                                    | 預設值 | 可設定範圍          |
| ------------------------------------- | --- | -------------- |
| <mark style="color:blue;">最大輪數</mark> | 6   | 2–10           |
| <mark style="color:blue;">最少輪數</mark> | 1   | 1 以上，且不可大於最大輪數 |

最少輪數維持預設值 1 時，和這個欄位推出前一樣：從第一輪起，預期結果一達成就結束。若希望每個案例都固定跑滿，把最少輪數設成與最大輪數相同即可。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-638d0e5a055294731944fbc384d80feffa7eb098%2Fevaluation-multi-turn-min-turns-default.png?alt=media" alt="建立評估視窗中，最大輪數為 6、最少輪數為 1 的預設設定"><figcaption><p>切換到多輪對話後，最少輪數欄位位於最大輪數下方，預設值為 1</p></figcaption></figure>

若最少輪數大於最大輪數，欄位下方會顯示「<mark style="color:blue;">最少輪數不可大於最大輪數</mark>」。這時點選「<mark style="color:blue;">確認</mark>」會跳出同樣的錯誤訊息，不會建立評估。輸入框只接受範圍內的整數，超出範圍的數字會自動調回可接受的上下限。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-f66597e00ea9f6531e7f7de6f480b53dc0263f7f%2Fevaluation-multi-turn-min-turns-invalid.png?alt=media" alt="最大輪數 3、最少輪數 5 時，最少輪數欄位顯示紅色錯誤訊息"><figcaption><p>最少輪數 5 大於最大輪數 3，無法送出</p></figcaption></figure>

評估建立後，多輪評估詳情頁上方會同時顯示這次使用的最大輪數與最少輪數。這個欄位推出前建立的評估，最少輪數顯示為 1。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-c6aeb466ca382618ad29f28ffb3f2d968f9101e3%2Fevaluation-multi-turn-min-turns-detail.png?alt=media" alt="多輪評估詳情頁顯示最大輪數 2 與最少輪數 1"><figcaption><p>詳情頁的統計卡列出本次評估的最大輪數與最少輪數</p></figcaption></figure>

{% hint style="info" %}
預期結果達成後，模擬使用者仍會依最少輪數繼續發話。「連續施壓下守住條件」這類案例適合設高一點；依序完成固定步驟的案例（例如逐題填完問卷），最少輪數設太高可能產生與任務無關的閒聊輪次，建議設成完成任務所需的輪數即可。
{% endhint %}

### 查看評估結果 <a href="#view-evaluation-results" id="view-evaluation-results"></a>

在評估記錄該列的「<mark style="color:blue;">操作</mark>」欄點第一個（文件）圖示，即可查看詳細報告。詳細報告包含：

* **成功率**：通過測試的案例百分比（標記為不穩定的測資不計入，見 [標記不穩定的測資](/build/agent-ops/test-datasets.md#flaky-test-cases)）
* **AI 洞察**：系統自動分析的評估摘要與改進建議
* **指標統計**：品質性評分、回答相關性等指標
* <mark style="color:blue;">**AI 助理設定(本次評測)**</mark>：這次評測執行時 Agent 的設定快照（模型、回答模式、角色指令、知識庫、工具設定等），點「<mark style="color:blue;">檢視配置詳情</mark>」展開。之後即使改了 Agent 設定，這裡仍保留當時的版本，方便比對「改了什麼之後分數變了」
* **測試案例明細**：每個問題的預期回應、實際回應、評分與狀態

#### 取消、繼續與匯出 <a href="#cancel-resume-export" id="cancel-resume-export"></a>

* <mark style="color:blue;">**取消評測**</mark>：執行中的評測可取消，系統會在目前批次完成後停止，以「部分完成」結束；已計算的分數保留，剩餘案例不執行。
* <mark style="color:blue;">**繼續評測**</mark>：評測狀態為「部分完成」時，可按「繼續評測」重新執行**發生錯誤**與**尚未執行**的測試案例（例如評估中途取消後沒跑到的案例）；已完成的案例保留、不重跑，也只對新完成的案例計費。
* <mark style="color:blue;">**匯出報告**</mark>：評測完成後才能匯出。按下後會建立匯出請求在背景產生 Excel，完成時頁面會提示「匯出請求已完成，可以下載檔案了」，按鈕改為顯示「<mark style="color:blue;">下載報告</mark>」。評估報告不會列在 AgentOps 的 [匯出請求](#export-requests) 頁，請在評估詳情頁下載。報告包含「建議與洞察」工作表。

**成功率參考基準：**

| Agent 類型 | 建議成功率 |
| -------- | ----- |
| 產品查詢助理   | ≥ 95% |
| 客服支援助理   | ≥ 90% |
| 通用對話助理   | ≥ 80% |

{% hint style="info" %}
更多關於洞察報告的說明，請參考：[評估洞察報告](/build/agent-ops/evaluation-insights.md)
{% endhint %}

### 管理評估記錄 <a href="#manage-evaluation-records" id="manage-evaluation-records"></a>

* **搜尋與篩選**：依測試集、Agent 或關鍵字篩選記錄
* **重新評估**：修改知識庫或 AI 設定後，用同一份測試集再建立一次評估，比對改善效果（列表沒有一鍵重跑的按鈕）
* **匯出**：將評估結果匯出為 Excel 格式

#### 編輯評測名稱與描述 <a href="#edit-evaluation-name-description" id="edit-evaluation-name-description"></a>

完成測試後，您仍可修改評測名稱與描述，不必刪除或重新執行測試。測試資料集、Agent、評測結果與執行狀態不會因此改變。

例如，小麥建立每週客服品質測試後，發現評測名稱的週次寫錯。她從自動化測試列表開啟編輯視窗，更正名稱並補上測試目的；儲存後，列表立即顯示新內容，原有的測試結果仍保留。

{% stepper %}
{% step %}

### 開啟自動化測試列表

進入左側選單「<mark style="color:blue;">AgentOps</mark>」→「<mark style="color:blue;">自動化測試</mark>」。
{% endstep %}

{% step %}

### 開啟編輯視窗

找到要調整的評測，在該列的「<mark style="color:blue;">操作</mark>」欄點擊「<mark style="color:blue;">編輯</mark>」圖示。
{% endstep %}

{% step %}

### 修改並儲存

修改「<mark style="color:blue;">評測名稱</mark>」或「<mark style="color:blue;">描述</mark>」，再點擊「<mark style="color:blue;">確定</mark>」。評測名稱為必填，最多 200 個字元；描述可以留空。
{% endstep %}
{% endstepper %}

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-70248a3c57f79ffa643153dad76b27d464f20916%2Fgap-agentops-edit-evaluation.png?alt=media" alt="自動化測試列表的編輯測試視窗，可修改評測名稱與描述"><figcaption><p>編輯視窗會帶入目前的評測名稱與描述</p></figcaption></figure>

{% hint style="info" %}
執行中、已完成或失敗的評測都可以修改名稱與描述；這項操作只更新辨識用資訊，不會重新執行測試。
{% endhint %}

***

## Agent 監控 <a href="#ai-agent-monitoring" id="ai-agent-monitoring"></a>

網頁語音與電話的紀錄、逐字稿與逐輪延遲，請見[語音對話紀錄與延遲分析](/build/agent-ops/evaluations/voice-monitoring.md)。

Agent 監控提供即時的對話運作數據，讓您深入了解每一次對話的處理細節、效能指標與品質評分。

### 進入 Agent 監控 <a href="#access-ai-agent-monitoring" id="access-ai-agent-monitoring"></a>

進入左側功能欄的「<mark style="color:blue;">AgentOps</mark>」，點選「<mark style="color:blue;">AI 助理監控</mark>」。

### 監控欄位說明 <a href="#monitoring-field-descriptions" id="monitoring-field-descriptions"></a>

「<mark style="color:blue;">文字對話紀錄</mark>」分頁的列表預設顯示下列欄位：

| 欄位       | 說明                                                                                                    |
| -------- | ----------------------------------------------------------------------------------------------------- |
| 用戶輸入訊息   | 使用者發送給 AI 的問題                                                                                         |
| 輸出訊息     | Agent 的回應內容                                                                                           |
| AI 助理    | 處理此對話的 Agent 名稱                                                                                       |
| 來源       | 這筆紀錄是<mark style="color:blue;">互動對話</mark>（使用者實際發問）還是<mark style="color:blue;">排程執行</mark>（由代理排程自動觸發） |
| 使用者反饋    | 讚 👍 或倒讚 👎                                                                                           |
| 品質評分     | 以忠實性評分作為代表分；滑鼠移到分數上，可看忠實性、回答正確性、回答相關性、回答相似度、上下文精確度、上下文召回率等子指標                                         |
| Token 用量 | 這次回覆消耗的 LLM 與向量化 Token 總數                                                                             |
| 額度消耗     | 這次回覆消耗的 Credits                                                                                       |
| 處理時間     | 完整回覆耗時；滑鼠移到時間上，可看附件處理、向量化、重排序、AI 模型推理與系統開銷各花多久                                                        |
| 建立時間     | 這筆紀錄的建立時間                                                                                             |
| 成員       | 以組織成員身分發起這筆對話的人；沒有對應成員（例如排程執行）時顯示「—」                                                                  |

ID、修飾輸入訊息、使用字數、LLM、錯誤類型與用戶等欄位預設隱藏，可用列表右上角的齒輪圖示叫出。

#### 品質分數怎麼算 <a href="#quality-score-calculation" id="quality-score-calculation"></a>

忠實性評分、回答相關性評分與上下文精確度評分都由評測模型（LLM）依 DeepEval 的 Faithfulness、Answer Relevancy、Contextual Precision 指標判斷，範圍 0～1，不是關鍵字比對：忠實性看回覆中的陳述有多少能在檢索到的段落找到依據；回答相關性看回覆有多少內容切中使用者的問題；上下文精確度看檢索到的段落與問題的相關程度。評測模型逐句判斷，同一則回覆重跑可能有小幅差異。各指標的定義、分數方向與分數偏低時的排查方向，見技術手冊的 [回覆評估與監測結果](https://docs.maiagent.ai/tech/advanced-genai-tech/evaluation)。

點每一筆最右側「<mark style="color:blue;">操作</mark>」欄的「<mark style="color:blue;">詳情</mark>」圖示進入對話詳情頁，可看到這次回覆的執行時間軸（每一步耗時、Token、Credit 與瓶頸）、送給模型的完整對話紀錄、用量與效能面板，並可匯出 JSON／Markdown／Credit 稽核，見 [對話詳情與執行時間軸](/build/agent-ops/evaluations/trace-timeline.md)。

### 查看圖片搜尋的用量 <a href="#view-image-search-usage" id="view-image-search-usage"></a>

Agent 使用知識庫的圖片搜尋時，系統會另外記錄圖片向量化的用量。您可以從單筆對話記錄確認這次回覆用了哪些資源：

{% stepper %}
{% step %}
進入 <mark style="color:blue;">AgentOps</mark> → <mark style="color:blue;">AI 助理監控</mark>，切換到 <mark style="color:blue;">文字對話紀錄</mark>。
{% endstep %}

{% step %}
找到要核對的回覆，點選最右側的<mark style="color:blue;">詳情</mark>圖示。
{% endstep %}

{% step %}
往下查看 Token 與 Credit 明細。一般文字向量化會列在 <mark style="color:blue;">向量化</mark>；該回覆有使用圖片搜尋時，會再顯示 <mark style="color:blue;">圖片向量化</mark>，Token 總計與 Credit 總計也會包含這一項。其他欄位的說明見 [用量與效能面板](/build/agent-ops/evaluations/trace-timeline.md#usage-panels)。
{% endstep %}
{% endstepper %}

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-85207671ac13857484431a19afc621223e83dadc%2Fgap-agentops-image-embedding.png?alt=media" alt="Agent 監控的單筆對話用量與 Credit 明細"><figcaption><p>單筆對話的用量明細；只有實際使用圖片搜尋的回覆才會顯示「圖片向量化」</p></figcaption></figure>

{% hint style="info" %}
看不到 <mark style="color:blue;">圖片向量化</mark> 不代表記錄遺失。這個項目只在該次回覆實際產生圖片向量化用量時顯示；沒有使用圖片搜尋時，畫面會維持原本的向量化明細。
{% endhint %}

例如，小麥公司的客服主管讓商品 Agent 從型錄圖片辨識零件外觀。她在測試後打開這筆對話的詳細資料，看到圖片向量化與對應 Credits，便能區分圖片搜尋和一般文字檢索的成本，再決定是否調整圖片型錄或 Agent 設定。

### 搜尋與篩選 <a href="#search-and-filter" id="search-and-filter"></a>

文字對話紀錄上方的篩選列可用的欄位：

| 欄位                                     | 說明                                                                                                                   | 預設顯示 |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ---- |
| <mark style="color:blue;">日期範圍</mark>  | 近 24 小時、近 7 天、近 30 天、近 90 天或<mark style="color:blue;">自訂區間</mark>                                                    | 是    |
| <mark style="color:blue;">關鍵詞</mark>   | 搜尋使用者輸入訊息與 Agent 回覆內容                                                                                                | 是    |
| <mark style="color:blue;">AI 助理</mark> | 選擇特定 Agent，追蹤其運作狀況                                                                                                   | 是    |
| <mark style="color:blue;">工具</mark>    | 只看呼叫過特定工具的問答，工具執行失敗也算；見[依使用工具篩選對話紀錄](#filter-by-tool)                                                                | 否    |
| <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>  | 指定錯誤類型（與[錯誤率怎麼計算](#error-rate-calculation)的分類相同）                                                                     | 否    |
| <mark style="color:blue;">評價</mark>    | 依使用者回饋篩選：<mark style="color:blue;">讚</mark>、<mark style="color:blue;">倒讚</mark>、<mark style="color:blue;">無評價</mark> | 否    |

#### 自訂篩選欄位 <a href="#customize-filter-fields" id="customize-filter-fields"></a>

篩選列右側的漏斗圖示 「<mark style="color:blue;">自訂篩選欄位</mark>」 可勾選要顯示哪些欄位（「顯示篩選欄位」清單），不常用的收起來讓畫面簡潔；按 「<mark style="color:blue;">恢復預設</mark>」 回到上表的預設組合。設定存在您的瀏覽器，其他成員不受影響。<mark style="color:blue;">重置篩選</mark> 只清掉目前填的條件，不改變顯示哪些欄位。

<mark style="color:blue;">匯出</mark> 會依目前篩選條件建立匯出請求（Excel 或 CSV），見[匯出請求](#export-requests)；匯出只支援互動對話，來源選了排程執行時會提示先清除來源篩選。

### 依成員與來源篩選對話紀錄 <a href="#filter-by-member-and-source" id="filter-by-member-and-source"></a>

<mark style="color:blue;">文字對話紀錄</mark>可用<mark style="color:blue;">來源</mark>與<mark style="color:blue;">成員</mark>兩個篩選欄位（預設收起，先在 [自訂篩選欄位](#customize-filter-fields) 勾選），列表中也有對應的<mark style="color:blue;">來源</mark>與<mark style="color:blue;">成員</mark>欄位，方便您分開檢視「誰問的」以及「是人問的還是排程自動跑的」。

例如，客服主管想了解新進同事這幾週都怎麼使用內部 Agent。她進入文字對話紀錄，把<mark style="color:blue;">來源</mark>設為<mark style="color:blue;">互動對話</mark>，排除排程自動產生的紀錄，再從<mark style="color:blue;">全部成員</mark>選出這位同事，列表只剩他的對話；確認內容後按下<mark style="color:blue;">匯出</mark>，就能把同一份清單交給教育訓練窗口，不需要請工程師撈資料。

#### 1. 依成員篩選 <a href="#filter-by-member" id="filter-by-member"></a>

進入 <mark style="color:blue;">AgentOps</mark> → <mark style="color:blue;">AI 助理監控</mark>，切換到<mark style="color:blue;">文字對話紀錄</mark>，在 [自訂篩選欄位](#customize-filter-fields) 勾選<mark style="color:blue;">成員</mark>後，點選<mark style="color:blue;">全部成員</mark>，從清單中勾選要檢視的成員（可複選、可輸入關鍵字搜尋）。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-33bb6d331b3f178a4edd1be5aff3612384a07697%2Fagentops-records-member-filter.png?alt=media" alt="對話紀錄篩選列展開成員下拉選單"><figcaption><p>從「全部成員」下拉選單挑選要檢視的成員（成員姓名與 Email 已遮蔽）</p></figcaption></figure>

選定後，列表只顯示這些成員發起的對話，並可與關鍵字、Agent、錯誤狀態、日期等其他篩選條件疊加。表格右側的<mark style="color:blue;">成員</mark>欄會顯示每筆紀錄對應的成員。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-a8a097caa9ac5aef1c80a74873f7444e9a6db8f8%2Fagentops-records-member-column.png?alt=media" alt="依成員篩選後的對話紀錄列表與成員欄"><figcaption><p>篩選一位成員後的對話紀錄，右側「成員」欄顯示對應成員（已遮蔽）</p></figcaption></figure>

#### 2. 依來源篩選排程執行 <a href="#filter-scheduled-runs" id="filter-scheduled-runs"></a>

透過<mark style="color:blue;">代理排程</mark>自動執行的任務，也會出現在文字對話紀錄中，並在<mark style="color:blue;">來源</mark>欄標示為<mark style="color:blue;">排程執行</mark>；一般使用者發問的紀錄則標示為<mark style="color:blue;">互動對話</mark>。在 [自訂篩選欄位](#customize-filter-fields) 勾選<mark style="color:blue;">來源</mark>後，點選<mark style="color:blue;">全部來源</mark>，可只看其中一種。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-0d649032c0cf8cb9e3979e8b2a9ad6204a0b1f8b%2Fagentops-records-scheduled-filter.png?alt=media" alt="來源篩選為排程執行時的對話紀錄"><figcaption><p>來源選擇「排程執行」後，成員篩選與匯出按鈕變為不可用，滑鼠移到匯出按鈕會顯示原因</p></figcaption></figure>

{% hint style="info" %}
**選擇「排程執行」時的限制**

* 排程執行沒有對應的成員與使用者回饋，因此<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>查看。
  {% endhint %}

點選排程執行紀錄的<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;">排程 ID</mark>，方便回頭對照是哪一個排程產生的。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-c2463bbc35f85580d016676cd78243c9c913e5ff%2Fagentops-records-scheduled-detail.png?alt=media" alt="排程執行紀錄的對話詳情基本資訊"><figcaption><p>排程執行紀錄的基本資訊：排程名稱、來源「排程執行」與狀態「成功」</p></figcaption></figure>

#### 3. 從倒讚回饋整理改善清單 <a href="#triage-downvotes" id="triage-downvotes"></a>

把 <mark style="color:blue;">評價</mark> 篩選設為 <mark style="color:blue;">倒讚</mark>（這個欄位預設收起，先在 [自訂篩選欄位](#customize-filter-fields) 勾選），列表就只剩使用者按過倒讚的回覆。逐筆點 <mark style="color:blue;">詳情</mark> 查看 Agent 當時檢索到的段落與執行過程；使用者倒讚時勾選的原因與補充文字，在 [所有對話的對話檢視器](/serve/daily-operations/reply/conversation-viewer.md#user-feedback) 逐則查看。判斷是知識庫缺資料、角色指令不夠明確，還是檢索沒找到正確段落：知識庫缺資料的，直接從對話紀錄 [加入 FAQ](/build/agent-ops/add-to-faq.md)；其他的回到 Agent 設定調整後，用 [自動評估](#auto-evaluation) 重跑測試集確認。

對話紀錄沒有「待處理」或「負責人」欄位；需要多人分工追蹤時，按 <mark style="color:blue;">匯出</mark> 把篩選結果匯成 Excel 當作改善清單。

### 依使用工具篩選對話紀錄 <a href="#filter-by-tool" id="filter-by-tool"></a>

<mark style="color:blue;">文字對話紀錄</mark>可以只列出呼叫過某個工具的問答，例如組織自建的 API 工具，或 Tavily Web Search 這類平台內建工具。篩選結果可以再和日期、Agent、評價等條件疊加，按下<mark style="color:blue;">匯出</mark>後，Excel 會多一欄記錄每筆問答用了哪些工具、執行成功或失敗。

例如，客服主管發現有客戶反映「查不到訂單」。她在文字對話紀錄叫出<mark style="color:blue;">工具</mark>篩選，選擇訂單查詢工具，列表就只剩 Agent 呼叫過這個工具的問答；接著按<mark style="color:blue;">匯出</mark>，在 Excel 的<mark style="color:blue;">使用工具（執行結果）</mark>欄篩出標示「失敗」的列，就能整理出要請工程師排查的對話，不需要逐筆點開詳情。

{% stepper %}
{% step %}

### 叫出工具篩選 <a href="#show-tool-filter" id="show-tool-filter"></a>

進入 <mark style="color:blue;">AgentOps</mark> → <mark style="color:blue;">AI 助理監控</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>下拉選單。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-243ce04b3e1e1fd21b437e2ccc27bdd22bd78780%2Fagentops-records-tool-filter-field.png?alt=media" alt="自訂篩選欄位清單中勾選工具，篩選列出現全部工具下拉選單"><figcaption><p>在「顯示篩選欄位」勾選「工具」後，篩選列多出「全部工具」</p></figcaption></figure>
{% endstep %}

{% step %}

### 選擇要篩選的工具 <a href="#select-tool" id="select-tool"></a>

點選<mark style="color:blue;">全部工具</mark>，從清單選一個工具，也可以輸入名稱關鍵字搜尋。清單列出組織內的工具與平台內建工具，一次選一個。選定後列表立即更新，只顯示這次回覆呼叫過該工具的問答；同一則回覆呼叫多次也只列一筆。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-1d9b44db2774cda8c9fd964609fd9b2bbe5a8885%2Fagentops-records-tool-filter-result.png?alt=media" alt="工具篩選選定一個訂單查詢工具後的對話紀錄列表"><figcaption><p>選定工具後，列表只剩呼叫過這個工具的問答，下方顯示符合的筆數</p></figcaption></figure>
{% endstep %}

{% step %}

### 匯出並查看工具執行結果 <a href="#export-tool-usage" id="export-tool-usage"></a>

按<mark style="color:blue;">匯出</mark>，匯出檔會套用目前的工具篩選，到 [匯出請求](#export-requests) 下載。Excel 最後一欄是<mark style="color:blue;">使用工具（執行結果）</mark>，格式如「訂單查詢（成功）、Tavily Web Search（失敗）」：

* 依這次回覆第一次呼叫的順序列出，同一個工具呼叫多次只列一次，其中任一次成功就標示「成功」。
* 尚未完成或逾時的呼叫算「失敗」。
* 工具名稱以呼叫當時記下的名稱為準，之後改名不影響已發生的紀錄；較早、沒有記下名稱的紀錄會顯示工具目前的名稱。工具刪除後，舊紀錄若沒有保存當時的名稱，會顯示「已刪除工具」。
* 這次回覆沒有呼叫任何工具時，該欄留白。
  {% endstep %}
  {% endstepper %}

{% hint style="info" %}

* 已刪除的工具不會出現在<mark style="color:blue;">全部工具</mark>清單中，但匯出檔仍會保留它過去的呼叫紀錄。
* 按<mark style="color:blue;">重置篩選</mark>，或在「<mark style="color:blue;">自訂篩選欄位</mark>」取消勾選<mark style="color:blue;">工具</mark>，都會清除目前選的工具。
* 列表包含排程執行，匯出只含互動對話；排程執行也呼叫過該工具時，列表筆數會多於匯出筆數。
  {% endhint %}

### 查看 MaiGPT 對話 <a href="#view-maigpt-conversations" id="view-maigpt-conversations"></a>

成員在 MaiGPT 的提問與 AI 回覆，也會記錄在 <mark style="color:blue;">AI 助理監控</mark> 的 <mark style="color:blue;">文字對話紀錄</mark> 中，<mark style="color:blue;">AI 助理</mark> 欄顯示為 MaiGPT。管理員要了解某位成員怎麼使用 MaiGPT 時，用成員篩選就能找到他的對話。

#### 誰看得到成員的 MaiGPT 對話 <a href="#maigpt-conversations-permissions" id="maigpt-conversations-permissions"></a>

| 身分                                                | 能否在對話紀錄看到成員的 MaiGPT 對話                          |
| ------------------------------------------------- | ----------------------------------------------- |
| 組織擁有者                                             | 看得到，組織擁有者可以看到組織內所有對話紀錄                          |
| 所屬角色有 <mark style="color:blue;">AI 助理監控權限</mark>  | 看得到                                             |
| 所屬角色沒有 <mark style="color:blue;">AI 助理監控權限</mark> | 進不了 <mark style="color:blue;">AI 助理監控</mark> 頁面 |

<mark style="color:blue;">AI 助理監控權限</mark> 位於角色權限的 <mark style="color:blue;">AgentOps 權限</mark> 底下。非擁有者在對話紀錄中，看得到「分配給所屬角色的 Agent」的紀錄；系統建立 MaiGPT 時就會把它分配給預設角色，而所有成員都屬於預設角色，所以擁有 <mark style="color:blue;">AI 助理監控權限</mark> 的成員都看得到 MaiGPT 對話。所屬角色有 <mark style="color:blue;">MaiGPT 權限</mark> 時同樣看得到。設定方式見 [角色權限管理](/org/roles/role-permission.md)。

#### 查看步驟 <a href="#view-maigpt-conversations-steps" id="view-maigpt-conversations-steps"></a>

{% stepper %}
{% step %}
進入 <mark style="color:blue;">AgentOps</mark> → <mark style="color:blue;">AI 助理監控</mark>，切換到 <mark style="color:blue;">文字對話紀錄</mark>。
{% endstep %}

{% step %}
在 [自訂篩選欄位](#customize-filter-fields) 勾選 <mark style="color:blue;">成員</mark>，點選 <mark style="color:blue;">全部成員</mark>，勾選要查看的成員（可複選、可輸入關鍵字搜尋）。需要時同樣叫出 <mark style="color:blue;">來源</mark> 並設為 <mark style="color:blue;">互動對話</mark>，並調整時間範圍；篩選列預設只顯示 <mark style="color:blue;">近 90 天</mark> 的紀錄。
{% endstep %}

{% step %}
在列表中找 <mark style="color:blue;">AI 助理</mark> 欄為 MaiGPT 的紀錄，點最右側的 <mark style="color:blue;">詳情</mark> 查看完整的提問與回覆。
{% endstep %}
{% endstepper %}

{% hint style="info" %} <mark style="color:blue;">全部助理</mark> 下拉選單不會列出 MaiGPT，請改用成員篩選，再從 <mark style="color:blue;">AI 助理</mark> 欄辨認 MaiGPT 的紀錄。需要整理成清單時，可以按 <mark style="color:blue;">匯出</mark>，匯出檔會套用目前的篩選條件。
{% endhint %}

成員端的隱私說明見 [MaiGPT 安全性與隱私](/work/maigpt/faq/security.md#admin-access-to-chat)。

### 匯出請求 <a href="#export-requests" id="export-requests"></a>

在<mark style="color:blue;">文字對話紀錄</mark>按下<mark style="color:blue;">匯出</mark>後，系統會依目前的篩選條件（包含成員、來源與工具）在背景產生 Excel，並顯示「匯出請求已建立，正在處理中...」。到左側功能欄的 <mark style="color:blue;">AgentOps</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>欄下載。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-f417d42249de3cc61fd2e3255da547a9a669a793%2Fagentops-export-requests-user.png?alt=media" alt="匯出請求列表，含使用者欄"><figcaption><p>匯出請求列表：可看到狀態、發起匯出的使用者（已遮蔽）、記錄數與檔案大小</p></figcaption></figure>

{% hint style="info" %}
多位管理者共用同一個組織時，可從<mark style="color:blue;">使用者</mark>欄分辨每份匯出檔是誰建立的，再決定要下載或刪除哪一份。
{% endhint %}

### 儀表板指標與錯誤率 <a href="#dashboard-metrics" id="dashboard-metrics"></a>

切換到「<mark style="color:blue;">儀表板</mark>」分頁，上方「<mark style="color:blue;">概況</mark>」分成<mark style="color:blue;">文字助理</mark>與<mark style="color:blue;">語音助理</mark>兩張卡。文字助理卡列出下列指標，並附上與前一個相同長度區間（vs 上期）的變化率；卡片下方另有區間內的 <mark style="color:blue;">Credit 消耗</mark> 與助理數，點「<mark style="color:blue;">查看紀錄</mark>」可直接跳到文字對話紀錄：

| 指標      | 說明                                                                   |
| ------- | -------------------------------------------------------------------- |
| 對話數     | 區間內 Agent**回覆的次數**。同一個對話有幾輪 AI 回覆就計幾次；由真人客服接手回覆、排程自動執行的不計入（定義詳見下方說明） |
| 錯誤率     | 發生系統錯誤的回覆比例（計算方式見下）                                                  |
| 平均回應時間  | 從收到訊息到回覆完成的平均時間                                                      |
| 平均 TTFT | 使用者送出訊息到看到第一個字的平均時間                                                  |

篩選列可選日期區間、<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>為粒度。儀表板只統計互動對話，排程執行請到「文字對話紀錄」查看。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-c25472c7f3765cfc8f340690d9ec7776e240797a%2Fagentops-dashboard-metrics.png?alt=media" alt="Agent 監控儀表板的篩選列與概況卡"><figcaption><p>儀表板篩選列與概況：文字助理卡顯示對話數、錯誤率、平均回應時間、平均 TTFT 與 Credit 消耗</p></figcaption></figure>

#### 儀表板圖表 <a href="#dashboard-charts" id="dashboard-charts"></a>

概況下方的「<mark style="color:blue;">詳細分析</mark>」切到<mark style="color:blue;">文字助理</mark>時，會顯示下列圖表，點圖例可切換該系列的顯示：

| 圖表                                       | 看什麼                                                                                                                                                                                                                                                                                                  |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 對話量趨勢                                    | 區間內 Agent 回覆次數的變化                                                                                                                                                                                                                                                                                    |
| 回應時間趨勢                                   | 回覆時間的平均值（Reply AVG）、P95 與 LLM 平均推理時間（LLM AVG）的變化                                                                                                                                                                                                                                                     |
| 錯誤率趨勢                                    | 整體錯誤率的變化（計算方式見下方）                                                                                                                                                                                                                                                                                    |
| <mark style="color:blue;">錯誤率分類趨勢</mark> | 把錯誤拆成 <mark style="color:blue;">Timeout</mark>、<mark style="color:blue;">LLM</mark>、<mark style="color:blue;">System</mark>、<mark style="color:blue;">Tool Failure</mark>、<mark style="color:blue;">Other</mark> 五類各自的趨勢。System 代表設定錯誤（例如模型或金鑰設定有問題）；模型串流中斷歸為 Timeout；使用者主動中斷（Client Interrupt）不計入錯誤 |
| <mark style="color:blue;">串流效能指標</mark>  | 左軸 <mark style="color:blue;">TTFT</mark>（送出訊息到第一個字的時間）、右軸 <mark style="color:blue;">TPS</mark>（每秒生成 Token 數）。TTFT 升高代表前置作業或模型啟動變慢，TPS 下降代表生成變慢                                                                                                                                                       |
| <mark style="color:blue;">回答品質分數</mark>  | 區間內 <mark style="color:blue;">Faithfulness</mark>（忠實性）與 <mark style="color:blue;">Relevancy</mark>（回答相關性）的平均分數，範圍 0～1；只有開啟自動評估的 Agent 才有資料，見 [AI 客服品質管理](/serve/ai-quality-guide.md)                                                                                                                 |
| LLM 模型分布                                 | 各模型的回覆占比                                                                                                                                                                                                                                                                                             |
| 助理服務排名                                   | 比較各 Agent 的對話數、錯誤率、平均回應時間、平均 TTFT 與 TPS，點欄位標題可排序                                                                                                                                                                                                                                                     |

單一 Agent 的同一組圖表，在該 Agent 設定頁的「<mark style="color:blue;">使用分析</mark>」→「<mark style="color:blue;">監控指標</mark>」也看得到（需 AI 助理監控權限）。

#### 對話數怎麼計算 <a href="#conversation-count-definition" id="conversation-count-definition"></a>

儀表板的「對話數」與「對話量趨勢」是以 **Agent 每一次回覆** 為單位，不是以「開了幾個對話」為單位：

| 情境                       | 是否計入 | 計入數量 |
| ------------------------ | ---- | ---- |
| 使用者進入服務，但沒有送出訊息          | 不計   | 0    |
| 使用者送出 1 則訊息，AI 回覆 1 次    | 計    | 1    |
| 同一個對話中使用者問 5 次，AI 回覆 5 次 | 計    | 5    |
| 使用者送出訊息，但由真人客服接手回覆       | 不計   | 0    |
| 使用者送出訊息，AI 回覆時發生錯誤       | 計    | 1    |
| 排程自動執行的任務                | 不計   | 0    |

{% hint style="info" %}
若要看「有多少個對話被開啟」，請改看 Agent「使用分析」分頁的「對話次數」：使用者送出第一則訊息即計 1，同一個對話不論幾輪只算 1，真人客服接手的對話也會計入。兩個數字的定義不同，一般情況下儀表板的「對話數」會大於「使用分析」的「對話次數」。詳見 [使用分析](/build/agent/usage.md#conversations-count)。
{% endhint %}

#### 錯誤率怎麼計算 <a href="#error-rate-calculation" id="error-rate-calculation"></a>

> 錯誤率 ＝ 發生系統錯誤的回覆筆數 ÷ 總回覆筆數 × 100%

只有**系統層**的錯誤才會計入（例如模型呼叫失敗、逾時）。以下情況**不列入**錯誤，避免高估：

* 使用者主動中斷回覆（Client Interrupt）
* 內容防護機制（Hook）的正常攔截

{% hint style="info" %}
錯誤率是「服務穩定度」指標，不是答題品質分數。錯誤率異常升高時，建議進入該 Agent 的對話紀錄查明原因（例如模型異常、外部工具串接失敗）；若要評估「回答得好不好」，請搭配品質評分（忠實性／回答相關性）與使用者的讚／倒讚回饋一起檢視。
{% endhint %}

### 監控最佳實踐 <a href="#monitoring-best-practices" id="monitoring-best-practices"></a>

**每日檢視**：查看最近 24 小時的對話，識別異常的回應時間或錯誤

**識別效能瓶頸**：

* 回覆時間 > 10 秒：檢查知識庫檢索效率或考慮更快的 LLM
* Token 用量過高：評估是否可縮短 System Prompt 或對話歷史

**品質問題追蹤**：

1. 使用關鍵字搜尋找到問題對話
2. 分析根本原因（知識庫不足 / AI 理解錯誤 / 模型限制）
3. 將問題案例加入測試資料集，執行自動評估驗證修復

***

## 常見問題 <a href="#faq" id="faq"></a>

### Q：自動評估與 Agent 監控有什麼不同？ <a href="#faq-evaluation-vs-monitoring" id="faq-evaluation-vs-monitoring"></a>

|      | 自動評估      | Agent 監控   |
| ---- | --------- | ---------- |
| 用途   | 定期品質測試    | 即時運作監控     |
| 資料來源 | 預設的測試資料集  | 實際用戶對話     |
| 主要指標 | 成功率、回應時間  | 效能、成本、品質評分 |
| 適合對象 | 品質驗證、回歸測試 | 日常監控、問題排查  |

### Q：多久執行一次評估？ <a href="#faq-how-often-to-evaluate" id="faq-how-often-to-evaluate"></a>

建議：核心功能每週一次、完整測試每月一次、重大更新後立即執行。

後台沒有定期自動重跑測試集的排程設定，每次評估都由您手動在 <mark style="color:blue;">確認評測費用</mark> 視窗按 <mark style="color:blue;">確認並開始評測</mark> 啟動；需要定期重跑時，可以由您自己的排程呼叫 [執行單輪評估 API](https://docs.maiagent.ai/api/api-reference/ping-gu-he-ce-shi-ji#evaluations-evaluate-create)。Agent 進階設定裡的 <mark style="color:blue;">開啟自動評估</mark> 是另一回事：開啟後每一則實際對話都會即時評分，結果顯示在 Agent 監控（見 [AI 客服品質管理](/serve/ai-quality-guide.md)），不是定期執行測試集。

### Q：評估會影響實際用戶嗎？ <a href="#faq-evaluation-impact-on-users" id="faq-evaluation-impact-on-users"></a>

不會。自動評估使用獨立環境，不會干擾實際用戶的對話。

### Q：使用者看到「無法生成回應，請稍後再試。」是什麼意思？ <a href="#faq-unable-to-generate-response" id="faq-unable-to-generate-response"></a>

這是回覆流程發生系統層錯誤時給使用者的通用訊息，例如模型呼叫失敗、圖片或文字處理失敗、範本與混合模式處理失敗。它不是額度用完（額度用完顯示對話平台設定的 [額度用完提示訊息](/build/conversation-settings/platform-settings/interaction-settings.md#quota-exhausted-message)），也不是 Hook 攔截（顯示 Hook 設定的攔截訊息）；Agent 執行逾時時，若有設定 [逾時自訂訊息](/build/agent/custom-max-tokens.md#agent-timeout-message) 會顯示該訊息。排查時到文字對話紀錄，先在 [自訂篩選欄位](#customize-filter-fields) 勾選 <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> 看錯誤內容；外部工具失敗另見 [工具執行紀錄](/build/agent-ops/tool-execution-records.md)。

### Q：監控數據保留多久？ <a href="#faq-monitoring-data-retention" id="faq-monitoring-data-retention"></a>

監控資料不會依時間自動清除。需要在其他系統長期留存或分析時，請用 [匯出請求](#export-requests) 下載。方案到期後整個組織資料的保留期限，見 [資料保留政策](/others/trial-and-plans.md#data-retention-policy)。


---

# 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.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.