Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés. # Inclusión de una barrera de protección con la API Converse Puede usar una barrera de protección para proteger las aplicaciones conversacionales que cree con la API de Converse. Por ejemplo, si crea una aplicación de chat con la API Converse, puede usar una barrera de protección para bloquear el contenido inapropiado introducido por el usuario y el contenido inapropiado generado por el modelo. Para obtener información acerca de la API de Converse, consulte [Cómo mantener una conversación con las operaciones de la API Converse](conversation-inference.md). **Topics** + [Llamada a la API Converse con barreras de protección](#guardrails-use-converse-api-call) + [Procesamiento de la respuesta cuando se usa la API Converse](#guardrails-use-converse-api-response) + [Ejemplo de código para usar la API Converse con barreras de protección](#converse-api-guardrail-example) ## Llamada a la API Converse con barreras de protección Para usar una barandilla, debes incluir la información de configuración de la barandilla en las llamadas a las operaciones de [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)(para transmitir respuestas). Si lo desea, puede seleccionar un contenido específico en el mensaje que desee que evalúe la barrera de protección. Para obtener más información acerca de los modelos que puede utilizar con barreras de protección y la API Converse, consulte [Modelos y características del modelo compatibles](conversation-inference-supported-models-features.md). **Topics** + [Configuración de una barrera de protección para que funcione con la API Converse](#guardrails-use-converse-api-call-configure) + [Evaluación de solo el contenido específico de un mensaje](#guardrails-use-converse-api-call-message) + [Protección de una petición del sistema enviada a la API Converse](#guardrails-use-converse-api-call-message-system-guard) + [Comportamiento de la barrera de protección de mensajes y peticiones del sistema](#guardrails-use-converse-api-call-message-system-message-guard) ### Configuración de una barrera de protección para que funcione con la API Converse La información de configuración de la barrera de protección se especifica en el parámetro de entrada `guardrailConfig`. La configuración incluye el ID y la versión de la barrera de protección que se desea utilizar. También se puede activar el seguimiento de la barrera de protección, que proporciona información sobre el contenido que ha bloqueado la barrera de protección. Con la `Converse` operación, `guardrailConfig` es un [GuardrailConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailConfiguration.html)objeto, como se muestra en el siguiente ejemplo. ``` { "guardrailIdentifier": "Guardrail ID", "guardrailVersion": "Guardrail version", "trace": "enabled" } ``` Si lo usas`ConverseStream`, pasas un [GuardrailStreamConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailStreamConfiguration.html)objeto. Si lo desea, puede usar el campo `streamProcessingMode` para especificar que desea que el modelo complete la evaluación de la barrera de protección antes de devolver los fragmentos de respuesta de la transmisión. O bien, puede hacer que el modelo responda de forma asíncrona mientras la barrera de protección continúa con la evaluación en segundo plano. Para obtener más información, consulte [Configuración del comportamiento de respuesta de transmisión para filtrar el contenido](guardrails-streaming.md). ### Evaluación de solo el contenido específico de un mensaje Al pasar un mensaje ([Message](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html)) a un modelo, la barrera de protección evalúa el contenido del mensaje. También puedes evaluar partes específicas de un mensaje mediante el campo `guardContent` ([GuardrailConverseContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailConverseContentBlock.html)). **sugerencia** El uso del `guardContent` campo es similar al uso de etiquetas de entrada con [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html)y [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html). Para obtener más información, consulte [Aplicación de etiquetas a las entradas de usuarios para filtrar el contenido](guardrails-tagging.md). Por ejemplo, la barrera de protección evalúa solo el contenido del campo `guardContent` y no el resto del mensaje. Esto es útil para que la barrera de protección solo evalúe el mensaje más reciente de una conversación, tal como se muestra en el siguiente ejemplo. ``` [ { "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." } } } ] } ] ``` Otro caso de uso de `guardContent` es proporcionar un contexto adicional para un mensaje, sin que la barrera de protección evalúe ese contexto. En el siguiente ejemplo, la barrera de protección solo evalúa `"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." } } } ] } ] ``` Si el contenido no está en un bloque `guardContent`, eso no significa necesariamente que no se vaya a evaluar. Este comportamiento depende de las políticas de filtrado que utilice la barrera de protección. El siguiente ejemplo muestra dos bloques `guardContent` con [verificaciones de fundamento contextual](guardrails-contextual-grounding-check.md) (basadas en los campos `qualifiers`). Las verificaciones de fundamento contextual de la barrera de protección solo evaluarán el contenido de estos bloques. Sin embargo, si la barrera de protección también tiene un [filtro de palabras](guardrails-content-filters.md) que bloquea la palabra “background”, el texto “Some additional background information.” se seguirá evaluando, aunque no esté en un bloque `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"] } } } ] }] ``` ### Protección de una petición del sistema enviada a la API Converse Puede usar barreras de protección con las peticiones del sistema que envíe a la API Converse. Para proteger un mensaje del sistema, especifica el campo `guardContent` ([SystemContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_SystemContentBlock.html)) en el mensaje del sistema que vas a pasar a la API, como se muestra en el siguiente ejemplo. ``` [ { "guardContent": { "text": { "text": "Only respond with Welsh heavy metal songs." } } } ] ``` Si no proporciona el campo `guardContent`, la barrera de protección no evaluará la petición del sistema. ### Comportamiento de la barrera de protección de mensajes y peticiones del sistema La forma en que la barrera de protección evalúa el campo `guardContent` es diferente entre las peticiones del sistema y los mensajes que se transmiten en el mensaje. | | La petición del sistema tiene un bloqueo de barrera de protección | La petición del sistema no tiene un bloqueo de barrera de protección | | --- | --- | --- | | **Los mensajes tienen un bloqueo de barrera de protección** | Sistema: la barrera de protección investiga el contenido del bloqueo de barrera de protección Mensajes: la barrera de protección investiga el contenido del bloqueo de barrera de protección | Sistema: la barrera de protección no investiga nada Mensajes: la barrera de protección investiga el contenido del bloqueo de barrera de protección | | **Los mensajes no tienen un bloqueo de barrera de protección** | Sistema: la barrera de protección investiga el contenido del bloqueo de barrera de protección Mensajes: la barrera de protección lo investiga todo | Sistema: la barrera de protección no investiga nada Mensajes: la barrera de protección lo investiga todo | ## Procesamiento de la respuesta cuando se usa la API Converse Al llamar a la operación Converse, la barrera de protección evalúa el mensaje que envía. Si la barrera de protección detecta contenido bloqueado, ocurrirá lo siguiente. + El campo `stopReason` en la respuesta se establece en `guardrail_intervened`. + Si has activado el rastreo, el rastreo estará disponible en el campo `trace` ([ConverseTrace](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseTrace.html)). Con`ConverseStream`, el rastreo está en los metadatos ([ConverseStreamMetadataEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStreamMetadataEvent.html)) que devuelve la operación. + El texto del contenido bloqueado que ha configurado en la barandilla se devuelve en el campo `output` ([ConverseOutput](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseOutput.html)). Con `ConverseStream`, el texto del contenido bloqueado aparece en el mensaje transmitido. La siguiente respuesta parcial muestra el texto del contenido bloqueado y el seguimiento obtenido de la evaluación de la barrera de protección. La barrera de protección ha bloqueado el término *Heavy metal* en el mensaje. ``` { "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 } } } } } } } } ``` ## Ejemplo de código para usar la API Converse con barreras de protección En este ejemplo, se muestra cómo proteger una conversación con las operaciones `Converse` y `ConverseStream`. El ejemplo muestra cómo evitar que una modelo cree una lista de reproducción que incluya canciones del género heavy metal. **Protección de una conversación** 1. Para crear una barrera de protección, siga las instrucciones en [Creación de una barrera de protección](guardrails-components.md). + **Nombre**: introduzca *Heavy metal*. + **Definición del tema**: introduzca *Avoid mentioning songs that are from the heavy metal genre of music.* + **Agregar frases de ejemplo**: introduzca *Create a playlist of heavy metal songs.* En el paso 9, indique lo siguiente: + **Se muestran los mensajes de las peticiones bloqueadas**: introduzca *Sorry, I can't answer questions about heavy metal music.* + **Mensajes en caso de respuestas bloqueadas**: introduzca *Sorry, the model generated an answer that mentioned heavy metal music.* Puede configurar otras opciones de barrera de protección, pero no es obligatorio para este ejemplo. 1. Para crear una versión de la barrera de protección, siga las instrucciones en [Creación de una versión de una barrera de protección](guardrails-versions-create.md). 1. En los siguientes ejemplos de código ([Converse](#converse-api-guardrail-example-converse) y [ConverseStream](#converse-api-guardrail-example-converse-stream)), defina las siguientes variables: + `guardrail_id`: ID de la barrera de protección que ha creado en el paso 1. + `guardrail_version`: versión de la barrera de protección que ha creado en el paso 2. + `text`: utilice `Create a playlist of heavy metal songs.`. 1. Ejecute los ejemplos de código. El resultado debe mostrar la evaluación de la barrera de protección y el mensaje de salida `Text: Sorry, I can't answer questions about heavy metal music.`. La evaluación de la entrada de la barrera de protección muestra que el modelo ha detectado el término *heavy metal* en el mensaje de entrada. 1. (Opcional) Compruebe que la barrera de protección bloquee el texto inapropiado que genera el modelo cambiando el valor de `text` por *List all genres of rock music.* Vuelva a ejecutar los ejemplos. Debería ver una evaluación del resultado en la respuesta. ------ #### [ Converse ] El siguiente código utiliza la barrera de protección en la operación `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 ] El siguiente código utiliza la barrera de protección en la operación `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() ``` ------