Avvio rapido

Concedere l'accesso a livello di tenancy

Per consentire a un gruppo di utenti di gestire tutte le risorse di intelligenza artificiale generativa nella tenancy:

allow group <your-group-name> to manage generative-ai-family 
in tenancy

Concedi accesso a livello di compartimento

Per definire l'ambito dell'accesso a un compartimento specifico:

allow group <your-group-name> to manage generative-ai-family 
in compartment <your-compartment-name>

Una volta stabilite queste autorizzazioni, si è pronti per creare il primo progetto.

Trova OCID chiave API

Per definire l'ambito delle autorizzazioni per una chiave API specifica, è necessario il relativo OCID.

Nella console:

1. Passare alla pagina della lista Chiavi API.
2. Selezionare la chiave API creata.
3. Copiare OCID (in genere inizia con ocid1.generativeaiapikey...)

Concedere l'autorizzazione alla chiave API

Creare un criterio IAM per consentire alla chiave API di richiamare l'API delle risposte:

allow group <your-group-name> 
to manage generative-ai-response in tenancy where ALL 
{request.principal.type='generativeaiapikey', 
request.principal.id='<your-api-key-OCID>'}

Questo criterio consente alle richieste autenticate con la chiave API specificata di accedere all'API Risposte, mantenendo l'accesso definito e controllato.

URL di base 🔗

Utilizzare il seguente URL di base per accedere all'API Risposte OCI:

https://inference.generativeai.<region>.oci.oraclecloud.com/openai/v1

Sostituire <region> con l'identificativo di area appropriato (ad esempio, us-chicago-1).

Supporto SDK 🔗

L'API OCI Responses è compatibile con OpenAI SDK, consigliato per interagire con il servizio. È supportato in molti linguaggi, tra cui Python, Java, TypeScript, Go e .NET.

Puoi anche usarlo con framework di agenti popolari come LangChain, LlamaIndex e OpenAI Agents SDK.

Quando utilizzare l'autenticazione IAM

Prendere in considerazione l'uso dell'autenticazione IAM quando:

• Esecuzione di applicazioni nei servizi OCI (ad esempio, Functions o OKE)
• Evitare credenziali di lunga durata come le chiavi API
• Applicazione di un controllo dell'accesso capillare tramite criteri IAM

Installare la libreria di autenticazione IAM OCI

Installare la libreria oci-genai-auth, che fornisce le utility di supporto per l'integrazione dell'autenticazione IAM OCI con OpenAI SDK:

pip install oci-genai-auth

Questa libreria include i seguenti strumenti di supporto per l'autenticazione:

• OciSessionAuth (per lo sviluppo locale)
• OciUserPrincipalAuth
• OciInstancePrincipalAuth
• OciResourcePrincipalAuth (per ambienti gestiti da OCI)

Configurare il client OpenAI

Quando si utilizza l'autenticazione IAM, inizializzare il client OpenAI con un client HTTP personalizzato e un handler di autenticazione. In questo caso, il valore api_key è "not used".

Esempio: sviluppo locale (OciSessionAuth)

Utilizzare questo approccio quando si esegue il codice a livello locale (ad esempio su un laptop che utilizza un profilo CLI OCI):

from openai import OpenAI
from oci_openai import OciSessionAuth
import httpx

client = OpenAI(
    base_url="https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/openai/v1",  # update region if needed
    api_key="not-used",
    project="ocid1.generativeaiproject.oc1.us-chicago-1.xxxxxxxx",  # project OCID created earlier
    http_client=httpx.Client(auth=OciSessionAuth(profile_name="DEFAULT"))  # update profile if needed
)

response = client.responses.create(
    model="xai.grok-4-1-fast-reasoning",
    input="Write a one-sentence explanation of what a database is."
)

print(response.output_text)

Esempio: OCI Managed Environments (OciResourcePrincipalAuth)

Utilizzare questo approccio quando si esegue in servizi OCI come OCI Functions o OCI Container Engine for Kubernetes (OKE):

Se si utilizza l'autenticazione IAM OCI

Se i criteri sono stati aggiunti in Prerequisito: impostazione delle autorizzazioni IAM, saltare questo passo.

Per consentire a un gruppo di utenti di chiamare l'API Risposte, aggiungere il criterio seguente:

allow group <your-group-name> 
to manage generative-ai-response in tenancy

Se si utilizza l'autenticazione chiave API IA generativa

Quando si utilizza l'autenticazione della chiave API, è necessario un altro criterio per autorizzare le richieste effettuate con la chiave API. Se i criteri sono stati aggiunti in 3. Aggiungere l'autorizzazione alla chiave API, saltare questo passo.

Per concedere l'accesso a una chiave API specifica:

allow group <your-group-name> 
to manage generative-ai-response in tenancy 
where ALL {request.principal.type='generativeaiapikey', 
request.principal.id='<your-api-key-OCID>'}

Per un accesso più ampio (ad esempio durante i test), è possibile utilizzare un criterio più generale:

allow any-user 
to manage generative-ai-family in tenancy 
where ALL {request.principal.type='generativeaiapikey', 
request.principal.id='<your-api-key-OCID>'}

Questi criteri garantiscono che le richieste, autenticate tramite chiavi IAM o API, siano autorizzate ad accedere alle risorse OCI Generative AI.

Modelli in hosting di terze parti

OCI Generative AI fornisce l'accesso AI modelli da fornitori di terze parti. Specificare il modello utilizzando il nome completamente qualificato:

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

Modelli su richiesta

I modelli on-demand sono ospitati e gestiti da OCI e sono disponibili senza richiedere un'infrastruttura dedicata:

response = client.responses.create(
    model="openai.gpt-oss-120b",
    input="Write a one-sentence explanation of what a database is."
)

Cluster AI dedicati (modalità dedicata)

Per i carichi di lavoro di produzione che richiedono isolamento o prestazioni prevedibili, puoi distribuire modelli su un cluster AI dedicato. In questo caso, utilizzare l'OCID endpoint del cluster come identificativo del modello:

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

Streaming di tutti gli eventi

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)

Output solo testo flusso (token delta)

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)

Lo streaming è particolarmente utile per le applicazioni interattive in cui si desidera visualizzare le risposte agli utenti man mano che vengono generati.

Integrazione con gli strumenti di osservabilità 🔗

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

Molti provider supportano le API compatibili con OpenAI. Una di queste opzioni è Langfuse, una piattaforma di progettazione LLM open source che aiuta gli sviluppatori a eseguire il debug, monitorare e migliorare le applicazioni LLM. Fornisce osservabilità end-to-end per il tracciamento delle azioni degli agenti, supporta il controllo delle versioni dei prompt e aiuta nella valutazione degli output del modello. Langfuse si integra con framework popolari come OpenAI, LangChain e LlamaIndex.

L'esempio seguente mostra come utilizzare Langfuse per tracciare e monitorare le chiamate API Risposte.

Passo 1: Installare l'SDK Langfuse

pip install langfuse

Passo 2: configurare le variabili di ambiente

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"

Passo 3: strumento del client OpenAI

Importare il client OpenAI dall'SDK Langfuse. Il codice 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.us-ashburn-1.oci.oraclecloud.com/openai/v1",
    api_key=os.getenv("OCI_GENAI_API_KEY"),
    project=os.getenv("OCI_GENAI_PROJECT_ID"),
)

# Requests are automatically instrumented by Langfuse
response = client.responses.create(
    model="openai.gpt-oss-120b",
    tools=[
        {
            "type": "mcp",
            "server_label": "dmcp",
            "server_url": "https://mcp.deepwiki.com/mcp",
            "require_approval": "never",
        },
    ],
    input="Explain why tracing and observability are important in distributed systems."
)

print(response.output_text)

Questa integrazione offre visibilità end-to-end sulle chiamate API senza richiedere modifiche significative al codice dell'applicazione.

Input immagine come URL dati codificati in Base64

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="openai.gpt-oss-120b",
    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)

Input immagine come URL accessibile da Internet

response = client.responses.create(
    model="openai.gpt-oss-120b",
    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)

Sostituire "image_url" con un URL immagine valido.

Input file come ID file

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)

Input file come URL accessibile da Internet

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)

Impegno ragionamento

import json

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

print(response.output_text)

Output riepilogo motivo

Se stai creando un chatbot, abilitare riepiloghi del ragionamento può aiutare gli utenti a capire meglio come il modello è arrivato a un risultato. Durante lo streaming, gli utenti possono anche vedere i token di ragionamento mentre il modello sta pensando.

import json

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

print(response.output_text)

Cosa questo permette

Gli strumenti di funzione sono utili quando l'applicazione deve mantenere il controllo dell'esecuzione, pur consentendo al modello di decidere quando sono necessarie informazioni esterne.

Tipici casi d'uso sono:

• Ricerca degli eventi del calendario
• Recupero dei dati dell'applicazione
• Chiamata di API interne o esterne
• Esecuzione di business logic o calcoli

Questo approccio ti offre flessibilità mantenendo il percorso di esecuzione all'interno dell'applicazione.

Flusso di esecuzione 🔗

Un'interazione tipica dello strumento di funzione funziona così:

1. Il client invia una richiesta che include una o più definizioni di strumento.
2. Il modello decide se uno di questi strumenti è necessario.
3. Se è necessario uno strumento, il modello restituisce il nome e gli argomenti dello strumento.
4. L'applicazione esegue lo strumento e prepara il risultato.
5. L'applicazione invia il risultato in una richiesta di follow-up.
6. Il modello utilizza tale risultato per completare la risposta.

Opzioni di gestione dello stato 🔗

Esistono due modi comuni per gestire lo stato nelle seguenti richieste:

• Stato gestito dal servizio: consigliato per la maggior parte dei casi d'uso. La richiesta di follow-up include previous_response_id e il servizio tiene traccia dello scambio precedente.
• Stato gestito dal client: l'applicazione conserva l'intera cronologia delle interazioni e invia il contesto accumulato a ogni richiesta.

Definizione di uno strumento funzionale

Nell'esempio seguente viene definito uno strumento che recupera gli eventi di calendario per una data specificata.

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

Includere questo array tools nella richiesta client.responses.create().

Esempio: stato gestito dal servizio

In questo modello, la prima richiesta consente al modello di decidere se lo strumento è necessario. La seconda richiesta restituisce il risultato dello strumento e fa riferimento alla risposta precedente.

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)

Esempio: stato gestito dal servizio

In questo modello, l'applicazione mantiene lo scambio completo e lo risottomette con la richiesta di follow-up.

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 di funzione sono un'opzione efficace quando l'applicazione deve rimanere responsabile dell'esecuzione, del controllo dell'accesso e della logica di integrazione, pur consentendo al modello di richiedere le informazioni di cui ha bisogno.

Quando utilizzare lo strumento MCP

Utilizzare lo strumento MCP quando il modello deve accedere a funzionalità esterne ospitate su un server MCP.

Questo approccio è utile quando si desidera:

• Il servizio per comunicare direttamente con il server MCP
• Meno passi di orchestrazione lato client
• Latenza inferiore rispetto a un pattern di strumenti eseguito dal client
• Accesso alle funzionalità esposte tramite un server MCP remoto

Lo strumento MCP fa parte del set di strumenti OCI Generative AI e può essere utilizzato insieme ad altri strumenti supportati.

Supporto trasporto

Le chiamate MCP remote utilizzano Streamable HTTP.

Definizione di uno strumento MCP

Aggiungere la definizione del server MCP nel campo tools della richiesta.

response_stream = client.responses.create(
    model="xai.grok-code-fast-1",
    tools=[
        {
            "type": "mcp",
            "server_label": "calendar",
            "server_description": "An MCP server that retrieves calendar events for a specified date.",
            "server_url": "https://example.com/mcp",
            "require_approval": "never",
        },
    ],
    input="What events are scheduled for 2026-04-02?",
    stream=True,
)

for event in response_stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)

In questo esempio viene eseguito il flusso della risposta e viene stampato il testo man mano che viene generato.

Limitare gli strumenti esposti dal server MCP

Se il server MCP remoto espone un numero di strumenti superiore a quello richiesto dall'applicazione, è possibile limitare il set disponibile utilizzando allowed_tools.

response_stream = client.responses.create(
    model="openai.gpt-oss-120b",
    tools=[
        {
            "type": "mcp",
            "server_label": "calendar",
            "server_description": "An MCP server that retrieves calendar events for a specified date.",
            "server_url": "https://example.com/mcp",
            "require_approval": "never",
            "allowed_tools": ["get_events"],
        },
    ],
    input="Show the calendar events for 2026-02-02.",
    stream=True,
    store=False,
)

Autenticazione al server MCP

response_stream = client.responses.create(
    model="xai.grok-4-1-fast-reasoning",
    tools=[
        {
            "type": "mcp",
            "server_label": "calendar",
            "server_url": "https://calendar.example.com/mcp",
            "authorization": "$CALENDAR_OAUTH_ACCESS_TOKEN"
        },
    ],
    input="List my meetings for 2026-02-02.",
    stream=True,
    store=False,
)

Passare solo il valore del token. Non includere il prefisso Bearer. OCI invia il token su TLS come parte della richiesta e non decodifica, ispeziona, memorizza o registra il token.

Hosting server MCP

OCI Generative AI fornisce anche l'hosting di server MCP per aiutare a distribuire e ridimensionare i server MCP.

Lo strumento MCP è una buona opzione quando desideri che OCI Generative AI funzioni direttamente con un server MCP remoto durante l'esecuzione delle richieste, senza richiedere all'applicazione client di gestire ogni passo dello strumento stesso.

Prepara una memoria di vettore

Prima di utilizzare la ricerca file, creare una memoria di vettore e aggiungere i file a cui si desidera fare riferimento al modello. OCI Generative AI supporta diversi pattern di gestione dei file tramite API che seguono lo stile API dei file OpenAI.

Esempio

Per rendere disponibile la ricerca file in una richiesta, aggiungere una voce dello strumento con type: "file_search" e fornire l'ID della memoria di vettore.

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)

Per cosa puoi usarlo

Se stai usando questo per la prima volta, aiuta a pensare a Code Interpreter come a un'area di lavoro Python temporanea per il modello.

È possibile utilizzarlo per task quali:

• risolvere problemi matematici
• analisi dei file caricati
• pulizia o trasformazione dei dati
• creazione di grafici o tabelle
• generazione di file di output quali log o set di dati elaborati

Ambiente esecuzione

L'ambiente Python include più di 420 librerie preinstallate, pertanto molte attività comuni funzionano senza alcuna configurazione aggiuntiva.

Il codice viene eseguito all'interno di un container. Questo contenitore è l'ambiente di lavoro in cui viene eseguito Python e dove vengono memorizzati i file durante la sessione.

Limiti memoria contenitore

I contenitori dell'interprete di codice utilizzano un pool di memoria condivisa di 64 GB per tenancy.

Le dimensioni del contenitore supportate sono:

• 1 GB
• 4 GB
• 16 GB
• 64 GB

Questo limite condiviso può essere diviso tra più container. Ad esempio, potrebbe supportare:

• sessantaquattro contenitori da 1 GB
• sedici contenitori da 4 GB
• quattro contenitori da 16 GB
• un contenitore da 64 GB

Se è necessaria maggiore capacità, è possibile sottomettere una richiesta di servizio.

Scadenza container

Un contenitore scade dopo 20 minuti di inattività.

Questo è importante sapere quando si creano flussi in più fasi:

• impossibile riutilizzare un contenitore scaduto
• è necessario creare un nuovo contenitore
• i file devono essere nuovamente caricati, se necessario
• stato in-memory, ad esempio variabili Python, perso

Per questo motivo, è meglio trattare i container come ambienti di lavoro temporanei.

Esempio

response = client.responses.create(
    model="xai.grok-4-1-fast-reasoning",
    tools=[
        {
            "type": "code_interpreter",
            "container": {"type": "auto"}
        }
    ],
    instructions="Use the python tool to solve the problem and explain the result.",
    input="Find the value of (18 / 3) + 7 * 2."
)

print(response.output_text)

Container per interprete codice

L'interprete di codice ha bisogno di un contenitore. Il contenitore è l'ambiente isolato in cui il modello esegue il codice Python.

Un contenitore può contenere:

• file caricati
• file creati dal modello
• dati di lavoro temporanei durante l'esecuzione

Quando si utilizza l'interprete di codice, è possibile assegnare una delle due modalità contenitore riportate di seguito.

• Automatico: OCI Generative AI crea il contenitore automaticamente e assegna automaticamente una dimensione del contenitore.
• OCID contenitore: si crea il contenitore da soli, si definisce la dimensione del contenitore e si fornisce l'OCID.

Per entrambe le opzioni, i container vengono creati e gestiti in AI generativa OCI. Il codice eseguito in tali contenitori viene eseguito anche nella tenancy AI generativa OCI.

Modalità automatica

In modalità automatica, il servizio crea automaticamente il contenitore. Questa è l'opzione più semplice e un buon punto di partenza per la maggior parte degli utenti.

Utilizza la modalità automatica quando:

• vuoi che OCI Generative AI gestisca il container
• Non hai bisogno di un controllo diretto sull'ambiente
• vuoi un setup più semplice

response = client.responses.create(
    model="xai.grok-code-fast-1",
    tools=[{
        "type": "code_interpreter",
        "container": {
            "type": "auto"
        }
    }],
    input="Use the python tool to calculate the average of 12, 18, 24, and 30."
)

Modalità esplicita

In modalità esplicita, si crea prima il contenitore e si imposta la dimensione. Passare quindi l'ID contenitore nella richiesta.

Utilizzare la modalità esplicita quando si desidera un maggiore controllo sulle specifiche del contenitore, ad esempio la dimensione della memoria.

container = client.containers.create(name="test-container", memory_limit="4g")

response = client.responses.create(
    model="xai.grok-code-fast-1",
    tools=[{
        "type": "code_interpreter",
        "container": container.id
    }],
    tool_choice="required",
    input="Use the python tool to calculate the average of 12, 18, 24, and 30."
)

print(response.output_text)

File nell'interprete di codice

Code Interpreter può funzionare con i file durante la vita del contenitore. Il modello può leggere i file forniti e può anche creare nuovi file.

Ciò è utile per flussi di lavoro quali:

• lettura di un file CSV o PDF
• generazione di un grafico
• salvataggio output elaborato
• creazione di log o report

Persistenza file 🔗

I file creati o modificati dallo strumento python rimangono disponibili nello stesso contenitore finché il contenitore non è scaduto.

Ciò significa che il modello può basarsi su lavori precedenti nella stessa sessione. Ad esempio, può:

1. leggi un file
2. analizza
3. salvare un grafico
4. utilizzare il grafico più tardi nello stesso contenitore

Alla scadenza del contenitore, lo stato non è più disponibile.

Caricamento e gestione dei file 🔗

È possibile gestire i file contenitore tramite le API del file contenitore.

Le operazioni comuni includono:

• Crea file contenitore: aggiunge un file al contenitore
• Elenca file contenitore: consente di visualizzare i file nel contenitore
• Elimina file contenitore: rimuovere un file
• Recupera contenuto file contenitore: scaricare un file dal contenitore.

Ciò consente di utilizzare il contenitore come area di lavoro temporanea per l'esecuzione del codice basata su modelli.

File e citazioni di output 🔗

Quando il modello crea i file, tali file vengono memorizzati nel contenitore e possono essere utilizzati come riferimento nella risposta.

Questi riferimenti includono:

• container_id
• file_id
• filename

È possibile utilizzare questi valori per recuperare il contenuto del file generato.

L'API OCI Responses supporta endpoint compatibili con OpenAI per funzioni quali Risposte, File, Container e File contenitore. Per questo motivo, la documentazione OpenAI correlata può essere utilizzata come riferimento per la struttura delle richieste, i formati di risposta e i flussi di lavoro generali. Tuttavia, quando si utilizzano queste API con OCI, inviare richieste agli endpoint di inferenza AI generativa OCI, utilizzare l'autenticazione OCI e tenere presente che le risorse e l'esecuzione rimangono nell'AI generativa OCI e non in una tenancy OpenAI.

Requisiti indispensabili

Prima di utilizzare lo strumento NL2SQL, creare un database e configurare le connessioni al database necessarie.

Per ulteriori informazioni, fare riferimento agli argomenti sotto riportati.

• Duplica un'istanza di Autonomous AI Database
• Uso della console di Oracle Cloud Infrastructure

Autorizzazioni per negozi semantici

Accesso ai segreti

Concedere l'accesso di gruppo per leggere i segreti utilizzati dagli strumenti di database:

allow group <your-group-name> 
to read secret-family in compartment <your-compartment-name> 
where all {request.principal.type='generativeaisemanticstore'}

Accesso alle connessioni agli strumenti di database

Concedere al gruppo l'accesso alle risorse degli strumenti di database necessarie:

allow group <your-group-name> 
to use database-tools-family in compartment <compartment-name> 
where all {request.principal.type='generativeaisemanticstore'}

allow group <your-group-name> 
to read database-family in compartment <compartment-name> 
where all {request.principal.type='generativeaisemanticstore'}

allow group <your-group-name> 
to read autonomous-database-family in compartment <compartment-name> 
where all {request.principal.type='generativeaisemanticstore'}

Accesso alle risorse di intelligenza artificiale generativa

Se il criterio più ampio riportato di seguito è già in vigore, include l'accesso alle risorse dell'area di memorizzazione semantica:

allow group <your-group-name> 
to manage generative-ai-family in tenancy

Se si desidera un accesso più limitato, utilizzare il criterio riportato di seguito per consentire al gruppo di creare e gestire le aree di memorizzazione semantiche.

allow group <your-group-name> 
to manage generative-ai-semantic-store 
in compartment <your-compartment-name>

Se il gruppo deve utilizzare solo un'area di memorizzazione semantica esistente e chiamare NL2SQL, utilizzare i criteri più specifici riportati di seguito.

allow group <your-group-name> 
to use generative-ai-semantic-store 
in compartment <your-compartment-name>

allow group <your-group-name> 
to manage generative-ai-nl2sql 
in compartment <your-compartment-name>

Concatenamento risposte

Con il concatenamento delle risposte, ogni nuova risposta punta a quella precedente. Questa è un'opzione semplice quando si desidera portare avanti il contesto senza creare esplicitamente una risorsa di conversazione.

# first turn
response1 = client.responses.create(
    model="openai.gpt-oss-120b",
    input="Give me three ideas for a team offsite.",
)
print("Response 1:", response1.output_text)

# second turn
response2 = client.responses.create(
    model="openai.gpt-oss-120b",
    input="Make the second idea more budget friendly.",
    previous_response_id=response1.id,
)
print("Response 2:", response2.output_text)

API conversazioni

# create a conversation
conversation = client.conversations.create(
    metadata={"topic": "demo"}
)
print("Conversation ID:", conversation.id)

# first turn
response1 = client.responses.create(
    model="openai.gpt-oss-120b",
    input="Give me three ideas for a team offsite.",
    conversation=conversation.id,
)
print("Response 1:", response1.output_text)

# second turn
response2 = client.responses.create(
    model="openai.gpt-oss-120b",
    input="Make the second idea more budget friendly.",
    conversation=conversation.id,
)
print("Response 2:", response2.output_text)