Acheminer les demandes de modèle entre les régions OCI

Créez un profil d'acheminement pour un modèle sur demande, puis utilisez l'OCID du profil d'acheminement dans les demandes d'achèvement et de réponse de clavardage des applications Python.

Aperçu

Un profil d'acheminement spécifie un modèle sur demande pris en charge et une ou plusieurs régions OCI cibles dans le même domaine où ce modèle est disponible. Les applications envoient des demandes à un point d'extrémité régional de l'API du service d'intelligence artificielle générative pour OCI et transmettent l'OCID du profil d'acheminement en tant que valeur model. L'intelligence artificielle générative répond à chaque demande d'une région admissible dans le profil.

Utilisez un profil lorsque les applications ont besoin du même modèle et du même jeu approuvé de régions de desserte. Vous pouvez mettre à jour la configuration du profil dans OCI au lieu de tenir à jour une liste de régions dans chaque application. Un profil comportant plusieurs régions cibles n'implique pas un routage cyclique ou une priorité de région fixe.

Dans ce tutoriel, deux applications Python appellent le point d'extrémité de l'API de Chicago. L'un utilise les achèvements de clavardage et l'autre utilise les réponses. Les deux utilisent un profil d'acheminement pour openai.gpt-oss-120b qui permet de servir à partir de Chicago, Francfort ou Osaka.

Vous créez un profil, installez la trousse SDK Python OpenAI, exécutez les deux exemples et vérifiez l'en-tête de réponse x-genai-selected-region pour voir quelle région a servi chaque demande.

Note

Vous ne pouvez utiliser un profil avec les deux API que si son modèle sélectionné prend en charge à la fois l'API de fin d'exécution de clavardage OCI et l'API de réponses OCI. Les deux API sont disponibles au moyen de profils d'acheminement dans des régions sans traitement de modèle local. Lors de l'appel à partir d'une de ces régions, utilisez le point d'extrémité d'API de cette région et sélectionnez les régions cibles où le modèle est disponible.

Avant de commencer

Pour terminer ce tutoriel, vous devez :

Accès au service d'intelligence artificielle générative pour OCI, autorisation de créer un profil d'acheminement dans le compartiment sélectionné et autorisation de l'utiliser pour l'inférence. Voir Autorisations au niveau de l'API pour les profils d'acheminement.
Modèle sur demande pris en charge disponible pour votre location dans les régions cibles. Pour exécuter les deux exemples avec un profil, sélectionnez un modèle qui prend en charge les deux API. Voir Modèles d'IA générative par région.
Une clé d'API du service d'intelligence artificielle générative pour OCI autorisée pour les demandes au moyen du point d'extrémité de Chicago. Ne placez pas la clé dans le code source ou ne la validez pas dans un référentiel.
Python 3.11 ou version ultérieure, et uv installés sur macOS, Linux ou Windows Subsystem pour Linux. Les commandes de ce tutoriel utilisent un interpréteur de commandes compatible avec Bash.

Les exemples utilisent la trousse SDK Python OpenAI avec le point d'extrémité compatible OpenAI d'OCI. Ils ne nécessitent pas la trousse SDK Python pour OCI ou l'interface de ligne de commande pour OCI.

1. Créer un profil d'acheminement

Cet exemple crée un profil dans US Midwest (Chicago). Ses régions cibles peuvent différer de la région du point d'extrémité de l'API, mais elles doivent être disponibles pour le modèle sélectionné et dans le même domaine. Si un modèle ou une région dans cet exemple n'est pas disponible pour votre location, sélectionnez une option disponible.

Connectez-vous à la console OCI et sélectionnez États-Unis - Midwest (Chicago) (us-chicago-1) dans le sélecteur de région.
Ouvrez Analyse et intelligence artificielle, sélectionnez Intelligence artificielle générative, puis Profils d'acheminement.
Pour plus d'informations sur la page de liste, voir Liste des profils d'acheminement.
Sélectionnez Créer un profil d'acheminement.
Entrez un nom, tel que gpt-oss-multiregion, sélectionnez un compartiment et ajoutez éventuellement une description ou des marqueurs.
Sous Configuration, sélectionnez openai.gpt-oss-120b dans Sélection de modèle.

OpenAI gpt-oss-120b est disponible sur demande à Chicago, Francfort et Osaka et prend en charge à la fois l'API d'achèvement de clavardage OCI et l'API de réponses OCI.

Pour sélectionner un modèle, vérifiez la disponibilité sur demande des modèles par région dans les régions cibles et les modèles et régions pour les points d'extrémité compatibles avec OCI OpenAI pour les modèles pris en charge par les API que vous prévoyez d'appeler.
Sous Régions OCI cibles, sélectionnez les régions à partir desquelles le modèle peut être servi.
Dans cet exemple, sélectionnez les régions suivantes :
- Midwest américain (Chicago) : us-chicago-1
- Centre de l'Allemagne (Francfort) : eu-frankfurt-1
- Centre du Japon (Osaka) : ap-osaka-1
Sélectionnez Créer.
Ouvrez la page des détails du profil. Vérifiez que son statut est Actif et vérifiez le modèle sélectionné et les régions OCI cibles. Copiez l'OCID complet du profil.
Pour plus de détails sur cette page, voir Obtention des détails d'un profil d'acheminement. Vous utilisez l'OCID comme valeur model dans les deux scripts.

Le profil est prêt pour les demandes d'inférence sur demande prises en charge.

2. Préparer l'environnement Python

Dans un répertoire de travail, créez et activez un environnement virtuel et installez la trousse SDK Python OpenAI :
```
uv venv --python 3.11 .venv
source .venv/bin/activate
uv pip install --upgrade openai
```
Si .venv existe déjà, activez-le et exécutez la commande d'installation. La trousse SDK Python pour OCI n'est pas nécessaire pour ces exemples.
Définissez la région de point d'extrémité d'API et l'OCID du profil d'acheminement pour l'interpréteur de commandes courant :
```
export OCI_REGION=us-chicago-1
export OCI_ROUTING_PROFILE_OCID='<your-routing-profile-ocid>'
```
Remplacez <your-routing-profile-ocid> par l'OCID complet affiché dans le profil d'acheminement. OCI_REGION détermine quel point d'extrémité d'API régional reçoit la demande. Le profil d'acheminement spécifie les régions où le modèle peut le servir.
Avoir une clé d'API OCI Generative AI prête.
Chaque script invite à entrer la clé sans l'afficher si OCI_GENAI_API_KEY n'est pas défini par un gestionnaire de clés secrètes ou un autre mécanisme sécurisé. Ne collez la clé dans aucun des scripts.

3. Exécuter l'exemple d'achèvement de clavardage

Enregistrez le code suivant sous le nom routing-chat-completion.py dans votre répertoire de travail :

"""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()

Lorsque l'environnement virtuel est activé, exécutez le script :
```
python routing-chat-completion.py
```
À You:, entrez une invite. Après la réponse, entrez un suivi ou exit à arrêter.
Le script diffuse le texte à partir de chunk.choices[0].delta.content et conserve l'historique de conversation localement pour le processus courant.

4. Exemple d'exécution des réponses

Utilisez cet exemple uniquement si le modèle sélectionné dans le profil d'acheminement prend en charge l'API Réponses. Il utilise le même OCID de profil et le même point d'extrémité régional que l'exemple d'achèvement de clavardage.

Enregistrez le code suivant sous le nom routing-responses-api.py dans le répertoire de travail :

"""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()

Lorsque l'environnement virtuel est activé, exécutez le script :
```
python routing-responses-api.py
```
Entrez une invite et un suivi, puis entrez exit pour arrêter.
Le script diffuse les événements response.output_text.delta. Il conserve l'historique des conversations localement et le renvoie à chaque tour; il n'utilise pas previous_response_id ou une conversation gérée par le serveur. Les autres types d'événement sont ignorés.

Vérifier le résultat et le dépannage

Dans l'un ou l'autre des scripts, entrez une invite telle que Explain model routing in two sentences. La réponse de l'assistant doit être transmise au terminal. Si OCI retourne x-genai-selected-region, le script affiche la région qui a servi la demande. Il peut différer de Chicago, la région du point d'extrémité de l'API, mais doit être l'une des régions cibles du profil.

Les deux exemples ignorent les invites vides. Entrez exit ou quit, appuyez sur Ctrl+C ou envoyez la fin de l'entrée à l'invite pour vous arrêter. L'historique n'est conservé que pendant l'exécution du script.


Symptôme	Que vérifier
Erreur d'authentification ou d'autorisation	Vérifiez la clé d'API du service d'intelligence artificielle générative pour OCI, sa région et son accès, l'autorisation de lecture du profil d'acheminement et l'autorisation pour l'opération d'inférence.
Profil introuvable ou valeur de modèle non valide	Utilisez l'OCID de profil complet dans `OCI_ROUTING_PROFILE_OCID`. Vérifiez que le profil est actif et que `OCI_REGION` pointe vers la région de point d'extrémité que vous voulez appeler.
API ou paramètre de demande non pris en charge	Vérifiez que le modèle sélectionné du profil prend en charge l'API utilisée par le script. Ce tutoriel ne nécessite pas de paramètre `reasoning` propre au modèle.
La demande ne peut pas être servie	Vérifiez que le modèle sélectionné est disponible dans les régions cibles du profil et vérifiez l'erreur retournée.
La région du service est `not reported`	Le script n'a pas trouvé `x-genai-selected-region` dans les en-têtes de réponse. Vérifiez la réponse et le comportement du service; ne déduisez pas la région de service uniquement à partir du point d'extrémité de l'API.

Les exemples montrent les demandes basées sur un profil et la diffusion de texte en continu. Ils ne définissent ni ne vérifient pas de priorité de routage, d'algorithme d'équilibrage de charge ou de politique de basculement.

Documentation sur Oracle Cloud Infrastructure