> 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/test-datasets.md).

# 測試集管理

建立測試資料集,系統化管理測試案例,驗證 Agent 回應品質

## 什麼是測試資料集? <a href="#what-is-test-dataset" id="what-is-test-dataset"></a>

測試資料集是一組預先準備好的測試案例集合,用於驗證 Agent 的回應品質與準確性。透過建立標準化的測試資料集,您可以:

**確保回應品質**

* 驗證 Agent 對常見問題的回應是否符合預期
* 確保知識庫更新後回應不會退化
* 持續追蹤回應品質的變化趨勢

**提升效率**

* 批次測試多個問題,無需逐一手動驗證
* 建立可重複使用的測試案例,節省測試時間
* 快速識別問題並及時調整

**團隊協作**

* 集中管理所有測試案例
* 不同成員可共同維護測試資料
* 追蹤測試案例的建立者與更新時間

## 如何進入測試資料集管理 <a href="#how-to-access-test-dataset-management" id="how-to-access-test-dataset-management"></a>

進入左側功能欄的 「<mark style="color:blue;">**AgentOps**</mark>」,點選 「<mark style="color:blue;">**測試集**</mark>」，即可看到測試集管理頁面。

頁面中會顯示以下資訊:

* **測試資料集 ID**: 系統自動產生的唯一識別碼
* **測試資料集名稱**: 您為資料集設定的名稱
* <mark style="color:blue;">單輪測試案例數</mark>：此測試集內已啟用的單輪案例筆數
* <mark style="color:blue;">多輪測試案例數</mark>：此測試集內已啟用的多輪案例筆數，並非對話輪數
* **建立者**: 建立此資料集的使用者
* **建立時間**: 資料集建立的日期與時間
* **最後更新**: 資料集最後修改的時間
* **操作按鈕**: 編輯、刪除等功能

## 使用情境：確認案例數量 <a href="#check-case-counts" id="check-case-counts"></a>

客服主管想確認題庫是否同時涵蓋一問一答與來回確認的服務情境。她開啟 <mark style="color:blue;">AgentOps</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-e7bc63ad313c5f8fdc217c59f8a2ae9016a7279d%2Ftest-datasets-case-counts.png?alt=media" alt="測試集列表分別顯示單輪測試案例數 3 與多輪測試案例數 2"><figcaption><p>兩種案例分欄計數；圖中的多輪數字 2 代表兩筆案例，不是兩輪對話。</p></figcaption></figure>

{% hint style="info" %}
兩欄只計算已啟用的案例。停用的案例不計入；某一類沒有已啟用的案例時，該欄顯示 0。
{% endhint %}

## 建立測試資料集 <a href="#create-test-dataset" id="create-test-dataset"></a>

### 1. 開始建立 <a href="#start-creating" id="start-creating"></a>

點擊頁面右上角的 「<mark style="color:blue;">**建立測試集**</mark>」按鈕,開始建立新的測試資料集。

### 2. 設定基本資訊 <a href="#set-basic-info" id="set-basic-info"></a>

在彈出的對話框中,輸入以下資訊:

**測試資料集名稱** (必填)

* 建議使用有意義的名稱,例如:「產品查詢測試集」、「客服常見問題測試」
* 方便日後管理與識別用途

**測試資料集描述** (選填)

* 說明此測試集的用途與涵蓋範圍
* 例如:「用於測試產品規格查詢功能,包含 50 個常見產品問題」

<mark style="color:blue;">選擇 AI 助理</mark>（必填）

* 選擇要測試的 Agent
* 一個測試資料集可以對應一個或多個 Agent

### 3. 新增測試案例 <a href="#add-test-cases" id="add-test-cases"></a>

測試資料集建立後，點進測試集，在左側點選「<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>       | 已有整理好的題庫     | 上傳 CSV／XLS／XLSX，一次匯入多題 |
| <mark style="color:blue;">從知識庫檔案生成</mark> | 剛上傳知識庫、還沒有題目 | 由 AI 依知識庫檔案內容自動出題      |

每個測試案例包含:

**問題**

* 使用者可能詢問的問題（最多 1000 字）
* 建議涵蓋各種問法與情境

**預期答案**

* Agent 應該如何回答（最多 2000 字）
* 可以是關鍵字、句子或完整段落
* 評估時由評測模型比對實際回應與預期答案

#### 手動輸入 <a href="#add-manually" id="add-manually"></a>

選「<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>」開關見 [標記不穩定（flaky）的測資](#flaky-test-cases)。

#### 匯入檔案 <a href="#import-from-file" id="import-from-file"></a>

選「<mark style="color:blue;">匯入</mark>」，把檔案拖進「<mark style="color:blue;">上傳檔案</mark>」區或點擊選取，可一次上傳多個檔案：

* 支援格式：CSV、XLS、XLSX；單一檔案不超過 10MB
* 檔案第一列為欄位標題，須包含 `question`（問題）與 `ground_truth`（預期答案）兩欄；其他欄位會被忽略
* 匯入成功後會顯示「測試案例匯入成功」，列表會多出對應筆數；匯入的案例在「<mark style="color:blue;">建立方式</mark>」顯示為匯入

```
question,ground_truth
你們的退貨政策是什麼?,購買後 7 天內可無條件退貨,商品需保持全新未使用狀態
如何申請退款?,請透過會員中心的訂單管理頁面申請退款
```

#### 從知識庫檔案生成 <a href="#generate-from-knowledge" id="generate-from-knowledge"></a>

選「<mark style="color:blue;">從知識庫檔案生成</mark>」，由 AI 讀取您指定的知識庫檔案，自動產生「問題＋預期答案」：

1. 在「<mark style="color:blue;">新增題目數量</mark>」輸入要產生的題數（1–50）。
2. 點「<mark style="color:blue;">選擇知識庫檔案</mark>」，在視窗左側搜尋並點選知識庫，右側勾選要出題的檔案（最多 50 個，上方進度條會顯示已選數量），按「<mark style="color:blue;">確認選擇</mark>」。只能選已處理完成的文件；不支援的檔案類型會自動過濾掉。
3. 按「<mark style="color:blue;">確認</mark>」。系統提示「測試案例生成任務已提交，正在背景處理中」，測試案例列表上方會顯示「正在生成測試案例（已生成 N/M 題）」的進度；測試集列表的「單輪測試案例數」欄也會顯示進度。完成後重新整理即可看到新題目，「建立方式」顯示為從知識庫檔案生成。

{% hint style="info" %}
生成的題數以「要求題數」為上限；檔案內容不足時實際生成會比較少。生成完成後請逐題檢查，必要時修改預期答案或刪除不合適的題目——自動生成是起點，不是最終答案。
{% 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;">生成明細</mark>」，可看到「<mark style="color:blue;">已處理檔案</mark>」數與「<mark style="color:blue;">逐檔結果</mark>」：每個檔案的狀態、「<mark style="color:blue;">生成筆數</mark>」與「<mark style="color:blue;">錯誤原因</mark>」。狀態為「部分完成」時，通常是其中幾個檔案無法解析，從逐檔結果就能找出是哪幾個。

#### 標記不穩定（flaky）的測資 <a href="#flaky-test-cases" id="flaky-test-cases"></a>

新增或編輯單筆測試案例時，可開啟「<mark style="color:blue;">不穩定</mark>」開關。標記為不穩定（flaky）的測資在自動評估時**仍會執行並保留結果，但不計入通過率**（分子與分母都排除）。適合答案本身有多種合理說法、或依賴外部即時資料而結果不穩定的題目：保留它們觀察趨勢，又不讓它們拉低整體通過率。評估結果頁各指標的統計則涵蓋所有已完成的測資，包含 flaky。

#### 批量刪除 <a href="#batch-delete-test-cases" id="batch-delete-test-cases"></a>

在測試案例列表勾選多筆後，上方會出現「<mark style="color:blue;">批量刪除 (N)</mark>」，確認後一次刪除所選案例。

**測試案例範例:**

```
問題: 你們的退貨政策是什麼?
預期回應: 購買後 7 天內可無條件退貨,商品需保持全新未使用狀態

問題: 如何申請退款?
預期回應: 請透過會員中心的訂單管理頁面申請退款,審核通過後 3-5 個工作天內退款

問題: 退貨運費誰負擔?
預期回應: 若為商品瑕疵由我們負擔運費,若為個人因素退貨則由買家負擔
```

### 4. 多輪對話測試案例 <a href="#multi-turn-test-cases" id="multi-turn-test-cases"></a>

單輪測試案例檢查「一問一答」；要檢查需要來回確認的任務（例如先問訂單編號、再確認退貨原因），請在測試集左側點選「<mark style="color:blue;">多輪對話測試案例</mark>」。這裡的案例只會被「多輪對話」類型的評估使用，見 [評估多輪對話](/build/agent-ops/evaluations.md#multi-turn-evaluation)。

點「<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>」，輸入題數並選擇知識庫檔案，由 AI 依檔案內容合成「情境＋預期結果」的多輪案例；流程與單輪的 [從知識庫檔案生成](#generate-from-knowledge) 相同，完成後重新整理列表。

## 管理測試資料集 <a href="#manage-test-datasets" id="manage-test-datasets"></a>

### 搜尋測試資料集 <a href="#search-test-dataset" id="search-test-dataset"></a>

使用頁面上方的搜尋欄,您可以透過以下方式快速找到目標資料集:

* 測試資料集 ID
* 測試資料集名稱
* 描述內容關鍵字

輸入關鍵字後,系統會即時過濾並顯示符合條件的資料集。

### 編輯測試資料集 <a href="#edit-test-dataset" id="edit-test-dataset"></a>

點擊操作欄位中的 「<mark style="color:blue;">**編輯**</mark>」按鈕,您可以:

* 修改測試資料集名稱與描述
* 新增、編輯或刪除測試案例
* 調整測試案例的順序

{% hint style="info" %}
建議定期檢視並更新測試案例,確保測試內容與實際業務需求保持一致
{% endhint %}

### 刪除測試資料集 <a href="#delete-test-dataset" id="delete-test-dataset"></a>

點擊操作欄位中的 「<mark style="color:blue;">**刪除**</mark>」按鈕,即可刪除不再需要的測試資料集。

{% hint style="warning" %}
刪除測試資料集後無法復原,請謹慎操作。若該資料集已被用於自動評估,相關評估記錄仍會保留,但無法再次執行相同測試。
{% endhint %}

## 測試資料集最佳實踐 <a href="#test-dataset-best-practices" id="test-dataset-best-practices"></a>

### 1. 建立結構化的測試分類 <a href="#structured-test-categories" id="structured-test-categories"></a>

依照業務需求將測試案例分組:

```
產品相關知識庫測試:
├── 產品查詢測試集 (50個案例)
├── 價格諮詢測試集 (30個案例)
└── 庫存確認測試集 (20個案例)

客服流程測試:
├── 訂單處理測試集 (40個案例)
├── 退換貨流程測試集 (35個案例)
└── 會員服務測試集 (25個案例)
```

### 2. 涵蓋多種問法 <a href="#cover-multiple-phrasings" id="cover-multiple-phrasings"></a>

同一個概念可能有不同的問法,建議在測試案例中涵蓋:

```
正式問法: 請問貴公司的營業時間為何?
口語問法: 你們幾點開?
簡短問法: 營業時間
完整句子: 我想知道你們的營業時間是幾點到幾點
```

### 3. 包含邊界情境 <a href="#include-edge-cases" id="include-edge-cases"></a>

測試極端情況與模糊問題:

* 不完整的問題:「價格」、「怎麼辦」
* 含有錯別字的問題:「產品槼格」
* 複合問題:「價格多少?可以退貨嗎?有什麼顏色?」
* 不在知識範圍的問題:測試 Agent 如何應對

### 4. 定期更新測試資料 <a href="#regular-data-updates" id="regular-data-updates"></a>

* **新功能上線時**: 新增對應的測試案例
* **知識庫更新後**: 確認相關測試案例是否需要調整
* **發現問題時**: 立即新增該情境的測試案例,避免再次發生
* **定期審查**: 每月或每季檢視測試案例是否仍符合現況

### 5. 設定適當的測試數量 <a href="#appropriate-test-count" id="appropriate-test-count"></a>

建議每個測試資料集包含:

* **最少 20 個測試案例**: 確保涵蓋基本情境
* **建議 30-50 個測試案例**: 平衡測試覆蓋率與執行時間
* **特殊情況可達 100+ 案例**: 適用於複雜業務邏輯

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

### Q1: 測試資料集與自動評估的關係是什麼? <a href="#faq-test-dataset-vs-auto-evaluation" id="faq-test-dataset-vs-auto-evaluation"></a>

測試資料集是自動評估的基礎。您需要先建立測試資料集,然後在「自動評估」功能中選擇測試資料集與 Agent,系統會自動執行測試並產生評估報告。

> 更多資訊請參考: [自動評估](/build/agent-ops/evaluations.md)

### Q2: 一個測試資料集可以測試多個 Agent 嗎? <a href="#faq-one-dataset-multiple-agents" id="faq-one-dataset-multiple-agents"></a>

可以。您可以在自動評估時選擇同一個測試資料集搭配不同的 Agent,比較不同 Agent 在相同測試案例下的表現差異。

### Q3: 測試案例的預期回應需要完全一致嗎? <a href="#faq-expected-response-exact-match" id="faq-expected-response-exact-match"></a>

不需要。系統會檢查 Agent 的實際回應是否「包含」預期回應的關鍵內容。您可以設定關鍵字或重要句子,只要實際回應包含這些內容即視為通過。

### Q4: 如何匯入大量測試案例? <a href="#faq-bulk-import-test-cases" id="faq-bulk-import-test-cases"></a>

在「新增測試案例」選擇「<mark style="color:blue;">匯入</mark>」，上傳含 `question` 與 `ground_truth` 兩欄的 CSV／XLS／XLSX 即可，見 [匯入檔案](#import-from-file)。還沒有題庫時，可改用 [從知識庫檔案生成](#generate-from-knowledge) 讓 AI 先出題。

### Q5: 測試資料集可以共享給其他組織成員嗎? <a href="#faq-share-dataset-with-members" id="faq-share-dataset-with-members"></a>

可以。同一組織下的所有成員都可以查看與使用測試資料集。您可以透過「建立者」欄位識別是誰建立的資料集,方便團隊協作。

### Q6: 刪除 Agent 後,相關的測試資料集會消失嗎? <a href="#faq-dataset-after-agent-deleted" id="faq-dataset-after-agent-deleted"></a>

不會。測試資料集是獨立管理的,即使刪除 Agent,測試資料集仍會保留。您可以將同一個測試資料集用於其他 Agent 的測試。

***

## 下一步 <a href="#next-steps" id="next-steps"></a>

建立測試資料集後,您可以:

* 前往 [自動評估](/build/agent-ops/evaluations.md) 執行測試並查看結果
* 透過 [Agent 監控](/build/agent-ops/evaluations.md#ai-agent-monitoring) 追蹤 Agent 的實際運作表現
* 根據評估結果調整知識庫內容或 Agent 設定


---

# 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/test-datasets.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.