Documentazione dell'infrastruttura Oracle Cloud

Endpoint compatibili con OCI OpenAI

Utilizza gli endpoint compatibili con OCI Generative AI OpenAI per chiamare i modelli AI di livello Enterprise e creare agenti AI di livello Enterprise attraverso API familiari in stile OpenAI. Chiama questi endpoint per raggiungere i pattern di richieste OpenAI supportati mantenendo al contempo l'autenticazione, l'esecuzione e la gestione delle risorse all'interno di OCI.

Modelli AI aziendali
Chiama i modelli in hosting supportati o i modelli importati con l'API Risposte o Completamenti chat.
Agenti AI aziendali

Utilizzare l'API Risposte come API principale compatibile con OpenAI per carichi di lavoro agenti. È possibile utilizzarlo insieme agli strumenti degli agenti supportati, alle funzionalità di memoria degli agenti e agli elementi di base degli agenti di basso livello, ad esempio File, Vector Stores e Container.

Oltre agli endpoint compatibili con OpenAI, OCI Generative AI fornisce anche un'API di inferenza OCI nativa tramite un endpoint separato per le attività di chat, incorporamento e riassegnazione.

Informazioni sugli endpoint compatibili con OCI OpenAI

L'endpoint di base compatibile con OpenAI è:

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

È possibile utilizzare l'endpoint di base con percorsi di tipo OpenAI supportati da OCI.

Percorsi di esempio:

  • /responses
  • /conversations
  • /containers
  • /files

Vantaggi principali

Sebbene il formato API sia compatibile con OpenAI, l'implementazione è completamente integrata con OCI:

  • L'autenticazione utilizza le chiavi API OCI Generative AI o l'autenticazione basata su OCI IAM, non le credenziali OpenAI.
  • Le richieste vengono instradate agli endpoint di inferenza dell'AI generativa OCI in un'area OCI supportata.
  • Risorse come file e container vengono create e gestite in OCI.
  • L'elaborazione dei dati rimane all'interno dell'infrastruttura OCI.
  • Le applicazioni esistenti create per l'API OpenAI possono spesso essere adattate con modifiche minime al codice, in genere aggiornando l'URL di base, il metodo di autenticazione e il nome del modello.

Ad esempio, una richiesta a /openai/v1/containers crea e gestisce una risorsa contenitore in OCI Generative AI.

Autenticazione

È possibile accedere agli endpoint compatibili con OCI OpenAI in due modi:

Utilizza le API key per test e sviluppo precoce. Utilizza l'autenticazione basata su IAM per i carichi di lavoro di produzione e gli ambienti gestiti da OCI.

Endpoint supportati

Importante

Utilizza gli endpoint compatibili con OCI OpenAI solo con modelli supportati nelle aree supportate.

Per flussi di lavoro inferenza modello e agenti

Per accedere ai modelli in hosting e importati supportati tramite l'API compatibile con OCI OpenAI per l'inferenza dei modelli e i flussi di lavoro agenti, utilizzare gli endpoint riportati di seguito.

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

API Percorso endpoint Uso suggerito
API risposte /responses Utilizzare questa interfaccia principale per chiamare i modelli e generare risposte. Facoltativamente, includere gli strumenti supportati e gli ID conversazione per il contesto.
API conversazioni /conversations Utilizza questa interfaccia persistente con conservazione dello stato per gestire la cronologia delle conversazioni in più turni. Includere l'ID conversazione nell'API Risposte, che rimane l'endpoint primario per la generazione delle risposte del modello.
API completamenti chat /chat/completions Utilizzare questa interfaccia chat senza stato e il predecessore dell'API Conversazioni con conservazione dello stato se si dispone già di un codice applicazione basato sull'API Chat Completions o se è necessaria un'interfaccia chat-only più semplice. In caso contrario, utilizzare l'API Conversazioni insieme all'API Risposte.

Componenti agente-generazione

Per carichi di lavoro agenti, le API compatibili con OCI OpenAI includono i seguenti componenti di base:

API Percorso endpoint Uso suggerito
API File /files Per caricare e gestire i file
API File Vector Store /vector_stores/{id}/files Per gestire i file allegati a una memoria di vettore.
API batch file Vector Store /vector_stores/{id}/file_batches Per aggiungere e gestire contemporaneamente un batch di file della memoria di vettore.
API di ricerca area di memorizzazione vettore /vector_stores/{id}/search Per eseguire ricerche dirette su una memoria di vettore.
API container /containers Per la creazione e la gestione dei contenitori sandbox da utilizzare nei flussi di lavoro degli agenti.
API Container Files /containers/{id}/files Per gestire i file in un contenitore sandbox.

Suggerimento

Per la maggior parte dei nuovi carichi di lavoro agenti, utilizzare l'API Risposte come punto di accesso principale.

In molti casi, è possibile selezionare un modello supportato, facoltativamente includere il contesto di conversazione, dichiarare gli strumenti supportati nella richiesta e inviare la richiesta tramite l'API Risposte. OCI Generative AI gestisce quindi l'esecuzione dei modelli e l'uso degli strumenti come parte di tale flusso di lavoro.

Se necessario, è anche possibile combinare l'API Risposte con API di base di livello inferiore, ad esempio file, magazzini vettoriali e container.

Questo approccio è utile quando si desidera:

  • Utilizza i modelli supportati tramite un'unica API.
  • Dichiara gli strumenti direttamente nella richiesta.
  • Crea flussi di lavoro autentici con l'esecuzione gestita da OCI.
  • Aggiungere il contesto di conversazione tramite l'API Conversations.
  • Combina le richieste del modello con file, vector store o container quando necessario.

Esempio: utilizzo degli strumenti

Ad esempio, per utilizzare MCP Calling, specificare un modello e dichiarare lo strumento MCP nella richiesta API Risposte. Non è necessaria un'API separata specifica per MCP.

response = client.responses.create(
    model="openai.gpt-oss-120b",
    tools=[
        {
            "type": "mcp",
            "server_url": "https://example.com/mcp",
        }
    ],
    input="What events are scheduled for 2026-04-02?"
)

Esempio: utilizzo della cronologia delle conversazioni

Per il contesto della conversazione, creare prima una conversazione.

conversation = client.conversations.create()

Quindi inviare l'ID conversazione nella richiesta API Risposte per una conversazione in più turni.

response = client.responses.create(
    model="openai.gpt-oss-120b",
    input=[
        {
            "role": "user",
            "content": "Recommend a restaurant based on the food that I like."
        }
    ],
    conversation=conversation.id,
)