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à.
# Inferenza utilizzando l'API Converse
L'API Converse è disponibile solo sull'endpoint. `bedrock-runtime`
L’API Converse per Amazon Bedrock consente di creare applicazioni conversazionali che inviano e ricevono messaggi verso e da un modello Amazon Bedrock. È possibile ad esempio creare un chatbot che gestisca una conversazione a più turni e utilizzi una personalizzazione del tono o della persona adatta alle esigenze specifiche, come un utile assistente di supporto tecnico.
Per utilizzare l'ConverseAPI, si utilizzano le operazioni [Converse](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html) o [ConverseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStream.html)(per lo streaming delle risposte) per inviare messaggi a un modello. È possibile utilizzare le operazioni di inferenza di base esistenti ([InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html)o [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html)) per le applicazioni di conversazione. Si consiglia tuttavia di utilizzare l’API Converse in quanto è un’API coerente in grado di funzionare con tutti i modelli Amazon Bedrock che supportano i messaggi. Ciò significa che è possibile scrivere il codice una sola volta e utilizzarlo con modelli diversi. Se un modello ha parametri di inferenza unici, l’API Converse consente anche di passare tali parametri in una struttura specifica del modello.
L’API Converse può essere utilizzata per implementare l’[uso di strumenti](tool-use.md) e di [guardrail](guardrails-use-converse-api.md) nelle tue applicazioni.
**Nota**
Con i modelli Mistral AI and Meta, l’API Converse integra l’input dell’utente in un tipo di prompt specifico del modello che abilita le conversazioni.
Le restrizioni si applicano alle seguenti operazioni:`InvokeModel`, `InvokeModelWithResponseStream``Converse`, e`ConverseStream`. Per i dettagli, consulta [Restrizioni API](inference-api-restrictions.md).
Per esempi di codice, consulta le sezioni seguenti:
+ Esempi Python per questo argomento: [Converse Esempi di APIEsempi di API Converse (spostati)](conversation-inference-examples.md)
+ Vari linguaggi e modelli: [Esempi di codice per Amazon Bedrock Runtime utilizzando AWS SDK](service_code_examples_bedrock-runtime.md)
+ Tutorial Java: [una guida per gli sviluppatori Java alla nuova API Converse di Bedrock](https://community.aws/content/2hUiEkO83hpoGF5nm3FWrdfYvPt/amazon-bedrock-converse-api-java-developer-guide)
+ JavaScript tutorial — [Una guida per sviluppatori alla nuova Converse API di Bedrock](https://community.aws/content/2dtauBCeDa703x7fDS9Q30MJoBA/amazon-bedrock-converse-api-developer-guide)
## Utilizzo di Converse "Hello, World\!"
Per utilizzare l’API Converse, vengono chiamate le operazioni `Converse` o `ConverseStream` per inviare messaggi a un modello. Per chiamare `Converse`, è richiesta l’autorizzazione per l’operazione `bedrock:InvokeModel`. Per chiamare `ConverseStream`, è richiesta l’autorizzazione per l’operazione `bedrock:InvokeModelWithResponseStream`.
### Richiesta
Quando si effettua una richiesta [Converse](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html) con un [endpoint di runtime Amazon Bedrock](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#br-rt), è possibile includere i seguenti campi:
+ **modelId**: parametro obbligatorio nell’intestazione che consente di specificare la risorsa da utilizzare per l’inferenza.
+ I seguenti campi consentono di personalizzare il prompt:
+ **messages**: consente di specificare il contenuto e il ruolo dei prompt.
+ **system**: consente di specificare i prompt di sistema che definiscono le istruzioni o il contesto per il modello.
+ **inferenceConfig**: consente di specificare i parametri di inferenza comuni a tutti i modelli. Parametri di inferenza che influenzano la generazione della risposta.
+ **aggiuntivo ModelRequestFields**: consente di specificare i parametri di inferenza specifici del modello con cui si esegue l'inferenza.
+ **promptVariables** (se si utilizza un prompt di Gestione prompt): consente di definire le variabili da usare nel prompt e i valori da assegnarvi.
+ I seguenti campi consentono di personalizzare la modalità di restituzione della risposta:
+ **guardrailConfig**: consente di includere un guardrail da applicare all’intero prompt.
+ **toolConfig**: consente di includere uno strumento che aiuti un modello a generare risposte.
+ **aggiuntivo ModelResponseFieldPaths** — Utilizzate questo campo per specificare i campi da restituire come oggetto puntatore JSON.
+ **ServiceTier**: utilizza questo campo per specificare il livello di servizio per una richiesta particolare
+ **requestMetadata**: consente di includere metadati che si possono filtrare quando si utilizzano log di invocazione.
**Nota**
Le seguenti restrizioni si applicano quando si utilizza un prompt di Gestione prompt con `Converse` o `ConverseStream`:
Non è possibile includere i campi `additionalModelRequestFields`, `inferenceConfig`, `system` o `toolConfig`.
Se si include il campo `messages`, i messaggi vengono aggiunti dopo i messaggi definiti nel prompt.
Se si include il campo `guardrailConfig`, il guardrail viene applicato all’intero prompt. Se includi `guardContent` blocchi nel [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html)campo, il guardrail verrà applicato solo a quei blocchi.
Per ulteriori informazioni su una campo nel corpo della richiesta `Converse`, espandi la sezione corrispondente:
#### messages
Il campo `messages` è un array di oggetti [Message](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html), ciascuno dei quali definisce un messaggio tra l’utente e il modello. Un oggetto `Message` contiene i campi seguenti:
+ **role**: definisce se il messaggio proviene da `user` (prompt inviato al modello) o `assistant` (risposta del modello).
+ **content**: definisce il contenuto del prompt.
**Nota**
Amazon Bedrock non archivia testo, immagini o documenti forniti dall’utente come contenuto. I dati vengono utilizzati solo per generare la risposta.
È possibile mantenere il contesto della conversazione includendone tutti i messaggi nelle richieste `Converse` successive e utilizzando il campo `role` per specificare se il messaggio proviene dall’utente o dal modello.
Il `content` campo è mappato su una serie di [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html)oggetti. All'interno di ciascuno [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html), puoi specificare uno dei seguenti campi (per vedere quali modelli supportano quali blocchi, consulta [i modelli in sintesi](model-cards.md)):
------
#### [ text ]
Il campo `text` viene mappato a una stringa che specifica il prompt. Il `text` campo viene interpretato insieme ad altri campi specificati nello stesso [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html).
Quanto segue mostra un oggetto [Message](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) con una `content` matrice contenente solo un testo [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html):
```
{
"role": "user",
"content": [
{
"text": "{{string}}"
}
]
}
```
------
#### [ image ]
Il `image` campo è mappato su un [ImageBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ImageBlock.html). Passa i byte non elaborati, con codifica base64, per un’immagine nel campo `bytes`. Se si utilizza un AWS SDK, non è necessario codificare i byte in base64.
Se si esclude il campo `text`, il modello descrive l’immagine.
Quanto segue mostra un esempio di oggetto [Message](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) con un `content` array contenente solo un'immagine: [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html)
```
{
"role": "user",
"content": [
{
"image": {
"format": "png",
"source": {
"bytes": "{{image in bytes}}"
}
}
}
]
}
```
È anche possibile specificare un URI Amazon S3 anziché passare i byte direttamente nel corpo della richiesta. Di seguito viene mostrato un oggetto `Message` di esempio con un array di contenuti in cui è inclusa l’origine passata tramite un URI Amazon S3.
```
{
"role": "user",
"content": [
{
"image": {
"format": "png",
"source": {
"s3Location": {
"uri": "s3://amzn-s3-demo-bucket/myImage",
"bucketOwner": "111122223333"
}
}
}
}
]
}
```
------
#### [ document ]
Il `document` campo è mappato su un [DocumentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_DocumentBlock.html). Se si include un oggetto `DocumentBlock`, verificare che la richiesta sia conforme alle seguenti restrizioni:
+ Nel campo `content` dell’oggetto [Message](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html), è necessario includere anche un campo `text` con un prompt relativo al documento.
+ Passa i byte non elaborati, con codifica base64, per il documento nel campo `bytes`. Se utilizzi un SDK AWS , non è necessario utilizzare la codifica base64 per i byte.
+ Il campo `name` può contenere solo i seguenti caratteri:
+ Caratteri alfanumerici
+ Caratteri di spaziatura (non più di uno in una stessa riga)
+ Trattini
+ Parentesi
+ Parentesi quadre
**Nota**
Il campo `name` è vulnerabile alle iniezioni di prompt, poiché il modello potrebbe inavvertitamente interpretarle come istruzioni. Pertanto, consigliamo di specificare un nome neutro.
Quando si utilizza un documento, è possibile abilitare il tag `citations`, che fornisce citazioni specifiche del documento nella risposta alla chiamata API. Consulta l'[DocumentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_DocumentBlock.html)API per maggiori dettagli.
Quanto segue mostra un oggetto [Message](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) di esempio con un `content` array contenente solo un documento [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html)e un testo [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html)di accompagnamento obbligatorio.
```
{
"role": "user",
"content": [
{
"text": "{{string}}"
},
{
"document": {
"format": "pdf",
"name": "MyDocument",
"source": {
"bytes": "{{document in bytes}}"
}
}
}
]
}
```
È anche possibile specificare un URI Amazon S3 anziché passare i byte direttamente nel corpo della richiesta. Di seguito viene mostrato un oggetto `Message` di esempio con un array di contenuti in cui è inclusa l’origine passata tramite un URI Amazon S3.
```
{
"role": "user",
"content": [
{
"text": "{{string}}"
},
{
"document": {
"format": "pdf",
"name": "MyDocument",
"source": {
"s3Location": {
"uri": "s3://amzn-s3-demo-bucket/myDocument",
"bucketOwner": "111122223333"
}
}
}
}
]
}
```
------
#### [ video ]
Il `video` campo è mappato a un [VideoBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_VideoBlock.html)oggetto. Passa i byte non elaborati nel campo `bytes` con codifica base64. Se si utilizza l' AWS SDK, non è necessario codificare i byte in base64.
Se non si include il campo `text`, il modello descrive il video.
Quanto segue mostra un oggetto [Message](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) di esempio con un `content` array contenente solo un video. [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html)
```
{
"role": "user",
"content": [
{
"video": {
"format": "mp4",
"source": {
"bytes": "{{video in bytes}}"
}
}
}
]
}
```
È anche possibile specificare un URI Amazon S3 anziché passare i byte direttamente nel corpo della richiesta. Di seguito viene mostrato un oggetto `Message` di esempio con un array di contenuti in cui è inclusa l’origine passata tramite un URI Amazon S3.
```
{
"role": "user",
"content": [
{
"video": {
"format": "mp4",
"source": {
"s3Location": {
"uri": "s3://amzn-s3-demo-bucket/myVideo",
"bucketOwner": "111122223333"
}
}
}
}
]
}
```
**Nota**
Il ruolo assunto deve disporre dell’autorizzazione `s3:GetObject` per l’URI Amazon S3. Il campo `bucketOwner` è facoltativo, ma è necessario specificare se l’account che effettua la richiesta non possiede il bucket in cui si trova l’URI Amazon S3. Per ulteriori informazioni, consulta [Configurare l’accesso a bucket Amazon S3](s3-bucket-access.md).
------
#### [ cachePoint ]
È possibile aggiungere punti di controllo della cache come blocco in un messaggio insieme a un prompt di accompagnamento utilizzando `cachePoint` i campi per utilizzare la memorizzazione nella cache dei prompt. Il caching dei prompt è una funzionalità che consente di iniziare a memorizzare nella cache il contesto delle conversazioni per ottenere risparmi in termini di costi e latenza. Per ulteriori informazioni, consulta [Caching dei prompt per un’inferenza del modello più rapida](prompt-caching.md).
Di seguito viene illustrato un oggetto [Message](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) di esempio con un `content` array contenente un documento [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html)e il testo di accompagnamento obbligatorio [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html), nonché un **CachePoint che aggiunge sia il contenuto del documento che quello del testo alla cache**.
```
{
"role": "user",
"content": [
{
"text": "{{string}}"
},
{
"document": {
"format": "pdf",
"name": "string",
"source": {
"bytes": "{{document in bytes}}"
}
}
},
{
"cachePoint": {
"type": "default"
}
}
]
}
```
------
#### [ guardContent ]
Il `guardContent` campo è mappato a un oggetto. [GuardrailConverseContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailConverseContentBlock.html) È possibile utilizzare questo campo per specificare un input che deve essere valutato dal guardrail definito nel campo `guardrailConfig`. Se non si specifica questo campo, il guardrail valuta tutti i messaggi nel corpo della richiesta. In un oggetto `GuardBlock`, si possono passare i seguenti tipi di contenuto:
+ **text** — Quanto segue mostra un esempio di oggetto [Message](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) con un `content` array contenente solo un testo [GuardrailConverseContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailConverseContentBlock.html):
```
{
"role": "user",
"content": [
{
"text": "Tell me what stocks to buy.",
"qualifiers": [
"guard_content"
]
}
]
}
```
Si definisce il testo da valutare e si includono i qualificatori da utilizzare per la [correlazione contestuale](guardrails-contextual-grounding-check.md).
+ **image** — Quanto segue mostra un oggetto [Message](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) con un `content` array contenente solo un'immagine [GuardrailConverseContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailConverseContentBlock.html):
```
{
"role": "user",
"content": [
{
"format": "png",
"source": {
"bytes": "{{image in bytes}}"
}
}
]
}
```
Si specifica il formato dell’immagine e si definisce l’immagine in byte.
Per ulteriori informazioni sull’utilizzo dei guardrail, consulta [Rilevare e filtrare contenuti dannosi utilizzando Guardrail per Amazon Bedrock](guardrails.md).
------
#### [ reasoningContent ]
Il `reasoningContent` campo è mappato su un [ReasoningContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ReasoningContentBlock.html). Questo blocco include contenuti riguardanti il ragionamento che è stato eseguito dal modello per generare la risposta nell’oggetto `ContentBlock` associato.
Di seguito viene mostrato un oggetto `Message` con un array `content` contenente solo un oggetto `ReasoningContentBlock` e un oggetto `ContentBlock` testo associato.
```
{
"role": "user",
"content": [
{
"text": "{{string}}"
},
{
"reasoningContent": {
"reasoningText": {
"text": "{{string}}",
"signature": "{{string}}"
}
"redactedContent": "{{base64-encoded binary data object}}"
}
}
]
}
```
L’oggetto `ReasoningContentBlock` contiene il ragionamento utilizzato per generare il contenuto associato nel campo `reasoningText`, oltre a qualsiasi contenuto del ragionamento crittografato dal provider del modello per motivi di affidabilità e sicurezza nel campo `redactedContent`.
Nel campo `reasoningText`, i campi `text` descrivono il ragionamento. Il campo `signature` è un hash di tutti i messaggi della conversazione ed è una protezione contro la manomissione del ragionamento utilizzato dal modello. È necessario includere la firma e tutti i messaggi precedenti nelle richieste `Converse` successive. Se uno qualsiasi dei messaggi viene modificato, la risposta genera un errore.
------
#### [ toolUse ]
Contiene informazioni su uno strumento che il modello può utilizzare. Per ulteriori informazioni, consulta [Utilizzo di uno strumento per completare una risposta al modello Amazon Bedrock](tool-use.md).
------
#### [ toolResult ]
Contiene informazioni sul risultato ottenuto dal modello con l’utilizzo di uno strumento. Per ulteriori informazioni, consulta [Utilizzo di uno strumento per completare una risposta al modello Amazon Bedrock](tool-use.md).
------
Nell’esempio `messages` seguente, l’utente richiede un elenco di tre brani pop e il modello genera un elenco di brani.
```
[
{
"role": "user",
"content": [
{
"text": "Create a list of 3 pop songs."
}
]
},
{
"role": "assistant",
"content": [
{
"text": "Here is a list of 3 pop songs by artists from the United Kingdom:\n\n1. \"As It Was\" by Harry Styles\n2. \"Easy On Me\" by Adele\n3. \"Unholy\" by Sam Smith and Kim Petras"
}
]
}
]
```
#### sistema
Un prompt di sistema è un tipo di prompt che fornisce istruzioni o contesto al modello sull’attività che deve eseguire o sulla persona che dovrebbe adottare durante la conversazione. È possibile specificare un elenco di prompt di sistema per la richiesta nel campo `system` ([SystemContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_SystemContentBlock.html)), come illustrato nell'esempio seguente.
```
[
{
"text": "You are an app that creates play lists for a radio station that plays rock and pop music. Only return song names and the artist. "
}
]
```
#### inferenceConfig
L'ConverseAPI supporta un set base di parametri di inferenza impostati nel `inferenceConfig` campo (). [InferenceConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InferenceConfiguration.html) I parametri di inferenza inclusi nel set di base sono i seguenti:
+ **maxTokens**: numero massimo di token da consentire nella risposta generata.
+ **stopSequences**: elenco di sequenze di arresto. Una sequenza di arresto è una sequenza di caratteri che determina l’interruzione della generazione della risposta da parte del modello.
+ **temperature**: probabilità che il modello selezioni opzioni con maggiore probabilità durante la generazione di una risposta.
+ **topP**: percentuale di candidati più probabili che il modello considera per il token successivo.
Per ulteriori informazioni, consulta [Influenza sulla generazione della risposta con i parametri di inferenza](inference-parameters.md).
L’esempio JSON seguente imposta il parametro di inferenza `temperature`.
```
{"temperature": 0.5}
```
#### addizionale ModelRequestFields
Se il modello in uso ha parametri di inferenza aggiuntivi, è possibile impostare tali parametri specificandoli come elementi JSON nel campo `additionalModelRequestFields`. L’esempio JSON seguente mostra come impostare `top_k`, disponibile nei modelli Anthropic Claude, ma non è un parametro di inferenza di base nell’API Messages.
```
{"top_k": 200}
```
#### promptVariables
Se si specifica un prompt di [Gestione prompt](prompt-management.md) in `modelId` come risorsa su cui eseguire l’inferenza, è possibile utilizzare questo campo per assegnare i valori effettivi alle variabili dei prompt. Il campo `promptVariables` è mappato a un oggetto JSON con chiavi che corrispondono alle variabili definite nei prompt e ai valori con cui sostituire le variabili.
Supponiamo ad esempio che sia presente un prompt che dice **Make me a {{{{genre}}}} playlist consisting of the following number of songs: {{{{number}}}}.** L’ID del prompt è `PROMPT12345` e la sua versione è `1`. È possibile inviare la seguente richiesta `Converse` per sostituire le variabili:
```
POST /model/arn:aws:bedrock:us-east-1:111122223333:prompt/PROMPT12345:1/converse HTTP/1.1
Content-type: application/json
{
"promptVariables": {
"genre": {
"text": "pop"
},
"number": {
"text": "3"
}
}
}
```
#### guardrailConfig
È possibile applicare un guardrail creato con [Guardrail per Amazon Bedrock](guardrails.md) includendo questo campo. Per applicare il guardrail a un messaggio specifico della conversazione, includi il messaggio in a [GuardrailConverseContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailConverseContentBlock.html). Se non si include alcun oggetto `GuardrailConverseContentBlock` nel corpo della richiesta, il guardrail viene applicato a tutti i messaggi nel campo `messages`. Per vedere un esempio, consulta [Includi un guardrail con Converse "Hello, World\!"](guardrails-use-converse-api.md).
#### toolConfig
Questo campo consente di definire uno strumento che il modello può utilizzare per generare una risposta. Per ulteriori informazioni, consulta [Utilizzo di uno strumento per completare una risposta al modello Amazon Bedrock](tool-use.md).
#### addizionale ModelResponseFieldPaths
Si può anche specificare i percorsi per i parametri aggiuntivi del modello nel campo `additionalModelResponseFieldPaths`, come illustrato nell’esempio seguente:
```
[ "/stop_sequence" ]
```
L’API restituisce i campi aggiuntivi richiesti nel campo `additionalModelResponseFields`.
#### requestMetadata
Il `requestMetadata` campo è mappato a un oggetto JSON di tag chiave-valore registrati con la richiesta nei log di invocazione del modello. Puoi utilizzare i metadati della richiesta per filtrare e aggregare i log per team, applicazione, ambiente o qualsiasi altra dimensione che varia a seconda della chiamata.
La stessa funzionalità è disponibile su [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html)e [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html)tramite l'`X-Amzn-Bedrock-Request-Metadata`intestazione HTTP. Per informazioni dettagliate sulle API supportate, sui limiti e sulla modalità di visualizzazione dei metadati delle richieste nei registri delle chiamate, consulta. [Per-request etichettatura dei metadati](cost-mgmt-request-metadata.md)
#### ServiceTier
Questo campo è mappato a un oggetto JSON. È possibile specificare il livello di servizio per una richiesta particolare.
L'esempio seguente mostra la `serviceTier` struttura:
```
"serviceTier": {
"type": "reserved" | "priority" | "default" | "flex"
}
```
Per informazioni dettagliate sui livelli di servizio, inclusi prezzi e caratteristiche prestazionali, vedere[Livelli di servizio per l'ottimizzazione delle prestazioni e dei costi](service-tiers-inference.md).
È anche possibile aggiungere, facoltativamente, punti di controllo della cache ai campi `tools` o `system` per utilizzare il caching dei prompt, a seconda del modello in uso. Per ulteriori informazioni, consulta [Caching dei prompt per un’inferenza del modello più rapida](prompt-caching.md).
### Risposta
La risposta ricevuta dall’API Converse dipende dall’operazione chiamata, `Converse` o `ConverseStream`.
#### Risposta Converse
Nel modulo di risposta`Converse`, il `output` campo ([ConverseOutput](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseOutput.html)) contiene il [messaggio (Message](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html)) generato dal modello. Il contenuto del messaggio si trova nel campo `content` ([ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html)) e il ruolo (`user`o`assistant`) a cui corrisponde il messaggio è nel `role` campo.
Se è stato utilizzato il [caching dei prompt](prompt-caching.md), nel campo di utilizzo `cacheReadInputTokens` e `cacheWriteInputTokens` indicano quanti token totali sono stati letti e scritti dalla e nella cache, rispettivamente.
Se hai utilizzato [i livelli di servizio](#inference-service-tiers), nel campo di risposta, ti `service tier` diremo quale livello di servizio è stato utilizzato per la richiesta.
Il `metrics` campo ([ConverseMetrics](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseMetrics.html)) include le metriche per la chiamata. Per determinare il motivo per cui il modello ha interrotto la generazione di contenuto, controlla il campo `stopReason`. È possibile ottenere informazioni sui token passati al modello nella richiesta e sui token generati nella risposta controllando il `usage` campo (). [TokenUsage](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_TokenUsage.html) Se sono stati specificati campi di risposta aggiuntivi nella richiesta, l’API li restituisce come elementi JSON nel campo `additionalModelResponseFields`.
L’esempio seguente mostra la risposta ottenuta da `Converse` quando si passa il prompt discusso in [Richiesta](#conversation-inference-call-request).
```
{
"output": {
"message": {
"role": "assistant",
"content": [
{
"text": "Here is a list of 3 pop songs by artists from the United Kingdom:\n\n1. \"Wannabe\" by Spice Girls\n2. \"Bitter Sweet Symphony\" by The Verve \n3. \"Don't Look Back in Anger\" by Oasis"
}
]
}
},
"stopReason": "end_turn",
"usage": {
"inputTokens": 125,
"outputTokens": 60,
"totalTokens": 185
},
"metrics": {
"latencyMs": 1175
}
}
```
#### ConverseStream risposta
Se si chiama `ConverseStream` per trasmettere in streaming la risposta da un modello, il flusso viene restituito nel campo `stream` della risposta. Il flusso invia gli eventi seguenti nell’ordine indicato.
1. `messageStart`([MessageStartEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_MessageStartEvent.html)). L'evento di inizio di un messaggio. Include il ruolo per il messaggio.
1. `contentBlockStart`([ContentBlockStartEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlockStartEvent.html)). Un evento di avvio del blocco di contenuto. Solo con utilizzo dello strumento.
1. `contentBlockDelta`([ContentBlockDeltaEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlockDeltaEvent.html)). Un evento delta del blocco di contenuto. Include uno degli elementi seguenti:
+ `text`: testo parziale generato dal modello.
+ `reasoningContent`: ragionamento parziale eseguito dal modello per generare la risposta. È necessario inviare l’oggetto `signature` restituito, oltre a tutti i messaggi precedenti nelle richieste `Converse` successive. Se uno qualsiasi dei messaggi viene modificato, la risposta genera un errore.
+ `toolUse`: oggetto JSON di input parziale per l’utilizzo dello strumento.
1. `contentBlockStop`([ContentBlockStopEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlockStopEvent.html)). Un evento Content Block Stop.
1. `messageStop`([MessageStopEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_MessageStopEvent.html)). L'evento di interruzione del messaggio. Include il motivo per cui il modello ha interrotto la generazione di output.
1. `metadata`([ConverseStreamMetadataEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStreamMetadataEvent.html)). Metadati per la richiesta. I metadati includono l'utilizzo del token in `usage` ([TokenUsage](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_TokenUsage.html)) e le metriche per la chiamata in `metrics` (). [ConverseStreamMetadataEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStreamMetadataEvent.html)
ConverseStream trasmette un blocco di contenuto completo come `ContentBlockStartEvent` evento, uno o più `ContentBlockDeltaEvent` eventi e un evento. `ContentBlockStopEvent` Utilizza il campo `contentBlockIndex` come indice per correlare gli eventi che compongono un blocco di contenuto.
Di seguito è mostrato un esempio di risposta parziale di `ConverseStream`.
```
{'messageStart': {'role': 'assistant'}}
{'contentBlockDelta': {'delta': {'text': ''}, 'contentBlockIndex': 0}}
{'contentBlockDelta': {'delta': {'text': ' Title'}, 'contentBlockIndex': 0}}
{'contentBlockDelta': {'delta': {'text': ':'}, 'contentBlockIndex': 0}}
.
.
.
{'contentBlockDelta': {'delta': {'text': ' The'}, 'contentBlockIndex': 0}}
{'messageStop': {'stopReason': 'max_tokens'}}
{'metadata': {'usage': {'inputTokens': 47, 'outputTokens': 20, 'totalTokens': 67}, 'metrics': {'latencyMs': 100.0}}}
```
## Converse Esempi di API
Gli esempi seguenti mostrano come utilizzare le operazioni `Converse` e `ConverseStream`.
------
#### [ Text ]
Questo esempio mostra come chiamare l’operazione `Converse` con il modello *Anthropic Claude 3 Sonnet*. L’esempio mostra come inviare il testo di input, i parametri di inferenza e i parametri aggiuntivi univoci per il modello. Il codice avvia una conversazione chiedendo al modello di creare un elenco di brani. Continua quindi la conversazione chiedendo che i brani siano di artisti del Regno Unito.
```
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
Shows how to use the Converse API with Anthropic Claude 3 Sonnet (on demand).
"""
import logging
import boto3
from botocore.exceptions import ClientError
logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO)
def generate_conversation(bedrock_client,
model_id,
system_prompts,
messages):
"""
Sends messages to a model.
Args:
bedrock_client: The Boto3 Bedrock runtime client.
model_id (str): The model ID to use.
system_prompts (JSON) : The system prompts for the model to use.
messages (JSON) : The messages to send to the model.
Returns:
response (JSON): The conversation that the model generated.
"""
logger.info("Generating message with model %s", model_id)
# Inference parameters to use.
temperature = 0.5
top_k = 200
# Base inference parameters to use.
inference_config = {"temperature": temperature}
# Additional inference parameters to use.
additional_model_fields = {"top_k": top_k}
# Send the message.
response = bedrock_client.converse(
modelId=model_id,
messages=messages,
system=system_prompts,
inferenceConfig=inference_config,
additionalModelRequestFields=additional_model_fields
)
# Log token usage.
token_usage = response['usage']
logger.info("Input tokens: %s", token_usage['inputTokens'])
logger.info("Output tokens: %s", token_usage['outputTokens'])
logger.info("Total tokens: %s", token_usage['totalTokens'])
logger.info("Stop reason: %s", response['stopReason'])
return response
def main():
"""
Entrypoint for Anthropic Claude 3 Sonnet example.
"""
logging.basicConfig(level=logging.INFO,
format="%(levelname)s: %(message)s")
model_id = "anthropic.claude-3-sonnet-20240229-v1:0"
# Setup the system prompts and messages to send to the model.
system_prompts = [{"text": "You are an app that creates playlists for a radio station that plays rock and pop music. Only return song names and the artist."}]
message_1 = {
"role": "user",
"content": [{"text": "Create a list of 3 pop songs."}]
}
message_2 = {
"role": "user",
"content": [{"text": "Make sure the songs are by artists from the United Kingdom."}]
}
messages = []
try:
bedrock_client = boto3.client(service_name='bedrock-runtime')
# Start the conversation with the 1st message.
messages.append(message_1)
response = generate_conversation(
bedrock_client, model_id, system_prompts, messages)
# Add the response message to the conversation.
output_message = response['output']['message']
messages.append(output_message)
# Continue the conversation with the 2nd message.
messages.append(message_2)
response = generate_conversation(
bedrock_client, model_id, system_prompts, messages)
output_message = response['output']['message']
messages.append(output_message)
# Show the complete conversation.
for message in messages:
print(f"Role: {message['role']}")
for content in message['content']:
print(f"Text: {content['text']}")
print()
except ClientError as err:
message = err.response['Error']['Message']
logger.error("A client error occurred: %s", message)
print(f"A client error occured: {message}")
else:
print(
f"Finished generating text with model {model_id}.")
if __name__ == "__main__":
main()
```
------
#### [ Image ]
Questo esempio mostra come inviare un’immagine nell’ambito di un messaggio e richiede che il modello la descriva. L’esempio utilizza l’operazione `Converse` e il modello *Anthropic Claude 3 Sonnet*.
```
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
Shows how to send an image with the Converse API with an accompanying text prompt to Anthropic Claude 3 Sonnet (on demand).
"""
import logging
import boto3
from botocore.exceptions import ClientError
logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO)
def generate_conversation(bedrock_client,
model_id,
input_text,
input_image):
"""
Sends a message to a model.
Args:
bedrock_client: The Boto3 Bedrock runtime client.
model_id (str): The model ID to use.
input text : The text prompt accompanying the image.
input_image : The path to the input image.
Returns:
response (JSON): The conversation that the model generated.
"""
logger.info("Generating message with model %s", model_id)
# Get image extension and read in image as bytes
image_ext = input_image.split(".")[-1]
with open(input_image, "rb") as f:
image = f.read()
message = {
"role": "user",
"content": [
{
"text": input_text
},
{
"image": {
"format": image_ext,
"source": {
"bytes": image
}
}
}
]
}
messages = [message]
# Send the message.
response = bedrock_client.converse(
modelId=model_id,
messages=messages
)
return response
def main():
"""
Entrypoint for Anthropic Claude 3 Sonnet example.
"""
logging.basicConfig(level=logging.INFO,
format="%(levelname)s: %(message)s")
model_id = "anthropic.claude-3-sonnet-20240229-v1:0"
input_text = "What's in this image?"
input_image = "path/to/image"
try:
bedrock_client = boto3.client(service_name="bedrock-runtime")
response = generate_conversation(
bedrock_client, model_id, input_text, input_image)
output_message = response['output']['message']
print(f"Role: {output_message['role']}")
for content in output_message['content']:
print(f"Text: {content['text']}")
token_usage = response['usage']
print(f"Input tokens: {token_usage['inputTokens']}")
print(f"Output tokens: {token_usage['outputTokens']}")
print(f"Total tokens: {token_usage['totalTokens']}")
print(f"Stop reason: {response['stopReason']}")
except ClientError as err:
message = err.response['Error']['Message']
logger.error("A client error occurred: %s", message)
print(f"A client error occured: {message}")
else:
print(
f"Finished generating text with model {model_id}.")
if __name__ == "__main__":
main()
```
------
#### [ Document ]
Questo esempio mostra come inviare un documento nell’ambito di un messaggio e richiede che il modello ne descriva il contenuto. L’esempio utilizza l’operazione `Converse` e il modello *Anthropic Claude 3 Sonnet*.
```
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
Shows how to send an document as part of a message to Anthropic Claude 3 Sonnet (on demand).
"""
import logging
import boto3
from botocore.exceptions import ClientError
logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO)
def generate_message(bedrock_client,
model_id,
input_text,
input_document_path):
"""
Sends a message to a model.
Args:
bedrock_client: The Boto3 Bedrock runtime client.
model_id (str): The model ID to use.
input text : The input message.
input_document_path : The path to the input document.
Returns:
response (JSON): The conversation that the model generated.
"""
logger.info("Generating message with model %s", model_id)
# Get format from path and read the path
input_document_format = input_document_path.split(".")[-1]
with open(input_document_path, 'rb') as input_document_file:
input_document = input_document_file.read()
# Message to send.
message = {
"role": "user",
"content": [
{
"text": input_text
},
{
"document": {
"name": "MyDocument",
"format": input_document_format,
"source": {
"bytes": input_document
}
}
}
]
}
messages = [message]
# Send the message.
response = bedrock_client.converse(
modelId=model_id,
messages=messages
)
return response
def main():
"""
Entrypoint for Anthropic Claude 3 Sonnet example.
"""
logging.basicConfig(level=logging.INFO,
format="%(levelname)s: %(message)s")
model_id = "anthropic.claude-3-sonnet-20240229-v1:0"
input_text = "What's in this document?"
input_document_path = "path/to/document"
try:
bedrock_client = boto3.client(service_name="bedrock-runtime")
response = generate_message(
bedrock_client, model_id, input_text, input_document_path)
output_message = response['output']['message']
print(f"Role: {output_message['role']}")
for content in output_message['content']:
print(f"Text: {content['text']}")
token_usage = response['usage']
print(f"Input tokens: {token_usage['inputTokens']}")
print(f"Output tokens: {token_usage['outputTokens']}")
print(f"Total tokens: {token_usage['totalTokens']}")
print(f"Stop reason: {response['stopReason']}")
except ClientError as err:
message = err.response['Error']['Message']
logger.error("A client error occurred: %s", message)
print(f"A client error occured: {message}")
else:
print(
f"Finished generating text with model {model_id}.")
if __name__ == "__main__":
main()
```
------
#### [ Streaming ]
Questo esempio mostra come chiamare l’operazione `ConverseStream` con il modello *Anthropic Claude 3 Sonnet*. L’esempio mostra come inviare il testo di input, i parametri di inferenza e i parametri aggiuntivi univoci per il modello.
```
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
Shows how to use the Converse API to stream a response from Anthropic Claude 3 Sonnet (on demand).
"""
import logging
import boto3
from botocore.exceptions import ClientError
logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO)
def stream_conversation(bedrock_client,
model_id,
messages,
system_prompts,
inference_config,
additional_model_fields):
"""
Sends messages to a model and streams the response.
Args:
bedrock_client: The Boto3 Bedrock runtime client.
model_id (str): The model ID to use.
messages (JSON) : The messages to send.
system_prompts (JSON) : The system prompts to send.
inference_config (JSON) : The inference configuration to use.
additional_model_fields (JSON) : Additional model fields to use.
Returns:
Nothing.
"""
logger.info("Streaming messages with model %s", model_id)
response = bedrock_client.converse_stream(
modelId=model_id,
messages=messages,
system=system_prompts,
inferenceConfig=inference_config,
additionalModelRequestFields=additional_model_fields
)
stream = response.get('stream')
if stream:
for event in stream:
if 'messageStart' in event:
print(f"\nRole: {event['messageStart']['role']}")
if 'contentBlockDelta' in event:
print(event['contentBlockDelta']['delta']['text'], end="")
if 'messageStop' in event:
print(f"\nStop reason: {event['messageStop']['stopReason']}")
if 'metadata' in event:
metadata = event['metadata']
if 'usage' in metadata:
print("\nToken usage")
print(f"Input tokens: {metadata['usage']['inputTokens']}")
print(
f":Output tokens: {metadata['usage']['outputTokens']}")
print(f":Total tokens: {metadata['usage']['totalTokens']}")
if 'metrics' in event['metadata']:
print(
f"Latency: {metadata['metrics']['latencyMs']} milliseconds")
def main():
"""
Entrypoint for streaming message API response example.
"""
logging.basicConfig(level=logging.INFO,
format="%(levelname)s: %(message)s")
model_id = "anthropic.claude-3-sonnet-20240229-v1:0"
system_prompt = """You are an app that creates playlists for a radio station
that plays rock and pop music. Only return song names and the artist."""
# Message to send to the model.
input_text = "Create a list of 3 pop songs."
message = {
"role": "user",
"content": [{"text": input_text}]
}
messages = [message]
# System prompts.
system_prompts = [{"text" : system_prompt}]
# inference parameters to use.
temperature = 0.5
top_k = 200
# Base inference parameters.
inference_config = {
"temperature": temperature
}
# Additional model inference parameters.
additional_model_fields = {"top_k": top_k}
try:
bedrock_client = boto3.client(service_name='bedrock-runtime')
stream_conversation(bedrock_client, model_id, messages,
system_prompts, inference_config, additional_model_fields)
except ClientError as err:
message = err.response['Error']['Message']
logger.error("A client error occurred: %s", message)
print("A client error occured: " +
format(message))
else:
print(
f"Finished streaming messages with model {model_id}.")
if __name__ == "__main__":
main()
```
------
#### [ Video ]
Questo esempio mostra come inviare un video nell’ambito di un messaggio e richiede che il modello lo descriva. L’esempio utilizza l’operazione `Converse` e il modello Amazon Nova Pro.
```
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
Shows how to send a video with the Converse API to Amazon Nova Pro (on demand).
"""
import logging
import boto3
from botocore.exceptions import ClientError
logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO)
def generate_conversation(bedrock_client,
model_id,
input_text,
input_video):
"""
Sends a message to a model.
Args:
bedrock_client: The Boto3 Bedrock runtime client.
model_id (str): The model ID to use.
input text : The input message.
input_video : The input video.
Returns:
response (JSON): The conversation that the model generated.
"""
logger.info("Generating message with model %s", model_id)
# Message to send.
with open(input_video, "rb") as f:
video = f.read()
message = {
"role": "user",
"content": [
{
"text": input_text
},
{
"video": {
"format": 'mp4',
"source": {
"bytes": video
}
}
}
]
}
messages = [message]
# Send the message.
response = bedrock_client.converse(
modelId=model_id,
messages=messages
)
return response
def main():
"""
Entrypoint for Amazon Nova Pro example.
"""
logging.basicConfig(level=logging.INFO,
format="%(levelname)s: %(message)s")
model_id = "amazon.nova-pro-v1:0"
input_text = "What's in this video?"
input_video = "path/to/video"
try:
bedrock_client = boto3.client(service_name="bedrock-runtime")
response = generate_conversation(
bedrock_client, model_id, input_text, input_video)
output_message = response['output']['message']
print(f"Role: {output_message['role']}")
for content in output_message['content']:
print(f"Text: {content['text']}")
token_usage = response['usage']
print(f"Input tokens: {token_usage['inputTokens']}")
print(f"Output tokens: {token_usage['outputTokens']}")
print(f"Total tokens: {token_usage['totalTokens']}")
print(f"Stop reason: {response['stopReason']}")
except ClientError as err:
message = err.response['Error']['Message']
logger.error("A client error occurred: %s", message)
print(f"A client error occured: {message}")
else:
print(
f"Finished generating text with model {model_id}.")
if __name__ == "__main__":
main()
```
------