Démarrage rapide

Avant de créer un projet ou d'appeler l'API de réponses OCI, assurez-vous que les autorisations IAM requises sont en place.

L'API de réponses OCI prend en charge deux méthodes d'authentification. Vous pouvez utiliser l'une des deux options.

• Clés d'API du service d'intelligence artificielle générative pour OCI

  Authentifier et atteindre les modèles et les points d'extrémité avec des clés d'API propres au service d'IA générative compatibles avec OpenAI. Utilisez cette option pour les tests et le développement précoce.

• Authentification basée sur OCI IAM

  Authentifier et atteindre les modèles et les points d'extrémité à l'aide de demandes d'API signées. Nous recommandons cette option pour les charges de travail de production et les environnements gérés par OCI. Envisagez d'utiliser l'authentification IAM lorsque vous effectuez les opérations suivantes :

  • Exécuter des applications dans des services OCI tels que Functions ou Oracle Kubernetes Engine (OKE)
  • Vous voulez éviter les clés d'API de longue durée
  • Besoin d'un contrôle d'accès centralisé au moyen de l'OCI IAM

Installez le SDK OpenAI officiel.

Python

pip install openai

Pour les autres langues, consultez la page Bibliothèques OpenAI.

L'API des réponses OCI est l'API principale pour créer des applications agéntiques d'IA d'entreprise dans l'IA générative OCI. Il vous permet d'envoyer des demandes de modèle, d'utiliser des outils et de gérer le contexte de conversation au moyen d'une seule API.

Utilisez l'API Réponses pour :

• Exécuter des flux de travail simples d'inférence en une seule étape ou en plusieurs étapes pour les agents
• Activer ou désactiver le raisonnement, selon le cas d'utilisation
• Intégrer des outils gérés par la plate-forme ou côté client
• Gérer l'état de la conversation dans le service ou dans le client

L'API de réponses OCI utilise une interface compatible OpenAI. Les demandes utilisent la même syntaxe de style OpenAI, mais elles sont envoyées au service d'intelligence artificielle générative pour OCI et authentifiées au moyen des données d'identification OCI, telles que les clés d'API du service d'intelligence artificielle générative pour OCI ou l'authentification basée sur OCI IAM.

Le client recommandé est la trousse SDK OpenAI. Il prend en charge des langages tels que Python, Java, TypeScript, Go et .NET. Vous pouvez également l'utiliser avec des cadres tels que LangChain, LlamaIndex et OpenAI Agents SDK.

Utilisez l'URL de base suivante :

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

Remplacez ${region} par votre région OCI, par exemple us-chicago-1.

Pour l'API Réponses, utilisez le chemin de point d'extrémité suivant :

/responses

Vous pouvez utiliser l'API de réponses OCI pour appeler différents types de modèle disponibles dans les régions prises en charge par le service d'intelligence artificielle générative pour OCI. Pour obtenir la liste des modèles et des régions pris en charge, voir Modèles et régions d'agent.

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

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

Sélectionnez un modèle dans une région disponible, avec le mode disponible qui correspond le mieux à vos exigences en matière de performance, de coût et de contrôle.

Les exemples suivants montrent comment appeler l'API Responses à l'aide de Python. Si la demande retourne une explication, l'API des réponses OCI fonctionne correctement.

Si vous rencontrez des problèmes lors de l'appel de l'API, l'activation de la journalisation du débogage peut faciliter le dépannage. Les journaux de débogage affichent les demandes et les réponses HTTP brutes, y compris opc-request-id, ce qui est utile lors de l'utilisation du soutien technique d'Oracle.

Vous pouvez référencer cet ID demande lors du signalement de problèmes pour vous aider à identifier et diagnostiquer les problèmes plus rapidement.

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

L'API des réponses OCI prend en charge la diffusion en continu, où vous pouvez recevoir les sorties de modèle de manière incrémentielle au fur et à mesure que les jetons sont générés.

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)

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)

Les contrôles de raisonnement vous permettent de régler l'effort utilisé par le modèle avant de produire une réponse. Cette option est utile lorsque vous souhaitez hiérarchiser la vitesse, la profondeur ou un équilibre entre les deux.

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

print(response.output_text)

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

print(response.output_text)

Utilisez des sorties structurées lorsque vous souhaitez que le modèle retourne des données dans un format prévisible au lieu de texte à structure libre. Cette fonction est utile pour extraire des champs d'une entrée non structurée, transmettre des résultats à d'autres systèmes ou afficher des valeurs spécifiques dans une interface utilisateur. Dans l'API OCI Responses, vous définissez un schéma et analysez la réponse par rapport à celui-ci, ce qui rend la sortie plus cohérente et plus facile à utiliser pour les applications. Les sorties structurées correspondent à un schéma fourni, tandis qu'un mode JSON garantit uniquement un JSON valide.

Un objet fortement typé est un objet dont les champs et les types de données sont définis à l'avance. Par exemple, si un schéma indique que customer_name doit être une chaîne et que priority doit être l'un des suivants : "low", "medium" ou "high", le résultat analysé suit cette structure. Cela permet au code de travailler plus facilement avec la réponse en toute sécurité et de manière prévisible. L'API de réponses OCI prend en charge ce problème en vous permettant de définir un schéma et d'analyser la sortie du modèle dans des objets fortement typés.

Cette approche est utile lors de l'intégration à des systèmes en aval, de l'application de la cohérence ou de l'extraction de champs spécifiques à partir d'une entrée en langage naturel.

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)

Exemple de sortie :

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'
)

L'API de réponses OCI prend en charge les modèles qui acceptent les entrées multimodales. Vous pouvez combiner du texte avec des images, des fichiers et des contrôles de raisonnement pour prendre en charge des flux de travail plus riches tels que l'analyse de documents, la compréhension des images et des réponses de modèle plus délibérées.

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)

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)

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)

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)

Utilisez la recherche de fichiers pour permettre au modèle d'extraire le contenu pertinent des fichiers stockés dans un magasin de vecteurs lors de la génération de la réponse. Cette fonction est utile lorsque vous souhaitez que les réponses reflètent les documents que vous fournissez plutôt que de vous fier uniquement aux connaissances intégrées du modèle.

En créant des magasins vectoriels et en leur ajoutant des fichiers, vous activez la recherche sémantique et basée sur des mots clés dans vos données. Cela étend les connaissances intégrées du modèle avec votre contenu personnalisé et aide à produire des réponses plus précises et contextuelles.

Comme la recherche de fichiers est gérée par le service, votre application n'a pas besoin de mettre en oeuvre son propre pipeline d'extraction.

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)

Utilisez l'interpréteur de code pour laisser le modèle écrire et exécuter du code Python dans un conteneur isolé et sécurisé. Cet outil est utile pour les calculs, l'analyse de données, le traitement de fichiers et d'autres tâches de calcul.

Comme le code s'exécute dans un environnement isolé sans accès réseau externe, l'interpréteur de code est une bonne option lorsque le flux de travail nécessite un calcul ou un traitement de fichiers dans un paramètre contrôlé.

Utilisez l'appel de fonction pour laisser les données ou les actions de demande de modèle de votre application lors d'un flux de travail d'API de réponses. Cela est utile lorsque le modèle a besoin d'informations ou d'opérations qui ne sont pas disponibles dans l'invite elle-même, telles que les données de calendrier, l'état de l'application interne ou le résultat d'une opération personnalisée.

Avec ce modèle, le modèle n'exécute pas directement la fonction. Au lieu de cela, il retourne le nom et les arguments de la fonction, votre application exécute la fonction, puis l'application renvoie la sortie de la fonction afin que le modèle puisse continuer et produire la réponse orientée utilisateur.

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"],
        },
    },
]

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)

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)

Les outils MCP (Model Context Protocol) sont des fonctions exécutables ou des capacités que les modèles d'IA peuvent utiliser pour interagir avec des systèmes externes. Utilisez l'appel MCP dans le service d'intelligence artificielle générative pour OCI pour permettre à un modèle d'accéder aux outils exécutables exposés par un serveur MCP distant lors d'une demande d'API de réponses. Ces outils peuvent fournir un accès à des systèmes externes tels qu'une API, des bases de données, des systèmes de fichiers ou des points d'extrémité d'application. OCI Generative AI communique directement avec les serveurs MCP distants dans le cadre du flux de travail de demande.

Utilisez SQL Search (NL2SQL) pour convertir des demandes en langage naturel en SQL validé pour les données d'entreprise dans OCI Generative AI.

NL2SQL aide les agents d'IA d'entreprise à travailler avec des données d'entreprise fédérées sans déplacer ou dupliquer les données sous-jacentes. Il utilise une couche d'enrichissement sémantique pour mapper des termes métier avec des tables, des colonnes et des jointures de base de données, puis génère du code SQL à partir d'une entrée en langage naturel.

NL2SQL génère uniquement du code SQL. Elle n'exécute pas l'interrogation elle-même. L'exécution des interrogations est gérée séparément via le serveur MCP DBTools, qui autorise et exécute l'interrogation sur la base de données source à l'aide de l'identité de l'utilisateur final et des garde-corps appropriés.

Avant d'utiliser NL2SQL, vous devez disposer des éléments suivants :

• Une base de données source, telle qu'Oracle Autonomous Database
• Deux connexions à DBTools :
  • Connexion d'enrichissement
  • Connexion à l'interrogation
• Autorisations IAM pour les magasins sémantiques, NL2SQL, les outils de base de données et les clés secrètes
• Authentification OCI IAM configurée pour les API du service OCI utilisées dans ce démarrage rapide

Avant de créer un magasin sémantique, créez la base de données source et les connexions DBTools requises.

Vous avez besoin des connexions suivantes :

Avant de créer un magasin sémantique, configurez les politiques IAM requises.

Ce démarrage rapide utilise l'authentification OCI IAM pour l'API du service OCI qui crée des magasins sémantiques, exécute des tâches d'enrichissement et génère du code SQL.

Configurer l'authentification OCI IAM pour l'identité qui signe les demandes. Les exemples de cette section utilisent la trousse SDK Python pour OCI et BaseClient.

Vous pouvez vous authentifier en utilisant :

• Fichier de configuration OCI et clés de signature d'API
• Signataire de jeton de sécurité

Les exemples suivants utilisent SecurityTokenSigner, mais vous pouvez également utiliser un signataire de configuration OCI standard si cela convient mieux à votre environnement.

Sujets connexes

• Fichier de configuration de la trousse SDK et de l'interface de ligne de commande
• Signatures de demande
• Trousse SDK Python du signataire

Pour Automation, si vous avez sélectionné Aucun au lieu de À la création, vous pouvez exécuter l'enrichissement une fois le magasin sémantique créé. Effectuez cette étape si vous avez ignoré l'option En cours de création.

Le processus d'enrichissement lit les métadonnées du schéma, telles que les tables et les colonnes, à partir de la base de données connectée. OCI Generative AI utilise ces métadonnées pour générer le code SQL.

Pour déclencher l'enrichissement manuellement, appelez l'API GenerateEnrichmentJob.

Vous pouvez également gérer les tâches d'enrichissement à l'aide de l'API suivante :

• ListEnrichmentJobs
• GetEnrichmentJob
• CancelEnrichmentJob

NL2SQL utilise les API du service OCI plutôt que les chemins /openai/v1 compatibles avec OCI OpenAI.

Une fois le magasin sémantique prêt et l'enrichissement terminé, appelez l'API NL2SQL pour générer du code SQL à partir du langage naturel.

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

Utilisez les données de trace de réponse intégrées dans l'API Réponses OCI pour comprendre comment une demande a été traitée. Pour une observabilité plus approfondie, vous pouvez également intégrer l'API des réponses OCI à des plates-formes d'observabilité externes telles que Langfuse.

Ce démarrage rapide montre comment inspecter les détails d'exécution retournés par l'API Responses et comment tracer les demandes à l'aide de Langfuse.

Avant de commencer, vous devez disposer des éléments suivants :

• Un projet d'IA générative OCI
• Authentification configurée pour l'API de réponses OCI
• Trousse SDK OpenAI installée
• Un client d'API de réponses OCI fonctionnel

(Facultatif) Pour intégrer Langfuse, vous avez besoin d'un compte et de données d'identification Langfuse.

Lorsque vous appelez l'API de réponses OCI, la réponse inclut un champ output. Ce champ est un tableau d'éléments qui décrivent ce qui s'est passé pendant la demande.

Chaque élément représente une étape de l'exécution et peut inclure différents types, tels que :

• message
• file_search_call
• mcp_call

Ces éléments de sortie permettent de voir comment la demande a été traitée. Vous pouvez les utiliser pour :

• Déboguer et comprendre le comportement du modèle
• Afficher les étapes d'exécution dans une interface utilisateur
• Créer des flux de travail d'observabilité ou de journalisation personnalisés

Par exemple, après avoir envoyé une demande, vous pouvez inspecter le champ output :

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)

Pour obtenir des informations plus précises, telles que la latence, les coûts et les traces d'exécution, vous pouvez intégrer l'API des réponses d'OCI à une plate-forme d'observabilité.

Une option est Langfuse, une plate-forme d'ingénierie LLM à code source libre qui aide les développeurs à déboguer, surveiller et améliorer les applications LLM. Langfuse fournit une observabilité de bout en bout pour le suivi des actions d'agent, prend en charge le contrôle des versions rapide et aide à évaluer les sorties du modèle. Il s'intègre à des frameworks populaires tels que OpenAI, LangChain et LlamaIndex.

Installez le SDK Langfuse :

pip install langfuse

Définissez les variables d'environnement Langfuse et OCI requises :

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"

Importez le client OpenAI à partir du SDK Langfuse. Le code de demande existant reste le même, mais les demandes sont automatiquement suivies.

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

Après avoir instrumenté le client, envoyez une demande d'API Responses comme d'habitude. Langfuse trace automatiquement la demande.

Exemple :

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)