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

229
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: > **Note:** **decouple the language model (LLM) from the application**, creating an intermediate layer that allows:
- trocar modelos facilmente - easy model switching
- integrar diferentes provedores (OCI, OpenAI, modelos locais) - integration with multiple providers (OCI, OpenAI, local models)
- padronizar consumo via API OpenAI - 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`) - Receives requests in OpenAI format (`/v1/chat/completions`)
- Traduz para chamadas do OCI Generative AI - Translates them into OCI Generative AI calls
- Retorna resposta no mesmo formato OpenAI - 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:** > **More importantly:**
Esse modelo permite evoluir para: This model enables evolution toward:
- múltiplos LLMs - multiple LLMs
- fallback entre provedores - provider fallback
- balanceamento - load balancing
- controle centralizado - 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 - receives standardized requests
- adapta para outro backend - adapts them to another backend
- retorna no mesmo formato - returns responses in the same format
Neste caso: In this case:
Entrada: Input:
``` ```
/v1/chat/completions /v1/chat/completions
``` ```
Saída: Output:
``` ```
OCI Generative AI → resposta OpenAI-like OCI Generative AI → OpenAI-like response
``` ```
>**Nota:** Benefício: > **Note (Benefit):**
Você não precisa alterar aplicações ao trocar o modelo. You don’t need to modify applications when switching models.
--- ---
### 2. NeMo Guardrails ### 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 - controlling LLM behavior
- aplicar regras de segurança - applying safety rules
- garantir previsibilidade - ensuring predictability
Ele atua como uma camada entre: It operates as a layer between:
``` ```
Usuário ↔ Guardrails ↔ LLM User ↔ Guardrails ↔ LLM
``` ```
--- ---
### 3. Guardrails (Rails) ### 3. Guardrails (Rails)
Guardrails são regras que atuam em pontos específicos: Guardrails are rules applied at specific stages:
- antes da entrada (input) - before input (input)
- durante o processamento - during processing
- após a resposta (output) - after response (output)
>**Nota:** Eles permitem: > **Note:** They allow:
- bloquear conteúdo - blocking content
- validar respostas - validating responses
- controlar comportamento - controlling behavior
--- ---
### 4. Arquitetura Final ### 4. Final Architecture
``` ```
User User
↓ ↓
NeMo Guardrails NeMo Guardrails
↓ ↓
Proxy OpenAI (porta 8051) OpenAI Proxy (port 8051)
↓ ↓
OCI Generative AI OCI Generative AI
↓ ↓
Resposta Response
``` ```
--- ---
## Pré-requisitos ## Prerequisites
- Python 3.10+ - Python 3.10+
- OCI configurado (`~/.oci/config`) - OCI configured (`~/.oci/config`)
- Dependências: - Dependencies:
```bash ```bash
pip install nemoguardrails fastapi uvicorn 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 - exposing an OpenAI-compatible endpoint
- traduzir requisições para OCI - translating requests to OCI
- formatar respostas - formatting responses
### Execução ### Execution
```bash ```bash
uvicorn oci_openai_proxy:app --host 0.0.0.0 --port 8051 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 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/ 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 ### models
Define qual modelo será usado. Defines which model will be used.
```yaml ```yaml
models: models:
@@ -172,8 +172,7 @@ models:
model: gpt-4 model: gpt-4
``` ```
>**Nota:** Importante: > **Note:** Even using OCI, we use `engine: openai` because the proxy simulates this API.
Mesmo usando OCI, usamos `engine: openai` porque o proxy simula essa API.
--- ---
@@ -185,8 +184,8 @@ parameters:
api_key: dummy api_key: dummy
``` ```
- `base_url`: aponta para o proxy - `base_url`: points to the proxy
- `api_key`: não é usada, mas é exigida pela interface OpenAI - `api_key`: not used, but required by OpenAI interface
--- ---
@@ -202,26 +201,26 @@ rails:
- self check output - 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 ```co
define flow self check input define flow self check input
user input user input
bot respond "Input validado" bot respond "Input validated"
``` ```
>**Nota:** Isso significa: > **Note:** This means:
Sempre que houver entrada do usuário, execute esse fluxo. Whenever user input occurs, this flow is executed.
--- ---
@@ -230,46 +229,46 @@ Sempre que houver entrada do usuário, execute esse fluxo.
```co ```co
define flow self check output define flow self check output
bot 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 ```bash
nemoguardrails run --config config nemoguardrails run --config config
``` ```
>**Nota:** Isso inicia o servidor do guardrails. > **Note:** This starts the guardrails server.
--- ---
## Testando ## Testing
```bash ```bash
curl http://localhost:8000/v1/chat/completions \ curl http://localhost:8000/v1/chat/completions \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-d '{ -d '{
"model": "gpt-4", "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 - request goes through guardrails
- proxy é acionado - proxy is invoked
- OCI responde - OCI responds
- saída é filtrada - output is filtered
Fluxo real: Real flow:
``` ```
User User
@@ -280,30 +279,30 @@ LLM (via Proxy)
↓ ↓
Output Rails Output Rails
↓ ↓
Resposta final Final Response
``` ```
--- ---
## Observações Importantes ## Important Notes
- O proxy deve estar ativo antes do NeMo - Proxy must be running before NeMo
- Logs podem ser ativados para debug - Logs can be enabled for debugging
- O sistema é extensível para: - System is extensible for:
- múltiplos modelos - multiple models
- fallback automático - automatic fallback
- auditoria - auditing
--- ---
## Conclusão ## Conclusion
Este modelo permite: This model allows:
- desacoplar LLM da aplicação - decoupling LLM from application
- trocar backend sem impacto - switching backend without impact
- aplicar governança com guardrails - applying governance with guardrails
- evoluir para arquitetura multi-modelo - 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) - [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) - [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. How to integrate external tools (tools/APIs) into a workflow with NVIDIA NeMo Guardrails:
- Executar ações externas • Execute external actions
- Chamar APIs • Call APIs
- Usar funções ou serviços do sistema • Use system functions or services
- Integrar com agentes e workflows reais • Integrate with real agents and workflows
### Observability: ### Observability:
- [Logging and Debugging Guardrails Generated Responses](https://docs.nvidia.com/nemo/guardrails/latest/observability/logging/index.html) - [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) - [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 ## Acknowledgments
- **Author** - Cristiano Hoshikawa (Oracle LAD A-Team Solution Engineer) - Author: Cristiano Hoshikawa (Oracle LAD A-Team Solution Engineer)