As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Incluir uma barreira de proteção com a API Converse É possível usar uma barreira de proteção para proteger as aplicações de conversação criadas com a API Converse. Por exemplo, se você criar uma aplicação de chat com a API Converse, poderá usar uma barreira de proteção para bloquear conteúdo inadequado inserido pelo usuário e conteúdo inadequado gerado pelo modelo. Para obter informações sobre a API do Converse, consulte [Realizar uma conversa com as operações de API Converse](conversation-inference.md). **Topics** + [Chamar a API Converse com barreiras de proteção](#guardrails-use-converse-api-call) + [Processar a resposta ao usar a API Converse](#guardrails-use-converse-api-response) + [Exemplo de código para usar a API Converse com barreiras de proteção](#converse-api-guardrail-example) ## Chamar a API Converse com barreiras de proteção Para usar uma grade de proteção, você inclui informações de configuração da grade de proteção em chamadas para o [Converse](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html) ou [ConverseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStream.html)(para respostas de streaming) em operações. Opcionalmente, é possível selecionar um conteúdo específico na mensagem que deseja que a barreira de proteção avalie. Para ter informações sobre os modelos que podem ser usados com barreiras de proteção e a API Converse, consulte [Modelos compatíveis e recursos do modelo](conversation-inference-supported-models-features.md). **Topics** + [Configurar uma barreira de proteção para funcionar com a API Converse](#guardrails-use-converse-api-call-configure) + [Avaliar somente conteúdo específico em uma mensagem](#guardrails-use-converse-api-call-message) + [Proteger um prompt do sistema enviado à API Converse](#guardrails-use-converse-api-call-message-system-guard) + [Comportamento da barreira de proteção do prompt do sistema e da mensagem](#guardrails-use-converse-api-call-message-system-message-guard) ### Configurar uma barreira de proteção para funcionar com a API Converse Você especifica as informações de configuração da barreira de proteção no parâmetro de entrada `guardrailConfig`. A configuração inclui o ID e a versão da barreira de proteção que você deseja usar. Você também pode habilitar o rastreamento da barreira de proteção, que fornece informações sobre o conteúdo que a barreira de proteção bloqueou. Com a `Converse` operação, `guardrailConfig` é um [GuardrailConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailConfiguration.html)objeto, conforme mostrado no exemplo a seguir. ``` { "guardrailIdentifier": "Guardrail ID", "guardrailVersion": "Guardrail version", "trace": "enabled" } ``` Se você usar`ConverseStream`, você passa um [GuardrailStreamConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailStreamConfiguration.html)objeto. Opcionalmente, é possível usar o campo `streamProcessingMode` para especificar que deseja que o modelo conclua a avaliação da barreira de proteção, antes de retornar fragmentos da resposta de streaming. Ou é possível fazer com que o modelo responda de forma assíncrona enquanto a barreira de proteção continua sua avaliação em segundo plano. Para obter mais informações, consulte [Configurar o comportamento da resposta de streaming para filtrar o conteúdo](guardrails-streaming.md). ### Avaliar somente conteúdo específico em uma mensagem Ao transmitir uma [mensagem](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) para um modelo, a barreira de proteção avalia o conteúdo da mensagem. Você também pode avaliar partes específicas de uma mensagem usando o campo `guardContent` ([GuardrailConverseContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailConverseContentBlock.html)). **dica** Usar o `guardContent` campo é semelhante ao uso de tags de entrada com [InvokeModel[InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html)](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html)e. Para obter mais informações, consulte [Aplicar tags à entrada do usuário para filtrar conteúdo](guardrails-tagging.md). Por exemplo, a barreira de proteção a seguir avalia somente o conteúdo no campo `guardContent` e não no restante da mensagem. Isso é útil para que a barreira de proteção avalie somente as mensagens mais recentes em uma conversa, conforme mostrado no exemplo a seguir. ``` [ { "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." } } } ] } ] ``` Outro caso de uso de `guardContent` é fornecer contexto adicional para uma mensagem, sem que a barreira de proteção avalie esse contexto. No exemplo a seguir, a barreira de proteção avalia apenas `"Create a playlist of heavy metal songs"` e ignora `"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 o conteúdo não estiver em um bloco `guardContent`, isso não significa necessariamente que ele não será avaliado. Esse comportamento depende das políticas de filtragem que a barreira de proteção usa. O exemplo a seguir mostra dois blocos `guardContent` com [verificações de base contextual](guardrails-contextual-grounding-check.md) (com base nos campos `qualifiers`). As verificações de base contextual na barreira de proteção avaliarão apenas o conteúdo desses blocos. No entanto, se a barreira de proteção também tiver um [filtro de palavras](guardrails-content-filters.md) que bloqueie a palavra “básicas”, o texto “Algumas informações básicas adicionais” ainda será avaliado, mesmo que não esteja em um bloco `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"] } } } ] }] ``` ### Proteger um prompt do sistema enviado à API Converse É possível usar barreiras de proteção com prompts do sistema que você envia à API Converse. Para proteger um prompt do sistema, especifique o campo `guardContent` ([SystemContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_SystemContentBlock.html)) no prompt do sistema que você passa para a API, conforme mostrado no exemplo a seguir. ``` [ { "guardContent": { "text": { "text": "Only respond with Welsh heavy metal songs." } } } ] ``` Se você não fornecer o campo `guardContent`, a barreira de proteção não avaliará a mensagem do prompt do sistema. ### Comportamento da barreira de proteção do prompt do sistema e da mensagem A forma como a barreira de proteção avalia o campo `guardContent` se comporta de forma diferente entre os prompts do sistema e de mensagens que você passa na mensagem. | | O prompt do sistema tem um bloco de barreira de proteção | O prompt do sistema não tem um bloco da barreira de proteção | | --- | --- | --- | | **As mensagens têm um bloco de barreira de proteção** | Sistema: a barreira de proteção investiga o conteúdo no bloco de barreira de proteção. Mensagens: a barreira de proteção investiga o conteúdo no bloco de barreira de proteção. | Sistema: a barreira de proteção não investiga nada Mensagens: a barreira de proteção investiga o conteúdo no bloco de barreira de proteção. | | **As mensagens não têm um bloco de barreira de proteção** | Sistema: a barreira de proteção investiga o conteúdo no bloco de barreira de proteção. Mensagens: a barreira de proteção investiga tudo | Sistema: a barreira de proteção não investiga nada Mensagens: a barreira de proteção investiga tudo | ## Processar a resposta ao usar a API Converse Quando você chama a operação Converse, a barreira de proteção avalia a mensagem que você envia. Se a barreira de proteção detectar conteúdo bloqueado, acontecerá o seguinte: + O campo `stopReason` na resposta é definido como `guardrail_intervened`. + Se você ativou o rastreamento, o rastreamento estará disponível no campo `trace` ([ConverseTrace](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseTrace.html)). Com`ConverseStream`, o rastreamento está nos metadados ([ConverseStreamMetadataEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStreamMetadataEvent.html)) que a operação retorna. + O texto do conteúdo bloqueado que você configurou na grade de proteção é retornado no campo `output` ([ConverseOutput](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseOutput.html)). Com `ConverseStream`, o texto do conteúdo bloqueado está na mensagem transmitida. A resposta parcial a seguir mostra o texto do conteúdo bloqueado e o rastreamento da avaliação da barreira de proteção. A barreira de proteção bloqueou o termo *Heavy Metal* na mensagem. ``` { "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 } } } } } } } } ``` ## Exemplo de código para usar a API Converse com barreiras de proteção Este exemplo mostra como proteger uma conversa com as operações `Converse` e `ConverseStream`. O exemplo mostra como impedir que um modelo crie uma playlist que inclui músicas do gênero heavy metal. **Como proteger uma conversa** 1. Crie uma barreira de proteção seguindo as instruções em [Criar uma barreira de proteção](guardrails-components.md). + **Nome**: insira *Heavy metal*. + **Definição de tópico**: insira *Evitar mencionar músicas do gênero musical heavy metal*. + **Adicionar exemplos de frases**: insira *Criar uma playlist de músicas de heavy metal.* Na Etapa 9, insira o seguinte: + **Mensagens mostradas para prompts bloqueados**: insira *Desculpe, não posso responder a perguntas sobre música heavy metal.* + **Mensagens para respostas bloqueadas**: insira *Desculpe, o modelo gerou uma resposta que mencionava música heavy metal.* É possível configurar outras opções da barreira de proteção, mas isso não é necessário neste exemplo. 1. Crie uma versão da barreira de proteção seguindo as instruções em [Criar uma versão de uma barreira de proteção](guardrails-versions-create.md). 1. Nos exemplos de código a seguir ([Converse](#converse-api-guardrail-example-converse) e [ConverseStream](#converse-api-guardrail-example-converse-stream)), defina as seguintes variáveis: + `guardrail_id`: o ID das barreiras de proteção que você criou na Etapa 1. + `guardrail_version`: a versão da barreira de proteção que você criou na Etapa 2. + `text`: use `Create a playlist of heavy metal songs.` 1. Execute os exemplos de código. A saída deve exibir a avaliação da barreira de proteção e a mensagem de saída `Text: Sorry, I can't answer questions about heavy metal music.`. A avaliação da entrada da barreira de proteção mostra que o modelo detectou o termo *heavy metal* na mensagem de entrada. 1. (Opcional) Teste se a barreira de proteção bloqueia o texto impróprio que o modelo gera alterando o valor de `text` para *Listar todos os gêneros de música de rock*. Execute os exemplos novamente. Você deve ver uma avaliação de saída na resposta. ------ #### [ Converse ] O código a seguir usa a barreira de proteção com a operação `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 ] O código a seguir usa a barreira de proteção com a operação `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() ``` ------