AI-помічник для заявок — Telegram-бот для GovTech

Огляд

Conversational AI-помічник у вигляді Telegram-бота для українського консультаційного сервісу, що обслуговує малий бізнес — підприємців, які подають заявки на державні та євросоюзні програми.

Роль: Sole architect, engineer, DevOps Термін: 8 тижнів MVP + 2 тижні калібрування Домен: Business Automation / GovTech — Україна

Одна повна заявка — 2–4 години на клієнта. З 50+ активних клієнтів на місяць — bottleneck очевидний. Клієнт хотів Telegram-бота для своєї команди: описати клієнта → отримати готовий .xlsx.

Жорстке обмеження: збереження Excel-формул. Розрахункова частина шаблону залежить від ланцюгів формул — будь-яке рішення, що замінює формули статичними значеннями, ламає документ щойно користувач редагує комірку в Excel.

Рішення

Фахівці описують клієнтський бізнес у 10–20 повідомленнях. Система:

Маршрутизує розмову до правильної програми через RAG + LLM-класифікатор (pgvector HNSW + OpenRouter)
Вилучає структуровані факти через LLM function-calling з валідацією схеми
Перевіряє консистентність з правилами донора (обмеження фінансування, мінімум працівників, допустимі категорії витрат)
Заповнює Excel-шаблон — тільки вхідні комірки; всі формульні комірки залишаються незайманими
Повертає готовий .xlsx через Telegram

Якщо впевненість AI падає нижче порогу — розмова ескалюється до живого оператора з повним контекстом (історія, вилучені факти, поточний стан) через окремий Telegram-інтерфейс.

Архітектура

Дев’ять підсистем скомпільовані в один Go-бінарник: Channel Adapter, AI Core, Knowledge Base, Session Store, Billing, People & Access, Workplaces, Observability, Integration Layer. Деплой через docker compose up на Hetzner CCX23 (4 vCPU AMD EPYC, 16 GB RAM, ~€28/міс).

Огляд системної архітектури

FSM сесії

12-стейтна FSM розмови

Сесії розмов зберігаються як FSM-стани в PostgreSQL — не в пам’яті. Бот переживає перезапуски сервера в середині розмови. LLM-виклики ідемпотентні через two-phase transaction з таблицею inflight_request — ніякого дублювання білінгу або генерації файлів при повторних спробах.

Ескалація до оператора

Схема ескалації до оператора

Білінговий потік

Схема підписки та білінгу

Ключові технічні рішення

Локальні embeddings (Ollama bge-m3)

Векторні операції виконуються повністю на сервері — без хмарної залежності для пошуку по базі знань. bge-m3 (567M параметрів, 1024-dim, мультимовна) запускається через Ollama на тому самому Hetzner VPS. Якщо хмарний LLM-провайдер недоступний — RAG-retrieval продовжує працювати.

Дві причини: (1) резільентність — хмарні embedding API були єдиною точкою відмови в аналогічних системах; (2) приватність — дані заявників не виходять за межі українського VPS.

Збереження Excel-формул

Go-бібліотека excelize. Template Validator запускається при завантаженні шаблону і блокує публікацію будь-якого шаблону, що втратить цілісність формул. Генератор артефактів заповнює лише комірки, марковані як input-плейсхолдери; формульні комірки ідентифікуються при ingest і повністю виключаються із шляху запису.

Go-моноліт, один бінарник

При 50 одночасних користувачах мережевий оверхед мікросервісів — чисті витрати. Компоненти AI Core мають щільні залежності: вивід Extractor іде прямо в Consistency Controller, потім в Artefact Generator. У моноліті: три виклики функцій. У мікросервісах: три HTTP round-trips плюс circuit breakers. docker compose up і один лог-стрім о 2-й ночі.

Специфікація першою + multi-model AI review

До написання першого рядка коду: детальна специфікація платформи пройшла кілька ітерацій multi-model AI review (Claude, Gemini, GPT-4o, DeepSeek, Grok паралельно) — десятки Architecture Decision Records.

Приклади знахідок до імплементації: оцінка RAM для Ollama була 2 GB (реально 3–4 GB); порядок primary/fallback для embedding-провайдера був інвертований; Prompt Registry опинився в Integration Layer замість AI Core.

Результати (після калібрування, тиждень 10)

Метрика	Ціль	Факт
Пілотних користувачів	10–20	15
Всього сесій завершено	≥50	65
Згенерованих `.xlsx` артефактів	—	~50
p50 відповідь AI	≤6s	5.1s
p95 відповідь AI	≤12s	10.6s
Валідність Excel-артефактів	99.9%	100%
Рівень ескалацій	<30%	22%
Вартість на користувача/міс	$5–10	~$7
Виконання в термін	8 тижнів	за графіком

Стек

Шар	Технологія
Мова	Go 1.26
Bot framework	go-telegram/bot
База даних	PostgreSQL 16 + pgvector
Embeddings	Ollama bge-m3 (локально, 1024-dim, мультимовна)
LLM-провайдер	OpenRouter (Claude / Gemini)
Генерація Excel	excelize
DB queries	sqlc + pgx
Background jobs	river (Go job queue, pg-backed)
Секрети	SOPS + age
Observability	OTel + Loki + Prometheus + Grafana + Tempo
Інфраструктура	Hetzner CCX23, Docker Compose, Caddy + Let’s Encrypt
CI/CD	GitHub Actions: golangci-lint, trivy, go test