aichat-go

Каждое входящее сообщение Telegram проходит следующий путь:

1. Приём webhook — POST /webhook/{tg_api_key} поступает на публичный HTTP-сервер (:8080). API-ключ в URL маршрутизирует к нужному бандлу проекта.
2. Нормализация в Gateway — TelegramUpdate преобразуется в domain.Message с извлечением текста, подписи, файлов и информации об отправителе.
3. Загрузка состояния — Состояние чата загружается из PostgreSQL по составному ключу (chat_id, project_id).
4. Проверка команд — /start сбрасывает состояние и возвращает приветствие. /debug переключает режим отладки.
5. Сбор файлов — Вложения накапливаются в состоянии. Файлы без текста получают немедленное подтверждение без LLM-вызовов.
6. Диспетчеризация по этапу — На основе вычисленного состояния (CurrentStage()) сообщение направляется соответствующему обработчику этапа.
7. Сохранение состояния — Обновлённое состояние записывается обратно в PostgreSQL.
8. Сброс таймера — Таймер follow-up сбрасывается на шаг 0 для данного чата.

cmd/
  bot/         # Основной бинарник бота
    main.go     # Связка: БД, LLM по уровням, бандлы проектов, HTTP-сервер
    config.go   # Загрузка JSON-конфига с fallback на env-переменные
  crawler/     # CLI-индексатор базы знаний
    main.go     # Подкоманды: init-project, seed, add-urls, register
  cli/         # Локальный readline-интерфейс для тестирования
    main.go     # Тот же конвейер агента, файловый CRM-вывод

internal/
  domain/      types.go        # Stage, Message, ChatState, Lead, SearchResult
  agent/       agent.go        # Диспетчеризация HandleMessage
                stages.go       # Обработчики Этапов 1/1.5/2/3
                commands.go     # /start, /debug
                lead_commands.go # Группа лидов: /prompt, /stats
  llm/         tiered.go       # TieredClient: маршрутизация по уровням
                chain.go        # Цепочка провайдеров с retry + fallback
                openai.go       # OpenAI-совместимый провайдер
                claude.go       # Claude/Anthropic провайдер
                embedding_adapter.go # Форматирование текста для конкретных моделей
  search/      hybrid.go       # DBSF Qdrant + реранкинг + соседи
                reranker.go     # Клиент cross-encoder Cohere
                bm25.go         # BM25Encoder, Tokenize
  db/          postgres.go     # Реализация PostgreSQL
  gateway/     telegram.go     # Нормализация TelegramUpdate
  telegram/    client.go       # HTTP-клиент, retry при 429
  crm/         telegram.go     # TelegramCRM: резюме + история + медиа
  timer/       timer.go        # Планировщик, последовательности, LLM-классификация
  metrics/     metrics.go      # Определения метрик
                llm.go          # Обёртка InstrumentedLLMClient
  crawler/     pipeline.go     # Возобновляемый 4-фазный конвейер
                chunker.go      # Семантический + простой чанкинг
                indexer.go      # Upsert в Qdrant
  i18n/        i18n.go         # T(), Tf(), встроенные локали
                locales/    ru.json, en.json

migrations/  001_initial.sql, 002_bm25_index.sql, 003_timers.sql
nix/         module.nix, example-configuration.nix
flake.nix    Makefile

Finished=true записывается в базу данных до отправки в CRM, а LeadSent=true записывается после. Это предотвращает дублирование лидов при параллельных webhook-запросах или срабатываниях таймера, читающих устаревшее состояние. Если бот падает между двумя записями, система таймеров повторяет отправку в CRM при следующем срабатывании или при перезапуске.

Когда пользователь отправляет файл без текста, бот немедленно подтверждает получение («Принято! Дайте знать, когда закончите.») без обращения к LLM. Файлы накапливаются в состоянии чата и прикрепляются к лиду при его генерации.

Медиафайлы в лиде группируются по типу для наглядного представления:

• Фото + видео — отправляются как медиа-альбом (Telegram группирует их визуально)
• Документы — отправляются как альбом документов
• Голосовые / видео-заметки — отправляются поштучно (Telegram не поддерживает альбомы для них)

При первом взаимодействии на Этапе 2 бот отправляет кнопку Telegram request_contact вместе с ответом. Это позволяет пользователям поделиться номером телефона одним нажатием.

• Отправляется только один раз за диалог (отслеживается через state.UserSettings.ContactRequested)
• Полученный контакт хранится в состоянии чата (не в истории) для конфиденциальности
• Контактные данные включаются в резюме лида и промпты извлечения
• Когда пользователь говорит «возьмите мой телефон из Telegram», LLM может использовать реальные данные контакта

Бот мягко напоминает пользователю поделиться городом и номером телефона, но не блокирует генерацию лида. Если пользователь предоставил достаточно информации для качественного лида, finish=true допускается даже без всех полей. Это избегает раздражения пользователей, которые предпочитают не делиться определённой информацией, при этом максимизируя качество лида.

• Стандартная формула BM25: IDF * (tf * (k1 + 1)) / (tf + k1 * (1 - b + b * dl/avgDL))
• Параметры: k1=1.5, b=0.75
• Токенизатор: Unicode-совместимый (кириллица + латиница), приведение к нижнему регистру, разбивка по не-буквенным/не-цифровым символам
• Хранение: словарь, IDF, avgDL, numDocs хранятся как JSONB в PostgreSQL (таблица bm25_indexes)
• Кеш в памяти: загружается из БД при первом использовании для каждого проекта, инвалидируется при обновлениях краулера

// Поток обработки сообщения пользователя
Сообщение пользователя
  → #4 rewriteQuery (Извлечение) → поисковые вариации
  → гибридный поиск (DBSF-слияние, dense + BM25)
  → реранкер (cross-encoder Cohere, если настроен)
  → топ-5 результатов → расширение соседями (позиции N-1/N+1)
  → #5 determineURL (Извлечение) → выбор услуги или уточнение
  → при входе в Этап 2: #14 извлечение цен (Извлечение, однократно, кеш)
  → #1 или #2 Ответ этапа (Чат) → ответ пользователю
  → #6 + #7 + #8 extractContact (3x Извлечение, параллельно)
  → если завершено:
      → #9 generateSummary (Извлечение) → резюме для CRM
      → #3 Завершение Этапа 3 (Чат) → прощание

// Поток таймера
Срабатывание таймера
  → #10 classifyStatus (Извлечение) → cold/hot/finished
  → #11 generateFollowUp (Извлечение, условно)
  → если завершено: #12 summary (Извлечение) → лид в CRM

// Поток краулера
Краулер
  → #13 семантическое определение границ на странице (Извлечение)
  → разрезание исходного текста по обнаруженным границам
  → добавление темы при эмбеддинге ("Topic: X\n\n...")
  → пакетный эмбеддинг (32 чанка за API-вызов)

TieredClient маршрутизирует вызовы Complete на основе req.Tier:

• TierChat → цепочка Чат (модели для клиентов)
• TierExtract → цепочка Извлечение (лёгкие модели). При отсутствии конфигурации переключается на цепочку Чат.
• Embed → цепочка эмбеддингов (обёрнута в AdaptedProvider для форматирования текста под конкретную модель)

Каждая цепочка имеет независимый retry/fallback. Формула задержки: 2^attempt + 10% jitter, максимум 60 с. Пул ключей ротирует API-ключи round-robin.

Адаптеры эмбеддингов

AdaptedProvider оборачивает провайдер эмбеддингов и форматирует текст в зависимости от режима (документ или запрос). Адаптер выбирается автоматически по имени модели. Модели E5-instruct получают префикс Instruct: ...\nQuery: ... для запросов. Авторазбиение по лимиту токенов: если чанк превышает лимит модели, текст разбивается по предложениям, каждая половина эмбеддится рекурсивно, и векторы усредняются + L2-нормализуются.

new-projects/{project-name}/
  1_pages/{urlhash}.json    # одна Page на URL
  2_chunks/{urlhash}.json   # []Chunk на URL
  3_embeds/{urlhash}.json   # []EmbeddedChunk на URL
  3_embeds/bm25.json        # снимок BM25-энкодера

Семантический чанкинг (по умолчанию)

Один LLM-вызов на страницу (уровень Извлечение, temp 0.1) определяет естественные тематические границы. LLM выводит якорные фразы в формате TOPIC: X | STARTS: Y. Исходный текст разрезается по обнаруженным границам, сохраняя точный текст источника без перефразирования LLM. Каждый чанк получает метку темы для эмбеддинга.

Простой чанкинг (--no-llm-chunk)

Разбивка с учётом абзацев и заголовков. Текст разбивается по двойным переносам строк и markdown-заголовкам. Короткие абзацы объединяются до maxChars (по умолчанию 1500). Чанки получают нумерованные метки тем («Part 1», «Part 2» и т.д.).

При индексации текст каждого чанка дополняется меткой темы перед эмбеддингом:

До: "Our basic plan starts at $99/month with unlimited support."
После:  "Topic: Pricing plans\n\nOur basic plan starts at $99/month with unlimited support."

Тема выступает как семантический якорь — эмбеддинг теперь захватывает тему чанка, а не только его поверхностное содержание. Запрос о «стоимости» будет лучше совпадать с чанком, привязанным к теме «Pricing plans», даже если текст чанка не содержит слова «стоимость».

Поисковые запросы не нуждаются в префиксе темы — пространство эмбеддингов выравнивается естественным образом.

# Создать новый проект и сразу заполнить базу знаний
bin/aichat-crawler init-project \
  --name myproject \
  --tg-api-key "123456:ABC-DEF" \
  --tg-lead-group -1001234567890 \
  --language en \
  --prompt1 "You are a sales consultant..." \
  --prompt2 "You are helping a customer..." \
  --start-reply "Welcome! How can I help?" \
  --sitemap-url "https://example.com/sitemap.xml"

# Заполнить проект позднее (отдельно от создания)
bin/aichat-crawler seed \
  --project-id "uuid-from-init-output" \
  --project-name myproject \
  --sitemap-url "https://example.com/sitemap.xml"

# Добавить URL в существующий проект
bin/aichat-crawler add-urls \
  --project-name myproject \
  --urls "https://example.com/new-page1,https://example.com/new-page2"

# Установить промпты из файлов
bin/aichat-crawler set \
  --project-name myproject prompt1 @prompts/prompt1.txt

1. Сброс — Каждое входящее сообщение сбрасывает таймер для данного чата, начиная последовательность с шага 0.
2. Срабатывание — Загружается свежее состояние чата и история. Пропускается, если уже завершено. Классифицирует клиента через LLM, затем действует на основе классификации.
3. Сохранение — Состояние таймера записывается в PostgreSQL со временем следующего срабатывания. При перезапуске Reload() восстанавливает все активные таймеры, вычисляя оставшуюся задержку и немедленно запуская просроченные.
4. Повтор отправки лида — Если таймер обнаруживает Finished=true, LeadSent=false, он повторяет отправку в CRM вместо классификации.
5. Отмена — Когда пользователь отправляет новое сообщение, старый таймер отменяется (горутина завершается + запись в БД обновляется).

Безопасность горутин: Каждая пара чат/проект получает одну горутину. Проверка идентичности current == self предотвращает ситуацию, когда вытесненная горутина очищает состояние более нового таймера.

Экономия токенов: Двухступенчатый подход (сначала классификация, затем генерация условно) пропускает генерацию follow-up для клиентов со статусом finished и hot, которым ещё не нужно сообщение.

Бандлы проектов (Telegram-клиент, агент, CRM, база знаний) хранятся в карте в памяти. Новые проекты могут быть зарегистрированы в рантайме двумя путями:

• Админ-группа — команда /project_init создаёт проект, заполняет базу знаний и регистрирует бандл мгновенно. Перезапуск не требуется.
• Внутренний API — POST /api/register-project/{id} для CLI или внешних инструментов, которые заполняют БД самостоятельно.

Шаг 1: Создайте бота в BotFather, скопируйте токен.

Шаг 2: Отправьте одну команду в группе лидов админ-проекта:

/project_init myproject sitemap https://example.com/sitemap.xml 123456:AAH...token

Система проверяет токен, создаёт проект, заполняет базу знаний и отвечает с прогрессом:

> Project "myproject" created (bot: @myproject_bot). Seeding started...
> Scraping completed: 42 pages
> Chunking completed: 156 chunks
> Embeddings completed: 156 vectors
> Upload completed: 42 pages, 156 chunks indexed
> Project "myproject" init finished!
> Test the bot: https://t.me/myproject_bot
> To create the CRM group, click:
> https://t.me/myproject_bot?startgroup=connect_myproject

Шаг 3: Нажмите на deep link. Telegram откроет интерфейс создания группы с уже добавленным ботом. Бот автоматически обнаружит группу и подключит её как группу лидов. ID группы не нужен — обнаруживается автоматически через команду /start connect_{name}.

Команды группы лидов (по проекту)

Команды пользовательского чата

Три миграции в migrations/:

001_initial.sql

CREATE TABLE projects (
  id          UUID PRIMARY KEY,
  name        TEXT UNIQUE,
  tg_lead_group BIGINT,
  tg_api_key  TEXT UNIQUE,
  prompts     JSONB,
  language    TEXT DEFAULT 'ru'
);

CREATE TABLE chat_history (
  id          UUID PRIMARY KEY,
  chat_id     BIGINT,
  project_id  UUID REFERENCES projects(id),
  question    TEXT,
  reply       TEXT,
  dbinfo      JSONB,
  created_at  TIMESTAMPTZ
);

CREATE TABLE chat_states (
  chat_id     BIGINT,
  project_id  UUID REFERENCES projects(id),
  state       JSONB,
  PRIMARY KEY (chat_id, project_id)
);

002_bm25_index.sql

CREATE TABLE bm25_indexes (
  project_id  UUID PRIMARY KEY REFERENCES projects(id),
  vocab       JSONB,
  idf         JSONB,
  avg_dl      FLOAT,
  num_docs    INT,
  updated_at  TIMESTAMPTZ
);

003_timers.sql

CREATE TABLE timers (
  chat_id     BIGINT,
  project_id  UUID REFERENCES projects(id),
  step        INT,
  trigger_at  TIMESTAMPTZ,
  PRIMARY KEY (chat_id, project_id)
);

Ключевые индексы

• idx_chat_history_chat_id на (chat_id, created_at) — поиск истории
• idx_chat_states_project на (project_id) — запросы на уровне проекта
• idx_chat_states_state_gin GIN на (state) — JSONB-запросы по состоянию

type CRM interface {
    SendLead(ctx context.Context, lead domain.Lead) (string, error)
    Name() string
}

Текущая реализация: TelegramCRM. Интерфейс спроектирован для будущих CRM-бэкендов (Bitrix, AmoCRM) через паттерн диспетчера MultiCRM.

services.aichat = {
  enable = true;
  configFile = "/run/secrets/aichat-config.json";
  listenAddr = ":8080";

  # База данных
  enablePostgres = true;
  dbName = "aichat";
  postgresPort = 5432;

  # Qdrant
  enableQdrant = true;
  qdrantPort = 6333;
  qdrantDataDir = "/var/lib/qdrant";

  # Резервное копирование
  enableBackup = true;
  backupDir = "/var/backup/aichat";
  backupRetentionDays = 14;
};

Резервное копирование

• Ежедневный systemd-таймер с RandomizedDelaySec=1h
• pg_dump + снимки Qdrant
• 14-дневное хранение с автоматической очисткой

Секреты (sops-nix)

• Зашифрованы в secrets/production.yaml с использованием age-ключей
• Расшифровываются при загрузке на целевой машине с помощью SSH-ключа хоста
• Ключи: aichat_config (полный JSON-конфиг), cloudflared_creds (учётные данные туннеля)

# Развернуть изменения кода в продакшн
make prod-deploy

# SSH-туннели для доступа краулера к БД + Qdrant продакшна
make prod-tunnel
# PostgreSQL на localhost:15432, Qdrant на localhost:16333

# Заполнить проект на продакшне (при открытом туннеле)
./bin/aichat-crawler --config /tmp/config.prod-tunnel.json init-project \
  --name myproject --tg-api-key "TOKEN" --language ru \
  --no-llm-chunk --workers 1 --urls "URL1,URL2,..."

# Получить файлы трейсов с продакшна
ssh root@server "cat /var/lib/aichat/traces/{chatID}/{dialogID}.log"

После запуска бота и его доступности по HTTPS зарегистрируйте webhook в Telegram:

curl -X POST "https://api.telegram.org/bot{TG_API_KEY}/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-domain.com/webhook/{TG_API_KEY}"}'

URL webhook должен точно соответствовать https://{host}/webhook/{tg_api_key}, где tg_api_key — токен бота из таблицы projects. API-ключ в URL маршрутизирует входящие обновления к нужному бандлу проекта.

Требования: Go 1.22+, PostgreSQL 16, Qdrant

# Собрать все бинарники
make build
# создаёт bin/aichat-bot, bin/aichat-crawler, bin/aichat-cli

# Запустить миграции
make migrate DATABASE_URL="postgres://user:pass@localhost/aichat"

# Запустить бота с JSON-конфигом
bin/aichat-bot --config config.prod.json

# Или с переменными окружения
DATABASE_URL="postgres://user:pass@localhost/aichat" \
OPENAI_API_KEYS="sk-xxx" \
bin/aichat-bot

В продакшне используется Cloudflare Tunnel для маршрутизации HTTPS-трафика к боту без открытия портов. Туннель направляет aichat.example.com на localhost:8080 на сервере.

• Учётные данные туннеля управляются через sops-nix (зашифрованы в покое)
• Настроен в nix/production.nix
• Нет необходимости в TLS-сертификатах или настройке обратного прокси
• Webhook Telegram указывают на URL туннеля

• Группируйте метрики LLM по provider для сравнения производительности и частоты ошибок провайдеров
• Отслеживайте aichat_agent_messages_total по stage, чтобы видеть конверсию воронки (general → service_specific → final)
• Следите за aichat_timer_active_sequences как индикатором общего числа активных диалогов
• Используйте aichat_webhook_request_duration_seconds p95, чтобы замечать медленные ответы (типично: 2-5 с, включая LLM + поиск)
• Мониторьте aichat_crm_leads_total по project для отслеживания генерации лидов по арендаторам

Идентификаторы моделей используют формат "provider/model". Имя провайдера отделяется по первому символу / и сопоставляется с картой providers.

Ограничение модели Извлечение: Должна возвращать контент в поле choices[].message.content. Модели с thinking/reasoning, использующие поле reasoning, не подходят для уровня Извлечение.

# Собрать все три бинарника
make build        # создаёт bin/aichat-bot, bin/aichat-crawler, bin/aichat-cli

# Запустить тесты
make test         # go test ./...

# Линтер
make lint         # go vet ./...

# Локальные сервисы для разработки (PostgreSQL + Qdrant через Docker)
make dev-services

# Запустить CLI-интерфейс для тестирования (без Telegram)
bin/aichat-cli --config config.dev.json --project myproject