Как собрать ассистента, который не выдумывает

1. Карта проекта что за что отвечает

Проект маленький: одна статическая страница, один файл бэкенда на чистом Node без единой зависимости, и папка с базами знаний. Всё остальное — проверки и деплой.

Что стоит на сервере

2. Поток ответа от вопроса до текста

Бот — это не «запрос в большую модель». Это конвейер из семи шагов, и последние три важнее первых: они решают, можно ли вообще показать человеку то, что придумала модель.

Ключевой принцип: отказ лучше правдоподобной выдумки. Клиент, которому бот назвал несуществующую цену, стоит дороже, чем клиент, которому бот сказал «этого нет в базе, уточню у администратора».

3. Контексты как писать базу знаний

База знаний — единственный материал, из которого бот имеет право отвечать. Формат: один файл на нишу, внутри список разделов. Раздел = одна тема = один ответ.

{
  "slug": "delivery",
  "company": "Демо · доставка еды",
  "refusal": "В нашей базе этого нет, поэтому ответа не будет. …",
  "contact": "Оператор подскажет — напишите в мессенджер …",
  "chunks": [
    {
      "id": "сроки",
      "topic": "Сроки",
      "keywords": ["долго", "время", "ждать", "заказ", "когда привезут"],
      "text": "От 40 минут до часа двадцати в обычное время: горячее и гриль
               считаются отдельно. Точное время называем при подтверждении заказа."
    }
  ]
}

Правила написания раздела

1. Один раздел — одна тема и один вопрос. «Сроки» и «Минимальная сумма» — два раздела. Смесь в одном тексте даёт ответ не на тот вопрос.
2. text — только проверяемые факты. Цены, сроки, условия, что нужно принести, до какого часа. Без «мы лучшие», «индивидуальный подход», «качественно и быстро» — модель охотно пересказывает пустоту.
3. Числа пиши как произносишь. «от 40 минут до часа двадцати», а не «40–80 мин»: модель воспроизводит форму записи, и сверка цифр сравнивает строки.
4. keywords — словами клиента, а не специалиста. Клиент пишет «долго?», «когда привезут», «минималка». Если слово есть в ключевых, раздел поднимается наверх автоматически; если его нет — вопрос может не пройти гейт.
5. Глаголы движения и состояния тоже в ключевые. «когда привезут», «ждут», «везут» — по ним находится естественный вопрос «сколько едет заказ».
6. Запреты пиши прямо. «Безглютеновых позиций в меню нет», «Ночью доставка не работает». Раздел с запретом спасает от выдуманной услуги.
7. Нет данных — так и пиши. «Точное время называем при подтверждении» лучше, чем молчание: модель честно перескажет отсутствие цифры вместо того, чтобы её сочинить.
8. Объём текста раздела — 1–3 предложения. Длинный раздел размывает ответ: модель обязана уместиться в 1–3 предложения, и из простыни она вытащит что-то одно.
9. Разделов на нишу — 8–12. Меньше — чаще отказы, больше — начинает путаться, какой фрагмент главный.
10. Не кладите в базу то, что меняется каждый день (наличие, свободные окна, акции без срока) — для этого есть «уточнит оператор».

Хорошо и плохо

Поля отказа и контакта

refusal — что видит гость, когда в базе правда ничего нет. contact — вторая фраза отказа: как связаться. Отказ всегда собирается из трёх частей: «в базе нет» (одна из трёх формулировок, чтобы не отвечать шаблонно) + подсказка по темам, которые бот знает + контакт.

4. Новая ниша за 10 минут

Код менять не нужно: ниша — это данные. Один файл на сервере и один блок в браузерном зеркале.

Шаг 1. Файл базы

• поменять slug (латиницей, он придёт в запросе), company, refusal, contact;
• написать 8–12 разделов по правилам из раздела 3;
• каждому разделу дать короткий id — по нему ищутся правки.

Шаг 2. Зеркало в демо на странице

Добавить такой же набор в NICHES: chips (кнопки-примеры, 6–8 живых вопросов), na (вопросы, ответа на которые в базе нет — они показывают, что бот не выдумывает), refusal. Кнопка ниши берётся оттуда же.

Шаг 3. Проверка маршрутизации

Дописать свои вопросы в test/routing.mjs — по одному на раздел и 1–2 «чего нет в базе», — и прогнать:

Цель — «маршрутизация демо: N/N». Если вопрос не попадает в свой раздел, сначала правь keywords, и только потом пороги.

Шаг 4. Выкладка

Скрипт зальёт и tenants/*.json, и статику, перезапустит сервис и сам спросит бою, отвечает ли новая ниша.

5. Правила для ИИ системный промпт

Они прописаны в одном месте — в функции systemFor(). Это единственный файл, где боту объясняют, как себя вести.

Ты — ассистент компании «{company}». Отвечай по-русски, дружелюбно и коротко: 1–3 предложения.
Правило 1: используй ТОЛЬКО материалы ниже. Своих знаний о теме, ценах и законах не добавляй.
Правило 2: числа называй ровно так, как они стоят в материалах.
Правило 3: если в материалах про это ничего нет — ответь одной фразой: «Этого нет в базе
           компании, уточню у администратора».
Правило 4: не выдумывай цены, часы и правила, которых нет в материалах. Не считай и не
           перечисляй количество позиций.
Правило 5: пиши обычным текстом в одно-два сообщения: без звёздочек, решёток и маркдауна.
Правило 6: пересказывай своими словами и не начинай ответ одинаково — в диалоге реплики
           должны различаться.
Правило 7: это продолжение разговора. Реплики до этого: гость — «…»; ты — «…». Если вопрос
           короткий и без новых слов, он про это же.
Правило 8 (тон): <фразировка выбранного тона>

Тоны

Тон выбирается случайно по весам — поэтому два одинаковых вопроса не дают одинаковый ответ. Строгий тон ещё и резервный: если живой черновик не прошёл проверки, модель спрашивается второй раз уже в нём.

Что можно менять смело

• приветствие и «по-русски / по-казахски» — первая строка промпта;
• длину ответа (1–3 предложения) и тон;
• вес тона, если «с юмором» мешает;
• фразу «Этого нет в базе компании, уточню у администратора» — её стоит менять под голос клиента.

Чего менять нельзя

• Правила 1–4 — это весь смысл продукта. Ослабил — получил выдуманные цены;
• Правило 5 — виджет печатает обычный текст, markdown покажет гостю звёздочки;
• «Материалы:» в конец промпта — без них модели неоткуда брать факты.

6. Поиск и гейт пороги, стоп-слова, основы слов

Гейт решает одну задачу: пускать ли вопрос в базу вообще. Он же — самая частая причина жалоб в духе «я спросил нормально, а он отказал».

Три вещи, которые надо понимать про оценку совпадения

1. Редкое слово весит больше частого (idf). «Лактоза» в одной теме сильнее, чем «можно» в десяти.
2. Слово, которого в базе нет вообще, не топит вопрос, но и не проходит бесплатно: ему считается 40 % веса. Поэтому «сколько едет заказ» находится по слову «заказ», а «где можно покурить» из одного служебного «можно» остаётся за гейтом.
3. Окончания не важны. «цена» = «цены», «привезёте» = «привезут»: сверяется основа слова (начало без хвоста, но не короче 3 знаков) и 3/4 общего начала у длинных слов.

Служебные слова

STOP_STEMS (server-bots.mjs:36) — слова, которые ничего не говорят о теме: «как», «что», «скажи», «покажи», а также «можно», «нужно», «делать», «просто», «ещё». Они выбрасываются из вопроса. Добавляешь новое слово-паразит в отказе — добавь его сюда, иначе оно начнёт тянуть ответ не туда.

Диалог

Уточняющий вопрос («а реально?», «а долго?») сам по себе ни на что не похож. Поэтому бот берёт последние 6 реплик и пересобирает поиск с прошлым вопросом гостя; в промпт при этом попадает, что он продолжает разговор. Работает только если фронтенд шлёт history — в site.js это массив turns.

7. Проверки заземлённости почему ответ мог стать цитатой

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

Почему по всей базе: законный пересказ часто использует слова из соседнего раздела. Если сравнивать только с тремя найденными фрагментами, хорошие ответы начнут отбиваться, и бот замолчит цитатами — это ровно тот случай, когда «всё работает, но скучно».

8. Модель по API-ключу три строки и рестарт

Без ключа бот отвечает дословными фрагментами базы — это рабочий режим, а не поломка. Генерация включается тремя переменными окружения, код не меняется.

Шаг 1. Купить ключ

Подойдёт любой OpenAI-совместимый эндпоинт: Mistral, Yandex GPT, ProxyAPI, OpenRouter, сервер провайдера GPU. Нужны три вещи: адрес вида https://…/v1, ключ и имя модели.

Шаг 2. Положить ключ на сервер

BOTS_TOKEN=…            # уже есть: доступ к журналу заявок
BOTS_API_BASE=https://api.mistral.ai/v1
BOTS_API_KEY=<ключ>
BOTS_MODEL=ministral-14b-latest

Файл читается сервисом через EnvironmentFile. В git, в чат, в скриншоты и в браузер он не попадает никогда. Ключ, показанный в переписке, считается скомпрометированным и меняется.

Шаг 3. Перезапустить и проверить

Ответ {"ok":true,"gen":true,…} — генерация жива. Страницу перезагружать не нужно: лендинг сам опрашивает /health и меняет плашку на «поиск + генерация».

Шаг 4. Живая проверка вопросом

Один вопрос через node (не через curl: кириллица в Git Bash приходит битой, и ты увидишь «отказ» там, где всё хорошо):

Что смотреть, если генерация не включилась

• gen: false → не хватает одной из трёх переменных или сервис не перезапущен;
• в логе «пустой ответ провайдера: …Rate limit…» → 429: модель недоступна на твоём тарифе или ты долбишь её серией без пауз;
• в логе «Protocol "https:" not supported» → код пытается слать https-запрос http-библиотекой (в текущей версии это исправлено выбором библиотеки по протоколу);
• ответ есть, но всегда цитата → проверки заземлённости: смотри черновик в логе и текст базы.

9. Подписка и своя модель что выбрать клиенту

Три схемы, между которыми выбирают по двум признакам: куда уходят переписки и сколько стоит ответ.

Код от выбора схемы не меняется вообще: providerChat() говорит по OpenAI-совместимому протоколу и сам выбирает http/https по адресу. Отличие локальной модели — адрес на http:// и имя модели, которое отдаёт GET /v1/models.

Что сказать клиенту про персональные данные

• в форме заявки собирается имя и контакт по согласию, оператор данных — сам клиент, мы обработчик;
• в провайдера уходит текст вопроса и фрагменты базы, а не паспортные данные;
• если это критично — схема «своя модель», и переписка никуда не уходит.

Сколько это стоит в деньгах

Один ответ = вопрос + три фрагмента базы + системный промпт ≈ 400–700 токенов на вход и до 260 на выход. Даже на платном тарифе это копейки на вопрос; реальная статья расходов — не токены, а работа по сбору базы и сопровождению. Поэтому и продаётся база + настройка, а не «доступ к нейросети».

10. Деплой и проверки

Одна команда, которая поднимает файл-лист, сверяет байты и сама спрашивает бою.

1. Заливка в /tmp/botsapi-stage: index.html, styles.css, site.js, privacy.html, server-bots.mjs, server-bots.sh, tenants/*.json. Список белый — новый файл в скрипт не попал, значит на сервер он не уехал.
2. Unix-концы строк для .sh и .mjs: правки из-под Windows иначе ломают bash.
3. server-bots.sh: приложение, /etc/bots.env (существующий не трогает), systemd, Caddy с validate и откатом, права на статику, robots.
4. Сверка md5 каждого статического файла: локальный ≠ серверный → падение, а не «вроде залилось».
5. Живые ответы: коды и типы страниц, редирект /aistudio → /aistudio/, /health.
6. Тест бота: test/live-check.mjs — ответ по базе, отказ на посторонний вопрос, приём заявки; тестовая строка из журнала вычищается.

Перед тем как заливать

Локальный запуск без BOTS_API_KEY — это не «неполноценный тест»: гейт и маршрутизация проверяются именно в офлайне, без лимитов провайдера.

Откат

Caddyfile трогается только через validate, и при неудаче остаётся предыдущая версия. Сервис поднимается заново сам (Restart=always). Откатить код — значит залить прежние файлы тем же скриптом: держи в репозитории коммит на каждую выкладку.

11. Заявки и данные

• Без токена заявки отдают 403. Токен — из /etc/bots.env, в переписку его не печатают.
• Хранение: /opt/botsapi/data/leads.jsonl, одна строка = одна заявка. Бэкап = забрать этот файл.
• Форма требует согласие на обработку данных; без него заявка не уходит, и это же проверяет сервер, а не только браузер.

12. Неполадки симптом → причина → что делать

13. Чек-лист перед сдачей клиенту

Как померить качество словами, а не ощущениями

1. Доля отказов на 20 живых вопросах из переписки клиента. Больше 3 — база тонкая, дописывай разделы, а не пороги.
2. Доля цитат вместо пересказа: читается из плашки mode. Массово — проверки душат, смотри отвергнутые черновики в логе.
3. Разнообразие: один и тот же вопрос три раза — три разных первых слова. Одинаково — проверь, что тон вообще выбирается случайно.
4. Ни одной выдуманной цифры: прогони 20 вопросов и сверь все числа с базой. Одна найденная выдумка стоит дороже всех отказов.

Коротко о главном