Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Integre las comprobaciones de razonamiento automatizadas en su aplicación

Después de implementar tu política de razonamiento automatizado en una barrera (consulteImplementación de la política de razonamiento automatizado en su aplicación), puedes usarla en tiempo de ejecución para validar las respuestas de la LLM y tomar medidas en función de los comentarios. En esta página, se explica cómo utilizar la API de validación, interpretar los resultados mediante programación e implementar patrones de integración comunes, como reescribir las respuestas no válidas y formular preguntas aclaratorias.

Las comprobaciones de razonamiento automatizadas solo funcionan en modo de detección: devuelven resultados y comentarios en lugar de bloquear el contenido. Tu aplicación es responsable de decidir qué hacer con los resultados: entregar la respuesta, reescribirla, pedir aclaraciones o volver a un comportamiento predeterminado.

Cómo evalúan el contenido las comprobaciones de razonamiento automatizadas

Las comprobaciones de razonamiento automatizadas traducen el contenido que envías en una implicación lógica (una «relaciónif/then») y, a continuación, comprueban esa implicación con respecto a las normas de tu política. La traducción produce dos tipos de enunciados lógicos:

Las verificaciones de razonamiento automatizadas deciden qué afirmaciones son premisas y cuáles son afirmaciones cuando traducen el contenido; la división no se extrae directamente de los campos de entrada. Lo que se controla a través de la API es si cada contenido se introduce como entrada del lado del usuario (una pregunta o condición declarada) o como entrada del lado del agente (una respuesta para validar). El query calificador marca el contenido como del lado del usuario guardContent (o texto sin etiquetar) lo marca como del lado del agente; las comprobaciones de razonamiento automatizadas lo ignoran. groundingSource A continuación, la traducción deduce las premisas y las afirmaciones a partir de la información combinada.

Si tienes que etiquetar el contenido y cómo hacerlo, depende de la API que utilices.

Diferencias clave entre las API

Información general de la integración

En tiempo de ejecución, la integración sigue este flujo:

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
    

Los resultados de Automated Reasoning se devuelven a través de cualquier API que admita una configuración de Amazon Bedrock Guardrails:

Llame ApplyGuardrail con comprobaciones de razonamiento automatizadas

ApplyGuardrailevalúa todo el contenido que apruebas. El etiquetado es opcional: de forma predeterminada, cada bloque de contenido se trata como contenido del lado del agente (reclamación) y se valida según las normas de su política, que es la vía de integración más sencilla. Para dar un contexto adicional a las comprobaciones de razonamiento automático, puedes configurar qualifiers un bloque de contenido para marcarlo como entrada del lado del usuario (). query A diferencia de Converse yInvokeModel, ApplyGuardrail no añade un modelo de respuesta para ti, el contenido que envíes debe incluir al menos un bloque de reclamación; de lo contrario, la solicitud devolverá un. ValidationException

Estructura de la solicitud

Ejemplo: valide una respuesta de LLM mediante el 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."
      }
    }
  ]'

Ejemplo: validar una respuesta LLM con 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))

Estructura de una respuesta

La ApplyGuardrail respuesta incluye una matriz. assessments Cada evaluación contiene un automatedReasoningPolicy objeto con una findings matriz. Cada hallazgo es de un tipo de unión; está presente exactamente una de las siguientes claves:

Para obtener una descripción detallada de cada tipo de hallazgo y sus campos, consulteHallazgos y resultados de validación.

Llame a Converse con comprobaciones de razonamiento automatizadas

Las comprobaciones de razonamiento automatizadas se ejecutan en una Converse solicitud solo cuando la solicitud incluye al menos un guardContent bloque. Una solicitud que se envía solo de forma simple text no ejecuta comprobaciones de razonamiento automatizadas.

Solo texto sin formato (se omiten las comprobaciones de razonamiento automatizadas)

Si tu Converse solicitud utiliza solo text bloques simples (sin guardContent bloques), el texto no se etiqueta para una evaluación exhaustiva, por lo que las comprobaciones de razonamiento automatizadas no tienen nada que evaluar y se omiten:

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

Se devuelve esta solicitud. automatedReasoningPolicyUnits: 0 Otras políticas cautelares (contenido, tema, palabra e información confidencial) siguen evaluando el contenido; solo se omiten las comprobaciones de razonamiento automatizadas. Para ejecutar comprobaciones de razonamiento automatizadas, usa un guardContent bloque como se muestra en la siguiente sección.

Uso de bloques GuardContent

Para ejecutar comprobaciones de razonamiento automatizadasConverse, agrupa el contenido que deseas evaluar en un guardContent bloque y establece sus calificadores. Así es como se marca qué contenido está del lado del usuario y cuál está del lado del agente.

La siguiente tabla muestra cómo cada calificador marca el contenido para las comprobaciones de razonamiento automatizadas.

El calificador establece únicamente si el contenido es del lado del usuario o del lado del agente; las comprobaciones de razonamiento automatizadas derivan de las premisas y afirmaciones reales al traducir la información combinada. Un bloque sin calificadores especificados tiene el valor predeterminado (del lado del agente). guard_content Puedes especificar varios calificadores en un bloque. El orden de prioridad es. guard_content > query > grounding_source

Ejemplo: llame a Converse con calificadores de razonamiento automático utilizando el 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"]
            }
          }
        }
      ]
    }
  ]'

Cuando se ejecutan las comprobaciones de razonamiento automático

En la siguiente tabla se resume si las comprobaciones de razonamiento automático se ejecutan para cada forma de Converse solicitud. En todos los casos en los que se ejecutan, la respuesta del modelo se adjunta como un bloque del lado del agente (reclamación).

Llame InvokeModel con comprobaciones de razonamiento automatizadas

Funcionamiento

InvokeModelrequiere dos cosas para las comprobaciones de razonamiento automatizadas:

El formato de la etiqueta XML es el siguiente:

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

Donde:

Etiquete las funciones para las comprobaciones de razonamiento automatizadas

El calificador solo establece si el texto etiquetado es una entrada del usuario o del lado del agente; las comprobaciones de razonamiento automatizadas derivan de las premisas y las afirmaciones cuando traducen la entrada combinada. Etiquete el mensaje del usuario query para contextualizar las comprobaciones. La salida del modelo se añade automáticamente como un bloque del lado del agente (reclamación), por lo que basta con etiquetar el mensaje query solo para que se ejecuten las comprobaciones.

Multi-tag reglas de precedencia y anidación

Un solo segmento de texto se puede incluir en varios tipos de etiquetas anidadas. Cuando se aplican varias etiquetas al mismo contenido, la prioridad determina la función de razonamiento automatizado:. guardContent > query > groundingSource Si el contenido está etiquetado con ambos guardContent yquery, se trata como una afirmación.

Se aplican las siguientes reglas de anidación:

Ejemplo: llame InvokeModel con etiquetas de razonamiento automatizado mediante el 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

Se devuelve esta solicitudautomatedReasoningPolicyUnits: 1, con los resultados del razonamiento automatizado en el seguimiento.

Comportamiento predeterminado (sin etiquetas)

La misma solicitud sin las etiquetas XML utiliza texto sin formato:

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

Esta solicitud devuelve el automatedReasoningPolicyUnits: 0 resultado: no se ejecutaron las comprobaciones de razonamiento automatizadas y no se produjo ningún error. La barandilla sigue evaluando otras políticas (contenido, tema, palabra e información confidencial), pero se omiten por completo las comprobaciones de razonamiento automático.

Interprete los hallazgos del razonamiento automatizado en tiempo de ejecución

Para actuar en función de los hallazgos del razonamiento automatizado de forma programática, tu aplicación debe extraer el tipo de hallazgo, los detalles de la traducción y las reglas que las respalden o contradigan. En las siguientes secciones se explica cómo analizar cada parte de un hallazgo.

Determine el tipo de hallazgo

Cada hallazgo es una unión: existe exactamente una clave. Compruebe qué clave existe para determinar el tipo de hallazgo:

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

Lea la traducción

La mayoría de los tipos de búsqueda incluyen un translation objeto que muestra cómo las comprobaciones de razonamiento automatizadas tradujeron la entrada del lenguaje natural en lógica formal. La traducción contiene:

Compruebe untranslatedPremises y untranslatedClaims comprenda el alcance de la validación. VALIDEl resultado solo cubre las afirmaciones traducidas; el contenido no traducido no se verifica.

Lee las reglas que respaldan o contradicen

Según el tipo de hallazgo, el hallazgo incluye reglas que explican el resultado:

Estas reglas y escenarios son las entradas clave para el patrón de reescritura descrito enReescribe las respuestas no válidas con comentarios de realidad aumentada.

Determine el resultado agregado

Una sola solicitud de validación puede arrojar varios resultados. Para determinar el resultado general, clasifique los hallazgos por gravedad y seleccione los peores. El orden de gravedad de peor a mejor es: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

Gestione los resultados de la validación en su aplicación

Utilice el resultado agregado para decidir qué hará su aplicación a continuación. En la siguiente tabla se resume la acción recomendada para cada tipo de resultado.

Reescribe las respuestas no válidas con comentarios de realidad aumentada

El patrón de integración más eficaz para las comprobaciones de razonamiento automatizadas es el ciclo de reescritura: cuando una respuesta es invalid osatisfiable, la aplicación crea un mensaje que incluye la respuesta original, los hallazgos específicos y las reglas de la política, y luego pide al LLM que reescriba la respuesta para que sea coherente con la política. La respuesta reescrita se valida de nuevo y el ciclo continúa hasta que la respuesta se alcanza valid o se alcanza un número máximo de iteraciones.

Flujo del bucle de reescritura

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
      

Construye el mensaje de reescritura

El mensaje de reescritura debe incluir tres datos extraídos de los hallazgos de la AR:

Ejemplo de plantilla de mensaje de reescritura:

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.

Mejores prácticas de reescritura

Haga preguntas aclaratorias

Cuando las comprobaciones de razonamiento automatizado translationAmbiguous satisfiable arrojen impossible resultados o resulten, es posible que el LLM no tenga suficiente información para reescribir la respuesta con precisión. En estos casos, la aplicación puede solicitar una aclaración al usuario y, a continuación, incorporar las respuestas en el siguiente intento de validación.

¿Cuándo pedir una aclaración

Patrón de aclaración

El flujo de clarificación funciona de la siguiente manera:

Ejemplo: generar preguntas aclaratorias a partir de un hallazgo 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 ejemplo de reescritura de chatbot

Para una implementación completa y al estilo de producción de los patrones descritos en esta página, consulta las comprobaciones de razonamiento automático sobre cómo reescribir el chatbot. GitHub En este ejemplo de aplicación se muestra lo siguiente:

El ejemplo utiliza un Python/Flask backend con una interfaz de React y se comunica con Amazon Bedrock para la inferencia LLM y con Amazon Bedrock Guardrails para la validación a través de la API. ApplyGuardrail

Cree un registro de auditoría

Los resultados del razonamiento automatizado proporcionan una prueba de validez matemáticamente verificable. En el caso de los sectores regulados y los escenarios de cumplimiento, esta prueba es un elemento diferenciador clave: se puede demostrar que la respuesta de la IA se verificó con arreglo a normas políticas específicas con asignaciones de variables específicas, y no solo se comparó con patrones o se evaluó probabilísticamente.

Para crear un registro de auditoría eficaz, registre la siguiente información para cada solicitud de validación:

Ejemplo: estructura de entradas del registro de auditoría

{
  "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
}