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 um aplicativo RAG, agora poderá avaliar a entrada do usuário antes de realizar 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).