JA ▾
API キーを取得

API Migrationガイド:LLMプロバイダの安全な切替

このAPIマイグレーションガイドでは、すでにOpenAIスタイルのチャットエンドポイントと通信しているアプリを、別のプロバイダに移行する方法を解説します。作業の大部分は変更する2行のコードではなく、旧プロバイダに意図せず依存している部分を特定することです。

最終更新

バルブが1つのパイプラインから別のパイプラインへ、光の立方体の流れの一部を切り替える様子を示し、段階的な移行を表しています

まとめ

  • OpenAI互換のターゲットでは、ベースURL、キー、モデルIDを変更し、動作を確認します。
  • まず機能を把握します:埋め込み、画像、ファインチューニングは、テキストのみ対応のAPIには移行されません。
  • フラグを使ってパーセンテージでロールアウトし、ロールバックを1つの設定変更で完了できるようにします。
  • 切り替え前に、自身のトークン数から新しい請求額を見積もります。

6つのステップによる計画

  1. アプリが呼び出すすべてのAPI機能を把握します。
  2. プロバイダの設定を構成に移動します。
  3. パラメータとモデル名をマッピングします。
  4. 新しい制限に合わせたエラーとレート制限の処理を追加します。
  5. トラフィックの一部を新しいプロバイダにルーティングして比較します。
  6. コストを確認し、切り替え、しばらく旧ルートを維持します。

例のターゲットは https://api.apimigration.com/v1 で、モデルIDは uncensored です。同じ手順はすべてのOpenAI互換プロバイダに適用されるため、ベンダー固有のレシピではなくチェックリストとしてお読みください。途中で問題が発生した場合は、一般的なLLM統合エラーに関するトラブルシューティング記事が一般的な原因をカバーしています。

ステップ1:アプリの使用状況を把握する

旧プロバイダへのすべての呼び出しをコード内で検索し、機能とエンドポイントのリストを作成します。1つのチャット呼び出しには、特定のスタイルに依存するシステムプロンプト、ツールスキーマ、JSONレスポンス形式、大きなコンテキストなど、複数の依存関係が隠れていることがあります。

アプリ内の機能このAPIでの対応状況
チャットコンプリーション、/v1/responsesサポート
SSEによるストリーミングサポート済み、使用量は最後に送信
ツール呼び出しサポート済み、ストリーミングされたtool_callsを含む
JSON モードresponse_formatで対応
コンテキスト100,000 トークン(プロンプトと補完を含む)
埋め込み、画像、オーディオ、ファインチューニング提供不可、他のプロバイダにこれらを維持してください

旧プロバイダが埋め込みや画像生成も扱っていた場合は、移行を分割します:テキスト呼び出しのみを移動し、残りは既存のプロバイダのままにしておきます。

ステップ2:プロバイダの設定を構成ファイルに置く

ハードコードされたURLは、移行をコード変更に変えてしまいます。ベースURL、キー、モデルを環境変数から読み込み、デプロイなしで切り替えられるようにします。

export LLM_BASE_URL="https://api.apimigration.com/v1"
export LLM_API_KEY="YOUR_KEY"
export LLM_MODEL="uncensored"
import os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ["LLM_BASE_URL"],
    api_key=os.environ["LLM_API_KEY"],
)
MODEL = os.environ.get("LLM_MODEL", "uncensored")

認証は標準的な Authorization: Bearer ヘッダーであり、SDKが自動的に設定します。キーを確認し、サーバーが提供する機能を確認するには、GET /v1/models を呼び出します。

curl https://api.apimigration.com/v1/models \
  -H "Authorization: Bearer $LLM_API_KEY"

ステップ3:パラメータとプロンプトのマッピング

このAPIで透過されるパラメータ:temperature、top_p、stop、seed、および頻度ペナルティと存在ペナルティ。max_tokensはオプションです。古いコードで制御不能なコスト増を防ぐために設定している場合は、そのまま維持してください。

注意深く確認すべきことが3つあります。

  • ベンダー固有のフィールド。 OpenAIのリクエスト形式外のフィールドは無視または拒否される可能性があります。正確な本番環境のペイロードで1つのリクエストを送信し、レスポンスを読み取ります。
  • モデルの動作。 異なるモデルは同じプロンプトを異なる方法で解釈します。旧モデル向けに調整されたシステムプロンプトは、小さな編集が必要になることがよくあります。それらをテストし、推測しないでください。
  • 拒否。 旧プロンプトに拒否を回避するためのワークアラウンドが含まれていた場合、それらを通常は削除できます。これによりプロンプトが短くなります。

モデルは回答内容も異なります。このモデルは法的な成人向け用途に最適化されており、未成年者を含む性的コンテンツはブロックされます。

ステップ4:新しい制限に合わせてエラー処理を調整する

フルキーは同時8リクエスト、1分あたり300リクエストを許可します。トライアルキーは同時2リクエスト、1分あたり60リクエストを許可します。制限を超えると、HTTP 429とエラーコード rate_limited または concurrency が返されます。一時的な過負荷時にも429が返され、Retry-After: 5 が付きます。

import time
from openai import RateLimitError

def chat(messages, retries=4):
    for attempt in range(retries):
        try:
            return client.chat.completions.create(model=MODEL, messages=messages)
        except RateLimitError:
            time.sleep(5 * (attempt + 1))
    raise RuntimeError("still rate limited after retries")

ストリーミングリクエストはストリームが終了するまで同時呼び出し枠を保持するため、フリーズしたクライアントが他のリクエストを枯渇させる可能性があります。finally ブロックでストリームを閉じます。旧プロバイダがより多くの並列呼び出しを許可していた場合は、新しい制限に合わせてセマフォを追加します。失敗したリクエストは課金されないため、リトライは予算に対して安全です。

ステップ5:割合でロールアウトする

すべてを一度に変更しないでください。ユーザーの安定した少量の割合を新しいプロバイダに送信し、旧プロバイダをフォールバックとして維持してください。ユーザーIDをハッシュ化することで、各ユーザーが片側に留まり、会話の途中で声が変更されることがなくなります。

import hashlib

def use_new(user_id: str, percent: int) -> bool:
    bucket = int(hashlib.sha256(user_id.encode()).hexdigest(), 16) % 100
    return bucket < percent

# 5 percent, then 25, 50, 100 as metrics hold
new_client = OpenAI(base_url="https://api.apimigration.com/v1", api_key=os.environ["NEW_KEY"])
old_client = OpenAI(base_url=os.environ["OLD_BASE_URL"], api_key=os.environ["OLD_KEY"])

def pick(user_id):
    return new_client if use_new(user_id, int(os.environ.get("ROLLOUT_PERCENT", "0"))) else old_client

前のフェーズが1日ほど正常に動作した後で、割合を上げます。ロールバックは、環境変数を0に戻す1つの操作です。

切替後にチームを驚かせる要素

ベースURLの変更は初回で動作します。驚きはその後に来ます。

  • トーンとフォーマットのドリフト。 同じプロンプトが異なる言葉の回答を生成します。"Answer:" プレフィックスの正規表現など、自由テキストを解析する機能は最初に失敗します。プログラムが読み取るものには、JSON モードまたは関数呼び出しを優先してください。
  • 異なるトークン数。 各モデルは独自の方式でテキストをトークン化します。旧プロバイダのトークン数に基づくコスト見積もりは、ある程度ずれるため、usage フィールドで再測定してください。
  • 出力の長さ。max_tokensを指定しない場合、生成結果は100,000トークンのウィンドウの残りを使用する可能性があります。古い環境にデフォルトの上限がある場合は、意図的に設定してください。
  • タイムアウト。 クライアントのタイムアウトは旧プロバイダ向けに調整されていました。新しいプロバイダでの長い回答は、それを超過する可能性があります。可能な限りストリーミングし、ストリーミングしない呼び出しのタイムアウトを上げます。
  • 静かな拒否の変化。 製品が以前拒否メッセージをキャッチしてフォールバックを表示していた場合、そのコードは動作しなくなる可能性があります。それをまだ必要かどうかを判断してください。

切り替え前の短いチェックリスト

  1. インベントリにあるすべての機能に、テスト済みの同等機能または文書化されたギャップがあります。
  2. APIを呼び出すすべてのサービスにおいて、ベースURL、キー、モデルは設定から取得されます。
  3. コード内のレート制限と同時接続の上限は、新しい制限と一致しています。
  4. クライアントの切断時にストリームは閉じられます。
  5. ログにはX-Request-Idヘッダーが含まれているため、ヘルプを依頼する際にリクエストを引用できます。
  6. 残高はX-Balance-USDまたはGET /v1/balanceを通じて監視され、残高が少なくなる前にアラートが設定されます。
  7. 旧プロバイダーは資金提供されており、ロールバック用に設定されています。
  8. ロールバックの決定を行う責任者が明確に指定されています。

最後の項目は、午前2時にインシデントが起きるまで馬鹿げているように見えます。誰かがフラグを切り替えることを許可される必要があります。

ステップ6:コストを確認してから切り替え

自社のトラフィックから新しい請求書を計算します。料金は入力トークン100万トークンあたり$0.15、出力トークン100万トークンあたり$0.50です。

例:1日あたり10,000リクエスト、各リクエストに1,500入力トークンと400出力トークンが含まれる場合。

  • 入力:15,000,000トークン x $0.15 / 1,000,000 = $2.25。
  • 出力:4,000,000トークン x $0.50 / 1,000,000 = $2.00。
  • 合計:1日あたり$4.25。

古いプロバイダの現在の価格ページを使用して、古い請求と比較してください。ここではサブスクリプションのない前払いクレジットで課金され、クレジットは期限切れになりません。チャージは$20から$500までの整数単位で実行され、$50以上で5%、$100以上で10%、$200以上で15%のボーナスが付与されます。暗号資産(TRC20上のUSDTまたはBase上のUSDC)で支払いされます。残額はX-Balance-USDレスポンスヘッダーに表示されるため、アラートに使用できます。

新規アカウントは、最初のテストのために$0.50の無料トライアルクレジットを受け取ることができます。価格を確認し、次にAPIキーを取得し、パラメータのマッピング中はドキュメントを開いたままにしてください。

よくある質問

ベースURLの変更だけで移行できますか?

OpenAI互換のAPIでは、ベースURL、キー、モデルIDの変更が必要です。異なるモデルは異なる回答を返すため、プロンプトのテストは引き続き行ってください。

関数呼び出しとJSONモードは引き続き機能しますか?

関数呼び出しとJSONモード(response_format json_object)はサポートされています。切り替え前に、実際のプロンプトでスキーマを検証してください。

アプリが埋め込みを使用している場合はどうすればよいですか?

このAPIはテキストのみで、埋め込み、画像生成、ファインチューニングを提供しません。それらの呼び出しは現在のプロバイダーに維持してください。

どのように素早くロールバックしますか?

ロールアウト率などの環境フラグでルーティングし、新しいルーティングが数日間正常に実行されるまで、古いクライアントの設定を維持してください。

APIキーを取得

登録し、キーをコピーし、ベースURLを更新します。セットアップは完了です。

API キーを取得