Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
Utilizzare l’API ApplyGuardrail in un’applicazione
Guardrail viene utilizzato per implementare misure di protezione per le applicazioni di IA generativa, personalizzate per i tuoi casi d’uso e allineate alle tue policy di IA responsabile. Guardrail consente di configurare argomenti negati, filtrare i contenuti dannosi e rimuovere informazioni sensibili.
Puoi utilizzare l’API ApplyGuardrail per valutare qualsiasi testo utilizzando la tua versione preconfigurata di Guardrail per Amazon Bedrock, senza invocare i modelli di fondazione.
Le funzionalità dell’API ApplyGuardrail includono:
-
Convalida dei contenuti: puoi inviare qualsiasi input/output di testo all’API ApplyGuardrail per confrontarlo con le regole di esclusione degli argomenti, i filtri dei contenuti, i rilevatori di PII e gli elenchi di parole bloccate che hai definito. È possibile valutare gli input degli utenti e gli output generati da modelli di fondazione in modo indipendente.
-
Implementazione flessibile: è possibile integrare l’API ApplyGuardrail in qualsiasi punto del flusso dell’applicazione per convalidare i dati prima di elaborare o fornire i risultati all’utente. Ad esempio, se utilizzi un’applicazione RAG, ora puoi valutare l’input dell’utente prima di eseguire il recupero, invece di attendere la generazione della risposta finale.
-
Disaccoppiamento dai modelli di fondazione: l’API ApplyGuardrail è disaccoppiata dai modelli di fondazione. Ora puoi utilizzare Guardrail senza invocare i modelli di fondazione. Puoi utilizzare i risultati della valutazione per progettare l’esperienza sulla tua applicazione di IA generativa.
Chiamare ApplyGuardrail nel flusso della tua applicazione
La richiesta consente al cliente di passare tutto il contenuto che deve essere protetto utilizzando i guardrail definiti. Il campo source deve essere impostato su INPUT quando il contenuto da valutare proviene da un utente (in genere, il prompt di input del LLM). Il campo source deve essere impostato su OUTPUT quando devono essere applicati guardrail di output del modello (in genere, la risposta LLM).
Quando si utilizza ApplyGuardrail, si specificano gli elementi 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"
}
}
]
}
Casi d’uso di esempio di ApplyGuardrail
Il campo outputs della richiesta ApplyGuardrail dipende dall’azione intrapresa dal guardrail sul contenuto passato.
-
Se il guardrail è intervenuto dove il contenuto è solo mascherato, viene restituito il contenuto esatto con il mascheramento applicato.
-
Se il guardrail è intervenuto e ha bloccato il contenuto della richiesta, il campo outputs sarà un testo singolo, ovvero il messaggio predefinito basato sulla configurazione del guardrail.
-
Se non è stata intrapresa alcuna azione da parte del guardrail sul contenuto della richiesta, l’array outputs è vuoto.
- Guardrails takes no action
-
Esempio di richiesta
{
"source": "OUTPUT",
"content": [
"text": {
"text": "Hi, my name is Zaid. Which car brand is reliable?"
}
]
}
Esempio di risposta
{
"usage": {
"topicPolicyUnitsProcessed": 1,
"contentPolicyUnitsProcessed": 1,
"wordPolicyUnitsProcessed": 0,
"sensitiveInformationPolicyFreeUnits": 0
},
"action": "NONE",
"outputs": [],
"assessments": [{}]
}
- Guardrails blocks content
-
Esempio di risposta
{
"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
-
Esempio di risposta
Guardrail interviene mascherando il 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
-
Esempio di input
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
Esempio di output (blocca il contenuto)
{
"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"
}
]
}
}
]
}
Restituire l’output completo nella risposta di ApplyGuardrail
Il contenuto viene considerato rilevato se viola le configurazioni del guardrail. Ad esempio, la correlazione contestuale viene considerata rilevata se il punteggio di correlazione o pertinenza è inferiore alla soglia corrispondente.
Per impostazione predefinita, l’operazione ApplyGuardrail restituisce solo il contenuto rilevato in una risposta. È possibile specificare il campo outputScope con il valore FULL per restituire l’output completo. In questo caso, la risposta include anche voci non rilevate per un debug avanzato.
È possibile configurare lo stesso comportamento nelle operazioni Invoke e Converse impostando trace sull’opzione enabled full.
L’intero ambito di output non si applica ai filtri per parole o alle espressioni regolari nei filtri per informazioni sensibili. Si applica a tutte le altre policy di filtraggio, comprese le informazioni sensibili con filtri in grado di rilevare le Informazioni di identificazione personale (PII).
