Documentazione dell'infrastruttura Oracle Cloud

Chiavi API

Le chiavi API dell'AI generativa OCI sono token di credenziali sicure utilizzati per autenticare i chiamanti e autorizzare l'accesso a modelli di linguaggio di grandi dimensioni ospitati dal servizio OCI Generative AI.

Informazioni sulla chiave API

Una chiave API OCI Generative AI è un token segreto (una stringa) specifico del servizio OCI Generative AI. È possibile generare una chiave API e utilizzarla per accedere ai modelli di linguaggio di grandi dimensioni ospitati dal servizio.

Questa chiave API è diversa da una chiave API IAM OCI, che utilizza una coppia di chiavi pubblica/privata per fornire l'accesso alla tenancy OCI generale.

Come funziona la chiave API

Ogni chiave API OCI Generative AI include due segreti separati, ad esempio key-one e key-two. Entrambi i segreti sono stringhe uniche.

  • La chiave API viene creata tramite il servizio e il nome dell'intelligenza artificiale generativa e vengono impostate le date di scadenza per i due segreti.
  • Ogni segreto fornisce lo stesso livello di accesso ed è collegato alla stessa chiave API. È possibile utilizzare i segreti in modo intercambiabile nelle applicazioni.
  • Quando l'applicazione chiama un endpoint del modello AI generativa OCI, includere uno dei segreti nell'intestazione Autorizzazione.
Importante

La chiave API deve trovarsi nella stessa area del modello con cui si desidera utilizzarla.

Come utilizzare la chiave API

Puoi generare le chiavi API dell'AI generativa OCI e utilizzarle per accedere agli endpoint dei modelli linguistici di grandi dimensioni ospitati dal servizio AI generativa utilizzando l'API REST o l'SDK openai nativo. Di seguito è illustrata la procedura da utilizzare per le chiavi API.

  1. In OCI Generative AI, creare una chiave API in un'area supportata per il modello che si desidera utilizzare.
  2. In OCI IAM, Aggiungi autorizzazioni chiave API.
  3. Utilizzare questa chiave quando si chiama un modello supportato in un'area supportata utilizzando una delle seguenti opzioni:

Modelli supportati

Modelli per API completamenti chat
Modelli per API risposte
Importante

Chiamate esterne ai modelli xAI Grok

I modelli xAI Grok sono ospitati in un data center OCI, in una tenancy di cui è stato eseguito il provisioning per xAI. I modelli xAI Grok, a cui è possibile accedere tramite il servizio OCI Generative AI, sono gestiti da xAI.

Utilizzo di chiavi API con API REST

È possibile utilizzare le chiavi API nelle intestazioni dell'API REST e curl. Ecco gli endpoint che puoi utilizzare per l'API REST.

Endpoint supportati

Completamenti chat
https://inference.generativeai.<region-identifier>.oci.oraclecloud.com/20231130/actions/v1/chat/completions
Risposte
https://inference.generativeai.<region-identifier>.oci.oraclecloud.com/20231130/actions/v1/responses

Esempio con curl:

curl 
--location 'https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/v1/chat/completions' \
--header 'Authorization: Bearer sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
--header 'Content-Type: application/json' \
--data '{
"model": "xai.grok-4",
"messages": [
    {
    "role": "user",
    "content": "What's the capital of France?"
    }
]
}'

Utilizzo di chiavi API con SDK OpenAI

È possibile utilizzare le chiavi API con OpenAI SDK. Ecco gli endpoint che è possibile utilizzare per l'SDK OpenAI.

Endpoint supportati

Specificare base_url come 
https://inference.generativeai.<region-identifier>.oci.oraclecloud.com/20231130/actions/v1
Completamenti chat
Utilizzare questo metodo: client.chat.completions.create
Risposte
Utilizzare questo metodo: client.responses.create
Esempio
from openai import OpenAI
import os

API_KEY=os.getenv("OPENAI_API_KEY")

print(API_KEY)

client = OpenAI(
    api_key=API_KEY,
    base_url="https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/v1"
)

# Responses API
response = client.responses.create(
    model="openai.gpt-oss-120b",
    # model="xai.grok-3",
    # meta models are not supported with the Responses API
    input="Write a one-sentence bedtime story about a unicorn."
)
print(response)

# Completion API
response = client.chat.completions.create(
    # model="openai.gpt-oss-120b",
    # model="meta.llama-3.3-70b-instruct",
    model="xai.grok-3",
    messages=[{
        "role": "user", 
        "content": "Write a one-sentence bedtime story about a unicorn."
        }
    ]
)
print(response)
Di riferimento
repository GitHub Oracle

Aree supportate

Aree

Per gli SDK OpenAI, le aree OCI supportate da utilizzare con le chiavi API sono limitate a:

  • Germania (Centro) - Francoforte
  • India (Sud) - Hyderabad
  • Giappone centrale (Osaka)
  • Stati Uniti (Est) - Ashburn
  • Stati Uniti (Midwest) - Chicago
  • Stati Uniti (Ovest) - Phoenix

Per confermare le aree utilizzabili di un modello per il pacchetto OCI OpenAI, eseguire le seguenti operazioni.

  1. Aprire la scheda del modello nella documentazione sull'intelligenza artificiale generativa:
  2. Prendere nota delle aree elencate per il modello.
  3. Selezionare un'area per il modello visualizzata sia nelle aree disponibili del modello sia nelle sei aree OCI OpenAI precedenti.
  4. Verificare se il modello è disponibile nella modalità desiderata (on-demand o dedicata).

    Per l'accesso ai modelli in modalità dedicata, sono supportati endpoint sia pubblici che privati.

Rotazione o sostituzione di una chiave

Per ruotare una chiave API OCI Generative AI, puoi modificarne lo stato nella console OCI o utilizzando l'operazione SetApiKeyState con l'API. Di seguito è illustrata la procedura.

  1. Attivare il segreto standby. Attivare il segreto non utilizzato (ad esempio, due chiavi) e aggiornare le applicazioni per utilizzarlo.
  2. Verificare il failover. Confermare che le richieste vengano autenticate con il segreto appena attivato e che i carichi di lavoro continuino senza interruzioni.
  3. Revoca o disattiva il primo segreto.
    • Se si sospetta una perdita o è il momento di ritirare il primo segreto, revocarlo. Dopo la propagazione della modifica, le richieste che utilizzano il segreto revocato vengono rifiutate. La revoca di un segreto lo disabilita definitivamente e l'azione è irreversibile.
    • Se si prevede di riutilizzare il primo segreto, disattivarlo. Dopo la propagazione della modifica, le richieste che utilizzano il segreto disattivato vengono rifiutate fino a quando non viene riattivato.
    Suggerimento

    Disattivare un segreto per sospensione o indagine a breve termine. Revocare un segreto se è stato compromesso o se è necessario ritirarlo definitivamente.

Per i passi su come eseguire questi task, vedere Gestione delle chiavi API.

Importante

Copiare immediatamente segreti nuovi o rigenerati e memorizzarli in modo sicuro. appaiono solo una volta.

Procedure ottimali

Memorizza sempre i segreti chiave dell'API OCI Generative AI in un gestore di segreti approvato. Non impegnarli mai a controllarli o incorporarli nel codice lato client.

  • Utilizza la configurazione a due segreti per una rotazione fluida e senza tempi di inattività e imposta le scadenze per aggiornare regolarmente le chiavi.
  • Limitare l'accesso alle chiavi utilizzando i compartimenti e i criteri dei privilegi minimi.
  • Monitora l'uso, imposta avvisi e ruota immediatamente i tasti se rilevi attività sospette.

Gestione delle chiavi API

Dopo aver ottenuto l'autorizzazione IAM per la risorsa chiave API AI generativa OCI, è possibile gestire le chiavi API utilizzando le operazioni riportate di seguito.

Esempi su GitHub

Per un'esperienza pratica, vedere alcuni esempi nel repository Oracle GitHub.