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 el desarrollo más reciente de la rama principal. La última versión publicada es la 0.23.0.
✨✨✨
📌 La documentación oficial de la biblioteca NeMo Guardrails está disponible en docs.nvidia.com/nemo/guardrails.
✨✨✨
La biblioteca NVIDIA NeMo Guardrails es un kit de herramientas de código abierto para agregar 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 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 visión general técnica del sistema y la evaluación actual.
Python 3.10, 3.11, 3.12 o 3.13.
Para instalar con 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="Guardrails Programables">
</div>
Los beneficios clave de añadir *guardrails programables* incluyen:
- **Creación de aplicaciones basadas en LLM fiables, seguras y protegidas:** puede definir rails para guiar y proteger las conversaciones; puede elegir definir el comportamiento de su aplicación basada en LLM en temas específicos y evitar que entable discusiones sobre temas no deseados.
- **Conexión segura de modelos, cadenas y otros servicios:** 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 ofrece varios mecanismos para proteger una aplicación de chat impulsada por LLM contra vulnerabilidades comunes de LLM, como jailbreaks e inyecciones de prompt. A continuación se muestra una visión general de ejemplo de la protección que ofrecen las 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 más detalles, consulte la página [Escaneo de vulnerabilidades de LLM](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 conocida como Generación Aumentada por Recuperación): aplique la verificación de hechos y la moderación de salidas.
2. **Asistentes específicos de dominio** (también conocidos como chatbots): asegúrese de que el asistente se mantenga en el tema y siga los flujos conversacionales diseñados.
3. **Endpoints de LLM**: añada guardrails a su LLM personalizado para una interacción con el cliente más segura.
4. **LangChain Chains** (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 más detalles). Usar la API de Python es similar a usar el LLM directamente. Llamar a la capa de guardrails en lugar de al LLM solo requiere cambios mínimos en la base de código e implica dos sencillos pasos:
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 muestra:```json {"role": "assistant", "content": "Hi! How can I help you?"}
El formato de entrada y salida del método `generate` es similar al de 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 kit de herramientas asíncrono primero, ya que los mecanismos principales están implementados con el modelo asíncrono de Python. Los métodos públicos tienen una versión síncrona y una versión 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 soporta 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="Flujo de guardrails programables">
</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 (p. ej., para enmascarar datos potencialmente sensibles, para reformular).
2. **Rails de diálogo**: influyen en cómo se le da el prompt al LLM; los rails de diálogo operan sobre mensajes en forma canónica, para más detalles ver 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 (Generación Aumentada por Recuperación); un rail de recuperación puede rechazar un fragmento, impidiendo que se use para dar prompt al LLM, o alterar los fragmentos relevantes (p. ej., 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 el LLM necesita llamar.
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 (p. ej., eliminando datos sensibles).
### Configuración de guardrails
Una configuración de guardrails define **el/los LLM(s)** a usar 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 rails configurados esencialmente reenviará las solicitudes al LLM.
La estructura estándar para una carpeta de configuración de guardrails tiene este aspecto:```
.
├── config
│ ├── actions.py
│ ├── config.py
│ ├── config.yml
│ ├── rails.co
│ ├── ...
El config.yml contiene todas las opciones de configuración generales, como modelos de LLM, rails activos y datos de configuración personalizados". El archivo config.py contiene cualquier código de inicialización personalizado y actions.py contiene cualquier acción personalizada de python. Para una descripción general completa, consulta 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 (consulte la siguiente sección para obtener una descripción general rápida de qué es Colang) que definen varios tipos de rails. A continuación se muestra un ejemplo de archivo `greeting.co` que define los rails de diálogo 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 carril 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 varios tipos de guardarraíles, este kit de herramientas presenta **Colang**, un lenguaje de modelado creado específicamente para diseñar flujos de diálogo flexibles, aunque 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 una breve introducción a la sintaxis de Colang 1.0, consulta la Guía de sintaxis del lenguaje Colang 1.0.
Para comenzar con Colang 2.0, consulta 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 salvaguardas para la autocomprobació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 temática), detección de jailbreak e inyección, e integraciones con modelos de la comunidad y API de terceros. Para 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 de NeMo Guardrails también viene con 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.
Puede usar la CLI de la biblioteca 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
No se ha proporcionado ningún contenido en la entrada para traducir.```json { "config_id": "sample", "messages": [{ "role":"user", "content":"Hello! What can you do for me?" }] }
Ejemplo de salida:```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 uso de 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 Documentación de integración de LangChain.
Evaluar la seguridad de una aplicación conversacional basada en LLM es una tarea compleja y sigue siendo una cuestión 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., cadena constitucional), 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 kit de herramientas flexible que pueda integrar todos estos enfoques complementarios en una capa cohesiva de guardrails para LLM. Por ejemplo, el kit de herramientas ofrece integración lista para usar con ActiveFence, PolicyAI, AlignScore y cadenas de LangChain.
Hasta donde sabemos, la biblioteca NeMo Guardrails es el único kit 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 manera precisa. Por otro lado, permite un control granular 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 implementación y funciones de seguridad son más utilizados. La biblioteca emite un evento de uso cuando se instancia 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. 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 versiones exactas 0.22.0 y 0.23.0, del 22 de mayo al 18 de agosto de 2026:
Última actualización: 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 de 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 utiliza 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 cada carga útil de evento en un archivo de auditoría local en ~/.config/nemoguardrails/usage_stats.json. El archivo de auditoría almacena los eventos en JSONL, no el sobre completo de telemetría de NVIDIA. Las escrituras de auditoría se realizan con el mejor esfuerzo, y la transmisión de telemetría continúa incluso si falla 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
Establezca la exclusión voluntaria 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 que ya esté en ejecución.
Consulte [docs/telemetry.md](https://docs.nvidia.com/nemo/guardrails/latest/telemetry.html) para ver el esquema completo y las descripciones campo por campo.
Puede excluirse de 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 separados. La biblioteca NVIDIA NeMo Guardrails puede usar 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á pensado únicamente para evaluación y pruebas y no debe usarse en entornos de producción. No envíe información confidencial ni datos personales al utilizar NVIDIA Build.
## Invitación 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 a 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 [directrices de contribución](https://github.com/nvidia-nemo/guardrails/blob/develop/CONTRIBUTING.md).
## Licencia
La biblioteca NeMo Guardrails está licenciada bajo la [Apache License, Versión 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",
}