Более подробные инструкции см. в [Руководстве по установке](https://docs.nvidia.com/nemo/guardrails/get-started/installation-guide).

## Обзор

<!-- start-documentation-reuse -->

Библиотека NeMo Guardrails позволяет разработчикам, создающим приложения на основе LLM, добавлять **программируемые ограждения** (programmable guardrails) между кодом приложения и 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>

Ключевые преимущества добавления *программируемых ограждений*:

- **Создание надёжных, безопасных и защищённых приложений на основе LLM:** вы можете определять ограждения для управления и защиты диалогов; вы можете задать поведение вашего приложения на основе LLM по определённым темам и предотвратить его участие в обсуждениях нежелательных тем.

- **Безопасное подключение моделей, цепочек и других сервисов:** вы можете безопасно и бесшовно подключать LLM к другим сервисам (также известным как инструменты).

- **Управляемый диалог**: вы можете направлять LLM по заранее заданным сценариям разговора, что позволяет проектировать взаимодействие в соответствии с лучшими практиками дизайна диалогов и обеспечивать соблюдение стандартных операционных процедур (например, аутентификация, поддержка).

<!-- end-documentation-reuse -->

### Защита от уязвимостей LLM

Библиотека NeMo Guardrails предоставляет несколько механизмов защиты чат-приложений на основе LLM от распространённых уязвимостей LLM, таких как джейлбрейки и инъекции промптов. Ниже приведён примерный обзор защиты, обеспечиваемой различными конфигурациями ограждений для примера [ABC Bot](https://github.com/nvidia-nemo/guardrails/blob/develop/examples/bots/abc), включённого в этот репозиторий. Более подробную информацию см. на странице [Сканирование уязвимостей 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>

### Сценарии использования

Программируемые ограждения можно применять в различных типах сценариев использования:

1. **Ответы на вопросы** по набору документов (также известное как Retrieval Augmented Generation): обеспечение проверки фактов и модерации вывода.
2. **Ассистенты для конкретных предметных областей** (также известные как чат-боты): обеспечение того, чтобы ассистент оставался в рамках темы и следовал спроектированным сценариям разговора.
3. **Конечные точки LLM**: добавление ограждений к вашей пользовательской LLM для более безопасного взаимодействия с клиентами.
4. **Цепочки LangChain** (опционально): если вы используете LangChain для какого-либо сценария, вы можете добавить слой ограждений вокруг ваших цепочек. Чтобы включить эту интеграцию, задайте переменную окружения `NEMOGUARDRAILS_LLM_FRAMEWORK=langchain` или вызовите `set_default_framework("langchain")`.

### Использование

Чтобы добавить программируемые ограждения в ваше приложение, вы можете использовать Python API или сервер ограждений (см. [Руководство по серверу](https://docs.nvidia.com/nemo/guardrails/get-started/integrate-into-application) для получения подробной информации). Использование Python API аналогично прямому использованию LLM. Вызов слоя ограждений вместо LLM требует лишь минимальных изменений в кодовой базе и включает два простых шага:

1. Загрузка конфигурации ограждений и создание экземпляра `LLMRails`.
2. Выполнение вызовов к LLM с использованием методов `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!"}]
)

Формат ввода и вывода для метода `generate` аналогичен [Chat Completions API](https://platform.openai.com/docs/guides/gpt/chat-completions-api) от OpenAI.

#### Асинхронный API

Библиотека NeMo Guardrails — это набор инструментов, ориентированный в первую очередь на асинхронность, поскольку основные механизмы реализованы с использованием асинхронной модели Python. Публичные методы имеют как синхронную, так и асинхронную версии. Например: `LLMRails.generate` и `LLMRails.generate_async`.

### Поддерживаемые LLM

Вы можете использовать NeMo Guardrails с несколькими LLM, такими как OpenAI GPT-3.5, GPT-4, LLaMa-2, Falcon, Vicuna или Mosaic. Для получения более подробной информации ознакомьтесь с разделом [Supported LLM Models](https://docs.nvidia.com/nemo/guardrails/about-nemo-guardrails-library/supported-llms) в руководстве по конфигурации.

### Типы Guardrails

Библиотека NeMo Guardrails поддерживает пять основных типов 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. **Input rails**: применяются к входным данным от пользователя; input rail может отклонить входные данные, остановив любую дополнительную обработку, или изменить входные данные (например, для маскировки потенциально конфиденциальных данных, для перефразирования).

2. **Dialog rails**: влияют на то, как формируется запрос к LLM; dialog rails работают с сообщениями в канонической форме, подробности см. в [Colang Guide](https://docs.nvidia.com/nemo/guardrails/configure-guardrails/colang)) и определяют, следует ли выполнить действие, следует ли вызвать LLM для генерации следующего шага или ответа, следует ли вместо этого использовать предопределённый ответ и т. д.

3. **Retrieval rails**: применяются к извлечённым фрагментам в случае сценария RAG (Retrieval Augmented Generation); retrieval rail может отклонить фрагмент, предотвратив его использование для формирования запроса к LLM, или изменить соответствующие фрагменты (например, для маскировки потенциально конфиденциальных данных).

4. **Execution rails**: применяются к входным/выходным данным пользовательских действий (также известных как инструменты), которые должны быть вызваны LLM.

5. **Output rails**: применяются к выходным данным, сгенерированным LLM; output rail может отклонить выходные данные, предотвратив их возврат пользователю, или изменить их (например, удалив конфиденциальные данные).

### Конфигурация Guardrails

Конфигурация guardrails определяет **LLM**, которые будут использоваться, и **один или несколько guardrails**. Конфигурация guardrails может включать любое количество input/dialog/output/retrieval/execution rails. Конфигурация без настроенных rails по сути будет перенаправлять запросы к LLM.

Стандартная структура папки конфигурации guardrails выглядит следующим образом:```
.
├── config
│   ├── actions.py
│   ├── config.py
│   ├── config.yml
│   ├── rails.co
│   ├── ...

Файлы `.co`, включённые в конфигурацию guardrails, содержат определения Colang (см. следующий раздел для краткого обзора того, что такое Colang), которые определяют различные типы rails. Ниже приведён пример файла `greeting.co`, который определяет dialog rails для приветствия пользователя.```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

Для настройки и реализации различных типов guardrails этот инструментарий представляет **Colang** — язык моделирования, специально созданный для проектирования гибких, но при этом контролируемых диалоговых потоков. Colang имеет синтаксис, похожий на Python, и разработан так, чтобы быть простым и интуитивно понятным, особенно для разработчиков.```{note}
Two versions of Colang, 1.0 and 2.0, are supported and Colang 1.0 is the default.

Библиотека включает guardrails для самопроверки LLM (модерация ввода/вывода, проверка фактов, обнаружение галлюцинаций), модели безопасности NVIDIA (безопасность контента, безопасность тем), обнаружение jailbreak и инъекций, а также интеграции с моделями сообщества и сторонними API. Полный список см. в [документации по библиотеке Guardrails](https://docs.nvidia.com/nemo/guardrails/user-guides/guardrails-library.html).

## CLI

Библиотека NeMo Guardrails также поставляется со встроенным CLI.```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.

Например, чтобы получить завершение чата для конфигурации `sample`, можно использовать эндпоинт `/v1/chat/completions`:```
POST /v1/chat/completions

./tool -u https://example.com

./tool -l targets.txt -o results.json -f json

./tool -u https://example.com -p http://127.0.0.1:8080 -H "Authorization: Bearer token"

./tool -l targets.txt -t 50 -T 10

threads: 20
timeout: 15
retries: 5
output_format: json
proxy: http://127.0.0.1:8080
headers:
  User-Agent: "Custom Agent"
  Accept: "*/*"

Пример вывода:```json
{"role": "assistant", "content": "Hi! How can I help you?"}

Установите отказ от телеметрии до запуска библиотеки NVIDIA NeMo Guardrails. Изменение переменных среды или создание `do_not_track` после запуска телеметрии не остановит уже работающий поток heartbeat.

Обратитесь к [docs/telemetry.md](https://docs.nvidia.com/nemo/guardrails/latest/telemetry.html) для получения полной схемы и описания каждого поля.

Вы можете отказаться от сбора телеметрии в любое время. Отказ применяется только к сбору данных самой библиотекой NVIDIA NeMo Guardrails.

Сторонние конечные точки имеют отдельные условия и правила конфиденциальности. Библиотека NVIDIA NeMo Guardrails может использовать конечные точки вывода, такие как NVIDIA Build (`build.nvidia.com`). Если вы используете NVIDIA Build или другую стороннюю конечную точку, условия обслуживания и правила конфиденциальности этой конечной точки применяются независимо от библиотеки. Любой отказ от телеметрии в библиотеке NVIDIA NeMo Guardrails не распространяется на выбранную вами конечную точку. NVIDIA Build предназначен только для оценки и тестирования и не должен использоваться в производственных средах. Не передавайте конфиденциальную информацию или персональные данные при использовании NVIDIA Build.

## Приглашение сообщества к участию

Примеры rails, находящиеся в репозитории, являются отличными отправными точками. Мы с энтузиазмом приглашаем сообщество внести свой вклад в то, чтобы сделать возможности надёжных, безопасных и защищённых LLM доступными для всех. Руководство по настройке среды разработки и участию в разработке библиотеки NeMo Guardrails см. в [руководстве по участию](https://github.com/nvidia-nemo/guardrails/blob/develop/CONTRIBUTING.md).

## Лицензия

Библиотека NeMo Guardrails лицензирована в соответствии с [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0).

## Как цитировать

Если вы используете библиотеку NeMo Guardrails, цитируйте [статью EMNLP 2023](https://aclanthology.org/2023.emnlp-demo.40), в которой она представлена.```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",
}