nvidia-nemo/guardrailsSalvaguardas programables para aplicaciones de chat con LLM: aplica reglas de entrada/salida, bloquea jailbreaks e inyecciones de prompt, detecta alucinaciones y enmascara datos sensibles.
ÚLTIMA VERSIÓN / VERSIÓN DE DESARROLLO: La rama develop sigue lo último en desarrollo. La última versión publicada es la 0.24.1.
✨✨✨
📌 La documentación oficial de la biblioteca NeMo Guardrails está disponible en docs.nvidia.com/nemo/guardrails.
✨✨✨
La biblioteca NVIDIA NeMo Guardrails es un conjunto de herramientas de código abierto para añadir fácilmente guardrails programables a aplicaciones conversacionales basadas en LLM. Los guardrails (o "rails" para abreviar) son formas específicas de controlar la salida de un modelo de lenguaje grande, como no hablar de política, responder de una manera particular a solicitudes específicas del usuario, seguir una ruta de diálogo predefinida, usar un estilo de lenguaje particular, extraer datos estructurados y más.
Este artículo presenta la biblioteca NeMo Guardrails y contiene una descripción técnica del sistema y la evaluación actual.
Python 3.10, 3.11, 3.12 o 3.13.
Para instalar usando pip:```bash
pip install nemoguardrails
Para obtener instrucciones más detalladas, consulte la [Guía de instalación](https://docs.nvidia.com/nemo/guardrails/get-started/installation-guide).
## Descripción general
<!-- start-documentation-reuse -->
La biblioteca NeMo Guardrails permite a los desarrolladores que crean aplicaciones basadas en LLM añadir **guardrails programables** entre el código de la aplicación y el LLM.
<div align="center">
<img src="https://raw.githubusercontent.com/NVIDIA-NeMo/Guardrails/develop/docs/_static/images/programmable_guardrails.png" width="75%" alt="Programmable Guardrails">
</div>
Los beneficios clave de añadir *guardrails programables* incluyen:
- **Crear aplicaciones basadas en LLM confiables, seguras y protegidas:** puede definir rails para guiar y salvaguardar las conversaciones; puede optar por definir el comportamiento de su aplicación basada en LLM sobre temas específicos y evitar que participe en discusiones sobre temas no deseados.
- **Conectar modelos, cadenas y otros servicios de forma segura:** puede conectar un LLM a otros servicios (también conocidos como herramientas) de forma fluida y segura.
- **Diálogo controlable**: puede dirigir el LLM para que siga rutas conversacionales predefinidas, lo que le permite diseñar la interacción siguiendo las mejores prácticas de diseño de conversaciones y aplicar procedimientos operativos estándar (por ejemplo, autenticación, soporte).
<!-- end-documentation-reuse -->
### Protección contra vulnerabilidades de LLM
La biblioteca NeMo Guardrails proporciona varios mecanismos para proteger una aplicación de chat impulsada por LLM contra vulnerabilidades comunes de LLM, como jailbreaks e inyecciones de prompts. A continuación se muestra una descripción general de ejemplo de la protección ofrecida por diferentes configuraciones de guardrails para el ejemplo [ABC Bot](https://github.com/nvidia-nemo/guardrails/blob/develop/examples/bots/abc) incluido en este repositorio. Para obtener más detalles, consulte la página [LLM Vulnerability Scanning](https://docs.nvidia.com/nemo/guardrails/evaluation/llm-vulnerability-scanning.html).
<div align="center">
<img src="https://raw.githubusercontent.com/NVIDIA-NeMo/Guardrails/develop/docs/_static/images/abc-llm-vulnerability-scan-results.png" width="500">
</div>
### Casos de uso
Puede utilizar guardrails programables en diferentes tipos de casos de uso:
1. **Respuesta a preguntas** sobre un conjunto de documentos (también conocido como Generación Aumentada por Recuperación): Aplicar verificación de hechos y moderación de la salida.
2. **Asistentes específicos de dominio** (también conocidos como chatbots): Asegurar que el asistente se mantenga en el tema y siga los flujos conversacionales diseñados.
3. **Endpoints de LLM**: Añadir guardrails a su LLM personalizado para una interacción más segura con el cliente.
4. **Cadenas de LangChain** (opcional): Si utiliza LangChain para cualquier caso de uso, puede añadir una capa de guardrails alrededor de sus cadenas. Para habilitar esta integración, establezca la variable de entorno `NEMOGUARDRAILS_LLM_FRAMEWORK=langchain` o llame a `set_default_framework("langchain")`.
### Uso
Para añadir guardrails programables a su aplicación puede utilizar la API de Python o un servidor de guardrails (consulte la [Guía del servidor](https://docs.nvidia.com/nemo/guardrails/get-started/integrate-into-application) para obtener más detalles). Usar la API de Python es similar a usar el LLM directamente. Llamar a la capa de guardrails en lugar del LLM requiere solo cambios mínimos en el código base, e implica dos pasos sencillos:
1. Cargar una configuración de guardrails y crear una instancia de `LLMRails`.
2. Realizar las llamadas al LLM utilizando los métodos `generate`/`generate_async`.```python
from nemoguardrails import LLMRails, RailsConfig
# Load a guardrails configuration from the specified path.
config = RailsConfig.from_path("PATH/TO/CONFIG")
rails = LLMRails(config)
completion = rails.generate(
messages=[{"role": "user", "content": "Hello world!"}]
)
Salida de ejemplo:```json {"role": "assistant", "content": "Hi! How can I help you?"}
El formato de entrada y salida para el método `generate` es similar a la [API de Chat Completions](https://platform.openai.com/docs/guides/gpt/chat-completions-api) de OpenAI.
#### API asíncrona
La librería NeMo Guardrails es un toolkit async-first, ya que la mecánica principal está implementada utilizando el modelo asíncrono de Python. Los métodos públicos tienen tanto una versión síncrona como una asíncrona. Por ejemplo: `LLMRails.generate` y `LLMRails.generate_async`.
### LLMs compatibles
Puedes usar NeMo Guardrails con múltiples LLMs como OpenAI GPT-3.5, GPT-4, LLaMa-2, Falcon, Vicuna o Mosaic. Para más detalles, consulta la sección [Modelos LLM compatibles](https://docs.nvidia.com/nemo/guardrails/about-nemo-guardrails-library/supported-llms) en la Guía de configuración.
### Tipos de guardrails
La librería NeMo Guardrails admite cinco tipos principales de guardrails:
<div align="center">
<img src="https://raw.githubusercontent.com/NVIDIA-NeMo/Guardrails/develop/docs/_static/images/programmable_guardrails_flow.png" width="75%" alt="Programmable Guardrails Flow">
</div>
1. **Rails de entrada**: se aplican a la entrada del usuario; un rail de entrada puede rechazar la entrada, deteniendo cualquier procesamiento adicional, o alterar la entrada (por ejemplo, para enmascarar datos potencialmente sensibles, para reformular).
2. **Rails de diálogo**: influyen en cómo se le indica al LLM; los rails de diálogo operan sobre mensajes en forma canónica (para más detalles, consulta la [Guía de Colang](https://docs.nvidia.com/nemo/guardrails/configure-guardrails/colang)) y determinan si se debe ejecutar una acción, si se debe invocar al LLM para generar el siguiente paso o una respuesta, si se debe usar una respuesta predefinida en su lugar, etc.
3. **Rails de recuperación**: se aplican a los fragmentos recuperados en el caso de un escenario RAG (Retrieval Augmented Generation); un rail de recuperación puede rechazar un fragmento, impidiendo que se use para indicarle al LLM, o alterar los fragmentos relevantes (por ejemplo, para enmascarar datos potencialmente sensibles).
4. **Rails de ejecución**: se aplican a la entrada/salida de las acciones personalizadas (también conocidas como herramientas), que deben ser invocadas por el LLM.
5. **Rails de salida**: se aplican a la salida generada por el LLM; un rail de salida puede rechazar la salida, impidiendo que se devuelva al usuario, o alterarla (por ejemplo, eliminando datos sensibles).
### Configuración de guardrails
Una configuración de guardrails define el o los **LLM** que se utilizarán y **uno o más guardrails**. Una configuración de guardrails puede incluir cualquier número de rails de entrada/diálogo/salida/recuperación/ejecución. Una configuración sin ningún rail configurado esencialmente reenviará las solicitudes al LLM.
La estructura estándar para una carpeta de configuración de guardrails es la siguiente:```
.
├── config
│ ├── actions.py
│ ├── config.py
│ ├── config.yml
│ ├── rails.co
│ ├── ...
El config.yml contiene todas las opciones de configuración general, como los modelos LLM, los rails activos y los datos de configuración personalizados". El archivo config.py contiene cualquier código de inicialización personalizado y el actions.py contiene cualquier acción de python personalizada. Para obtener una visión completa, consulte la Guía de configuración.
A continuación se muestra un ejemplo de config.yml:```yaml
models:
rails:
input: flows: - check jailbreak - mask sensitive data on input
output: flows: - self check facts - self check hallucination - activefence moderation on input
config: # Configure the types of entities that should be masked on user input. sensitive_data_detection: input: entities: - PERSON - EMAIL_ADDRESS
Los archivos `.co` incluidos en una configuración de guardrails contienen las definiciones de Colang (consulta la siguiente sección para obtener una descripción rápida de qué es Colang) que definen varios tipos de rails. A continuación se muestra un ejemplo del archivo `greeting.co` que define los dialog rails para saludar al usuario.```colang
define user express greeting
"Hello!"
"Good afternoon!"
define flow
user express greeting
bot express greeting
bot offer to help
define bot express greeting
"Hello there!"
define bot offer to help
"How can I help you today?"
A continuación se muestra un ejemplo adicional de definiciones de Colang para un rail de diálogo contra insultos:```colang define user express insult "You are stupid"
define flow user express insult bot express calmly willingness to help
### Colang
Para configurar e implementar diversos tipos de barreras de protección, este conjunto de herramientas introduce **Colang**, un lenguaje de modelado creado específicamente para diseñar flujos de diálogo flexibles pero controlables. Colang tiene una sintaxis similar a Python y está diseñado para ser simple e intuitivo, especialmente para desarrolladores.```{note}
Two versions of Colang, 1.0 and 2.0, are supported and Colang 1.0 is the default.
Para obtener una breve introducción a la sintaxis de Colang 1.0, consulte la Guía de sintaxis del lenguaje Colang 1.0.
Para comenzar con Colang 2.0, consulte la Documentación de Colang 2.0.
NeMo Guardrails incluye un conjunto de guardrails integrados.```{note} The built-in guardrails may or may not be suitable for a given production use case. As always, developers should work with their internal application team to ensure guardrails meets requirements for the relevant industry and use case and address unforeseen product misuse.
La biblioteca incluye guardrails para la autoverificación de LLM (moderación de entrada/salida, verificación de hechos, detección de alucinaciones), modelos de seguridad de NVIDIA (seguridad de contenido, seguridad de temas), detección de jailbreak e inyección, e integraciones con modelos de la comunidad y API de terceros. Para obtener la lista completa, consulte la [documentación de la biblioteca de Guardrails](https://docs.nvidia.com/nemo/guardrails/user-guides/guardrails-library.html).
## CLI
La biblioteca NeMo Guardrails también incluye una CLI integrada.```bash
$ nemoguardrails --help
Usage: nemoguardrails [OPTIONS] COMMAND [ARGS]...
actions-server Start a NeMo Guardrails actions server.
chat Start an interactive chat session.
evaluate Run an evaluation task.
server Start a NeMo Guardrails server.
Puedes usar la CLI de la librería NeMo Guardrails para iniciar un servidor de guardrails. El servidor puede cargar una o más configuraciones desde la carpeta especificada y exponer una API HTTP para usarlas.``` nemoguardrails server [--config PATH/TO/CONFIGS] [--port PORT]
Por ejemplo, para obtener una finalización de chat para una configuración `sample`, puedes usar el endpoint `/v1/chat/completions`:```
POST /v1/chat/completions
core/config.py — Carga la configuración desde config.yaml y variables de entorno.logger.py — Registro estructurado con salida en color.models.py — Modelos de datos (Target, Finding, ScanResult).exceptions.py — Excepciones personalizadas.scanner/engine.py — Orquestador de escaneo principal.http_client.py — Cliente HTTP con reintentos y limitación de velocidad.checks/ — Comprobaciones de seguridad individuales.reporting/console.py — Salida de resultados en terminal.json_report.py — Exportación de resultados a JSON.html_report.py — Generación de informes HTML.utils/validators.py — Validación de entrada y URL.helpers.py — Funciones auxiliares diversas.# Clonar el repositorio
git clone https://github.com/example/security-scanner.git
cd security-scanner
# Crear un entorno virtual
python3 -m venv venv
source venv/bin/activate
# Instalar dependencias
pip install -r requirements.txt
# Ejecutar un escaneo básico
python -m scanner --target https://example.com
Edita config.yaml para personalizar el comportamiento del escáner:
scanner:
timeout: 30
max_retries: 3
rate_limit: 10
user_agent: "SecurityScanner/1.0"
checks:
ssl: true
headers: true
cookies: true
cors: true
reporting:
format: "html"
output_dir: "./reports"
# Escanear un único objetivo
python -m scanner --target https://example.com
# Escanear múltiples objetivos desde un archivo
python -m scanner --input targets.txt
# Especificar el formato de salida
python -m scanner --target https://example.com --format json
# Habilitar salida detallada
python -m scanner --target https://example.com --verbose
¡Las contribuciones son bienvenidas! Por favor, consulta CONTRIBUTING.md para más detalles.
git checkout -b feature/amazing-feature)git commit -m 'Add amazing feature')git push origin feature/amazing-feature)Este proyecto está licenciado bajo la Licencia MIT — consulta el archivo LICENSE para más detalles.```json
{
"config_id": "sample",
"messages": [{
"role":"user",
"content":"Hello! What can you do for me?"
}]
}
Salida de ejemplo:```json
{"role": "assistant", "content": "Hi! How can I help you?"}
Para iniciar un servidor de guardrails, también puedes usar un contenedor Docker. La biblioteca NeMo Guardrails proporciona un Dockerfile que puedes usar para construir una imagen nemoguardrails. Para más información, consulta la sección using Docker.
La integración con LangChain es opcional. Para habilitarla, establece la variable de entorno NEMOGUARDRAILS_LLM_FRAMEWORK=langchain o llama a set_default_framework("langchain"). Luego instala los paquetes de LangChain que requiera tu configuración. Después de habilitar la integración, puedes envolver una configuración de guardrails alrededor de una cadena de LangChain (o cualquier Runnable), y puedes llamar a una cadena de LangChain desde dentro de una configuración de guardrails. Para más información, consulta la LangChain Integration Documentation.
Evaluar la seguridad de una aplicación conversacional basada en LLM es una tarea compleja y todavía una pregunta de investigación abierta. Para respaldar una evaluación adecuada, la biblioteca NeMo Guardrails proporciona lo siguiente:
nemoguardrails evaluate, con soporte para rails temáticos, verificación de hechos, moderación (jailbreak y moderación de salida) y alucinaciones.Hay muchas formas de añadir guardrails a una aplicación conversacional basada en LLM. Por ejemplo: endpoints de moderación explícitos (p. ej., OpenAI, ActiveFence, PolicyAI), cadenas de crítica (p. ej., constitutional chain), análisis de la salida (p. ej., guardrails.ai), guardrails individuales (p. ej., LLM-Guard), detección de alucinaciones para aplicaciones RAG (p. ej., Got It AI, Patronus Lynx).
La biblioteca NeMo Guardrails tiene como objetivo proporcionar un conjunto de herramientas flexible que pueda integrar todos estos enfoques complementarios en una capa cohesiva de guardrails para LLM. Por ejemplo, el conjunto de herramientas proporciona integración lista para usar con ActiveFence, PolicyAI, AlignScore y cadenas de LangChain.
Hasta donde sabemos, la biblioteca NeMo Guardrails es el único conjunto de herramientas de guardrails que también ofrece una solución para modelar el diálogo entre el usuario y el LLM. Esto permite, por un lado, la capacidad de guiar el diálogo de forma precisa. Por otro lado, permite un control detallado sobre cuándo deben usarse ciertos guardrails, p. ej., usar la verificación de hechos solo para ciertos tipos de preguntas.
La biblioteca NVIDIA NeMo Guardrails recopila telemetría anónima para ayudar a NVIDIA a comprender qué patrones de despliegue y funciones de seguridad se usan más. La biblioteca emite un evento de uso cuando instancias LLMRails, IORails o Guardrails, y luego emite latidos periódicos desde un único hilo daemon por proceso. Esta telemetría es independiente del tracing por solicitud. Tú configuras el tracing en tu configuración de guardrails y lo envías a tu propio backend de observabilidad. La telemetría es un ping anónimo mínimo a NVIDIA.
Uso anónimo agregado en las compilaciones de las versiones exactas 0.22.0 y 0.23.0, del 22 de mayo al 18 de agosto de 2026:
Última actualización el 18 de agosto de 2026
La telemetría incluye:
openai, nim o nvidia_ai_endpoints, nunca nombres de modelos ni credencialesjailbreak_detection, content_safety o topic_safetylibrary, api o cli)LLMRails o IORails)No se recopila contenido del usuario en la carga útil del evento. La carga útil no incluye nombres de modelos, claves de API, endpoints, prompts, completions, recuentos de tokens, métricas por solicitud, rutas de archivos, nombres de usuario ni direcciones IP. NVIDIA usa los datos de forma agregada para priorizar el trabajo de ingeniería y compartirá las tendencias de adopción con la comunidad.
La biblioteca también intenta escribir la carga útil de cada evento en un archivo de auditoría local en ~/.config/nemoguardrails/usage_stats.json. El archivo de auditoría almacena el JSONL del evento, no el sobre completo de telemetría de NVIDIA. Las escrituras de auditoría son de mejor esfuerzo, y la transmisión de telemetría continúa aunque falle la escritura de auditoría local.
Establece cualquiera de las siguientes opciones para deshabilitar la telemetría:```bash export NEMO_GUARDRAILS_NO_USAGE_STATS=1
export DO_NOT_TRACK=1
mkdir -p ~/.config/nemoguardrails && touch ~/.config/nemoguardrails/do_not_track
Configure la exclusión antes de que se inicie la biblioteca NVIDIA NeMo Guardrails. Cambiar las variables de entorno o crear `do_not_track` después de que la telemetría haya comenzado no detiene un hilo de latido ya en ejecución.
Consulte [docs/telemetry.md](https://docs.nvidia.com/nemo/guardrails/latest/telemetry.html) para obtener el esquema completo y las descripciones campo por campo.
Puede optar por no participar en la recopilación de telemetría en cualquier momento. La exclusión se aplica únicamente a la recopilación de datos por parte de la propia biblioteca NVIDIA NeMo Guardrails.
Los endpoints de terceros tienen términos y prácticas de privacidad independientes. La biblioteca NVIDIA NeMo Guardrails puede utilizar endpoints de inferencia como NVIDIA Build (`build.nvidia.com`). Si utiliza NVIDIA Build u otro endpoint de terceros, los términos de servicio y las prácticas de privacidad de ese endpoint se aplican de forma independiente a la biblioteca. Cualquier exclusión de telemetría en la biblioteca NVIDIA NeMo Guardrails no se extiende al endpoint que elija. NVIDIA Build está destinado únicamente a evaluación y pruebas y no debe utilizarse en entornos de producción. No envíe información confidencial ni datos personales cuando utilice NVIDIA Build.
## Invitar a la comunidad a contribuir
Los rails de ejemplo que residen en el repositorio son excelentes puntos de partida. Invitamos con entusiasmo a la comunidad a contribuir para que el poder de los LLM confiables, seguros y protegidos sea accesible para todos. Para obtener orientación sobre cómo configurar un entorno de desarrollo y cómo contribuir a la biblioteca NeMo Guardrails, consulte las [pautas de contribución](https://github.com/nvidia-nemo/guardrails/blob/develop/CONTRIBUTING.md).
## Licencia
La biblioteca NeMo Guardrails está licenciada bajo la [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0).
## Cómo citar
Si utiliza la biblioteca NeMo Guardrails, cite el [artículo de EMNLP 2023](https://aclanthology.org/2023.emnlp-demo.40) que la presenta.```bibtex
@inproceedings{rebedea-etal-2023-nemo,
title = "{N}e{M}o Guardrails: A Toolkit for Controllable and Safe {LLM} Applications with Programmable Rails",
author = "Rebedea, Traian and
Dinu, Razvan and
Sreedhar, Makesh Narsimhan and
Parisien, Christopher and
Cohen, Jonathan",
editor = "Feng, Yansong and
Lefever, Els",
booktitle = "Proceedings of the 2023 Conference on Empirical Methods in Natural Language Processing: System Demonstrations",
month = dec,
year = "2023",
address = "Singapore",
publisher = "Association for Computational Linguistics",
url = "https://aclanthology.org/2023.emnlp-demo.40",
doi = "10.18653/v1/2023.emnlp-demo.40",
pages = "431--445",
}