cristiano.hoshikawa/nemo_guardrails_oci_generative_ai
1
0
Fork 0
mirror of https://github.com/hoshikawa2/nemo_guardrails_oci_generative_ai.git synced 2026-07-09 16:04:20 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update README.md

Browse Source
This commit is contained in:
Cristiano Hoshikawa
2026-04-27 07:36:14 -03:00
committed by GitHub
parent 02ecf7f562
commit da05d4d7d3
1 changed files with 113 additions and 118 deletions
Download Patch File Download Diff File Expand all files Collapse all files

231
README.md
View File

@@ -1,119 +1,119 @@
# Tutorial Avançado: Integração do NeMo Guardrails com OCI Generative AI via Proxy OpenAI-Compatible
# Advanced Tutorial: Integrating NeMo Guardrails with OCI Generative AI via an OpenAI-Compatible Proxy
---
## Introdução
## Introduction
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.
This tutorial demonstrates how to use **OCI Generative AI** through an OpenAI-compatible API interface, enabling integration with modern frameworks such as NVIDIA NeMo Guardrails.
A ideia principal não é apenas “usar um proxy”, mas sim:
The main idea is not just to “use a proxy”, but rather:
>**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
> **Note:** **decouple the language model (LLM) from the application**, creating an intermediate layer that allows:
- easy model switching
- integration with multiple providers (OCI, OpenAI, local models)
- standardized consumption via the OpenAI API
---
## Ideia Central
## Core Idea
O proxy `oci_openai_proxy.py` atua como um **adaptador universal**:
The `oci_openai_proxy.py` acts as a **universal adapter**:
- Recebe requisições no padrão OpenAI (`/v1/chat/completions`)
- Traduz para chamadas do OCI Generative AI
- Retorna resposta no mesmo formato OpenAI
- Receives requests in OpenAI format (`/v1/chat/completions`)
- Translates them into OCI Generative AI calls
- Returns responses in the same OpenAI format
>**Nota:** Isso permite que ferramentas como o NeMo Guardrails funcionem sem saber que estão usando OCI.
> **Note:** This allows tools like NeMo Guardrails to operate without knowing they are using OCI.
>**Mais importante:**
Esse modelo permite evoluir para:
- múltiplos LLMs
- fallback entre provedores
- balanceamento
- controle centralizado
> **More importantly:**
This model enables evolution toward:
- multiple LLMs
- provider fallback
- load balancing
- centralized control
---
## Conceitos Fundamentais (Explicação detalhada)
## Fundamental Concepts (Detailed Explanation)
### 1. Proxy OpenAI-Compatible
### 1. OpenAI-Compatible Proxy
Um proxy é uma aplicação intermediária que:
A proxy is an intermediate application that:
- recebe requisições padronizadas
- adapta para outro backend
- retorna no mesmo formato
- receives standardized requests
- adapts them to another backend
- returns responses in the same format
Neste caso:
In this case:
Entrada:
Input:
```
/v1/chat/completions
```
Saída:
Output:
```
OCI Generative AI → resposta OpenAI-like
OCI Generative AI → OpenAI-like response
```
>**Nota:** Benefício:
Você não precisa alterar aplicações ao trocar o modelo.
> **Note (Benefit):**
You don’t need to modify applications when switching models.
---
### 2. NeMo Guardrails
O **entity["software","NVIDIA NeMo Guardrails","framework"]** é um framework que permite:
NVIDIA NeMo Guardrails is a framework that enables:
- controlar comportamento do LLM
- aplicar regras de segurança
- garantir previsibilidade
- controlling LLM behavior
- applying safety rules
- ensuring predictability
Ele atua como uma camada entre:
It operates as a layer between:
```
Usuário ↔ Guardrails ↔ LLM
User ↔ Guardrails ↔ LLM
```
---
### 3. Guardrails (Rails)
Guardrails são regras que atuam em pontos específicos:
Guardrails are rules applied at specific stages:
- antes da entrada (input)
- durante o processamento
- após a resposta (output)
- before input (input)
- during processing
- after response (output)
>**Nota:** Eles permitem:
- bloquear conteúdo
- validar respostas
- controlar comportamento
> **Note:** They allow:
- blocking content
- validating responses
- controlling behavior
---
### 4. Arquitetura Final
### 4. Final Architecture
```
User
↓
NeMo Guardrails
↓
Proxy OpenAI (porta 8051)
OpenAI Proxy (port 8051)
↓
OCI Generative AI
↓
Resposta
Response
```
---
## Pré-requisitos
## Prerequisites
- Python 3.10+
- OCI configurado (`~/.oci/config`)
- Dependências:
- Python 3.10+
- OCI configured (`~/.oci/config`)
- Dependencies:
```bash
pip install nemoguardrails fastapi uvicorn
@@ -121,23 +121,23 @@ pip install nemoguardrails fastapi uvicorn
---
## Subindo o Proxy OCI
## Running the OCI Proxy
### Arquivo: oci_openai_proxy.py
### File: oci_openai_proxy.py
Este arquivo é responsável por:
This file is responsible for:
- expor endpoint OpenAI
- traduzir requisições para OCI
- formatar respostas
- exposing an OpenAI-compatible endpoint
- translating requests to OCI
- formatting responses
### Execução
### Execution
```bash
uvicorn oci_openai_proxy:app --host 0.0.0.0 --port 8051
```
>**Nota:** Endpoint disponível:
> **Note:** Available endpoint:
```
http://localhost:8051/v1/chat/completions
@@ -145,9 +145,9 @@ http://localhost:8051/v1/chat/completions
---
## Configuração do NeMo Guardrails
## Configuring NeMo Guardrails
### Estrutura de arquivos
### File structure
```
config/
@@ -157,13 +157,13 @@ config/
---
## Arquivo: config.yml (Explicação detalhada)
## File: config.yml (Detailed Explanation)
Este é o arquivo principal de configuração.
This is the main configuration file.
### models
Define qual modelo será usado.
Defines which model will be used.
```yaml
models:
@@ -172,8 +172,7 @@ models:
model: gpt-4
```
>**Nota:** Importante:
Mesmo usando OCI, usamos `engine: openai` porque o proxy simula essa API.
> **Note:** Even using OCI, we use `engine: openai` because the proxy simulates this API.
---
@@ -185,8 +184,8 @@ parameters:
api_key: dummy
```
- `base_url`: aponta para o proxy
- `api_key`: não é usada, mas é exigida pela interface OpenAI
- `base_url`: points to the proxy
- `api_key`: not used, but required by OpenAI interface
---
@@ -202,26 +201,26 @@ rails:
- self check output
```
>**Nota:** Define quais regras serão aplicadas.
> **Note:** Defines which rules will be applied.
---
## Arquivo: rails.co (Explicação detalhada)
## File: rails.co (Detailed Explanation)
Este arquivo define os **fluxos de comportamento**.
This file defines **behavior flows**.
Ele usa a linguagem Colang.
It uses Colang language.
### Exemplo:
### Example:
```co
define flow self check input
user input
bot respond "Input validado"
bot respond "Input validated"
```
>**Nota:** Isso significa:
Sempre que houver entrada do usuário, execute esse fluxo.
> **Note:** This means:
Whenever user input occurs, this flow is executed.
---
@@ -230,46 +229,46 @@ Sempre que houver entrada do usuário, execute esse fluxo.
```co
define flow self check output
bot output
bot respond "Output validado"
bot respond "Output validated"
```
>**Nota:** Intercepta a saída antes de retornar ao usuário.
> **Note:** Intercepts output before returning to user.
---
## Executando o NeMo
## Running NeMo
```bash
nemoguardrails run --config config
```
>**Nota:** Isso inicia o servidor do guardrails.
> **Note:** This starts the guardrails server.
---
## Testando
## Testing
```bash
curl http://localhost:8000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4",
"messages": [{"role": "user", "content": "Olá"}]
"messages": [{"role": "user", "content": "Hello"}]
}'
```
---
## Resultados Esperados
## Expected Results
Você deverá observar:
You should observe:
- request passa pelo guardrails
- proxy é acionado
- OCI responde
- saída é filtrada
- request goes through guardrails
- proxy is invoked
- OCI responds
- output is filtered
Fluxo real:
Real flow:
```
User
@@ -280,30 +279,30 @@ LLM (via Proxy)
↓
Output Rails
↓
Resposta final
Final Response
```
---
## Observações Importantes
## Important Notes
- 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
- Proxy must be running before NeMo
- Logs can be enabled for debugging
- System is extensible for:
- multiple models
- automatic fallback
- auditing
---
## Conclusão
## Conclusion
Este modelo permite:
This model allows:
- desacoplar LLM da aplicação
- trocar backend sem impacto
- aplicar governança com guardrails
- evoluir para arquitetura multi-modelo
- decoupling LLM from application
- switching backend without impact
- applying governance with guardrails
- evolving to multi-model architecture
---
@@ -311,34 +310,30 @@ Este modelo permite:
- [NeMo Guardrails Library Configuration Overview](https://docs.nvidia.com/nemo/guardrails/latest/configure-rails/overview.html)
Visão geral de como estruturar o sistema de controle do LLM
Overview of how to structure the LLM control system
- [Tools Integration with the NeMo Guardrails Library](https://docs.nvidia.com/nemo/guardrails/latest/integration/tools-integration.html)
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
How to integrate external tools (tools/APIs) into a workflow with NVIDIA NeMo Guardrails:
• Execute external actions
• Call APIs
• Use system functions or services
• Integrate with real agents and workflows
### Observability:
- [Logging and Debugging Guardrails Generated Responses](https://docs.nvidia.com/nemo/guardrails/latest/observability/logging/index.html)
Como observar, entender e depurar o que acontece dentro do fluxo de guardrails durante a execução de um LLM.
How to observe, understand, and debug what happens within the guardrails flow during the execution of an LLM.
- [Quick Start for Tracing Guardrails](https://docs.nvidia.com/nemo/guardrails/latest/observability/tracing/quick-start.html)
Exemplo de código para habilitar tracing (rastreamento detalhado) no NeMo Guardrails usando OpenTelemetry.
Example code to enable tracing (detailed execution tracking) in NeMo Guardrails using OpenTelemetry.
---
## Acknowledgments
- **Author** - Cristiano Hoshikawa (Oracle LAD A-Team Solution Engineer)
- Author: Cristiano Hoshikawa (Oracle LAD A-Team Solution Engineer)