Schnellstart
Führen Sie die folgenden Schritte aus, um mit der Erstellung von Enterprise AI Agents mit der OCI Responses API zu beginnen.
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
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>.
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.
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ü 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).
- 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.
- 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.
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.
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
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
Schlüsselnamen und Ablaufzeit
Verwenden Sie den Befehl
api-key createund 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.
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:
- Öffnen Sie die Listenseite "API-Schlüssel".
- Wählen Sie den erstellten API-Schlüssel.
- 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>'}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-authDas Package oci-genai-auth bietet Authentifizierungshilfen für die Integration der OCI-IAM-Authentifizierung in das OpenAI-SDK, einschließlich:
OciSessionAuthfür lokale EntwicklungOciUserPrincipalAuthfür Benutzer, die OCI IAM-API-Signaturschlüssel verwendenOciInstancePrincipalAuthOciResourcePrincipalAuthfü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:
- Thema: Anforderungssignaturen
- Tutorial: API-Authentifizierung für OCI einrichten
Installieren Sie das offizielle OpenAI SDK.
Python
pip install openaiUm 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.
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
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.
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äß.
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)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)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)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
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(
...
)
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.
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.
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)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'
)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.
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
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
Mit der Dateisuche können Sie relevante Inhalte aus Dateien abrufen, die während der Antwortgenerierung in einem Vektorspeicher gespeichert sind. Dies ist nützlich, wenn Antworten die von Ihnen bereitgestellten Dokumente widerspiegeln sollen, anstatt sich nur auf das integrierte Wissen des Modells zu verlassen.
Indem Sie Vektorspeicher erstellen und Dateien hinzufügen, aktivieren Sie die semantische und schlüsselwortbasierte Suche in Ihren Daten. Dies erweitert das integrierte Wissen des Modells um Ihre benutzerdefinierten Inhalte und hilft, präzisere, kontextbezogene Antworten zu erstellen.
Da die Dateisuche vom Service verarbeitet wird, muss Ihre Anwendung keine eigene Abrufpipeline implementieren.
Vektorspeicher vorbereiten
Bevor Sie die Dateisuche verwenden, erstellen Sie einen Vektorspeicher, und fügen Sie die Dateien hinzu, auf die das Modell verweisen soll. OCI Generative AI unterstützt die folgenden APIs für die Verwaltung von Dateien und Vektorspeichern:
| API-Set | Beschreibung |
|---|---|
| Dateien | Dateien hochladen und verwalten. |
| Vector Store-Dateien | Dateien verwalten, die an einen Vektorspeicher angehängt sind. |
| Vektorspeicherdatei-Batches | Fügen Sie mehrere Dateien in einem Vektorspeicher-Batch hinzu, und verwalten Sie sie. |
| Containerdateien | Verwalten Sie Dateien in einem Container. |
Beispiel
Um die Dateisuche in einer Anforderung zu verwenden, fügen Sie in der Eigenschaft tools eine Tooldefinition mit type: "file_search" hinzu, und geben Sie die Vektorspeicher-ID an.
response = client.responses.create(
model="openai.gpt-oss-120b",
input="Summarize the main ideas covered in the documents in this vector store.",
tools=[
{
"type": "file_search",
"vector_store_ids": ["<vector_store_id>"]
}
]
)
print(response)
In diesem Beispiel gilt:
- Das Modell kann den Vektorspeicherinhalt während der Antwortgenerierung verwenden.
- Der Dateiabruf wird von der Plattform verwaltet.
- Hybride Suchparameter werden mit dem File Search-Tool nicht unterstützt.
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.
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.
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.
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_idfile_idfilename
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.
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.
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:
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:
- Der Client sendet eine Anforderung, die eine oder mehrere Funktionstooldefinitionen enthält.
- Das Modell entscheidet, ob eines dieser Werkzeuge benötigt wird.
- Wenn ein Tool benötigt wird, gibt das Modell den Funktionsnamen und die Argumente zurück.
- Die Anwendung führt die Funktion aus und bereitet das Ergebnis vor.
- Die Anwendung sendet dieses Ergebnis in einer Folgeanforderung zurück.
- 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.
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-(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
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.
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
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
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
- Erstellen Sie eine dynamische Gruppe für asemantische Speicher im Mandanten mit der folgenden Abgleichsregel:
all {resource.type='generativeaisemanticstore'} - 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>'} - 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>'} - 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> - 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> - 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> - 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
generativeaisemanticstorekann:- 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'}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
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
- Öffnen Sie die Listenseite für Vektorspeicher.
- Geben Sie einen Namen und eine Beschreibung ein.
- Wählen Sie das Compartment <QuickStart-compartment-name> aus.
- Wählen Sie unter Datenquellentyp die Option Strukturierte Daten aus.
- Wählen Sie unter Synchronisierungs-Connector konfigurieren OCI-Datenbank-Tool als Verbindungstyp aus.
- Geben Sie die Anreicherungsverbindungs-ID ein, und wählen Sie Anreicherungsverbindung testen aus.
- Geben Sie die Verbindungs-ID abfragen ein, und wählen Sie Abfrageverbindung testen aus.
- Geben Sie unter Schemas die Namen des aufzunehmenden Datenbankschemas an.
-
Wählen Sie unter Automatisierung aus, wann die Anreicherung ausgeführt wird:
- Keine
- Beim Erstellen
- 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))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:
ListEnrichmentJobsGetEnrichmentJobCancelEnrichmentJob
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
-
CreateSemanticStoreListSemanticStoresGetSemanticStoreUpdateSemanticStoreChangeSemanticStoreCompartmentDeleteSemanticStore
- Anreicherungsjobs
-
ListEnrichmentJobsGetEnrichmentJobGenerateEnrichmentJobCancelEnrichmentJob
- SQL generieren
GenerateSqlFromNl
Die Basis-URL unterscheidet sich für die API für semantische Speicher und Anreicherungsjobs.
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
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.
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.
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:
messagefile_search_callmcp_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)
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
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"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"),
)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)