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á.
Usar a API ApplyGuardrail na sua aplicação
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.
Chamar ApplyGuardrail no fluxo da aplicação
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).
Ao usar ApplyGuardrail, você especifica o guardrailIdentifierguardrailVersion
- 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 caso 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"
}
]
}
}
]
}
Exibir a saída completa na resposta ApplyGuardrail
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 operação ApplyGuardrail exibe 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.
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).
