> 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/knowledge-base/test-search-result.md).

# 搜尋測試

在 LLM 正式上線前，可以先透過搜尋測試預覽功能，確認 LLM 所搜尋到的資料相關性與內容

## 為什麼需要搜尋測試？ <a href="#why-search-testing" id="why-search-testing"></a>

1. **確保回應準確性**

* Agent 的回應品質直接影響客戶滿意度
* 錯誤或不相關的答案會損害品牌信任度

2. **避免資訊遺漏**

* 避免重要產品細節或安全說明被忽略
* 優化知識庫的使用效率

3. **提升問答一致性**

* 確保相同問題在不同時間都能得到一致的答案
* 避免因知識庫更新導致的回應不穩定

透過搜尋測試與片段預覽功能，您可以即時查看 Agent 使用的資料片段品質，確保您的問答水準。

## 如何開始？ <a href="#how-to-get-started" id="how-to-get-started"></a>

1. 進入知識庫頁面，選擇要查看的知識庫並進入設定

<div><figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-c323186667e939261f4e539f8e8f15b5bef31bff%2Fimage%20(204)%20(1).png?alt=media" alt=""><figcaption></figcaption></figure> <figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-88c68e4bc4d8d3d06b484412c99830e620e59695%2F%E8%9E%A2%E5%B9%95%E6%93%B7%E5%8F%96%E7%95%AB%E9%9D%A2%202025-08-19%20105727%20(1).png?alt=media" alt=""><figcaption></figcaption></figure></div>

2. 進入後點選左側的 「<mark style="color:blue;">AI 搜尋</mark>」（頁面標題為 「知識庫搜尋測試」）

在對話框內輸入要搜尋的內容：「挑選露營區要注意什麼？」，按下搜尋鍵後，Agent 就會根據您的對話內容搜尋最相關的文件。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-8c8c0d07a29d2283341ae412727851aec5fe01b1%2Fimage%20(203).png?alt=media" alt=""><figcaption></figcaption></figure>

3. 查看搜尋結果

右側會出現 Agent 回答時會檢索的片段，如圖共有 12 個片段（檢索片段數量設定請參考：[如何建立知識庫：基本設置](/build/knowledge-base/km-basic-settings.md#retrieval-chunk)）

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-2207b0818bd902a0c1df84366a52ea5386ab768e%2F%E8%9E%A2%E5%B9%95%E6%93%B7%E5%8F%96%E7%95%AB%E9%9D%A2%202025-08-19%20115153-1.png?alt=media" alt=""><figcaption></figcaption></figure>

右側為針對此問題回答時根據的檢索內容，每個片段會顯示：

* 字數：片段涵蓋的字數
* 命中次數：Agent 在回答時參考此片段的次數 (只統計正式問答，測試問答不會納入命中次數計算中)

  命中次數越高代表使用者詢問較多關於此片段的問題。

搜尋結果區右上角的 <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>」：保留這台瀏覽器最近 10 筆查詢，點任一筆即可重新搜尋，方便用同一組問題比較調整前後的差異；<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-9fc5437758e4e579e756893bbe7beddc378118df%2Fimage%20(164).png?alt=media" alt=""><figcaption></figcaption></figure>

## AI 摘要 <a href="#ai-summary" id="ai-summary"></a>

搜尋框旁的 「<mark style="color:blue;">AI 摘要</mark>」 開關預設開啟：每次搜尋後，除了列出片段，上方還會多一段由 LLM 根據這些片段整理出來的摘要，讓您直接看到「用這批片段能不能答出這個問題」，不必逐一讀完片段。

* 開關旁的下拉選單可 <mark style="color:blue;">選擇模型（預設使用系統設定）</mark>，想比較不同模型的整理效果時再換。
* 摘要是額外的 LLM 呼叫，會依所選模型消耗組織的 Credits；只想看檢索結果時關掉開關即可。
* 畫面顯示「AI 摘要功能尚未啟用，請聯繫管理員」代表組織尚未設定可用的模型；「Credit 餘額不足，無法生成 AI 摘要」請先儲值；「搜尋無結果，無法生成摘要」則是沒有片段可整理，請改寫問題或檢查文件。

{% hint style="info" %}
AI 摘要只用於這個測試頁，不代表 Agent 對話時的實際回覆：Agent 還會套用角色指令、回答模式與其他設定。要看完整回覆品質請到 [自動評估與 Agent 監控](/build/agent-ops/evaluations.md)。
{% endhint %}

## 檢查知識片段品質 <a href="#check-chunk-quality" id="check-chunk-quality"></a>

透過搜尋測試，可以確定 Agent 在推理時使用哪些片段，進而檢查這些片段的內容是否需要優化，如：

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-de43de20be264906e935ea1ddba3983f3cda74de%2Fimage%20(165).png?alt=media" alt=""><figcaption></figcaption></figure>

若在搜尋結果中發現許多空白的片段，且這些空白片段都屬於「<mark style="color:blue;">初級露營.pdf</mark>」這個檔案，這時就能檢查「<mark style="color:blue;">初級露營.pdf</mark>」的檔案內容是否都正確，並在**正式上線前**即時更新。

## 搜尋模式與查詢元資料條件 <a href="#search-by-metadata" id="search-by-metadata"></a>

搜尋測試頁的左側可以調整兩件事：用哪一種方式搜尋，以及只在哪些文件或標籤範圍內搜尋。

### 選擇搜尋模式 <a href="#search-modes" id="search-modes"></a>

在 <mark style="color:blue;">搜尋模式</mark> 選擇其中一種：

| 搜尋模式                                      | 怎麼找              | 適合測試                    |
| ----------------------------------------- | ---------------- | ----------------------- |
| <mark style="color:blue;">混合搜尋</mark>（預設） | 同時比對語意與關鍵字，再合併結果 | 一般問題，最接近 Agent 對話時的檢索方式 |
| <mark style="color:blue;">語意搜尋</mark>     | 只比對語意，措辭不同也找得到   | 自然語言的提問                 |
| <mark style="color:blue;">關鍵字搜尋</mark>    | 只比對字詞            | 產品型號、專有名詞、代碼是否找得到       |

{% hint style="info" %}
搜尋模式只影響這次的搜尋測試；Agent 對話時一律使用平台設定的檢索方式（預設為混合搜尋，見[技術人員手冊 - 混合檢索](https://docs.maiagent.ai/tech/quickstart/rag#hybrid-search)）。<mark style="color:blue;">關鍵字搜尋</mark> 只支援 Elasticsearch，知識庫改接其他類型的[自帶向量資料庫](/build/knowledge-base/km-basic-settings.md#vector-database)時無法使用。
{% endhint %}

### 搜尋結果有相關度分數嗎？ <a href="#relevance-score" id="relevance-score"></a>

搜尋測試的片段依相關程度由高到低排列，但**不顯示分數**，[知識庫檢索 API](https://docs.maiagent.ai/tech/api-integration/knowledge-base-api#search-response) 的回應同樣不含分數；請以排序判斷相關程度。Web Chat 引用節點上的 <mark style="color:blue;">相關度</mark> 百分比是 Agent 回答當下對被引用片段的評分，見 [引用來源顯示](/build/choose-channel/web-chat/citation-display.md#citation-display-location)。搜尋沒有任何片段時，畫面會顯示沒有結果；開著 AI 摘要時則顯示「搜尋無結果，無法生成摘要」。

### 什麼是查詢元資料條件？ <a href="#what-is-metadata-search" id="what-is-metadata-search"></a>

查詢元資料（Query Metadata）用來限定這次搜尋的範圍：只在指定的檔案、FAQ，或符合指定標籤條件的文件中搜尋。它和設定在聯絡人、對話上的查詢元資料是同一種條件，所以可以用搜尋測試模擬「某位聯絡人提問時，會檢索到哪些片段」。概念說明見 [查詢元資料](/org/querymetadata.md)。

### 如何設定查詢元資料條件 <a href="#how-to-use-metadata-search" id="how-to-use-metadata-search"></a>

1. 在搜尋測試頁左側的 <mark style="color:blue;">Query Metadata</mark> 區塊，點選右上角的 <mark style="color:blue;">查詢構建器</mark>。知識庫還沒有任何文件或 FAQ 時，這個按鈕無法點選。
2. 在查詢構建器勾選要開放的文件或 FAQ；需要依標籤篩選時，開啟標籤過濾並設定條件。操作方式同 [查詢構建器](/org/querymetadata/query-builder.md)。
3. 確認後，<mark style="color:blue;">Query Metadata</mark> 區塊會以 JSON 顯示目前的條件，並標示共有幾個條件。
4. 輸入問題並點選 <mark style="color:blue;">搜尋</mark>，結果只會包含條件範圍內的片段。

### 什麼時候用 <a href="#metadata-search-advantages" id="metadata-search-advantages"></a>

* **驗證權限範圍**：確認套用某組條件後，不該看到的文件確實不會被檢索出來。
* **縮小範圍排查**：某個問題的結果混入其他文件時，先限定在預期的文件內測試，判斷問題出在內容本身還是檢索範圍。

### 實際應用場景 <a href="#practical-use-cases" id="practical-use-cases"></a>

* **會員分級內容**：產品價格表只開放給 VIP 會員。用查詢構建器只勾選一般會員可看的文件或標籤，詢問「價格是多少？」，確認結果中不會出現價格表的片段。
* **型號查詢**：客戶常用型號提問，例如「A100 的保固多久？」。切換到 <mark style="color:blue;">關鍵字搜尋</mark> 測試型號是否找得到；找不到時，檢查文件中的型號寫法是否和客戶的寫法一致。

## 搜尋測試協助您 <a href="#what-search-testing-helps-you" id="what-search-testing-helps-you"></a>

### 定期測試重要問題 <a href="#regular-testing-key-questions" id="regular-testing-key-questions"></a>

* 建議經常測試核心業務相關問題
* 在知識庫更新後進行重新測試
* 記錄並比較測試結果的改善情況

### 識別內容空白點 <a href="#identify-content-gaps" id="identify-content-gaps"></a>

* 發現知識缺口：測試常見問題，找出完全沒有命中結果的查詢
* 範例：測試「帳篷防水等級說明」發現無相關片段 → 需補充防水規格文件

{% hint style="info" %}
平台不會自動記錄「檢索不到內容」的使用者提問，也沒有零結果查詢的報表。要從正式對話找出知識缺口，請用 [對話平台分析](/serve/daily-operations/reply/inbox-analysis.md#failure-reasons) 的「知識庫缺口」分類，或在 [Agent 監控](/build/agent-ops/evaluations.md) 逐筆查看回答時實際檢索到的片段，再把缺少的內容補進知識庫。
{% endhint %}

### 評估內容完整性 <a href="#evaluate-content-completeness" id="evaluate-content-completeness"></a>

* 檢查回答深度：確認AI回答是否涵蓋問題的所有面向
* 範例：查詢「露營安全注意事項」→ 檢查是否涵蓋天氣、野生動物、用火安全等各個層面

## 問題測試技巧 <a href="#query-testing-techniques" id="query-testing-techniques"></a>

您可以：

* 用不同方式詢問同一個問題
* 測試複雜情境和多重條件查詢
* 驗證專業術語和產品名稱的檢索效果

透過這些測試技巧，全面評估回覆的正確度及完整性。


---

# 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/knowledge-base/test-search-result.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.