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-mantle`Utilizzalo solo quando un modello o una funzionalità richiesti non sono disponibili`bedrock-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** Attivo`bedrock-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 `` 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](model-cards.md) 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 completo[Endpoint di inferenza supportati da Amazon Bedrock](endpoints.md), vedi e per i dettagli di ogni differenza, vedi. [Utilizzo dell'API Responses sull'endpoint bedrock-runtime](#bedrock-mantle-responses-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..amazonaws.com/openai/v1" # bedrock-mantle OPENAI_BASE_URL="https://bedrock-mantle..api.aws/v1" OPENAI_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, consulta[Chiavi API](api-keys.md). 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 attivo`bedrock-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](quotas-runtime.md) Per `bedrock-mantle`, consulta [Quote per l'endpoint del substrato roccioso](quotas-mantle.md). ## Regioni ed endpoint supportati Sull'`bedrock-runtime`endpoint, 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](endpoints-region-availability.md). I modelli che supportano l'API su ciascun endpoint sono elencati in. [Disponibilità degli endpoint](models-endpoint-availability.md) L'`bedrock-mantle`endpoint è disponibile in un sottoinsieme di questi. Regione AWS Per le regioni che supportano ogni endpoint, vedi. [Disponibilità regionale per endpoint](endpoints-region-availability.md) Per l'URL di base da utilizzare con una regione, consulta[Endpoint di inferenza supportati da Amazon Bedrock](endpoints.md). ## 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. Attivato`bedrock-mantle`, l'inferenza autorizza. `bedrock-mantle:CreateInference` Attiva`bedrock-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](inference-prereq.md). ## Scegli un modello Il supporto di modelli e API differisce a seconda degli endpoint. Ad esempio`bedrock-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` o`global.openai.gpt-5.6-sol`, anziché l'ID del modello di base. **Importante** `bedrock-runtime`non implementa l' OpenAI-compatible`GET /models`operazione, quindi `client.models.list()` e `GET /openai/v1/models` non funziona su quell'endpoint. Usa il piano di controllo [ListFoundationModels](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_ListFoundationModels.html)e [ListInferenceProfiles](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_ListInferenceProfiles.html)le operazioni di Amazon Bedrock e consulta le schede modello per il supporto API specifico [I modelli a colpo d'occhio](model-cards.md) per gli endpoint e gli ID dei profili di inferenza. Per alcuni esempi, consulta [Ottieni l'elenco dei modelli](models-get-info.md). **Nota** I modelli GPT OSS supportano Chat Completions, Converse e Invoke on`bedrock-runtime`, ma lì non supportano l'API Responses. Per utilizzare interamente sia Responses che Chat Completions`bedrock-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](https://developers.openai.com/api/reference/resources/models). 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 modello`previous_response_id`, poiché tali comportamenti sono diversi. `bedrock-runtime` Per l'elenco completo, consulta [Utilizzo dell'API Responses sull'endpoint bedrock-runtime](#bedrock-mantle-responses-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-mantle`endpoint supporta anche l'elaborazione in background. Per i dettagli completi sull'API, consulta la [documentazione di OpenAI Responses](https://developers.openai.com/api/reference/resources/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](models-api-compatibility.md) 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, vedere[Progetti (OpenAI-compatible)](projects.md). + 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 on`bedrock-mantle`. `GET /openai/v1/responses/{id}` `bedrock-runtime` Dopo 30 giorni, la risposta viene eliminata automaticamente e non è più recuperabile. + In `store` tal caso`false`, 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 su`none`, che rifiuta una risposta esplicita. `store=true` Per ulteriori informazioni, consulta [Conservazione dei dati](data-retention.md). 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](cross-region-inference.md) 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 to`true`: ``` # 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 on`bedrock-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 su`https://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 e[I modelli a colpo d'occhio](model-cards.md), per sapere come funziona il routing, consulta. [Indirizza le richieste di inferenza del modello attraverso Regioni AWS con inferenza interregionale](cross-region-inference.md) **Autorizzazioni** La creazione di una risposta autorizza due risorse: `bedrock:InvokeModel` (o`bedrock: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, rispettivamente`bedrock: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:ProjectArn``bedrock: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](inference-prereq.md). **Differenze di comportamento** + **Le richieste sono sempre sincrone.** `background=true`viene rifiutato con un errore 400. Il `store` parametro non viene modificato e mantiene l'impostazione predefinita`true`, 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](web-search.md). Client-side l'uso degli strumenti funziona su entrambi gli endpoint. + **È supportato solo il progetto predefinito.** L'`OpenAI-Project`intestazione è accettata solo come ARN di progetto predefinito `default` o come ARN; qualsiasi altro valore viene rifiutato. Consulta [Progetti (OpenAI-compatible)](projects.md). + **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](guardrails.md) 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](guardrails-test.md). + **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](cost-management.md).