Подключение и эксплуатация Guardrails

Что передать команде сервиса

Для вызовов из RAG и Memory нужен внутренний адрес Guardrails и согласованная конфигурация. Адрес Control Plane не является адресом проверки текста. Конкретные имена Kubernetes Service, секреты и ревизии зависят от среды; в руководстве они намеренно не подставлены из локального демонстрационного кластера.

В текущем процессе Guardrails один входящий сервисный токен. Владелец этого токена может выбирать любую присутствующую в наборе политику; отдельной проверки прав «этот токен может вызывать только эту политику» нет. Если командам нужны разные границы доступа, поставьте отдельные экземпляры с отдельными наборами/секретами либо согласуйте внешний механизм ограничения. Не раздавайте токен работающего Gateway как готовое универсальное подключение для всех команд.

Ограничения сети и TLS обеспечивает среда. Сам HTTP-процесс запускается на заданном адресе/порту; serve не настраивает сертификаты. Разрешите только нужные источники вызовов и назначения провайдеров. Настройки DNS/исходящего доступа должны исключать обход согласованных адресов и рекурсивные вызовы. Такая конфигурация для RAG/Memory этим документом не развёртывается.

Настройки процесса

Токен содержит от 32 до 4096 печатных ASCII-символов без пробелов. Завершающий перевод строки в файле допускается. Секреты не хранятся внутри политики, примера запроса или Git. Правило содержит только credentialRef.

Для внешнего классификатора недостаточно вписать URL в редактор политики: адрес, протокол, модель и ссылка на секрет должны пройти допуск среды. Провайдерская модель может быть любой, совместимой с выбранным профилем. Автоматической привязки к конкретному поставщику нет.

HTTP-клиент Guardrails проверяет TLS, не следует редиректам и не использует прокси из переменных окружения. Классификатор вызывается по согласованному прямому адресу. Вызов собственной защищённой модели через Gateway создаст рекурсию: проверка будет снова вызывать саму себя.

Текст уходит внешнему провайдеру только для правил, которые его вызывают. Локальные стоп-листы и регулярные выражения внешнюю модель не используют. Если ПД запрещено передавать классификатору, сначала выполните отдельную локальную проверку с маскированием. Порядок правил одной политики эту задачу не решает: правила видят исходный текст.

Подготовка и смена версии

Набор политик имеет schemaVersion: agent-platform.guardrail-runtime.bundle/v1, содержит обе стадии проверок, список провайдеров и общие ограничения. Guardrails читает и проверяет его при старте. Изменение файла на диске не приводит к перечитыванию. Управляющего метода перезагрузки нет.

Для обновления нужны новый проверенный набор, его контрольная сумма и новый процесс или поколение развёртывания. Клиент должен переключать согласованный набор «адрес, политика, ревизия, контрольная сумма, профиль» как единое целое. Пока один Service распределяет запросы между старыми и новыми наборами, часть вызовов с новой контрольной суммой получит 503. Для прямых потребителей используйте адрес поколения либо согласованное переключение, которое исключает такое смешение.

Старое поколение сохраняют, пока завершаются его запросы и пока нужен откат. Обработка старых заданий очереди тоже должна учитываться. Число поколений и срок их хранения ограничивают явно; бесконечное сохранение не заменяет план удаления. В текущей управляемой доставке через Control Plane есть предел 32 поколения и нет автоматического удаления по возрасту.

Для модельной привязки подготовку, ожидание готовности и проверку конфигурации Gateway выполняет Control Plane. Guardrails не обращается к БД Control Plane или Kubernetes на каждый запрос. Поэтому недоступность управления сама по себе не останавливает уже загруженные проверки. Отзыв политики также требует новой доставки или явного снятия привязки, а не только изменения записи в БД.

Размеры, время и нагрузка

Для новых поколений, создаваемых Control Plane, предел тела одной проверки — 1 МиБ, до 64 сообщений. Это размер JSON в байтах, а не число токенов модели. Контекст не обрезается: при превышении возвращается 413 body_too_large. Сохранённые поколения сохраняют прежние ограничения до повторного применения политики.

Профиль установки допускает явный раздел runtimeLimits: maxBodyBytes, maxMessages, maxMatches, maxConcurrency, maxInFlightBytes, queueSize. Значения по умолчанию — соответственно 1048576, 64, 256, 32, 8388608, 0. Предел одной проверки можно настроить до 2 МиБ. Перед увеличением проверьте ограничения шлюза, таймауты правил и память на ожидаемой нагрузке. Это настройка установки, а не поле пользовательской политики.

maxInFlightBytes ограничивает суммарный объём принятых тел, пока проверки выполняются. Бюджет освобождается также при ошибке, отмене и таймауте. Он не равен полной памяти процесса: разобранный JSON, результаты маскирования, библиотеки и сетевые буферы требуют дополнительной памяти. Ограничение памяти контейнера и нагрузочная проверка остаются необходимыми.

У внешнего детектора и LLM-классификатора есть отдельный maxInputBytes. Он учитывает сериализованный запрос поставщику, включая инструкцию классификатора. Увеличение общего лимита Runtime не увеличивает этот предел автоматически и не расширяет контекстное окно модели. Большие запросы для таких правил нужно согласовать отдельно; молчаливого сокращения текста нет.

У Guardrails нет внутренней очереди: при заполнении лимита одновременных проверок возвращается 503 overloaded. Ограничивайте число параллельных вызовов со стороны обработчиков RAG/Memory. Суммарная нагрузка всех процессов и повторов важнее ограничения одного обработчика.

Общий бюджет стадии включает получение тела, разбор, правила и подготовку ответа. Каждое правило также имеет свой таймаут. Например, учебная политика имеет бюджет 250 мс, а пример клиента ждёт до 1 секунды на сетевую фазу. Это значения для локальной проверки, не обещание задержки реального сервиса. Для LLM-проверки согласуйте бюджет отдельно; максимум схемы — 5000 мс на стадию.

Общий срок операции сервиса должен учитывать соединение, передачу тела, выполнение правил, применение результата и возможный повтор. По окончании этого срока отменяйте запрос. Не позволяйте позднему ответу продолжить запись уже отменённого задания. При повторе не запускайте неограниченное число параллельных проверок одного документа.

Наблюдение и диагностика

GET /readyz возвращает {"ready":true}, если набор загружен. Это не проверка качества правил, доступности внешней модели или применения конфигурации Gateway. После запуска выполните синтетические проверки разрешения, маскирования и запрета; одного состояния готовности недостаточно.

GET /metrics требует сервисного токена. Метрики содержат ограниченные счётчики проверок, ошибок, наблюдаемых срабатываний и длительности. Они не содержат текст, ключи, адреса провайдеров или имена политик в метках. Это показатели процесса, которые сбрасываются при перезапуске, а не журнал всех решений. Общего хранилища результатов или гарантированной записи каждого решения во внешнюю систему аудита Guardrails не предоставляет.

Не включайте запись тел запросов в прокси и журнале приложения ради диагностики. Используйте код ошибки, идентификатор задания, версию политики и длительность. Проверка причин не должна создавать новую копию защищаемых данных в журнале.

Последовательность ввода в работу

1. Обе команды согласуют точки записи/чтения и поля, которые нужно проверять.
2. Владелец политики готовит правила и синтетический корпус, платформа — конфигурацию и доступ.
3. Команда сервиса проверяет локальные примеры и правильность обработки всех трёх решений.
4. На общей тестовой среде выполняются сквозные сценарии, включая недоступность Guardrails и повтор задания.
5. Проверяются новое поколение, переключение и откат, а затем согласуется включение для реальных данных.

Прохождение примеров из документа подтверждает контракт проверки текста. Готовность интеграции в сервисе подтверждается только испытанием его реальной записи и выдачи вместе с хранилищами, очередями и проверками доступа.

Потоковые ответы и нагрузка

Для нового профиля шлюз передаёт x-ap-gr-response-mode, включает проверку SSE и сохраняет вложения при входном маскировании. Изображения не проходят через Runtime. При срабатывании выходного маскирования SSE останавливается, тогда как обычный JSON-ответ маскируется. Контракт и ограничения.

Оценивайте задержку на всём маршруте: клиент, шлюз, правила и модель. Для Runtime измеряйте длительность проверок, ошибки overloaded и таймауты; для шлюза — память, процессор, время до первого текста и число активных потоков. Сравнивайте одинаковый текст с вложением и без него при одинаковой конкурентности. Число проверок SSE зависит от объёма ответа. Внешний детектор и LLM-классификатор могут вызываться для каждого окна; их задержка и квоты требуют отдельного нагрузочного прогона. Нельзя переносить показатели стоп-листа на классификатор. maxConcurrency, отсутствие внутренней очереди и бюджет стадии ограничивают накопление работы; при превышении лимитов проверка завершается ошибкой, а содержимое не пропускается без защиты.