リリース前に大規模言語モデルのAPI中継とゲートウェイをどう評価するか：信頼性のための7項目受け入れチェックリスト

import statistics
import time
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # APIYI の統一インターフェース
)

def one_call(prompt: str) -> dict:
    start = time.perf_counter()
    ok, ttft = False, None
    try:
        stream = client.chat.completions.create(
            model="gpt-4o-mini",
            messages=[{"role": "user", "content": prompt}],
            stream=True,
        )
        for chunk in stream:
            delta = chunk.choices[0].delta.content
            if delta and ttft is None:
                ttft = time.perf_counter() - start
        ok = True
    except Exception as exc:
        return {"ok": False, "ttft": None,
                "total": time.perf_counter() - start, "err": type(exc).__name__}
    return {"ok": ok, "ttft": ttft,
            "total": time.perf_counter() - start, "err": None}

def summarize(rows: list) -> None:
    done = [r for r in rows if r["ok"]]
    totals = sorted(r["total"] for r in done)
    print(f"成功率 {len(done)}/{len(rows)}")
    if totals:
        print(f"p50 {statistics.median(totals):.3f}s")
        print(f"p95 {totals[int(len(totals) * 0.95) - 1]:.3f}s")

rows = [one_call("把下面这句话翻译成英文：请检查订单状态。") for _ in range(50)]
summarize(rows)

負荷テストでもっともよくある間違いは、RPMと同時実行数を混同してしまうことです。毎分リクエスト数、毎分トークン数、同時に実行中のリクエスト数は、それぞれ別の制約を表していて、互いに代用できません。レイテンシが上がるとリトライがシステムへの負荷をさらに増幅させるので、スクリプトにはローカルキュー、最大待機時間、上限付きのバックオフリトライを必ず組み込む必要があります。

ここで見落としやすいポイントがあります。APIYIのドキュメントでは、「同時実行」ページと「トークンとグループ」ページで、レート制限の適用範囲に関する記述が完全には一致していません。前者は複数のトークンクォータが独立していると述べ、後者はレート制限がアカウントに紐づくと説明しています。受け入れテストで正しいのは、**自分の対象アカウントと対象チャネルで実際のクォータを実測する**ことです。同時実行数とRPMを別々に記録し、他人のスクリーンショットにある固定値をそのまま当てはめたり、キーを増やして制限を回避しようとしたりしないでください。

—

## 有効な結果あたりのコストとフォールバック動作をどう確認するか

単価よりも比べる価値があるのは、「ビジネス上有効な結果1件あたりの実コスト」です。計算方法はシンプルで、分子には決済済みの支出全額（リトライとフォールバックを含む）を置き、分母にはビジネス上有効な結果数を置きます。確定した返金は分子から差し引きます。

以下は純粋な仮定の算例で、アルゴリズムの説明だけが目的であり、特定のベンダーの価格を示すものではありません。

| プラン | 決済済み純支出 | ビジネス上有効な結果 | 有効な結果あたりのコスト |
|——|————–|————–|——————|
| プランA | 3.0ドル | 90件 | 約0.0333ドル |
| プランB | 3.2ドル | 98件 | 約0.0327ドル |

支出だけを見ればプランAのほうが安く、有効な結果で割るとプランBのほうが割安になります。「どこが安いのか」という問いがビジネス側の分母なしでは意味を持たないのは、まさにこういう理由です。あわせて2点に注意してください。事前に確保されたまま未決済の非同期タスク枠は別途記載する必要があります。また、消費記録だけを積み上げると純支出を過大評価することがあります。非同期タスクの返金はマイナス値のレコードとして請求に現れるからです。

フォールバックは、まったく性格の異なる2種類の変化に分けて捉える必要があります。**チャネル切り替え**は同じモデルのまま経路を変えるもので、モデルの能力と価格は理論上変わりません。一方**モデル切り替え**は、メインモデルが使えないときにリストに沿って別のモデルを試すもので、業界では一般的な仕組みです。たとえばOpenRouterのmodel fallbacksは、最終的に実際に使用したモデルの価格で課金し、レスポンスのmodelフィールドに最終モデルを示すと明記しています。この例はあくまで仕組みの説明用であり、フィールドの意味を他のプラットフォームにそのまま持ち込むことはできません。

したがって、受け入れ項目は少なくとも次の4点をカバーする必要があります。フォールバック後の最終モデルはどれか、コア機能が依然として成立するか、1回あたりの費用に上限があるか、最大待機時間はどれくらいか。モデルの切り替えが許されない業務があるなら、フォールバックを無効にできるかも確認してください。ストリーミングの場合は別途テストが必要です。部分的な出力が返された後に失敗したとき、シームレスに継続できるかどうかは、非ストリーミングの成功フォールバックからは推測できません。

> 💡 **選択のヒント**：直結の価格とフォールバック経路を同じ表で並べて比べてこそ、本当のコストが見えてきます。複数モデルの実際の課金記録を手早く集めて比較したいなら、APIYI apiyi.com で小規模なサンプルを流し、その結果を自分の受け入れ表で精算してみてください。

—

## データ経路と障害時の責任をどう確認するか

「私たちは安全です」「私たちは安定しています」といった表現で済まされがちな2点ですが、実はトラブルが起きたときに頼れるのは、この2点だけです。確認の基本は、ゲートウェイ、上流のモデルプロバイダー、詳細なトラブルシューティングログ、非同期の成果物を同じデータ経路上に並べ、各層のポリシーを順番に確認していくことです。

| 経路上の要素 | 確認すべきポリシー | 確認方法 |
|———-|—————-|———-|
| ゲートウェイ自体 | 入出力をデフォルトで保存するか、トラブルシューティングログを誰が有効化できるか、保持期間はどのくらいか | 公式のデータセキュリティおよびログに関する説明を読む |
| 上流のモデルプロバイダー | 学習への利用、保持期間、オプトイン（明示的な許可）の要否 | 各上流のポリシーを個別に読み、1つにまとめない |
| 詳細なトラブルシューティングログ | 記録範囲、閲覧できる担当者、デフォルトの保持期間、無効化後の削除時点 | 無効化スイッチを切っても、既存の記録がすぐ削除されるわけではないことを確認する |
| 非同期タスクの成果物 | 成果物の保存場所、ダウンロードリンクの有効期限 | 自社側で早めに保存し、一時リンクに依存しない |

公開ドキュメントによると、APIYIの通常の運用方針では、顧客の入出力はデフォルトで保存されません。詳細なトラブルシューティングログは管理者が一時的に有効化でき、入力、コンテキスト、出力をすべて記録します。内容を閲覧できるのは管理者のみで、ページに記載されているデフォルトの保持期間は7〜30日です。同じページには、記録スイッチを無効にしても、既存の記録がすぐに削除されたとは解釈できないことも明記されています。こうした内容を扱うときは「公式ドキュメントの説明」という出典を明示しておきましょう。これはコンプライアンス認証ではなく、法的な結論でもありません。

見落とされがちな運用上の事実がもう1つあります。ログ自体にもライフサイクルがあることです。APIYIのログ保持に関する専用ページには、呼び出しログは直近約2か月分がローリング方式で保持され、毎月5日、15日、25日に、その日から2か月以上前の記録が削除されると書かれています。削除されたログは復元できないため、長期的な照合や監査に必要な明細は、自分でエクスポートして保管する必要があります。同期結果と非同期成果物では保存期間も異なり、成果物のダウンロードリンクは約1日で有効期限が切れるとされています。この期間を過ぎてから振り返ろうとしても、手元に証拠は残っていません。

障害時の責任については、実行可能な条項にまで落とし込んで確認します。APIYIのSLA専用ページで説明されているのは、プラットフォーム側の原因で損失が生じた場合のクレジット（利用額）の再付与と、企業が契約で保証範囲、可用性指標、対応時間、賠償上限を取り決められる点です。すべての顧客に共通する固定の可用率が示されているわけではありません。ベンダーを比較するときは、指標の集計期間、分母の定義、障害の除外項目、申請手続き、補償の形式を記録しておきましょう。また、サービスクレジットによる補償と現金での賠償では、調達上の価値が異なることも押さえておく必要があります。

—

## 検収表1枚で本番投入の範囲を決める

記録を結論にまとめるときは、「信頼性ランキング」ではなく、投入範囲の判断を出してください。同じベンダーでも、インタラクティブな業務では「重要度の低いタスク」までしか任せられない一方、オフラインのバッチ処理なら十分に使える、ということがあります。

| 結論 | 必要な根拠 | 切り替え・停止のトリガー条件 |
|——|—————-|———————-|
| 小規模での本番投入が可能 | 主要な機能がすべて合格している、p95 が業務のしきい値内に収まっている、利用可能な結果あたりのコストが許容範囲内、データ経路と SLA を確認済み | 業務での可用率がしきい値を下回る状態が続く、または課金の異常を突き合わせられない |
| 重要度の低いタスクのみに利用 | 機能は合格だがレイテンシの変動が大きい、またはフォールバックによってモデルや費用が変わる | 重要な経路は自社構築または直接接続に戻す、フォールバック設定を明示的に無効化する |
| 条件が整ってから再評価 | ドキュメントの確認のみで自アカウントでの実測がない、または SLA の条項が契約に反映されていない | 実測データと契約条項がそろった時点で、あらためて結論を出す |

ドキュメントの確認しかできていない場合は、結論を正直に「公開されている機能と調達条件を確認済み」と書き、実際の検収は次のラウンドに回しましょう。障害時の挙動を検証したいときは、ベンダーが認めているテスト用の設定や隔離環境を使ってください。共有の本番サービスに意図的に負荷や障害を与えてはいけません。また、タイムアウトして結果が不明なときは、まず実行状況と課金を確認し、同じ業務アクションを重複して実行しないようにしてください。

> 🚀 **クイックスタート**：テスト用スクリプトをゼロから作りたくない場合は、まず APIYI（apiyi.com）の無料テスト枠を使って、上記7項目チェックリストの「機能」と「レイテンシ」の2列を一通り試してみてください。そのうえで、より負荷の高いストレステストに進むかどうかを判断すると効率的です。


—

## よくある質問 FAQ

—

## 大規模言語モデルAPI中継ゲートウェイの核心ポイント

– **信頼性は業務側の合格判定で定義する**：プラットフォームでの課金成功、クライアントが200を受け取ったこと、業務側のパースが通ったこと。これはそれぞれ別々に数えるべき3つの事象です。
– **遅延は2つの計測点に分ける**：TTFTは対話体験を左右し、完了までの総時間はデリバリー能力を左右します。どちらもp95で見ます。
– **RPMと同時実行数は分けて記録する**：RPMが低くても、処理中の同時実行数は高く積み上がることがあります。制限の基準は、対象アカウントでの実測値に従います。
– **コストは「利用可能な結果」で割る**：精算済みの支出合計を、業務上利用可能だった結果の数で割ります。リトライとフォールバックの分も分子に入れます。
– **フォールバックはチャネル切り替えとモデル切り替えを区別する**：最終モデル、コア機能、コスト上限、最大待ち時間の4項目を一つずつ検証します。
– **データと責任は実行可能な条項で判断する**：ログには保持期間があり、SLAには統計の定義、除外項目、補償の形態が揃っていなければなりません。
– **導入の進め方**：まず APIYI apiyi.com の少ないサンプルで「能力」と「遅延」の2列を埋め、そのうえで負荷テストと契約内容の突き合わせに進みます。

—

## まとめ

ある大規模言語モデルAPIの中継・ゲートウェイが信頼できるかどうかを見極めるのは、突き詰めれば「印象」ではなく「証拠集め」の作業です。「使えるかどうか」を、業務上の利用可能な結果、エンドツーエンドの遅延、利用可能な結果あたりのコスト、データの経路、障害時の責任という5つの層に分解し、それぞれについて後から確認できる記録を残しておけば、多くの想定外をリリース前に「既知の項目」へと変えられます。

実際に進めるときは、次の3点を覚えておいてください。結論には範囲だけを書き、順位は書きません。基準には自分の実測値だけを書き、他人のスクリーンショットは書きません。証拠は再確認できる範囲までに留めます。ログはいずれ失効するからです。この3点を守れば、選定の議論は「声の大きさ」に依存しなくなります。

まずは APIYI apiyi.com で少サンプルの受け入れ検証を一巡することをおすすめします。統一インターフェースと無料のテスト枠が用意されているため、複数のモデルを同じ表で比較しやすくなります。

—

## 参考資料

1. **APIYI のトークンとグループ**：複数キー、クォータ、リソースグループ、フォールバックグループの解説
– リンク： `docs.apiyi.com/faq/token-and-groups`
– 説明： キーの割り当て、リソースグループ、メイン／バックアップ経路の仕組みを確認するための資料

2. **APIYI のログ保持・削除ポリシー**：ログのローテーション保持とエクスポートの解説
– リンク： `docs.apiyi.com/faq/log-retention-policy`
– 説明： 突合や監査に必要な明細を、自前でどこまで保存しておくべきかを確認

3. **APIYI 詳細ログの説明**：トラブルシューティング用ログの有効範囲と保持期間
– リンク： `docs.apiyi.com/faq/user-logs-control`
– 説明： データ経路上のどの階層でログが取られるかを確認

4. **APIYI データセキュリティの説明**：入出力をデフォルトで保存しない方針について
– リンク： `docs.apiyi.com/faq/data-security`
– 説明： 上流プロバイダのポリシーと階層を分けて読み比べるための資料

5. **APIYI の SLA 保証**：クォータの補填と契約で定められた範囲
– リンク： `docs.apiyi.com/faq/sla-guarantee`
– 説明： 障害時の責任がどのような補償の形で果たされ、どこまでが対象かを理解する

6. **ログの請求金額の読み方**：請求明細のフィールドと倍率の算出基準
– リンク： `docs.apiyi.com/faq/log-billing-explained`
– 説明： 有効な結果1件あたりの実際のコストを算出するために使用

7. **ログ上は完了・課金済みなのにクライアントに応答が届かない場合**：クライアント側タイムアウトとプラットフォーム側課金のずれ
– リンク： `docs.apiyi.com/faq/log-duration-vs-client-wait`
– 説明： 異常な注文を調査する際の必読資料

– リンク： `openrouter.ai/docs/guides/routing/provider-selection`
– 説明： 経路切り替えとモデル切り替えの違いを理解する

9. **OpenRouter Model Fallbacks**：モデルのフォールバックと実際の課金基準
– リンク： `openrouter.ai/docs/guides/routing/model-fallbacks`
– 説明： 最終的に使われたモデルと課金の帰属についての業界での一般的な扱いを解説

—

> **著者**：APIYI 技術チーム
> **技術交流**：APIYI（apiyi.com）のトップページからお気軽にお問い合わせください。ドキュメントは docs.apiyi.com のドキュメントセンターでご覧いただけます