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á. # Use a ApplyGuardrail API em seu aplicativo As barreiras de proteção são usadas para implementar proteções nas aplicações de IA generativa personalizadas para os casos de uso e alinhadas às políticas de IA responsável. As barreiras de proteção permitem configurar tópicos negados, filtrar conteúdo prejudicial e remover informações confidenciais. É possível usar a API `ApplyGuardrail` para avaliar qualquer texto usando as suas barreiras de proteção do Amazon Bedrock pré-configuradas, sem invocar os modelos de base. Os recursos da API `ApplyGuardrail` incluem: + **Validação de conteúdo**: é possível enviar qualquer entrada ou saída de texto à API `ApplyGuardrail` para compará-la com as regras de rejeição de tópicos, os filtros de conteúdo, os detectores de PII e as listas de bloqueio de palavras que você definiu. É possível avaliar as entradas do usuário e as saídas geradas por FM de forma independente. + **Implantação flexível**: é possível integrar a API `ApplyGuardrail` em qualquer lugar no fluxo da aplicação para validar os dados antes de processar ou fornecer resultados ao usuário. Por exemplo, se você estiver usando uma aplicação de RAG, agora poderá avaliar a entrada do usuário antes de executar a recuperação, em vez de esperar até a geração final da resposta. + **Desacoplamento em relação aos modelos de base**: a API `ApplyGuardrail` está desacoplada dos modelos de base. Agora é possível usar as barreiras de proteção sem invocar os modelos de base. É possível usar os resultados da avaliação para criar a experiência em sua aplicação de IA generativa. **Topics** + [Ligue para ApplyGuardrail o fluxo do seu aplicativo](#guardrails-use-independent-api-call) + [Especifique a grade de proteção a ser usada com ApplyGuardrail](#guardrails-use-indepedent-api-call-configure) + [Exemplos de casos de uso de ApplyGuardrail](#guardrails-use-independent-api-call-message) + [Retorna a saída completa em ApplyGuardrail resposta](#guardrails-use-return-full-assessment) ## Ligue para ApplyGuardrail o fluxo do seu aplicativo A solicitação permite que o cliente transmita todo o conteúdo que deve ser protegido usando suas barreiras de proteção definidas. O campo de origem deve ser definido como `INPUT` quando o conteúdo a ser avaliado é de um usuário (normalmente o prompt de entrada para o LLM). A fonte deve ser definida como `OUTPUT` quando as barreiras de proteção de saída do modelo devem ser aplicadas (normalmente a resposta do LLM). ## Especifique a grade de proteção a ser usada com ApplyGuardrail Ao usar `ApplyGuardrail`, você especifica o `guardrailIdentifier` e a `guardrailVersion` da barreira de proteção que 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. ------ #### [ ApplyGuardrail API request ] ``` POST /guardrail/{guardrailIdentifier}/version/{guardrailVersion}/apply HTTP/1.1 { "source": "INPUT" | "OUTPUT", "content": [{ "text": { "text": "string", } }, ] } ``` ------ #### [ ApplyGuardrail API response ] ``` { "usage": { "topicPolicyUnits": "integer", "contentPolicyUnits": "integer", "wordPolicyUnits": "integer", "sensitiveInformationPolicyUnits": "integer", "sensitiveInformationPolicyFreeUnits": "integer", "contextualGroundingPolicyUnits": "integer" }, "action": "GUARDRAIL_INTERVENED" | "NONE", "output": [ // if guardrail intervened and output is masked we return request in same format // with masking // if guardrail intervened and blocked, output is a single text with canned message // if guardrail did not intervene, output is empty array { "text": "string", }, ], "assessments": [{ "topicPolicy": { "topics": [{ "name": "string", "type": "DENY", "action": "BLOCKED", }] }, "contentPolicy": { "filters": [{ "type": "INSULTS | HATE | SEXUAL | VIOLENCE | MISCONDUCT |PROMPT_ATTACK", "confidence": "NONE" | "LOW" | "MEDIUM" | "HIGH", "filterStrength": "NONE" | "LOW" | "MEDIUM" | "HIGH", "action": "BLOCKED" }] }, "wordPolicy": { "customWords": [{ "match": "string", "action": "BLOCKED" }], "managedWordLists": [{ "match": "string", "type": "PROFANITY", "action": "BLOCKED" }] }, "sensitiveInformationPolicy": { "piiEntities": [{ // for all types see: https://docs.aws.amazon.com/bedrock/latest/APIReference/API_GuardrailPiiEntityConfig.html#bedrock-Type-GuardrailPiiEntityConfig-type "type": "ADDRESS" | "AGE" | ..., "match": "string", "action": "BLOCKED" | "ANONYMIZED" }], "regexes": [{ "name": "string", "regex": "string", "match": "string", "action": "BLOCKED" | "ANONYMIZED" }], "contextualGroundingPolicy": { "filters": [{ "type": "GROUNDING | RELEVANCE", "threshold": "double", "score": "double", "action": "BLOCKED | NONE" }] }, "invocationMetrics": { "guardrailProcessingLatency": "integer", "usage": { "topicPolicyUnits": "integer", "contentPolicyUnits": "integer", "wordPolicyUnits": "integer", "sensitiveInformationPolicyUnits": "integer", "sensitiveInformationPolicyFreeUnits": "integer", "contextualGroundingPolicyUnits": "integer" }, "guardrailCoverage": { "textCharacters": { "guarded":"integer", "total": "integer" } } } }, "guardrailCoverage": { "textCharacters": { "guarded": "integer", "total": "integer" } } ] } ``` ------ ## Exemplos de casos de uso de ApplyGuardrail As saídas da solicitação `ApplyGuardrail` dependem da ação tomada pela barreira de proteção no conteúdo passado. + Se a barreira de proteção interveio no conteúdo que estava apenas mascarado, o conteúdo exato será retornado com o mascaramento aplicado. + Se a barreira de proteção interveio e bloqueou o conteúdo da solicitação, o campo de saídas será um único texto, que é a mensagem predefinida com base na configuração da barreira de proteção. + Se nenhuma ação da barreira de proteção tiver sido tomada no conteúdo da solicitação, a matriz de saídas estará vazia. ------ #### [ Guardrails takes no action ] **Exemplo de solicitação** ``` { "source": "OUTPUT", "content": [ "text": { "text": "Hi, my name is Zaid. Which car brand is reliable?" } ] } ``` **Exemplo de resposta** ``` { "usage": { "topicPolicyUnitsProcessed": 1, "contentPolicyUnitsProcessed": 1, "wordPolicyUnitsProcessed": 0, "sensitiveInformationPolicyFreeUnits": 0 }, "action": "NONE", "outputs": [], "assessments": [{}] } ``` ------ #### [ Guardrails blocks content ] **Exemplo de resposta** ``` { "usage": { "topicPolicyUnitsProcessed": 1, "contentPolicyUnitsProcessed": 1, "wordPolicyUnitsProcessed": 0, "sensitiveInformationPolicyFreeUnits": 0 }, "action": "GUARDRAIL_INTERVENED", "outputs": [{ "text": "Configured guardrail canned message (i.e., can't respond)" }], "assessments": [{ "topicPolicy": { "topics": [{ "name": "Cars", "type": "DENY", "action": "BLOCKED" }] }, "sensitiveInformationPolicy": { "piiEntities": [{ "type": "NAME", "match": "ZAID", "action": "ANONYMIZED" }], "regexes": [] } }] } ``` ------ #### [ Guardrails masks content ] **Exemplo de resposta** As barreiras de proteção intervêm mascarando o nome `ZAID`. ``` { "usage": { "topicPolicyUnitsProcessed": 1, "contentPolicyUnitsProcessed": 1, "wordPolicyUnitsProcessed": 0, "sensitiveInformationPolicyFreeUnits": 0 }, "action": "GUARDRAIL_INTERVENED", "outputs": [{ "text": "Hi, my name is {NAME}. Which car brand is reliable?" }, { "text": "Hello {NAME}, ABC Cars are reliable ..." } ], "assessments": [{ "sensitiveInformationPolicy": { "piiEntities": [{ "type": "NAME", "match": "ZAID", "action": "ANONYMIZED" }], "regexes": [] } }] } ``` ------ #### [ AWS CLI example ] **Exemplo de entrada** ``` aws bedrock-runtime apply-guardrail \ --cli-input-json '{ "guardrailIdentifier": "someGuardrailId", "guardrailVersion": "DRAFT", "source": "INPUT", "content": [ { "text": { "text": "How should I invest for my retirement? I want to be able to generate $5,000 a month" } } ] }' \ --region us-east-1 \ --output json ``` **Exemplo de saída (bloqueia o conteúdo)** ``` { "usage": { "topicPolicyUnits": 1, "contentPolicyUnits": 1, "wordPolicyUnits": 1, "sensitiveInformationPolicyUnits": 1, "sensitiveInformationPolicyFreeUnits": 0 }, "action": "GUARDRAIL_INTERVENED", "outputs": [ { "text": "I apologize, but I am not able to provide fiduciary advice. =" } ], "assessments": [ { "topicPolicy": { "topics": [ { "name": "Fiduciary Advice", "type": "DENY", "action": "BLOCKED" } ] } } ] } ``` ------ ## Retorna a saída completa em ApplyGuardrail resposta O conteúdo é considerado detectado se violar suas configurações de barreira de proteção. Por exemplo, a base contextual é considerada detectada se a pontuação de fundamentação ou relevância for menor que o limite correspondente. Por padrão, a [ApplyGuardrail](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ApplyGuardrail.html)operação retorna somente o conteúdo detectado em uma resposta. Você pode especificar o campo `outputScope` com o valor `FULL` para exibir a saída completa. Nesse caso, a resposta também incluirá entradas não detectadas para aprimorar a depuração. É possível configurar esse mesmo comportamento nas operações `Invoke` e `Converse` definindo o rastreamento para a opção completa habilitada. **nota** O escopo completo da saída não se aplica a filtros de palavras ou regex em filtros de informações sensíveis. Ele se aplica a todas as outras políticas de filtragem, inclusive de informações sensíveis com filtros que podem detectar informações de identificação pessoal (PII).