Démarrage express

Avant de créer un projet ou d'appeler l'API OCI Responses, vérifiez que les droits d'accès IAM requis sont en place.

L'API OCI Responses prend en charge deux méthodes d'authentification. Vous pouvez utiliser l'une ou l'autre option.

• Clés d'API OCI Generative AI

  Authentifiez et atteignez les modèles et les adresses avec des clés d'API propres au service d'IA générative compatibles OpenAI. Utilisez cette option pour les tests et le développement anticipé.

• Authentification basée sur OCI IAM

  Authentifier et atteindre les modèles et les adresses à 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 :

  • Exécuter des applications dans des services OCI tels que Functions ou Oracle Kubernetes Engine (OKE)
  • Vous voulez éviter les clés d'API à long terme
  • Besoin d'un contrôle d'accès centralisé via OCI IAM

Installez le SDK officiel OpenAI.

Python

pip install openai

Pour les autres langues, reportez-vous à la page Bibliothèques OpenAI.

L'API OCI Responses est l'API principale pour créer des applications agénétiques d'IA d'entreprise dans OCI Generative AI. Il vous permet d'envoyer des demandes de modèle, d'utiliser des outils et de gérer le contexte de conversation via une seule API.

Utilisez l'API des réponses pour :

• Exécuter des workflows d'inférence simple en une étape ou en plusieurs étapes
• 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 des réponses OCI utilise une interface compatible OpenAI. Les demandes utilisent la même syntaxe de type OpenAI, mais elles sont envoyées à OCI Generative AI et authentifiées avec les informations d'identification OCI, telles que les clés d'API OCI Generative AI ou l'authentification basée sur OCI IAM.

Le client recommandé est le kit SDK OpenAI. Il prend en charge des langages tels que Python, Java, TypeScript, Go et .NET. Vous pouvez également l'utiliser avec des frameworks 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 la région OCI, par exemple, us-chicago-1.

Pour l'API des réponses, utilisez le chemin d'adresse suivant :

/responses

Vous pouvez utiliser l'API OCI Responses pour appeler différents types de modèle disponibles dans les régions prises en charge par OCI Generative AI. Pour obtenir la liste des modèles et des régions pris en charge, reportez-vous à 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 performances, de coûts et de contrôle.

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

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

Vous pouvez référencer cet ID de demande lorsque vous signalez des problèmes afin d'identifier et de diagnostiquer plus rapidement les problèmes.

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 OCI Responses prend en charge la transmission en continu, où vous pouvez recevoir les sorties de modèle de façon incrémentielle lorsque 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 que le modèle utilise avant de produire une réponse. Ceci est utile lorsque vous souhaitez hiérarchiser la vitesse, la profondeur ou un équilibre des 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 voulez que le modèle renvoie des données dans un format prévisible au lieu d'un texte de format libre. Cela est utile pour extraire des champs d'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 des réponses OCI, 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 de type fort 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'une des chaînes "low", "medium" ou "high", le résultat analysé suit cette structure. Le code peut ainsi plus facilement utiliser la réponse de manière sûre et prévisible. L'API OCI Responses le prend en charge en vous permettant de définir un schéma et d'analyser la sortie du modèle en objets fortement typés.

Cette approche est utile lors de l'intégration avec les systèmes en aval, de l'application de la cohérence ou de l'extraction de champs spécifiques à partir de la saisie du 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 OCI Responses 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 d'images et des réponses de modèles 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 fichier pour permettre au modèle d'extraire le contenu pertinent des fichiers stockés dans une banque de vecteurs lors de la génération de la réponse. Cela est utile lorsque vous voulez que les réponses reflètent les documents que vous fournissez plutôt que de compter uniquement sur les connaissances intégrées du modèle.

En créant des banques de vecteurs et en y 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.

Etant donné que la recherche de fichier est gérée par le service, votre application n'a pas besoin d'implémenter 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 des données, le traitement des fichiers et d'autres tâches volumineuses.

Comme le code s'exécute dans un environnement isolé sans accès au réseau externe, l'interpréteur de code est une bonne option lorsque le workflow a besoin d'un calcul ou d'un traitement de fichier dans un paramètre contrôlé.

Utilisez l'appel de fonction pour laisser le modèle demander des données ou des actions à partir de votre application lors d'un workflow d'API 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 la fonction directement. Au lieu de cela, il renvoie le nom et les arguments de la fonction, l'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 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 fonctionnalités que les modèles d'IA peuvent utiliser pour interagir avec des systèmes externes. Utilisez l'appel MCP dans OCI Generative AI 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 que des API, des bases de données, des systèmes de fichiers ou des adresses d'application. OCI Generative AI communique directement avec les serveurs MCP distants dans le cadre du workflow 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 à utiliser les données d'entreprise fédérées sans déplacer ni dupliquer les données sous-jacentes. Il utilise une couche d'enrichissement sémantique pour mettre en correspondance des termes métier avec des tables de base de données, des colonnes et des jointures, puis génère du code SQL à partir d'entrées en langage naturel.

NL2SQL génère uniquement du code SQL. Il n'exécute pas la requête elle-même. L'exécution des requêtes est gérée séparément via le serveur DBTools MCP, qui autorise et exécute la requête sur la base de données source à l'aide de l'identité de l'utilisateur final et des garde-fous 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 de requête
• Droits d'accès IAM pour les magasins sémantiques, NL2SQL, Database Tools et les clés secrètes
• Authentification OCI IAM configurée pour les API de service OCI utilisées dans ce démarrage rapide

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

Les connexions suivantes sont nécessaires :

Avant de créer une banque sémantique, configurez les stratégies IAM requises.

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

Configurez l'authentification OCI IAM pour l'identité qui signe les demandes. Les exemples de cette section utilisent le kit SDK Python OCI et BaseClient.

Vous pouvez vous authentifier à l'aide des éléments suivants :

• 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.

Rubriques connexes

• Fichier d'interface de ligne de commande et de kit SDK
• Signatures des demandes
• Kit SDK Python Signer

Pour Automatisation, si vous avez sélectionné Aucun au lieu de Lors de la création, vous pouvez exécuter l'enrichissement une fois la banque sémantique créée. Effectuez cette étape si vous avez ignoré l'option Lors de la 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 SQL.

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

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

• ListEnrichmentJobs
• GetEnrichmentJob
• CancelEnrichmentJob

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

Une fois la banque sémantique prête 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 OCI Responses pour comprendre comment une demande a été traitée. Pour une observabilité plus approfondie, vous pouvez également intégrer l'API OCI Responses aux plates-formes d'observabilité externes telles que Langfuse.

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

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

• Un projet OCI Generative AI
• Authentification configurée pour l'API OCI Responses
• Le kit SDK OpenAI est installé
• Un client API OCI Réponses fonctionnel

(Facultatif) Pour l'intégration à Langfuse, vous avez besoin d'un compte et d'informations d'identification Langfuse.

Lorsque vous appelez l'API OCI Responses, 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 fournissent une visibilité sur la façon dont 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éez des workflows 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 détaillées, telles que la latence, les coûts et les traces d'exécution, vous pouvez intégrer l'API OCI Responses à une plate-forme d'observabilité.

L'une des options est Langfuse, une plate-forme d'ingénierie LLM open source 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 de l'agent, prend en charge la gestion des versions d'invite et aide à évaluer les sorties du modèle. Il s'intègre aux structures populaires telles qu'OpenAI, LangChain et LlamaIndex.

Installez le kit 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"),
)

Une fois que vous avez instrumenté le client, envoyez une demande d'API Réponses comme d'habitude. Langfuse trace automatiquement la demande.

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