使用状況とコストの分析

AI モデルの消費量を把握することは、コスト管理、パフォーマンス監視、そして公正なリソース割り当てを確実にするために不可欠です。このドキュメントでは、使用統計のクエリ方法、コストの追跡方法、そして AIGNE Hub が分析とレポートに使用するデータモデルの解釈方法について詳しく説明します。

概要

AIGNE Hub は、すべての API インタラクションを ModelCall エントリとして記録します。これらの記録は、すべての使用状況分析の基礎となります。システムは、このデータをクエリして集計するためのいくつかの API エンドポイントを提供しており、システム全体またはユーザーごとの消費量を監視できます。これにより、トークンの使用状況、クレジットの消費量、および全体的な API コール量を詳細に追跡できます。

データモデル

分析データを効果的にクエリし、解釈するためには、基礎となるデータ構造を理解することが不可欠です。以下の図は、ModelCall レコードがどのように生成され、分析エンドポイントによって使用されるかを示しています。

Usage & Cost Analytics

ModelCall オブジェクト

ハブを介して 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 — 2つの期間の間の成長率。

モデルコールのリスト表示

個々の API リクエストの詳細な時系列ログについては、GET /api/user/model-calls エンドポイントを使用します。これにより、ページネーションとフィルタリングを備えた生の ModelCall レコードにアクセスできます。

リクエストパラメータ

page number (default: 1) — ページネーション用のページ番号。
pageSize number (default: 50) — 1ページあたりに返すアイテムの数。最大は 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 エンドポイントを活用することで、ダッシュボードの構築、レポートの生成、および運用コストとパフォーマンスに関する重要な洞察を得ることができます。

クレジットの設定と請求方法の詳細については、サービスプロバイダーモードのドキュメントを参照してください。