公式SDKからの移行
既存のOpenAI、Anthropic、またはGemini SDKアプリケーションをAGTCloudへ接続し、互換性の境界を体系的に確認します。
アプリケーションがすでにOpenAI、Anthropic、GeminiのいずれかのSDKを使用している場合は、通常、元のSDKとアプリケーション構造を維持したまま、同じプロトコルに対応するAGTCloudへ接続できます。移行ではアドレスだけでなく、認証、モデルID、SDKが自動追加するパス、リクエストフィールド、レスポンス解析もまとめて確認する必要があります。
プロトコルの一貫性を保つ
OpenAI、Anthropic Messages、Gemini Generate Contentは、それぞれ異なるプロトコルです。まずは同じプロトコルのままサービスアドレスを置き換えてください。同時にプロトコルも変更する場合は、インターフェイス移行として別途設計・検証してください。
移行前の棚卸し
最小テキストリクエストだけで判断しないよう、まず現在のアプリケーションで実際に利用している機能を整理します。
| チェック項目 | 記録する必要があるもの |
|---|---|
| SDK | パッケージ名、言語、バージョン、同期または非同期クライアント |
| プロトコル | Chat Completions、Responses、Messages またはコンテンツの生成 |
| モデル | 現在のモデルID、およびコード内にモデルのホワイトリストがあるかどうか |
| 入力 | テキスト、画像、ファイル、システム コマンド、履歴メッセージ |
| 出力 | テキスト ショートカット プロパティ、完全な応答オブジェクト、カスタム解析ロジック |
| Streaming | イベントタイプ、差分の連結、終了判定 |
| ツール | ツール定義、コール ID、パラメータ解析、および結果の返却 |
| 信頼性 | タイムアウト、再試行、レート制限、ログおよびロールバック戦略 |
最小限の変更
3種類のSDKはいずれも次の設定を確認する必要がありますが、指定方法はSDKごとに異なります。
| 構成 | 移行アクション |
|---|---|
| API アドレス | このページの対応するチュートリアルで指定されている Origin または Base URLを使用して、SDK がバージョン パスを自動的に追加するかどうかを確認します。 |
| API Key | 環境変数から AGTCloud API Keyを読み取り、ソースコードやリポジトリに書き込まないでください。 |
| モデルID | 現在のAPI Keyで利用可能で、対象プロトコルをサポートするモデルを使用します。 |
| リクエスト方法 | chat.completions.create や messages.create など、元のプロトコルのクライアントメソッドを保持します。 |
| 応答読み取り | テキスト、ツール、Usage、およびエラー構造を AGTCloud リファレンスと照合します。 |
SDK別に移行する
OpenAI SDK は Chat Completions と Responses を呼び出すことができます。 AGTCloud Base URL には /v1 が含まれます。
| 移行前 | 移行後 |
|---|---|
| 元のサービスの API Key | AGTCLOUD_API_KEY 環境変数 |
| Base URL または SDK 元のサービスのデフォルト アドレス | https://api.agtcloud.cn/v1 |
| 元のモデル名 | 現在のAPI Keyで利用可能な MODEL_ID |
| 従来のチャットまたは Responses メソッド | 同じクライアントメソッドを維持する |
/v1 を繰り返し追加しないでください
https://api.agtcloud.cn/v1 にはすでにバージョン パスが含まれています。 https://api.agtcloud.cn/v1/v1 に構成したり、/chat/completions または /responses エンドポイント全体を追加したりしないでください。
完全なインストール、クライアントの初期化、および Python、TypeScript の例については、OpenAI SDK を参照してください。
3つの設定変更だけでは移行できない場合
次のシナリオでは、Base URL、キー、モデルを単に置き換えるのではなく、ビジネス コードを調整する必要があります。
- アプリケーションが Chat Completions から Responses に変更されました。
- OpenAI、Anthropic、または Gemini プロトコル間でのアプリケーションの移行。
- このコードは、SDK 応答クラス、ショートカット プロパティ、またはストリーミングイベントに直接依存します。
- ツール呼び出しでは、プロトコル固有の定義と結果戻り構造が使用されます。
- マルチモーダル Content Block、システム ディレクティブ、またはロール名の変更。
- SDK はパスを自動的に結合し、元のプロジェクトは完全なエンドポイント URL を渡します。
- アプリケーションは、モデルの検出、ファイルのアップロード、または元のサービスに固有のホスティング ツールに依存します。
移行結果を確認する
最小限のテキストリクエストを確認する
まず、ストリーミング、ツール、またはマルチモーダル コンテンツを使用しないリクエストを送信します。リクエストが予期された APIアドレスへ送信され、テキスト応答を読み取ることができることを確認します。
生産を復元するために必要な容量
ストリーミング、ツール呼び出し、構造化出力、マルチモダリティ、マルチターン状態の順序で 1 つずつ段階的に戻します。違いを見つけやすくするために、一度に追加される機能は 1 つだけです。
失敗したパスをチェックする
少なくとも無効な API Key、不正なモデルID、タイムアウト、スロットリング、および接続の中断を検証します。アプリケーションがステータス コードとエラー メッセージを読み取ることができ、無限に再試行しないことを確認します。
業績を比較する
HTTP 200だけで判断せず、ログ内のテキスト内容、ツール引数、終了理由、Usage、ストリーミングの終了判定、リクエストIDを対応付けて比較します。
段階的な切り替えとロールバック
- ビジネス コード内にアドレスやモデル名を散りばめることなく、新旧の Providerを別々の設定として保持します。
- 開発またはテスト トラフィック用の AGTCloud から始めて、時間の経過とともに範囲を拡大します。
- 各ステージの成功率、遅延、エラーの種類、機能の違いを記録します。
- 元のProvider設定と制御可能なロールバック スイッチを保持し、安定性を確認した後に古い設定をクリーンアップします。
サイレント無視に頼らないでください
一部の準拠した実装では、不明なフィールドを受け入れても、対応する機能が実装されていない場合があります。検証中は、実際の結果と応答構造を観察する必要があります。ステータスコードだけではフィールドが有効になったかどうかを判断できません。
次のステップ
- SDK 概要 を表示し、対応するチュートリアルを選択します。
- API Key、Base URL および認証 を表示します。
- Chat から Responses に移行する準備ができている場合は、Chat Completions → Responses を参照してください。
- ステータス コードまたはリクエストの失敗が発生した場合は、エラーとトラブルシューティング を参照してください。