administrator-guide.md

管理者ガイド

Language: English | 简体中文 | 日本語

このガイドは、TokenHub を企業 AI ゲートウェイとして運用するプラットフォーム管理者、セキュリティ運用者、インフラ担当者向けです。

管理者の範囲

領域	責任
Provider Channels	上流 Base URL、認証情報、リソース、ヘルスチェックを設定します
Model Directory	外部 API モデル名を公開し、Provider の上流モデルインベントリを管理します
Routing Policies	優先度、重み、フェイルオーバー戦略で外部モデルを Provider モデルに割り当てます
Projects and Teams	Key、クォータ、コスト配賦の組織境界を定義します
Identity Sources	OAuth または OIDC の企業ログインを設定します
Security and Audit	リクエストログ、管理操作、Key ローテーション、ポリシー変更を確認します

本番設定順序

1. 少なくとも 1 つの ID プロバイダーを設定し、管理者アカウントを保持します。
2. OpenAI Production、Azure East US、Internal Model Gateway などの上流 Provider を追加します。
3. Provider から必要な上流モデルを選択し、Provider モデルインベントリに取り込みます。
4. 選択したモデルを同名 1:1 マッピングで公開するか、カスタム外部名とマッピングを設定します。
5. Team、Project、Cost Center、既定クォータポリシーを作成します。
6. Model Playground と Request Logs でフローを検証します。
7. Key を広く発行する前に利用量配賦を確認します。

API Key の帰属と利用量配賦

API Key を発行するときは、帰属ユーザーで実際の利用者を選択します。発行者は監査メタデータに残りますが、Key の利用量は帰属ユーザーに計上されます。プラットフォーム管理者は任意の有効ユーザー、チームリーダーは自チームの有効ユーザーを選択でき、一般ユーザーは自分だけを指定できます。

新しい利用量レコードにはその時点の帰属ユーザーが固定保存されるため、後から帰属を変更したり Key を削除したりしても、記録済みの履歴は書き換わりません。このフィールド導入前のレコードは、Key の現在の帰属ユーザー、従来の発行者、プロジェクト責任者、最後に unknown の順でフォールバックします。個人ランキングには、利用実績に現れた Key 数と、現在帰属している失効前の Key 数が別々に表示されます。

Provider カタログの可用性

TokenHub は、最後に正常に読み込んだ Provider カタログをデータベースに保存します。バックエンドの起動時には毎回、設定済みのローカル provider-catalog.json を検証して読み込み、データベースのスナップショットをアトミックに置き換えます。通常の Provider Channels リクエストはデータベースのスナップショットだけを読み取り、管理者は同じローカルカタログを手動で更新することもできます。ローカルカタログの読み込み、解析、または完全性検証に失敗した場合、TokenHub は最後に有効だったスナップショットを引き続き使用します。

モデルディレクトリと公開

新しいモデルディレクトリは、従来混同しやすかった 3 つの概念を分離します。

ビュー	意味
外部モデル	アプリケーションに公開する API 契約です。これが既定ビューで、初期状態では公開済みモデルだけを表示します。
Provider 上流モデル	特定の Provider に取り込まれた実モデルのインベントリです。インベントリへの取り込みだけではクライアントに公開されません。
候補テンプレート	トラック対象カタログの参照メタデータです。取り込みとマッピングが完了するまで、接続済みでも呼び出し可能でもありません。

Provider モデルを取り込むとき、取り込んで公開 は既定で有効な同名 1:1 マッピングを作成します。取り込み前に外部名を編集することもできます。たとえば、外部名 DeepSeek を公開しながら OpenAI Production / gpt-4.5 にマッピングできます。1 つの Provider 上流モデルを複数の外部エイリアスにマッピングすることもできます。

管理者は外部モデルを手動で作成し、Provider に取り込み済みの上流モデルからマッピング先を選択することもできます。必要な上流モデルが一覧にない場合は、先に Provider インベントリへ取り込み、その後でマッピングを作成します。これにより「取り込み」と「公開」が明確な 2 つの手順になります。

「公開状態」と「実行時ヘルス」は独立しています。GET /v1/models に含まれるには、外部 Model が有効、1 つ以上の ModelRoute が有効、さらに API Key にモデル許可リストがある場合は対象モデルが許可済みである必要があります。Provider または Provider Resource の一時的な不健全は一覧の所属を変更せず、現在のリクエストを処理できるかどうかだけに影響し、ディレクトリとルーティング診断に別状態として表示されます。外部モデルを非公開にすると GET /v1/models から削除されますが、後で再公開できるようマッピングは保持されます。

モデルルーティングポリシー

管理コンソールでは、外部モデル全体に対してルーティング戦略を 1 つ設定します。モデルカードで戦略タブを選択すると、現在のタブに適したケース、実際の選択動作、パラメータの意味、具体例が表示されます。その戦略で表示される各 Provider のパラメータを調整して、戦略を適用 を選択します。戦略とすべての Provider パラメータはアトミックに保存されるため、モデルが部分更新された設定で動作することはありません。

固定比率では、各 Provider の横に相対的な重みを入力します。2 つの Provider に 75 と 25 を設定すると、目標比率 75% と 25% が表示されます。適応型は同じ値を基本重みとして使用し、実効配分を動的に調整します。品質、コスト、バランスモードでは、それぞれに関係するスコアだけを表示します。これらの戦略では、対象 Provider はすべて 1 つのトラフィック配分プールに入ります。Provider の順序を使うのは順次フェイルオーバーだけで、行をドラッグして 1 番目、2 番目以降の選択順を設定できます。

戦略	動作
priority_weighted	同じ優先度にあるルートへ、設定した重みの比率どおりにリクエストを配分します。たとえば重みが 75 と 25 の場合、目標比率は 75:25 です。
adaptive	設定した重みを基準に、直近 15 分間に実際に呼び出した試行から有効な重みを動的に調整します。各ルートは 5 サンプルから適応を開始し、最近の成功率と成功リクエストのレイテンシが配分に反映されます。飢餓状態や極端な変動を防ぐため、調整幅には上限と下限があります。
quality	毎回、品質スコアが最も高い Provider を先に試します。同点の場合だけ重みで順位を決めます。
cost	毎回、コスト効率スコアが最も高い Provider を先に試します。高いスコアほど安価で優先されます。
priority_only	Provider 一覧を厳密な主系・待機系の順序として使用し、通常時はトラフィックを分配しません。
balanced	重み + 品質スコア + コストスコア を実効重みとして確率的に分配し、既存設定との互換性を維持します。新規設定では通常、固定比率または適応型を使用します。

Provider の接続情報とプロジェクト制限は、引き続きルート単位で設定します。個別の Provider ルート編集では上流モデル、プロジェクトスコープ、スティッキーセッション、状態だけを変更し、全体戦略、重み、スコアはモデルポリシーで編集します。all はすべてのプロジェクト、include は選択したプロジェクトだけ、exclude は選択したプロジェクト以外で利用できます。プロジェクトによる絞り込みはトラフィック配分とフェイルオーバーより先に行われ、表示される目標比率も対象 Provider 間で再計算されます。

プライベートプロジェクトを内部モデルだけに限定するには、内部 Provider のルートを include にして対象のプライベートプロジェクトを選択します。対応する外部 Provider のルートは exclude にして同じプロジェクトを選択します。これにより、プライベートプロジェクトは内部ルートだけを使用し、その他のプロジェクトは外部 Provider を引き続き使用できます。

プロジェクトスコープはモデル検出にも反映されます。通常のモデル有効状態と API Key の許可リストに加え、呼び出し元 API Key のプロジェクトに対して有効なルートが 1 つ以上ある場合にだけ、その外部モデルが GET /v1/models に含まれます。

Provider リソースの自動復旧

TOKENHUB_RESOURCE_FAILURE_THRESHOLD 回連続で失敗した Provider リソースは切り離され、トラフィックの受信を停止してクールダウンに入ります。復旧は自動で行われ、管理者の操作は不要です。

フェーズ	挙動
切り離し	TOKENHUB_RESOURCE_COOLDOWN_SECONDS の間はルーティング対象外
ハーフオープン	クールダウン満了後、試行として 1 リクエストだけを通し、それ以外は引き続き拒否
復旧	試行が上流に到達して成功するとブレーカーを閉じ、失敗回数をリセットし、provider_resource_recovered アラートを発行
再切り離し	試行が失敗すると直ちに次のクールダウンへ移行し、TOKENHUB_RESOURCE_COOLDOWN_MAX_SECONDS を上限として毎回倍増

ブレーカーを閉じられるのは、試行リクエスト自身の成功だけです。ブレーカー作動時にすでに実行中だったリクエストは、結果にかかわらずブレーカーを閉じられません。ストリーム途中でのクライアント切断、ポリシー拒否、非対応モデルは失敗として数えず、失敗回数をリセットもしないため、「失敗・切断・失敗」のような交互パターンでもブレーカーは作動します。

コンソールからリソースを「テスト」した場合、アダプターがプローブに対応していれば即座に復旧します。これは実際の上流リクエストを発行するためです。リソースの無効化は引き続き管理者の最優先操作であり、無効化されたリソースは上流の状態にかかわらず自動復旧の対象になりません。

メトリクス

TokenHub は GET /metrics で Prometheus メトリクスを公開できます。既定では無効で、有効にするには TOKENHUB_METRICS_ENABLED=true を設定してください。無効の間は何も収集されず、エンドポイントは 404 を返します。このエンドポイントは常に認証を要求します。メトリクスにはモデル名、Provider とリソースの識別子、コストが含まれるため、匿名アクセスは許可されません。Authorization: Bearer <token> を送信してください。トークンは TOKENHUB_METRICS_TOKEN を使用し、未設定の場合は管理者トークンにフォールバックします。Prometheus のスクレイプ設定に管理者資格情報を置かずに済むよう、専用トークンの設定を推奨します。クエリ文字列でのトークン指定はアクセスログに残るため拒否されます。

メトリクス	種別	意味
tokenhub_gateway_requests_total	counter	論理的なモデル API リクエスト数。複数候補へのフェイルオーバーが発生しても 1 回として数えます。
tokenhub_gateway_request_duration_seconds	histogram	フェイルオーバーを含むエンドツーエンドのレイテンシ。バケットは 300 秒まで。
tokenhub_gateway_requests_in_flight	gauge	処理中のモデル API リクエスト数。管理トラフィックとスクレイプは含みません。
tokenhub_gateway_tokens_total	counter	種別ごとの Token：prompt、completion、cached、cache_write、reasoning。
tokenhub_gateway_cost_usd_total	counter	推定コスト。使用量レコードと同じ価格を使用します。

あわせて Go ランタイムとプロセスのメトリクスも公開されます。

Token の種別は排他的な分割ではないため、合計してはいけません。 prompt はすでに cached と cache_write を含み、reasoning は completion の一部です。合計すると二重計上になります。

ルーティング前に拒否されたリクエスト（無効な API Key、クォータ超過、未知のモデル）はリクエスト数のみを増やします。Provider に到達していないため、Token・コスト・所要時間は記録しません。カタログに存在しないモデル名はそのまま記録せず unknown として扱うため、任意のモデル名を大量に送っても系列数を増やすことはできません。

ラベルは model、provider_type、provider_id、resource_id、status_code、error_code、stream です。TOKENHUB_METRICS_PROJECT_LABEL=true を設定すると project_id が追加され、各ゲートウェイメトリクスの系列数がアクティブなプロジェクト数だけ増加します。プロジェクト単位のダッシュボードが必要な場合を除き無効のままにし、Key 単位の集計には使用量レポートを利用してください。

スクレイプではなく push が必要な場合は、OpenTelemetry Collector の prometheus receiver でこのエンドポイントを収集して転送してください。ゲートウェイ自体は Prometheus exposition 形式のみを提供します。

Prompt Cache の料金

モデルカタログでは、100 万 Token あたりのキャッシュ読み取り単価を任意で設定できます。設定した場合、キャッシュにヒットした入力 Token の推定コストにはその単価を使用します。空欄の場合、DeepSeek V4 Pro は標準入力単価の約 0.83%、その他の DeepSeek モデルは 2%、残りの Embedding 以外のモデルは 10% で推定します。モデル料金表では推定値を示し、ホバー時に適用した比率を説明します。

候補テンプレートの復元

外部モデルを削除するとデータベース上のレコードとルートは削除されますが、data/model-catalog.yaml や TOKENHUB_MODEL_CATALOG_FILE が指すファイルは変更されません。バックエンド起動時に、そのファイルの候補メタデータが再同期されます。管理者は「モデルディレクトリ」の「候補テンプレート」タブで「候補テンプレートを復元」を実行してメタデータを更新でき、カスタム外部モデルは保持されます。テンプレートの復元だけでは Provider への取り込み、マッピング作成、GET /v1/models への公開は行われません。

セキュリティチェックリスト

コントロール	要件
API keys	完全な Secret は一度だけ表示し、その後は prefix と suffix のみ保存
OAuth redirect URI	ローカルと本番の callback URL を ID プロバイダーに登録
RBAC	user、team leader、administrator、finance、security、operator の範囲を分離
Audit retention	リクエストログと管理イベントをコンプライアンス確認に十分な期間保持
Cost controls	可能な限り各リクエストを user、project、team、cost center に配賦

中国向け企業 ID プロバイダー

Identity Sources で DingTalk、Feishu、WeCom の組み込みテンプレートを選択します。テンプレートは公開エンドポイントと Claim マッピングを自動入力します。企業プロキシまたは互換性のあるプライベート環境を使う場合のみ、詳細設定でエンドポイントを上書きしてください。

ID ソースの新規作成には 3 つの必須手順があります。ID ソースを選択し、接続設定を入力し、ログインエントリと初回ログイン権限を設定します。接続設定の手順には選択した ID プロバイダーの公式設定ガイドへのリンクが表示され、アプリの作成と認証情報の取得方法を確認できます。汎用 OIDC / OAuth2 テンプレートでは、実際に使用する ID プロバイダーのアプリ登録ガイドを確認するよう案内し、対応するプロトコルリファレンスへのリンクを表示します。3 番目の手順で、完全なエンドポイント既定値を持つテンプレートは スキップして完了 を選択できます。必要なエンドポイントがない場合は詳細設定が必須になります。また、詳細設定でエンドポイント、Scope、Claim の既定値を上書きできます。既存の ID ソースを編集する場合は、完全なフォームを 1 画面に表示します。

TokenHub バックエンドの公開 URL と callback パス /api/admin/auth/oauth/callback を使用します。Callback URL を空欄にするとバックエンドリクエストの Host から自動生成します。明示的に設定する場合は、完全な URL を ID プロバイダー側のリダイレクト URL と完全に一致させてください。

プロバイダー	必要なアプリ設定	TokenHub の動作
DingTalk	Web アプリを作成し、ユーザー認可を有効にし、Callback URL と App Key / App Secret を設定	DingTalk v1.0 JSON Token API と専用のユーザー Token ヘッダーを使用します。メールがない場合は unionId から安定した内部メールを生成します。
Feishu	企業カスタムアプリを作成し、Web 認可、Callback URL、App ID / App Secret を設定。可能な場合はプロフィールと企業メールの権限も付与	Feishu OAuth v2 Token API を使い、ユーザー情報応答の data を展開します。メールがない場合は union_id から内部メールを生成します。
WeCom	カスタムアプリと信頼済み Web 認可ドメインを設定し、Corp ID、アプリ Secret、Agent ID、必要なディレクトリ参照権限を設定	WeCom CorpApp ログインを使い、アプリ Token の取得、callback code から UserId の解決、メンバー情報の取得を行います。biz_mail を優先し、必要な場合は userid から内部メールを生成します。

生成されたアドレスの末尾は <provider>.tokenhub.local です。これは内部アカウント識別子であり、メール配送先ではありません。新しいログインを E2E で確認するまで、管理可能なパスワード管理者アカウントを残してください。

スクリーンショット