Configuração de Guardrails

Você pode configurar guardrails usando aidputils como parte da seleção de um modelo básico usando OCIAIConf().

A configuração do Guardrails é fornecida ao selecionar um modelo básico no serviço OCI Generative AI. Neste exemplo, selecionamos o modelo 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)

A configuração de guardrails é uma string semelhante a JSON que consiste em um array de políticas. No exemplo acima, ele é definido neste bloco de código em que <guardrailsName> e <guardrailsDescription> são um nome e uma descrição definidos pelo usuário:

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

Cada política tem as seguintes chaves:

Key	Obrigatório	Descrição	Tipo de Dados	Valor padrão
policyName	No	Nome personalizado da política	String	N/D
policyType	Sim	Tipo de política de guardrail a ser aplicada. Os valores permitidos incluem: CONTENT_MODERATION PROMPT_ATTACKS_PREVENTION PII_DETECTION	ENUM
policyDescription	No	Uma descrição para a política	String
scope	No	O escopo define onde os guardrails são aplicados. Os valores permitidos incluem: USER_REQUEST AGENT_RESPONSE BOTH	ENUM
action	No	A ação a ser tomada quando a política é violada Os valores permitidos incluem: INFORM BLOCK ALLOW MASK (somente para PII_DETECTION)	ENUM
threshold	No	Limite para detecção. Intervalo é uma probabilidade entre 0 e 1.	flutuante
piiCategories	Sim	Categoria de dados de PII a serem detectados junto com sua ação e ativação.	Array

piiCategories também é um array de objetos semelhantes a JSON que usa as seguintes chaves:

Key	Obrigatório	Descrição	Tipo de Dados	Valor padrão
category	Sim	A categoria PII a ser detectada. Os valores permitidos incluem: PERSON ADDRESS TELEPHONE_NUMBER EMAIL	String	N/D
isEnabled	No	Ative a detecção da categoria de PII. Os valores permitidos incluem: True False	ENUM
action	No	Ação a ser tomada se a categoria PII for detectada. Substitua a ação acima. Os valores permitidos incluem: INFORM BLOCK ALLOW MASK	String

Exemplo: Configuração Completa de Corrimões

Neste caso, aplicamos as três políticas:

• moderação de conteúdo só é aplicada na resposta do agente,
• a injeção do prompt bloqueará solicitações do usuário se detectadas,
• O PII é detectado na resposta do agente e na solicitação do usuário. Cada categoria de PII é tratada de forma diferente.

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