# 對話平台分析

對話平台分析（Inbox Analysis）能針對特定對話平台、指定日期範圍內的真實對話，透過 AI 自動歸納主題、判斷解決狀況，並整理出具體改善建議，協助您持續優化 AI 助理的對話品質。

## 什麼是對話平台分析？ <a href="#what-is-inbox-analysis" id="what-is-inbox-analysis"></a>

在客服對話累積到一定量體後，光看總量或滿意度並不夠——您更想知道：

* **使用者實際在問什麼？** 最常被問的主題有哪些？
* **有多少對話真正被解決了？** 哪些類型的問題解決率偏低？
* **沒解決的原因是什麼？** 是知識庫缺內容、指令太限制，還是工具失敗？
* **回覆速度與成本分佈如何？** 哪些主題耗時長、Token 用量高？

對話平台分析就是為了回答這些問題而設計。系統會：

1. 擷取指定時間範圍內的對話
2. 使用嵌入模型做主題分群
3. 使用 LLM 逐筆分析對話的意圖、解決狀況、失敗原因
4. 綜合產出分析摘要（含改善建議）

{% hint style="info" %}
**與類似功能的差別**
{% endhint %}

| 功能                         | 觸發時機          | 用途                           |
| -------------------------- | ------------- | ---------------------------- |
| [使用分析](/org/usage.md)      | 即時統計          | AI 助理層級量化 KPI（對話字數、次數、滿意度）   |
| 對話平台「對話分析」設定（每個對話平台設定中的分頁） | 即時，每筆新訊息進來時   | 用 LLM 自動為對話打標籤，幫助分流與管理       |
| **本頁說明的「對話平台分析」**          | **手動觸發、批次回顧** | **針對指定日期範圍做主題分群、解決率分析、改善建議** |

***

## 如何使用 <a href="#how-to-use" id="how-to-use"></a>

{% stepper %}
{% step %}

#### 進入對話平台分析頁面 <a href="#enter-page" id="enter-page"></a>

1. 點選左側選單「<mark style="color:blue;">客服對話</mark>」→「<mark style="color:blue;">對話平台</mark>」
2. 在對話平台列表中，找到目標對話平台
3. 點選該列右側操作區的<mark style="color:blue;">📊 圖示</mark>（hover 顯示「對話平台分析」），進入分析頁面

頁面會顯示此對話平台過去建立的所有分析報告，包含日期範圍、狀態、對話數、處理時間等資訊。

<figure><img src="/files/CneKwOhd4fxe9ojPde4I" alt="對話平台分析列表頁"><figcaption><p>對話平台分析列表頁：顯示過去建立的分析報告</p></figcaption></figure>
{% endstep %}

{% step %}

#### 新增分析 <a href="#create-analysis" id="create-analysis"></a>

點選右上角的「<mark style="color:blue;">新增分析</mark>」按鈕，填寫以下必填欄位：

* **日期範圍**：選擇要分析的對話區間（不可選未來日期）
* **分析用 LLM**：用來逐筆分析對話的大型語言模型
* **嵌入模型**：用來做主題分群的嵌入模型
* **報告語言**：分析摘要的輸出語言（繁體中文、簡體中文、英文、日文、韓文）

<figure><img src="/files/EaZDAhOJlyBJv3trs50Q" alt="新增分析 Modal"><figcaption><p>新增分析 Modal：填寫必填欄位</p></figcaption></figure>

展開「<mark style="color:blue;">進階設定</mark>」可調整取樣策略（詳見下方「進階設定說明」）。

<figure><img src="/files/rwtQNqPqdBrBCb4mIkRu" alt="進階設定展開後"><figcaption><p>進階設定：調整取樣與並行參數</p></figcaption></figure>

按下「<mark style="color:blue;">確定</mark>」後，系統會在背景非同步執行分析，狀態會從「等待中」→「處理中」→「已完成」。
{% endstep %}

{% step %}

#### 查看報告 <a href="#view-report" id="view-report"></a>

待狀態變為「已完成」後，點擊該報告的「<mark style="color:blue;">查看報告</mark>」圖示（👁），即可進入報告詳情頁面。

報告內容依對話資料豐富程度呈現，包含數據概覽、解決狀況、主題分群、熱門問題、效能指標、分析摘要與逐筆對話分析。

<figure><img src="/files/QQ5kYGl7oDcvU6FKSa2a" alt="分析報告詳情頁"><figcaption><p>分析報告詳情頁：儀表板呈現指標、分群、失敗原因與效能分佈</p></figcaption></figure>
{% endstep %}
{% endstepper %}

***

## 報告內容說明 <a href="#report-content" id="report-content"></a>

### 1. 數據概覽 <a href="#data-overview" id="data-overview"></a>

| 指標   | 說明                          |
| ---- | --------------------------- |
| 總對話數 | 日期範圍內該對話平台的總對話數             |
| 已分析  | 實際被 LLM 分析的對話數量（受「最大取樣數」限制） |
| 抽樣率  | 已分析 / 總對話數（百分比）             |
| 處理時間 | 本次分析任務從開始到完成所花費的秒數          |

{% hint style="info" %}
當總對話數超過「最大取樣數」時，系統會以分群後的取樣策略選擇代表性對話進行分析，以控制成本與時間。
{% endhint %}

### 2. 解決狀況 <a href="#resolution-status" id="resolution-status"></a>

核心指標「**解決率**」計算公式：

```
解決率 = (已解決數 + 部分解決數) ÷ 已分析數
```

* **已解決**（綠）：AI 助理完整回答使用者問題
* **部分解決**（橘）：回答部分內容或方向正確但不完整
* **未解決**（紅）：無法回答或回答錯誤

解決率高於 50% 以綠色顯示，低於 50% 以紅色顯示，作為即時健康度提醒。

### 3. 效能指標 <a href="#performance-metrics" id="performance-metrics"></a>

呈現 AI 助理在這段時間的運算表現：

* **Token 總用量**：Input + Output Token 合計
* **每輪平均 Token**：平均每次對話輪次消耗的 Token 數
* **平均回覆時間**：從收到訊息到完整回覆的總耗時
* **平均首 Token 時間（TTFT）**：從收到訊息到開始輸出第一個 Token 的時間

### 4. 主題分群分佈 <a href="#topic-clusters" id="topic-clusters"></a>

將所有對話依「語意相似度」分群，以水平長條圖呈現各主題的出現次數與佔比。離群對話會歸類為「Noise / Outliers」。

透過此視圖可快速辨識使用者最常詢問的主題。

### 5. 解決 / 失敗原因分佈 <a href="#failure-reasons" id="failure-reasons"></a>

系統會為每筆分析的對話標記狀態或失敗原因，彙總如下：

| 原因     | 說明              |
| ------ | --------------- |
| 已解決    | AI 助理成功回答       |
| 部分解決   | 回答方向正確但不完整      |
| 知識庫缺口  | 知識庫缺少相關內容       |
| 指令過於限制 | 角色指令阻擋了合理回覆     |
| 工具失敗   | 工具執行錯誤或未觸發      |
| 用戶不明確  | 使用者訊息模糊、無法判斷意圖  |
| 離題     | 使用者問的內容不在助理範圍內  |
| 幻覺回應   | AI 生成了不存在或錯誤的資訊 |
| 未知     | 無法歸類到上述類別       |

此分佈可以直接引導後續改善動作：知識庫缺口多 → 補內容；指令過於限制多 → 調整角色指令；幻覺多 → 加強知識庫與指令約束。

### 6. 熱門問題排行 <a href="#top-questions" id="top-questions"></a>

以「次數」排序的主題列表，顯示每個主題的**出現次數**與**解決率**。展開任一列可看到該主題的範例意圖，幫助您快速確認分群是否符合預期。

### 7. 按主題效能分佈 <a href="#performance-by-topic" id="performance-by-topic"></a>

針對每個主題拆解 Token 與耗時，找出「貴」或「慢」的主題：

* 平均 Input / Output / Total Token
* 平均回覆時間
* 平均首 Token 時間

若某主題 Token 異常高，可考慮優化角色指令或知識庫召回；若某主題耗時長，可能是工具呼叫次數多或內容過長。

### 8. 分析摘要 <a href="#synthesis" id="synthesis"></a>

由 LLM 綜合所有分析結果生成的 Markdown 報告，通常包含：

* 整體表現摘要
* 主要問題模式
* 優先改善建議
* 具體調整方向

預設以摺疊區塊顯示，點擊標題即可展開閱讀。

### 9. 逐筆對話分析 <a href="#per-conversation-analysis" id="per-conversation-analysis"></a>

展開後可逐筆檢視每個被分析的對話，每筆包含：

* **意圖**（User Intent）：使用者真正想問什麼
* **主題**（Topic）：歸屬的主題分群
* **說明**（Resolution Detail）：解決狀況的詳細描述
* **改善建議**（Suggestions）：針對該筆對話的具體優化方向

***

## 進階設定說明 <a href="#advanced-config" id="advanced-config"></a>

進階設定控制取樣與執行策略，建議先以預設值執行，再依需求調整：

| 參數      | 預設值 | 說明                           |
| ------- | --- | ---------------------------- |
| 每群集取樣數  | 10  | 每個主題分群最多取幾筆對話進 LLM 分析        |
| 最大取樣數   | 150 | 整份報告最多分析幾筆對話（控制成本上限）         |
| 並行數     | 8   | LLM 分析的並行處理數，數字越高越快但瞬時資源消耗越高 |
| 最大擷取對話數 | —   | 從資料庫撈取的對話總量上限                |
| 最少對話訊息數 | —   | 訊息數少於此值的對話會被過濾（避免分析無意義的短對話）  |

{% hint style="warning" %}
**成本提醒**：分析會消耗 LLM Token 額度（Input + Output + Embedding）。分析前系統會檢查組織額度，額度不足時無法建立任務。
{% endhint %}

***

## 應用情境 <a href="#use-cases" id="use-cases"></a>

### 情境一：季度品質回顧 <a href="#case-quarterly-review" id="case-quarterly-review"></a>

**需求**：主管想知道上一季 Web Chat 對話平台的對話品質與主要問題。

**操作**：

1. 日期範圍選擇上一季
2. 最大取樣數設為 300（擴大樣本）
3. 執行分析，聚焦「解決/失敗原因分佈」與「熱門問題排行」
4. 針對知識庫缺口、指令過於限制等高頻原因排定改善任務

### 情境二：版本更新後影響評估 <a href="#case-version-impact" id="case-version-impact"></a>

**需求**：上週調整了角色指令，想知道是否改善對話品質。

**操作**：

1. 分別針對「調整前一週」與「調整後一週」建立兩份分析報告
2. 對比兩份報告的解決率與失敗原因分佈
3. 確認特定失敗類型是否下降

### 情境三：主題分群做知識庫補全 <a href="#case-knowledge-gap" id="case-knowledge-gap"></a>

**需求**：發現使用者常問的問題，想系統性補充知識庫。

**操作**：

1. 分析近一個月對話
2. 從「熱門問題排行」挑出高頻、低解決率的主題
3. 展開「範例意圖」確認實際問法
4. 回到知識庫補上對應 FAQ 或文件

***

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

### Q：為什麼有些對話沒被分析？ <a href="#faq-why-not-all-analyzed" id="faq-why-not-all-analyzed"></a>

系統會依「最大取樣數」與「最少對話訊息數」做過濾，並在分群後做代表性取樣。若總對話數龐大，會只取代表性樣本以控制成本。

### Q：解決率是如何判斷的？ <a href="#faq-resolution-rate" id="faq-resolution-rate"></a>

分析用 LLM 會對每個被分析的對話**直接歸類為 9 種狀態之一**：已解決、部分解決、知識庫缺口、指令過於限制、工具失敗、用戶不明確、離題、幻覺回應、未知。

解決率公式：

```
解決率 = (已解決 + 部分解決) ÷ 已分析總數
```

「已解決」與「部分解決」皆計入解決率分子，其餘 7 種狀態都視為未解決。

### Q：可以同時對同一對話平台建立多份分析嗎？ <a href="#faq-concurrent-analyses" id="faq-concurrent-analyses"></a>

可以，但**日期範圍不能與進行中的分析重疊**。若出現「此對話平台已有進行中的分析，日期範圍重疊」錯誤，請等待該分析完成或選擇不同的日期範圍。

### Q：分析要跑多久？ <a href="#faq-duration" id="faq-duration"></a>

視對話量、最大取樣數、並行數與所選模型而定。一般而言 150 筆取樣約數分鐘到十餘分鐘。系統預設處理時限為 110 分鐘，超過會自動標記為失敗。

### Q：分析失敗了怎麼辦？ <a href="#faq-failure" id="faq-failure"></a>

若狀態顯示「失敗」，可從報告列表查看「錯誤訊息」欄位。常見訊息與處理方式：

* 「Analysis timed out — the worker may have crashed during processing.」處理超過時限：建議調降「最大取樣數」減少分析量後重試
* 「Analysis task was never picked up by a worker.」任務未被分派：稍後再試一次即可
* 其他訊息：可截圖回報給 MaiAgent 服務窗口協助排查

{% hint style="info" %}
若是**額度不足**，會在建立分析時就直接被擋下並提示，不會出現在「失敗」狀態的報告中。
{% endhint %}

### Q：為什麼我的帳號看不到「對話平台分析」？ <a href="#faq-permission" id="faq-permission"></a>

「對話平台分析」是「客服對話」存取權限的子項。預設只要 MaiAgent 角色具備「客服對話」存取權限，就會包含此功能。

如果看不到，可能是：

* 您的 MaiAgent 角色沒有「客服對話」存取權限
* 組織管理員針對您的角色關閉了「對話平台分析」子權限

請聯絡組織管理員，到[角色權限管理](/org/role-permission.md)頁面檢查並調整。

***

## 注意事項 <a href="#notes" id="notes"></a>

{% hint style="info" %}
**權限說明**

* 「對話平台分析」是「客服對話」存取權限的子項，預設包含在所有具備「客服對話」權限的 MaiAgent 角色內
* 組織管理員可至[角色權限管理](/org/role-permission.md)頁面調整此功能對不同角色的開放
* 具備此權限的成員可建立與檢視所屬組織內的所有分析報告
  {% endhint %}

{% hint style="warning" %}
**成本提醒**

* 每次分析會消耗 LLM Input / Output Token 與 Embedding Token
* 建議在建立前於 Modal 中確認日期範圍與最大取樣數
* 可在進階設定中調整最大取樣數以控制成本上限
  {% endhint %}

{% hint style="danger" %}
**資料保護**

* 分析過程會將對話內容傳送給所選的 LLM 進行處理
* 請依組織資料處理政策選擇合規的模型
  {% endhint %}

***

## 相關功能 <a href="#related" id="related"></a>

{% hint style="info" %}
**延伸閱讀**

* [使用分析](/org/usage.md)：AI 助理層級的量化 KPI 儀表板
* [對話平台搜尋功能](/conversations/inbox-search.md)：快速搜尋特定對話
* [對話檢視器](/conversations/conversation-viewer.md)：查看單筆對話完整脈絡
* [評估洞察報告](https://github.com/Playma-Co-Ltd/maiagent-user-guide-gitbook/blob/main/zh-tw/channels/evaluation-insights.md)：AgentOps 批次測試後的自動洞察
  {% endhint %}


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.maiagent.ai/conversations/inbox-analysis.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.