用量與成本分析

了解 AI 模型的使用情況對於管理成本、監控效能和確保資源公平分配至關重要。本文件詳細介紹了如何查詢用量統計、追蹤成本，以及解讀 AIGNE Hub 用於分析和報告的資料模型。

總覽

AIGNE Hub 將每次 API 互動記錄為一筆 ModelCall 項目。這些記錄是所有用量分析的基礎。系統提供了多個 API 端點來查詢和匯總這些資料，讓您可以監控整個系統或每個使用者的消耗情況。這使得對權杖用量、點數消耗和整體 API 呼叫量進行詳細追蹤成為可能。

資料模型

了解底層資料結構對於有效查詢和解讀分析資料至關重要。下圖說明了 ModelCall 記錄是如何生成並被分析端點使用的。

Usage & Cost Analytics

ModelCall 物件

每個透過 Hub 向 AI 供應商發出的請求都會被記錄為一筆 ModelCall。此物件包含有關請求、其執行情況以及相關成本的詳細資訊。

id string (required) — 模型呼叫記錄的唯一識別碼。
providerId string (required) — 用於該呼叫的 AI 供應商的識別碼。
model string (required) — 被呼叫的具體模型（例如 'gpt-4o-mini'）。
credentialId string (required) — 用於向供應商進行身份驗證的憑證 ID。
type string (required) — API 呼叫的類型。可能的值包括 'chatCompletion'、'embedding'、'imageGeneration'、'audioGeneration'、'video' 或 'custom'。
totalUsage number (required) — 一個標準化的用量指標。對於文字模型，這通常是權杖總數（輸入 + 輸出）。
usageMetrics object — 用量的詳細分類，例如輸入和輸出權杖。
- inputTokens number — 輸入提示中的權杖數量。
- outputTokens number — 生成回應中的權杖數量。
credits number (required) — 根據配置的模型費率，該呼叫消耗的點數。
status string (required) — 呼叫的最終狀態。可以是 'success' 或 'failed'。
duration number — API 呼叫的持續時間，單位為秒。
errorReason string — 如果呼叫失敗，此欄位包含失敗的原因。
appDid string — 發起呼叫的應用程式的 DID。
userDid string (required) — 發出呼叫的使用者的 DID。
requestId string — 一個可選的客戶端請求識別碼，用於追蹤。
callTime number (required) — 發出呼叫時的 Unix 時間戳。
createdAt string (required) — 在資料庫中創建此記錄的時間戳。

查詢用量資料

您可以透過多個 REST API 端點來擷取分析資料。這些端點需要身份驗證。

取得用量統計

若要取得特定時段內用量的摘要和匯總視圖，請使用 GET /api/user/usage-stats 端點。對於全系統的分析，管理員可以使用 GET /api/user/admin/user-stats。

請求參數

startTime string (required) — 時間範圍的開始，以 Unix 時間戳表示。
endTime string (required) — 時間範圍的結束，以 Unix 時間戳表示。
allUsers boolean — 使用 /api/user/model-calls 時，設為 true 以取得所有使用者的資料。此功能僅限管理員使用。

請求範例

請求使用者統計資料

curl -X GET 'https://your-aigne-hub-url/api/user/usage-stats?startTime=1672531200&endTime=1675228799' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>'

回應內文

此端點會返回一個全面的物件，其中包含摘要、每日明細、模型統計和趨勢比較。

summary object — 一個包含指定期間內匯總總計的物件。
- totalCredits number — 消耗的總點數。
- totalCalls number — API 呼叫總次數。
- modelCount number — 使用的獨立模型總數。
- byType object — 一個按呼叫類型（例如 'chatCompletion'）分類的用量統計物件。
  - [callType] object
    - totalUsage number — 此類型的總用量（例如，權杖數）。
    - totalCredits number — 此類型消耗的總點數。
    - totalCalls number — 此類型的總呼叫次數。
    - successCalls number — 此類型的成功呼叫次數。
dailyStats array — 一個物件陣列，每個物件代表一天的用量統計。
- date string — 日期，格式為 'YYYY-MM-DD'。
- credits number — 當天消耗的總點數。
- tokens number — 當天處理的總權杖數。
- requests number — 當天發出的 API 呼叫總次數。
modelStats array — 一個列出最常用模型的陣列。
- providerId string — 該模型的供應商 ID。
- model string — 模型的名稱。
- totalCalls number — 對此模型發出的總呼叫次數。
trendComparison object — 當前期間與上一期間的用量比較。
- current object — 當前期間的統計資料。
- previous object — 對應的上一期間的統計資料。
- growth object — 兩個期間之間的增長率。

列出模型呼叫

若要取得按時間順序排列的個別 API 請求詳細日誌，請使用 GET /api/user/model-calls 端點。此端點提供對原始 ModelCall 記錄的存取，並支援分頁和篩選。

請求參數

page number (default: 1) — 分頁的頁碼。
pageSize number (default: 50) — 每頁返回的項目數。最大值為 100。
startTime string — 時間範圍的開始，以 Unix 時間戳表示。
endTime string — 時間範圍的結束，以 Unix 時間戳表示。
search string — 用於按模型名稱、應用程式 DID 或使用者 DID 篩選結果的搜尋詞。
status string — 按呼叫狀態篩選。可以是 'success'、'failed' 或 'all'。
model string — 按特定模型名稱篩選。
providerId string — 按特定供應商 ID 篩選。
appDid string — 按特定應用程式 DID 篩選。
allUsers boolean — 如果為 true，則返回所有使用者的模型呼叫（僅限管理員）。

請求範例

列出模型呼叫

curl -X GET 'https://your-aigne-hub-url/api/user/model-calls?page=1&pageSize=10&status=failed' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>'

回應內文

回應是一個包含 ModelCall 物件的分頁列表。

response.json

{
  "count": 1,
  "list": [
    {
      "id": "z8VwXGf6k3qN...",
      "providerId": "openai",
      "model": "gpt-4o-mini",
      "credentialId": "z3tXy..._default",
      "type": "chatCompletion",
      "totalUsage": 150,
      "usageMetrics": {
        "inputTokens": 100,
        "outputTokens": 50
      },
      "credits": 0.0002,
      "status": "failed",
      "duration": 2,
      "errorReason": "API key is invalid.",
      "appDid": "z2qa9sD2tFAP...",
      "userDid": "z1...",
      "requestId": null,
      "callTime": 1675228799,
      "createdAt": "2023-01-31T23:59:59.000Z",
      "updatedAt": "2023-01-31T23:59:59.000Z",
      "traceId": null,
      "provider": {
        "id": "openai",
        "name": "openai",
        "displayName": "OpenAI",
        "baseUrl": "https://api.openai.com/v1",
        "region": null,
        "enabled": true
      },
      "appInfo": {
        "appName": "My AI App",
        "appDid": "z2qa9sD2tFAP...",
        "appLogo": "...",
        "appUrl": "..."
      },
      "userInfo": {
        "did": "z1...",
        "fullName": "John Doe",
        "email": "john.doe@example.com",
        "avatar": "..."
      }
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 10
  }
}

匯出模型呼叫

您可以使用 GET /api/user/model-calls/export 端點將模型呼叫歷史記錄匯出為 CSV 檔案，以進行離線分析或報告。此端點接受與列表端點相同的篩選參數。

請求範例

匯出模型呼叫

curl -X GET 'https://your-aigne-hub-url/api/user/model-calls/export?startTime=1672531200&endTime=1675228799' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
-o model-calls-export.csv

伺服器將回應一個 text/csv 檔案，其中包含您請求的資料。

總結

AIGNE Hub 中的分析功能提供了強大的工具，用於監控和了解 AI 模型的使用情況。透過利用 ModelCall 資料模型和相關的 API 端點，您可以建立儀表板、生成報告，並獲得對營運成本和效能的關鍵洞察。

有關點數如何配置和計費的詳細資訊，請參閱服務供應商模式文件。