Сценарии Guardrails для RAG и Memory

На какие требования опираемся

Для RAG это ING-6 — проверка персональных данных и классификация до индексации, а также RET-8 — проверка извлечённого контекста. Для Memory — SEC-2: маскирование персональных данных до долговременного сохранения, включая проверку извлечённых фактов. Ниже описан предлагаемый адаптер к существующему API проверки текста, а не уже включённая интеграция в сервисах соседних команд.

Описания команд в Team Docs содержат различия между целевым API и поставкой. Руководство RAG отмечает отсутствие /v1/retrieve_and_pack и переиндексации через API. Руководство Memory отдельно отмечает, что Guardrails, JWT/SpiceDB-интеграция и некоторые операции памяти/контрольных точек ещё не включены. Поэтому первым этапом здесь используются приём документа и /v1/query для RAG, добавление/поиск/список памяти для Memory. Доступность конкретной версии их сервисов должна подтвердить соответствующая команда.

Общие правила преобразования

Извлеките только проверяемые текстовые поля в сообщения. Рядом сохраните таблицу позиций, например 0 → document.content.title, 1 → sections[0].text. После mask заменяйте поля по этой таблице. Не пытайтесь восстановить привязку по совпадению строк: одинаковый текст может встречаться в разных полях.

Сервис продолжает владеть doc_id, memory_id, agent_id, run_id, ACL, фильтрами доступа и ссылками на источник. Эти данные не являются параметрами Guardrails. Не передавайте их как дополнительные поля HTTP-тела. Поля title, подписи таблиц, строковые значения метаданных и URL могут сами содержать персональные данные: явно включите нужные поля в карту проверки либо исключите их из сохраняемых/выдаваемых данных. Проверка только content не покрывает остальные поля автоматически.

Один вызов оценивает набор сообщений целиком. HTTP-ответ не сообщает, какой именно документ вызвал запрет. Для независимого решения по каждому документу вызывайте Guardrails отдельно, с ограниченной конкурентностью. Стоп-лист и регулярные выражения не склеивают границы разных сообщений. Разрезанная между частями запрещённая фраза может не обнаружиться; LLM-проверка также не даёт гарантии обходоустойчивости.

Документ больше лимита нельзя молча обрезать. Согласуйте единицу проверки, размер частей, перекрытие и проверку собранного контекста. Если документ должен попасть в индекс целиком, сначала соберите результаты всех частей и только затем публикуйте новую версию. Ошибка последней части не должна оставлять первые части уже доступными пользователям.

RAG: приём документа

Точка входа по API RAG — POST /v1/documents:submit. Предлагаемый порядок для upsert:

1. Проверить права и форму документа обычным механизмом RAG. Выбрать политику по доверенной конфигурации коллекции/сервиса.
2. Для content извлечь текст из заголовка, секций и таблиц по явному списку полей. Для content_ref сначала получить и распарсить содержимое в RAG: Guardrails сам не скачивает S3/HTTP-объекты и не проверяет их по URI.
3. Отправить текст в /request. Для каждого поля использовать сообщение {"role":"user","content":"..."}. Конкретная роль здесь — соглашение адаптера, а не повышение доверия к документу.
4. При pass продолжить с проверенными строками. При mask сформировать новый канонический документ из возвращённых строк, сохранив идентификаторы и ACL.
5. Из проверенной версии строить части, эмбеддинги, индекс и поисковые выдержки. Если в системе есть хэш исходника для дедупликации, сохранить его назначение; отдельно хранить отпечаток обработанного представления. Не подменять смысл content_hash существующего API без решения команды RAG.
6. При запрете завершить документ отказом; при технической ошибке не публиковать его в индексе. Отображение этих случаев в FAILED/error_code задания согласует команда RAG. Новых HTTP-кодов её API это руководство не вводит.

202 Accepted у приёма документа означает принятие задания, а не прохождение Guardrails. Признак завершения должен появляться только после проверки и публикации разрешённой версии. Повторы должны использовать исходный ключ идемпотентности задания и согласованную ревизию политики.

Если сырые документы сохраняются в S3 или очереди до проверки, формулировка «персональные данные нигде не сохраняются» неверна. Для требования «до индекса» допустимость закрытого временного хранилища, его срок жизни и доступ определяет команда. Для более строгого требования проверку нужно ставить до такой записи. Удаление документа не должно блокироваться проверкой его удаляемого текста.

RAG: поисковая выдача

В первой интеграции используйте реализованный POST /v1/query.

1. Авторизовать поиск, применить ACL и фильтры средствами RAG.
2. Проверить текст поискового запроса до отправки во внешний сервис эмбеддингов, переписывания или ранжирования, если политика ограничивает такую передачу.
3. Получить разрешённые результаты и составить карту позиция → items[i].content и других выдаваемых текстовых полей.
4. Проверить выдачу через /response, используя choices[].message. При mask обновить соответствующие строки. doc_id, chunk_id и оценки релевантности остаются под управлением RAG.
5. Из проверенных строк собрать контекст для модели, пересчитать бюджет токенов. Если классификатор оценивает контекст целиком, проверить и итоговую сборку. Не добавлять после проверки непроверенные заголовки или исходные выдержки.

Предлагаемый вариант отказа для первого этапа — остановить выдачу целиком при deny/ошибке. Выборочно удалить опасный фрагмент можно только с отдельной проверкой каждого фрагмента и явно согласованным поведением частичной выдачи. При этом нужно пересчитать количество результатов и бюджет токенов, сохранить корректность цитат и не раскрыть удалённый текст в пояснениях.

Маскированная цитата уже не дословна: в отображении и ссылках на источник это должно учитываться. Ссылка на исходный документ не должна обходить его ACL или раскрывать данные, ради которых применили маскирование.

Memory: запись диалога и извлечение фактов

Точка входа — POST /v1/memories, поля messages, agent_id/run_id, infer. Порядок внедрения:

1. Выполнить проверки прав и области памяти. Guardrails не решает, чью память можно изменять, и не заменяет фильтры Memory.
2. Проверить messages перед очередью, если нельзя сохранять исходные ПД в её сообщениях. Для разрешённого промежуточного хранения явно определить срок и доступ. Поля сообщений Memory преобразовать в поддержанные role/content.
3. При infer: true отправить разрешённые сообщения в извлечение фактов. Если требуется скрыть ПД от модели извлечения, отправлять только результат локального маскирования. Проверка одного вызова модели не гарантирует безопасность произвольного нового факта после последующей обработки.
4. Проверить полученные факты перед записью. Для этой границы рекомендуем отдельную политику memory-write, секцию request, по одному сообщению на факт. В ней можно совместить локальные маски и классификацию допустимого факта. Имя политики — предложение конфигурации; готовой политики с таким именем нет.
5. При infer: false пройти ту же проверку перед записью. Этот путь не должен обходить Guardrails только потому, что LLM не вызывается.
6. Сохранять разрешённый/маскированный факт. История изменений, эмбеддинги, полнотекстовый индекс и производные поля должны создаваться из него. Повторная сборка объекта не должна вернуть исходный текст.
7. Завершить событие успешным только после сохранения разрешённого результата. При запрете/ошибке не выдавать SUCCEEDED с непроверенным фактом. Сопоставление с PENDING/SUCCEEDED/FAILED и кодами ошибок принадлежит команде Memory.

Правила для диалога и долговременного факта могут различаться: вопрос пользователя не всегда является фактом, который стоит запоминать. Не используйте Telecom- классификатор по умолчанию для всех доменов памяти.

custom_instructions/prompt из запроса Memory не должны становиться инструкцией самого Guardrails-классификатора. Его инструкция хранится в версии политики. Если пользовательские инструкции передаются модели извлечения, их нужно отдельно включить в анализ угроз и проверяемый вход Memory.

Memory: чтение и поиск

Для POST /v1/memories/search и GET /v1/memories:

1. Применить права, фильтры, срок действия фактов.
2. Получить факты и проверить выдаваемые строки results[i].memory через /response. Вести таблицу позиций до исходных id.
3. Подставить маскированный текст и пересчитать производные данные выдачи, включая tokens_returned, если они есть. Не менять идентификатор или область памяти.
4. При отказе не возвращать исходный текст. Поведение частичной выдачи согласовать отдельно; по умолчанию в первой интеграции останавливать весь результат.

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

Операции контрольных точек с произвольным объектом или base64 не покрываются текстовым API. Нельзя сериализовать непрозрачный снимок в строку и утверждать, что все его данные проверены. Для такого пути сначала нужен контракт извлечения и восстановления текстовых полей. Операции удаления и право на забвение не должны зависеть от разрешения Guardrails на содержимое удаляемой записи.

Ошибки, очереди и идемпотентность

При PolicyDenied повтор того же текста не является исправлением. При CheckUnavailable остановите запись/выдачу, а задание отложите либо завершите ошибкой в пределах согласованной политики повторов. Ограничьте число попыток, суммарное время и конкурентность; используйте задержку с разбросом, чтобы восстановление Guardrails не вызвало одновременный поток повторов.

Guardrails не знает job_id/event_id и не фиксирует успешную запись в вашей БД. Сохраните выбранную ревизию и контрольную сумму набора рядом с заданием. Правило повторной проверки после изменения политики должно быть явным: «то же задание с прежней ревизией» либо контролируемая перепроверка новой ревизией. Не переключайтесь незаметно на текущую политику в середине обработки документа.

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

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

Локальные примеры проверяют HTTP и применение результата к тексту. Они не заменяют эти сквозные испытания с настоящими RAG/Memory и их хранилищами.