> 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/tech/advanced-genai-tech/evaluation.md).

# 回覆評估與監測結果

MaiAgent 回覆評估的技術說明：Agent 監控與自動評估各用哪些指標、需要哪些資料、分數方向與測試案例的通過判定。

MaiAgent 用兩種方式評估 Agent 的回覆品質：上線後逐則計分的 **Agent 監控**，以及用測試集批次執行的 **自動評估**。本頁說明兩者使用的指標與計算方式；在後台建立評估、查看結果的操作，見使用者手冊的 [自動評估與 Agent 監控](https://docs.maiagent.ai/build/agent-ops/evaluations)；要從自己的系統建立測試集、執行評估與讀取結果，見 API 文件的 [評估與測試集](https://docs.maiagent.ai/api/api-reference/ping-gu-he-ce-shi-ji)。

## 兩種評估的差異 <a href="#two-modes" id="two-modes"></a>

| 項目     | Agent 監控                                        | 自動評估                                           |
| ------ | ----------------------------------------------- | ---------------------------------------------- |
| 評估對象   | 實際對話中的每一則回覆                                     | 測試集中的題目，由 Agent 實際作答後評分                        |
| 啟用方式   | Agent 的 <mark style="color:blue;">開啟自動評估</mark> | 在 AgentOps 建立評估                                |
| 評分框架   | Ragas                                           | DeepEval（4.1.7）                                |
| 評分用的模型 | 平台設定的評估模型                                       | 建立評估時選擇的 <mark style="color:blue;">評測模型</mark> |
| 指標     | 固定 3 項（見下方）                                     | 內建指標可組合，並可加自訂指標                                |
| 費用     | 評分會消耗組織的使用額度                                    | 作答與評分都會消耗組織的使用額度                               |

{% hint style="info" %}
地端部署時，Agent 監控使用的評估模型與 Embedding 模型由平台系統設定指定，需指向地端可連線的模型，否則評分會失敗。
{% endhint %}

## Agent 監控的指標 <a href="#monitoring-metrics" id="monitoring-metrics"></a>

Agent 開啟 <mark style="color:blue;">開啟自動評估</mark> 後，每次回覆完成時，平台在背景計算下列分數，結果顯示在 Agent 監控：

| 指標                        | 判斷內容                   |
| ------------------------- | ---------------------- |
| Faithfulness（誠實性）         | 回覆內容是否都能在檢索到的段落中找到依據   |
| Answer Relevancy（回答相關性）   | 回覆是否切中問題               |
| Context Precision（上下文精確度） | 檢索到的段落與問題的相關程度；不需要預期答案 |

實際對話沒有預期答案，所以監控不計算需要預期答案的指標。

## 自動評估的指標 <a href="#evaluation-metrics" id="evaluation-metrics"></a>

### 單輪評估 <a href="#single-turn-metrics" id="single-turn-metrics"></a>

每題由 Agent 實際作答後，以下列指標評分（後台顯示的名稱見「後台名稱」欄）：

| 指標                   | 後台名稱                                    | 判斷內容                  | 後台建立評估時                                    |
| -------------------- | --------------------------------------- | --------------------- | ------------------------------------------ |
| Faithfulness         | <mark style="color:blue;">品質性評分</mark>  | 回覆是否忠於檢索到的段落          | 一律計算                                       |
| Answer Relevancy     | <mark style="color:blue;">回答相關性</mark>  | 回覆是否切題                | 一律計算                                       |
| Contextual Precision | <mark style="color:blue;">上下文精確度</mark> | 相關段落是否排在前面            | 一律計算（需預期答案）                                |
| Contextual Relevancy | <mark style="color:blue;">上下文相關性</mark> | 檢索到的段落整體與問題的相關程度      | 一律計算（需預期答案）                                |
| Contextual Recall    | <mark style="color:blue;">上下文召回率</mark> | 預期答案需要的資訊是否都被檢索到      | 一律計算（需預期答案）                                |
| Bias                 | <mark style="color:blue;">偏見</mark>     | 回覆是否帶有偏見              | 一律計算                                       |
| Toxicity             | <mark style="color:blue;">冒犯性</mark>    | 回覆是否含冒犯或有害內容          | 一律計算                                       |
| Hallucination        | <mark style="color:blue;">幻覺</mark>     | 回覆是否與檢索內容矛盾           | 一律計算                                       |
| PII Leakage          | <mark style="color:blue;">PII 洩漏</mark> | 回覆是否洩漏個人識別資訊          | 選用（<mark style="color:blue;">安全類指標</mark>） |
| Role Violation       | <mark style="color:blue;">角色違規</mark>   | 回覆是否偏離 Agent 應有的角色    | 選用（<mark style="color:blue;">安全類指標</mark>） |
| Misuse               | <mark style="color:blue;">濫用</mark>     | Agent 是否被用於非預期用途      | 選用（<mark style="color:blue;">安全類指標</mark>） |
| Non-Advice           | <mark style="color:blue;">避免專業建議</mark> | 回覆是否避免提供醫療、法律、金融等專業建議 | 選用（<mark style="color:blue;">安全類指標</mark>） |

* 後台建立的單輪評估會計算上下文三項指標，因此**每一題都需要&#x20;**<mark style="color:blue;">**預期答案**</mark>：沒有填預期答案的題目會標為 <mark style="color:blue;">已跳過</mark>，不會作答也不計分。
* 平台的評估服務另支援 Task Completion、Tool Correctness、Summarization 三項指標，後台建立評估時不會啟用。

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

多輪評估由模擬使用者依測試案例的情境與 Agent 對話（最大輪數 2～10，預設 6），再以下列指標評分；至少須啟用一項內建指標，或設定自訂指標：

| 指標                                                                | 判斷內容           |
| ----------------------------------------------------------------- | -------------- |
| <mark style="color:blue;">逐輪忠實度（Turn Faithfulness）</mark>         | 每輪回覆是否忠於檢索到的內容 |
| <mark style="color:blue;">逐輪相關性（Turn Relevancy）</mark>            | 每輪回覆是否切題       |
| <mark style="color:blue;">對話完成度（Conversation Completeness）</mark> | 整段對話是否達成使用者的目標 |

### 自訂指標（GEval） <a href="#custom-metrics" id="custom-metrics"></a>

單輪與多輪評估都可以加 <mark style="color:blue;">自訂指標</mark>：以自然語言寫下 <mark style="color:blue;">評估準則</mark>，或列出 <mark style="color:blue;">評估步驟</mark>，由評測模型依準則給 0～1 分。

| 限制                                    | 規則                                        |
| ------------------------------------- | ----------------------------------------- |
| 數量                                    | 每次評估最多 10 個                               |
| 名稱                                    | 最多 100 字；同一次評估內不可重複（不分大小寫），也不可與該模式的內建指標同名 |
| 評估準則                                  | 最多 2,000 字                                |
| 評估步驟                                  | 最多 10 條，每條最多 500 字                        |
| <mark style="color:blue;">通過門檻</mark> | 0～1，預設 0.5                                |

單輪評估的自訂指標依題目、Agent 的回覆與檢索到的段落評分；多輪評估的自訂指標依整段對話逐字稿評分，不參考檢索段落。

## 分數方向與通過判定 <a href="#scoring" id="scoring"></a>

* 分數範圍為 0～1。內建指標沿用 DeepEval 的預設通過門檻 0.5。
* 單題分數保留 DeepEval 的原始方向：**偏見、冒犯性、幻覺、濫用是分數越低越好**，其他指標越高越好。評估的統計數字會把這四項換算成「1 − 分數」，讓所有統計一律越高越好。
* 單輪評估判定一題是否通過時，依序檢查三組關鍵指標，任何一組有指標未達門檻，該題就不通過：
  1. 安全類：偏見、冒犯性、幻覺、PII 洩漏、角色違規、濫用、避免專業建議
  2. 結果類：回答相關性（以及 Task Completion）
  3. 依據類：上下文召回率
* 其餘指標（品質性評分、上下文精確度、上下文相關性、自訂指標等）也需要達標；只有在上述三組都有計算且全部通過時，其餘指標未達標才不影響通過。
* 標記為不穩定（flaky）的題目仍會執行並保留結果，但不計入通過率。

## Faithfulness 與 Hallucination 的差異 <a href="#faithfulness-vs-hallucination" id="faithfulness-vs-hallucination"></a>

兩者都在檢查回覆與檢索內容的關係，但角度不同：

| 面向   | Faithfulness（品質性評分） | Hallucination（幻覺） |
| ---- | ------------------- | ----------------- |
| 評估問題 | 回覆中有多少陳述能在檢索內容找到依據？ | 回覆是否與檢索內容矛盾？      |
| 分數方向 | 越高越好                | 單題分數越低越好          |

例如檢索內容是「台北 101 的高度為 508 公尺，於 2004 年完工」，回覆多了一句「曾是世界最高建築」。這句在檢索內容中沒有依據，Faithfulness 會因此下降；Hallucination 則看回覆有沒有和檢索內容矛盾。

## 分數偏低時的排查方向 <a href="#troubleshooting" id="troubleshooting"></a>

* **上下文召回率、上下文精確度偏低**：檢索沒有找到正確的段落。先用 [搜尋測試](https://docs.maiagent.ai/build/knowledge-base/test-search-result) 確認，再調整知識庫內容、解析器或檢索參數，見 [RAG 知識庫檢索系統](/tech/quickstart/rag.md#parameters)。
* **品質性評分偏低、上下文分數正常**：段落已找到，但回覆沒有依據段落作答。檢查角色指令，或改用能力更強的模型。
* **回答相關性偏低**：回覆沒有切中問題，常見於角色指令限制過嚴或問題超出知識庫範圍。
* **分數普遍不穩定**：評分本身由評測模型判斷，請選用能力較強的評測模型。


---

# 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/tech/advanced-genai-tech/evaluation.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.