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.

Panoramica dell’integrazione

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

User question ──► LLM generates response ──► ApplyGuardrail validates 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:

Questa pagina si concentra sull'ApplyGuardrailAPI perché offre la massima flessibilità per l'implementazione dei modelli di riscrittura e chiarimento descritti di seguito. Per informazioni sull'utilizzo di guardrail con gli altri APIs, consulta Usare un guardrail.

Esempio di chatbot di riscrittura open source

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

Chiama ApplyGuardrail con controlli di ragionamento automatico

Usa l'ApplyGuardrailAPI per convalidare i contenuti rispetto al tuo guardrail. L'API accetta uno o più blocchi di contenuto e restituisce una valutazione che include i risultati del ragionamento automatico.

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.

Interpreta i risultati AR 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 è:TRANSLATION_AMBIGUOUS,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.")

Crea una pista di controllo

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
}