> 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/others/usage-statistics.md).

# 用量統計

組織設定「用量統計」頁的完整說明：誰可以使用與如何依角色限定只看授權 Agent、篩選條件、用量概覽與快取節省、各分頁（Agent、角色、成員、對話平台、聯絡人、語音助理、計費類別）的欄位定義、角色用量的計算方式、「未知」代表什麼，以及為什麼和額度頁的數字不同。

<mark style="color:blue;">用量統計</mark> 是管理員查看組織用量的主要入口：可以依時間區間看整體趨勢，也能從 Agent、角色、成員、對話平台、聯絡人等角度排名，找出用量最多的對象，並匯出 Excel。Credits 計費的組織還能查看 Credit 消耗、各計費類別的明細與快取節省。

## 誰可以使用 <a href="#permissions" id="permissions"></a>

* 需要角色權限 <mark style="color:blue;">組織權限</mark> 底下的 <mark style="color:blue;">用量統計權限</mark>（組織擁有者預設具備；設定方式見[編輯角色權限](/org/roles/role-permission.md#edit-role-permissions)）。
* <mark style="color:blue;">Credits</mark> 指標、Credit 欄位與 <mark style="color:blue;">計費類別</mark> 分頁，只在採用 Credits 計費的組織出現（見 [Credits 計費制度](/others/credits.md)）。
* 可以依角色限定成員只看自己被授權的 Agent 的用量，見[只看授權 Agent 的用量](#scope-to-authorized-agents)。

## 只看授權 Agent 的用量 <a href="#scope-to-authorized-agents" id="scope-to-authorized-agents"></a>

有用量統計權限的角色，可以再設定 <mark style="color:blue;">用量統計範圍</mark>，決定成員在這一頁看得到多少：

| 選項                                       | 成員看到的數據                                                                                         |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">全組織</mark>（預設） | 整個組織的用量                                                                                         |
| <mark style="color:blue;">僅授權助理</mark>   | 只有成員所屬角色被分配的 Agent 產生的用量（Agent 的分配方式見[分配 AI 助理](/org/roles/role-permission.md#assign-chatbots)） |

例如：客服部門的 Agent 管理員負責部門的 3 個 Agent，需要追蹤它們的用量，但組織不希望他看到其他部門的數字。管理員把他所屬角色的用量統計範圍改成 <mark style="color:blue;">僅授權助理</mark> 後，他打開用量統計，頁面上方會提示目前只顯示授權範圍，<mark style="color:blue;">AI 助理</mark>、<mark style="color:blue;">成員</mark> 等分頁也只計算這 3 個 Agent 的用量。

### 設定步驟 <a href="#scope-setup" id="scope-setup"></a>

1. 從左側選單點選 <mark style="color:blue;">組織設定</mark> → <mark style="color:blue;">組織概覽</mark>，在 <mark style="color:blue;">管理操作</mark> 區點選 <mark style="color:blue;">編輯角色權限</mark>。
2. 在角色列表點選要設定的角色的 <mark style="color:blue;">編輯</mark>，進入 <mark style="color:blue;">角色權限</mark> 分頁。
3. 勾選 <mark style="color:blue;">組織權限</mark> 底下的 <mark style="color:blue;">用量統計權限</mark>，權限清單下方會出現 <mark style="color:blue;">用量統計範圍</mark>。
4. 選擇 <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-9c959d9448d4149fb0b42d5a39b73a5a411e9886%2Fusage-statistics-role-scope-setting.png?alt=media" alt="角色權限分頁下方的用量統計範圍設定，選擇僅授權助理"><figcaption><p>勾選用量統計權限後，在角色權限分頁下方設定用量統計範圍</p></figcaption></figure>

取消勾選 <mark style="color:blue;">用量統計權限</mark> 時，這個設定會一併隱藏。擁有者一律看全組織，擁有者角色沒有這項設定。

### 成員實際看到的範圍 <a href="#scope-resolution" id="scope-resolution"></a>

* **有一個角色是全組織，就看全組織**：成員所屬的角色中，只要有任何一個具備用量統計權限、且範圍是 <mark style="color:blue;">全組織</mark>，他看到的就是全組織。所有給他用量統計權限的角色都設為 <mark style="color:blue;">僅授權助理</mark> 時，才只看授權 Agent。
* **授權 Agent 是所有角色加總**：「所屬角色被授權的 Agent」是成員所有角色（包含預設角色）在 <mark style="color:blue;">分配 AI 助理</mark> 分配到的 Agent 合在一起。成員若有 MaiGPT 使用權限，MaiGPT 的用量也在範圍內。

{% hint style="warning" %}
**留意預設角色**

* 每位成員都有預設角色，預設角色分配到的 Agent 會算進每個人的授權範圍。預設角色開放的 Agent 很多時，設成 <mark style="color:blue;">僅授權助理</mark> 能縮小的範圍就有限。
* 預設角色如果也勾了 <mark style="color:blue;">用量統計權限</mark>，且範圍維持 <mark style="color:blue;">全組織</mark>，所有成員都會看全組織，其他角色設成 <mark style="color:blue;">僅授權助理</mark> 不會生效。
  {% endhint %}

### 範圍限縮後的畫面 <a href="#scoped-view" id="scoped-view"></a>

* <mark style="color:blue;">用量概覽</mark> 上方會顯示提示：「您的角色用量統計範圍為「僅授權助理」，目前僅顯示您所屬角色可存取之 AI 助理的用量數據。」
* 用量概覽、各分頁與 <mark style="color:blue;">匯出 Excel</mark> 都只計入授權 Agent 的用量；不屬於任何 Agent 的消耗（例如知識庫儲存的每日計費）不會出現。
* <mark style="color:blue;">Credit 消耗</mark> 卡的 <mark style="color:blue;">餘額</mark> 仍是組織錢包的餘額；<mark style="color:blue;">預估剩餘</mark> 顯示為「-」，因為只看部分 Agent 的消耗無法推算組織餘額還能用多久。

## 進入方式 <a href="#how-to-enter" id="how-to-enter"></a>

從左側選單點選 <mark style="color:blue;">組織設定</mark> → <mark style="color:blue;">用量統計</mark>。

## 篩選條件 <a href="#filters" id="filters"></a>

頁面最上方的篩選列會套用到整頁：

| 篩選   | 選項                                                                                                                                                                                                         |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 時間粒度 | <mark style="color:blue;">每小時</mark>、<mark style="color:blue;">每日</mark>（預設）、<mark style="color:blue;">每月</mark>，決定圖表橫軸的間隔                                                                                 |
| 日期區間 | 預設為最近 30 天                                                                                                                                                                                                 |
| 指標   | <mark style="color:blue;">Token</mark>、<mark style="color:blue;">字數</mark>、<mark style="color:blue;">訊息</mark>、<mark style="color:blue;">對話</mark>、<mark style="color:blue;">Credits</mark>，決定圖表與排名依哪個數字計算 |
| 時區   | <mark style="color:blue;">當地時區</mark>、<mark style="color:blue;">UTC 時區</mark>，只影響圖表時間軸的顯示                                                                                                                  |

按 <mark style="color:blue;">重置篩選</mark> 可回到預設值。切到 <mark style="color:blue;">語音助理</mark> 分頁時，指標選單會換成 <mark style="color:blue;">STT 秒數</mark>、<mark style="color:blue;">TTS 字數</mark>、<mark style="color:blue;">語音模型 Token 數</mark> 與 <mark style="color:blue;">Credits</mark>。

## 用量概覽 <a href="#overview-cards" id="overview-cards"></a>

<mark style="color:blue;">用量概覽</mark> 以卡片顯示所選期間的總量：

| 卡片                                                                                           | 內容                                                                                                                                                 |
| -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">字數</mark>                                                          | 輸入、輸出與合計的字數                                                                                                                                        |
| TOKEN                                                                                        | 輸入、輸出與合計的 Token 數                                                                                                                                  |
| <mark style="color:blue;">訊息總數</mark>／<mark style="color:blue;">對話總數</mark>                  | 所選期間的訊息與對話數量                                                                                                                                       |
| <mark style="color:blue;">Credit 消耗</mark>（Credits 計費組織）                                     | Credit 消耗、<mark style="color:blue;">快取節省</mark>、錢包 <mark style="color:blue;">餘額</mark>，以及依期間日均消耗推算的 <mark style="color:blue;">預估剩餘</mark> 天數（僅供參考） |
| <mark style="color:blue;">STT / TTS 用量</mark>、<mark style="color:blue;">語音模型 Token 總數</mark> | 第二列，顯示語音通話的 STT 總秒數、TTS 總字數與語音模型 Token 數                                                                                                           |

<mark style="color:blue;">快取節省</mark> 是平台自動啟用 Prompt 快取後，所選期間累計省下的 Credits；淨節省大於 0 時才會顯示。快取的運作方式見 [Prompt Cache 快取用量](/others/credits.md#prompt-cache-usage)。

## 各分頁 <a href="#tabs" id="tabs"></a>

| 分頁                                     | 內容                                                                                                                         |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">趨勢</mark>    | 所選指標的 <mark style="color:blue;">使用量趨勢</mark>：每個時間點的用量與累積用量                                                                 |
| <mark style="color:blue;">AI 助理</mark> | 依 Agent 統計                                                                                                                 |
| <mark style="color:blue;">角色</mark>    | 依角色統計，計算方式見[角色分頁怎麼算](#role-tab-aggregation)                                                                                |
| <mark style="color:blue;">成員</mark>    | 依成員統計，含 <mark style="color:blue;">成員名稱</mark> 與 <mark style="color:blue;">成員 Email</mark>，是查看「每個人用了多少」的地方                  |
| <mark style="color:blue;">對話平台</mark>  | 依對話平台統計；<mark style="color:blue;">類型</mark> 欄會區分網頁、內部、API 等來源                                                              |
| <mark style="color:blue;">聯絡人</mark>   | 依聯絡人統計，每一列是「聯絡人 × Agent」，外部訪客的用量在這裡查                                                                                       |
| <mark style="color:blue;">語音助理</mark>  | 依 Agent 統計語音通話的 STT 秒數、語音模型 Token、TTS 字數與 <mark style="color:blue;">語音對話次數</mark>                                          |
| <mark style="color:blue;">計費類別</mark>  | 指標切到 <mark style="color:blue;">Credits</mark> 才會出現，依計費類別（例如 AI 文字生成與理解模型、知識庫與向量檢索系統）列出 Credit 消耗，可展開看各供應商與模型的消耗，以及各成員的消耗明細 |

除了 <mark style="color:blue;">趨勢</mark> 與 <mark style="color:blue;">計費類別</mark>，每個分頁都有三張圖（時間序列、<mark style="color:blue;">Top 10 排名</mark>、<mark style="color:blue;">使用佔比</mark>）和一張明細表。明細表上方可依 ID 或名稱搜尋，並可按 <mark style="color:blue;">匯出 Excel</mark> 依目前分頁、日期區間與搜尋條件下載資料。

{% hint style="info" %}
用量會在訊息處理完成後由背景作業累計，最新的對話可能需要稍候才會出現在統計中。<mark style="color:blue;">計費類別</mark> 的數字來自定期預聚合，可能因非同步扣款與小數四捨五入，和即時帳單有些許出入。
{% endhint %}

## 欄位定義 <a href="#column-definitions" id="column-definitions"></a>

| 欄位                                                                                                                           | 定義                                         |
| ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| <mark style="color:blue;">輸入字數</mark>／<mark style="color:blue;">輸出字數</mark>／<mark style="color:blue;">總字數</mark>             | 訊息內容的字元數。使用者發送的訊息計入輸入，Agent 的回覆計入輸出        |
| <mark style="color:blue;">輸入 Token</mark>／<mark style="color:blue;">輸出 Token</mark>／<mark style="color:blue;">總 Token</mark> | 模型處理的 Token 數。總 Token＝輸入＋輸出，不含快取           |
| <mark style="color:blue;">快取寫入</mark>／<mark style="color:blue;">快取讀取</mark>                                                  | 寫入 Prompt 快取、以及從快取讀取的 Token 數              |
| <mark style="color:blue;">快取命中率</mark>                                                                                       | 快取讀取 ÷（輸入 Token＋快取寫入＋快取讀取）                 |
| <mark style="color:blue;">訊息數</mark>                                                                                         | 每則訊息計 1 次，使用者的訊息與 Agent 的回覆都會計入            |
| <mark style="color:blue;">對話數</mark>                                                                                         | 新對話的第一則訊息出現時計 1 次                          |
| Credits                                                                                                                      | 所選期間的 Credit 消耗                            |
| <mark style="color:blue;">交易次數</mark>                                                                                        | Credit 扣款的筆數。一次對話可能產生多筆，例如模型用量、快取與工具呼叫各自計費 |

指標選 <mark style="color:blue;">Token</mark> 時，排名圖與佔比圖的數字會把快取寫入與快取讀取一起算進去，因此可能比表格的 <mark style="color:blue;">總 Token</mark> 大。

各分頁上方的總數（成員分頁的 <mark style="color:blue;">成員數</mark>、Agent 分頁的 Agent 數等，API 回應中為 `totalMembers`、`totalChatbots`）是**所選期間內有用量紀錄的對象數**（去重），不是組織目前的成員或 Agent 總數。例如要知道「這週有多少人問過問題」，把期間設為本週後看成員分頁的成員數即可；期間依所選日期的整天計算。

## 角色分頁怎麼算 <a href="#role-tab-aggregation" id="role-tab-aggregation"></a>

角色的用量是**該角色目前所有成員的個人用量加總**，不是「透過這個角色產生的用量」：

* 成員同時屬於多個角色時，他的用量會完整計入每一個角色。例如一位成員同屬 3 個角色、期間內只有他有用量，這 3 個角色會顯示一模一樣的數字。
* 因此各角色的數字加總，可能大於組織實際的總用量。
* 以查詢當下的角色成員名單計算：成員加入角色之前的用量也會算進這個角色；成員離開角色後，他的用量就不再計入。

## 「未知」代表什麼 <a href="#unknown-bucket" id="unknown-bucket"></a>

指標切到 <mark style="color:blue;">Credits</mark> 時，<mark style="color:blue;">成員</mark>、<mark style="color:blue;">對話平台</mark> 等分頁的排名圖與佔比圖可能出現「未知」。它代表這部分 Credit 消耗無法歸屬到某位成員；在 <mark style="color:blue;">對話平台</mark> 分頁則代表不屬於任何對話平台的消耗，例如知識庫儲存。<mark style="color:blue;">成員</mark> 分頁的「未知」常見來源有：

| 來源         | 說明                                           | 去哪裡看明細                                   |
| ---------- | -------------------------------------------- | ---------------------------------------- |
| 外部訪客       | 透過網頁 Web Chat、LINE 等對話平台與 Agent 對話的訪客，不是組織成員 | <mark style="color:blue;">聯絡人</mark> 分頁  |
| 已停用或已移除的成員 | 消耗發生時，對應的成員已不是組織的有效成員                        | —                                        |
| 系統計費       | 不由特定成員觸發的計費，例如知識庫儲存的每日計費，或找不到發起成員的自動作業       | <mark style="color:blue;">計費類別</mark> 分頁 |

## 為什麼和額度頁的數字不同 <a href="#why-differs-from-quota" id="why-differs-from-quota"></a>

<mark style="color:blue;">Credits</mark> 頁的 <mark style="color:blue;">額度分配</mark>，以及成員帳號頁的 <mark style="color:blue;">Credit 額度</mark>，「使用量」以「已用／上限」顯示。例如 `7,000.00 / 10,000.00` 代表這筆額度已用 7,000 Credits、上限 10,000 Credits。它和用量統計的數字常常對不起來，原因如下：

| 差異   | 用量統計                   | 額度                                                                                                 |
| ---- | ---------------------- | -------------------------------------------------------------------------------------------------- |
| 計算期間 | 篩選列選的日期區間（預設最近 30 天）   | 這筆額度生效、或上次重置之後的累計                                                                                  |
| 計入範圍 | 歸屬於該成員的所有用量            | 只計入額度[適用範圍](/others/credits/member-credit-quota.md#applicable-scope)內的消耗                           |
| 角色   | 以目前的角色成員，加總他們在期間內的全部用量 | 消費發生的當下，計入該成員所屬的每個受管控角色，且只從角色額度生效後開始累計（見[角色額度](/others/credits/member-credit-quota.md#role-quota)） |
| 更新時間 | 背景累計，計費類別為定期預聚合        | 每次扣款時累計                                                                                            |

要核對單筆扣款，請到 <mark style="color:blue;">Credits</mark> → <mark style="color:blue;">消耗記錄</mark>（見 [Credits 管理面板](/others/credits.md#consumption-tab)）。

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

#### Q：找不到 <mark style="color:blue;">計費類別</mark> 分頁？ <a href="#faq-credit-categories-missing" id="faq-credit-categories-missing"></a>

請先把指標切到 <mark style="color:blue;">Credits</mark>，分頁才會出現；停在這個分頁時，指標選單會鎖定為 Credits。若指標選單沒有 Credits，代表組織不是 Credits 計費。

#### Q：好幾個角色的數字一模一樣，是統計錯了嗎？ <a href="#faq-identical-roles" id="faq-identical-roles"></a>

通常不是。同一位成員屬於多個角色時，他的用量會完整計入每個角色；如果期間內只有這位成員有用量，這些角色就會顯示相同數字。詳見[角色分頁怎麼算](#role-tab-aggregation)。

#### Q：要怎麼產出每位成員的用量報表？ <a href="#faq-member-report" id="faq-member-report"></a>

切到 <mark style="color:blue;">成員</mark> 分頁、設定日期區間後按 <mark style="color:blue;">匯出 Excel</mark>。需要看 Credits 時，先把指標切到 <mark style="color:blue;">Credits</mark> 再匯出。

#### Q：外部訪客的用量算在哪裡？ <a href="#faq-visitor-usage" id="faq-visitor-usage"></a>

外部訪客不是組織成員，不會出現在 <mark style="color:blue;">成員</mark> 分頁的表格，請到 <mark style="color:blue;">聯絡人</mark> 或 <mark style="color:blue;">對話平台</mark> 分頁查看；以 Credits 檢視成員排名時，這部分會歸在「未知」。

#### Q：Agent 管理員只想看自己負責的 Agent 用量？ <a href="#faq-own-agents-only" id="faq-own-agents-only"></a>

把他所屬角色的 <mark style="color:blue;">用量統計範圍</mark> 設為 <mark style="color:blue;">僅授權助理</mark>，並在 <mark style="color:blue;">分配 AI 助理</mark> 只分配他負責的 Agent。設定步驟見[只看授權 Agent 的用量](#scope-setup)。

#### Q：角色已設為「僅授權助理」，成員還是看到全組織？ <a href="#faq-scope-still-organization" id="faq-scope-still-organization"></a>

檢查這位成員的其他角色（包含預設角色）：只要有一個角色具備 <mark style="color:blue;">用量統計權限</mark> 且範圍是 <mark style="color:blue;">全組織</mark>，他就會看全組織。另外，擁有者一律看全組織。詳見[成員實際看到的範圍](#scope-resolution)。


---

# 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/others/usage-statistics.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.