---
title: Gateway 用量與匯出
description: 用量分頁顯示花費、請求數，以及每個請求的模型、金鑰、部門和終端使用者。整月請求可從主控台或 gateway.usage.export 匯出 CSV，不含提示詞或回覆內容。
url: https://agentlab.cresclab.com/docs/zh-tw/gateway/usage
language: zh-Hant
updated: 2026-10-28
---

# Gateway 用量與匯出

用量分頁顯示花費、請求數，以及每個請求的模型、金鑰、部門和終端使用者。整月請求可從主控台或 gateway.usage.export 匯出 CSV，不含提示詞或回覆內容。

## 用量分頁

**AI Gateway › 用量**給工作區擁有者和管理員使用。選一段期間，需要的話再選一把金鑰。頁面會顯示花費、請求數和成功率、每日趨勢、依金鑰和依模型的花費、`auto` 的選擇情形，接著是每個請求：執行時間、金鑰、實際回答的模型和原因、token 數和結果。被拒絕的請求會寫出是哪個額度拒絕的。

## 終端使用者

用一把金鑰服務很多人的應用程式，可以註明每個請求是替誰發的。Gateway 會把它記錄為該請求的終端使用者：

| 端點                   | 欄位               |
| ---------------------- | ------------------ |
| `/v1/chat/completions` | `user`             |
| `/v1/responses`        | `user`             |
| `/v1/messages`         | `metadata.user_id` |

只會記錄這個識別碼，請求裡的其他內容都不會因此儲存，這個欄位也照原樣轉給供應商。請用你自己系統認得的 id，例如員工編號或雜湊過的信箱，不要用姓名。沒有註明的請求，會顯示為沒有終端使用者。

## 標籤

標籤替請求註明它的用途，例如團隊、功能或客戶，讓用量分頁可以依標籤拆分和篩選花費。在任何推論端點的 `X-AgentLab-Metadata` 標頭送一個 JSON 物件：

```bash
curl https://api.agentlab.cresclab.com/v1/chat/completions \
  -H "Authorization: Bearer $AGENTLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -H 'X-AgentLab-Metadata: {"team": "support", "feature": "summary"}' \
  -d '{"model": "auto", "messages": [{"role": "user", "content": "Hello"}]}'
```

用 SDK 時送同一個標頭，例如 Python：

```python
reply = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Hello"}],
    extra_headers={"X-AgentLab-Metadata": '{"team": "support", "feature": "summary"}'},
)
```

在 `/v1/chat/completions` 和 `/v1/responses`，OpenAI 本身的 `metadata` 內文欄位也會當成標籤讀取，並照原樣轉給供應商。同一個請求兩者都送時會合併；兩邊都有的鍵，值必須相同。這個標頭永遠不會轉給供應商。

| 規則 | 上限                                        |
| ---- | ------------------------------------------- |
| 標籤 | 每個請求最多 16 個。                        |
| 鍵   | 1 到 64 個英文字母、數字、`_`、`.` 或 `-`。 |
| 值   | 1 到 512 個字元的字串，不含控制字元。       |

標籤違反規則的請求會被拒絕，回 `400 invalid_metadata`，訊息會寫出違反的規則；標籤絕不會被悄悄丟掉。在 **AI Gateway › 用量**的明細選 **標籤**，再挑一個鍵，就能看到依各個值拆分的花費；點選一個值可把整頁縮小到它。請求詳情和 CSV 匯出都會顯示每個請求的標籤。標籤和終端使用者一樣是你自己的標記：不要放個人資料或提示詞內容。

## 匯出一個月

在用量分頁選擇**匯出 CSV**，選一個月份後下載。檔案每一列是一次請求嘗試，用 Excel 打開文字不會變亂碼，而且不含任何提示詞或回覆內容。

| 欄位                                       | 內容                                                                                 |
| ------------------------------------------ | ------------------------------------------------------------------------------------ |
| `request_id`                               | 請求的 id，和它的 `X-Request-Id` 標頭相同。                                          |
| `attempt_id`                               | 這一次嘗試。先經過 `auto` 判斷、或被重試過的請求，會有不只一次嘗試。                 |
| `started_at`                               | 嘗試開始的時間，UTC（ISO 8601）。                                                    |
| `state`                                    | `completed`、`failed`、`uncertain`（一直沒有回報用量）、`dispatched` 或 `prepared`。 |
| `model`                                    | 這次嘗試送往的模型。                                                                 |
| `decision`                                 | 為什麼是這個模型：指定模型時是 `explicit_pin`，否則是 `auto` 的判斷方式。            |
| `input_tokens`, `output_tokens`            | 量到的 token 數。不知道用量時留空。                                                  |
| `cached_read_tokens`, `cache_write_tokens` | 提示詞快取的 token 數。供應商沒有回報時留空。                                        |
| `cost_usd`                                 | 以當天該模型目錄價格計算的費用。不知道用量或價格時留空。                             |
| `key_id`, `key_name`                       | 送出這個請求的金鑰。                                                                 |
| `departments`                              | 嘗試開始時金鑰所歸屬的部門，以 `; ` 分隔。                                           |
| `end_user`                                 | 請求註明的終端使用者，沒有就留空。                                                   |
| `failure_code`                             | Gateway 有記錄時，這次嘗試沒有回答的原因，例如 `inference_allowance_exceeded`。      |
| `tags`                                     | 請求的標籤，一個 JSON 物件，例如 `{"team":"support"}`，沒有就留空。                  |

空白儲存格代表不知道，絕不代表零。月份以 UTC 的日曆月計算。開頭是 `=`、`+`、`-`、`@`、tab 或歸位字元的儲存格，會在前面加上 `'`，讓試算表顯示它而不是執行它。

## 用程式匯出

同一份檔案也可以從主控台 API 的 `gateway.usage.export` 程序分頁取得。每次呼叫最多回傳 5,000 列，CSV 文字放在 `content`，另外附上 `nextCursor`；帶著這個 cursor 再呼叫，直到它變成 `null`，再依序把每一頁的 `content` 接起來。只有第一頁帶有位元組順序標記（BOM）和標題列。呼叫者必須是工作區擁有者或管理員。