OCIリージョン間でのモデル・リクエストのルーティング

オンデマンド・モデルのルーティング・プロファイルを作成し、チャット完了およびPythonアプリケーションからのレスポンス・リクエストのルーティング・プロファイルOCIDを使用します。

概要

ルーティング・プロファイルは、サポートされている1つのオンデマンド・モデルと、そのモデルが使用可能な同じレルム内の1つ以上のターゲットOCIリージョンを指定します。アプリケーションは、リージョナルOCI生成AI APIエンドポイントにリクエストを送信し、ルーティング・プロファイルOCIDをmodel値として渡します。生成AIは、プロファイルの適格なリージョンからの各リクエストを処理します。

アプリケーションで同じモデルと承認されたサービス・リージョンのセットが必要な場合は、1つのプロファイルを使用します。各アプリケーションでリージョン・リストを保持するかわりに、OCIでプロファイルの構成を更新できます。複数のターゲット・リージョンを持つプロファイルは、ラウンドロビン・ルーティングまたは固定リージョン優先度を意味しません。

このチュートリアルでは、2つのPythonアプリケーションがシカゴAPIエンドポイントを呼び出します。1つはチャット完了を使用し、もう1つはレスポンスを使用します。どちらも、シカゴ、フランクフルトまたは大阪からの提供を許可するopenai.gpt-oss-120bのルーティング・プロファイルを使用します。

プロファイルを作成し、OpenAI Python SDKをインストールし、両方の例を実行して、x-genai-selected-regionレスポンス・ヘッダーをチェックし、各リクエストを処理したリージョンを確認します。

ノート

選択したモデルがOCIチャット完了およびレスポンスAPIの両方をサポートしている場合にのみ、両方のAPIでプロファイルを使用できます。どちらのAPIも、CPUのみのリージョンのルーティング・プロファイルを介して使用できます。CPUのみのリージョンからコールする場合は、そのリージョンのAPIエンドポイントを使用し、モデルが使用可能なターゲット・リージョンを選択します。

始める前に

このチュートリアルを完了するには、次のものが必要です。

OCI生成AIへのアクセス、選択したコンパートメントにルーティング・プロファイルを作成する権限、および推論に使用する権限。API-Level Permissions for Routing Profilesを参照してください。
ターゲット・リージョンでテナンシで使用可能な、サポートされているオンデマンド・モデル。両方の例を1つのプロファイルで実行するには、両方のAPIをサポートするモデルを選択します。リージョン別の生成AIモデルを参照してください。
シカゴ・エンドポイントを介したリクエストに対して認可されたOCI生成AI APIキー。キーをソース・コードに配置したり、リポジトリにコミットしないでください。
Python 3.11以降、およびuvはmacOS、LinuxまたはWindows Subsystem for Linuxにインストールされます。このチュートリアルのコマンドは、Bash互換のシェルを使用します。

この例では、OpenAI Python SDKをOCIのOpenAI互換エンドポイントとともに使用します。OCI Python SDKやOCI CLIは必要ありません。

1. ルーティング・プロファイルの作成

この例では、US Midwest (Chicago)にプロファイルを作成します。ターゲット・リージョンはAPIエンドポイント・リージョンと異なる場合がありますが、選択したモデルおよび同じレルムで使用可能である必要があります。この例のモデルまたはリージョンがテナンシで使用できない場合は、使用可能なオプションを選択します。

OCIコンソールにサインインし、リージョン・セレクタから「US Midwest (Chicago)」(us-chicago-1)を選択します。
「分析とAI」を開き、「生成AI」、「ルーティング・プロファイル」の順に選択します。
リストページの詳細は、Listing Routing Profilesを参照してください。
「ルーティング・プロファイルの作成」を選択します。
gpt-oss-multiregionなどの名前を入力し、コンパートメントを選択し、オプションで説明またはタグを追加します。
「構成」で、「モデル選択」からopenai.gpt-oss-120bを選択します。

OpenAI gpt-oss-120bは、シカゴ、フランクフルトおよび大阪でオンデマンドで使用でき、OCIチャット完了APIとレスポンスAPIの両方をサポートしています。

モデルを選択するには、「リージョン別モデル」でターゲット・リージョンのオンデマンド可用性を確認し、コールする予定のAPIでサポートされているモデルの場合は「OCI OpenAI互換エンドポイントのモデルとリージョン」を選択します。
「ターゲットOCIリージョン」で、モデルを提供できるリージョンを選択します。
この例では、次のリージョンを選択します。
- 米国中西部(シカゴ): us-chicago-1
- ドイツ中央部(フランクフルト): eu-frankfurt-1
- 日本中央部(大阪): ap-osaka-1
「作成」を選択します。
プロファイルの詳細ページを開きます。ステータスが「アクティブ」であることを確認し、選択したモデルおよびターゲットOCIリージョンを確認します。プロファイルの完全なOCIDをコピーします。
このページの詳細は、「ルーティング・プロファイルの詳細の取得」を参照してください。OCIDは、両方のスクリプトでmodel値として使用します。

このプロファイルは、サポートされているオンデマンド推論リクエストに対応しています。

2.Python環境の準備

作業ディレクトリで、仮想環境を作成およびアクティブ化し、OpenAI Python SDKをインストールします:
```
uv venv --python 3.11 .venv
source .venv/bin/activate
uv pip install --upgrade openai
```
.venvがすでに存在する場合は、アクティブ化してインストール・コマンドを実行します。これらの例では、OCI Python SDKは必要ありません。
現在のシェルのAPIエンドポイント・リージョンおよびルーティング・プロファイルOCIDを設定します。
```
export OCI_REGION=us-chicago-1
export OCI_ROUTING_PROFILE_OCID='<your-routing-profile-ocid>'
```
<your-routing-profile-ocid>を、ルーティング・プロファイルに表示される完全なOCIDに置き換えます。OCI_REGIONは、リクエストを受信するリージョンAPIエンドポイントを決定します。ルーティング・プロファイルは、モデルが処理できるリージョンを指定します。
OCI生成AI APIキーを準備します。
シークレット・マネージャまたは別のセキュア・メカニズムによってOCI_GENAI_API_KEYが設定されていない場合、各スクリプトでは、キーを表示せずにキーの入力を求められます。どちらのスクリプトにもキーを貼り付けないでください。

3. チャット完了の例の実行

次のコードをrouting-chat-completion.pyとして作業ディレクトリに保存します。

"""Chat with an OCI Generative AI routing profile."""

from __future__ import annotations

import os
from getpass import getpass

from openai import OpenAI


def main() -> None:
    region = os.environ.get("OCI_REGION", "us-chicago-1")
    profile_ocid = os.environ["OCI_ROUTING_PROFILE_OCID"]
    api_key = os.environ.get("OCI_GENAI_API_KEY") or getpass(
        "OCI Generative AI API key: "
    )
    client = OpenAI(
        base_url=f"https://inference.generativeai.{region}.oci.oraclecloud.com/openai/v1",
        api_key=api_key,
    )

    messages: list[dict[str, str]] = []
    print("Chat Completions with a routing profile. Type 'exit' to stop.\n")

    while True:
        try:
            prompt = input("You: ").strip()
        except (EOFError, KeyboardInterrupt):
            print("\nGoodbye!")
            break

        if prompt.lower() in {"exit", "quit"}:
            print("Goodbye!")
            break
        if not prompt:
            continue

        messages.append({"role": "user", "content": prompt})
        answer_parts: list[str] = []

        try:
            with client.chat.completions.create(
                model=profile_ocid,
                messages=messages,
                stream=True,
            ) as stream:
                selected_region = stream.response.headers.get(
                    "x-genai-selected-region"
                )
                print(f"Served from OCI region: {selected_region or 'not reported'}")
                print("Assistant: ", end="", flush=True)

                for chunk in stream:
                    if not chunk.choices:
                        continue
                    content = chunk.choices[0].delta.content
                    if content:
                        answer_parts.append(content)
                        print(content, end="", flush=True)
        except Exception as error:
            messages.pop()
            print(f"\nRequest failed: {error}\n")
            continue

        answer = "".join(answer_parts)
        if answer:
            messages.append({"role": "assistant", "content": answer})
        else:
            messages.pop()
        print("\n")


if __name__ == "__main__":
    main()

仮想環境がアクティブ化された状態で、スクリプトを実行します。
```
python routing-chat-completion.py
```
You:にプロンプトを入力します。レスポンスの後に、フォローアップまたはexitを入力して停止します。
スクリプトは、chunk.choices[0].delta.contentからテキストをストリーミングし、現在のプロセスの会話履歴をローカルに保持します。

4. レスポンスの実行例

この例は、ルーティング・プロファイルで選択されたモデルがレスポンスAPIをサポートする場合にのみ使用します。チャット完了の例と同じプロファイルOCIDおよびリージョン・エンドポイントが使用されます。

次のコードをrouting-responses-api.pyとして作業ディレクトリに保存します。

"""Use the Responses API with an OCI Generative AI routing profile."""

from __future__ import annotations

import os
from getpass import getpass

from openai import OpenAI


def main() -> None:
    region = os.environ.get("OCI_REGION", "us-chicago-1")
    profile_ocid = os.environ["OCI_ROUTING_PROFILE_OCID"]
    api_key = os.environ.get("OCI_GENAI_API_KEY") or getpass(
        "OCI Generative AI API key: "
    )
    client = OpenAI(
        base_url=f"https://inference.generativeai.{region}.oci.oraclecloud.com/openai/v1",
        api_key=api_key,
    )

    messages: list[dict[str, str]] = []
    print("Responses with a routing profile. Type 'exit' to stop.\n")

    while True:
        try:
            prompt = input("You: ").strip()
        except (EOFError, KeyboardInterrupt):
            print("\nGoodbye!")
            break

        if prompt.lower() in {"exit", "quit"}:
            print("Goodbye!")
            break
        if not prompt:
            continue

        messages.append({"role": "user", "content": prompt})
        answer_parts: list[str] = []

        try:
            with client.responses.create(
                model=profile_ocid,
                input=messages,
                stream=True,
            ) as stream:
                selected_region = stream.response.headers.get(
                    "x-genai-selected-region"
                )
                print(f"Served from OCI region: {selected_region or 'not reported'}")
                print("Assistant: ", end="", flush=True)

                for event in stream:
                    if event.type == "response.output_text.delta":
                        answer_parts.append(event.delta)
                        print(event.delta, end="", flush=True)
        except Exception as error:
            messages.pop()
            print(f"\nRequest failed: {error}\n")
            continue

        answer = "".join(answer_parts)
        if answer:
            messages.append({"role": "assistant", "content": answer})
        else:
            messages.pop()
        print("\n")


if __name__ == "__main__":
    main()

仮想環境がアクティブ化された状態で、スクリプトを実行します。
```
python routing-responses-api.py
```
プロンプトとフォローアップを入力し、exitを入力して停止します。
スクリプトはresponse.output_text.deltaイベントをストリームします。会話履歴をローカルに保持し、各ターンで再送信します。previous_response_idまたはサーバー管理の会話は使用しません。その他のイベント・タイプは無視されます。

結果の確認とトラブルシューティング

どちらのスクリプトでも、Explain model routing in two sentences.などのプロンプトを入力します。アシスタントの応答は端末にストリームされます。OCIがx-genai-selected-regionを返す場合、スクリプトはリクエストを処理したリージョンを表示します。APIエンドポイントのリージョンであるシカゴと異なる場合がありますが、プロファイルのターゲット・リージョンの1つである必要があります。

どちらの例も、空のプロンプトをスキップします。exitまたはquitと入力し、Ctrl+Cを押すか、プロンプトで入力終了を送信して停止します。履歴は、スクリプトの実行中にのみ保持されます。


現象	確認対象
認証または認可エラー	OCI生成AI APIキー、そのリージョンとアクセス、ルーティング・プロファイルの読取り権限、および推論操作の権限を確認します。
プロファイルが見つからないか、モデル値が無効です	`OCI_ROUTING_PROFILE_OCID`のフル・プロファイルOCIDを使用します。プロファイルが「アクティブ」であり、`OCI_REGION`がコールするエンドポイント・リージョンを指していることを確認します。
サポートされていないAPIまたはリクエスト・パラメータ	選択したプロファイル・モデルが、スクリプトで使用されるAPIをサポートしていることを確認します。このチュートリアルでは、モデル固有の`reasoning`パラメータは必要ありません。
要求を処理できません	選択したモデルがプロファイルのターゲット・リージョンで使用可能であることを確認し、返されたエラーをレビューします。
提供リージョンは`not reported`です	スクリプトでは、レスポンス・ヘッダーに`x-genai-selected-region`が見つかりませんでした。レスポンスとサービスの動作を確認し、APIエンドポイントのみからサービング・リージョンを推測しないでください。

この例では、プロファイルベースのリクエストとストリーミング・テキストを示します。ルーティング優先度、ロード・バランシング・アルゴリズムまたはフェイルオーバー・ポリシーを定義または検証しません。

Oracle Cloud Infrastructureドキュメント