RAG + OpenAI: дорожная карта бизнес-помощников Alatyr Service¶

Статус: целевая архитектура и продуктовый backlog.
Обновлено: 27.08.2026.
Связанные документы: openwebui-public-api.md, openwebui.md, rag-sync.md, crm-objects-spec.md, services-catalog.md.

1. Цель¶

Построить внутри alatyr-service не один универсальный чат, а набор специализированных помощников, которые работают на общем защищённом контуре:

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

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

2. Текущее состояние¶

На 27.08.2026 в production развёрнут PR alatyr-service #95, merge-коммит b0f97d1:

в карточке объекта есть вкладка «Помощник»;
доступны manager-only GET/POST API;
история сохраняется по объекту в SQLite-таблице object_assistant_messages;
в запрос передаётся свежий ограниченный контекст конкретного объекта;
policy и недоверенный CRM-контекст разделены;
глобальная knowledge-коллекция к запросу не подключается;
ответы не меняют CRM и не выполняют внешние действия;
содержимое ответов не пишется в application logs, включая URL с завершающим /;
действуют ограничения размера контекста, истории, ответа, очереди и частоты запросов;
за пределами localhost/test разрешён только HTTPS upstream;
UI честно сообщает, что сейчас видит метаданные файлов, но не их бинарное содержимое.

На VPS alatyr-service получает конфигурацию из /etc/alatyr-service.env через systemd drop-in. В процессе присутствуют имена:

RAG_API_BASE_URL;
RAG_API_MODEL;
RAG_API_OPENWEBUI_TOKEN;
RAG_API_EDGE_TOKEN;
RAG_API_TIMEOUT_MS.

Секретные значения в KB не фиксируются. Контрольный запрос к RAG после настройки сознательно отложен по решению владельца.

3. Источники истины¶

Данные	Источник истины	Роль ИИ
Объекты, заказчики, сотрудники, задачи, журнал работ	CRM `alatyr-service`	читать, объяснять, готовить черновики
Номенклатура, услуги, цены, остатки, резервы	МойСклад	подбирать позиции и проверять доступность
Контрагенты, договоры, счета, оплаты, акты	МоёДело	сверять факты и готовить исключения
Регламенты, архитектура, инструкции	Git KB `alatyr-infra-kb`	RAG-поиск с указанием файла
Документы конкретного объекта	изолированное object storage + object RAG	OCR, извлечение и проверка комплектности
Переписка и календарь	почта/календарь после отдельной интеграции	классификация, черновики, напоминания
Телефония и мессенджеры	подключаемые каналы после согласования	транскрипция, краткое резюме, постановка задач

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

4. Целевая архитектура¶

Админка / карточка объекта / входящие каналы
  → API alatyr-service и RBAC
  → выбор роли и сценария
  → context builder из canonical-источников
  → классификация и минимизация данных
  → object-scoped RAG / общая несекретная KB
  → model router: локальная модель или разрешённая cloud-модель
  → структурированный ответ по JSON-схеме
  → deterministic validation и бизнес-правила
  → черновик / preview / список уточнений
  → явное подтверждение пользователя
  → idempotent action через доменный сервис
  → append-only audit и результат в CRM

4.1. Модельный шлюз¶

Интеграцию проектировать provider-neutral:

локальная модель Open WebUI/Ollama для простых, повторяемых и чувствительных задач;
OpenAI API как опциональный серверный маршрут для более сложного рассуждения, structured output, OCR/vision и больших документов;
возможность позже добавить другого провайдера без переделки UI и доменной логики;
выбор маршрута по роли, классу данных, сложности, бюджету и доступности;
fallback только на заранее разрешённый маршрут, без тихой отправки данных во внешний cloud;
имя провайдера, модели и версия prompt фиксируются в audit.

OpenAI API нельзя вызывать из браузера. Ключ хранится только в Vaultwarden и server-side env/secret store. Для внешней модели нужны отдельные лимиты, таймауты, бюджет, журнал использования и политика передачи данных.

4.2. Контуры знаний¶

Нужны три изолированных слоя:

Общая KB — регламенты и инструкции без клиентских документов.
Object RAG — файлы и извлечённый текст только одного объекта, с обязательным object_id, ACL и lifecycle удаления.
Оперативный контекст — свежие данные CRM/МоёДело/МойСклад, передаваемые на один запрос и не превращаемые автоматически в общую knowledge base.

Автоматический поиск по всем клиентским документам в одной общей коллекции запрещён.

4.3. Конвейер документов¶

upload
  → MIME/size/malware preflight
  → связь с object_id, contract_id и типом документа
  → OCR / text extraction / table extraction
  → нормализация страниц и координат
  → чанки с ACL и provenance
  → индекс object RAG
  → проверка полноты индексации
  → version/delete sync при замене или удалении оригинала

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

5. Роли и сценарии¶

5.1. Секретарь¶

Может:

собирать дневную сводку: встречи, просрочки, новые обращения, ожидаемые оплаты, документы без ответа;
классифицировать входящие письма и сообщения по объекту, срочности и теме;
предлагать карточку новой заявки и перечень недостающих сведений;
готовить черновики ответов заказчику, подрядчику и сотруднику;
составлять протокол разговора или встречи, решения, ответственных и сроки;
готовить follow-up и напоминания;
объединять несколько каналов в одну хронологию объекта;
искать контакты, реквизиты и связанные документы в пределах разрешённого объекта.

Не может без подтверждения:

отправлять письмо или сообщение;
создавать/переносить встречу;
менять ответственного, срок, статус заявки или объекта;
обещать цену, срок, гарантию либо юридическое обязательство.

5.2. Квалификатор заявки и помощник по продажам¶

определяет тип объекта и работ;
задаёт discovery-вопросы;
проверяет, достаточно ли данных для выезда или предварительной оценки;
предлагает следующий шаг и подходящий пакет услуги;
готовит коммерческое предложение и варианты комплектации;
собирает возражения и проектирует ответ;
сравнивает плановую и фактическую конверсию;
не публикует финальную цену без расчёта сметчика и утверждения.

5.3. Сметчик¶

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

исходные данные
  → определение неизвестных
  → уточняющие вопросы
  → допущения
  → подбор каталога и норм
  → расчёт материалов, работ, логистики и резерва
  → проверка арифметики
  → варианты эконом / стандарт / резерв
  → черновик сметы
  → подтверждение

Пример исходных данных:

3 камеры, кабель по помещению, длина каждой линии 50 метров, регистратор, настройка выхода в интернет.

Помощник должен уточнить:

камеры IP или аналоговые, помещение или улица;
разрешение, объектив, ночная съёмка, микрофон, антивандальность;
питание PoE либо отдельные блоки, есть ли существующая сеть;
50 м — трасса каждой линии или общий метраж;
способ прокладки: лоток, гофра, штроба, открытый монтаж, высота;
нужен ли запас кабеля 10–15%, патч-корды, коннекторы, коробки и крепёж;
число каналов регистратора и резерв на расширение;
срок хранения архива, режим записи и требуемый объём диска;
монитор, ИБП, шкаф/полка, коммутатор, роутер;
способ удалённого доступа: P2P, статический IP, VPN;
есть ли интернет на объекте и кто предоставляет доступ к роутеру;
нужны ли проект, исполнительная документация, обучение и гарантия;
адрес, пропускной режим, выезд, ночные/высотные работы;
компания, НДС/УСН, формат сметы и желаемый бюджет.

Результат должен быть структурирован:

исходные данные;
уточнения и ответы;
явные допущения;
позиции: код каталога, наименование, количество, единица, закупочная и продажная цена, скидка/наценка;
трудовые операции и нормы;
расходники, логистика и резерв;
исключения из объёма работ;
срок действия цен;
три варианта комплектации;
контрольные суммы;
уровень уверенности и причины, почему смету ещё нельзя утверждать.

ИИ предлагает позиции, но цены и остатки перечитываются из МойСклад. Создание canonical estimate и отправка клиенту происходят только после preview и подтверждения.

5.4. Делопроизводитель¶

регистрирует входящий/исходящий документ;
определяет тип, объект, заказчика, договор, счёт, акт и родительский документ;
предлагает номер, дату и корректное имя файла;
проверяет обязательные реквизиты, подписи, приложения и количество страниц;
обнаруживает дубли, противоречивые версии и отсутствующие документы;
ведёт checklist комплекта: договор, допсоглашение, смета, счёт, оплата, акт, исполнительная документация;
отслеживает сроки ответа, подписания и возврата оригиналов;
извлекает таблицы, суммы, даты, ИНН/КПП/ОГРН и сравнивает с canonical CRM;
готовит реестр документов и архивную опись;
формирует задания на исправление, но не заменяет оригинал автоматически.

5.5. Договорной и юридический помощник¶

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

5.6. Координатор объекта и прораб¶

формирует утренний план и вечерний отчёт;
показывает просрочки, блокеры, незакрытые замечания и ожидаемые материалы;
сводит журнал работ, смены, фото, документы и задачи;
сравнивает план/факт по объёму, сроку и бюджету;
готовит задания сотрудникам и чек-листы приёмки;
фиксирует решения совещания и изменения объёма;
предлагает допсоглашение при выявленном дополнительном объёме;
не назначает людей и не меняет сроки без подтверждения.

5.7. Инженер и технический эксперт¶

ищет инструкции и runbook в Git KB;
строит дерево диагностики;
предлагает схему, спецификацию и последовательность пусконаладки;
проверяет совместимость камер, PoE, регистратора, диска, сети и питания;
рассчитывает архив видеонаблюдения и бюджет мощности;
готовит программу испытаний, чек-лист сдачи и регламент обслуживания;
формирует исполнительную документацию из фактических данных;
явно отделяет подтверждённые параметры от предположений.

5.8. Диспетчер сервисной службы¶

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

5.9. Снабженец и складской помощник¶

превращает смету в BOM и заявку на комплектацию;
сверяет остаток, резерв, ожидаемые поставки и аналоги;
предлагает замену только с объяснением отличий;
сравнивает поставщиков, цену, срок и гарантию;
предупреждает о дефиците и несовместимости;
готовит заказ поставщику как черновик;
не создаёт закупку и не списывает товар без подтверждения.

5.10. Финансовый контролёр и бухгалтерский помощник¶

сверяет цепочку смета → договор → счёт → оплата → акт;
находит расхождения сумм, дат, компаний и контрагентов;
показывает дебиторку, ожидаемые оплаты и документы без закрытия;
готовит управленческий cash-flow и прогноз;
собирает данные для налогового/бухгалтерского специалиста;
не выполняет проводки и не считает себя источником бухгалтерской истины.

5.11. Помощник по сотрудникам¶

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

5.12. Аналитик руководителя¶

портфель объектов: стадия, стоимость, оплата, маржа, риск;
загрузка сотрудников и узкие места;
прогноз завершения и поступлений;
повторные дефекты и причины выездов;
эффективность каналов продаж и услуг;
качество данных: пустые связи, документы без объекта, счета без договора;
ежедневный brief и еженедельный управленческий отчёт.

5.13. Хранитель базы знаний¶

отвечает по регламентам с указанием исходного Markdown-файла;
находит противоречия и устаревшие инструкции;
формирует черновик обновления KB после инцидента или решения;
предлагает FAQ и обучающие материалы;
не записывает в Git непроверенный вывод модели как факт.

5.14. Клиентский помощник, поздний этап¶

сообщает клиенту подтверждённый статус его объекта;
отвечает на FAQ и требования к подготовке площадки;
собирает первичную заявку и материалы;
показывает документы только своей организации и объекта;
передаёт человеку юридические, финансовые и конфликтные вопросы.

Этот контур требует полноценной tenant/object isolation, отдельной аутентификации и red-team проверки до публичного запуска.

6. Контракты структурированных ответов¶

Для критичных сценариев модель должна возвращать не свободный текст, а данные по версированной JSON-схеме.

Минимальные типы:

clarification_request;
estimate_draft;
document_check;
document_registry_entry;
crm_change_draft;
task_draft;
message_draft;
meeting_summary;
reconciliation_report;
risk_register;
management_brief.

Каждый контракт содержит:

schemaVersion;
role;
objectId;
sourceSnapshot;
assumptions;
missingFacts;
citations;
confidence;
warnings;
proposedActions;
requiresConfirmation.

Сервер валидирует схему, пересчитывает арифметику и повторно читает canonical данные перед выполнением действия.

7. Безопасность и управление действиями¶

7.1. Доступ¶

RBAC по роли;
object-level ACL до расширения доступа менеджеров;
запрет cross-object retrieval;
отдельные service users и токены;
минимальные permissions для каждой интеграции;
запрет передачи клиентских документов в общую коллекцию.

7.2. Данные¶

классификация: публичные, внутренние, персональные, финансовые, договорные, секретные;
минимизация полей перед моделью;
redaction ненужных ИНН, адресов, телефонов, ФИО и банковских реквизитов;
локальная модель по умолчанию для чувствительного контекста;
внешняя модель только по разрешённой policy;
retention и удаление истории/индекса вслед за исходным документом.

7.3. Prompt injection¶

system policy отдельно от CRM, RAG и истории;
контекст считается недоверенными данными;
инструкция внутри документа не может менять права или вызывать tool;
allowlist инструментов по роли;
вывод модели не используется как команда shell/SQL/API;
adversarial-набор тестов для заметок, файлов, писем и OCR.

7.4. Запись и внешние действия¶

Для отправки писем, изменения CRM, создания документов, счетов, актов, задач, закупок и календарных событий:

сформировать черновик;
показать полный preview и источник данных;
получить явное подтверждение;
повторить preflight и проверить свежесть snapshot;
выполнить idempotent action;
записать actor, время, payload hash и результат в audit;
при неоднозначном результате остановить автоповтор и отправить на reconciliation.

8. Этапы реализации¶

NOW: стабилизация текущего помощника¶

подтвердить существование private model wrapper и доступ service user;
проверить, что RAG_API_MODEL совпадает с разрешённым Model ID;
позднее выполнить один контролируемый запрос из карточки объекта; сейчас он отложен;
добавить health/latency/error monitoring без логирования текста;
описать rollback и ротацию обоих токенов;
собрать базовый evaluation-набор из безопасных тестовых объектов.

NEXT 1: секретарь и object copilot read-only¶

выбрать роль в UI;
краткие сводки, вопросы, риски, следующие действия;
структурированные ответы и citations на CRM/KB;
кнопки «создать черновик», но без записи;
feedback: полезно/ошибка/пропущенный факт.

NEXT 2: сметчик¶

диалог уточнений;
server-side калькулятор и проверка арифметики;
чтение каталога, цен и остатков МойСклад;
нормы работ, запас и расходники;
варианты комплектации;
preview canonical estimate;
сохранение только после подтверждения.

NEXT 3: делопроизводитель и object RAG¶

extraction/OCR для PDF, DOCX, XLSX и изображений;
object-scoped collections или metadata filters с ACL;
provenance до файла/страницы;
реестр документов;
контроль комплектности и версий;
синхронное удаление индекса при удалении файла.

LATER 1: гибрид OpenAI¶

отдельный server-side credential;
provider/model router и policy;
structured output и vision только для утверждённых сценариев;
лимиты бюджета по роли/пользователю/объекту;
redaction и отчёт о переданных данных;
локальный fallback либо честная ошибка, но не скрытая смена trust boundary.

LATER 2: управляемые действия¶

CRM change drafts;
создание задач и напоминаний;
генерация КП, договоров, приложений, счетов и актов;
отправка сообщений и писем только после preview;
календарь и протоколы;
append-only audit, idempotency и reconciliation.

LATER 3: кросс-канальный секретарь¶

почта;
календарь;
Telegram/MAX/WhatsApp при юридически допустимом подключении;
телефония и транскрипция;
единый inbox;
утренний brief и вечерний follow-up.

LATER 4: аналитика и клиентский кабинет¶

управленческие отчёты;
прогнозы ресурсов и денег;
customer-facing assistant с tenant isolation;
продуктовые пакеты CRM-60/CRM-61 для внешних клиентов.

9. Метрики готовности¶

Безопасность¶

0 случаев cross-object disclosure;
0 записей/отправок без подтверждения;
0 секретов и текста переписки в application logs;
100% внешних действий имеют audit;
100% удалённых документов удаляются из индекса по lifecycle.

Качество¶

доля ответов с подтверждаемым источником;
полнота обязательных уточнений;
точность арифметики сметы;
edit distance между черновиком и утверждённым документом;
процент честных отказов при недостатке данных;
количество найденных реальных несоответствий документов.

Эффект¶

время от заявки до первого квалифицированного ответа;
время подготовки сметы;
время регистрации комплекта документов;
число просроченных follow-up;
доля смет, подготовленных без ручного переноса каталога;
сокращение повторного ввода данных;
стоимость inference на объект и на утверждённый документ.

10. Решения, которые надо принять до write-автоматизации¶

Какие менеджеры видят все объекты, а какие только назначенные.
Какие классы данных разрешено отправлять в OpenAI API.
Нужна ли явная отметка пользователя для каждого cloud-запроса.
Кто утверждает смету и минимальную маржу.
Где хранятся нормы работ, расхода и коэффициенты.
Какие документы требуют обязательной юридической проверки.
Сколько хранится история чата и extracted text.
Какие каналы секретарь может только читать, а какие — использовать для отправки.
Как разделяются данные двух собственных компаний.
Какие операции запрещены ИИ безусловно.

11. Definition of Done для каждой новой роли¶

определён владелец процесса;
перечислены источники истины;
описаны вход, структурированный выход и обязательные вопросы;
установлен минимальный RBAC и object ACL;
есть negative/adversarial tests;
есть бюджет контекста и inference;
есть метрики качества;
read-only MVP принят на тестовых данных;
write path имеет preview, confirmation, idempotency и audit;
подготовлены rollback, мониторинг и runbook;
секреты находятся в Vaultwarden, а в KB записаны только имена и места хранения.