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à. # Usa l' ApplyGuardrail API nella tua 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. **Topics** + [Richiamate il flusso ApplyGuardrail della vostra applicazione](#guardrails-use-independent-api-call) + [Specificare il guardrail da utilizzare con ApplyGuardrail](#guardrails-use-indepedent-api-call-configure) + [Esempi di casi d'uso di ApplyGuardrail](#guardrails-use-independent-api-call-message) + [Restituisce l'output completo in ApplyGuardrail risposta](#guardrails-use-return-full-assessment) ## Richiamate il flusso ApplyGuardrail della vostra 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). ## Specificare il guardrail da utilizzare con ApplyGuardrail Quando si utilizza `ApplyGuardrail`, si specificano gli elementi `{{guardrailIdentifier}}` e `{{guardrailVersion}}` del guardrail da utilizzare. È possibile anche abilitare il tracciamento del guardrail, che fornisce informazioni sui contenuti bloccati dal guardrail. ------ #### [ 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" } } ] } ``` ------ ## Esempi di casi d'uso 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" } ] } } ] } ``` ------ ## Restituisce l'output completo in ApplyGuardrail risposta 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'[ApplyGuardrail](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ApplyGuardrail.html)operazione 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. **Nota** 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).