使用量与成本分析

了解 AI 模型的使用情况对于管理成本、监控性能和确保资源公平分配至关重要。本文档详细介绍了如何查询使用情况统计数据、跟踪成本以及解读 AIGNE Hub 用于分析和报告的数据模型。

概述

AIGNE Hub 将每一次 API 交互记录为一个 ModelCall 条目。这些记录是所有使用量分析的基础。系统提供了多个 API 端点来查询和聚合这些数据，让您可以监控整个系统或单个用户的使用情况。这使得对 token 使用量、积分消耗和总体 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) — 一个标准化的使用量指标。对于文本模型，这通常是 token 的总数（输入 + 输出）。
usageMetrics object — 使用量的详细分解，例如输入和输出的 token 数。
- inputTokens number — 输入提示中的 token 数量。
- outputTokens number — 生成响应中的 token 数量。
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 — 此类型的总使用量（例如 token 数）。
    - totalCredits number — 此类型消耗的总积分。
    - totalCalls number — 此类型的总调用次数。
    - successCalls number — 此类型成功调用的次数。
dailyStats array — 一个对象数组，每个对象代表一天的使用情况统计。
- date string — 日期，格式为 'YYYY-MM-DD'。
- credits number — 当天消耗的总积分。
- tokens number — 当天处理的总 token 数。
- 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 端点，您可以构建仪表盘、生成报告，并获得对运营成本和性能的关键洞察。

有关积分如何配置和计费的详细信息，请参阅服务提供商模式文档。