Modellanforderungen über OCI-Regionen hinweg weiterleiten

Erstellen Sie ein Routingprofil für ein On-Demand-Modell, und verwenden Sie dann die Routingprofil-OCID in Chatabschlüssen und -antwortenanforderungen aus Python-Anwendungen.

Überblick

Ein Routingprofil gibt ein unterstütztes On-Demand-Modell und mindestens eine OCI-Zielregion in derselben Realm an, in der dieses Modell verfügbar ist. Anwendungen senden Anforderungen an einen regionalen OCI Generative AI-API-Endpunkt und übergeben die Routingprofil-OCID als Wert model. Generative KI bedient jede Anforderung aus einer berechtigten Region im Profil.

Verwenden Sie ein Profil, wenn Anwendungen dasselbe Modell und eine genehmigte Gruppe von Serving-Regionen benötigen. Sie können die Konfiguration des Profils in OCI aktualisieren, anstatt eine Regionsliste in jeder Anwendung zu verwalten. Ein Profil mit mehreren Zielregionen bedeutet kein Round-Robin-Routing oder keine feste Regionspriorität.

In diesem Tutorial rufen zwei Python-Anwendungen den Chicago API-Endpunkt auf. Eine verwendet Chat-Abschlüsse und die andere verwendet Antworten. Beide verwenden ein Routingprofil für openai.gpt-oss-120b, das das Servieren aus Chicago, Frankfurt oder Osaka ermöglicht.

Zwei Anwendungen senden Chatabschlüsse und -antworten an den Chicago OCI Generative AI API-Endpunkt. Beide übergeben dieselbe Routingprofil-OCID wie das Modell. Das Profil wählt das On-Demand-Modell openai.gpt-oss-120b aus und ermöglicht es, aus Chicago, Frankfurt oder Osaka zu dienen.

Sie erstellen ein Profil, installieren das Python-SDK OpenAI, führen beide Beispiele aus, und prüfen den Antwortheader x-genai-selected-region, um zu sehen, welche Region für jede Anforderung bereitgestellt wurde.

Hinweis

Sie können ein Profil mit beiden APIs nur verwenden, wenn das ausgewählte Modell sowohl die OCI Chat Completions API als auch die OCI Responses API unterstützt. Beide APIs sind über Routingprofile in Regionen ohne lokale Modellverarbeitung verfügbar. Verwenden Sie beim Aufruf aus einer dieser Regionen den API-Endpunkt dieser Region, und wählen Sie Zielregionen aus, in denen das Modell verfügbar ist.

Bevor Sie beginnen

Um dieses Tutorial abzuschließen, benötigen Sie:

  • Zugriff auf OCI Generative AI, Berechtigung zum Erstellen eines Routingprofils im ausgewählten Compartment und Berechtigung zum Verwenden für Inferenz. Siehe Berechtigungen auf API-Ebene für Routingprofile.
  • Ein unterstütztes On-Demand-Modell, das für Ihren Mandanten in den Zielregionen verfügbar ist. Um beide Beispiele mit einem Profil auszuführen, wählen Sie ein Modell aus, das beide APIs unterstützt. Siehe Generative KI-Modelle nach Region.
  • Ein OCI Generative AI-API-Schlüssel, der für Anforderungen über den Chicago-Endpunkt autorisiert ist. Setzen Sie den Schlüssel nicht in den Quellcode, oder schreiben Sie ihn nicht in ein Repository fest.
  • Python 3.11 oder höher und uv auf macOS, Linux oder Windows-Subsystem für Linux installiert. Die Befehle in diesem Tutorial verwenden eine Bash-kompatible Shell.

In den Beispielen wird das Python-SDK OpenAI mit dem OpenAI-kompatiblen OCI-Endpunkt verwendet. Sie erfordern weder das OCI-Python-SDK noch die OCI-CLI.

1. Weiterleitungsprofil erstellen

In diesem Beispiel wird ein Profil in US Midwest (Chicago) erstellt. Die Zielregionen können sich von der API-Endpunktregion unterscheiden. Sie müssen jedoch für das ausgewählte Modell und in derselben Realm verfügbar sein. Wenn ein Modell oder eine Region in diesem Beispiel für Ihren Mandanten nicht verfügbar ist, wählen Sie eine verfügbare Option aus.

  1. Melden Sie sich bei der OCI-Konsole an, und wählen Sie US Midwest (Chicago) (us-chicago-1) im Regionsselektor aus.
  2. Öffnen Sie Analysen und KI, wählen Sie Generative KI und dann Routingprofile aus.
    Weitere Informationen zur Listenseite finden Sie unter Routingprofile auflisten.
  3. Wählen Sie Routingprofil erstellen aus.
  4. Geben Sie einen Namen wie gpt-oss-multiregion ein, wählen Sie ein Compartment aus, und fügen Sie optional eine Beschreibung oder Tags hinzu.
  5. Wählen Sie unter Konfiguration unter Modellauswahl die Option openai.gpt-oss-120b aus.

    OpenAI gpt-oss-120b ist auf Anforderung in Chicago, Frankfurt und Osaka verfügbar und unterstützt sowohl die OCI Chat Completions API als auch die OCI Responses API.

    Um ein Modell auszuwählen, prüfen Sie Modelle nach Region auf On-Demand-Verfügbarkeit in Ihren Zielregionen und Modelle und Regionen für OpenAI-kompatible OCI-Endpunkte auf Modelle, die von den APIs unterstützt werden, die Sie aufrufen möchten.

  6. Wählen Sie unter OCI-Regionen als Ziel festlegen die Regionen aus, aus denen das Modell bedient werden kann.

    Wählen Sie in diesem Beispiel die folgenden Regionen aus:

    • US Midwest (Chicago): us-chicago-1
    • Germany Central (Frankfurt): eu-frankfurt-1
    • Japan Central (Osaka): ap-osaka-1
  7. Wählen Sie Erstellen aus.
  8. Öffnen Sie die Detailseite des Profils. Bestätigen Sie, dass der Status Aktiv lautet, und prüfen Sie das ausgewählte Modell und die ausgewählten OCI-Zielregionen. Kopieren Sie die vollständige OCID des Profils.
    Weitere Informationen zu dieser Seite finden Sie unter Details eines Routingprofils abrufen. Sie verwenden die OCID als Wert model in beiden Skripten.
Das Profil ist bereit für unterstützte On-Demand-Inferenzanforderungen.

2. Python-Umgebung vorbereiten

  1. Erstellen und aktivieren Sie in einem Arbeitsverzeichnis eine virtuelle Umgebung, und installieren Sie das Python-SDK OpenAI:
    uv venv --python 3.11 .venv
    source .venv/bin/activate
    uv pip install --upgrade openai

    Wenn .venv bereits vorhanden ist, aktivieren Sie es, und führen Sie den Installationsbefehl aus. Für diese Beispiele ist das OCI-Python-SDK nicht erforderlich.

  2. Legen Sie die API-Endpunktregion und die Routingprofil-OCID für die aktuelle Shell fest:
    export OCI_REGION=us-chicago-1
    export OCI_ROUTING_PROFILE_OCID='<your-routing-profile-ocid>'

    Ersetzen Sie <your-routing-profile-ocid> durch die vollständige OCID, die im Routingprofil angezeigt wird. OCI_REGION bestimmt, welcher regionale API-Endpunkt die Anforderung empfängt. Das Routingprofil gibt die Regionen an, in denen das Modell das Routing ausführen kann.

  3. Halten Sie einen OCI Generative AI-API-Schlüssel bereit.
    Jedes Skript fordert zur Eingabe des Schlüssels auf, ohne ihn anzuzeigen, wenn OCI_GENAI_API_KEY nicht von einem Secret Manager oder einem anderen sicheren Mechanismus festgelegt wird. Fügen Sie den Schlüssel nicht in ein Skript ein.

3. Beispiel für Chatabschlüsse ausführen

  1. Speichern Sie den folgenden Code als routing-chat-completion.py in Ihrem Arbeitsverzeichnis:
    """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()
  2. Wenn die virtuelle Umgebung aktiviert ist, führen Sie das Skript aus:
    python routing-chat-completion.py
  3. Geben Sie unter You: einen Prompt ein. Geben Sie nach der Antwort ein Follow-up ein, oder exit, um den Vorgang zu stoppen.
    Das Skript streamt Text aus chunk.choices[0].delta.content und behält die Unterhaltungshistorie lokal für den aktuellen Prozess bei.

4. Beispiel für Antworten ausführen

Verwenden Sie dieses Beispiel nur, wenn das im Routingprofil ausgewählte Modell die Responses-API unterstützt. Es verwendet dieselbe Profil-OCID und denselben regionalen Endpunkt wie das Beispiel für Chatabschlüsse.

  1. Speichern Sie den folgenden Code als routing-responses-api.py im Arbeitsverzeichnis:
    """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()
  2. Wenn die virtuelle Umgebung aktiviert ist, führen Sie das Skript aus:
    python routing-responses-api.py
  3. Geben Sie einen Prompt und eine Nachsorge ein, und geben Sie dann exit ein, um den Vorgang zu stoppen.
    Das Skript streamt response.output_text.delta-Ereignisse. Die Unterhaltungshistorie wird lokal verwaltet und bei jedem Zug erneut gesendet. previous_response_id oder eine vom Server verwaltete Unterhaltung wird nicht verwendet. Andere Eventtypen werden ignoriert.

Ergebnis prüfen und Fehler beheben

Geben Sie in jedem Skript einen Prompt wie Explain model routing in two sentences. ein. Die Antwort des Assistenten muss an das Terminal übertragen werden. Wenn OCI x-genai-selected-region zurückgibt, zeigt das Skript die Region an, die der Anforderung entsprochen hat. Sie kann sich von Chicago, der Region des API-Endpunkts, unterscheiden, muss jedoch eine der Zielregionen im Profil sein.

In beiden Beispielen werden leere Prompts übersprungen. Geben Sie exit oder quit ein, drücken Sie Ctrl+C, oder senden Sie das Ende der Eingabe an der Eingabeaufforderung, um zu stoppen. Die Historie wird nur beibehalten, wenn das Skript ausgeführt wird.

SymptomWas zu überprüfen ist
Fehler bei Authentifizierung oder Autorisierung Prüfen Sie den OCI Generative AI-API-Schlüssel, seine Region und den Zugriff, die Leseberechtigung für das Routingprofil und die Berechtigung für den Inferenzvorgang.
Profil nicht gefunden oder ungültiger Modellwert Verwenden Sie die vollständige Profil-OCID in OCI_ROUTING_PROFILE_OCID. Stellen Sie sicher, dass das Profil aktiv ist und dass OCI_REGION auf die Endpunktregion verweist, die Sie aufrufen möchten.
Nicht unterstützter API- oder Anforderungsparameter Bestätigen Sie, dass das ausgewählte Modell des Profils die vom Skript verwendete API unterstützt. Für dieses Tutorial ist kein modellspezifischer Parameter reasoning erforderlich.
Anforderung kann nicht bedient werden Prüfen Sie, ob das ausgewählte Modell in den Zielregionen des Profils verfügbar ist, und prüfen Sie den zurückgegebenen Fehler.
Serving-Region ist not reported Das Skript hat x-genai-selected-region nicht in den Antwortheadern gefunden. Prüfen Sie das Antwort- und Serviceverhalten. Ziehen Sie die Serving-Region nicht allein aus dem API-Endpunkt inferenziert.

Die Beispiele zeigen profilbasierte Anforderungen und Streamingtext. Sie definieren oder prüfen keine Routingpriorität, keinen Load Balancing-Algorithmus oder keine Failover-Policy.