Inicio rapido

Antes de crear un proyecto o llamar a la API de respuestas de OCI, asegúrese de que los permisos de IAM necesarios están establecidos.

La API de respuestas de OCI soporta dos métodos de autenticación. Puede utilizar cualquiera de las dos opciones.

• Claves de API de OCI Generative AI

  Autenticar y llegar a los modelos y puntos finales con claves de API específicas del servicio de IA generativa compatibles con OpenAI. Utilice esta opción para pruebas y desarrollo anticipado.

• Autenticación basada en IAM de OCI

  Autenticar y acceder a los modelos y puntos finales mediante solicitudes de API firmadas. Recomendamos esta opción para cargas de trabajo de producción y entornos gestionados por OCI. Considere el uso de la autenticación de IAM cuando:

  • Ejecutar aplicaciones en servicios de OCI como Functions u Oracle Kubernetes Engine (OKE)
  • Quiere evitar claves de API de larga duración
  • Se necesita un control de acceso centralizado a través de OCI IAM

Instale el SDK oficial de OpenAI.

Python

pip install openai

Para otros idiomas, consulte la página Bibliotecas OpenAI.

La API de respuestas de OCI es la API principal para crear aplicaciones ágentes de IA empresarial en OCI Generative AI. Le permite enviar solicitudes de modelos, utilizar herramientas y gestionar el contexto de la conversación a través de una única API.

Utilice la API Responses para:

• Ejecute flujos de trabajo de agente de inferencia de un solo paso o de varios pasos
• Activar o desactivar el razonamiento, según el caso de uso
• Integrar herramientas gestionadas por la plataforma o del cliente
• Gestionar el estado de la conversación en el servicio o en el cliente

La API de respuestas de OCI utiliza una interfaz compatible con OpenAI. Las solicitudes utilizan la misma sintaxis de estilo OpenAI, pero se envían a OCI Generative AI y se autentican con credenciales de OCI, como claves de API de OCI Generative AI o autenticación basada en OCI IAM.

El cliente recomendado es el SDK OpenAI. Soporta lenguajes como Python, Java, TypeScript, Go y .NET. También puede utilizarlo con marcos como LangChain, LlamaIndex y OpenAI Agents SDK.

Utilice la siguiente URL base:

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

Sustituya ${region} por su región de OCI, por ejemplo, us-chicago-1.

Para la API Responses, utilice la siguiente ruta de acceso de punto final:

/responses

Puede utilizar la API de respuestas de OCI para llamar a diferentes tipos de modelos disponibles en las regiones soportadas de OCI Generative AI. Para obtener una lista de los modelos y regiones soportados, consulte Agent Models and Regions.

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

Seleccione un modelo en una región disponible, con el modo disponible que mejor se adapte a sus requisitos de rendimiento, costo y control.

En los siguientes ejemplos se muestra cómo llamar a la API de respuestas mediante Python. Si la solicitud devuelve una explicación, la API de respuestas de OCI funciona correctamente.

Si encuentra problemas al llamar a la API, activar el registro de depuración puede ayudar con la resolución de problemas. Los logs de depuración muestran las solicitudes y respuestas HTTP sin procesar, incluido opc-request-id, que es útil al trabajar con los Servicios de Soporte Oracle.

Puede hacer referencia a este ID de solicitud al informar problemas para ayudar a identificar y diagnosticar problemas más rápidamente.

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

La API de respuestas de OCI soporta la transmisión, donde puede recibir salidas de modelo de forma incremental a medida que se generan los tokens.

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)

Los controles de razonamiento le permiten ajustar cuánto esfuerzo utiliza el modelo antes de producir una respuesta. Esto es útil cuando se desea priorizar la velocidad, la profundidad o un equilibrio de ambos.

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)

Utilice salidas estructuradas cuando desee que el modelo devuelva datos en un formato predecible en lugar de texto de formato libre. Esto resulta útil para extraer campos de entradas no estructuradas, transferir resultados a otros sistemas o mostrar valores específicos en una interfaz de usuario. En la API de respuestas de OCI, puede definir un esquema y analizar la respuesta en él, lo que hace que la salida sea más coherente y fácil de utilizar para las aplicaciones. Las salidas estructuradas coinciden con un esquema proporcionado, mientras que el modo JSON solo garantiza un JSON válido.

Un objeto de tipo fuerte es un objeto cuyos campos y tipos de datos se definen con antelación. Por ejemplo, si un esquema dice que customer_name debe ser una cadena y priority debe ser "low", "medium" o "high", el resultado analizado sigue a esa estructura. Esto facilita que el código funcione con la respuesta de forma segura y predecible. La API de respuestas de OCI soporta esto al permitirle definir un esquema y analizar la salida del modelo en objetos de tipo fuerte.

Este enfoque es útil cuando se integra con sistemas descendentes, se aplica la coherencia o se extraen campos específicos de la entrada de lenguaje natural.

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)

Ejemplo de salida:

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

La API de respuestas de OCI soporta modelos que aceptan entradas multimodales. Puede combinar texto con imágenes, archivos y controles de razonamiento para admitir flujos de trabajo más completos, como análisis de documentos, comprensión de imágenes y respuestas de modelos más deliberadas.

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)

Utilice la búsqueda de archivos para permitir que el modelo recupere contenido relevante de los archivos almacenados en un almacén de vectores durante la generación de respuestas. Esto resulta útil cuando desea que las respuestas reflejen los documentos que proporciona, en lugar de depender solo de los conocimientos incorporados del modelo.

Mediante la creación de almacenes de vectores y la adición de archivos a ellos, se activa la búsqueda semántica y basada en palabras clave en los datos. Esto amplía el conocimiento integrado del modelo con su contenido personalizado y ayuda a producir respuestas más precisas y conscientes del contexto.

Puesto que el servicio se encarga de la búsqueda de archivos, la aplicación no necesita implantar su propio pipeline de recuperación.

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)

Utilice Code Interpreter para permitir que el modelo escriba y ejecute código Python en un contenedor seguro y aislado. Esta herramienta es útil para cálculos, análisis de datos, procesamiento de archivos y otras tareas de cálculo.

Debido a que el código se ejecuta en un entorno aislado sin acceso a la red externa, Code Interpreter es una buena opción cuando el flujo de trabajo necesita un cálculo o procesamiento de archivos en una configuración controlada.

Utilice Llamadas de función para permitir que el modelo solicite datos o acciones de la aplicación durante un flujo de trabajo de API de respuestas. Esto resulta útil cuando el modelo necesita información u operaciones que no están disponibles en la petición de datos en sí, como datos de calendario, estado interno de la aplicación o el resultado de una operación personalizada.

Con este patrón, el modelo no ejecuta la función directamente. En su lugar, devuelve el nombre y los argumentos de la función, la aplicación ejecuta la función y, a continuación, la aplicación vuelve a enviar la salida de la función para que el modelo pueda continuar y producir la respuesta orientada al usuario.

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)

Las herramientas de MCP (Model Context Protocol) son funciones ejecutables o capacidades que los modelos de IA pueden utilizar para interactuar con sistemas externos. Utiliza las llamadas MCP en OCI Generative AI para permitir que un modelo acceda a las herramientas ejecutables expuestas por un servidor MCP remoto durante una solicitud de API Responses. Estas herramientas pueden proporcionar acceso a sistemas externos como API, bases de datos, sistemas de archivos o puntos finales de aplicaciones. OCI Generative AI se comunica directamente con los servidores MCP remotos como parte del flujo de trabajo de solicitud.

Utiliza SQL Search (NL2SQL) para convertir solicitudes en lenguaje natural en SQL validado para datos empresariales en OCI Generative AI.

NL2SQL ayuda a los agentes de IA empresarial a trabajar con datos empresariales federados sin mover ni duplicar los datos subyacentes. Utiliza una capa de enriquecimiento semántico para asignar términos de negocio a tablas, columnas y uniones de base de datos y, a continuación, genera SQL a partir de la entrada en lenguaje natural.

NL2SQL sólo genera SQL. No ejecuta la consulta en sí. La ejecución de consultas se maneja por separado mediante el servidor MCP de DBTools, que autoriza y ejecuta la consulta en la base de datos de origen mediante la identidad del usuario final y las guías de protección adecuadas.

Antes de utilizar NL2SQL, debe tener:

• Una base de datos de origen, como Oracle Autonomous Database
• Dos conexiones de DBTools:
  • Conexión de enriquecimiento
  • Conexión de consulta
• Permisos de IAM para almacenes semánticos, NL2SQL, herramientas de base de datos y secretos
• Autenticación de OCI IAM configurada para las API del servicio OCI que se utilizan en este inicio rápido

Antes de crear un almacén semántico, cree la base de datos de origen y las conexiones de DBTools necesarias.

Necesita las siguientes conexiones:

Antes de crear un almacén semántico, configure las políticas de IAM necesarias.

Este inicio rápido utiliza la autenticación de OCI IAM para la API de servicio de OCI que crea almacenes semánticos, ejecuta trabajos de enriquecimiento y genera SQL.

Configure la autenticación de OCI IAM para la identidad que firma las solicitudes. Los ejemplos de esta sección utilizan el SDK de Python de OCI y BaseClient.

Puede autenticarse mediante:

• Un archivo de configuración de OCI y claves de firma de API
• Un firmante de token de seguridad

En los siguientes ejemplos se utiliza SecurityTokenSigner, pero también puede utilizar un firmante de configuración de OCI estándar si eso se ajusta mejor a su entorno.

Temas relacionados

• archivo de configuración del SDK y la CLI
• Firmas de solicitud
• SDK de Python del firmante

En Automatización, si ha seleccionado Ninguno en lugar de Al crear, puede ejecutar el enriquecimiento después de crear el almacén semántico. Realice este paso si ha omitido la opción Al crear.

El proceso de enriquecimiento lee los metadatos del esquema, como tablas y columnas, de la base de datos conectada. OCI Generative AI utiliza estos metadatos para ayudar a generar el SQL.

Para disparar el enriquecimiento manualmente, llame a la API GenerateEnrichmentJob.

También puede gestionar trabajos de enriquecimiento mediante la siguiente API:

• ListEnrichmentJobs
• GetEnrichmentJob
• CancelEnrichmentJob

NL2SQL utiliza API de servicio de OCI en lugar de las rutas /openai/v1 compatibles con OCI OpenAI.

Una vez que el almacén semántico esté listo y se haya completado el enriquecimiento, llame a la API NL2SQL para generar SQL a partir del lenguaje natural.

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

Utilice los datos de rastreo de respuesta incorporados en la API de respuestas de OCI para comprender cómo se procesó una solicitud. Para una observación más profunda, también puedes integrar la API de respuestas de OCI con plataformas de observación externas como Langfuse.

Este QuickStart muestra cómo inspeccionar los detalles de ejecución devueltos por la API de respuestas y cómo rastrear solicitudes mediante Langfuse.

Antes de empezar, debe tener:

• Un proyecto de IA generativa de OCI
• Autenticación configurada para la API de respuestas de OCI
• SDK de OpenAI instalado
• Un cliente de API de respuestas de OCI en funcionamiento

(Opcional) Para integrarse con Langfuse, necesita una cuenta y credenciales de Langfuse.

Cuando llama a la API de respuestas de OCI, la respuesta incluye un campo output. Este campo es una serie de elementos que describen lo que ha ocurrido durante la petición.

Cada elemento representa un paso en la ejecución y puede incluir diferentes tipos, como:

• message
• file_search_call
• mcp_call

Estos elementos de salida proporcionan visibilidad de cómo se procesó la solicitud. Puede utilizarlas para:

• Depurar y comprender el comportamiento del modelo
• Mostrar los pasos de ejecución en una interfaz de usuario
• Crear flujos de trabajo personalizados de observación o registro

Por ejemplo, después de enviar una solicitud, puede inspeccionar el campo 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)

Para obtener información más detallada, como rastreos de latencia, costos y ejecución, puede integrar la API de respuestas de OCI con una plataforma de observación.

Una opción es Langfuse, una plataforma de ingeniería de LLM de código abierto que ayuda a los desarrolladores a depurar, supervisar y mejorar aplicaciones de LLM. Langfuse proporciona una capacidad de observación integral para rastrear acciones de agente, soporta el control de versiones de petición de datos y ayuda a evaluar las salidas del modelo. Se integra con marcos populares como OpenAI, LangChain y LlamaIndex.

Instale el SDK de Langfuse:

pip install langfuse

Defina las variables de entorno de Langfuse y OCI necesarias:

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"

Importe el cliente OpenAI desde el SDK de Langfuse. El código de solicitud existente permanece igual, pero las solicitudes se rastrean automáticamente.

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

Después de instrumentar al cliente, envíe una solicitud de API de respuestas como de costumbre. Langfuse realiza un seguimiento automático de la solicitud.

Ejemplo:

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)