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 (vedi[Implementare la policy di ragionamento automatico nell’applicazione](deploy-automated-reasoning-policy.md)), 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:
+ **Premesse** — Il lato «se»: le condizioni antecedenti e i fatti dello scenario che definiscono il contesto del ragionamento (ad esempio, un fatto dichiarato dall'utente sulla propria situazione o una condizione da cui dipende la risposta). Le premesse sono facoltative.
+ **Affermazioni**: il lato opposto: le affermazioni da convalidare rispetto alle regole politiche (in genere le dichiarazioni sostanziali contenute nella risposta del modello).
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.
| "Hello, World\!" | È richiesta l'etichettatura? | In che modo i contenuti entrano nei controlli di ragionamento automatico |
| --- | --- | --- |
| ApplyGuardrail | No (opzionale) | Tutti i contenuti che trasmetti vengono valutati. Ogni blocco di contenuto è qualifiers impostato se deve essere immesso come input lato utente (query) o lato agente (guard\_content); un blocco senza qualificatore utilizza di default il lato agente. ApplyGuardrailnon aggiunge un modello di risposta per tuo conto, quindi i tuoi contenuti devono includere almeno un blocco lato agente (claim). |
| Converse(solo testo semplice) | Sì | I text blocchi semplici non sono etichettati, quindi i controlli di ragionamento automatico non hanno alcun contenuto da valutare e vengono ignorati ()automatedReasoningPolicyUnits: 0. Usa un guardContent blocco per attivare. |
| Converse (con guardContent) | Sì | Utilizzalo qualifiers sui guardContent blocchi per contrassegnare i contenuti lato utente e lato agente. La risposta del modello viene aggiunta automaticamente come blocco lato agente (claim). |
| InvokeModel | Sì | Raccogli il testo di input nei tag XML e impostalo tagSuffix nella configurazione della richiesta. La risposta del modello viene aggiunta automaticamente come blocco lato agente (claim). |
### Principali differenze tra le API
+ Su `Converse` e`InvokeModel`, la risposta del modello viene aggiunta automaticamente come blocco lato agente (claim). Di conseguenza, un input a cui si assegna solo un tag esegue `query` comunque i controlli di ragionamento automatico: la risposta fornisce l'attestazione.
+ L'omissione di tag o l'invio di solo testo semplice non produce un errore`Converse`, ma i controlli di ragionamento automatico non vengono applicati. `InvokeModel` La risposta lo indica con. `automatedReasoningPolicyUnits: 0`
+ Sì`InvokeModel`, il testo tra tag XML di guardrail che non contiene qualificatori è impostato come predefinito sul lato agente (claim).
+ I controlli di ragionamento automatizzato valutano la risposta (il contenuto lato agente); non vengono eseguiti su una valutazione autonoma. `INPUT`
+ Con`ApplyGuardrail`, non ti viene aggiunta alcuna risposta modello, quindi il contenuto che invii deve includere almeno un blocco lato agente (claim). In caso contrario, la richiesta restituisce un. `ValidationException`
## 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:
+ `ApplyGuardrail`— API di convalida autonoma. Usala quando desideri convalidare il contenuto indipendentemente dall'invocazione LLM. Questo è l'approccio consigliato per i controlli di ragionamento automatico perché offre il pieno controllo su quali contenuti vengono convalidati e quando.
+ `Converse`e `InvokeModel` — API di invocazione LLM con configurazione guardrail. I risultati del ragionamento automatico vengono restituiti nel campo della risposta. `trace`
## Chiama ApplyGuardrail con controlli di ragionamento automatico
`ApplyGuardrail`valuta 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` and`InvokeModel`, `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
`guardrailIdentifier`(richiesto)
L'ID o l'ARN del guardrail. Usa il guardrail a cui è allegata la tua politica di ragionamento automatizzato.
`guardrailVersion`(richiesto)
Il numero di versione del guardrail (ad esempio,`1`). Usa una versione numerata per i carichi di lavoro di produzione, no. `DRAFT`
`source`(richiesto)
Impostato su `OUTPUT` durante la convalida delle risposte LLM. Imposta su `INPUT` quando si convalidano le istruzioni dell'utente. Per i controlli di ragionamento automatico, in genere si convalida l'output LLM.
`content`(richiesto)
Una serie di blocchi di contenuto da convalidare. Ogni blocco contiene un `text` campo con il contenuto da controllare. Puoi passare la domanda dell'utente e la risposta LLM come blocchi di contenuto separati o combinarli in un unico blocco.
### 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:
+ `valid`
+ `invalid`
+ `satisfiable`
+ `impossible`
+ `translationAmbiguous`
+ `tooComplex`
+ `noTranslations`
Per una descrizione dettagliata di ogni tipo di risultato e dei relativi campi, vedere[Conclusioni e risultati di convalida](automated-reasoning-checks-concepts.md#ar-concept-findings).
## 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.
**Importante**
Quando i controlli di ragionamento automatico vengono ignorati, la richiesta ha comunque esito positivo senza errori, quindi una richiesta configurata in modo errato può non essere convalidata automaticamente. Conferma sempre la tua configurazione controllando che sia `automatedReasoningPolicyUnits` maggiore rispetto alla risposta. `0` Un valore di `0` significa che i controlli di ragionamento automatico non sono stati eseguiti (ad esempio, perché il contenuto non è stato taggato), anche se la richiesta ha avuto esito positivo.
### Utilizzo dei blocchi GuardContent
Per eseguire i controlli di ragionamento automatico`Converse`, 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.
**Nota**
L'`Converse`API utilizza snake\_case per le stringhe di qualificazione (`guard_content`,`grounding_source`), mentre i `InvokeModel` tag XML utilizzano camelCase (,). `guardContent` `groundingSource` Questi mappano agli stessi ruoli sottostanti.
La tabella seguente mostra come ogni qualificatore contrassegna il contenuto per i controlli di Automated Reasoning.
| Stringa di qualificazione (snake\_case) | Equivalente al tag XML (CamelCase) | Ruolo di input di Automated Reasoning |
| --- | --- | --- |
| "query" | query | User-side— la domanda o le condizioni dichiarate dall'utente. Fornisce un contesto da cui la traduzione può trarre le premesse. |
| "guard\_content" | guardContent | Agent-side— contenuti da convalidare in base alla tua politica. Fornisce i reclami controllati dalla traduzione. |
| "grounding\_source" | groundingSource | Ignorato dai controlli di ragionamento automatico (utilizzati dai controlli contestuali di base). |
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`
**Nota**
Sì`Converse`, la risposta del modello viene aggiunta automaticamente come blocco lato agente (claim), quindi una richiesta il cui utilizzo solo dei blocchi esegue `query` comunque i controlli di ragionamento automatico. (Quando si chiama `ApplyGuardrail` direttamente, non viene aggiunta alcuna risposta, quindi è necessario fornire personalmente almeno un blocco lato agente o la richiesta restituisce un.) `ValidationException`
### 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).
| Forma della richiesta | I controlli di ragionamento automatizzato vengono eseguiti? |
| --- | --- |
| Solo text blocchi semplici, no guardContent | No, il contenuto non è taggato, quindi i controlli vengono ignorati () automatedReasoningPolicyUnits: 0 |
| Ha guardContent blocchi con guard\_content o senza qualificatori | Sì |
| Ha guardContent blocchi con solo query | Sì, il modello di risposta allegato fornisce l'affermazione |
| Ha guardContent blocchi con solo grounding\_source | Sì, il modello di risposta allegato fornisce l'affermazione. Il grounding\_source blocco stesso viene ignorato (non fornisce né una premessa né un'affermazione), ma la richiesta continua a essere eseguita perché la risposta fornisce il contenuto dell'affermazione. |
## Chiama InvokeModel con controlli di ragionamento automatizzato
**avvertimento**
È necessario contrassegnare i dati inseriti con tag guardrail XML per consentire ai controlli di ragionamento automatico di valutare le risposte. Senza tag, i controlli di ragionamento automatico restituiscono`automatedReasoningPolicyUnits: 0`: non viene generato alcun errore e non viene effettuata alcuna valutazione.
### Come funziona
`InvokeModel`richiede due elementi per i controlli di ragionamento automatico:
1. A `tagSuffix` nell'`amazon-bedrock-guardrailConfig`oggetto del corpo.
1. Inserisci testo racchiuso in tag XML che utilizzano quel suffisso.
Il formato dei tag XML è il seguente:
```
text
```
Dove:
+ {{QUALIFIER}}è uno di `query``guardContent`, o `groundingSource` (CamelCase in XML).
+ {{SUFFIX}}corrisponde al `tagSuffix` valore nel corpo della richiesta.
+ `tagSuffix`deve corrispondere al modello `^[a-zA-Z0-9][a-zA-Z0-9-_]{0,18}[a-zA-Z0-9]$` (2—20 caratteri).
### Ruoli dei tag per i controlli di ragionamento automatico
| Qualificatore di tag XML | Ruolo di input di Automated Reasoning | Significato |
| --- | --- | --- |
| query | User-side | La domanda o le condizioni dichiarate dall'utente. Fornisce un contesto da cui la traduzione può trarre le premesse. |
| guardContent | Agent-side | Contenuti da convalidare in base alla tua politica. Fornisce i reclami controllati dalla traduzione. |
| groundingSource | Ignorato | Non utilizzato dai controlli di ragionamento automatico (utilizzati dai controlli di base contestuali). |
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.
**Nota**
Per impostazione predefinita, il testo tra i tag guardrail che non contiene alcun qualificatore è il contenuto lato agente (claim). Perché `InvokeModel` aggiunge la risposta del modello come affermazione, una richiesta che contrassegna il prompt solo con esegue comunque i controlli di ragionamento automatico. `query` (Ciò è diverso da una `ApplyGuardrail` chiamata diretta, che non aggiunge alcuna risposta e quindi restituisce un messaggio `ValidationException` se non si fornisce alcun contenuto relativo al claim.)
### 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` e`query`, viene considerato come un reclamo.
Si applicano le seguenti regole di nidificazione:
+ È possibile annidare tag di diversi tipi (ad esempio,`text`).
+ I tag dello stesso tipo non possono essere annidati automaticamente e i tag devono essere chiusi nell'ordine inverso rispetto a quello in cui sono stati aperti. Una struttura di tag non valida restituisce un. `ValidationException`
### 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": "Apply a 20% discount to my order and confirm it is done."
}
]
}
]
}' \
output.json
```
Questa richiesta restituisce`automatedReasoningPolicyUnits: 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 restituisce`automatedReasoningPolicyUnits: 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:
+ `premises`— Le condizioni estratte dall'input (ad esempio`isFullTime = true`,`tenureMonths = 24`).
+ `claims`— Le asserzioni da convalidare (ad esempio,). `eligibleForParentalLeave = true`
+ `untranslatedPremises`— Parti dell'input che non possono essere mappate su variabili politiche. Queste parti non sono convalidate.
+ `untranslatedClaims`— Affermazioni che non possono essere mappate su variabili politiche.
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:
+ `valid`i risultati includono`supportingRules`: le regole politiche che dimostrano la correttezza delle affermazioni.
+ `invalid`i risultati includono`contradictingRules`: le regole politiche violate dalle affermazioni.
+ `satisfiable`i risultati includono sia a che a`claimsFalseScenario`, `claimsTrueScenario` e mostrano le condizioni in base alle quali le affermazioni sono vere e false.
Queste regole e scenari sono gli input chiave per il modello di riscrittura descritto in. [Riscrivi le risposte non valide utilizzando il feedback AR](#rewrite-invalid-responses)
### 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.
| Risultato | Significato | Azione consigliata |
| --- | --- | --- |
| valid | La risposta si è dimostrata matematicamente corretta, date le premesse e le regole della politica. | Fornisci la risposta all'utente. Registra i risultati a fini di controllo (vedi[Crea un audit trail](#build-audit-trail)). |
| invalid | La risposta contraddice le vostre regole politiche. Il contradictingRules campo identifica quali regole sono state violate. | Riscrivi la risposta utilizzando il feedback di Automated Reasoning (vedi). [Riscrivi le risposte non valide utilizzando il feedback AR](#rewrite-invalid-responses) Se la riscrittura fallisce dopo più tentativi, blocca la risposta e restituisci un messaggio di fallback. |
| satisfiable | La risposta è corretta in alcune condizioni, ma non in tutte. Non è sbagliato, ma è incompleto: non menziona tutti i requisiti. | Riscrivi la risposta per includere le condizioni mancanti. Usa il claimsFalseScenario per identificare ciò che manca. In alternativa, puoi lasciare che il tuo LLM chieda chiarimenti all'utente. |
| impossible | Le premesse sono contraddittorie o la politica contiene regole contrastanti. | Chiedi all'utente di chiarire il proprio input (vedi). [Poni domande chiarificatrici](#ask-clarifying-questions) Se il problema persiste, potrebbe indicare un problema relativo alle politiche: consulta il rapporto sulla qualità. |
| translationAmbiguous | L'input ha diverse interpretazioni valide. I modelli di traduzione non erano d'accordo su come mappare il linguaggio naturale alle variabili politiche. | Chiedi chiarimenti all'utente per risolvere l'ambiguità. Utilizza i differenceScenarios campi options e per generare domande di chiarimento mirate. |
| tooComplex | L'input supera i limiti di elaborazione per l'analisi logica. | Semplifica l'input suddividendolo in parti più piccole o restituisci un messaggio di fallback che spiega che la risposta non può essere verificata. |
| noTranslations | L'input non è rilevante per il dominio della tua politica. Non è stato possibile mappare alcuna variabile di policy. | Il contenuto di questa politica non è tematico. Fornisci la risposta senza la convalida AR o utilizza altri componenti di guardrail (come le politiche tematiche) per gestire i contenuti fuori tema. |
## 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` o`satisfiable`, 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:
1. La risposta originale che non è riuscita a convalidare.
1. La constatazione specifica, comprese le premesse tradotte, le affermazioni e le regole contraddittorie o di supporto.
1. Un'istruzione per riscrivere la risposta in modo che sia coerente con le regole politiche.
**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.
```
**Suggerimento**
Includi sempre il contenuto di Retrieval Augmented Generation (RAG) nelle richieste di riscrittura o nelle regole delle policy in modo che l'LLM abbia tutto il contesto di cui ha bisogno durante la riscrittura. Il modello di richiesta di riscrittura fornisce i dettagli specifici dei risultati, mentre il prompt di sistema fornisce un contesto politico più ampio. [Questo approccio a doppio contesto è illustrato nell'esempio di chatbot di riscrittura open source.](https://github.com/aws-samples/amazon-bedrock-samples/tree/main/responsible_ai/automated-reasoning-rewriting-chatbot)
### Le migliori pratiche di riscrittura
+ **Imposta un numero massimo di iterazioni.** Il ciclo di riscrittura deve avere un limite rigido (in genere 2-5 iterazioni) per evitare cicli infiniti. Se la risposta non ha ancora raggiunto il numero massimo di iterazioni, restituisci la risposta migliore con un avviso o `valid` torna a un messaggio predefinito.
+ **Elabora i risultati in ordine di priorità.** Quando vengono restituiti più risultati, affronta prima il risultato più grave. L'ordine di gravità è:`translationAmbiguous`,`impossible`,`invalid`,`satisfiable`,`valid`.
+ **Includi il contesto delle politiche nel prompt di sistema.** L'LLM deve accedere al documento di origine o alle regole politiche complete per riscriverlo con precisione. È possibile utilizzare una [Knowledge Base](https://docs.aws.amazon.com/bedrock/latest/userguide/knowledge-base.html) per includere i documenti nella richiesta di generazione o utilizzare l'`ExportAutomatedReasoningPolicyVersion`API per recuperare la definizione della politica e formattarla per il LLM.
+ **Registra ogni iterazione.** Registra la risposta originale, i risultati, la richiesta di riscrittura e la risposta riscritta per ogni iterazione. Questa pista di controllo è utile per il debug e la conformità (vedi). [Crea un audit trail](#build-audit-trail)
## Poni domande chiarificatrici
Quando i controlli di ragionamento automatico restituiscono o danno `impossible` risultati `translationAmbiguous``satisfiable`, 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
+ **`translationAmbiguous`**— L'input ha più interpretazioni valide. Il `options` campo mostra le interpretazioni concorrenti e il `differenceScenarios` campo mostra come differiscono nella pratica. Usali per generare domande mirate sull'ambiguità specifica.
+ **`satisfiable`**— La risposta è corretta in alcune condizioni, ma non in tutte. `claimsFalseScenario`Mostra le condizioni in base alle quali la risposta sarebbe errata. Chiedi all'utente informazioni su queste condizioni specifiche.
+ **`impossible`**— L'input contiene affermazioni contraddittorie. Chiedi all'utente di chiarire la contraddizione.
+ **Riscrittura fallita**: se il LLM non è in grado di riscrivere la risposta in base a `valid` dopo più tentativi, potrebbe essere necessario un contesto aggiuntivo da parte dell'utente. Chiedi all'LLM di generare domande chiarificatrici sulla base dei risultati.
### Schema di chiarimento
Il flusso di chiarimento funziona come segue:
1. Estrai le variabili ambigue o le condizioni mancanti dai risultati AR.
1. Genera domande chiarificatrici, in modo programmatico dai campi di ricerca o chiedendo all'LLM di formulare domande sulla base dei risultati.
1. Presenta le domande all'utente e raccogli le risposte.
1. Incorpora le risposte nel contesto e genera una nuova risposta.
1. Convalida la nuova risposta con`ApplyGuardrail`.
**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](https://github.com/aws-samples/amazon-bedrock-samples/tree/main/responsible_ai/automated-reasoning-rewriting-chatbot) check rewriting chatbot on. GitHub Questa applicazione di esempio dimostra:
+ Un ciclo di riscrittura iterativo in cui le risposte non valide vengono corrette automaticamente in base al feedback del ragionamento automatico.
+ Follow-up domande quando il LLM necessita di un contesto aggiuntivo da parte dell'utente per riscriverlo con precisione.
+ Un meccanismo di timeout che riprende automaticamente l'elaborazione quando gli utenti non rispondono alle domande di chiarimento.
+ Inserimento del contesto delle politiche nei prompt LLM in modo che l'LLM possa fare riferimento alle regole politiche complete durante la riscrittura.
+ Registrazione di controllo JSON di ogni iterazione di convalida per la conformità e il debug.
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`
**Nota**
L'applicazione di esempio include il contenuto della policy direttamente nei prompt di generazione LLM per supportare qualsiasi policy di Automated Reasoning senza richiedere il caricamento di documenti. In un'implementazione di produzione, in genere si utilizzano contenuti RAG o si inserisce nel LLM il documento originale in linguaggio naturale anziché il codice sorgente della politica di Automated Reasoning.
## 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:
+ **Timestamp e ID della richiesta.** Quando è avvenuta la convalida e un identificatore univoco per la richiesta.
+ **Contenuto di input.** La domanda dell'utente e la risposta LLM che sono state convalidate.
+ **Tipo di ricerca e dettagli.** Il risultato della convalida (`valid`, ecc.)`invalid`, le premesse e le affermazioni tradotte e le regole di supporto o contraddittorie.
+ **Azioni intraprese.** Cosa ha fatto la tua candidatura con il risultato: ha fornito la risposta, l'ha riscritta, chiesto chiarimenti o l'ha bloccata.
+ **Riscrivere la storia.** Se la risposta è stata riscritta, registra ogni iterazione: la risposta originale, la richiesta di riscrittura, la risposta riscritta e il risultato della convalida per ogni iterazione.
+ **Versione della politica.** La versione guardrail e la versione della policy utilizzate per la convalida. Ciò garantisce la possibilità di riprodurre il risultato della convalida in un secondo momento.
**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
}
```
**Suggerimento**
Archivia i log di controllo in un archivio durevole e a prova di manomissione come Amazon Logs CloudWatch o Amazon S3 con blocco degli oggetti abilitato. Per gli scenari di conformità, prendi in considerazione l'utilizzo di Lake per interrogare i log di controllo in tutta l'organizzazione.