Avvio rapido

Prima di creare un progetto o chiamare l'API Risposte OCI, assicurarsi che siano disponibili le autorizzazioni IAM necessarie.

L'API OCI Responses supporta due metodi di autenticazione. È possibile utilizzare una delle due opzioni.

• Chiavi API OCI Generative AI

  Autentica e raggiungi i modelli e gli endpoint con chiavi API specifiche del servizio AI generativa compatibili con OpenAI. Utilizzare questa opzione per il test e lo sviluppo anticipato.

• Autenticazione basata su IAM OCI

  Autenticare e raggiungere i modelli e gli endpoint utilizzando le richieste API firmate. Consigliamo questa opzione per i carichi di lavoro di produzione e gli ambienti gestiti da OCI. Prendere in considerazione l'uso dell'autenticazione IAM quando si effettua le operazioni riportate di seguito.

  • Esegui le applicazioni nei servizi OCI come Functions o Oracle Kubernetes Engine (OKE)
  • Si desidera evitare chiavi API di lunga durata
  • Necessità di controllo dell'accesso centralizzato tramite IAM OCI

Installare l'SDK OpenAI ufficiale.

Python

pip install openai

Per altre lingue, vedere la pagina Librerie OpenAI.

L'API delle risposte OCI è l'API principale per la creazione di applicazioni Agentic AI aziendali nell'AI generativa OCI. Consente di inviare richieste modello, utilizzare strumenti e gestire il contesto di conversazione tramite un'unica API.

Utilizzare l'API Risposte per effettuare le operazioni riportate di seguito.

• Esegui flussi di lavoro degli agenti semplici e a passo singolo o in più fasi
• Abilita o disabilita il ragionamento, a seconda del caso d'uso
• Integra strumenti gestiti dalla piattaforma o lato client
• Gestire lo stato della conversazione nel servizio o nel client

L'API Risposte OCI utilizza un'interfaccia compatibile con OpenAI. Le richieste utilizzano la stessa sintassi in stile OpenAI, ma vengono inviate all'AI generativa OCI e autenticate con le credenziali OCI, come le chiavi API dell'AI generativa OCI o l'autenticazione basata su OCI IAM.

Il client consigliato è OpenAI SDK. Supporta linguaggi come Python, Java, TypeScript, Go e .NET. È inoltre possibile utilizzarlo con framework quali LangChain, LlamaIndex e OpenAI Agents SDK.

Utilizzare il seguente URL di base:

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

Sostituire ${region} con l'area OCI, ad esempio us-chicago-1.

Per l'API Risposte, utilizzare il seguente percorso endpoint:

/responses

È possibile utilizzare l'API Risposte OCI per chiamare diversi tipi di modelli disponibili nelle aree supportate dell'AI generativa OCI. Per un elenco dei modelli e delle aree supportati, vedere Modelli e aree agente.

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

Seleziona un modello in un'area disponibile, con la modalità disponibile più adatta alle tue esigenze in termini di prestazioni, costi e controllo.

Gli esempi riportati di seguito mostrano come chiamare l'API Risposte utilizzando Python. Se la richiesta restituisce una spiegazione, l'API Risposte OCI funziona correttamente.

In caso di problemi durante la chiamata all'API, l'abilitazione del log di debug può essere utile per la risoluzione dei problemi. I log di debug visualizzano le richieste e le risposte HTTP raw, incluso opc-request-id, utili quando si utilizza il supporto Oracle.

È possibile fare riferimento a questo ID richiesta durante la segnalazione dei problemi per facilitare l'identificazione e la diagnosi dei problemi più rapidamente.

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 supporta lo streaming, in cui è possibile ricevere gli output del modello in modo incrementale man mano che vengono generati i 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:
    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)

I controlli di ragionamento consentono di ottimizzare l'impegno utilizzato dal modello prima di produrre una risposta. Questo è utile quando si desidera dare priorità alla velocità, alla profondità o all'equilibrio di entrambi.

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)

Utilizzare gli output strutturati quando si desidera che il modello restituisca i dati in un formato prevedibile anziché in formato libero. Ciò è utile per estrarre campi da input non strutturati, passare risultati ad altri sistemi o mostrare valori specifici in un'interfaccia utente. Nell'API Risposte OCI è possibile definire uno schema e analizzarne la risposta, il che rende l'output più coerente e più facile da usare per le applicazioni. Gli output strutturati corrispondono a uno schema fornito, mentre una modalità JSON garantisce solo JSON valido.

Un oggetto fortemente digitato è un oggetto i cui campi e tipi di dati sono definiti in anticipo. Ad esempio, se uno schema indica che customer_name deve essere una stringa e che priority deve essere uno dei valori "low", "medium" o "high", il risultato analizzato segue tale struttura. Ciò rende più facile per il codice lavorare con la risposta in modo sicuro e prevedibile. L'API Risposte OCI supporta questo aspetto consentendo di definire uno schema e di analizzare l'output del modello in oggetti fortemente digitati.

Questo approccio è utile quando si integra con i sistemi a valle, applicando la coerenza o estraendo campi specifici dall'input del linguaggio naturale.

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)

Output di esempio:

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 supporta modelli che accettano input multimodali. È possibile combinare il testo con immagini, file e controlli di ragionamento per supportare flussi di lavoro più completi come l'analisi dei documenti, la comprensione delle immagini e risposte di modelli più deliberate.

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)

Utilizzare la ricerca file per consentire al modello di recuperare il contenuto pertinente dai file memorizzati in una memoria di vettore durante la generazione della risposta. Ciò è utile quando si desidera che le risposte riflettano i documenti forniti anziché basarsi solo sulla conoscenza integrata del modello.

La creazione di archivi vettoriali e l'aggiunta di file consentono di abilitare la ricerca semantica e basata su parole chiave nei dati. Ciò estende la conoscenza integrata del modello con i tuoi contenuti personalizzati e aiuta a produrre risposte più precise e sensibili al contesto.

Poiché la ricerca file è gestita dal servizio, l'applicazione non deve implementare la propria pipeline di recupero.

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)

Utilizzare l'interprete di codice per consentire al modello di scrivere ed eseguire codice Python in un contenitore sicuro e isolato. Questo strumento è utile per i calcoli, l'analisi dei dati, l'elaborazione dei file e altre attività complesse di calcolo.

Poiché il codice viene eseguito in un ambiente isolato senza accesso alla rete esterna, Code Interpreter è una buona opzione quando il flusso di lavoro richiede il calcolo o l'elaborazione dei file in un'impostazione controllata.

Utilizzare Chiamata funzione per consentire al modello di richiedere dati o azioni dall'applicazione durante un flusso di lavoro API Risposte. Ciò è utile quando il modello richiede informazioni o operazioni non disponibili nel prompt stesso, ad esempio dati di calendario, stato dell'applicazione interna o risultato di un'operazione personalizzata.

Con questo modello, il modello non esegue direttamente la funzione. Invece, restituisce il nome e gli argomenti della funzione, l'applicazione esegue la funzione e quindi l'applicazione invia l'output della funzione in modo che il modello possa continuare e produrre la risposta rivolta all'utente.

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)

Gli strumenti MCP (Model Context Protocol) sono funzioni eseguibili o funzionalità che i modelli AI possono utilizzare per interagire con sistemi esterni. Utilizza la chiamata MCP in OCI Generative AI per consentire a un modello di accedere agli strumenti eseguibili esposti da un server MCP remoto durante una richiesta API di risposte. Questi strumenti possono fornire l'accesso a sistemi esterni come API, database, file system o endpoint delle applicazioni. OCI Generative AI comunica direttamente con i server MCP remoti come parte del flusso di lavoro delle richieste.

Utilizza SQL Search (NL2SQL) per convertire le richieste in linguaggio naturale in SQL convalidato per i dati aziendali in OCI Generative AI.

NL2SQL aiuta gli Enterprise AI Agent a lavorare con i dati aziendali federati senza spostare o duplicare i dati sottostanti. Utilizza un livello di arricchimento semantico per mappare i termini aziendali a tabelle di database, colonne e join, quindi genera SQL da input in linguaggio naturale.

NL2SQL genera solo SQL. Non esegue la query stessa. L'esecuzione delle query viene gestita separatamente tramite il server MCP DBTools, che autorizza ed esegue la query sul database di origine utilizzando l'identità dell'utente finale e i guardrail appropriati.

Prima di utilizzare NL2SQL, è necessario disporre dei seguenti elementi:

• Un database di origine, ad esempio Oracle Autonomous Database
• Due connessioni DBTools:
  • Connessione di arricchimento
  • Connessione query
• Autorizzazioni IAM per Semantic Stores, NL2SQL, Database Tools e segreti
• Autenticazione IAM OCI configurata per le API del servizio OCI utilizzate in questo avvio rapido

Prima di creare un'area di memorizzazione semantica, creare il database di origine e le connessioni DBTools necessarie.

Sono necessarie le seguenti connessioni:

Prima di creare un'area di memorizzazione semantica, impostare i criteri IAM necessari.

Questo QuickStart utilizza l'autenticazione IAM OCI per l'API del servizio OCI che crea aree di memorizzazione semantiche, esegue job di arricchimento e genera SQL.

Impostare l'autenticazione IAM OCI per l'identità che firma le richieste. Gli esempi in questa sezione utilizzano l'SDK Python OCI e BaseClient.

È possibile eseguire l'autenticazione utilizzando:

• Un file di configurazione e chiavi di firma API OCI
• Firmatario del token di sicurezza

Gli esempi riportati di seguito utilizzano SecurityTokenSigner, ma è anche possibile utilizzare un firmatario di configurazione OCI standard se si adatta meglio al proprio ambiente.

Argomenti correlati

• file di configurazione SDK e CLI
• Firme richiesta
• SDK Python firmatario

Per Automazione, se è stato selezionato Nessuno anziché Al momento della creazione, è possibile eseguire l'arricchimento dopo la creazione dell'area di memorizzazione semantica. Eseguire questo passo se si è saltata l'opzione Al momento della creazione.

Il processo di arricchimento legge i metadati dello schema, ad esempio tabelle e colonne, dal database connesso. OCI Generative AI utilizza questi metadati per generare l'istruzione SQL.

Per attivare l'arricchimento manualmente, chiamare l'API GenerateEnrichmentJob.

È inoltre possibile gestire i job di integrazione utilizzando l'API seguente:

• ListEnrichmentJobs
• GetEnrichmentJob
• CancelEnrichmentJob

NL2SQL utilizza le API del servizio OCI anziché i percorsi /openai/v1 compatibili con OCI OpenAI.

Una volta che il Semantic Store è pronto e l'arricchimento è stato completato, chiamare l'API NL2SQL per generare SQL dal linguaggio naturale.

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

Utilizzare i dati di trace di risposta built-in nell'API Risposte OCI per comprendere come è stata elaborata una richiesta. Per un'osservabilità più approfondita, puoi anche integrare l'API delle risposte OCI con piattaforme di osservabilità esterne come Langfuse.

Questo QuickStart mostra come ispezionare i dettagli di esecuzione restituiti dall'API Risposte e come tracciare le richieste utilizzando Langfuse.

Prima di iniziare, è necessario disporre dei seguenti elementi:

• Un progetto di AI generativa OCI
• Autenticazione configurata per l'API Risposte OCI
• OpenAI SDK installato
• Client API di OCI Responses funzionante

(Facoltativo) Per l'integrazione con Langfuse, è necessario un account Langfuse e le credenziali.

Quando si chiama l'API Risposte OCI, la risposta include un campo output. Questo campo è un array di elementi che descrivono ciò che è accaduto durante la richiesta.

Ogni elemento rappresenta un passo dell'esecuzione e può includere tipi diversi, ad esempio:

• message
• file_search_call
• mcp_call

Questi elementi di output forniscono visibilità sull'elaborazione della richiesta. È possibile utilizzarli per:

• Eseguire il debug e comprendere il comportamento del modello
• Visualizzare i passi di esecuzione in un'interfaccia utente
• Crea flussi di lavoro di osservabilità o registrazione personalizzati

Ad esempio, dopo aver inviato una richiesta, è possibile ispezionare il 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)

Per insight più approfonditi, come latenza, costi e tracce di esecuzione, puoi integrare l'API delle risposte OCI con una piattaforma di osservabilità.

Un'opzione è Langfuse, una piattaforma di progettazione LLM open source che aiuta gli sviluppatori a eseguire il debug, monitorare e migliorare le applicazioni LLM. Langfuse offre osservabilità end-to-end per il trace delle azioni degli agenti, supporta il controllo delle versioni dei prompt e consente di valutare gli output dei modelli. Si integra con framework popolari come OpenAI, LangChain e LlamaIndex.

Installare Langfuse SDK:

pip install langfuse

Impostare le variabili di ambiente Langfuse e OCI necessarie:

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"

Importare il client OpenAI dall'SDK Langfuse. Il codice richiesta esistente rimane invariato, ma le richieste vengono tracciate automaticamente.

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

Dopo aver eseguito la strumentazione del client, inviare una richiesta API Risposte come al solito. Langfuse traccia automaticamente la richiesta.

Esempio:

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)