Подключение RAG и Memory к Guardrails

Назначение и статус

Руководство предназначено разработчикам RAG и Memory, которые подключают проверку текста перед индексацией, сохранением и выдачей данных. Guardrails принимает текст, выполняет выбранную версию политики и возвращает разрешение, запрет или текст с маскированием. Решение применяет вызывающий сервис.

Описание нового профиля agentgateway-1.5.0-chat-webhook-v2 обновлено 17 сентября 2026 года. Примеры прямого вызова ниже сохраняют прежний текстовый профиль: их формат и режим маскирования не изменились. Для интеграции с новым профилем дополнительно задайте доверенный заголовок x-ap-gr-response-mode: buffered; sse-reject используется шлюзом для проверки окон потокового ответа. Различия режимов. Подключение к самим сервисам RAG и Memory необходимо реализовать и проверить совместно с их владельцами; наличие API не означает, что оно уже включено. Существующие контракты RAG и Memory здесь не меняются.

Читать последовательно:

1. Эта страница — границы компонентов и первый работающий вызов.
2. API проверки текста — точные HTTP-запросы, ответы, ошибки и ограничения.
3. Сценарии RAG и Memory — точки вызова, преобразование данных и критерии приёмки.
4. Политики и применение через Control Plane — API управления для владельцев политик.
5. Подключение и эксплуатация — параметры среды, версии, таймауты и диагностика.

Кто за что отвечает

Есть два способа использовать текущую реализацию:

• Проверка вызовов модели через Agentgateway. Политика привязывается к модели в Control Plane. Gateway сам вызывает /request и /response. Это защищает поддержанный текстовый вызов модели, но не отдельную запись в хранилище RAG или Memory.
• Прямая проверка из сервиса. Адаптер вызывает тот же API Guardrails перед записью или выдачей. Этот путь можно проверить локально уже сейчас. Для общей среды нужно отдельно согласовать и поставить адрес, доступ и выбранные версии. Автоматических привязок вида «политика → коллекция RAG / память агента» в Control Plane нет.

Не создавайте второй сервис-переводчик только ради HTTP-формата: достаточно небольшого адаптера внутри вашего сервиса. Guardrails не получает tenant_id, права на коллекцию или пользователя и не заменяет ваши проверки доступа.

Первый запуск без внешних моделей

Нужны рабочая копия указанной ветки agent-platform, uv и Python 3.14 для Guardrails. Команды ниже выполняются из корня репозитория. Kubernetes и ключ внешней LLM не нужны. Пример включает стоп-фразу BLOCK-CONTENT и маскирование email на обеих стадиях. Это учебная политика, а не полный набор правил для персональных данных.

Сначала установите зависимости и проверьте конфигурацию:

uv sync --project src/guardrail-runtime --locked
uv run --project src/guardrail-runtime --locked guardrail-runtime validate \
  --bundle docs/examples/guardrails-integration/policy-bundle.json

Ожидается код завершения 0, политика rag-memory-text, ревизия 1 и поле digest. Для приложенного файла контрольная сумма равна b879b5f4c909ae91f775a9276e726590b35a3bcd8917e1cb9ef7fa6f1c47279c. Это SHA-256 канонического JSON RFC 8785, без префикса sha256:. Обычный sha256sum форматированного файла даст другое значение.

Проверьте маскирование без HTTP:

uv run --project src/guardrail-runtime --locked guardrail-runtime dry-run \
  --bundle docs/examples/guardrails-integration/policy-bundle.json \
  --policy rag-memory-text --revision 1 --stage request \
  --input docs/examples/guardrails-integration/request.json

Ожидается outcome: "mask" и текст Связаться: [EMAIL]. dry-run возвращает дополнительные findings; онлайн API их не возвращает. В результатах локальной команды может быть текст: не запускайте её с реальными персональными данными в записываемом терминале или CI-журнале.

Для HTTP создайте отдельный временный каталог. В нём будет только локальный одноразовый токен; команда не выводит его и не меняет секреты платформы:

export GR_DEMO_DIR="$(mktemp -d)"
uv run --project src/guardrail-runtime --locked python - <<'PY'
import os, secrets
from pathlib import Path
p = Path(os.environ['GR_DEMO_DIR']) / 'token'
p.write_text(secrets.token_urlsafe(48))
p.chmod(0o600)
PY
export AP_GUARDRAIL_RUNTIME_BUNDLE_FILE="$PWD/docs/examples/guardrails-integration/policy-bundle.json"
export AP_GUARDRAIL_RUNTIME_BUNDLE_DIGEST=b879b5f4c909ae91f775a9276e726590b35a3bcd8917e1cb9ef7fa6f1c47279c
export AP_GUARDRAIL_RUNTIME_TOKEN_FILE="$GR_DEMO_DIR/token"
export AP_GUARDRAIL_RUNTIME_PROVIDER_ORIGINS='[]'
export AP_GUARDRAIL_RUNTIME_CREDENTIAL_FILES='{}'
export AP_GUARDRAIL_RUNTIME_CLASSIFIER_TARGETS='[]'
echo "$GR_DEMO_DIR"
uv run --project src/guardrail-runtime --locked guardrail-runtime serve \
  --host 127.0.0.1 --port 18090

Процесс остаётся в первом терминале. Во втором терминале перейдите в ту же рабочую копию, укажите путь GR_DEMO_DIR, выведенный перед запуском сервера, и выполните:

export GR_DEMO_DIR=/путь/к/временному/каталогу
curl --fail --silent http://127.0.0.1:18090/readyz
uv run --project src/guardrail-runtime --locked python - <<'PY'
import os, sys
from pathlib import Path
sys.path.insert(0, 'docs/examples/guardrails-integration')
from guardrails_client import GuardrailsClient, PolicyDenied

with GuardrailsClient(
    base_url='http://127.0.0.1:18090',
    token_file=Path(os.environ['GR_DEMO_DIR']) / 'token',
    policy_id='rag-memory-text', revision='1',
    digest='b879b5f4c909ae91f775a9276e726590b35a3bcd8917e1cb9ef7fa6f1c47279c',
    schema_file=Path('src/guardrail-runtime/guardrail_runtime/contracts/openapi.json'),
) as guardrails:
    clean = guardrails.check('request', [{'role': 'user', 'content': 'Обычный текст'}])
    assert clean.outcome == 'pass'
    masked = guardrails.check('request', [{'role': 'user', 'content': 'Связаться: demo@example.org'}])
    assert masked.messages[0]['content'] == 'Связаться: [EMAIL]'
    try:
        guardrails.check('response', [{'role': 'assistant', 'content': 'BLOCK-CONTENT'}])
    except PolicyDenied:
        print('PASS: разрешение, маскирование и блокировка через HTTP')
    else:
        raise AssertionError('Ожидалась блокировка')
PY

Ожидается {"ready":true} и строка PASS. После проверки остановите сервер через Ctrl-C. Удалите только созданный токен и пустой каталог:

test -n "$GR_DEMO_DIR" && rm -- "$GR_DEMO_DIR/token"
test -n "$GR_DEMO_DIR" && rmdir -- "$GR_DEMO_DIR"

Что можно забрать в свой сервис

Пример клиента на Python использует httpx и jsonschema. Он проверяет схему ответа, ограничивает объём, не следует редиректам и различает PolicyDenied и CheckUnavailable. Создавайте один экземпляр на жизненный цикл обработчика, не на каждый факт. Синхронный пример не вызывайте непосредственно в цикле событий асинхронного сервиса: используйте выделенный поток либо перенесите тот же алгоритм на httpx.AsyncClient. Фазовые таймауты HTTP-клиента не заменяют общий срок операции.

Это пример интеграции, не выпущенный SDK. Версии зависимостей для вашей поставки фиксирует ваша команда; проверенный набор находится в src/guardrail-runtime/uv.lock. Пример не создаёт очереди, не пишет данные и не реализует повторы автоматически.

Доступны также OpenAPI, схема политик, учебная политика и входной запрос. Версии файлов и контрольные суммы включены в манифест артефактов.

Переход к общей среде

Перед передачей реальных данных получите у платформенной команды единый набор: адрес Guardrails, доверенный сертификат и имя сервера, путь к сервисному секрету, идентификатор и ревизию политики, контрольную сумму набора, профиль содержимого, лимиты и таймауты. Эти значения задаются конфигурацией сервиса, а не полями пользовательского запроса. Список и владельцы параметров приведены в эксплуатационном разделе.

Начните со стоп-листа и синтетических данных. Затем проверьте сохранение именно маскированного текста, поведение при недоступности Guardrails и повторы очереди. Перед подключением LLM-классификатора согласуйте, какие данные разрешено передавать выбранной модели, и проверьте качество на примерах своей команды.