nemo_guardrails_oci_generative_ai/README.md

Tutorial Avançado: Integração do NeMo Guardrails com OCI Generative AI via Proxy OpenAI-Compatible

---

Introdução

Este tutorial demonstra como utilizar o OCI Generative AI por meio de uma interface compatível com a API da OpenAI, permitindo integração com frameworks modernos como o NeMo Guardrails.

A ideia principal não é apenas “usar um proxy”, mas sim:

Nota: desacoplar o modelo de linguagem (LLM) da aplicação, criando uma camada intermediária que permite:

• trocar modelos facilmente
• integrar diferentes provedores (OCI, OpenAI, modelos locais)
• padronizar consumo via API OpenAI

---

Ideia Central

O proxy oci_openai_proxy.py atua como um adaptador universal:

• Recebe requisições no padrão OpenAI (/v1/chat/completions)
• Traduz para chamadas do OCI Generative AI
• Retorna resposta no mesmo formato OpenAI

Nota: Isso permite que ferramentas como o NeMo Guardrails funcionem sem saber que estão usando OCI.

Mais importante: Esse modelo permite evoluir para:

• múltiplos LLMs
• fallback entre provedores
• balanceamento
• controle centralizado

---

Conceitos Fundamentais (Explicação detalhada)

1. Proxy OpenAI-Compatible

Um proxy é uma aplicação intermediária que:

• recebe requisições padronizadas
• adapta para outro backend
• retorna no mesmo formato

Neste caso:

Entrada:

/v1/chat/completions

Saída:

OCI Generative AI → resposta OpenAI-like

Nota: Benefício: Você não precisa alterar aplicações ao trocar o modelo.

---

2. NeMo Guardrails

O entity["software","NVIDIA NeMo Guardrails","framework"] é um framework que permite:

• controlar comportamento do LLM
• aplicar regras de segurança
• garantir previsibilidade

Ele atua como uma camada entre:

Usuário ↔ Guardrails ↔ LLM

---

3. Guardrails (Rails)

Guardrails são regras que atuam em pontos específicos:

• antes da entrada (input)
• durante o processamento
• após a resposta (output)

Nota: Eles permitem:

• bloquear conteúdo
• validar respostas
• controlar comportamento

---

4. Arquitetura Final

User
 ↓
NeMo Guardrails
 ↓
Proxy OpenAI (porta 8051)
 ↓
OCI Generative AI
 ↓
Resposta

---

Pré-requisitos

• Python 3.10+
• OCI configurado (~/.oci/config)
• Dependências:

pip install nemoguardrails fastapi uvicorn

---

Subindo o Proxy OCI

Arquivo: oci_openai_proxy.py

Este arquivo é responsável por:

• expor endpoint OpenAI
• traduzir requisições para OCI
• formatar respostas

Execução

uvicorn oci_openai_proxy:app --host 0.0.0.0 --port 8051

Nota: Endpoint disponível:

http://localhost:8051/v1/chat/completions

---

Configuração do NeMo Guardrails

Estrutura de arquivos

config/
 ├── config.yml
 ├── rails.co

---

Arquivo: config.yml (Explicação detalhada)

Este é o arquivo principal de configuração.

models

Define qual modelo será usado.

models:
  - type: main
    engine: openai
    model: gpt-4

Nota: Importante: Mesmo usando OCI, usamos engine: openai porque o proxy simula essa API.

---

parameters

parameters:
  base_url: http://localhost:8051/v1
  api_key: dummy

• base_url: aponta para o proxy
• api_key: não é usada, mas é exigida pela interface OpenAI

---

rails

rails:
  input:
    flows:
      - self check input
  output:
    flows:
      - self check output

Nota: Define quais regras serão aplicadas.

---

Arquivo: rails.co (Explicação detalhada)

Este arquivo define os fluxos de comportamento.

Ele usa a linguagem Colang.

Exemplo:

define flow self check input
  user input
  bot respond "Input validado"

Nota: Isso significa: Sempre que houver entrada do usuário, execute esse fluxo.

---

Output flow

define flow self check output
  bot output
  bot respond "Output validado"

Nota: Intercepta a saída antes de retornar ao usuário.

---

Executando o NeMo

nemoguardrails run --config config

Nota: Isso inicia o servidor do guardrails.

---

Testando

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "Olá"}]
  }'

---

Resultados Esperados

Você deverá observar:

• request passa pelo guardrails
• proxy é acionado
• OCI responde
• saída é filtrada

Fluxo real:

User
 ↓
Input Rails
 ↓
LLM (via Proxy)
 ↓
Output Rails
 ↓
Resposta final

---

Observações Importantes

• O proxy deve estar ativo antes do NeMo
• Logs podem ser ativados para debug
• O sistema é extensível para:
  • múltiplos modelos
  • fallback automático
  • auditoria

---

Conclusão

Este modelo permite:

• desacoplar LLM da aplicação
• trocar backend sem impacto
• aplicar governança com guardrails
• evoluir para arquitetura multi-modelo

---

References

NeMo Guardrails Library Configuration Overview Visão geral de como estruturar o sistema de controle do LLM https://docs.nvidia.com/nemo/guardrails/latest/configure-rails/overview.html

Tools Integration with the NeMo Guardrails Library Como integrar ferramentas externas (tools/APIs) dentro de um fluxo com NVIDIA NeMo Guardrails. • Executar ações externas • Chamar APIs • Usar funções ou serviços do sistema • Integrar com agentes e workflows reais https://docs.nvidia.com/nemo/guardrails/latest/integration/tools-integration.html

Observability:

Logging and Debugging Guardrails Generated Responses Como observar, entender e depurar o que acontece dentro do fluxo de guardrails durante a execução de um LLM. https://docs.nvidia.com/nemo/guardrails/latest/observability/logging/index.html

Quick Start for Tracing Guardrails Exemplo de código para habilitar tracing (rastreamento detalhado) no NeMo Guardrails usando OpenTelemetry. https://docs.nvidia.com/nemo/guardrails/latest/observability/tracing/quick-start.html

---

Acknowledgments

• Author - Cristiano Hoshikawa (Oracle LAD A-Team Solution Engineer)