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à. # Implementare la policy di ragionamento automatico nell’applicazione Dopo aver testato la policy di ragionamento automatico e averne trovato soddisfacenti le prestazioni, puoi distribuirla per utilizzarla nell’applicazione con Guardrail per Amazon Bedrock. Questa pagina descrive l'intero flusso di lavoro di implementazione: salvataggio di una versione immutabile, collegamento a un guardrail, automazione della distribuzione e integrazione nelle pipeline. CloudFormation CI/CD ## Salvare una versione della policy di ragionamento automatico Quando hai finito di testare la tua policy, crea una versione immutabile. Le versioni immutabili assicurano che la politica allegata al tuo guardrail non cambi inaspettatamente quando continui a modificare la BOZZA. Ogni versione è identificata da un numero di versione numerico (1, 2, 3,...) e non può essere modificata dopo la creazione. ### Utilizzo della console 1. Nel riquadro di navigazione a sinistra, scegli **Ragionamento automatico**. 1. Scegli la policy di Ragionamento automatico che desideri utilizzare con l’applicazione. 1. Scegli **Salva come nuova versione**. Puoi utilizzare questa versione della policy con il guardrail. ### Utilizzo dell’API Utilizza l'`CreateAutomatedReasoningPolicyVersion`API per creare una versione immutabile della tua politica di ragionamento automatico. #### Parametri della richiesta `policyArn`(richiesto) Il nome della risorsa Amazon (ARN) della policy di ragionamento automatico per cui creare la versione. `lastUpdatedDefinitionHash`(richiesto) L'hash della definizione della politica per la nuova versione. Recupera questo hash dall'API. `GetAutomatedReasoningPolicy` Questo ti assicura di verificare la versione esatta della definizione di policy che hai testato. #### Esempio ``` # Get the current definition hash aws bedrock get-automated-reasoning-policy \ --policy-arn "arn:aws:bedrock:{{us-east-1}}:{{111122223333}}:automated-reasoning-policy/{{lnq5hhz70wgk}}" \ --query "definitionHash" --output text # Create the version aws bedrock create-automated-reasoning-policy-version \ --policy-arn "arn:aws:bedrock:{{us-east-1}}:{{111122223333}}:automated-reasoning-policy/{{lnq5hhz70wgk}}" \ --last-updated-definition-hash "{{583463f067a8a4f49fc1206b4642fd40...}}" ``` Risposta di esempio: ``` { "policyArn": "arn:aws:bedrock:us-east-1:111122223333:automated-reasoning-policy/lnq5hhz70wgk", "version": "1", "name": "MyHRPolicy" } ``` ## Aggiungere la policy di ragionamento automatico al guardrail Dopo aver salvato una versione della tua policy di ragionamento automatico, aggiungila a un guardrail. Il guardrail è il componente di runtime che l'applicazione chiama per convalidare le risposte LLM. È possibile aggiungere una politica di ragionamento automatico a un guardrail nuovo o esistente. ### Utilizzo della console 1. **Nella barra di navigazione a sinistra, scegli **Guardrails**, quindi scegli **Crea guardrail (oppure seleziona un guardrail** esistente e scegli Modifica).** 1. Quando arrivi alla schermata **Aggiungi controlli del ragionamento automatico**, scegli **Abilita la policy del ragionamento automatico**. 1. Per **Nome della policy**, scegli una versione salvata di una policy di ragionamento automatico, quindi scegli **Avanti**. 1. Completa la creazione o l'aggiornamento del guardrail. ### Utilizzo dell’API Usa l'`UpdateGuardrail`API `CreateGuardrail` or per aggiungere una politica di ragionamento automatizzato al tuo guardrail. Includi il `automatedReasoningConfig` parametro con l'ARN della policy con versione. #### Parametri della richiesta `automatedReasoningConfig` La configurazione per i controlli del ragionamento automatico in Guardrail per Amazon Bedrock. `policyArn`(obbligatorio) L'ARN della versione della policy di Automated Reasoning da utilizzare con il guardrail. Utilizza l'ARN con versione (che termina `:1` con, ecc.)`:2`, non l'ARN senza versione. #### Esempio ``` aws bedrock create-guardrail \ --name "{{HR-Policy-Guardrail}}" \ --description "{{Guardrail for HR policy validation}}" \ --automated-reasoning-policy-config policies="arn:aws:bedrock:{{us-east-1}}:{{111122223333}}:automated-reasoning-policy/{{lnq5hhz70wgk}}:{{1}}" \ --cross-region-config '{"guardrailProfileIdentifier": "{{us}}.guardrail.v1:0"}' \ --blocked-input-messaging "I cannot process this request." \ --blocked-outputs-messaging "I cannot provide this response." ``` **Importante** Utilizza l'ARN della policy con versione (ad esempio`arn:aws:bedrock:us-east-1:111122223333:automated-reasoning-policy/lnq5hhz70wgk:1`,). Se si utilizza l'ARN senza versione, l'API restituisce un errore. Crea prima una versione utilizzando. `CreateAutomatedReasoningPolicyVersion` **Importante** I guardrail che utilizzano i controlli di ragionamento automatico richiedono un profilo di inferenza interregionale. Includi il `--cross-region-config` parametro con una `guardrailProfileIdentifier` che corrisponda al prefisso della tua regione (ad esempio, per le regioni degli Stati Uniti o `us.guardrail.v1:0` per le regioni dell'UE). `eu.guardrail.v1:0` Se ometti questo parametro, l'API restituisce un. `ValidationException` ## Esporta una versione della policy per la distribuzione Per implementare una policy tramite CloudFormation o una CI/CD pipeline, è necessaria la definizione della policy JSON. Utilizza l'`ExportAutomatedReasoningPolicyVersion`API per esportare la definizione completa della politica, incluse tutte le regole, le variabili e i tipi personalizzati, da una versione salvata. La definizione esportata è lo stesso formato accettato dalla `PolicyDefinition` proprietà della CloudFormation `AWS::Bedrock::AutomatedReasoningPolicy` risorsa. In questo modo è semplice spostare una policy dal flusso di lavoro della console interattiva alla distribuzione automatizzata. ``` # Export the policy definition from version 1 aws bedrock export-automated-reasoning-policy-version \ --policy-arn "arn:aws:bedrock:{{us-east-1}}:{{111122223333}}:automated-reasoning-policy/{{lnq5hhz70wgk}}:{{1}}" \ --query "policyDefinition" \ --output json > {{policy-definition.json}} ``` Il file JSON esportato contiene la seguente struttura: ``` { "version": "1.0", "variables": [ { "name": "isFullTime", "type": "BOOL", "description": "Whether the employee works full-time (true) or part-time (false)." }, { "name": "tenureMonths", "type": "INT", "description": "The number of complete months the employee has been continuously employed." } ], "rules": [ { "id": "A1B2C3D4E5F6", "expression": "(=> (and isFullTime (> tenureMonths 12)) eligibleForParentalLeave)" } ], "types": [] } ``` Archivia questo file nel controllo della versione insieme ai tuoi CloudFormation modelli. Quando aggiorni la policy, esporta la nuova versione e aggiorna il file per avviare una distribuzione. ## Automatizza la distribuzione con CloudFormation Utilizzalo CloudFormation per implementare la tua policy di ragionamento automatico e guardrail come infrastruttura come codice. La `AWS::Bedrock::AutomatedReasoningPolicy` risorsa crea una policy con una definizione di policy che esporti dall'API o dalla console. In combinazione con`AWS::Bedrock::Guardrail`, puoi implementare lo stack di convalida completo in un unico modello. **Nota** CloudFormation crea la risorsa politica con la definizione di politica fornita dall'utente. Non esegue un flusso di lavoro di creazione né estrae regole dai documenti di origine. Devi prima creare e testare la tua policy in modo interattivo (utilizzando la console, l'API o la CLI di Kiro), quindi esportare la definizione della policy testata per utilizzarla nel tuo modello. Per ulteriori informazioni, consulta [Esporta una versione della policy per la distribuzione](#export-policy-version). *Per il riferimento completo alla proprietà della risorsa politica, consulta [AWS::Bedrock::AutomatedReasoningPolicy](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-bedrock-automatedreasoningpolicy.html) nel Template Reference.CloudFormation * ### Esempio: implementa una politica e un guardrail Il CloudFormation modello seguente crea una politica di ragionamento automatico con una definizione di politica e un guardrail che vi fa riferimento. Sostituisci la definizione della policy con il codice JSON esportato dalla policy testata. ``` AWSTemplateFormatVersion: '2010-09-09' Description: Deploy an Automated Reasoning policy and guardrail Parameters: PolicyName: Type: String Default: {{MyHRPolicy}} Description: Name of the Automated Reasoning policy GuardrailName: Type: String Default: {{HR-Policy-Guardrail}} Description: Name of the guardrail Resources: AutomatedReasoningPolicy: Type: AWS::Bedrock::AutomatedReasoningPolicy Properties: Name: !Ref PolicyName Description: Validates HR chatbot responses about leave eligibility PolicyDefinition: Version: '1.0' Variables: - Name: isFullTime Type: BOOL Description: >- Whether the employee works full-time (true) or part-time (false). Set to true when users mention being full-time or working 40+ hours per week. - Name: tenureMonths Type: INT Description: >- The number of complete months the employee has been continuously employed. When users mention years of service, convert to months (for example, 2 years = 24 months). - Name: eligibleForParentalLeave Type: BOOL Description: >- Whether the employee is eligible for parental leave based on employment status and tenure. Rules: - Id: {{A1B2C3D4E5F6}} Expression: >- (=> (and isFullTime (> tenureMonths 12)) eligibleForParentalLeave) - Id: {{G7H8I9J0K1L2}} Expression: >- (=> (or (not isFullTime) (<= tenureMonths 12)) (not eligibleForParentalLeave)) Types: [] Tags: - Key: Environment Value: Production - Key: Team Value: HR Guardrail: Type: AWS::Bedrock::Guardrail Properties: Name: !Ref GuardrailName Description: Guardrail with Automated Reasoning checks for HR policy BlockedInputMessaging: I cannot process this request. BlockedOutputsMessaging: I cannot provide this response. AutomatedReasoningPolicyConfig: Policies: - !GetAtt AutomatedReasoningPolicy.PolicyArn CrossRegionConfig: GuardrailProfileArn: !Sub "arn:aws:bedrock:${AWS::Region}:${AWS::AccountId}:guardrail-profile/{{us}}.guardrail.v1:0" Outputs: PolicyArn: Description: ARN of the Automated Reasoning policy Value: !GetAtt AutomatedReasoningPolicy.PolicyArn PolicyId: Description: ID of the Automated Reasoning policy Value: !GetAtt AutomatedReasoningPolicy.PolicyId GuardrailId: Description: ID of the guardrail Value: !Ref Guardrail ``` **Suggerimento** Per le implementazioni di produzione, conserva la definizione della policy in un file JSON separato e fai riferimento ad essa utilizzando `Fn::Include` o caricandola come parametro del modello. Ciò mantiene pulito il modello e semplifica l'aggiornamento indipendente della definizione della politica. **Importante** I guardrail che utilizzano i controlli di ragionamento automatico richiedono un profilo di inferenza interregionale. La `CrossRegionConfig` proprietà specifica l'ARN del profilo del guardrail per la tua regione. Sostituisci il prefisso Region (`us`) con il prefisso appropriato per la tua regione di distribuzione (ad esempio, `eu` per le regioni dell'UE). Se ometti questa proprietà, la creazione del guardrail fallisce. ### Esempio: implementazione con una chiave KMS gestita dal cliente Per crittografare la tua politica con una chiave KMS gestita dal cliente, aggiungi la proprietà. `KmsKeyId` È inoltre necessario configurare la policy chiave per consentire ad Amazon Bedrock di utilizzare la chiave. Per le autorizzazioni necessarie per la policy chiave, consulta. [Autorizzazioni KMS per le policy di ragionamento automatico](create-automated-reasoning-policy.md#automated-reasoning-policy-kms-permissions) ``` AutomatedReasoningPolicy: Type: AWS::Bedrock::AutomatedReasoningPolicy Properties: Name: !Ref PolicyName Description: Validates HR chatbot responses about leave eligibility KmsKeyId: !GetAtt PolicyEncryptionKey.Arn PolicyDefinition: # ... policy definition ... Tags: - Key: Environment Value: Production ``` **Importante** La modifica della `KmsKeyId` proprietà richiede la sostituzione della risorsa. CloudFormation eliminerà la politica esistente e ne creerà una nuova con un nuovo ARN. Aggiorna tutti i guardrail che fanno riferimento all'ARN della vecchia policy. ## Fasi successive Dopo aver implementato la policy e il guardrail, integra i controlli di ragionamento automatico nell'applicazione per convalidare le risposte LLM in fase di esecuzione. Per ulteriori informazioni, consulta [Integra i controlli di ragionamento automatizzato nella tua applicazione](integrate-automated-reasoning-checks.md).