--- outline: 2 head: - - meta - name: description content: OneGateway のよくある質問。製品の位置付け、モデル連携、API Key、権限、クォータと課金、プロバイダーのルーティング、セマンティックキャッシュ、ガードレール、呼び出しのトラブルシューティングを扱います。 --- # よくある質問 このページは、OneGateway を利用するメンバー（アプリケーションを連携する開発者を含む）と管理者を対象に、連携、日常の利用、管理に関するよくある質問に回答します。初めて呼び出す場合は、まず[クイックスタート](/ja/guide/getting-started)をお読みください。表示されるメニューや利用できる機能は、ご利用の環境の設定とロール権限によって異なります。 | 知りたいこと | 参照先 | | --- | --- | | 製品の用途、デプロイ方式、データの流れ | [製品とデプロイ](#product) | | アプリケーションの連携方法、モデルの選び方 | [連携とモデル](#integration) | | キー、ロール、部署、グループ料金の違い | [API Keys と権限](#access) | | クォータ不足、周期リセット、引き換え、料金 | [クォータと課金](#billing) | | プロバイダーの接続、プライマリ／バックアップの切り替え、設定の反映 | [プロバイダーとルーティング](#routing) | | `og-auto`、複雑度によるモデル選択、モデルの切り替え | [インテリジェントルーティング](#intelligent-routing) | | キャッシュでコストを削減できるか、ヒットしない理由 | [セマンティックキャッシュ](#cache) | | コンテンツのブロック、マスキング、ストリーミングレスポンス | [ガードレール](#guardrails) | | リクエストログの遅延、呼び出しの失敗、問題の報告 | [リクエストログとトラブルシューティング](#troubleshooting) | ## 製品とデプロイ {#product} ### OneGateway はどのような課題を解決しますか？ {#product-purpose} OneGateway は、企業向けの統合 AI ゲートウェイ兼 Token 管理プラットフォームです。従業員、業務アプリケーション、AI エージェントは統一された入口からモデルを呼び出し、管理者はプロバイダー接続、モデル権限、API Key、利用クォータ、呼び出し記録を一元管理します。 OneGateway が提供するのはモデルへのアクセスとガバナンスの機能であり、モデルの回答は引き続き接続先の上流サービスが生成します。主な機能は[はじめに](/ja/guide/introduction)を参照してください。 ### すでにモデルプロバイダーのアカウントがあるのに、なぜ OneGateway が必要なのですか？ {#existing-provider-accounts} 企業は上流のキーを一元的に保管し、メンバーやアプリケーションごとに OneGateway の API Key を個別に発行できるため、各アプリケーションでプロバイダーのキーを分散管理する必要がなくなります。さらに、モデル権限と利用上限を統一的に設定し、メンバー、部署、モデル別に費用を確認できるほか、同じモデルに複数のプロバイダーを設定して負荷分散や障害時のリトライを行えます。 ### どのようなデプロイ方式に対応していますか？業務データはどこに送られますか？ {#deployment-data-flow} SaaS とハイブリッドデプロイに対応しています。SaaS はプラットフォームが提供するクラウドサービスを利用します。ハイブリッドデプロイでは企業の社内ネットワークに専用の Token Gate をデプロイするため、社内ネットワーク上のモデルとの連携や、企業内部の呼び出しトラフィックの管理に適しています。 ハイブリッドデプロイで社内ネットワーク上のモデルを呼び出す場合、リクエストとレスポンスの内容は企業ネットワーク内にとどめることができ、設定、クォータ、使用量などの管理データはクラウドのコンソールと同期されます。**実際のデータの流れは、依存するサービスの配置場所にも左右されます**。外部モデルを呼び出す場合はそのモデルサービスにリクエストが送信され、外部の Embedding、安全審査モデル、判定サービスを有効にした場合は、関連するテキストもそれらのサービスに送信されます。デプロイ時には、これらの依存サービスの配置場所もあわせて確認してください。[デプロイモード](/ja/guide/introduction#デプロイモード)を参照してください。 ### コンソールとゲートウェイはそれぞれ何を担当しますか？アプリケーションはどのアドレスにアクセスすべきですか？ {#console-and-gateway} コンソールはユーザー、権限、設定、レポート、監査の管理を担当します。ゲートウェイ（Token Gate）はリアルタイムのリクエスト処理を担当し、プロトコル変換、ルーティング、クォータの検証と差し引き、有効化されたプラグインの処理を行います。 日常の管理はすべて OneGateway コンソールで行い、アプリケーションは API Keys ページに表示される **API URL** を使用します。 ## 連携とモデル {#integration} ### アプリケーションを連携するには何を準備すればよいですか？既存のアプリケーションはどの程度コードを変更する必要がありますか？ {#integration-requirements} **API URL、OneGateway API Key、モデル ID** の 3 つを準備します。最初の 2 つは API Keys ページから取得し、モデル ID は利用可能なモデルのページからコピーします。 既存のアプリケーションが互換性のある API 形式を使用している場合、通常はアドレス、キー、モデル ID を置き換えるだけで済みます。プロバイダー固有のパラメーターや機能を使用している場合は、選択したモデルと接続タイプがそれらに対応しているかも確認してください。完全な呼び出し例は[クイックスタート](/ja/guide/getting-started)を参照してください。 ### API URL に `/v1` を付ける必要はありますか？モデル名には何を指定すればよいですか？ {#api-url-and-model-id} リクエストアドレスにベースアドレスと完全なアドレスのどちらを指定するかは、使用するクライアントによって異なります。クイックスタートの OpenAI 形式の例では、SDK を使う場合は Base URL（`https://your-api-endpoint/v1`）を指定し、チャットの HTTP リクエストを直接送信する場合は完全なアドレス（`https://your-api-endpoint/v1/chat/completions`）を指定します。クライアントによってはパスを自動補完するものがあるため、`/v1` が重複しないようクライアントの挙動を確認してください。 リクエストの `model` には、[利用可能なモデル](/ja/user/models)に表示される **モデル ID** を指定する必要があります。カード上の表示名やプロバイダー名を指定しないでください。管理者から案内された[仮想モデル](#virtual-model)名（例：`og-auto`）は例外で、利用可能なモデルに表示されなくても直接指定できます。 管理者がモデル名のマッピングを設定している場合、[リクエストログ](/ja/user/usage#個々の呼び出しの明細を確認する)に表示される上流の実際のモデルが、リクエストしたモデル ID と異なることがあります。名前が異なること自体は呼び出しエラーを意味しません。必要に応じて、管理者にそのプロバイダーのマッピング設定を確認してもらってください。 ### 企業の自社構築モデルを接続できますか？すべてのモデルが同じ機能に対応していますか？ {#self-hosted-models} プロトコル互換の自社構築モデルを接続できます。ただし、ゲートウェイがそのサービスアドレスにアクセスでき、管理者が対応する接続タイプ、認証情報、モデルを設定していることが前提です。 統一された入口を使っても、モデル自体の能力は変わりません。コンテキスト長、ツール呼び出し、画像、音声、推論などの機能は、引き続き対象モデルと接続プロトコルに依存します。モデル定義のコンテキストと価格のフィールドは説明と課金のためのものであり、変更してもモデルの能力は拡張されません。[プロバイダーとモデル](/ja/admin/providers-and-models)を参照してください。 ### 同僚には表示される、または呼び出せるモデルを、なぜ自分は使えないのですか？ {#model-access} メンバーによって利用できるモデルの範囲が異なる場合があります。まず自分の利用可能なモデルを確認し、次に API Key の利用可能なモデルの制限を確認してください。管理者は、対象モデルに有効な状態で、かつそのキーのグループ料金が選択されたプロバイダーが存在するかも確認する必要があります。 **ページにモデルが表示されていても、すべての API Key で呼び出せるとは限りません**。キーに設定された制限によって、範囲がさらに絞り込まれることがあります。権限の関係は[グループ料金と API Key](/ja/admin/providers-and-models#api-key-へのグループ料金の指定)を参照してください。 ### モデルのステータスがグレー、または価格が `--` と表示されるのはどういう意味ですか？ {#model-status} グレーのステータスブロックは、その時間帯に呼び出し記録や監視データがないことを示しており、それだけでモデルが利用できないと判断することはできません。ステータスはモデル全体の直近の呼び出し状況を示すものであり、次のリクエストが必ず成功することを保証するものでもありません。 価格が `--` と表示される場合は、その価格項目が未設定であることを示しており、無料で呼び出せることを意味するものではありません。リクエスト単位で課金されるモデルでは、出力価格が `—` と表示されます。各フィールドの詳細は[モデルカードの見方](/ja/user/models#モデルカードの見方)を参照してください。 ## API Keys と権限 {#access} ### OneGateway API Key と上流プロバイダーのキーはどう違いますか？ {#api-key-types} 上流のキーは管理者がプロバイダーの接続設定で管理し、ゲートウェイがモデルサービスにアクセスするために使用します。OneGateway API Key は、メンバーやアプリケーションがゲートウェイにアクセスするための認証情報であり、特定のメンバーに帰属し、プラットフォームの権限とクォータのルールに従います。 アプリケーションごとに API Key を作成し、クォータ、有効期限、利用可能なモデル、IP 制限を個別に設定できるため、利用状況の追跡や個別アプリケーションの停止が容易になります。操作方法は[API Keys](/ja/user/tokens)を参照してください。 各アカウントで作成できるキーの数にはシステム上限があります。作成時に数の上限超過が表示された場合は、管理者に制限を確認してもらい、既存のキーがまだアプリケーションで使用されていないかを確認したうえで整理してください。 ### API Key に「Unlimited quota」「All models」と表示されている場合、本当に制限はないのですか？ {#unlimited-key} いいえ。「Unlimited quota」は、そのキーに個別の利用上限がないことを示すだけであり、呼び出しには引き続きメンバーのクォータ、アカウント残高、その他のアクセスルールが適用されます。 「All models」は、キーに追加のモデル許可リストが設定されていないことを示します。対象モデルを提供する有効なプロバイダーが引き続き必要であり、プラットフォーム上のすべてのモデルを呼び出す権限が付与されるわけではありません。 ### ロール、部署、グループ料金はそれぞれ何を制御しますか？ {#roles-and-groups} | 設定 | 主な役割 | | --- | --- | | ロール | 表示されるメニューと実行できる操作を制御します | | 部署 | 組織上の所属を記録し、部署別の使用量と費用の分析に使用します | | グループ料金 | 呼び出しに適用される料金倍率を決定します | | API Key の制限 | 特定のアプリケーションや用途について、モデル、クォータ、有効期限、送信元 IP をさらに制限します | 部署を変更しても、ロール、グループ料金、メンバーのクォータは自動的には変わりません。ユーザーのグループ料金を変更した後は、グループ料金を明示的に指定している API Key も確認してください。グループ料金の選択方法と管理画面はデプロイ方式と権限によって異なります。プラットフォームがグループ料金を一元管理している環境では手動で調整する画面が提供されない場合があるため、その場合は管理者に適用される料金倍率を確認してもらってください。詳しくは[グループ料金](/ja/admin/providers-and-models#グループ料金)を参照してください。 ### API Key が漏洩した場合や担当者が退職した場合、どうすれば呼び出しを停止できますか？ {#revoke-access} キーの漏洩が疑われる場合： 1. その API Key のステータススイッチをオフにし、調査のためにキーとその履歴は残しておきます。 2. 新しいキーを作成し、アプリケーションを更新します。 3. 不要になったことを確認したら、古いキーを削除します。削除は元に戻せません。 担当者が退職した場合、管理者はアカウントを無効化し、その API Key のステータスを確認したうえで、設定が同期され、古い認証情報によるリクエストが拒否されることを確認してください。クォータの取り消しだけでアクセスを停止しないでください。アカウントにはまだ利用可能な残高が残っている可能性があります。 セマンティックキャッシュを有効にしている場合は、本来キャッシュにヒットするリクエストと、上流への転送が必要なリクエストをそれぞれ検証する必要があります。キャッシュ前の有効な認証情報の検証結果は、デフォルトで 5 分間キャッシュされます。コンソールのスイッチだけで、すべての経路が古い認証情報を即座に拒否すると推測することはできず、この時間を失効が反映されるまでの保証と見なすこともできません。古い認証情報でまだ回答が得られる場合は、管理者が設定の同期と Token Gate の認証情報検証の状態を確認してください。アプリケーションのキーを差し替えただけでは、古い認証情報が無効になったことにはなりません。[認証情報の検証と無効化の確認](/ja/guide/semantic-cache#認証情報の検証と無効化の確認)、[API Keys の管理](/ja/admin/tokens)、[ユーザーの管理と無効化](/ja/admin/users#ユーザーの管理と無効化)を参照してください。 ### 同じ API Key が一部のマシンでは使えて、他のマシンでは使えないのはなぜですか？ {#machine-specific-failures} まず、キーの **IP restrictions** に、それらのマシンの実際の送信元アドレスが含まれているかを確認してください。プロキシやネットワークアドレス変換（NAT）を経由している場合、送信元アドレスはマシンの内部アドレスと異なることがあります。次に、双方の API URL、モデル ID、キーが一致しているか、またネットワークからゲートウェイに到達できるかを確認してください。 ## クォータと課金 {#billing} ### メンバーのクォータ、アカウント残高、API Key のクォータはどう違いますか？ {#quota-types} | 種類 | 出所と用途 | 周期ごとにリセットされるか | | --- | --- | --- | | メンバーのクォータ | 管理者がメンバーに割り当てる周期ごとの利用上限 | はい | | アカウント残高 | 引き換えコードでチャージし、実際の利用額に応じて差し引かれます | いいえ | | API Key のクォータ | 個々のキーに課す追加の利用上限 | メンバーのクォータの周期に合わせて自動リセットされることはありません | ここでいうクォータ、残高、キーのクォータはいずれも**利用金額**であり、Token 数ではありません。`$` は米ドルを表し、たとえば `$100` は 100 米ドル分の利用クォータを意味します。 呼び出しでは、まずメンバーのクォータが消費され、クォータが不足するとアカウント残高が消費されます。メンバーのクォータが設定されていない場合は、直接残高が使用されます。同時に、API Key のクォータ制限は独立して適用されます。詳しくは[クォータと残高](/ja/admin/quota#クォータと残高)を参照してください。 ### 新しいアカウントで初めて呼び出したときにクォータ不足と表示されます。どうすればよいですか？ {#new-account-quota} アカウントや API Key を作成しても、利用クォータが付与されるわけではありません。まず[個人ダッシュボード](/ja/user/my-dashboard)で、メンバーのクォータが設定されているか、残高が利用可能かを確認してください。メンバーのクォータがなく残高もゼロの場合は、管理者に[クォータの割り当て](/ja/admin/quota#クォータの割り当て)を依頼するか、環境で引き換えコードが有効になっていれば、有効な引き換えコードを使って[残高をチャージ](/ja/user/redemption)してください。 割り当てやチャージが完了したら、API Key 自体のクォータと設定の同期状態も確認してから、再度呼び出してください。HTTP ステータスコードだけでクォータの問題かどうかを判断しないでください。 ### メンバーのクォータを使い切ると必ず呼び出しが停止しますか？残高があるのにクォータ不足と表示されるのはなぜですか？ {#exhausted-quota} メンバーのクォータを使い切っても、アカウント残高が十分であれば呼び出しを続けられる場合があります。メンバーのクォータを取り消しても、残高は消去されません。 逆に、メンバーのクォータや残高がまだ残っていても、**個々の API Key のクォータを使い切ると呼び出しはブロックされます**。トラブルシューティングの際は、メンバーのクォータ、アカウント残高、キーのクォータを同時に確認し、設定が同期されているかも確認してください。ページに表示される使用済み金額が、リアルタイムの利用状況より遅れて反映されることもあります。 ### クォータはいつリセットされますか？使い切れなかった分は繰り越せますか？ {#quota-resets} 選択できるリセット周期は、ご利用の環境のクォータ設定ページに従います。毎週の場合は毎週月曜日の 00:00、毎月の場合は毎月 1 日の 00:00 にリセットされます。ページに毎日のオプションがある場合は、毎日 00:00 にリセットされます。 リセットはゲートウェイサーバーの稼働タイムゾーンに基づいて実行され、個人のコンピューターや組織のタイムゾーン設定には左右されません。コンソールに表示される **Next reset** の時刻を基準にしてください。 前の周期で使用しなかったメンバーのクォータは次の周期に繰り越されず、リセット日や時刻を自分で選ぶこともできません。引き換えコードでチャージした残高は、周期リセットの影響を受けません。[周期リセットと使用量の通知](/ja/admin/quota#周期リセットと使用量通知)を参照してください。 ### クォータを引き上げると、今周期にすでに使用した金額は保持されますか？ {#quota-adjustments} いいえ。クォータの調整を保存すると元の周期が終了し、新しい周期が開始されます。**今周期の使用済み金額はゼロに戻り**、新しい設定に基づいてクォータと次回リセット時刻が再計算されます。 これは、元の周期の残りクォータに金額を単純に追加するものではありません。現在の調整画面は通知設定の保存にも使われるため、通知設定だけを変更した場合でも、保存すると同様に周期がリセットされます。詳しくは[クォータの調整と取り消し](/ja/admin/quota#クォータの調整と取り消し)を参照してください。 ### 部署単位でクォータを割り当てると、部署全体で 1 つの金額を共有するのですか？新しいメンバーには自動的にクォータが付与されますか？ {#department-quotas} いいえ。部署単位の選択は一括でメンバーを選ぶための手段にすぎず、保存すると、今回選択した各メンバーにそれぞれクォータが設定されます。たとえば、10 人を選択して 1 人あたり $100 のクォータを設定した場合、各メンバーがそれぞれ $100 の周期クォータを持つことになります。 後から部署に加わったメンバーには、このクォータは自動的には付与されません。管理者は **Unconfigured** ビューで該当メンバーを見つけ、別途割り当てる必要があります。メンバーが部署を異動しても、既存のクォータのルールは自動的には変わりません。一括保存は一部のみ成功する場合があるため、失敗の明細に従って保存に失敗したメンバーだけを処理し、すでに成功したメンバーを重複して調整しないようにしてください。 ### 引き換えコードの画面がないのはなぜですか？引き換えに成功するとメンバーのクォータが増えますか？ {#redemption} 引き換えコード機能は、環境で有効になっている必要があります。組織では通常、メンバーのクォータと引き換えコードのどちらか一方の方式を選択します。画面が表示されない場合は、[個人ダッシュボード](/ja/user/my-dashboard)でクォータを確認し、管理者に問い合わせてください。 引き換えに成功すると増えるのは、現在ログインしているアカウントの **残高** であり、周期クォータが増えることはなく、今周期の使用済み金額がリセットされることもありません。同じ引き換えコードは 1 回しか引き換えられません。引き換えできない場合は、使用済み、期限切れ、無効化済み、または適用範囲外ではないかを管理者に確認してもらってください。[引き換えコードでチャージ](/ja/user/redemption)を参照してください。 ### 料金はどのように計算されますか？同じモデルでも料金が異なるのはなぜですか？ {#billing-calculation} モデルは、Token の使用量またはリクエスト回数に応じて課金されます。従量課金には、入力、出力、キャッシュ読み取り、キャッシュ作成、画像、音声などの価格項目が含まれる場合があり、適用される料金倍率を組み合わせて計算されます。 同じモデルでも、実際の入出力の長さ、キャッシュの使用量、料金倍率、課金設定が異なれば、料金に差が生じることがあります。確認する際は[リクエストログ](/ja/user/usage#個々の呼び出しの明細を確認する)の詳細を展開し、今回の価格、使用量、料金倍率、課金の計算過程を確認してください。総 Token 数に単一の価格を掛けるだけで見積もらないでください。 ### リクエストログの料金に「Subscription」と表示されている場合、無料で呼び出せたということですか？ {#subscription-charge} いいえ。「Subscription」は、今回の呼び出しがメンバーの周期クォータから差し引かれたことを示します。引き換えコードの残高を使用した場合、料金の列には今回の呼び出しの具体的な金額が表示されます。周期クォータの消費状況は[個人ダッシュボード](/ja/user/my-dashboard)で確認でき、個々の呼び出しの課金はリクエストログの詳細を展開して確認できます。 ## プロバイダーとルーティング {#routing} ### プロバイダーの接続テストに成功したのに、モデルの呼び出しが失敗するのはなぜですか？ {#connection-test} 接続テストは主に上流のモデル一覧 API にアクセスし、接続の確認とモデルの検出を行うものです。各モデルが正常に回答を生成できるかどうかや、メンバーの呼び出し権限までは検証しません。 あわせて、プロバイダーが有効になっているか、対応モデルが正しいか、対応するグループ料金が選択されているか、API Key が制限を満たしているかを確認し、実際に一度呼び出してみてください。テストに成功したのに選択できるモデルがない場合は、まず現在のインスタンスに同名のモデル定義が存在するかを確認してください。詳しくは[接続のテストとモデルの選択](/ja/admin/providers-and-models#接続テストとモデルの選択)を参照してください。 ### 同じモデルで複数のプロバイダーを使うにはどうすればよいですか？優先度と重みの違いは何ですか？ {#routing-priority} 同じモデルを複数のプロバイダーで提供できます。優先度は数値が大きいほど優先され、同じ優先度の中では重みに応じてトラフィックが分散されます。優先度の低いプロバイダーはバックアップの候補になります。 たとえば、同じ階層にある 2 つのプロバイダーの重みが 3 と 1 の場合、選択される確率はおよそ 3/4 と 1/4 と考えられますが、少数のリクエストで厳密に 3:1 に分配されることは保証されません。**優先度と重みはプロバイダーの設定に属する**ため、あるモデルのルーティングビューで変更すると、そのプロバイダーが提供する他のモデルにも影響します。[モデルのルーティング](/ja/admin/providers-and-models#モデルルーティング)を参照してください。 ### バックアップのプロバイダーを設定しておけば、プライマリのプロバイダーが失敗したときに必ず切り替わりますか？ {#failover} 保証されません。切り替えは、リトライのきっかけとなるエラー、リトライ回数、バックアッププロバイダーの状態、グループ料金の設定、対象モデルが利用可能かどうかに左右されます。管理者は実際のリトライポリシーに基づいて検証し、リクエストログで最終的にリクエストを処理したプロバイダーを確認してください。 プロバイダーが切り替わっても、アプリケーションは通常、元のモデル ID をそのまま使い続けます。 ### モデル定義を作成するだけで呼び出せますか？モデルを無効化すると何に影響しますか？ {#model-definitions} いいえ。モデル定義では名前、コンテキスト、説明、価格を管理しますが、実際に利用するにはプロバイダーの設定も必要です。管理者はモデルをプロバイダーの対応範囲に追加し、グループ料金、有効状態、同期結果を確認してください。 モデルを無効化すると、現在のゲートウェイインスタンス内の関連するプロバイダーの対応範囲からそのモデルが削除され、そのモデルに依存する呼び出しに影響します。再度有効化した後も、提供するプロバイダーと同期結果を確認する必要があります。[モデルマーケット](/ja/admin/providers-and-models#モデルマーケットプレイス)を参照してください。 ## インテリジェントルーティング {#intelligent-routing} 以下では連携時によくある疑問に回答します。詳細は[インテリジェントルーティングのよくある質問](/ja/guide/intelligent-routing#よくある質問)を参照してください。 ### `og-auto` とは何ですか？利用可能なモデルに見当たらないのはなぜですか？ {#virtual-model} `og-auto` のような名前は、管理者が[インテリジェントルーティング](/ja/guide/intelligent-routing)で設定した**仮想モデル**です。リクエストで指定すると、ゲートウェイがリクエストの複雑度やルールに従って実際のモデルに書き換えます。仮想モデルはどのプロバイダーにも対応しないため、[利用可能なモデル](/ja/user/models)には表示されませんが、リクエストで直接使用できます。利用できる仮想モデルは管理者に確認してください。 ### 実際にどのモデルが使われたか、どのモデルで課金されたかを確認するには？ {#routed-model} `og-route-model` レスポンスヘッダーで判断してください。これはルーティング後にプロバイダーへ送られたモデルで、課金もこのモデルで行われます。実際の費用は[リクエストログ](/ja/user/usage)の課金明細で確認してください。レスポンスボディの `model` はプロバイダーが返すモデル名で、プロバイダーがモデルをマッピングしている場合やバージョン付きの名前を使う場合は異なることがあるため、価格の確認には使えません。元々指定したモデルは `og-route-requested-model` レスポンスヘッダーに含まれ、モデルが書き換えられた場合にのみ付きます。 ### `og-auto` を使うと 403 や「モデルへのアクセス権がない」と返されます。どうすればよいですか？ {#routing-403} API Key で利用可能なモデルを制限している場合、書き換え後の**実際のモデル**で検証されます。`og-route-model` に表示されたモデルをこのキーの利用可能なモデルに追加してください。より確実なのは、その仮想モデルで使われる可能性のあるすべてのモデルを管理者に確認し、まとめて追加することです。403 では候補モデルへの切り替えは発生しません。 ### プライマリモデルが失敗したとき、自動でモデルが切り替わりますか？ {#routing-fallback} 管理者がルールに候補モデルを設定している場合は切り替わります。既定のポリシーでは、モデルに利用可能なプロバイダーがない場合、429 のレート制限、500 / 502 / 503 / 529、接続失敗のときに切り替えます。504 / 524 のタイムアウト、料金未設定、権限不足、クォータ不足、センシティブワードによる拒否では切り替えず、原因を判別できない一部の上流の内部エラーでも切り替えません。切り替えのポリシーは管理者が調整できます。ストリーミングリクエストは出力開始前にだけ切り替えます。詳しくは[失敗時の自動切り替え](/ja/guide/intelligent-routing#失敗時の自動切り替え)を参照してください。切り替えが発生した場合、`og-route` レスポンスヘッダーは `FALLBACK` になり、`og-route-attempts` は 1 より大きくなります。 ## セマンティックキャッシュ {#cache} 以下では連携時によくある疑問に回答します。操作の詳細は[セマンティックキャッシュのよくある質問](/ja/guide/semantic-cache#よくある質問)を参照してください。 ### セマンティックキャッシュはモデルプロバイダーのプロンプトキャッシュと同じですか？必ずコスト削減や高速化につながりますか？ {#cache-benefits} 同じではありません。セマンティックキャッシュにヒットすると過去の回答をそのまま再利用し、業務モデルへの生成リクエストは行いません。一方、プロバイダーのプロンプトキャッシュは通常、モデルの生成自体は実行し、入力処理の結果の一部を再利用するだけです。 セマンティック検索には Embedding の呼び出しが必要になる場合があり、ヒットしなかった場合はさらに業務モデルへのリクエストが必要です。そのため、実際の効果はヒット率、有効期間、検索のオーバーヘッドによって決まります。回答が安定しているよくある質問には適していますが、リアルタイムの情報、個人の状態、毎回異なる創作結果が求められるタスクでは、有効化を慎重に検討してください。[セマンティックキャッシュ](/ja/guide/semantic-cache)を参照してください。 ### 同じまたは似た質問なのに、キャッシュにヒットしないのはなぜですか？ {#cache-misses} キャッシュのマッチングには、API の認証情報、キャッシュキー、エンドポイント、ストリーミングモード、モデル、生成パラメーターなども影響し、似た質問の場合はさらにセマンティックのしきい値を満たす必要があります。最初に成功した回答はバックグラウンドで書き込まれるため、直後にリトライしてもヒットしないことがあります。エントリーの期限切れ、メッセージ数のしきい値の超過、書き込みが行われていないことも結果に影響します。 まず `og-cache` レスポンスヘッダーを確認してください。`HIT` はヒット、`MISS` は検索の対象になったもののヒットしなかったことを示します。このヘッダーがない場合は、キャッシュの前提条件を満たしているか、プロキシがレスポンスヘッダーを保持しているかを確認してください。しきい値 `0.8` はマッチングの基準を示すものであり、**回答の正確性が 80% であることを意味するものではありません**。詳しくは[キャッシュのトラブルシューティング](/ja/guide/semantic-cache#症状別のトラブルシューティング)を参照してください。 ### 回答を強制的に再生成するにはどうすればよいですか？ナレッジを更新すると古いキャッシュは自動的に無効になりますか？ {#fresh-answers} 未使用の `hcd-og-cache-key` を使用するか、管理者に関連するキャッシュを削除してもらってください。ナレッジを更新する際は、業務キーを `product-faq:v1` から `product-faq:v2` に切り替えることができます。 `hcd-og-no-store: true` は今回の回答の保存を禁止するだけで、古いキャッシュの読み取りは引き続き許可されます。再生成したうえで保存もしない場合は、新しいキャッシュキーと No-Store を同時に使用してください。デフォルトの TTL を変更しても古いエントリーがすぐに期限切れになることはなく、ヒットしても有効期間は延長されません。操作方法は[ライフサイクルと削除](/ja/guide/semantic-cache#ライフサイクルと削除)を参照してください。 ### 異なるユーザー間でキャッシュは共有されますか？ {#cache-isolation} API の認証情報またはキャッシュキーが異なる場合、エントリーは共有されません。複数のユーザーが同じ API の認証情報とキャッシュキーを共用している場合は、回答が再利用される可能性があります。分離が必要な場合は、信頼できるアプリケーション側で異なる業務キーを設定してください。 呼び出し元が設定できるテナントヘッダーは業務上の識別子にすぎず、認可の代わりにはなりません。具体的なマッチング条件は[キャッシュ空間とマッチングの境界](/ja/guide/semantic-cache#キャッシュ空間とマッチングの範囲)を参照してください。 ### ストリーミングや Responses のリクエストはキャッシュできますか？ヒット時の `usage` は今回の消費量ですか？ {#streaming-cache} セマンティックキャッシュは、Chat Completions、Anthropic Messages、ステートレスな Responses リクエストに対応しており、ストリーミング呼び出しも含まれます。Responses で `background: true`、`conversation`、または空でない `previous_response_id` を使用する場合はキャッシュがスキップされます。`/v1/responses/compact` はキャッシュの対象外です。 ストリーミングと非ストリーミングは別々にキャッシュされ、中断された部分的な回答は保存されません。**キャッシュの再生に含まれる `usage` は過去のレスポンスのデータ**であり、今回の上流での消費量を示すものではなく、今回の実際の課金額をこれに基づいて判断することもできません。キャッシュにヒットしても、今回の総費用がゼロになるわけではありません。対応範囲と集計の基準は[セマンティックキャッシュ](/ja/guide/semantic-cache)を参照してください。 ## ガードレール {#guardrails} ### ガードレールは何をチェックしますか？画像、音声、ファイル内の機密情報も検出できますか？ {#guardrail-coverage} ガードレールは管理者の設定に従ってリクエストとレスポンスのテキストをチェックし、機密情報のマスキング、プロンプトインジェクションの検出、コンテンツの審査に使用できます。マルチモーダルメッセージ内のテキストブロックはチェックできますが、画像、音声、ファイルのブロック自体はスキップされます。それらの内容をチェックする必要がある場合は、業務側で先にテキストを抽出してください。 推論過程や一部のツール引数にもカバー範囲の制限があるため、ガードレールを有効にしたからといって、リクエスト内のすべての内容がチェックされるとは考えないでください。具体的なエンドポイントとフィールドの境界は[ガードレール](/ja/guide/guardrails#既知の制限)を参照してください。 ### ガードレールにブロックされたリクエストでも、モデルの使用量は発生しますか？ {#blocked-usage} リクエスト側のブロックは業務モデルへの転送前に行われるため、今回の業務モデルの生成呼び出しによる Token の消費は発生しません。レスポンス側のブロックについては、回答の出所を区別する必要があります。 - **今回の呼び出しで上流が生成した回答**：モデルはすでに内容の全部または一部を生成しているため、該当する使用量は上流の実際の記録に基づき、ブロックによって自動的に取り消されることはありません。 - **今回セマンティックキャッシュにヒットした回答**：再生時も出力ガードレールを通過しますが、今回は業務モデルの生成呼び出しは行われていません。過去のレスポンスに含まれる `usage` を今回の生成使用量と見なすことはできず、これに基づいて総費用がゼロと判断することもできません。 ガードレールが独立した安全審査モデルを呼び出す場合、審査自体でもモデルの使用量が発生することがあり、業務モデルの呼び出しとは別に計算されます。詳しくは[ガードレールのよくある質問](/ja/guide/guardrails#よくある質問)を参照してください。 ### ガードレールによるブロックと通常の呼び出し失敗はどのように区別できますか？ストリーミングの回答が途中までしか返されないのはなぜですか？ {#guardrail-errors} ガードレールによるブロックのエラータイプまたはエラーコードは `guardrail_blocked` です。非ストリーミングのブロックはデフォルトで HTTP 400 を返しますが、このステータスコードは管理者が設定できるため、エラー本文と `og-guardrail` レスポンスヘッダーをあわせて判断してください。ストリーミングレスポンスの開始後に出力がブロックされた場合は、エラーフレームが送信されてストリームが終了し、すでに送信された内容は取り消せません。 **ストリーミングのレスポンスヘッダーはリクエスト側の判定結果のみを反映します**。出力側の結果は、SSE のエラーイベントとサーバー側のログをあわせて判断してください。ガードレールによるブロックの証拠がない場合は、ネットワークや上流の中断も調査する必要があります。[ブロック時に呼び出し元に表示される内容](/ja/guide/guardrails#ブロック時に呼び出し元が受け取るもの)を参照してください。 ### 審査サービスの障害で業務が止まることはありますか？まず観察してからブロックを有効にできますか？ {#moderation-failures} チェックの実行に失敗した場合、デフォルトでは通過させ、実行エラーを記録します。審査に失敗したときにリクエストをブロックしたい場合は、チェック項目を `fail_on_error: true` に設定し、所属するガードレールで `deny: true` を有効にしたうえで、実行失敗に対応する重大度がブロックのしきい値に達するようにする必要があります。**実行失敗を違反として記録するだけでは、必ずブロックされるわけではありません。** プラグイン自体の例外は独立した `error_policy` で制御され、チェック項目の設定の代わりには使えません。通過したことはチェックに合格したことを意味しないため、管理者は `outcome=error` イベントに注意してください。 まず `deny: false` でヒット状況を観察してから、ブロックを有効にすることができます。なお、観察モードで無効になるのはブロックのみであり、**マスキングによる書き換えは無効になりません**。関連する設定は[段階的なロールアウト](/ja/guide/guardrails#段階的な導入)と[他の機能との関係](/ja/guide/guardrails#他の機能との関係)を参照してください。 ### セマンティックキャッシュにヒットした回答はガードレールを迂回しますか？ {#cached-answer-checks} 規定どおりにプラグインの順序を設定していれば、リクエストはまずガードレールを通過してからキャッシュを検索し、回答はまず出力ガードレールを通過してからキャッシュに書き込まれます。キャッシュにヒットした回答も、現在のリクエストに適用される出力ガードレールを通過します。 ガードレールがストレージ内の過去のエントリーを能動的にスキャンして削除することはありません。古い内容を取り除く必要がある場合は、別途キャッシュを削除するか、キャッシュキーのバージョンを切り替えてください。設定の関係は[他の機能との関係](/ja/guide/guardrails#他の機能との関係)を参照してください。 ## リクエストログとトラブルシューティング {#troubleshooting} ### 呼び出した直後にリクエストログが見つからないのはなぜですか？ダッシュボードのデータが現在の利用額と異なるのはなぜですか？ {#delayed-logs} モデルサービスに転送される呼び出しでは、クォータは呼び出し時にリアルタイムで検証・差し引きされますが、コンソールの呼び出しログ、使用量、実行時のフィールドはバックグラウンドタスクによって反映されるため、遅延が生じます。こうした呼び出し記録は通常、約 2 分後にリクエストログに表示され、集計統計も同時に更新されるとは限りません。 **キャッシュヒットやリクエスト側のガードレールによるブロックでは、上流モデルの呼び出し記録が生成されるとは限りません**。そのため、上記のログ同期を待つだけでは不十分です。Request ID をもとに、Token Gate のリクエストログ、キャッシュの監視、ガードレールのイベントを確認してください。これらのプラグインのログと統計を利用するには、ログプラグインと対応するストレージを有効にする必要があり、具体的な照会画面は現在の環境のコンソール統合によって異なります。関連する記録を有効にしていなかった場合、待機や再読み込みをしても対応する過去のイベントが補完されることはありません。 リクエストログが見つからない場合は、まず期間とユーザーの絞り込み条件を確認してください。リクエストログはデフォルトで直近 7 日間を表示し、メインの一覧は直近 30 日間を保持します。それより古い記録は **Historical Data** で確認できます。記録が欠落し続ける場合は、管理者に同期状態を確認してもらってください。[リクエストログ](/ja/user/usage)を参照してください。 ### メンバーは他の人の呼び出し記録を見られますか？管理者は設定の変更をどのように追跡しますか？ {#data-access} 一般のメンバーが確認できるのは自分の呼び出し記録と個人の統計のみです。管理者は権限の範囲内で組織のデータを確認でき、部署、メンバー、モデルなどの単位で費用と使用量を分析できます。 リクエストログはモデルの呼び出しを追跡し、操作監査は管理上の変更（たとえば、誰が API Key、プロバイダー、料金、ルーティングポリシーを変更したか）を追跡します。両者の用途は異なります。メンバーは[個人ダッシュボード](/ja/user/my-dashboard)、管理者は[ダッシュボードと分析](/ja/user/dashboard)を確認できます。 ### 429 が返される、またはレート制限が表示される場合、制限しているのはプラットフォームとプロバイダーのどちらですか？ {#rate-limits} どちらの可能性もあります。プラットフォームのレート制限ルールが有効になっている場合、リクエストは組織、API Key、またはグローバルのリクエスト頻度の制限を受けることがあります。上流のプロバイダーも、そのアカウントやモデルのリクエスト量を制限している場合があります。HTTP 429 だけでは、どの層による制限かを特定できません。 エラー本文、レスポンスヘッダー、発生時刻、Request ID を保存し、管理者に Token Gate のリクエストログ、レート制限ルール、上流からの返却情報をあわせて特定してもらってください。プラットフォームのルールは権限を持つ管理者が確認し、上流の制限は該当するプロバイダーアカウントの上限と状態を確認する必要があります。 アプリケーションでは、リクエストの頻度と同時実行数を下げ、間隔を空けたバックオフ付きのリトライを採用してください。レスポンスに `Retry-After` が含まれている場合は、その指示に従って待機してください。リトライ回数を増やしたり、バックアップのプロバイダーを設定したりしても、現在の制限を回避できるとは限りません。 ### 呼び出しが失敗した場合、どのような順序で調査すればよいですか？ {#troubleshooting-order} まず完全なエラー情報を保存し、そのうえで現象ごとに確認してください。HTTP ステータスコードだけで原因を判断しないようにしてください。 | 現象 | 優先して確認すること | | --- | --- | | 接続できない、パスが存在しない | API URL、クライアントが自動補完するパス、ネットワークの到達性 | | キーが無効または期限切れ | キーが完全か、オフまたは削除されていないか、有効期限、所属アカウントの状態 | | モデルが存在しない、または権限がない | モデル ID、キーのグループ料金とモデル制限、プロバイダーによる提供と有効状態 | | クォータ不足 | API Key のクォータ、メンバーのクォータ、アカウント残高、および設定の同期結果 | | 一部のマシンのみ失敗する | IP 制限、実際の送信元アドレス、ネットワーク経路 | | 429 またはレート制限の表示 | [制限の発生元](#rate-limits)、プラットフォームのルール、上流の上限、リトライ間隔 | | タイムアウトまたは上流のエラー | レスポンスのエラー情報、実際のプロバイダー、プロバイダーの状態、リトライポリシー | | `guardrail_blocked` | ガードレールの識別子、ヒットイベント、リクエスト側とレスポンス側のどちらでブロックされたか | | 設定を保存しても変化がない | 同期またはホットリロードの結果を確認し、新しいリクエストで検証 | [クイックスタート](/ja/guide/getting-started)の最小リクエストを使ってアドレス、キー、モデルを検証し、その後アプリケーションの他のパラメーターを段階的に戻していくことができます。管理者向けの接続のトラブルシューティングは[検証とトラブルシューティング](/ja/admin/providers-and-models#検証とトラブルシューティング)を参照してください。 ### 管理者に問題を報告する際は、どのような情報を提供すればよいですか？ {#reporting-issues} 発生時刻とそのタイムゾーン、Request ID（ある場合）、モデル ID、API Key の名前、エンドポイントのパス、ストリーミングかどうか、HTTP ステータスコード、エラー内容を提供し、影響範囲と安定して再現できるかどうかも説明してください。キャッシュの問題では `og-cache` などのレスポンスヘッダーを、ガードレールの問題ではガードレールの識別子とストリーミングのエラーイベントを添付できます。 リクエストのサンプルが必要な場合は、先にマスキングしてください。完全な API Key、上流のキー、関係のない機密の業務内容は提供しないでください。管理者はこれらの情報をもとに、呼び出しログ、プラグインのイベント、設定変更の記録を関連付けることができます。