Configurazione guardrails

È possibile configurare i guardrail utilizzando helpputils come parte della selezione di un modello di base utilizzando OCIAIConf().

La configurazione dei guardrail viene fornita quando si seleziona un modello di base dal servizio OCI Generative AI. In questo esempio, selezioniamo il modello xai.grok-4:

from aidputils.agents.toolkit.configs import OCIAIConf 
guardrails_config = { 
    "name" : "<guardrailsName>", 
    "description" : "<guardrailsDescription>", 
    "policies" : [ ] 
  } 
model_args = {} 
llm_conf = OCIAIConf(model_provider='generic', 
                     compartment_id='<compartment_ocid>', 
                     model_args=model_args, 
                     endpoint='https://inference.generativeai.<oci-region>.oci.oraclecloud.com', 
                     model_id='xai.grok-4', 
                     guardrails_config=guardrails_config)

La configurazione dei guardrails è una stringa di tipo JSON costituita da un array di criteri. Nell'esempio precedente, è definito in questo blocco di codice in cui <guardrailsName> e <guardrailsDescription> sono un nome e una descrizione definiti dall'utente:

guardrails_config = { 
    "name" : "<guardrailsName>", 
    "description" : "<guardrailsDescription>", 
    "policies" : [ ] 
  }

Ogni criterio dispone delle chiavi elencate di seguito.

Legenda	Obbligatorio.	Descrizione	Tipo di dati	Valore predefinito
policyName	N.	Nome personalizzato per il criterio	Stringa	ND
policyType	Sì	Tipo di criterio Guardrail da applicare. I valori consentiti includono: CONTENT_MODERATION PROMPT_ATTACKS_PREVENTION PII_DETECTION	ENUM
policyDescription	N.	Una descrizione del criterio	Stringa
scope	N.	L'ambito definisce dove vengono applicati i guardrail. I valori consentiti includono: USER_REQUEST AGENT_RESPONSE BOTH	ENUM
action	N.	Azione da eseguire quando il criterio viene violato I valori consentiti includono: INFORM BLOCK ALLOW MASK (solo per PII_DETECTION)	ENUM
threshold	N.	Soglia per il rilevamento. Intervallo è una probabilità compresa tra 0 e 1.	float
piiCategories	Sì	Categoria di dati PII da rilevare insieme alla loro azione e abilitazione.	Array

piiCategories è anche un array di oggetti simili a JSON che utilizza le seguenti chiavi:

Legenda	Obbligatorio.	Descrizione	Tipo di dati	Valore predefinito
category	Sì	La categoria PII da rilevare. I valori consentiti includono: PERSON ADDRESS TELEPHONE_NUMBER EMAIL	Stringa	ND
isEnabled	N.	Abilita il rilevamento della categoria PII. I valori consentiti includono: True False	ENUM
action	N.	Azione da eseguire se viene rilevata una categoria di informazioni di identificazione personale. Eseguire l'override dell'azione precedente. I valori consentiti includono: INFORM BLOCK ALLOW MASK	Stringa

Esempio: configurazione completa dei guardrail

In questo caso applichiamo tutte e tre le politiche:

• la moderazione del contenuto viene applicata solo alla risposta dell'agente,
• l'iniezione rapida bloccherà le richieste dell'utente se rilevate,
• PII rilevate sia nella risposta dell'agente che nella richiesta dell'utente. Ogni categoria di informazioni di identificazione personale viene trattata in modo diverso.

guardrails_config = { 
    "policies" : [ { 
      "policyType" : "CONTENT_MODERATION", 
      "policyName" : "Content Moderation prevention", 
      "policyDescription" : "Choose an action to take when hate, sexual, violence, toxic, derogatory, or harassment content is detected in either the user input query or the agent response.", 
      "scope" : "AGENT_RESPONSE", 
      "action" : "INFORM", 
      "threshold" : 0.5, 
      "categories" : [ ] 
    }, { 
      "policyType" : "PROMPT_ATTACKS_PREVENTION", 
      "policyName" : "Prompt Injection prevention", 
      "policyDescription" : "Choose action when prompt injection is detected on the user query.", 
      "scope" : "USER_REQUEST", 
      "action" : "BLOCK", 
      "threshold" : 0.5 
    }, { 
      "policyType" : "PII_DETECTION", 
      "policyName" : "Personally Identifiable Information (PII) detection", 
      "policyDescription" : "Choose an action to take when PII entities are detected in either the user input query or the agent response.", 
      "scope" : "AGENT_RESPONSE", 
      "action" : "INFORM", 
      "threshold" : 0.5, 
      "piiCategories" : [ { 
        "category" : "PERSON", 
        "isEnabled" : False, 
        "action" : "INFORM" 
      }, { 
        "category" : "ADDRESS", 
        "isEnabled" : False, 
        "action" : "INFORM" 
      }, { 
        "category" : "TELEPHONE_NUMBER", 
        "isEnabled" : True, 
        "action" : "MASK" 
      }, { 
        "category" : "EMAIL", 
        "isEnabled" : True, 
        "action" : "MASK" 
      } ] 
    }, { 
      "policyType" : "PII_DETECTION", 
      "policyName" : "Personally Identifiable Information (PII) detection", 
      "policyDescription" : "Choose an action to take when PII entities are detected in either the user input query or the agent response.", 
      "scope" : "USER_REQUEST", 
      "action" : "INFORM", 
      "threshold" : 0.5, 
      "piiCategories" : [ { 
        "category" : "PERSON", 
        "isEnabled" : True, 
        "action" : "INFORM" 
      }, { 
        "category" : "ADDRESS", 
        "isEnabled" : True, 
        "action" : "INFORM" 
      }, { 
        "category" : "TELEPHONE_NUMBER", 
        "isEnabled" : True, 
        "action" : "BLOCK" 
      }, { 
        "category" : "EMAIL", 
        "isEnabled" : False, 
        "action" : "INFORM" 
      } ] 
    } ] 
  }