View a markdown version of this page

API delle risposte - Amazon Bedrock
Regioni ed endpoint supportatiPrerequisitiScegli un modelloMigra da bedrock-mantle a bedrock-runtimeAPI di risposta

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

API delle risposte

Amazon Bedrock fornisce l'API OpenAI Responses sia sugli endpoint che sugli bedrock-runtime bedrock-mantle endpoint. Usalo bedrock-runtime per nuove applicazioni. bedrock-mantleUtilizzalo solo quando un modello o una funzionalità richiesti non sono disponibilibedrock-runtime.

Endpoint URL di base Quando utilizzarlo
bedrock-runtime (consigliato) https://bedrock-runtime.{region}.amazonaws.com/openai/v1 Nuove applicazioni e migrazioni quando sono supportati il modello richiesto e le funzionalità dell'API Responses.
bedrock-mantle(compatibilità) https://bedrock-mantle.{region}.api.aws/v1 Applicazioni e carichi di lavoro esistenti che richiedono Mantle-only supporto, ad esempio l'accesso dell'API Responses ai modelli GPT OSS, l'inferenza in background o gli strumenti lato server.
Nota

Attivobedrock-mantle, il prefisso del percorso varia in base al modello. La maggior parte dei modelli viene /v1 fornita sotto, come illustrato nella tabella precedente, ma alcuni vengono invece serviti sotto/openai/v1. Una richiesta che utilizza il prefisso sbagliato per un modello viene rifiutata con. model `<model-id>` isn't supported on this route Per confermare l'URL di base per un modello specifico, consultate la tabella Programmatic Access nella relativa scheda in. I modelli a colpo d'occhio

I due endpoint non supportano funzionalità identiche. Le richieste bedrock-runtime sono sempre sincrone, gli strumenti lato server non sono disponibili ed è supportato solo il progetto predefinito. Per il confronto completoEndpoint di inferenza supportati da Amazon Bedrock, vedi e per i dettagli di ogni differenza, vedi. Utilizzo dell'API Responses sull'endpoint bedrock-runtime

Importante

Quando usi l'OpenAISDK con Amazon Bedrock, devi indirizzarlo all'endpoint Amazon Bedrock, non all'endpoint. OpenAI Imposta le seguenti variabili di ambiente, scegliendo l'URL di base per l'endpoint che desideri:

# bedrock-runtime (recommended)
OPENAI_BASE_URL="https://bedrock-runtime.<your-region>.amazonaws.com/openai/v1"

# bedrock-mantle
OPENAI_BASE_URL="https://bedrock-mantle.<your-region>.api.aws/v1"

OPENAI_API_KEY="<your Bedrock API key>"

Non utilizzate la vostra chiave OpenAI API o l'URL di OpenAI base (https://api.openai.com/v1). Questi si connettono OpenAI direttamente, non ad Amazon Bedrock. Per creare una chiave API Amazon Bedrock, consultaChiavi API.

I vantaggi principali includono:

  • Inferenza asincrona: supporto per carichi di lavoro di inferenza a lunga durata tramite l'API Responses. Disponibile bedrock-mantle solo su.

  • Gestione delle conversazioni con stato: ricostruisci automaticamente il contesto senza passare manualmente la cronologia delle conversazioni ad ogni richiesta

  • Utilizzo semplificato degli strumenti: integrazione semplificata per flussi di lavoro agentici

  • Modalità di risposta flessibili: supporto per risposte in streaming e non in streaming

  • Migrazione semplice: compatibile con le basi di codice OpenAI SDK esistenti

Ogni endpoint è regolato da un proprio set di quote. Per il traffico di Responses attivobedrock-runtime, si applicano le quote di token al minuto e di token al giorno del modello, che vengono condivise con le altre API di inferenza su quell'endpoint: vedi. Quote per l'endpoint bedrock-runtime Per bedrock-mantle, consulta Quote per l'endpoint del substrato roccioso.

Regioni ed endpoint supportati

Sull'bedrock-runtimeendpoint, l'API Responses è disponibile Regione AWS ovunque sia disponibile l'endpoint, incluse le regioni AWS GovCloud (Stati Uniti). Per l'elenco, consulta Disponibilità regionale per endpoint. I modelli che supportano l'API su ciascun endpoint sono elencati in. Disponibilità degli endpoint

L'bedrock-mantleendpoint è disponibile in un sottoinsieme di questi. Regione AWS Per le regioni che supportano ogni endpoint, vedi. Disponibilità regionale per endpoint Per l'URL di base da utilizzare con una regione, consultaEndpoint di inferenza supportati da Amazon Bedrock.

Prerequisiti

Prima di utilizzare le OpenAI API, assicurati di disporre di quanto segue:

  • Autenticazione: puoi autenticarti utilizzando:

    • Chiave API Amazon Bedrock (richiesta per OpenAI SDK)

    • AWS credenziali (supportate per le richieste HTTP)

  • OpenAISDK (opzionale) — Installa l'SDK OpenAI Python se usi le richieste. SDK-based

  • Variabili di ambiente: imposta le seguenti variabili di ambiente:

    • OPENAI_API_KEY— Imposta sulla tua chiave API Amazon Bedrock

    • OPENAI_BASE_URL— Imposta sull'endpoint Amazon Bedrock per la tua regione (ad esempio, https://bedrock-runtime.us-east-1.amazonaws.com/openai/v1 o) https://bedrock-mantle.us-east-1.api.aws/v1

  • Autorizzazioni: le azioni necessarie dipendono dall'endpoint. Attivatobedrock-mantle, l'inferenza autorizza. bedrock-mantle:CreateInference Attivabedrock-runtime, autorizza bedrock:InvokeModel sia l'obiettivo di inferenza che il progetto predefinito dell'account, mentre la gestione delle risposte archiviate autorizza bedrock:GetInvoke e su quel progetto. bedrock:CancelInvoke bedrock:DeleteInvoke Per esempi di policy, consulta Prerequisiti per l’esecuzione dell’inferenza del modello.

Scegli un modello

Il supporto di modelli e API differisce a seconda degli endpoint. Ad esempiobedrock-runtime, scegli un modello la cui scheda modello elenchi l'API Responses supportata su quell'endpoint. Le richieste per i modelli OpenAI GPT a peso chiuso devono indicare un profilo di inferenza definito dal sistema, ad esempio us.openai.gpt-5.6-sol oglobal.openai.gpt-5.6-sol, anziché l'ID del modello di base.

Importante

bedrock-runtimenon implementa l' OpenAI-compatibleGET /modelsoperazione, quindi client.models.list() e GET /openai/v1/models non funziona su quell'endpoint. Usa il piano di controllo ListFoundationModelse ListInferenceProfilesle operazioni di Amazon Bedrock e consulta le schede modello per il supporto API specifico I modelli a colpo d'occhio per gli endpoint e gli ID dei profili di inferenza. Per alcuni esempi, consulta Ottieni l'elenco dei modelli.

Nota

I modelli GPT OSS supportano Chat Completions, Converse e Invoke onbedrock-runtime, ma lì non supportano l'API Responses. Per utilizzare interamente sia Responses che Chat Completionsbedrock-runtime, scegli un modello che elenchi entrambe le API supportate su quell'endpoint. Per utilizzare l'API Responses con GPT OSS, usa. bedrock-mantle

Elenca i modelli su bedrock-mantle

L'API OpenAI-compatible Models è disponibile su. bedrock-mantle Per i dettagli completi sull'API, consulta la documentazione OpenAI dei modelli. Per elencare i modelli su quell'endpoint, scegli la scheda relativa al tuo metodo preferito, quindi segui i passaggi:

OpenAI SDK (Python)
# List all available models using the OpenAI SDK
# Requires OPENAI_API_KEY and OPENAI_BASE_URL environment variables

from openai import OpenAI

client = OpenAI()

models = client.models.list()

for model in models.data:
    print(model.id)
HTTP request

Effettua una richiesta GET a/v1/models:

# List all available models
# Requires OPENAI_API_KEY and OPENAI_BASE_URL environment variables

curl -X GET $OPENAI_BASE_URL/models \
   -H "Authorization: Bearer $OPENAI_API_KEY"

Migra da bedrock-mantle a bedrock-runtime

Prima di spostare un carico di lavoro dell'API Responses, verifica che il relativo modello e le funzionalità richieste siano supportati. bedrock-runtime Quindi apporta le seguenti modifiche:

Impostazione mantello roccioso bedrock-runtime
URL di base https://bedrock-mantle.{region}.api.aws/v1 https://bedrock-runtime.{region}.amazonaws.com/openai/v1
Valore del modello ID del modello, ad esempio openai.gpt-5.6-sol ID del modello di runtime o del profilo di inferenza del sistema, ad esempio global.openai.gpt-5.6-sol
Scoperta del modello GET /models o client.models.list() ListFoundationModelse modelli di carte ListInferenceProfiles
Progetto Progetto predefinito o creato dal cliente Solo progetto predefinito

Richieste di test che utilizzano l'elaborazione in background, gli strumenti lato server, i profili di inferenza delle applicazioni o l'ereditarietà del modelloprevious_response_id, poiché tali comportamenti sono diversi. bedrock-runtime Per l'elenco completo, consulta Utilizzo dell'API Responses sull'endpoint bedrock-runtime.

API di risposta

L'API Responses fornisce una gestione statica delle conversazioni con supporto per lo streaming e le interazioni a turni multipli. L'bedrock-mantleendpoint supporta anche l'elaborazione in background. Per i dettagli completi sull'API, consulta la documentazione di OpenAI Responses.

Nota

Non tutti i modelli supportano l'API Responses su entrambi gli endpoint. Controlla la tabella API specifica dell'endpoint sulla scheda del modello prima di scegliere un modello. La tabella di compatibilità riportata in Compatibilità delle API basso riassume le funzionalità del modello tra gli endpoint, ma non implica che un'API sia disponibile su ogni endpoint.

In che modo l'API Responses memorizza lo stato delle conversazioni

L'API Responses può utilizzare lo stato memorizzato per abilitare conversazioni a turni multipli e consentire di fare riferimento ai turni precedenti tramite il previous_response_id parametro. L'archiviazione è abilitata per impostazione predefinita, ma può essere disabilitata su richiesta tramite il store parametro. Le risposte archiviate rientrano nell'ambito del progetto. Una risposta di un progetto non può essere utilizzata come risposta precedente o letta in un secondo progetto. Per ulteriori informazioni sui progetti, vedereProgetti (OpenAI-compatible).

  • Quando store è true (impostazione predefinita), Amazon Bedrock conserva la risposta, inclusi input e output, per 30 giorni. Durante questa finestra puoi concatenare le richieste di follow-up inviando previous_response_id e recuperando la risposta con GET /v1/responses/{id} on o onbedrock-mantle. GET /openai/v1/responses/{id} bedrock-runtime Dopo 30 giorni, la risposta viene eliminata automaticamente e non è più recuperabile.

  • In store tal casofalse, Amazon Bedrock non conserva alcun dato della richiesta o della risposta. Il previous_response_id parametro non può essere utilizzato per continuare la conversazione.

Il valore predefinito true deve corrispondere alla specifica dell'API OpenAI Responses. I clienti che non desiderano che Amazon Bedrock conservi i dati delle conversazioni devono store impostarla esplicitamente false su ogni richiesta o impostare la modalità di conservazione dei dati dell'account sunone, che rifiuta una risposta esplicita. store=true Per ulteriori informazioni, consulta Conservazione dei dati.

I dati archiviati vengono crittografati quando sono inattivi e riconducibili alla risorsa Project dell'account chiamante. AWS I dati vengono archiviati esclusivamente per soddisfare le richieste dell'utente e non vengono utilizzati o conservati per altri scopi. Sìbedrock-mantle, vengono conservati nella cartella a cui è stata inviata Regione AWS la richiesta. Sìbedrock-runtime, una richiesta che utilizza l'inferenza interregionale può essere elaborata in un'altra regione e la risposta viene archiviata nella regione che l'ha elaborata Regione AWS, in modo che una richiesta che utilizza un profilo di inferenza globale possa archiviare i dati in qualsiasi regione commerciale verso cui viene indirizzata il profilo. Se hai requisiti di residenza dei dati, utilizza un profilo di inferenza geografica anziché uno globale.

Richiesta di base

Per creare una risposta, scegli un esempio per il tuo endpoint. Gli bedrock-runtime esempi utilizzano un profilo di inferenza di sistema globale. Utilizza invece un profilo geografico se hai requisiti di residenza dei dati.

bedrock-runtime: OpenAI SDK (Python)
from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="global.openai.gpt-5.6-sol",
    input="Can you explain the features of Amazon Bedrock?"
)
print(response)
bedrock-runtime: HTTP request

Effettua una richiesta POST a/openai/v1/responses:

curl -X POST "$OPENAI_BASE_URL/responses" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer $OPENAI_API_KEY" \
   -d '{
    "model": "global.openai.gpt-5.6-sol",
    "input": "Can you explain the features of Amazon Bedrock?"
}'
bedrock-mantle: OpenAI SDK (Python)
# Create a basic response using the OpenAI SDK
# Requires OPENAI_API_KEY and OPENAI_BASE_URL environment variables

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="openai.gpt-oss-120b",
    input=[
        {"role": "user", "content": "Hello! How can you help me today?"}
    ]
)

print(response)
bedrock-mantle: HTTP request

Effettua una richiesta POST a/v1/responses:

# Create a basic response
# Requires OPENAI_API_KEY and OPENAI_BASE_URL environment variables

curl -X POST $OPENAI_BASE_URL/responses \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer $OPENAI_API_KEY" \
   -d '{
    "model": "openai.gpt-oss-120b",
    "input": [
        {"role": "user", "content": "Hello! How can you help me today?"}
    ]
}'

Risposte in streaming

Per ricevere gli eventi di risposta in modo incrementale, scegli un esempio per il tuo endpoint.

bedrock-runtime: OpenAI SDK (Python)
from openai import OpenAI

client = OpenAI()

stream = client.responses.create(
    model="global.openai.gpt-5.6-sol",
    input="Tell me a story",
    stream=True
)

for event in stream:
    print(event)
bedrock-runtime: HTTP request

Effettua una richiesta POST a /openai/v1/responses with stream set to: true

curl -X POST "$OPENAI_BASE_URL/responses" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer $OPENAI_API_KEY" \
   -d '{
    "model": "global.openai.gpt-5.6-sol",
    "input": "Tell me a story",
    "stream": true
}'
bedrock-mantle: OpenAI SDK (Python)
# Stream response events incrementally using the OpenAI SDK
# Requires OPENAI_API_KEY and OPENAI_BASE_URL environment variables

from openai import OpenAI

client = OpenAI()

stream = client.responses.create(
    model="openai.gpt-oss-120b",
    input=[{"role": "user", "content": "Tell me a story"}],
    stream=True
)

for event in stream:
    print(event)
bedrock-mantle: HTTP request

Effettua una richiesta POST a /v1/responses with stream set totrue:

# Stream response events incrementally
# Requires OPENAI_API_KEY and OPENAI_BASE_URL environment variables

curl -X POST $OPENAI_BASE_URL/responses \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer $OPENAI_API_KEY" \
   -d '{
    "model": "openai.gpt-oss-120b",
    "input": [
        {"role": "user", "content": "Tell me a story"}
    ],
    "stream": true
}'

Utilizzo dell'API Responses sull'endpoint bedrock-runtime

L'API Responses on bedrock-runtime utilizza lo stesso formato di richiesta e risposta di onbedrock-mantle, quindi l'OpenAISDK funziona con entrambi i formati. Ciò che cambia è l'URL di base, gli ID del modello, le autorizzazioni e un numero limitato di comportamenti descritti in questa sezione.

URL e percorsi di base

Imposta il tuo URL di base suhttps://bedrock-runtime.region.amazonaws.com/openai/v1. L'API viene servita sui seguenti percorsi:

  • POST /openai/v1/responses— creare una risposta.

  • GET /openai/v1/responses/{id}— recupera una risposta memorizzata.

  • POST /openai/v1/responses/{id}/cancel— annullare una risposta ancora in corso.

  • DELETE /openai/v1/responses/{id}— eliminare una risposta memorizzata.

ID dei modelli

Assegnate un nome a un profilo di inferenza interregionale come modello, non a un ID del modello di base. I modelli OpenAI GPT utilizzano i global. profili us. and nelle regioni commerciali e i us-gov. profili nelle regioni AWS GovCloud (Stati Uniti), ad esempio. us.openai.gpt-5.6-sol In-Region l'inferenza non è disponibile per questi modelli su questo endpoint. Per l'ID del profilo di ogni modello, consulta la relativa scheda del modello in eI modelli a colpo d'occhio, per sapere come funziona il routing, consulta. Indirizza le richieste di inferenza del modello attraverso Regioni AWS con inferenza interregionale

Autorizzazioni

La creazione di una risposta autorizza due risorse: bedrock:InvokeModel (obedrock:InvokeModelWithResponseStream) sull'obiettivo di inferenza, come qualsiasi richiesta di inferenza, e bedrock:InvokeModel sul progetto predefinito del tuo account. Il recupero, l'annullamento e l'eliminazione di una risposta memorizzata autorizzano, rispettivamentebedrock:GetInvoke, bedrock:CancelInvoke ciascuna di esse sul progetto. bedrock:DeleteInvoke Gli ID di risposta individuali non sono risorse IAM.

Due chiavi di condizione consentono a una politica su una risorsa di vincolare l'altra. L'autorizzazione inference-target, così come l'autorizzazione del progetto bedrock:ProjectArnbedrock:ModelArn, riporta in base al profilo di inferenza o al modello di base denominato dalla richiesta, e mai i modelli di destinazione a cui indirizza un profilo interregionale. Per esempi di policy, consulta Prerequisiti per l’esecuzione dell’inferenza del modello.

Differenze di comportamento

  • Le richieste sono sempre sincrone. background=trueviene rifiutato con un errore 400. Il store parametro non viene modificato e mantiene l'impostazione predefinitatrue, quindi le conversazioni a più turni memorizzate funzionano normalmente.

  • modelè obbligatorio per ogni richiesta, inclusa una che fornisce. previous_response_id Ciò differisce dalla specifica dell'API OpenAI Responses e da bedrock-mantle dove il modello può essere omesso ed ereditato dalla risposta precedente. Il modello fa parte dell'oggetto per cui è autorizzata la richiesta, quindi deve essere nominato nella richiesta stessa.

  • Server-side l'uso degli strumenti e gli strumenti preconfigurati non sono disponibili, inclusa la ricerca sul web. Client-side l'uso degli strumenti funziona su entrambi gli endpoint.

  • È supportato solo il progetto predefinito. L'OpenAI-Projectintestazione è accettata solo come ARN di progetto predefinito default o come ARN; qualsiasi altro valore viene rifiutato. Consulta Progetti (OpenAI-compatible).

  • I profili di inferenza delle applicazioni non sono supportati. Una richiesta che ne nomina uno come obiettivo di inferenza viene rifiutata con un errore 400. I profili di inferenza di sistema, geografici e globali funzionano normalmente.

  • I guardrail sono supportati. Imposta le intestazioni X-Amzn-Bedrock-GuardrailIdentifier e X-Amzn-Bedrock-GuardrailVersion richiedi. Con l'OpenAISDK, trasmetti questi valori. extra_headers Per ulteriori informazioni, consulta Testare il guardrail.

  • Una risposta memorizzata appartiene a chi l' Regione AWS ha fornita. Il recupero, l'annullamento o l'eliminazione e la continuazione della conversazione con previous_response_id essa sono tutti gestiti da quella regione. Un ID di risposta che non può essere trovato, perché non è mai esistito, appartiene a un altro account o non è mai stato archiviato, restituisce lo stesso errore 404 in ogni caso.

Monitoraggio e costi

Poiché ogni richiesta è sincrona, le CloudWatch metriche e la registrazione delle chiamate dei modelli funzionano per l'API Responses allo stesso modo per le altre API di inferenza su questo endpoint, incluse le richieste di streaming. L'utilizzo viene attribuito all'obiettivo di inferenza, esattamente come avviene per Converse e InvokeModel il progetto predefinito non è mai il punto di riferimento della fatturazione. Consulta Monitora l'utilizzo e i costi in Amazon Bedrock.