Usage, Quota & Spend Tracking (中文 (繁體))

概覽

每個流經 OmniRoute 的請求都會產生一筆使用量記錄，其中包含：

識別資訊：使用了哪個 API 金鑰、提供者、模型及組合
權杖：提示詞權杖、補全權杖、快取權杖及總量
成本：美元金額（根據定價資料計算）
時間資訊：延遲、開始／結束時間戳記
狀態：成功、錯誤、受到速率限制等

這些記錄會彙總為分析資料、以配額快照的形式持久保存，並用於強制執行每個金鑰的預算限制。

請求 ──▶ chatCore ──▶ usage.record() ──▶ SQLite
                                  │
                          ┌───────┼───────┐
                          ▼       ▼       ▼
                      分析      配額     計費
                   （儀表板） （強制執行）（匯出）

記錄的內容

usage.ts 服務會為每個請求擷取一個使用量事件：

欄位	類型	來源
`id`	string	記錄時產生的 UUID
`apiKeyId`	string	發起請求的 API 金鑰
`provider`	string	提供者 ID（openai、anthropic 等）
`model`	string	模型 ID（gpt-5、claude-opus-4-6 等）
`comboId`	string?	若透過組合進行路由，則為組合 ID
`promptTokens`	number	來自上游回應
`completionTokens`	number	來自上游回應
`cachedTokens`	number	快取命中的權杖（Anthropic 提示詞快取等）
`totalTokens`	number	提示詞 + 補全
`costUsd`	number	根據定價資料計算
`latencyMs`	number	端對端請求持續時間
`status`	enum	`success`、`error`、`rate_limited`、`timeout`、`cancelled`
`errorClass`	string?	若 status != success，則為錯誤類別
`timestamp`	string	ISO 8601 UTC
`metadata`	object	外掛程式注入的自訂資料

權杖的來源

權杖是在回應處理常式中，從上游提供者的回應擷取：

// 來自 open-sse/handlers/chatCore.ts
const response = await providerExecutor.execute(provider, request);
const usage = response.usage || {
  prompt_tokens: 0,
  completion_tokens: 0,
  cached_tokens: 0,
};

對於未傳回使用量的提供者（例如某些使用 Web Cookie 的提供者），OmniRoute 會使用 每個權杖約 4 個字元 的啟發式方法估算權杖數量（請參閱 open-sse/services/autoCombo/pipelineRouter.ts）。

快取權杖

OmniRoute 會分別追蹤 cached_tokens 與 prompt_tokens，原因如下：

Anthropic 提示詞快取會對快取權杖收取較低的費率（一般費率的 10%）
某些提供者會傳回 cache_read_input_tokens，這些權杖應採用不同的計價方式
分析資料可以顯示快取命中率 = cached_tokens / prompt_tokens

成本計算

成本是根據從 LiteLLM 同步的定價資料計算得出（src/lib/pricingSync.ts）：

模型	輸入 $/1M	輸出 $/1M	快取 $/1M
gpt-5	$2.50	$10.00	—
claude-opus-4-6	$15.00	$75.00	$1.50
claude-sonnet-4-5	$3.00	$15.00	$0.30
gemini-2.5-pro	$1.25	$10.00	—

成本公式（src/lib/usage/costCalculator.ts）：

cost =
  (prompt_tokens - cached_tokens) * input_price +
  cached_tokens * cached_price +
  completion_tokens * output_price;

為什麼要從提示詞中扣除快取部分？ 快取部分會單獨計價；如果對整個提示詞收取輸入價格，便會重複計算。

定價同步

定價資料會透過 /api/pricing/sync 端點自動從 LiteLLM 同步（由內建的 cron 工作觸發，而非使用者可設定的環境變數）：

# 手動觸發
curl -X POST http://localhost:20128/api/pricing/sync

對於沒有定價資料的模型，OmniRoute 會改用內部平均費率來估算成本（資料來源為 LiteLLM 的定價資料）。

日期範圍彙總

usageAnalytics.ts 模組會根據原始用量資料計算儀表板小工具。它支援 7 種時間範圍：

範圍	時間區間	使用情境
`1d`	過去 24 小時	偵測每小時成本突增
`7d`	過去 7 天	每週檢視
`30d`	過去 30 天	每月計費
`90d`	過去 90 天	每季分析
`ytd`	自當年度 1 月 1 日起	追蹤年度預算
`all`	所有時間	全期統計資料
`custom`	使用者定義的開始／結束日期	稽核、臨時查詢

計算的儀表板小工具

對於任何日期範圍，分析層都會計算：

小工具	說明
摘要卡片	請求總數、總成本、權杖總數、成功率
每日趨勢圖	每日成本與權杖數量，依模型堆疊顯示
活動熱圖	時段 × 星期幾的網格，顏色 = 請求數量
模型明細	各模型成本的圓餅圖
提供者明細	各提供者請求數量的長條圖
熱門 API 金鑰	依成本排序的前 10 個金鑰表格
錯誤分析	隨時間變化的錯誤率、最常見的錯誤類別

程式化存取

import { computeAnalytics } from "@/lib/usageAnalytics";

const analytics = await computeAnalytics(
  history,              // 用量歷史記錄
  "7d",                 // 時間範圍："1d" | "7d" | "30d" | "90d" | "ytd" | "all" | "custom"
  connectionMap,        // 提供者連線對應表（connectionId → 帳戶名稱）
  {
    startDate: "2025-01-01",  // 選用：用於 "custom" 範圍
    endDate: "2025-06-01",   // 選用：用於 "custom" 範圍
  }
);

console.log(analytics.summary.totalCost);   // 12.34（美分）
console.log(analytics.byModel[0]);           // { model, cost, requests, promptTokens, completionTokens }

---

## 配額強制執行

每個 API 金鑰的配額會在兩個位置強制執行：

1. **軟性限制** (`quotaWarnAt`)：當使用量超過閾值時，在儀表板顯示警告
2. **硬性限制** (`quotaLimit`)：超過限制時，以 HTTP 429 拒絕請求

### 設定

```ts
// 每個 API 金鑰
await updateApiKey(keyId, {
  quotaWarnAt: 5_00,    // $5.00 — 顯示警告
  quotaLimit: 10_00,    // $10.00 — 強制停止
  quotaWindow: "month", // "day" | "week" | "month" | "all"
});

強制執行流程

請求 ──▶ quotaCheck()
              │
              ├── 未超過限制？  ──▶ 允許
              │
              └── 超過限制？  ──▶ 429 Too Many Requests
                                   並附上 Retry-After 標頭

配額快照

quotaSnapshots 資料表會儲存歷史配額狀態，以供趨勢分析：

每個成本 > 0 的請求都會建立快照，並用於：

在儀表板中呈現配額進度列
顯示 30 天配額趨勢圖
當使用量接近限制時觸發警示

REST API

列出使用量記錄

GET /api/usage?range=7d&limit=100
GET /api/usage?apiKeyId=key-123&range=30d
GET /api/usage?provider=openai&range=1d

回應：

{
  "records": [
    {
      "id": "uuid",
      "apiKeyId": "key-123",
      "provider": "openai",
      "model": "gpt-5",
      "promptTokens": 1234,
      "completionTokens": 567,
      "totalTokens": 1801,
      "costUsd": 0.005,
      "latencyMs": 1234,
      "status": "success",
      "timestamp": "2026-06-08T12:00:00Z"
    }
  ],
  "total": 1234,
  "nextCursor": "..."
}

取得分析摘要

GET /api/usage/analytics?range=7d&groupBy=model

回應：

{
  "summary": {
    "totalCost": 12.34,
    "totalRequests": 5678,
    "totalTokens": 12345678,
    "successRate": 0.987,
    "avgLatencyMs": 1234
  },
  "models": [
    { "model": "gpt-5", "cost": 8.5, "requests": 1234, "tokens": 4567890 },
    {
      "model": "claude-opus-4-6",
      "cost": 3.84,
      "requests": 234,
      "tokens": 234567
    }
  ],
  "daily": [
    { "date": "2026-06-01", "cost": 1.5, "requests": 800 },
    { "date": "2026-06-02", "cost": 2.0, "requests": 1000 }
  ]
}

查詢使用量分析

使用量資料透過儀表板或 MCP 工具存取，而非直接透過 REST 匯出端點。可用的分析包括：

/api/usage/analytics — 彙總的使用量指標（依模型、提供者、金鑰分組）
/api/usage/quota — 每個 API 金鑰目前的配額狀態
/api/usage/history — 請求歷史記錄

MCP 工具

有兩個 MCP 工具會向代理程式提供使用量資料（請參閱 open-sse/mcp-server/tools/）：

工具	說明
`omniroute_cost_report`	產生指定期間內每個金鑰的成本報告
`omniroute_check_quota`	傳回 API 金鑰目前的配額狀態

代理程式呼叫範例：

{
  "tool": "omniroute_cost_report",
  "args": { "period": "week" }
}

保留與清理

每個請求的使用量資料約增長 1-10KB。在大規模使用下，這可能相當可觀。

保留設定

使用量歷程的保留期限可透過 UI 中的「資料庫設定」或 /api/settings/database 進行設定。

預設情況下，使用量歷程會保留 90 天。

清理

舊記錄由 src/lib/db/cleanup.ts 清理：

由背景 cron 程序觸發
刪除 usage_history 中早於已設定 usageHistory 保留期限的記錄

儲存空間估算

請求速率	30 天儲存空間	90 天儲存空間
100 次請求/天	~3MB	~9MB
1,000 次請求/天	~30MB	~90MB
10,000 次請求/天	~300MB	~900MB
100,000 次請求/天	~3GB	~9GB

對於流量非常高的情況，請考慮：

透過「資料庫設定」縮短保留期限
使用 aggregated_metrics 取代原始記錄（僅供分析使用）

成本最佳化技巧

1. 使用正確的模型

# 快速回答 — 使用便宜且快速的模型
curl -d '{"model":"auto/fast","messages":[...]}'

# 複雜任務 — 使用高品質模型
curl -d '{"model":"auto/smart","messages":[...]}'

2. 啟用快取

Anthropic 提示詞快取可在重複的上下文上節省 90% 的成本：

// 快取會自動進行 — 只需包含相同的大型系統提示詞
const response = await openai.chat({
  model: "claude-sonnet-4-5",
  system: longSystemPrompt, // 將自動快取
  messages: [{ role: "user", content: "..." }],
});

3. 使用壓縮

RTK + Caveman 壓縮可在大量使用工具的工作階段中節省 15-95% 的成本：

const config = {
  compression: {
    engine: "rtk",
    intensity: "aggressive",
  },
};

4. 設定每個金鑰的配額

請務必設定 quotaLimit，以防止成本失控：

await updateApiKey(keyId, { quotaLimit: 10_00 }); // 每月上限 $10

5. 稽核主要使用者

使用儀表板或 /api/usage/analytics，依 API 金鑰分組並按成本排序：

GET /api/usage/analytics?groupBy=apiKey

疑難排解

「成本高於預期」

檢查 /api/usage/analytics?groupBy=model — 找出昂貴的模型
檢查 /api/usage/analytics?groupBy=apiKey — 找出高用量使用者
確認定價資料為最新版本：POST /api/pricing/sync

「記錄遺失」

檢查「儀表板 → 資料庫 → 清理」下的資料庫保留設定 — 舊記錄會由定期清理工作刪除（src/lib/db/cleanup.ts）
檢查 src/lib/db/usage*.ts 中是否有錯誤 — 資料庫寫入失敗會被記錄，但不會顯示給使用者
確認請求確實到達 chatCore — 檢查組合路由

「配額未生效」

檢查金鑰的 quotaLimit 設定
確認 quotaWindow 設定正確
尋找 quotaSnapshots 記錄 — 每次請求都應建立這些記錄

另請參閱

DATABASE_GUIDE.md — 使用量資料表的結構描述
ENVIRONMENT.md — 定價同步環境變數
AUTO-COMBO.md — auto/fast、auto/cheap 如何降低成本
API_REFERENCE.md — 完整的 /api/usage/* 參考資料
原始碼：open-sse/services/usage.ts、src/lib/usageAnalytics.ts、src/lib/db/usage*.ts

OmniRoute 原始碼 (a58000c7685f)

HagiCode

HagiCode 是智慧代理程式開發工作台，結合結構化工作流程、多代理程式執行與 Hero Dungeon 介面，將想法化為交付成果。

以更聰明、更快速且更有趣的智慧代理程式工作流程，打造實用的軟體。

Smart結構化流程將意圖轉化為從構想到交付的可執行步驟。
Efficient多代理程式工作流程讓研究、實作與審查並行進行。
FunHero Dungeon 讓長時間的程式協作更直覺、更有參與感。

造訪 HagiCode

選擇語言