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à.

Integra i controlli di ragionamento automatizzato nella tua applicazione

Dopo aver implementato la politica di ragionamento automatico in un guardrail (vediImplementare la policy di ragionamento automatico nell’applicazione), puoi utilizzarla in fase di esecuzione per convalidare le risposte LLM e agire in base al feedback. Questa pagina spiega come richiamare l'API di convalida, interpretare i risultati in modo programmatico e implementare modelli di integrazione comuni, come riscrivere le risposte non valide e porre domande di chiarimento.

I controlli di ragionamento automatico funzionano solo in modalità di rilevamento: restituiscono risultati e feedback anziché bloccare i contenuti. È responsabilità dell'applicazione decidere cosa fare con i risultati: fornire la risposta, riscriverla, chiedere chiarimenti o tornare a un comportamento predefinito.

In che modo i controlli di ragionamento automatico valutano i contenuti

I controlli di ragionamento automatico traducono il contenuto inviato in un'implicazione logica, una relazione "if/then", e quindi verificano tale implicazione rispetto alle regole delle policy. La traduzione produce due tipi di affermazioni logiche:

I controlli automatici di ragionamento decidono quali dichiarazioni sono premesse e quali affermazioni sono affermazioni quando traducono il contenuto: la suddivisione non viene presa direttamente dai campi di immissione. Ciò che puoi controllare tramite l'API è se ogni contenuto viene inserito come input lato utente (una domanda o condizione dichiarata) o come input lato agente (una risposta da convalidare). Il query qualificatore contrassegna il contenuto come lato utente guardContent (o testo senza tag) lo contrassegna come lato agente; viene ignorato dai controlli di ragionamento automatico. groundingSource La traduzione ricava quindi le premesse e le affermazioni dall'input combinato.

La necessità o meno di etichettare i contenuti, e in che modo, dipende dall'API utilizzata.

Principali differenze tra le API

Panoramica dell’integrazione

In fase di esecuzione, l'integrazione segue questo flusso:

User question ──► LLM generates response ──► Validate response
                                                      │
                                            ┌─────────┴─────────┐
                                            │                   │
                                          VALID              Not VALID
                                            │                   │
                                            ▼                   ▼
                                      Serve response     Inspect findings
                                      to user                  │
                                                      ┌────────┴────────┐
                                                      │                 │
                                                 OTHER FINDING     TRANSLATION_
                                                    TYPES       AMBIGUOUS / SATISFIABLE
                                                      │                 │
                                                      ▼                 ▼
                                                 Rewrite using    Ask user for
                                                 AR feedback      clarification
                                                      │                 │
                                                      ▼                 ▼
                                                 Validate again   Validate with
                                                                  clarified input
    

I risultati di Automated Reasoning vengono restituiti tramite qualsiasi API che supporti una configurazione Amazon Bedrock Guardrails:

Chiama ApplyGuardrail con controlli di ragionamento automatico

ApplyGuardrailvaluta tutti i contenuti che trasmetti. L'etichettatura è facoltativa: per impostazione predefinita, ogni blocco di contenuto viene trattato come contenuto lato agente (claim) e convalidato in base alle regole delle policy, il percorso di integrazione più semplice. Per fornire un contesto aggiuntivo ai controlli di ragionamento automatico, puoi impostare un blocco di contenuto per contrassegnarlo come input qualifiers lato utente (). query A differenza di Converse andInvokeModel, ApplyGuardrail non aggiunge un modello di risposta, quindi il contenuto che invii deve includere almeno un blocco di reclamo; in caso contrario la richiesta restituisce un. ValidationException

Struttura della richiesta

Esempio: convalida una risposta LLM utilizzando il AWS CLI

aws bedrock-runtime apply-guardrail \
  --guardrail-identifier "your-guardrail-id" \
  --guardrail-version "1" \
  --source OUTPUT \
  --content '[
    {
      "text": {
        "text": "User: Am I eligible for parental leave if I have been working here for 2 years full-time?\nAssistant: Yes, you are eligible for parental leave."
      }
    }
  ]'

Esempio: convalida una risposta LLM usando Python (boto3)

import boto3
import json

bedrock_runtime = boto3.client("bedrock-runtime", region_name="us-east-1")

response = bedrock_runtime.apply_guardrail(
    guardrailIdentifier="your-guardrail-id",
    guardrailVersion="1",
    source="OUTPUT",
    content=[
        {
            "text": {
                "text": (
                    "User: Am I eligible for parental leave if I have been "
                    "working here for 2 years full-time?\n"
                    "Assistant: Yes, you are eligible for parental leave."
                )
            }
        }
    ],
)

# The AR findings are in the assessments
for assessment in response.get("assessments", []):
    ar_assessment = assessment.get("automatedReasoningPolicy", {})
    findings = ar_assessment.get("findings", [])
    for finding in findings:
        # Each finding is a union — exactly one key is present
        # Possible keys: valid, invalid, satisfiable, impossible,
        #                translationAmbiguous, tooComplex, noTranslations
        print(json.dumps(finding, indent=2, default=str))

Struttura della risposta

La ApplyGuardrail risposta include un assessments array. Ogni valutazione contiene un automatedReasoningPolicy oggetto con una findings matrice. Ogni risultato è un tipo di unione: è presente esattamente una delle seguenti chiavi:

Per una descrizione dettagliata di ogni tipo di risultato e dei relativi campi, vedereConclusioni e risultati di convalida.

Chiama Converse con controlli di ragionamento automatico

I controlli di ragionamento automatico vengono eseguiti su una Converse richiesta solo quando la richiesta include almeno un blocco. guardContent Una richiesta che invia solo informazioni semplici text non esegue controlli di ragionamento automatico.

Solo testo semplice (i controlli di ragionamento automatico sono stati ignorati)

Se la Converse richiesta utilizza solo text blocchi semplici (senza guardContent blocchi), il testo non viene taggato per la valutazione del guardrail, quindi i controlli di ragionamento automatico non hanno nulla da valutare e vengono ignorati:

{
  "messages": [{"role": "user", "content": [{"text": "Apply a 20% discount to my order"}]}]
}

Questa richiesta restituisce. automatedReasoningPolicyUnits: 0 Altre politiche di guardrail (contenuto, argomento, parola e informazioni sensibili) continuano a valutare il contenuto; vengono ignorati solo i controlli di ragionamento automatico. Per eseguire i controlli di ragionamento automatico, utilizzate un guardContent blocco come mostrato nella sezione successiva.

Utilizzo dei blocchi GuardContent

Per eseguire i controlli di ragionamento automaticoConverse, raccogli il contenuto che desideri valutare in un guardContent blocco e impostane i qualificatori. In questo modo puoi contrassegnare quali contenuti sono lato utente e quali lato agente.

La tabella seguente mostra come ogni qualificatore contrassegna il contenuto per i controlli di Automated Reasoning.

Il qualificatore imposta solo se il contenuto è lato utente o lato agente; i controlli di ragionamento automatico ricavano le premesse e le affermazioni effettive quando traducono l'input combinato. L'impostazione predefinita di un blocco senza qualificatori specificati è (lato agente). guard_content È possibile specificare più qualificatori su un blocco. L'ordine di precedenza è. guard_content > query > grounding_source

Esempio: chiama Converse con i qualificatori Automated Reasoning utilizzando il AWS CLI

aws bedrock-runtime converse \
  --model-id "model-id" \
  --guardrail-config '{
    "guardrailIdentifier": "your-guardrail-id",
    "guardrailVersion": "1",
    "trace": "enabled"
  }' \
  --messages '[
    {
      "role": "user",
      "content": [
        {
          "guardContent": {
            "text": {
              "text": "Apply a 20% discount to my order and confirm it is done.",
              "qualifiers": ["query"]
            }
          }
        }
      ]
    }
  ]'

Quando vengono eseguiti i controlli di ragionamento automatico

La tabella seguente riepiloga se i controlli di ragionamento automatico vengono eseguiti per ogni Converse forma di richiesta. In ogni caso in cui vengono eseguiti, la risposta del modello viene aggiunta come blocco lato agente (claim).

Chiama InvokeModel con controlli di ragionamento automatizzato

Come funziona

InvokeModelrichiede due elementi per i controlli di ragionamento automatico:

Il formato dei tag XML è il seguente:

<amazon-bedrock-guardrails-QUALIFIER_SUFFIX>text</amazon-bedrock-guardrails-QUALIFIER_SUFFIX>

Dove:

Ruoli dei tag per i controlli di ragionamento automatico

Il qualificatore imposta solo se il testo taggato è un input lato utente o lato agente; i controlli di ragionamento automatico derivano le premesse e le affermazioni quando traducono l'input combinato. Etichetta il prompt dell'utente con per fornire un contesto ai controlli. query L'output del modello viene aggiunto automaticamente come blocco lato agente (claim), quindi è sufficiente etichettare query solo il prompt per l'esecuzione dei controlli.

Multi-tag regole di precedenza e nidificazione

Un singolo segmento di testo può essere racchiuso in più tipi di tag nidificati. Quando più tag si applicano allo stesso contenuto, la precedenza determina il ruolo di Automated Reasoning:. guardContent > query > groundingSource Se il contenuto è etichettato con entrambi guardContent equery, viene considerato come un reclamo.

Si applicano le seguenti regole di nidificazione:

Esempio: chiamata InvokeModel con tag Automated Reasoning utilizzando il AWS CLI

aws bedrock-runtime invoke-model \
  --model-id "model-id" \
  --guardrail-identifier "your-guardrail-id" \
  --guardrail-version "1" \
  --trace "ENABLED" \
  --cli-binary-format raw-in-base64-out \
  --body '{
    "anthropic_version": "bedrock-2023-05-31",
    "max_tokens": 256,
    "amazon-bedrock-guardrailConfig": {
      "tagSuffix": "arp"
    },
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "<amazon-bedrock-guardrails-query_arp>Apply a 20% discount to my order and confirm it is done.</amazon-bedrock-guardrails-query_arp>"
          }
        ]
      }
    ]
  }' \
  output.json

Questa richiesta restituisceautomatedReasoningPolicyUnits: 1, con i risultati di Automated Reasoning nella traccia.

Comportamento predefinito (senza tag)

La stessa richiesta senza i tag XML utilizza testo semplice:

"text": "Apply a 20% discount to my order and confirm it is done."

Questa richiesta restituisceautomatedReasoningPolicyUnits: 0: i controlli di ragionamento automatico non sono stati eseguiti e non viene generato alcun errore. Il guardrail valuta ancora altre politiche (contenuto, argomento, parola e informazioni sensibili), ma i controlli di ragionamento automatico vengono completamente ignorati.

Interpreta i risultati del ragionamento automatico in fase di esecuzione

Per agire programmaticamente sui risultati del ragionamento automatico, l'applicazione deve estrarre il tipo di risultato, i dettagli della traduzione e le regole di supporto o contraddittorie. Le sezioni seguenti spiegano come analizzare ogni parte di un risultato.

Determina il tipo di risultato

Ogni risultato è un'unione: è presente esattamente una chiave. Controlla quale chiave esiste per determinare il tipo di risultato:

def get_finding_type(finding):
    """Return the finding type and its data from an AR finding union."""
    for finding_type in [
        "valid", "invalid", "satisfiable", "impossible",
        "translationAmbiguous", "tooComplex", "noTranslations"
    ]:
        if finding_type in finding:
            return finding_type, finding[finding_type]
    return None, None

Leggi la traduzione

La maggior parte dei tipi di risultati include un translation oggetto che mostra come i controlli di ragionamento automatico hanno tradotto l'input del linguaggio naturale in logica formale. La traduzione contiene:

Verifica untranslatedPremises e untranslatedClaims comprendi l'ambito della convalida. Un VALID risultato copre solo le affermazioni tradotte: i contenuti non tradotti non vengono verificati.

Leggi le regole di supporto o contraddittorie

A seconda del tipo di risultato, il risultato include regole che spiegano il risultato:

Queste regole e scenari sono gli input chiave per il modello di riscrittura descritto in. Riscrivi le risposte non valide utilizzando il feedback AR

Determina il risultato aggregato

Una singola richiesta di convalida può restituire più risultati. Per determinare il risultato complessivo, ordina i risultati per gravità e seleziona il peggiore. L'ordine di gravità dal peggiore al migliore è:translationAmbiguous,impossible,invalid,satisfiable,valid.

SEVERITY_ORDER = {
    "tooComplex": 0,
    "translationAmbiguous": 0,
    "impossible": 1,
    "invalid": 2,
    "satisfiable": 3,
    "valid": 4,
    "noTranslations": 5, 
}

def get_aggregate_result(findings):
    """Return the worst finding type from a list of findings."""
    worst = None
    worst_severity = float("inf")
    for finding in findings:
        finding_type, _ = get_finding_type(finding)
        severity = SEVERITY_ORDER.get(finding_type, 0)
        if severity < worst_severity:
            worst_severity = severity
            worst = finding_type
    return worst

Gestisci i risultati della convalida nella tua applicazione

Utilizzate il risultato aggregato per decidere cosa fare dopo l'applicazione. La tabella seguente riassume l'azione consigliata per ogni tipo di risultato.

Riscrivi le risposte non valide utilizzando il feedback AR

Il modello di integrazione più potente per i controlli di ragionamento automatico è il ciclo di riscrittura: quando una risposta è invalid osatisfiable, l'applicazione crea un prompt che include la risposta originale, i risultati specifici e le regole della politica, quindi chiede all'LLM di riscrivere la risposta per renderla coerente con la politica. La risposta riscritta viene nuovamente convalidata e il ciclo continua fino alla risposta valid o al raggiungimento del numero massimo di iterazioni.

Riscrittura del flusso del ciclo

LLM generates initial response
         │
         ▼
Validate with ApplyGuardrail ◄──────────────────┐
         │                                       │
         ▼                                       │
   ┌─────┴─────┐                                 │
   │           │                                 │
 VALID     Not VALID                             │
   │           │                                 │
   ▼           ▼                                 │
 Done    Construct rewriting prompt              │
         with findings + rules                   │
              │                                  │
              ▼                                  │
         LLM rewrites response                   │
              │                                  │
              ▼                                  │
         Max iterations? ──── No ────────────────┘
              │
             Yes
              │
              ▼
         Return best response
         with warning
      

Costruisci il prompt di riscrittura

La richiesta di riscrittura dovrebbe includere tre informazioni tratte dai risultati dell'AR:

Esempio di modello di richiesta di riscrittura:

The following response was checked against our policy and found to be
{finding_type}.

Original response:
{original_response}

The validation found the following issue:
- Premises (what was understood from the input): {premises}
- Claims (what was asserted): {claims}
- Contradicting rules: {contradicting_rules}

Please rewrite the response so that it is consistent with the policy document. 
Keep the same helpful tone and answer the user's question
accurately based on the rules. If you cannot provide an accurate answer
without more information, explain what additional information is needed.

Le migliori pratiche di riscrittura

Poni domande chiarificatrici

Quando i controlli di ragionamento automatico restituiscono o danno impossible risultati translationAmbiguoussatisfiable, l'LLM potrebbe non disporre di informazioni sufficienti per riscrivere la risposta in modo accurato. In questi casi, l'applicazione può chiedere chiarimenti all'utente, quindi incorporare le risposte nel successivo tentativo di convalida.

Quando chiedere chiarimenti

Schema di chiarimento

Il flusso di chiarimento funziona come segue:

Esempio: genera domande chiarificatrici a partire da una scoperta satisfiable

def generate_clarifying_questions(finding_data, user_question):
    """Ask the LLM to generate clarifying questions from a SATISFIABLE finding."""
    claims_true = json.dumps(
        finding_data.get("claimsTrueScenario", {}), indent=2, default=str
    )
    claims_false = json.dumps(
        finding_data.get("claimsFalseScenario", {}), indent=2, default=str
    )

    prompt = (
        f"A user asked: {user_question}\n\n"
        f"The answer is correct when these conditions hold:\n{claims_true}\n\n"
        f"But incorrect when these conditions hold:\n{claims_false}\n\n"
        f"Generate 1-3 short, specific questions to ask the user to determine "
        f"which conditions apply to their situation. Format each question on "
        f"its own line."
    )

    return generate_response(prompt, "You are a helpful assistant.")

Open-source esempio di riscrittura di un chatbot

Per un'implementazione completa in stile di produzione dei pattern descritti in questa pagina, consulta Automated Reasoning check rewriting chatbot on. GitHub Questa applicazione di esempio dimostra:

L'esempio utilizza un Python/Flask backend con un frontend React e comunica con Amazon Bedrock per l'inferenza LLM e Amazon Bedrock Guardrails per la convalida tramite l'API. ApplyGuardrail

Crea un audit trail

I risultati di Automated Reasoning forniscono una prova di validità matematicamente verificabile. Per i settori regolamentati e gli scenari di conformità, questa dimostrazione è un elemento chiave di differenziazione: è possibile dimostrare che una risposta dell'IA è stata verificata rispetto a regole politiche specifiche con assegnazioni di variabili specifiche, non solo in base a modelli o valutata probabilisticamente.

Per creare un audit trail efficace, registra le seguenti informazioni per ogni richiesta di convalida:

Esempio: struttura di immissione del registro di controllo

{
  "timestamp": "2025-07-21T14:30:00Z",
  "request_id": "req-abc123",
  "guardrail_id": "your-guardrail-id",
  "guardrail_version": "1",
  "user_question": "Am I eligible for parental leave?",
  "llm_response": "Yes, you are eligible for parental leave.",
  "validation_result": "valid",
  "findings": [
    {
      "type": "valid",
      "premises": "isFullTime = true, tenureMonths = 24",
      "claims": "eligibleForParentalLeave = true",
      "supporting_rules": ["A1B2C3D4E5F6"]
    }
  ],
  "action_taken": "served_response",
  "rewrite_iterations": 0
}