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!"}]
)

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
│   ├── ...

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?"

### 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.

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.

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

# 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

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

Salida de ejemplo:```json
{"role": "assistant", "content": "Hi! How can I help you?"}

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",
}