Schnellstart

Führen Sie die folgenden Schritte aus, um mit der Erstellung von Enterprise AI Agents mit der OCI Responses API zu beginnen.

Tipp

Um einen Überblick über die Schritte und Features in diesem QuickStart zu erhalten, halten Sie diese Seite ausgeblendet, und prüfen Sie die Titel. Blenden Sie dann jeden Titel ein, um weitere Details anzuzeigen. In den ersten sechs Schritten wird Ihre Umgebung so eingerichtet, dass eine Modellantwort mit der Responses-API abgerufen wird. In den übrigen Abschnitten werden weitere Funktionen zum Erstellen von Agents angezeigt.

Modellantwort mit Antwort-API abrufen

Voraussetzungen

Bevor Sie ein Projekt erstellen oder die OCI-Antworten-API aufrufen, stellen Sie sicher, dass die erforderlichen IAM-Berechtigungen vorhanden sind.

Zugriff auf OCI Generative AI-Ressourcen erteilen

sk einen Administrator, um der Benutzergruppe, zu der Sie gehören, die Berechtigung zur Verwaltung von OCI Generative AI-Ressourcen im Compartment zu erteilen, das für dieses QuickStart verwendet wird, <QuickStart-compartment-name>.

allow group <your-group-name> 
to manage generative-ai-family
in compartment <QuickStart-compartment-name>

Mit dieser Berechtigung können Sie alle generativen KI-Serviceressourcen erstellen, einschließlich Projekten, API-Schlüsseln, Vektorspeichern und semantischen Speichern in der <QuickStart-compartment-name>.

Wichtig

Dieser QuickStart verwendet ein Setup im Sandbox-Stil für seine Berechtigungen. Es wird empfohlen, nur Administratoren oder Benutzern, die in Sandbox-Umgebungen arbeiten, umfassenden Zugriff zu gewähren. Wenden Sie restriktivere Policys zur Verwendung in der Produktion an.
1. Projekt erstellen

Ein Projekt ist die grundlegende Ressource für die Organisation von KI-Agenten und zugehörigen Assets in OCI Generative AI. Sie können ein Projekt mit der Konsole erstellen.

Nachdem Sie ein Projekt erstellt haben, können Sie es über die Konsole verwalten. Beispiel: Sie können die zugehörigen Details aktualisieren, in ein anderes Compartment verschieben, Tags verwalten oder löschen. Diese Aktionen stehen im Menü Aktionen (drei Punkte) auf der Projektlistenseite zur Verfügung.

Navigieren Sie zunächst zur Projektlistenseite, und wählen Sie Projekt erstellen aus.

Grundlegende Informationen

Definieren Sie zunächst die Kernattribute des Projekts.

  • Name (optional):

    Geben Sie einen Namen an, der mit einem Buchstaben oder Unterstrich beginnt, gefolgt von Buchstaben, Zahlen, Bindestrichen oder Unterstrichen. Die Länge kann zwischen 1 und 255 Zeichen betragen. Wenn Sie keinen Namen angeben, wird dieser automatisch mit dem Format generativeaiproject<timestamp> generiert, z.B. generativeaiproject20260316042443. Sie können dies später aktualisieren.

  • Beschreibung (optional):

    Fügen Sie eine kurze Beschreibung hinzu, um den Zweck des Projekts zu identifizieren.

  • Compartment:

    Wählen Sie das Compartment <QuickStart-compartment-name> aus.

Datenaufbewahrung

Konfigurieren Sie, wie lange die generierten Daten gespeichert werden.

  • Antwortaufbewahrung:

    Definiert, wie lange individuelle Modellantworten nach der Generierung gespeichert werden.

  • Aufbewahrung von Unterhaltungen:

    Legt fest, wie lange eine gesamte Unterhaltung nach der letzten Aktualisierung beibehalten wird.

Sie können beide Werte in Stunden festlegen, maximal 720 Stunden (30 Tage).

Konfiguration der Kurzzeitspeicherkomprimierung

Kurzzeitgedächtnisverdichtung fasst die jüngste Konversationsgeschichte in einer kompakten Darstellung zusammen. Es hilft, den Kontext beizubehalten und gleichzeitig die Tokenverwendung und -latenz zu reduzieren.

  • Aktivieren (optional):

    Aktivieren Sie die Kurzzeitgedächtnisverdichtung, um vorherige Interaktionen automatisch zu verdichten.

  • Modellauswahl:

    Wenn Sie diese Funktion aktivieren, wählen Sie ein Compaction-Modell aus. Die verfügbaren Modelle variieren je nach Region.

    Verfügbare Modelle finden Sie unter 2.1 Short-Term Memory Compaction (Conversation History Compaction).

Wichtig

  • Sie können das Komprimierungsmodell nur zum Zeitpunkt der Erstellung auswählen und diese Option später nicht mehr ändern.
  • Wenn diese Option aktiviert ist, kann dieses Feature nicht deaktiviert werden, ohne das Projekt zu löschen.

Konfiguration des Langzeitspeichers

Durch die Aktivierung des Langzeitgedächtnisses kann der Dienst wichtige Informationen aus Unterhaltungen extrahieren und für die zukünftige Verwendung beibehalten. Diese Daten werden als Einbettungen gespeichert, sodass sie über Interaktionen hinweg durchsuchbar und wiederverwendbar sind.

  • Aktivieren (optional):

    Aktivieren Sie das Langzeitgedächtnis, um wichtige Erkenntnisse aus Gesprächen zu erhalten.

  • Modellauswahl:

    Wählen Sie die folgenden Modelle:

    • Extraktionsmodell: Identifiziert und erfasst wichtige Informationen.
    • Einbettungsmodell: Konvertiert gespeicherte Daten zum Abrufen in Vektordarstellungen.
Wichtig

  • Sie müssen diese Modelle während der Projekterstellung auswählen.
  • Nachdem er aktiviert wurde, können Sie die Modelle nicht mehr ändern, und der Langzeitspeicher kann nur deaktiviert werden, wenn das Projekt gelöscht wird.
Tipp

Um optimale Ergebnisse zu erzielen, legen Sie sowohl die Antwortaufbewahrung als auch die Unterhaltung auf die maximale Dauer von 720 Stunden fest, wenn Sie Langzeitspeicher verwenden.

Tags

Mit Tags können Sie Ressourcen organisieren und verwalten.

  • Optional: Wählen Sie Tag hinzufügen aus, um dem Projekt Metadaten zuzuweisen.

    Weitere Informationen finden Sie unter Ressourcentags.

Nach Abschluss dieser Aufgaben können Sie Erstellen auswählen.

2. Authentifizierung einrichten

Die OCI Responses API unterstützt zwei Authentifizierungsmethoden. Sie können eine der beiden Optionen verwenden.

  • OCI Generative AI-API-Schlüssel

    Authentifizieren und erreichen Sie die Modelle und Endpunkte mit OpenAI-kompatiblen service-spezifischen API-Schlüsseln der generativen KI. Verwenden Sie diese Option für Tests und frühe Entwicklung.

  • OCI-IAM-basierte Authentifizierung

    Authentifizieren und erreichen Sie die Modelle und Endpunkte mit signierten API-Anforderungen. Wir empfehlen diese Option für Produktions-Workloads und OCI-verwaltete Umgebungen. Verwenden Sie die IAM-Authentifizierung, wenn Sie:

    • Anwendungen in OCI-Services wie Functions oder Oracle Kubernetes Engine (OKE) ausführen
    • Möchten Sie langlebige API-Schlüssel vermeiden?
    • Zentrale Zugriffskontrolle über OCI IAM erforderlich
2.1 (a) API-Schlüssel erstellen

Dieser Schritt ist nur erforderlich, wenn Sie die OCI Generative AI-API-Schlüsselauthentifizierung verwenden.

Erstellen Sie einen API-Schlüssel, um Anforderungen bei OCI Generative AI zu authentifizieren. Sie können den Schlüssel benennen und optional bis zu zwei Schlüsselnamen mit Ablaufdaten und -zeiten konfigurieren.

Sie können API-Schlüssel mit der Konsole, der CLI oder der API erstellen und verwalten.

  • Wählen Sie auf der API-Schlüsselseite Liste die Option API-Schlüssel erstellen aus.

    Grundlegende Informationen

    1. Geben Sie einen Namen für den API-Schlüssel ein. Dieses Feld ist erforderlich. Beginnen Sie den Namen mit einem Buchstaben oder Unterstrich, gefolgt von Buchstaben, Zahlen, Bindestrichen und Unterstrichen. Die Länge kann zwischen 1 und 255 Zeichen betragen.
    2. (Optional) Geben Sie eine Beschreibung ein.
    3. Speichern Sie den API-Schlüssel im Compartment <QuickStart-compartment-name>.
      Sie benötigen die Berechtigung, in einem Compartment zu arbeiten, um die darin enthaltenen Ressourcen anzuzeigen. Wenn Sie nicht sicher sind, welches Compartment verwendet werden soll, wenden Sie sich an einen Administrator. Weitere Informationen finden Sie unter Compartments.
    4. (Optional) Weisen Sie diesem API-Schlüssel Tags zu. Siehe Ressourcentags.

    Schlüsselnamen und Ablaufzeit

    1. Geben Sie unter Name des Schlüssels einen Namen für den ersten Schlüssel ein. Beginnen Sie den Namen mit einem Buchstaben oder Unterstrich, gefolgt von Buchstaben, Zahlen, Bindestrichen und Unterstrichen. Die Länge kann zwischen 1 und 255 Zeichen betragen.
    2. (Optional) Legen Sie Key One-Ablaufdatum und Key One-Ablaufzeit (UTC) fest.
      Der Standardwert beträgt drei Monate ab dem Erstellungsdatum.
    3. Geben Sie einen Namen für den zweiten Schlüssel unter Zwei-Schlüssel-Name ein.
    4. (Optional) Legen Sie das Zwei-Schlüssel-Ablaufdatum und die Zwei-Schlüssel-Ablaufzeit (UTC) fest.
      Der Standardwert beträgt drei Monate ab dem Erstellungsdatum.
    5. Wählen Sie Erstellen aus.
  • Verwenden Sie den Befehl api-key create und die erforderlichen Parameter, um einen API-Schlüssel zu erstellen.

    oci generative-ai api-key create [OPTIONS]

    Eine vollständige Liste der Parameter und Werte für CLI-Befehle finden Sie in der CLI-Befehlsreferenz.

  • Führen Sie den Vorgang CreateApiKey aus, um einen API-Schlüssel zu erstellen. Geben Sie den Anzeigenamen, die optionale Beschreibung und beliebige Schlüsselnamen mit ihren Ablaufzeitstempeln in UTC an.

2.1 (b) Berechtigung zum API-Schlüssel hinzufügen

Dieser Schritt ist nur erforderlich, wenn Sie die OCI Generative AI-API-Schlüsselauthentifizierung verwenden.

API-Schlüssel-OCID suchen

Um Berechtigungen auf einen bestimmten API-Schlüssel zu beschränken, rufen Sie zuerst die zugehörige OCID ab.

Führen Sie in der Konsole Folgendes aus:

  1. Öffnen Sie die Listenseite "API-Schlüssel".
  2. Wählen Sie den erstellten API-Schlüssel.
  3. Kopieren Sie die OCID. Er beginnt normalerweise mit ocid1.generativeaiapikey....

Berechtigung für API-Schlüssel erteilen

Um zuzulassen, dass eine bestimmte Benutzergruppe die Responses-API mit diesem API-Schlüssel aufrufen kann, fügen Sie die folgende IAM-Policy hinzu:

allow group <agent-builders-with-Responses-API-group>
to manage generative-ai-response 
in compartment <QuickStart-compartment-name> 
where ALL {request.principal.type='generativeaiapikey',
request.principal.id='<api-key-OCID>'}

Mit dieser Policy können Anforderungen, die mit dem angegebenen API-Schlüssel authentifiziert wurden, auf die Responses-API zugreifen, während der Zugriffsgeltungsbereich beibehalten und kontrolliert wird.

Für einen umfassenderen Sandbox-Zugriff können Sie die folgende Policy verwenden:

allow any-user to use generative-ai-family 
in compartment <QuickStart-compartment-name> 
where ALL {request.principal.type='generativeaiapikey', 
request.principal.id='<your-api-key-OCID>'}
2.2 (a) OCI Generative AI IAM-Authentifizierungsbibliothek installieren

Dieser Schritt ist nur erforderlich, wenn Sie die OCI Generative AI-API-Schlüsselauthentifizierung verwenden. Wenn Sie OCI Generative AI-API-Schlüssel verwenden, überspringen Sie diesen Schritt.

Installieren Sie das OCI Generative AI Authentication Helper-Package:

pip install oci-genai-auth

Das Package oci-genai-auth bietet Authentifizierungshilfen für die Integration der OCI-IAM-Authentifizierung in das OpenAI-SDK, einschließlich:

  • OciSessionAuth für lokale Entwicklung
  • OciUserPrincipalAuth für Benutzer, die OCI IAM-API-Signaturschlüssel verwenden
  • OciInstancePrincipalAuth
  • OciResourcePrincipalAuth für OCI-verwaltete Umgebungen

Wenn Sie die OCI IAM-Authentifizierung mit dem OpenAI-Client verwenden, legen Sie api_key="not-used" fest, und geben Sie eine authentifizierte http_client an.

Richten Sie für OciUserPrincipalAuth eine OCI-Konfigurationsdatei für die Identität ein, die Anforderungen signiert. Informationen hierzu finden Sie in den folgenden verwandten Themen:

3. openai installieren

Installieren Sie das offizielle OpenAI SDK.

Python

pip install openai
Hinweis

Um die Responses-API aufzurufen, verwenden Sie das OpenAI-SDK und nicht das OCI-SDK. Stellen Sie außerdem sicher, dass Sie die neueste Version des OpenAI-SDK verwenden.

Weitere Sprachen finden Sie auf der Seite OpenAI-Bibliotheken.

4. Endpunkt für OCI-Antwort-API suchen

Die OCI-Responses-API ist die primäre API zum Erstellen von Agent-Anwendungen für Unternehmens-KI in OCI Generative AI. Damit können Sie Modellanforderungen senden, Tools verwenden und den Konversationskontext über eine einzige API verwalten.

Mit der Antwort-API können Sie:

  • Einfache Inferenz- oder mehrstufige Agent-Workflows ausführen
  • Logik je nach Anwendungsfall aktivieren oder deaktivieren
  • Plattformverwaltete oder clientseitige Tools integrieren
  • Unterhaltungsstatus entweder im Service oder im Client verwalten

Die OCI Responses API verwendet eine OpenAI-kompatible Schnittstelle. Anforderungen verwenden dieselbe OpenAI-ähnliche Syntax, werden jedoch an OCI Generative AI gesendet und mit OCI-Zugangsdaten authentifiziert, wie OCI Generative AI-API-Schlüssel oder OCI IAM-basierte Authentifizierung.

Der empfohlene Client ist das OpenAI-SDK. Es unterstützt Sprachen wie Python, Java, TypeScript, Go und .NET. Sie können es auch mit Frameworks wie LangChain, LlamaIndex und OpenAI Agents SDK verwenden.

Verwenden Sie die folgende Basis-URL:

Basis-URL: https://inference.generativeai.${region}.oci.oraclecloud.com/openai/v1

Ersetzen Sie ${region} durch Ihre OCI-Region. Beispiel: us-chicago-1.

Verwenden Sie für die Responses-API den folgenden Endpunktpfad:

/responses
5. Unterstützte Modell-IDs und Regionen suchen

Mit der OCI Responses-API können Sie verschiedene Typen von Modellen aufrufen, die in von OCI Generative AI unterstützten Regionen verfügbar sind. Eine Liste der unterstützten Modelle und Regionen finden Sie unter Agent-Modelle und -Regionen.

Bedarfsgesteuerter Modus

On-Demand-Modelle werden von OCI gehostet und verwaltet und sind verfügbar, ohne dass dedizierte KI-Cluster erforderlich sind. Beispiele:

response = client.responses.create(
    model="xai.grok-4-1-fast-reasoning",
    input="Write a one-sentence explanation of what a database is."
)
response = client.responses.create(
    model="google.gemini-2.5-pro",
    input="Write a one-sentence explanation of what a database is."
)

Dedizierter Modus

Für Produktions-Workloads, die eine Isolation oder vorhersehbare Performance erfordern, können Sie Modelle in einem dedizierten KI-Cluster hosten. Verwenden Sie in diesem Fall die Clusterendpunkt-OCID als Modell-ID:

response = client.responses.create(
    model="<dedicated-ai-cluster-endpoint-ocid>",
    input="Write a one-sentence explanation of what a database is."
)

Stellen Sie sicher, dass Sie beim Senden der Anforderung dieselbe Region wie das Cluster auswählen.

Wählen Sie ein Modell in einer verfügbaren Region mit dem verfügbaren Modus, der am besten zu Ihren Anforderungen an Performance, Kosten und Kontrolle passt.

6. Erste Antwort erstellen

Die folgenden Beispiele zeigen, wie Sie die Responses-API mit Python aufrufen. Wenn die Anforderung eine Erklärung zurückgibt, funktioniert die OCI Responses API ordnungsgemäß.

Beispiel für einen API-Schlüssel
from openai import OpenAI

client = OpenAI(
    base_url="https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/openai/v1",  # change the region if needed
    api_key="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",  # replace with your Generative AI API key created in Step 2
    project="ocid1.generativeaiproject.oc1.us-chicago-1.xxxxxxxx"  # replace with your Generative AI project OCID created in Step 1
)

response = client.responses.create(
    model="xai.grok-4-1-fast-reasoning",
    input="Write a one-sentence explanation of what a database is."
)

print(response.output_text)
Beispiel für OciUserPrincipalAuth

Verwenden Sie diesen Ansatz, wenn Sie OCI IAM-API-Signaturschlüssel (nicht OCI Generative AI-API-Schlüssel) verwenden. Siehe Erforderliche Schlüssel und OCIDs.

from openai import OpenAI
from oci_openai import OciUserPrincipalAuth
import httpx

client = OpenAI(
    base_url="https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/openai/v1",
    api_key="not-used",
    project="ocid1.generativeaiproject.oc1.us-chicago-1.xxxxxxxx",
    http_client=httpx.Client(
        auth=OciUserPrincipalAuth(
            config_file="~/.oci/config",
            profile_name="DEFAULT",
        )
    )

response = client.responses.create(
    model="xai.grok-4-1-fast-reasoning",
    input="Write a one-sentence explanation of what a database is."
)

print(response.output_text)
Beispiel für OciSessionAuth

Verwenden Sie diesen Ansatz, wenn Sie Code lokal ausführen:

from openai import OpenAI
from oci_openai import OciSessionAuth
import httpx

client = OpenAI(
    base_url="https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/openai/v1",  # update region if needed
    api_key="not-used",
    project="ocid1.generativeaiproject.oc1.us-chicago-1.xxxxxxxx",  # project OCID created earlier
    http_client=httpx.Client(auth=OciSessionAuth(profile_name="DEFAULT"))  # update profile if needed
)

response = client.responses.create(
    model="xai.grok-4-1-fast-reasoning",
    input="Write a one-sentence explanation of what a database is."
)

print(response.output_text)
Beispiel für OciResourcePrincipalAuth

Verwenden Sie diesen Ansatz bei der Arbeit mit verwalteten Umgebungen wie OCI Functions oder OCI Container Engine for Kubernetes (OKE):

from openai import OpenAI
from oci_openai import OciResourcePrincipalAuth
import httpx

client = OpenAI(
    base_url="https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/openai/v1",  # update region if needed
    api_key="not-used",
    project="ocid1.generativeaiproject.oc1.us-chicago-1.xxxxxxxx",  # project OCID created earlier
    http_client=httpx.Client(auth=OciResourcePrincipalAuth()),
)

response = client.responses.create(
    model="xai.grok-4-1-fast-reasoning",
    input="Write a one-sentence explanation of what a database is."
)

print(response.output_text)

Weitere Funktionen

Debug-Logging aktivieren

Wenn beim Aufruf der API Probleme auftreten, kann die Aktivierung des Debug-Loggings bei der Fehlerbehebung hilfreich sein. In Debuglogs werden die Raw-HTTP-Anforderungen und -Antworten angezeigt, einschließlich der opc-request-id, die bei der Arbeit mit Oracle-Support nützlich ist.

Sie können diese Anforderungs-ID referenzieren, wenn Sie Probleme melden, um Probleme schneller zu identifizieren und zu diagnostizieren.

from openai import OpenAI
import logging

logger = logging.getLogger("openai")
logger.setLevel(logging.DEBUG)
logger.addHandler(logging.StreamHandler())

# Create and use the OpenAI client as usual
client = OpenAI(
    ...
)
Streamantworten

Die OCI Responses API unterstützt Streaming, bei dem Sie Modellausgaben inkrementell empfangen können, wenn die Token generiert werden.

Alle Ereignisse streamen

response_stream = client.responses.create(
    model="openai.gpt-oss-120b",
    input="Explain the difference between structured and unstructured data.",
    stream=True
)

for event in response_stream:
    print(event)

Nur Textausgabe streamen (Delta-Token)

response_stream = client.responses.create(
    model="openai.gpt-oss-120b",
    input="Explain the difference between structured and unstructured data.",
    stream=True
)

for event in response_stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)

Streaming ist besonders nützlich für interaktive Anwendungen, in denen Benutzer die Antworten lesen können, während sie generiert werden.

Begründung hinzufügen

Mit Argumentationssteuerelementen können Sie einstellen, wie viel Aufwand das Modell verwendet, bevor Sie eine Antwort erstellen. Dies ist nützlich, wenn Sie Geschwindigkeit, Tiefe oder eine Balance von beidem priorisieren möchten.

Tipp

Prüfen Sie die wichtigsten Features auf der Detailseite des Modells, um sicherzustellen, dass das Modell, das Sie aufrufen, eine Begründung enthält. Siehe Verfügbare Chatmodelle.

Grundlegender Aufwand

response = client.responses.create(
    model="openai.gpt-oss-120b",
    input="Solve 18 * (4 + 2).",
    reasoning={"effort": "medium"},
    store=False,
)

print(response.output_text)

Ergebnisübersicht

Wenn Sie einen Chatbot erstellen, kann das Aktivieren von Begründungsübersichten Benutzern helfen, besser zu verstehen, wie das Modell zu einem Ergebnis kam. Beim Streaming können Benutzer auch Argumentationstoken sehen, während das Modell denkt.

response = client.responses.create(
    model="openai.gpt-oss-120b",
    input="Solve 18 * (4 + 2).",
    reasoning={"summary": "auto"},
    store=False,
)

print(response.output_text)
Strukturierte Ausgaben abrufen

Verwenden Sie strukturierte Ausgaben, wenn das Modell Daten in einem vorhersehbaren Format anstelle von Freiformtext zurückgeben soll. Dies ist nützlich, um Felder aus unstrukturierten Eingaben zu extrahieren, Ergebnisse an andere Systeme zu übergeben oder bestimmte Werte in einer Benutzeroberfläche anzuzeigen. In der OCI Responses API definieren Sie ein Schema und parsen die Antwort darauf, wodurch die Ausgabe konsistenter und einfacher für Anwendungen zu verwenden ist. Strukturierte Ausgaben stimmen mit einem angegebenen Schema überein, während ein JSON-Modus nur gültige JSON garantiert.

Ein stark eingegebenes Objekt ist ein Objekt, dessen Felder und Datentypen im Voraus definiert werden. Beispiel: Wenn ein Schema angibt, dass customer_name eine Zeichenfolge sein muss und priority einer der folgenden Werte sein muss: "low", "medium" oder "high", folgt das geparste Ergebnis dieser Struktur. Dies erleichtert es dem Code, sicher und vorhersehbar mit der Antwort zu arbeiten. Die OCI Responses API unterstützt dies, indem Sie ein Schema definieren und die Modellausgabe in stark typisierte Objekte parsen können.

Dieser Ansatz ist nützlich, wenn er in nachgelagerte Systeme integriert, Konsistenz durchgesetzt oder bestimmte Felder aus der Eingabe in natürlicher Sprache extrahiert werden.

from pydantic import BaseModel
from typing import Literal

class SupportRequest(BaseModel):
    customer_name: str
    product: str
    issue_summary: str
    priority: Literal["low", "medium", "high"]
    requested_action: str

response = client.responses.parse(
    model="<supported-model-id>",
    input=[
        {"role": "system", "content": "Extract the support request into the schema."},
        {
            "role": "user",
            "content": (
                "Sarah Johnson from Example Company says the mobile inventory app "
                "crashes whenever she scans more than 20 items in one session. "
                "This is delaying warehouse processing, and she wants a fix as soon as possible."
            ),
        },
    ],
    text_format=SupportRequest,
)

support_request = response.output_parsed
print(support_request)

Beispielausgabe:

SupportRequest(
customer_name='Sarah Johnson', 
product='mobile inventory app', 
issue_summary='App crashes whenever she scans more than 20 items in one session.', 
priority='high', 
requested_action='Provide a fix as soon as possible'
)
Multimodale Eingaben senden

Die OCI Responses API unterstützt Modelle, die multimodale Eingaben akzeptieren. Sie können Text mit Bildern, Dateien und Argumentationssteuerelementen kombinieren, um umfangreichere Workflows wie Dokumentanalyse, Bildverständnis und bewusstere Modellantworten zu unterstützen.

Tipp

Prüfen Sie die wichtigsten Features auf der Detailseite des Modells, um sicherzustellen, dass das Modell, das Sie aufrufen, multimodale Eingaben akzeptiert. Siehe Verfügbare Chatmodelle.

Bildeingabe als Base64-codierte Daten-URL

import base64

def encode_image(image_path):
    with open(image_path, "rb") as image_file:
        return base64.b64encode(image_file.read()).decode("utf-8")

base64_image = encode_image("/path/to/image.png")

response = client.responses.create(
    model="google.gemini-2.5-pro",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "Describe the main objects in this image."},
                {
                    "type": "input_image",
                    "image_url": f"data:image/jpeg;base64,{base64_image}",
                    "detail": "high",
                },
            ],
        }
    ],
)

print(response.output_text)

Bildeingabe als Internet-URL

response = client.responses.create(
    model="google.gemini-2.5-pro",
    store=False,
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "Describe the scene shown in this image."},
                {
                    "type": "input_image",
                    "image_url": "https://example.photos/id/123",
                },
            ],
        }
    ],
)

print(response.output_text)

Ersetzen Sie image_url durch eine gültige Bild-URL.

Dateieingabe als Dateikennung

Wichtig

Die Eingabefunktion für die Datei-ID wird nur mit Google Gemini-Modellen unterstützt. Für jede Anforderung muss die kombinierte Größe aller hochgeladenen PDF-Dateien unter 50 MB liegen, und Sie können maximal 10 Datei-IDs in der Anforderung angeben. Siehe Unterstützte Zwillinge-Modelle.
file = client.files.create(
    file=open("<path-to-file>", "rb"),
    purpose="user_data"
)

response = client.responses.create(
    model="google.gemini-2.5-pro",
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_file",
                    "file_id": file.id,
                },
                {
                    "type": "input_text",
                    "text": "Summarize this document.",
                },
            ]
        }
    ]
)

print(response.output_text)

Dateieingabe als URL für Internetzugriff

response = client.responses.create(
    model="google.gemini-2.5-flash",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "Summarize this file."},
                {
                    "type": "input_file",
                    "file_url": "https://www.example.com/letters/example-letter.pdf",
                },
            ],
        }
    ],
)

print(response.output_text)

Werkzeuge zur Antwort-API hinzufügen

Code-Interpreter

Mit Code Interpreter kann das Modell Python-Code in einem sicheren, isolierten Container schreiben und ausführen. Dieses Tool ist nützlich für Berechnungen, Datenanalysen, Dateiverarbeitung und andere rechenintensive Aufgaben.

Hinweis

Das OCI-Code-Interpreter-Tool verwendet dasselbe Format wie das OpenAI-Code-Interpreter-Tool, das mit der Responses-API mit dem OCI OpenAI-kompatiblen Endpunkt verwendet wird. Syntax- und Anforderungsdetails finden Sie im Thema "Code Interpreter" in der OpenAI-Dokumentation.
Tipp

Referenzieren Sie in Eingabeaufforderungen den Code-Interpreter als python-Tool. Beispiel: Use the python tool to solve the problem.

Da Code in einer isolierten Umgebung ohne externen Netzwerkzugriff ausgeführt wird, ist Code Interpreter eine gute Option, wenn der Workflow eine Berechnung oder Dateiverarbeitung in einer kontrollierten Einstellung erfordert.

Code-Intepreter verwenden

Wenn Sie dies zum ersten Mal verwenden, betrachten Sie Code Interpreter als temporären Python-Workspace für das Modell.

Sie können sie für folgende Aufgaben verwenden:

  • Lösung von mathematischen Problemen
  • Hochgeladene Dateien werden analysiert
  • Daten bereinigen oder transformieren
  • Diagramme oder Tabellen erstellen
  • Ausgabedateien wie Logs oder verarbeitete Datasets generieren

Ausführungsumgebung

Die Python-Umgebung umfasst mehr als 420 vorinstallierte Bibliotheken, einschließlich Pandas, Matplotlib und SciPy, so dass viele gängige Aufgaben ohne zusätzliches Setup funktionieren.

Der Code wird in einem Sandbox-Container ausgeführt. Dieser Container ist die Arbeitsumgebung, in der Python ausgeführt wird und in der hochgeladene Dateien, generierte Dateien und temporäre Arbeitsdaten während der Session gespeichert werden.

Grenzwerte für Containerspeicher

Codeinterpreter-Container verwenden einen Shared Memory-Pool von 64 GB pro Mandant.

Folgende Containergrößen werden unterstützt:

  • 1 GB
  • 4 GB
  • 16 GB
  • 64 GB

Dieses gemeinsame Limit kann auf mehrere Container aufgeteilt werden. Sie kann beispielsweise Folgendes unterstützen:

  • Vierundsechzig 1 GB Container
  • Sechzehn 4 GB Container
  • Vier 16 GB Container
  • Ein 64 GB Container

Wenn Sie mehr Kapazität benötigen, können Sie eine Serviceanfrage einreichen.

Containerablauf

Ein Container läuft nach 20 Minuten Inaktivität ab.

Dies ist wichtig, wenn Sie mehrstufige Abläufe erstellen:

  • Ein abgelaufener Container kann nicht wiederverwendet werden
  • Sie müssen einen neuen Container erstellen
  • Dateien müssen bei Bedarf erneut hochgeladen werden
  • In-Memory-Status, wie Python-Variablen und Python-Objekte, geht verloren

Daher ist es am besten, Container als temporäre Arbeitsumgebungen zu behandeln.

Beispiel

Um Codeinterpreter zu verwenden, fügen Sie in der Eigenschaft tools eine Tooldefinition mit "type": "code_interpreter" hinzu.

response = client.responses.create(
    model="xai.grok-4-1-fast-reasoning",
    tools=[
        {
            "type": "code_interpreter",
            "container": {"type": "auto"}
        }
    ],
    instructions="Use the python tool to solve the problem and explain the result.",
    input="Find the value of (18 / 3) + 7 * 2."
)

print(response.output_text)

In diesem Beispiel ist das python-Tool Code Interpreter.

Container für Code-Interpreter

Das Codeinterpreter-Tool erfordert ein Containerobjekt. Der Container ist die isolierte Umgebung, in der das Modell Python-Code ausführt.

Ein Container kann Folgendes enthalten:

  • Hochgeladene Dateien
  • Vom Modell erstellte Dateien
  • Temporäre Arbeitsdaten während der Ausführung

Wenn Sie Code Interpreter verwenden, können Sie einen von zwei Containermodi verwenden:

  • auto: OCI Generative AI stellt einen Container im aktuellen Kontext bereit oder verwendet ihn wieder.
  • Container-OCID: Sie erstellen den Container selbst, definieren die Speichergröße und geben die OCID an.

Bei beiden Optionen werden die Container in OCI Generative AI erstellt und verwaltet. Der Code, der in diesen Containern ausgeführt wird, wird auch im OCI Generative AI-Mandanten ausgeführt.

Hinweis

Das OCI-Code-Interpreter-Tool verwendet dasselbe Format wie das OpenAI-Code-Interpreter-Tool, das mit der Responses-API mit dem OCI OpenAI-kompatiblen Endpunkt verwendet wird. Syntax- und Anforderungsdetails finden Sie unter Containers for Code Intepreters und OpenAI Containers API documentation.

Automatischer Modus

Im automatischen Modus stellt der Service den Container bereit oder verwendet ihn wieder. Dies ist die einfachste Option und ein guter Ausgangspunkt für die meisten Benutzer.

Verwenden Sie den automatischen Modus, wenn:

  • Sie möchten, dass OCI Generative AI den Container verwaltet
  • Sie brauchen keine direkte Kontrolle über die Umwelt
  • Sie wollen ein einfacheres Setup

Sie können optional memory_limit angeben. Wenn Sie es nicht angeben, ist der Standardwert 1 GB.

response = client.responses.create(
    model="xai.grok-code-fast-1",
    tools=[{
        "type": "code_interpreter",
        "container": {
            "type": "auto",
            "memory_limit": "1g"
        }
    }],
    input="Use the python tool to calculate the average of 12, 18, 24, and 30."
)

Expliziter Modus

Im expliziten Modus erstellen Sie zuerst den Container und legen die Größe fest. Anschließend übergeben Sie die Container-ID in der Anforderung.

Verwenden Sie den expliziten Modus, wenn Sie mehr Kontrolle über Containereinstellungen haben möchten, z. B. Speichergröße, oder wenn Sie eine dedizierte Session beibehalten möchten.

container = client.containers.create(name="test-container", memory_limit="4g")

response = client.responses.create(
    model="xai.grok-code-fast-1",
    tools=[{
        "type": "code_interpreter",
        "container": container.id
    }],
    tool_choice="required",
    input="Use the python tool to calculate the average of 12, 18, 24, and 30."
)

print(response.output_text)

Dateien in Code-Interpreter

Code Interpreter unterstützt die dynamische Dateiinteraktion während der Lebensdauer des Containers. Das Modell kann von Ihnen bereitgestellte Dateien lesen und auch neue Dateien erstellen.

Dies ist nützlich für Workflows wie:

  • CSV oder PDF lesen
  • Diagramme generieren
  • Verarbeitete Ausgabe wird gespeichert
  • Protokolle oder Berichte erstellen

API-Referenz: OpenAI Container Files API-Dokumentation und Container Files API.

Dateipersistenz

Dateien, die vom python-Tool erstellt oder aktualisiert wurden, bleiben während der Codeausführung in demselben Container bestehen, solange der Container nicht abgelaufen ist.

Das bedeutet, dass das Modell auf früheren Arbeiten in derselben Session aufbauen kann. Sie kann beispielsweise:

  • Datei lesen
  • Analysieren
  • Diagramm speichern
  • Dieses Diagramm später im selben Container verwenden

Wenn der Container abläuft, ist dieser Status nicht mehr verfügbar.

Dateien hochladen und verwalten

Sie können Containerdateien über die Container Files-APIs verwalten.

Zu den allgemeinen Vorgängen gehören:

  • Containerdatei erstellen: Fügen Sie dem Container eine Datei hinzu, entweder durch Multipart-Upload oder durch Referenzieren einer vorhandenen /v1/files-ID
  • Containerdateien auflisten: Zeigt Dateien im Container an
  • Containerdatei löschen: Entfernen einer Datei
  • Containerdateiinhalt abrufen: Datei aus dem Container herunterladen

Auf diese Weise können Sie den Container als temporären Workspace für die Ausführung von modellgesteuertem Code verwenden.

Ausgabedateien und Zitate

Wenn das Modell Dateien erstellt, werden diese Dateien im Container gespeichert und können als Annotationen in der Antwort zurückgegeben werden.

Diese Annotationen können Folgendes umfassen:

  • container_id
  • file_id
  • filename

Sie können diese Werte verwenden, um den generierten Dateiinhalt abzurufen.

Die Antwort kann ein container_file_citation-Objekt enthalten, das die generierte Datei identifiziert. Mit dem Vorgang Containerdateiinhalt abrufen können Sie die Datei herunterladen.

Die OCI-Responses-API unterstützt OpenAI-kompatible Endpunkte für Features wie Antworten, Dateien, Container und Containerdateien. Sie können die zugehörige OpenAI-Dokumentation als Referenz für Anforderungsstruktur, Antwortformate und allgemeine Workflows verwenden. Wenn Sie diese APIs mit OCI verwenden, senden Sie Anforderungen an die OCI Generative AI-Inferenzendpunkte, verwenden Sie die OCI-Authentifizierung, und beachten Sie, dass die Ressourcen und die Ausführung in OCI Generative AI verbleiben, nicht in einem OpenAI-Mandanten.

Hinweis

Die OCI-Dateien-API verwendet dasselbe Format wie die OpenAI-Dateien-API mit dem OCI OpenAI-kompatiblen Endpunkt. Syntax- und Anforderungsdetails finden Sie in der Dokumentation zur OpenAI-Dateien-API.
Hinweis

Der OCI-Code-Interpreter, der als Tool für die Ressponses-API verwendet wird, verwendet dasselbe Format wie der OpenAI-Code-Interpreter mit dem OCI OpenAI-kompatiblen Endpunkt. Syntax und Anforderung finden Sie in den folgenden Referenzen:

Funktionsaufrufe

Verwenden Sie den Funktionsaufruf, damit das Modell Daten oder Aktionen aus Ihrer Anwendung während eines API-Workflow für Antworten anfordert. Dies ist nützlich, wenn das Modell Informationen oder Vorgänge benötigt, die im Prompt selbst nicht verfügbar sind, wie z.B. Kalenderdaten, interner Anwendungsstatus oder das Ergebnis eines benutzerdefinierten Vorgangs.

Mit diesem Muster führt das Modell die Funktion nicht direkt aus. Stattdessen werden der Funktionsname und die Argumente zurückgegeben, die Anwendung führt die Funktion aus, und dann sendet die Anwendung die Funktionsausgabe zurück, damit das Modell fortfahren und die benutzerorientierte Antwort erzeugen kann.

Was dies ermöglicht

Funktionsaufrufe sind nützlich, wenn Ihre Anwendung die Kontrolle über die Ausführung behalten muss und das Modell dennoch entscheiden kann, wann externe Informationen benötigt werden.

Beispiele für Anwendungsfälle:

  • Kalenderereignisse suchen
  • Anwendungsdaten werden abgerufen...
  • Interne oder externe API wird aufgerufen
  • Geschäftslogik oder Berechnungen ausführen

Innerhalb Ihrer Funktion können Sie einen externen Service, eine Datenbank, eine Ihrer eigenen Library-APIs, eine CLI oder einen lokalen MCP-Server aufrufen.

Dieser Ansatz bietet Ihnen Flexibilität, während Sie den Ausführungspfad innerhalb der Anwendung beibehalten.

Ausführungsfluss

Eine typische Funktion, die Interaktion aufruft, funktioniert wie folgt:

  1. Der Client sendet eine Anforderung, die eine oder mehrere Funktionstooldefinitionen enthält.
  2. Das Modell entscheidet, ob eines dieser Werkzeuge benötigt wird.
  3. Wenn ein Tool benötigt wird, gibt das Modell den Funktionsnamen und die Argumente zurück.
  4. Die Anwendung führt die Funktion aus und bereitet das Ergebnis vor.
  5. Die Anwendung sendet dieses Ergebnis in einer Folgeanforderung zurück.
  6. Das Modell verwendet dieses Ergebnis, um die Antwort abzuschließen.

Optionen für die Zustandsbehandlung

Es gibt zwei allgemeine Möglichkeiten, den Status über diese Anforderungen hinweg zu verwalten:

  • Serviceverwalteter Status

    Empfohlen für die meisten Anwendungsfälle. Die Nachfassanforderung enthält previous_response_id, und der Service verfolgt den früheren Austausch.

  • Client-verwalteter Status

    Die Anwendung behält die vollständige Interaktionshistorie bei und sendet den akkumulierten Kontext mit jeder Anforderung.

Tipp

Halten Sie Werkzeugdefinitionen präzise. Klare Namen, gut geschriebene Beschreibungen und gut definierte Parameter helfen dem Modell, das richtige Tool auszuwählen und verwendbare Argumente zu generieren.

Funktionstools definieren

Um ein Funktionstool zu definieren, fügen Sie einen Eintrag in der Eigenschaft tools mit "type": "function" hinzu.

Das folgende Beispiel definiert ein Tool, das Kalenderereignisse für ein bestimmtes Datum abruft:

tools = [
    {
        "type": "function",
        "name": "get_calendar_events",
        "description": "Return calendar events scheduled for a specific date.",
        "parameters": {
            "type": "object",
            "properties": {
                "date": {
                    "type": "string",
                    "description": "Date to query, for example 2026-04-02"
                }
            },
            "required": ["date"],
        },
    },
]

Nehmen Sie dieses tools-Array in die client.responses.create()-Anforderung auf.

Beispiel: Service-verwalteter Status

In diesem Muster lässt die erste Anforderung das Modell entscheiden, ob das Tool benötigt wird. Die zweite Anforderung sendet das Toolergebnis zurück und referenziert die frühere Antwort.

import json

tools = [
    {
        "type": "function",
        "name": "get_calendar_events",
        "description": "Return calendar events scheduled for a specific date.",
        "parameters": {
            "type": "object",
            "properties": {
                "date": {
                    "type": "string",
                    "description": "Date to query, for example 2026-04-02"
                }
            },
            "required": ["date"],
        },
    },
]

def get_calendar_events(date):
    # Replace this with actual calendar logic or an API call
    return [
        {"time": "09:00", "title": "Team standup"},
        {"time": "13:00", "title": "Design review"},
        {"time": "16:00", "title": "Project check-in"},
    ]

# Initial request
response = client.responses.create(
    model="openai.gpt-oss-120b",
    tools=tools,
    input="Show the calendar events for 2026-04-02.",
)

# Execute the requested function
tool_outputs = []
for item in response.output:
    if item.type == "function_call" and item.name == "get_calendar_events":
        args = json.loads(item.arguments)
        events = get_calendar_events(**args)
        tool_outputs.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": json.dumps({"events": events}),
        })

# Follow-up request
final = client.responses.create(
    model="openai.gpt-oss-120b",
    instructions="Summarize the schedule clearly for the user.",
    tools=tools,
    input=tool_outputs,
    previous_response_id=response.id,
)

print(final.output_text)

Beispiel: Client-verwalteter Status

In diesem Muster behält die Anwendung den vollständigen Austausch bei und leitet ihn mit der Nachfassanforderung erneut weiter.

import json

tools = [
    {
        "type": "function",
        "name": "get_calendar_events",
        "description": "Return calendar events scheduled for a specific date.",
        "parameters": {
            "type": "object",
            "properties": {
                "date": {
                    "type": "string",
                    "description": "Date to query, for example 2026-04-02"
                }
            },
            "required": ["date"],
        },
    },
]

def get_calendar_events(date):
    # Replace this with actual calendar logic or an API call
    return [
        {"time": "09:00", "title": "Team standup"},
        {"time": "13:00", "title": "Design review"},
        {"time": "16:00", "title": "Project check-in"},
    ]

conversation = [
    {"role": "user", "content": "Show the calendar events for 2026-04-02."}
]

response = client.responses.create(
    model="openai.gpt-oss-120b",
    tools=tools,
    input=conversation,
)

conversation += response.output

for item in response.output:
    if item.type == "function_call" and item.name == "get_calendar_events":
        args = json.loads(item.arguments)
        events = get_calendar_events(**args)
        conversation.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": json.dumps({"events": events}),
        })

final = client.responses.create(
    model="openai.gpt-oss-120b",
    instructions="Summarize the schedule clearly for the user.",
    tools=tools,
    input=conversation,
)

print(final.output_text)

Funktionsaufrufe sind eine starke Option, wenn die Anwendung für die Ausführung, Zugriffskontrolle und Integrationslogik verantwortlich bleiben muss, während das Modell weiterhin die benötigten Informationen anfordern kann.

MCP - Aufruf

MCP-(Model Context Protocol-)Tools sind ausführbare Funktionen oder Funktionen, mit denen KI-Modelle mit externen Systemen interagieren können. Verwenden Sie MCP-Aufrufe in OCI Generative AI, damit ein Modell auf ausführbare Tools zugreifen kann, die von einem Remote-MCP-Server während einer Responses-API-Anforderung bereitgestellt werden. Diese Tools können Zugriff auf externe Systeme wie API, Datenbanken, Dateisysteme oder Anwendungsendpunkte ermöglichen. OCI Generative AI kommuniziert im Rahmen des Anforderungsworkflows direkt mit Remote-MCP-Servern.

Wann MCP-Aufrufe verwendet werden

Verwenden Sie MCP-Aufrufe, wenn das Modell Zugriff auf Tools benötigt, die auf einem Remote-MCP-Server gehostet werden. Dieser Ansatz ist nützlich, wenn Sie möchten:

  • Die Enterprise AI Agent-Plattform zur direkten Kommunikation mit dem MCP-Server
  • Weniger clientseitige Orchestrierungsschritte
  • Geringere Latenz als ein vom Client ausgeführtes Toolmuster
  • Zugriff auf Tools, die über einen Remote-MCP-Server verfügbar gemacht werden

Wichtige Features

MCP Calling bietet folgende Vorteile:

  • Direkte Plattform-zu-Server-Kommunikation: Im Gegensatz zu Standardfunktionsaufrufen, bei denen die Kontrolle an die Clientanwendung zurückgegeben wird, ermöglicht MCP Calling die direkte Kommunikation von OCI Generative AI mit dem Remote-MCP-Server.
  • Niedrigere Latenz: Da für die Anforderung keine zusätzliche Client-Roundtrip erforderlich ist, kann MCP Calling den Orchestrierungsaufwand reduzieren.

  • Transportunterstützung: Unterstützt Streamable HTTP (SSE veraltet und nicht unterstützt).

MCP-Tool festlegen

Um ein MCP-Tool zu definieren, fügen Sie einen Eintrag in der Eigenschaft tools mit "type": "mcp" hinzu.

response_stream = client.responses.create(
    model="openai.gpt-5.4",
    tools=[
        {
            "type": "mcp",
            "server_label": "dmcp",
            "server_description": "A Dungeons and Dragons MCP server to assist with dice rolling.",
            "server_url": "https://mcp.deepwiki.com/mcp",
            "require_approval": "never",
        },
    ],
    input="Roll 2d4+1",
    stream=True,
)

for event in response_stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)

In diesem Beispiel wird die Antwort gestreamt und der generierte Text ausgegeben.

Von einem MCP-Server bereitgestellte Tools einschränken

Ein Remote-MCP-Server kann viele Tools bereitstellen, was die Kosten und die Latenz erhöhen kann. Wenn die Anwendung nur eine Teilmenge dieser Tools benötigt, verwenden Sie allowed_tools, um das Set einzuschränken.

response_stream = client.responses.create(
    model="openai.gpt-oss-120b",
    tools=[
        {
            "type": "mcp",
            "server_label": "dmcp",
            "server_description": "A Dungeons and Dragons MCP server to assist with dice rolling.",
            "server_url": "https://mcp.deepwiki.com/mcp",
            "require_approval": "never",
            "allowed_tools": ["roll"],
        },
    ],
    input="Roll 2d4+1",
    stream=True,
    store=False,
)

Authentifizierung für den MCP-Server bereitstellen

Wenn der Remote-MCP-Server eine Authentifizierung erfordert, übergeben Sie das Zugriffstoken im Feld authorization.

response_stream = client.responses.create(
    model="xai.grok-4-1-fast-reasoning",
    tools=[
        {
            "type": "mcp",
            "server_label": "calendar",
            "server_url": "https://calendar.example.com/mcp",
            "authorization": "$CALENDAR_OAUTH_ACCESS_TOKEN"
        },
    ],
    input="List my meetings for 2026-02-02.",
    stream=True
)

Übergeben Sie nur den Raw-Tokenwert. Nehmen Sie das Präfix Bearer nicht auf.

OCI sendet das Token im API-Anforderungsbody über TLS. OCI decodiert, prüft, speichert oder protokolliert das Token nicht. Es wird empfohlen, TLS-verschlüsselte MCP-Serverendpunkte zu verwenden.

NL2SQL-Tool

SQL-Suche mit NL2SQL

Verwenden Sie SQL Search (NL2SQL), um Anforderungen in natürlicher Sprache in validiertes SQL für Unternehmensdaten in OCI Generative AI zu konvertieren.

NL2SQL unterstützt Enterprise AI Agents bei der Arbeit mit föderierten Unternehmensdaten, ohne die zugrunde liegenden Daten zu verschieben oder zu duplizieren. Es verwendet eine semantische Anreicherungsebene, um Geschäftsbegriffe Datenbanktabellen, Spalten und Joins zuzuordnen, und generiert dann SQL aus der Eingabe in natürlicher Sprache.

NL2SQL generiert nur SQL. Die Abfrage selbst wird nicht ausgeführt. Die Abfrageausführung wird separat über den DBTools MCP-Server abgewickelt, der die Abfrage für die Quelldatenbank autorisiert und ausführt, indem die Identity des Endbenutzers und die entsprechenden Guardrails verwendet werden.

Voraussetzungen

Bevor Sie NL2SQL verwenden können, benötigen Sie:

  • Eine Quelldatenbank, wie Oracle Autonomous Database
  • Zwei DBTools-Verbindungen:
    • Anreicherungsverbindung
    • Abfrageverbindung
  • IAM-Berechtigungen für semantische Speicher, NL2SQL, Datenbanktools und Secrets
  • OCI-IAM-Authentifizierung für die OCI-Service-APIs konfiguriert, die in diesem Schnellstart verwendet werden
1. Datenbank- und DBTools-Verbindungen erstellen

Bevor Sie einen semantischen Speicher erstellen, erstellen Sie die Quelldatenbank und die erforderlichen DBTools-Verbindungen.

Sie benötigen die folgenden Verbindungen:

Anreicherungsverbindung

Die Anreicherungsverbindung ist eine Datenbankverbindung mit höheren Berechtigungen, die während der Anreicherung verwendet wird. Sie benötigen Berechtigungen, um:

  • Abfragen ausführen
  • DDL-Vorgänge ausführen
  • Auf Beispielwerte aus der Datenbank zugreifen

OCI Generative AI verwendet diese Verbindung, um Schemadetails zu lesen und die für die SQL-Generierung erforderlichen Metadaten zu erstellen.

Abfrageverbindung

Die Abfrageverbindung ist eine Datenbankverbindung mit niedrigeren Berechtigungen, die zum Ausführen von Abfragen im Namen des abfragenden Benutzers verwendet wird.

Diese Trennung trägt dazu bei, dass die Verantwortlichkeiten für die Generierung und Ausführung unterschiedlich bleiben, und unterstützt eine sicherere Zugriffskontrolle.

Verwandte Themen

2. IAM-Berechtigungen für semantische Speicher und NL2SQL einrichten

Bevor Sie einen semantischen Speicher erstellen, richten Sie die erforderlichen IAM-Policys ein.

Für semantische Filialadministratoren

Wenn Sie Zugriff auf den ausgeführten QuickStart-Schritt Zugriff auf OCI Generative AI-Ressourcen erteilen erteilt haben, können Sie diesen Schritt für die Administratoren überspringen. Sie haben bereits die Berechtigung, semantische Speicher zu verwalten.

Semantische Speicheradministratoren sind Administratoren, die die semantische Speicherressource von OCI Generative AI und ihre NL2SQL-bezogenen Vorgänge erstellen, aktualisieren, löschen und verwalten.

Bitten Sie einen Administrator, eine IAM-Gruppe für die Administratoren zu erstellen. In diesem Thema wird die Admin-Gruppe wie folgt dargestellt:

  • <semantic-store-admin>
allow group <semantic-store-admin> 
to manage generative-ai-semantic-store 
in compartment <QuickStart-compartment-name>
allow group <semantic-store-admin> 
to manage generative-ai-nl2sql 
in compartment <QuickStart-compartment-name>
Admin-Aufgaben mit den vorhergehenden zwei Policys verfügbar

Eine <semantic-store-admin> kann:

  • semantischen Speicher erstellen
  • anzeigen und aktualisieren
  • löschen oder verschieben
  • Triggeranreicherung
  • Anreicherungsergebnisse prüfen
  • SQL aus natürlicher Sprache für Validierung/Tests generieren
  • NL2SQL-Vorgänge verwalten, die mit dem Speicher verknüpft sind

Für semantische OCI Generative AI-Speicher

  • Erstellen Sie eine dynamische Gruppe für semantische Speicher, die im Mandanten oder in einem angegebenen Compartment erstellt werden.
  • Erteilen Sie der dynamischen Gruppe folgende Berechtigungen:
    • Auf Datenbanktools-Verbindungen zugreifen
    • Datenbankmetadaten lesen
    • Autonomous Database-Metadaten lesen
    • Auf generative KI-Inferenz zugreifen
    • Von Datenbanktoolverbindungen verwendete Secrets lesen
  1. Erstellen Sie eine dynamische Gruppe für asemantische Speicher im Mandanten mit der folgenden Abgleichsregel:
    all {resource.type='generativeaisemanticstore'}
  2. Um die semantischen Speicher auf ein bestimmtes Compartment einzuschränken, aktualisieren Sie die vorherige Bedingung in:
    all {resource.type='generativeaisemanticstore',
     resource.compartment.id='<QuickStart-compartment-name>'}
  3. Policy erstellen, um der dynamischen Gruppe die Berechtigung für den Zugriff auf Datenbanktoolverbindungen in einem angegebenen Compartment zu erteilen.
    allow dynamic-group <dynamic-group-name> 
    to use database-tools-family in compartment <QuickStart-compartment-name>'}
  4. Fügen Sie eine Policy hinzu, um der dynamischen Gruppe die Berechtigung zum Lesen von Secrets zu erteilen, die von Datenbanktoolverbindungen verwendet werden.
    allow dynamic-group <dynamic-group-name> 
    to read secret-family in compartment <QuickStart-compartment-name>
  5. Fügen Sie eine Policy hinzu, um der dynamischen Gruppe die Berechtigung zum Lesen von Oracle Database-Metadaten für Datenbanktoolverbindungen zu erteilen.
    allow dynamic-group <dynamic-group-name> 
    to read database-family in compartment <QuickStart-compartment-name>
  6. Fügen Sie eine Policy hinzu, um der dynamischen Gruppe die Berechtigung zum Lesen von Autonomous Database-Metadaten für Datenbanktoolverbindungen und Anreicherungsjobs zu erteilen.
    allow dynamic-group <dynamic-group-name> 
    to read autonomous-database-family in compartment <QuickStart-compartment-name>
  7. Fügen Sie eine Policy hinzu, um der dynamischen Gruppe die Berechtigung zum Zugriff auf die OCI Generative AI-Ressourcen für Inferenz zu erteilen.
    allow dynamic-group <dynamic-group-name> 
    to use generative-ai-family in compartment <QuickStart-compartment-name>
Was die beiden vorhergehenden Richtlinien bieten

Die Ressource generativeaisemanticstore kann:

  • LLM-Inferenz über generative KI aufrufen
  • Datenbanktoolverbindungen für Anreicherung und Abfrage verwenden
  • Von Datenbanktools gesicherte Verbindungen erforderliche Secrets lesen
  • Oracle Database- und Autonomous Database-Metadaten lesen

Für semantische Filialbenutzer

Semantic Store-Benutzer sind Endbenutzer, die auf einen vorhandenen semantischen Speicher zugreifen und NL2SQL-Funktionen verwenden können, die Ressource jedoch nicht verwalten müssen.

Bitten Sie einen Administrator, eine IAM-Gruppe für die Benutzer zu erstellen. In diesem Thema wird die Benutzergruppe wie folgt dargestellt:

  • <semantic-store-users>
allow group <semantic-store-users> 
to read generative-ai-semantic-store 
in compartment <QuickStart-compartment-name>
allow group <semantic-store-users> 
to manage generative-ai-nl2sql 
in compartment <QuickStart-compartment-name>
Mit den vorhergehenden zwei Policen verfügbare Benutzeraufgaben

Die <semantic-store-users> kann:

  • semantischen Speicher anzeigen
  • Mit NL2SQL verknüpfte Funktionen verwenden
  • Ausgaben prüfen und abfragen
  • Informationen zur Zugriffsanreicherung

Für Benutzerzugriff auf Datenbanktoolverbindungen

Erteilen Sie der Gruppe Zugriff auf die erforderlichen Datenbanktoolressourcen:

allow group <semantic-store-users>
to use database-tools-family in compartment <QuickStart-compartment-name>
where all {request.principal.type='generativeaisemanticstore'}
allow group <semantic-store-users>
to read database-family in compartment <QuickStart-compartment-name>
where all {request.principal.type='generativeaisemanticstore'}
allow group <semantic-store-users>
to read autonomous-database-family in compartment <QuickStart-compartment-name>
where all {request.principal.type='generativeaisemanticstore'}
3. OCI-IAM-Authentifizierung einrichten

Dieser QuickStart verwendet die OCI IAM-Authentifizierung für die OCI-Service-API, mit der semantische Speicher erstellt, Anreicherungsjobs ausgeführt und SQL generiert werden.

Richten Sie die OCI-IAM-Authentifizierung für die Identität ein, die Anforderungen signiert. Die Beispiele in diesem Abschnitt verwenden das OCI-Python-SDK und BaseClient.

Sie können die Authentifizierung folgendermaßen durchführen:

  • OCI-Konfigurationsdatei und API-Signaturschlüssel
  • Ein Sicherheitstoken-Unterzeichner

In den folgenden Beispielen wird SecurityTokenSigner verwendet. Sie können jedoch auch einen Standard-OCI-Konfigurationsunterzeichner verwenden, wenn dieser besser zu Ihrer Umgebung passt.

Verwandte Themen

4. Semantischen Speicher erstellen

Um NL2SQL zu verwenden, erstellen Sie eine OCI-semantische Speicherressource.

Ein semantischer Speicher wird von einem Vektorspeicher mit strukturierten Daten gesichert und enthält die folgenden DBTools-Verbindungen:

  • Anreicherungsverbindung
  • Abfrageverbindung

Semantischen Speicher in der Konsole erstellen

  1. Öffnen Sie die Listenseite für Vektorspeicher.
  2. Geben Sie einen Namen und eine Beschreibung ein.
  3. Wählen Sie das Compartment <QuickStart-compartment-name> aus.
  4. Wählen Sie unter Datenquellentyp die Option Strukturierte Daten aus.
  5. Wählen Sie unter Synchronisierungs-Connector konfigurieren OCI-Datenbank-Tool als Verbindungstyp aus.
  6. Geben Sie die Anreicherungsverbindungs-ID ein, und wählen Sie Anreicherungsverbindung testen aus.
  7. Geben Sie die Verbindungs-ID abfragen ein, und wählen Sie Abfrageverbindung testen aus.
  8. Geben Sie unter Schemas die Namen des aufzunehmenden Datenbankschemas an.
  9. Wählen Sie unter Automatisierung aus, wann die Anreicherung ausgeführt wird:
    • Keine
    • Beim Erstellen
  10. Wählen Sie Erstellen aus.

Semantischen Speicher mit Python erstellen

Im folgenden Beispiel wird ein semantischer Speicher mit der OCI-Service-API erstellt und verwaltet:

import json
import oci
from oci.base_client import BaseClient
from oci.retry import DEFAULT_RETRY_STRATEGY

API_VERSION = "20231130"
HOST = "https://generativeai.us-ashburn-1.oci.oraclecloud.com"
BASE_PATH = f"/{API_VERSION}"

def get_signer_auth_security_token(profile="DEFAULT"):
    config = oci.config.from_file("~/.oci/config", profile)
    signer = oci.auth.signers.SecurityTokenSigner(config)
    return config, signer

def make_base_client(signer):
    return BaseClient(
        service_endpoint=HOST,
        signer=signer,
        retry_strategy=None,
    )

def create_semantic_store(client, body: dict):
    return client.call_api(
        resource_path=f"{BASE_PATH}/semanticStores",
        method="POST",
        header_params={"content-type": "application/json"},
        body=body,
    )

if __name__ == "__main__":
    config, signer = get_signer_auth_security_token(profile="DEFAULT")
    client = make_base_client(signer)

    create_body = {
        "displayName": "TestSemanticStore",
        "description": "Semantic store for the ADMIN schema",
        "freeformTags": {},
        "definedTags": {},
        "dataSource": {
            "queryingConnectionId": "ocid1.databasetoolsconnection.oc1.xxx",
            "enrichmentConnectionId": "ocid1.databasetoolsconnection.oc1.xxx",
            "connectionType": "DATABASE_TOOLS_CONNECTION",
        },
        "refreshSchedule": {"type": "ON_CREATE"},
        "compartmentId": "xxx",
        "schemas": {
            "connectionType": "DATABASE_TOOLS_CONNECTION",
            "schemas": [{"name": "ADMIN"}],
        },
    }

    create_resp = create_semantic_store(client, create_body)
    print("CREATE status:", create_resp.status)

    create_payload = create_resp.data
    if isinstance(create_payload, (bytes, str)):
        create_payload = json.loads(create_payload)

    print("CREATE response:", json.dumps(create_payload, indent=2))
5. Anreicherung manuell ausführen

Wenn Sie unter Automatisierung anstelle von Beim Erstellen die Option Keine ausgewählt haben, können Sie die Anreicherung ausführen, nachdem der semantische Speicher erstellt wurde. Führen Sie diesen Schritt aus, wenn Sie die Option Beim Erstellen übersprungen haben.

Der Anreicherungsprozess liest Schemametadaten, wie Tabellen und Spalten, aus der angemeldeten Datenbank. OCI Generative AI verwendet diese Metadaten, um die SQL zu generieren.

Um die Anreicherung manuell auszulösen, rufen Sie die API GenerateEnrichmentJob auf.

Sie können Anreicherungsjobs auch mit der folgenden API verwalten:

  • ListEnrichmentJobs
  • GetEnrichmentJob
  • CancelEnrichmentJob
6. OCI-Endpunkte für semantischen Speicher und GenerateSqlFromNl suchen

NL2SQL verwendet OCI-Service-APIs anstelle der OCI OpenAI-kompatiblen /openai/v1-Pfade.

Semantische Speicher-CRUD

Verwenden Sie die folgende Basis-URL für CRUD-Vorgänge im semantischen Speicher:

Basis-URL: https://generativeai.${region}.oci.oraclecloud.com

Verwenden Sie den folgenden Endpunktpfad:

/20231130/semanticStores

Authentifizierung:

  • Nur IAM-Session

API für Anreicherungsjob

Verwenden Sie die folgende Basis-URL für Anreicherungsjobs eines semantischen Speichers:

Basis-URL: https://inference.generativeai.${region}.oci.oraclecloud.com

Verwenden Sie den folgenden Endpunktpfad:

/20260325/semanticStores/{semanticStoreId}/

Authentifizierung:

  • Nur IAM-Session

SQL aus natürlicher Sprache generieren

Verwenden Sie die folgende Basis-URL für die SQL-Generierung:

Basis-URL: https://inference.generativeai.${region}.oci.oraclecloud.com

Verwenden Sie das folgende Endpunktmuster:

/20260325/semanticStores/{semanticStoreId}/actions/generateSqlFromNl

Authentifizierung:

  • Nur IAM-Session

Verfügbare semantische Speicher- und NL2SQL-APIs

Semantische Filialen

Semantische Filialen
  • CreateSemanticStore
  • ListSemanticStores
  • GetSemanticStore
  • UpdateSemanticStore
  • ChangeSemanticStoreCompartment
  • DeleteSemanticStore
Anreicherungsjobs
  • ListEnrichmentJobs
  • GetEnrichmentJob
  • GenerateEnrichmentJob
  • CancelEnrichmentJob
SQL generieren
GenerateSqlFromNl
Hinweis

Die Basis-URL unterscheidet sich für die API für semantische Speicher und Anreicherungsjobs.
7. Erste SQL-Anweisung generieren

Nachdem der semantische Speicher bereit ist und die Anreicherung abgeschlossen ist, rufen Sie die NL2SQL-API auf, um SQL aus natürlicher Sprache zu generieren.

import json
import oci
from oci.base_client import BaseClient

INFERENCE_BASE_URL = "https://inference.generativeai.<region>.oci.oraclecloud.com"
API_VERSION = "20260325"
SEMANTIC_STORE_ID = "ocid1.generativeaisemanticstore.oc1.xxx"

config = oci.config.from_file("~/.oci/config", "oc1")
signer = oci.auth.signers.SecurityTokenSigner(config)

client = BaseClient(
    service_endpoint=INFERENCE_BASE_URL,
    signer=signer,
    retry_strategy=None,
)

resource_path = (
    f"/{API_VERSION}/semanticStores/{SEMANTIC_STORE_ID}/actions/generateSqlFromNl"
)

body = {
    "displayName": "Generate SQL example",
    "description": "Generate SQL from natural language",
    "inputNaturalLanguageQuery": "Give me last week's order details."
}

resp = client.call_api(
    resource_path=resource_path,
    method="POST",
    header_params={"content-type": "application/json"},
    body=body,
)

print("HTTP status:", resp.status)
print("opc-request-id:", resp.headers.get("opc-request-id"))

data = resp.data
if isinstance(data, (bytes, str)):
    data = json.loads(data)

print(json.dumps(data, indent=2))

Beobachten

Informationen zum Tracing von Antwort-API-Aufrufen

Verwenden Sie die integrierten Antworttracedaten in der OCI-Antwort-API, um zu verstehen, wie eine Anforderung verarbeitet wurde. Um eine bessere Beobachtbarkeit zu gewährleisten, können Sie die OCI Responses API auch in externe Beobachtbarkeitsplattformen wie Langfuse integrieren.

Dieser QuickStart zeigt, wie Sie die von der Responses-API zurückgegebenen Ausführungsdetails prüfen und wie Sie Anforderungen mit Langfuse verfolgen.

Voraussetzungen

Bevor Sie beginnen, müssen Sie folgende Schritte ausführen:

  • Ein OCI Generative AI-Projekt
  • Für die OCI-Antwort-API konfigurierte Authentifizierung
  • Das OpenAI SDK installiert
  • Ein funktionierender OCI Responses API-Client

(Optional) Für die Integration mit Langfuse benötigen Sie ein Langfuse-Konto und Zugangsdaten.

1. Antwort-API-Ausgabe prüfen

Wenn Sie die OCI-Antworten-API aufrufen, enthält die Antwort ein Feld output. Dieses Feld enthält eine Reihe von Elementen, die beschreiben, was während der Anforderung geschehen ist.

Jedes Element stellt einen Schritt in der Ausführung dar und kann verschiedene Typen enthalten, wie:

  • message
  • file_search_call
  • mcp_call

Diese Ausgabeelemente bieten einen Einblick in die Verarbeitung der Anforderung. Sie können sie verwenden, um:

  • Modellverhalten debuggen und verstehen
  • Ausführungsschritte in einer Benutzeroberfläche anzeigen
  • Benutzerdefinierte Beobachtbarkeits- oder Loggingworkflows erstellen

Beispiel: Nachdem Sie eine Anforderung gesendet haben, können Sie das Feld output prüfen:

response = client.responses.create(
    model="openai.gpt-oss-120b",
    input="Explain the difference between structured and unstructured data."
)

for item in response.output:
    print(item.type)
2. Langfuse SDK installieren

Um tiefere Einblicke zu erhalten, wie Latenz-, Kosten- und Ausführungstraces, können Sie die OCI Responses API in eine Beobachtungsplattform integrieren.

Eine Option ist Langfuse, eine Open-Source-LLM-Engineering-Plattform, mit der Entwickler LLM-Anwendungen debuggen, überwachen und verbessern können. Langfuse bietet End-to-End-Beobachtbarkeit für das Tracing von Agent-Aktionen, unterstützt die Prompt-Versionierung und hilft bei der Auswertung von Modellausgaben. Es lässt sich in gängige Frameworks wie OpenAI, LangChain und LlamaIndex integrieren.

Installieren Sie das Langfuse SDK:

pip install langfuse
3. Umgebungsvariablen konfigurieren

Legen Sie die erforderlichen Langfuse- und OCI-Umgebungsvariablen fest:

LANGFUSE_SECRET_KEY="sk-lf-xxxxxxxxx"
LANGFUSE_PUBLIC_KEY="pk-lf-xxxxxxxxx"
LANGFUSE_BASE_URL="https://us.cloud.langfuse.com"

# OCI Generative AI credentials
OCI_GENAI_API_KEY="sk-xxxxxxxxx"
OCI_GENAI_PROJECT_ID="ocid1.generativeaiproject.oc1.xxx"
4. Instrumentieren des OpenAI-Clients

Importieren Sie den OpenAI-Client aus dem Langfuse-SDK. Der vorhandene Anforderungscode bleibt unverändert, Anforderungen werden jedoch automatisch verfolgt.

import os
from langfuse.openai import OpenAI  # Import from Langfuse

client = OpenAI(
    base_url="https://inference.generativeai.<region>.oci.oraclecloud.com/openai/v1",
    api_key=os.getenv("OCI_GENAI_API_KEY"),
    project=os.getenv("OCI_GENAI_PROJECT_ID"),
)
5. API-Anforderung für verfolgte Antworten senden

Nachdem Sie den Client instrumentiert haben, senden Sie wie gewohnt eine Responses API-Anforderung. Langfuse verfolgt die Anforderung automatisch.

Beispiel:

response = client.responses.create(
    model="openai.gpt-oss-120b",
    tools=[
        {
            "type": "mcp",
            "server_label": "dmcp",
            "server_url": "https://mcp.example.com/mcp",
            "require_approval": "never",
        },
    ],
    input="Explain why tracing and observability are important in distributed systems."
)

print(response.output_text)