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à. # Includere un guardrail con l’API Converse È possibile utilizzare un guardrail per proteggere le app conversazionali create con l’API Converse. Ad esempio, se viene creata un’app di chat con l’API Converse, è possibile utilizzare un guardrail per bloccare i contenuti inappropriati inseriti dall’utente e quelli generati dal modello. Per informazioni sull’API Converse, consultare [Avvio di una conversazione con le operazioni dell’API Converse](conversation-inference.md). **Topics** + [Chiamare l’API Converse con i guardrail](#guardrails-use-converse-api-call) + [Elaborazione della risposta quando si utilizza l’API Converse](#guardrails-use-converse-api-response) + [Esempio di codice per l’utilizzo dell’API Converse con i guardrail](#converse-api-guardrail-example) ## Chiamare l’API Converse con i guardrail Per utilizzare un guardrail, includi le informazioni di configurazione per il guardrail nelle chiamate a [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 le risposte in streaming) nelle operazioni. Facoltativamente, è possibile selezionare contenuti specifici nel messaggio che il guardrail deve valutare. Per informazioni sui modelli che è possibile utilizzare con i guardrail e l’API Converse, consultare [Modelli e funzionalità del modello supportati](conversation-inference-supported-models-features.md). **Topics** + [Configurare un guardrail da utilizzare con l’API Converse](#guardrails-use-converse-api-call-configure) + [Valutare solo contenuti specifici di un messaggio](#guardrails-use-converse-api-call-message) + [Protezione di un prompt di sistema inviato all’API Converse](#guardrails-use-converse-api-call-message-system-guard) + [Comportamento del guardrail per messaggi e prompt di sistema](#guardrails-use-converse-api-call-message-system-message-guard) ### Configurare un guardrail da utilizzare con l’API Converse Specificare le informazioni di configurazione del guardrail nel parametro di input `guardrailConfig`. La configurazione include l’ID e la versione del guardrail da utilizzare. È possibile anche abilitare il tracciamento del guardrail, che fornisce informazioni sui contenuti bloccati dal guardrail. Con l'`Converse`operazione, `guardrailConfig` è un [GuardrailConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailConfiguration.html)oggetto, come mostrato nell'esempio seguente. ``` { "guardrailIdentifier": "Guardrail ID", "guardrailVersion": "Guardrail version", "trace": "enabled" } ``` Se lo usi`ConverseStream`, passi un [GuardrailStreamConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailStreamConfiguration.html)oggetto. Facoltativamente, è possibile utilizzare il campo `streamProcessingMode` per specificare che il modello deve completare la valutazione del guardrail, prima di restituire blocchi di risposta in streaming. In alternativa, è possibile fare in modo che il modello risponda in modo asincrono mentre il guardrail continua la sua valutazione in background. Per ulteriori informazioni, consulta [Configurare il comportamento delle risposta in streaming per filtrare i contenuti](guardrails-streaming.md). ### Valutare solo contenuti specifici di un messaggio Se viene specificato un [messaggio](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) in un modello, il guardrail valuta il contenuto del messaggio. Puoi anche valutare parti specifiche di un messaggio utilizzando il campo `guardContent` ([GuardrailConverseContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailConverseContentBlock.html)). **Suggerimento** L'uso del `guardContent` campo è simile all'utilizzo dei tag di input con [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). Per ulteriori informazioni, consulta [Applicare tag all’input dell’utente per filtrare i contenuti](guardrails-tagging.md). Ad esempio, il seguente guardrail valuta solo il contenuto del campo `guardContent` e non il resto del messaggio. Ciò risulta utile quando si vuole che il guardrail valuti esclusivamente il messaggio più recente di una conversazione, come mostrato nell’esempio seguente. ``` [ { "role": "user", "content": [ { "text": "Create a playlist of 2 pop songs." } ] }, { "role": "assistant", "content": [ { "text": "Sure! Here are two pop songs:\n1. \"Bad Habits\" by Ed Sheeran\n2. \"All Of The Lights\" by Kanye West\n\nWould you like to add any more songs to this playlist?" } ] }, { "role": "user", "content": [ { "guardContent": { "text": { "text": "Create a playlist of 2 heavy metal songs." } } } ] } ] ``` Un altro caso d’uso di `guardContent` consiste nel fornire contesto aggiuntivo per un messaggio senza che il guardrail lo valuti. Nell’esempio seguente, il guardrail valuta `"Create a playlist of heavy metal songs"` e ignora solo il `"Only answer with a list of songs"`. ``` messages = [ { "role": "user", "content": [ { "text": "Only answer with a list of songs." }, { "guardContent": { "text": { "text": "Create a playlist of heavy metal songs." } } } ] } ] ``` Se il contenuto non si trova in un blocco `guardContent`, non significa necessariamente che non verrà valutato. Questo comportamento dipende dalle policy dei filtri utilizzate dal guardrail. L’esempio seguente mostra due blocchi `guardContent` con [controlli di correlazione contestuale](guardrails-contextual-grounding-check.md) (basati sui campi `qualifiers`). I controlli di correlazione contestuale nel guardrail valuteranno solo il contenuto di questi blocchi. Tuttavia, se il guardrail contiene anche un [filtro per parole](guardrails-content-filters.md) che blocca la parola “sfondo”, il testo “Alcune informazioni di base aggiuntive.” verrà comunque valutato, anche se non si trova in un blocco `guardContent`. ``` [{ "role": "user", "content": [{ "guardContent": { "text": { "text": "London is the capital of UK. Tokyo is the capital of Japan.", "qualifiers": ["grounding_source"] } } }, { "text": "Some additional background information." }, { "guardContent": { "text": { "text": "What is the capital of Japan?", "qualifiers": ["query"] } } } ] }] ``` ### Protezione di un prompt di sistema inviato all’API Converse È possibile utilizzare i guardrail con i prompt di sistema inviati all’API Converse. Per proteggere un prompt di sistema, specificate il campo `guardContent` ([SystemContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_SystemContentBlock.html)) nel prompt di sistema che passate all'API, come illustrato nell'esempio seguente. ``` [ { "guardContent": { "text": { "text": "Only respond with Welsh heavy metal songs." } } } ] ``` Se non viene specificato il campo `guardContent`, il guardrail non valuta il messaggio del prompt di sistema. ### Comportamento del guardrail per messaggi e prompt di sistema Il modo in cui il guardrail valuta il campo `guardContent` è diverso a seconda che si tratti di prompt di sistema o di messaggi specificati nel messaggio. | | Prompt di sistema con blocco del guardrail | Prompt di sistema senza blocco del guardrail | | --- | --- | --- | | **Messaggi con blocco del guardrail** | Sistema: il guardrail esamina il contenuto del blocco del guardrail Messaggi: il guardrail esamina il contenuto del blocco del guardrail | Sistema: il guardrail non esamina nulla Messaggi: il guardrail esamina il contenuto del blocco del guardrail | | **Messaggi senza blocco del guardrail** | Sistema: il guardrail esamina il contenuto del blocco del guardrail Messaggi: il guardrail esamina tutto | Sistema: il guardrail non esamina nulla Messaggi: il guardrail esamina tutto | ## Elaborazione della risposta quando si utilizza l’API Converse Durante la chiamata dell’operazione Converse, il guardrail valuta il messaggio inviato. Se il guardrail rileva contenuti bloccati, si verifica quanto segue. + Il campo `stopReason` nella risposta viene impostato su `guardrail_intervened`. + Se avete abilitato la traccia, la traccia è disponibile nel campo `trace` () [ConverseTrace](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseTrace.html). Con`ConverseStream`, la traccia si trova nei metadati ([ConverseStreamMetadataEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStreamMetadataEvent.html)) restituiti dall'operazione. + Il testo del contenuto bloccato che hai configurato nel guardrail viene restituito nel campo `output` ([ConverseOutput](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseOutput.html)). Con `ConverseStream` il testo del contenuto bloccato viene inserito nel messaggio in streaming. La seguente risposta parziale mostra il testo del contenuto bloccato e la traccia della valutazione del guardrail. Il guardrail ha bloccato il termine *Heavy metal* nel messaggio. ``` { "output": { "message": { "role": "assistant", "content": [ { "text": "Sorry, I can't answer questions about heavy metal music." } ] } }, "stopReason": "guardrail_intervened", "usage": { "inputTokens": 0, "outputTokens": 0, "totalTokens": 0 }, "metrics": { "latencyMs": 721 }, "trace": { "guardrail": { "inputAssessment": { "3o06191495ze": { "topicPolicy": { "topics": [ { "name": "Heavy metal", "type": "DENY", "action": "BLOCKED" } ] }, "invocationMetrics": { "guardrailProcessingLatency": 240, "usage": { "topicPolicyUnits": 1, "contentPolicyUnits": 0, "wordPolicyUnits": 0, "sensitiveInformationPolicyUnits": 0, "sensitiveInformationPolicyFreeUnits": 0, "contextualGroundingPolicyUnits": 0 }, "guardrailCoverage": { "textCharacters": { "guarded": 39, "total": 72 } } } } } } } } ``` ## Esempio di codice per l’utilizzo dell’API Converse con i guardrail Questo esempio mostra come proteggere una conversazione con le operazioni `Converse` e `ConverseStream`. L’esempio mostra come impedire a un modello di creare una playlist che include brani di genere heavy metal. **Come proteggere una conversazione** 1. Creare un guardrail seguendo le istruzioni riportate in [Creare un guardrail](guardrails-components.md). + **Nome**: inserire *Heavy metal*. + **Definizione per argomento**: inserire *Evita di menzionare brani appartenenti al genere musicale heavy metal*. + **Aggiungi frasi di esempio**: inserire *Crea una playlist di brani heavy metal*. Nella fase 9, inserire quanto segue: + **Messaggi visualizzati per i prompt bloccati**: inserire *Mi dispiace, non posso rispondere a domande sulla musica heavy metal*. + **Messaggi per le risposte bloccate**: inserire *Mi dispiace, il modello ha generato una risposta che menzionava la musica heavy metal*. È possibile configurare altre opzioni per i guardrail, ma non è necessario per questo esempio. 1. Creare una versione del guardrail seguendo le istruzioni riportate in [Creazione di una versione di un guardrail](guardrails-versions-create.md). 1. Nei seguenti esempi di codice ([Converse](#converse-api-guardrail-example-converse) e [ConverseStream](#converse-api-guardrail-example-converse-stream)), imposta le seguenti variabili: + `guardrail_id`: ID del guardrail creato nella fase 1. + `guardrail_version`: versione del guardrail creato nella fase 2. + `text`: utilizzare `Create a playlist of heavy metal songs.` 1. Eseguire il codice di esempio. L’output dovrebbe mostrare la valutazione del guardrail e il messaggio di output `Text: Sorry, I can't answer questions about heavy metal music.`. La valutazione dell’input del guardrail mostra che il modello ha rilevato il termine *heavy metal* nel messaggio di input. 1. (Facoltativo) Verificare che il guardrail blocchi il testo inappropriato generato dal modello modificando il valore di `text` in *Elenca tutti i generi di musica rock*. Eseguire nuovamente gli esempi. La risposta dovrebbe contenere una valutazione dell’output. ------ #### [ Converse ] Il codice seguente utilizza il guardrail con l’operazione `Converse`. ``` # Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. # SPDX-License-Identifier: Apache-2.0 """ Shows how to use a guardrail with the Converse API. """ import logging import json import boto3 from botocore.exceptions import ClientError logger = logging.getLogger(__name__) logging.basicConfig(level=logging.INFO) def generate_conversation(bedrock_client, model_id, messages, guardrail_config): """ Sends a message to a model. Args: bedrock_client: The Boto3 Bedrock runtime client. model_id (str): The model ID to use. messages JSON): The message to send to the model. guardrail_config : Configuration for the guardrail. Returns: response (JSON): The conversation that the model generated. """ logger.info("Generating message with model %s", model_id) # Send the message. response = bedrock_client.converse( modelId=model_id, messages=messages, guardrailConfig=guardrail_config ) return response def main(): """ Entrypoint for example. """ logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s") # The model to use. model_id="meta.llama3-8b-instruct-v1:0" # The ID and version of the guardrail. guardrail_id = "Your guardrail ID" guardrail_version = "DRAFT" # Configuration for the guardrail. guardrail_config = { "guardrailIdentifier": guardrail_id, "guardrailVersion": guardrail_version, "trace": "enabled" } text = "Create a playlist of 2 heavy metal songs." context_text = "Only answer with a list of songs." # The message for the model and the content that you want the guardrail to assess. messages = [ { "role": "user", "content": [ { "text": context_text, }, { "guardContent": { "text": { "text": text } } } ] } ] try: print(json.dumps(messages, indent=4)) bedrock_client = boto3.client(service_name='bedrock-runtime') response = generate_conversation( bedrock_client, model_id, messages, guardrail_config) output_message = response['output']['message'] if response['stopReason'] == "guardrail_intervened": trace = response['trace'] print("Guardrail trace:") print(json.dumps(trace['guardrail'], indent=4)) for content in output_message['content']: print(f"Text: {content['text']}") 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() ``` ------ #### [ ConverseStream ] Il codice seguente utilizza il guardrail con l’operazione `ConverseStream`. ``` # Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. # SPDX-License-Identifier: Apache-2.0 """ Shows how to use a guardrail with the ConverseStream operation. """ import logging import json import boto3 from botocore.exceptions import ClientError logger = logging.getLogger(__name__) logging.basicConfig(level=logging.INFO) def stream_conversation(bedrock_client, model_id, messages, guardrail_config): """ 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. guardrail_config : Configuration for the guardrail. Returns: Nothing. """ logger.info("Streaming messages with model %s", model_id) response = bedrock_client.converse_stream( modelId=model_id, messages=messages, guardrailConfig=guardrail_config ) 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 'trace' in metadata: print("\nAssessment") print(json.dumps(metadata['trace'], indent=4)) def main(): """ Entrypoint for streaming message API response example. """ logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s") # The model to use. model_id = "amazon.titan-text-express-v1" # The ID and version of the guardrail. guardrail_id = "Change to your guardrail ID" guardrail_version = "DRAFT" # Configuration for the guardrail. guardrail_config = { "guardrailIdentifier": guardrail_id, "guardrailVersion": guardrail_version, "trace": "enabled", "streamProcessingMode" : "sync" } text = "Create a playlist of heavy metal songs." # The message for the model and the content that you want the guardrail to assess. messages = [ { "role": "user", "content": [ { "text": text, }, { "guardContent": { "text": { "text": text } } } ] } ] try: bedrock_client = boto3.client(service_name='bedrock-runtime') stream_conversation(bedrock_client, model_id, messages, guardrail_config) 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() ``` ------