Что такое Baza и какую задачу она решает на полигоне
Baza начиналась как локальная база знаний: Markdown-файлы на диске, поиск по смыслу, отдельный индекс. В игровом режиме осталась та же основа, поменялись материалы и способ обращения к ним: вместо рабочих заметок в базе лежит мир игры, а вместо запроса «найди рабочий документ» звучит «поговори с трактирщицей о чём шепчут её гости». Автор описал этот опыт в разборе проекта на Habr.
Физически система выглядит как устройство на игровой точке: библиотека, мастерятник, таверна, при желании все три сразу. Игрок авторизуется, например по тайному слову, и дальше говорит с персонажем. Персонаж отвечает, читая только те материалы, которые этому гостю положены. Если в доступных материалах ответа нет, он молчит.
Задача, ради которой всё собрано, знакома каждому, кто водил игры: документы не ходят ногами. Игрок доходит до библиотеки тогда, когда дошёл, а мастер в этот момент держит в голове план полигона, рацию и чужой реквизит. Отсюда классика «подожди, я найду файл», а через час выясняется, что красивая импровизация одного персонажа спорит с документом, который выдали другому игроку. Помощник на точке снимает с мастера работу справочного бюро.
С технической стороны это RAG, а не чат-бот с биографией персонажа: ответ собирается из найденных фрагментов базы, а не из параметрической памяти модели. Разница практическая. Обновить мир игры можно правкой Markdown-файла, переобучение не нужно, а доступ к факту определяется разметкой прав, а не удачей промпта.
Архитектура RAG-пайплайна: от Markdown до ответа персонажа
Публичное описание проекта не раскрывает параметры нарезки, модель эмбеддингов и настройки поиска, поэтому дальше речь о схеме, а не о конкретных значениях. Цепочка такая: Markdown-документы на диске, нарезка на чанки, векторизация, хранение в PostgreSQL с pgvector, гибридный поиск (векторный плюс обычный по словам), объединение результатов через RRF, фильтрация по ACL, сборка промпта, вызов LLM (GigaChat или YandexGPT через API), валидатор и ответ, при необходимости озвученный через TTS. Речь игрока распознаёт Yandex SpeechKit.
Каждый шаг решает свою задачу. Чанкинг превращает документ в единицы, которые можно точечно фильтровать и подавать в контекст. Векторизация даёт поиск по смыслу: игрок спрашивает «кто из гостей ходит по ночам», а находится абзац про «ночного посетителя», хотя общих слов почти нет. Гибридный поиск добавляет точное совпадение по именам, названиям локаций и артефактов, где векторное сходство путается. ACL отсекает то, что игроку знать не положено, валидатор проверяет, что реплика осталась репликой персонажа.
Это та же основа, что и в обычном режиме Baza. Меняются материалы и формулировка запроса, механика поиска и выдачи остаётся прежней, поэтому наработки по базе знаний переносятся в игру без второй кодовой базы.
Почему гибридный поиск и RRF, а не только векторный поиск
Имена NPC, названия локаций, артефактов и команд — редкие строки. Эмбеддинг сжимает их в общее смысловое облако, и «ключ от северной калитки» может оказаться ближе к «ключу от южной калитки», чем к самому себе в другом падеже. Лексический поиск (BM25 или полнотекстовый) такие строки ловит точно, зато проваливается, когда игрок формулирует вопрос своими словами.
RRF (Reciprocal Rank Fusion) объединяет два ранжированных списка по формуле 1/(k + rank) и суммирует вклады. В исходной публикации по RRF значение k = 60, оно сглаживает вклад нижних позиций списка — это подтверждают разбор алгоритма RRF и глоссарий MemX. Практическая ценность в том, что веса двух поисков не нужно подбирать вручную: складываются ранги, а не сырые скоры с разной шкалой.
Ограничение: RRF переранжирует только то, что нашли оба поиска. Если документ не попал ни в один список, fusion его не спасёт. Поэтому пул кандидатов из каждого поиска должен быть заметно больше итогового top-k. Похожая логика гибридного поиска с разбором состава индекса описана в материале про память для Cursor на гибридном поиске QMD.
Чанкинг и хранение в pgvector
Ключевое решение: ACL должен быть свойством чанка, а не документа. Каждый чанк наследует метаданные из YAML-frontmatter родительского файла и лежит в PostgreSQL рядом с вектором в pgvector. Тогда права применяются как условие SQL-запроса, а не как проверка после выдачи. Схожий подход к локальному RAG с pgvector и разграничением доступа разобран в кейсе open-source ассистента «Свой».
Размер чанка и overlap в описании проекта не приводятся, это параметры подбора под плотность фактов в документах. Слишком мелкая нарезка рвёт связи: абзац про долг трактирщицы теряет абзац о том, кому этот долг принадлежит. Слишком крупная — в промпт попадает лишний текст, и grounding падает, потому что модели проще опереться на нерелевантную часть. Проверять нарезку стоит на реальных вопросах игроков, а не на пересказе правил.
Про метрику векторного поиска: pgvector поддерживает L2, inner product, cosine distance, а также L1, Hamming и Jaccard для соответствующих типов векторов. Выбор зависит от модели эмбеддингов: cosine измеряет угол и игнорирует магнитуду, L2 чувствителен к магнитуде, inner product — и к углу, и к магнитуде (разбор функций расстояния pgvector). Индекс в pgvector создаётся под конкретную функцию расстояния, поэтому для каждой используемой метрики нужен отдельный индекс. Смешивать разные модели эмбеддингов в одном индексе нельзя: пространства несовместимы, и после смены модели индекс приходится пересобирать целиком.
Granular ACL: как права попадают в YAML-frontmatter и фильтруют чанки до промпта
У любого материала есть допуск: всей игре, только ведьмакам, только тем, кто в конкретной локации, только этому отряду, только этому человеку. Пустой допуск означает общий материал, а поиск идёт только в рамках конкретной игры. Когда игрок авторизовался, система знает, кто перед ней, и отбирает только те чанки, которые этому гостю доступны. Отбор идёт до сборки промпта.
Отсюда главный тезис: LLM физически не видит недоступные документы. Она не может их пересказать, случайно упомянуть в метафоре или выдать в ответ на просьбу «а что ты знаешь про соседа». Утечка через модель исключена по построению, потому что в контексте нет самого секрета.
Пример разметки доступа в frontmatter
Ниже иллюстративный пример подхода, а не дословный формат Baza:
---
title: Ночной гость трактира
roles: [трактирщица]
locations: [таверна]
teams: []
players: [igrok-17]
---
Смысл полей простой: roles отвечает за игровые роли, locations привязывает материал к точке, teams закрывает командные секреты, players перечисляет конкретных игроков. Список игроков нужен отдельно от ролей, потому что персональный секрет не должен протекать к союзникам по команде: они играют рядом, но знать этот факт им рано.
Дефолт разумно делать закрытым: материал без явно указанных допусков не показывается никому. Цена такого решения — забытый frontmatter делает документ невидимым для всех, и это заметно на тестовой сборке. Обратный вариант, где отсутствие поля означает «доступно всем», ошибается в другую сторону и утекает молча. Он дешевле в написании и дороже в последствиях на игре.
Разметку стоит проверять схемой на этапе сборки индекса: неизвестный ключ или опечатка в названии роли превращают материал в мёртвый груз. Проверка «все роли из frontmatter есть в списке ролей игры» ловит такие ошибки до полигона, а не в разгар сцены.
Почему фильтрация до промпта, а не после ответа
Постфильтрация ответа выглядит проще: сгенерировали, проверили, при утечке переписали. Проблема в том, что модель уже увидела секрет. Любой сбой проверки даёт утечку, а косвенные формулировки проверка пропускает: «не буду говорить, кто ходит по ночам» тоже сообщает игроку, что такой факт в базе есть.
Префильтрация переводит задачу из «поймать утечку» в «не создавать её». Отказ становится следствием пустого контекста, а не результатом борьбы с моделью. Валидатор при этом остаётся нужен: он отвечает за роль, стиль и grounding, а не за доступ.
Технический нюанс, который легко пропустить: фильтр должен применяться внутри поиска, а не к уже отобранному top-k. Если сначала взять десять ближайших чанков, а потом отбросить недоступные, можно остаться с пустым контекстом при том, что доступные материалы в базе есть. Условие по ACL идёт в SQL вместе с поиском по вектору и повторяется для лексического поиска, иначе гибридная выдача принесёт закрытые чанки из второй ветки.
Валидатор ответов: role drift, упоминания ИИ, табу-слова и grounding
В публичном описании проекта валидатор ответов как отдельный компонент не раскрыт. Подтверждено другое: если в доступных материалах пусто, персонаж молчит. Ниже — типовой набор проверок для такого сценария; это ориентир для собственной реализации, а не перечень функций Baza.
| Проверка | Что ловит | Реакция |
|---|---|---|
| Role drift | выход из роли: технические объяснения, обращение к игроку как к пользователю, «я ассистент» | перегенерация с усиленным системным промптом или заготовленная реплика в роли |
| Упоминания ИИ | слова «нейросеть», «модель», «промпт», «токен», «API» | отбраковка ответа |
| Табу-слова | современные реалии в мире игры, служебная лексика, запрещённые темы | отбраковка или перегенерация |
| Целостность | обрыв фразы, пустой ответ, дублирование вопроса игрока | повторный вызов |
| Grounding | утверждения, которых нет в предоставленном контексте | отказ в рамках роли |
Порядок проверок имеет значение: дешёвые формальные проверки (табу-слова, обрыв) идут раньше дорогой проверки grounding, иначе вызовы LLM тратятся на ответы, которые всё равно отбракованы.
Grounding — самая сложная проверка. Формально она требует сопоставить утверждения ответа с фрагментами, попавшими в контекст. На практике чаще работает дешёвая версия: отдельный вызов модели-судьи с вопросом «есть ли это в контексте» плюс правила на конкретные типы утверждений (числа, имена, даты). Такая проверка зависит от качества контекста: если чанкинг разорвал связь между фактом и его условием, судья забракует корректный ответ.
Честный отказ вместо галлюцинации
Если в доступных материалах ответа нет, персонаж отказывает, не выдумывая факт. Автор описывает это прямо: если в материалах пусто, он молчит, и молчание на полигоне тоже полезная реплика, иногда лучшая (описание игрового режима).
Для игрового дизайна это работает как механика. Отказ в роли («про такое мне не докладывали») подсказывает, что информацию стоит искать у другого персонажа или в другой локации. Ответ «не знаю, спросите мастера» ломает сцену и выводит игрока из мира.
Пустой контекст после ACL — легитимный сигнал, а не ошибка. Это важно на уровне кода: пустая выдача поиска не должна запускать «ответ из общих знаний модели», иначе схема с доступом теряет смысл и персонаж начнёт уверенно рассказывать то, что игроку знать не положено.
Аутентификация на точке: тайное слово, QR-код, изображение и «страж»
На экране устройства стоит страж. Он не обязан быть милым, он обязан спросить слово. За этой формулировкой простая логика: идентификация определяет, какой набор чанков получит игрок. Без идентификации ACL работать не с чем.
Варианты, которые перечисляет автор: тайное слово, которое игроку является при загрузке; QR-код для киберпанк-игры; изображение. Простое распознавание с помощью ИИ автор называет несложным делом и упоминает, что пробовал его для одного проекта, и оно работает.
Ограничение попыток решено деградацией прав, а не блокировкой: после трёх неудачных игрок получает доступ с обращением «путник» или «Ваша Светлость» (описание стража и попыток). Фактически это гостевой уровень: игрок не уходит с точки ни с чем, но видит только то, что доступно гостю. Для полигона разумно, живой участник с плохой памятью не должен оставаться без ответа.
Форм-фактор не привязан к монитору. Колонку, микрофон и камеру можно вынести и задекорировать под светящегося идола, магический куб или тот же монитор компьютера. Это влияет на акустику: микрофон в декорации слышит хуже, чем на столе, поэтому распознавание проверяют на улице и в шуме, а не в тишине мастерской.
Стек и голосовой интерфейс: PostgreSQL, pgvector, GigaChat/YandexGPT, Yandex SpeechKit
Роли компонентов по описанию проекта:
- PostgreSQL с pgvector — хранение чанков, векторов и метаданных ACL в одной базе. Один запрос умеет искать похожее и фильтровать по правам.
- GigaChat или YandexGPT через API — генерация реплики персонажа. Русскоязычные модели здесь практичнее: мир игры и вопросы игроков на русском, меньше шансов получить смесь языков в ответе.
- Yandex SpeechKit, STT и TTS — распознавание речи игрока и озвучка ответа. Голосовой интерфейс важен на полигоне: руки заняты реквизитом, а читать с экрана в костюме неудобно.
- Markdown с YAML-frontmatter — формат хранения материалов и разметки допусков.
Оговорка про слово «локальный». Локальны база знаний, индекс и контроль доступа: Markdown лежит на диске, векторы в своей PostgreSQL. Генерация и распознавание речи идут через облачные API. Это меняет три вещи.
- Задержка. Два сетевых вызова (STT и LLM) плюс TTS дают паузу, которую игрок воспринимает как задумчивость персонажа только до определённого момента.
- Зависимость от сети. Полигон в поле, связь нестабильна, и нужен план на случай недоступности API.
- Приватность и стоимость. Содержимое реплик уходит вендору, каждый диалог расходует токены, а тайное слово игрока тоже проходит через внешний сервис, если распознавание облачное.
Альтернатива — локальная LLM на устройстве или на мини-сервере рядом с полигоном: тогда задержка и связь перестают быть проблемой, но меняются требования к железу и качество генерации. На слабом железе придётся урезать длину контекста, а вместе с ней и объём материалов, попадающих в промпт.
Что перенести из этого кейса в свои задачи
Переносимые идеи не зависят от полигона:
- ACL как свойство чанка во frontmatter, а не отдельная таблица прав, которую забывают синхронизировать с документами.
- Префильтрация до промпта вместо постфильтрации ответа. Работает везде, где есть документы с разным уровнем доступа.
- Гибридный поиск с RRF: имена, артикулы, коды ошибок и названия проектов плохо ищутся одними векторами.
- Валидатор с grounding и правом на честный отказ. Ассистент, который говорит «в документации этого нет», полезнее того, кто додумывает.
- Идентификация пользователя как вход в выдачу прав: сначала «кто ты», потом «что тебе видно».
Смежные сценарии: внутренняя база знаний с разграничением по отделам и проектам; поддержка клиентов, где ответы различаются по тарифу; обучение сотрудников с уровнями доступа; работа с медицинскими или юридическими документами, где часть материалов нельзя показывать всем сотрудникам.
Границы применимости тоже понятны. Права должны описываться заранее, на этапе написания документа. Динамические права (доступ на время инцидента, временные роли, персональные исключения на сотни пользователей) во frontmatter неудобны: понадобится отдельный слой групп и внешний источник прав. Если список доступа обновляется чаще, чем документы, схема на frontmatter начинает мешать. Как список ограничений влияет на архитектуру сильнее технических деталей, разобрано в кейсе системы управления корпоративной архитектурой.
Ограничения и слабые места решения
Что может сломаться, если тащить схему на большую игру или в продакшен:
- Ошибка во frontmatter. Опечатка в роли закрывает материал для всех, лишняя строка открывает секрет не тем. Лечится валидацией схемы и дефолтом «закрыто».
- Качество чанкинга. Разорванные связи между фактом и условием дают либо отказы там, где ответ есть, либо уверенные ответы по обрывку.
- Облачные LLM и STT/TTS. Задержка, зависимость от связи, стоимость за диалог и уход содержимого реплик вендору.
- Валидатор — это правила. Он снижает риск, но не даёт гарантии; слишком широкие правила превращают персонажа в молчаливого истукана, слишком узкие пропускают role drift.
- Поддержка контента. Материалы кто-то пишет и размечает, на полигоне это ложится на мастера, у которого и без того рация.
Чек-лист перед запуском:
- Кто отвечает за разметку прав и когда она проверяется?
- Что считается дефолтом для документа без frontmatter?
- Как проверяется grounding: набор тестовых вопросов с известными ответами и известными «дырами» в материалах?
- Что покажет точка, если API недоступен: заготовленные фразы, отказ, тишина?
- Как логируются отказы и пустые выдачи, чтобы видеть пробелы в материалах?
- Как проверено распознавание речи в шуме и на живых игроках в костюмах?
Схема с ACL на чанках и префильтрацией даёт то, чего не даёт аккуратный промпт: гарантию, что недоступный текст не попадёт в контекст. Качество поиска, стиль персонажа и устойчивость к сети требуют отдельной работы и проверки на реальных диалогах, и именно они определяют, будет ли точка полезной в поле.