Avito AI Assistant

Задача проекта

Avito AI Assistant — автономный event-driven сервис для автоматизации клиентских коммуникаций в Avito Messenger с поддержкой безопасной передачи управления оператору (human-in-the-loop) через Telegram.

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

Поток входящих сообщений и идемпотентность

Архитектура исключает слепое доверие внешним вебхукам: - Webhook Avito принимается эндпоинтом FastAPI; - Сервис повторно считывает канонические данные чата, сообщений и объявления через официальный Avito API; - Логика спроектирована с учётом доставки сообщений at-least-once и гарантирует идемпотентность (повторный вебхук не порождает дублирующих ответов); - Контекст диалога анализируется с учётом истории и прикреплённых вложений.

Паттерн Durable Outbox и надёжность

Для гарантированной доставки сообщений без потери данных реализован паттерн Durable Outbox: - Состояние входящего события и все планируемые побочные эффекты (карточка в Telegram, ответ в Avito, пересылка медиа) фиксируются в рамках единой транзакции PostgreSQL; - Фоновый диспетчер с очередью в Redis выполняет гарантированную доставку эффектов адресатам; - При сбоях сети или внешних API запускаются повторные попытки (retries) с экспоненциальным backoff; - События с исчерпанным лимитом попыток переводятся в терминальный статус failed без создания бесконечной нагрузки.

Human-in-the-loop и перехват диалога

Каждый диалог находится под полным контролем человека: - В Telegram-чат сотрудника отправляется структурированная карточка с именем клиента, ссылкой на объявление, исходным текстом, саммари, темой и уровнем срочности; - Если оператор отвечает reply'ем на карточку в Telegram, сообщение мгновенно отправляется клиенту в Avito; - При ответе человека AI-автоматизация для данного диалога немедленно блокируется и не возобновляется автоматически; - Для возврата ИИ оператор должен явно нажать инлайн-кнопку «Вернуть ИИ».

База знаний и поэтапный запуск

Факты и правила хранятся в версионируемых YAML-файлах со стабильными идентификаторами, триггерами и согласованными формулировками.

Поддерживается поэтапный ввод автоматизации в эксплуатацию (staged rollout): режим SHADOW (теневой скоринг ответов без отправки), allowlist конкретных тестовых объявлений и режим AUTO для всего профиля.

Длина автодиалога ограничена настраиваемым лимитом сообщений для предотвращения зацикливания.

Инфраструктура, безопасность и мониторинг

Сервис развёрнут в изолированной сети Docker Compose за обратным прокси Caddy с автоматическим HTTPS.

База данных PostgreSQL и Redis доступны только внутри приватной сети контейнеров. Действует строгая политика конфиденциальности: токены и тексты переписок не попадают в технические логи, а история диалогов подлежит регулярной retention-очистке через 90 дней.

Для оркестрации настроены раздельные health check эндпоинты: /live (работоспособность процесса) и /ready (проверка доступности PostgreSQL, Redis и актуальности миграций Alembic).