Настоящий документ описывает порядок установки и развёртывания экземпляра программного обеспечения «AI-оператор контакт-центра» (далее — ПО) на инфраструктуре пользователя, а также порядок проверки его работоспособности. Документ предназначен для технических специалистов, выполняющих развёртывание, в том числе для экспертов, осуществляющих проверку экземпляра ПО.

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

1. Состав программного обеспечения

ПО поставляется в виде набора контейнеризованных сервисов и вспомогательных компонентов.

1.1. Сервисы ПО

1.2. Используемое стороннее и системное ПО (устанавливается пользователем)

Встраиваемая векторная база данных (Chroma) входит в состав поискового сервиса и отдельной установки не требует: данные индекса хранятся в каталоге на диске, подключаемом к контейнерам как том.

1.3. Внешние сервисы, необходимые для полнофункциональной работы

2. Системные требования

2.1. Аппаратные требования (минимальные для одного экземпляра)

Допускается размещение всех компонентов на одном сервере (8 vCPU, 16 ГБ ОЗУ) для тестового или демонстрационного стенда. Требования к серверу LLM-инференса определяются выбранной языковой моделью и в состав требований ПО не входят.

2.2. Программные требования

• ОС Linux x86_64 с поддержкой Docker (ядро 5.x и новее);
• Docker Engine 24+ и Docker Compose v2;
• MongoDB 6.0 и новее;
• Redis 7 / Valkey 7 и новее;
• nginx 1.22 и новее (или аналог);
• при запуске вне контейнеров: Python 3.11 (строго), пакетный менеджер PDM.

2.3. Сетевые требования

• Входящий HTTPS (443) — приём вебхуков чат-платформы;
• исходящий HTTPS — обращения к чат-платформе, LLM-сервису, сервису эмбеддингов, источникам фидов и справочников;
• исходящий SMTP — почтовые отчёты;
• внутренняя сеть между сервером приложений и сервером СУБД (порты MongoDB и Redis).

3. Архитектура развёртывания

Экземпляр ПО развёртывается как стек Docker Compose из трёх контейнеров:

1. контейнер API-сервиса — диалоговый конвейер, вебхуки, статистика;
2. контейнер поискового сервиса — MCP-инструменты;
3. контейнер фонового воркера — периодические задачи обработки данных (использует образ поискового сервиса).

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

ПО поддерживает мультитенантное использование: для каждого обслуживаемого предприятия (тенанта) разворачивается отдельный стек Compose со своим файлом конфигурации; общими могут быть экземпляры Redis/Valkey (изоляция обеспечивается префиксом ключей) и СУБД. Внешний reverse proxy маршрутизирует запросы на порт соответствующего стека.

Аутентификация всех запросов к API сервисов выполняется самим ПО по ключу API, передаваемому в HTTP-заголовке.

4. Порядок развёртывания

4.1. Подготовка

1. Установите Docker Engine и Docker Compose согласно документации производителя ОС.
2. Разверните и настройте MongoDB и Redis/Valkey; создайте базу данных и учётную запись для ПО.
3. Обеспечьте доступность LLM-сервиса и сервиса эмбеддингов (адреса их HTTP API потребуются на шаге конфигурации).
4. Создайте рабочий каталог экземпляра, например /opt/contact-center/tenant-a/, и подкаталог тома векторной базы ./vector_db/.

4.2. Загрузка образов

Docker-образы сервисов поставляются в составе дистрибутива ПО в виде архивов и загружаются командой:

docker load -i contact-center-api.tar
docker load -i contact-center-search.tar

Альтернативно образы могут быть собраны из исходных текстов дистрибутива (в составе каждого сервиса имеется Dockerfile на базе python:3.11):

docker build -t contact-center/api:<версия> ./apiService
docker build -t contact-center/search:<версия> ./searchService

4.3. Файл docker-compose.yml (пример)

Разместите в рабочем каталоге файл следующего вида (номера внешних портов приведены для примера и выбираются администратором):

services:
  api:
    image: contact-center/api:<версия>
    restart: unless-stopped
    env_file: ./api.env
    ports:
      - "127.0.0.1:8080:80"

  search:
    image: contact-center/search:<версия>
    restart: unless-stopped
    env_file: ./search.env
    volumes:
      - ./vector_db:/app/vector_db
    ports:
      - "127.0.0.1:8081:80"

  worker:
    image: contact-center/search:<версия>
    restart: unless-stopped
    env_file: ./search.env
    volumes:
      - ./vector_db:/app/vector_db
    command: <команда запуска фонового воркера из документации дистрибутива>

При размещении СУБД на отдельном сервере при необходимости используйте секцию extra_hosts для сопоставления имён хостов и IP-адресов.

4.4. Конфигурация (переменные окружения)

Конфигурация задаётся файлами окружения для каждого сервиса. Параметры включают: ключи аутентификации API, строки подключения к СУБД и хранилищу состояния, адреса LLM-сервиса и сервиса эмбеддингов, параметры интеграции с чат-платформой и учётной системой, режим работы (автономный/подсказки), долю автоматизируемого трафика и параметры SMTP. Полный перечень переменных с комментариями содержится в файлах-образцах в составе дистрибутива; значения определяются инфраструктурой пользователя и в настоящем документе не приводятся.

Значения секретов (ключи, пароли, строки подключения с учётными данными) должны храниться с ограничением доступа (права на файлы окружения 0600) и не должны включаться в системы контроля версий.

4.5. Запуск стека

cd /opt/contact-center/tenant-a
docker compose up -d
docker compose ps

Все три контейнера должны перейти в состояние running (Up).

4.6. Первичное наполнение данных

После первого запуска выполните начальную загрузку каталога и построение векторного индекса — вызовом служебных защищённых HTTP-эндпоинтов поискового сервиса (перечень — в документации дистрибутива; ключ API обязателен):

curl -X POST -H "<заголовок ключа API>: <ключ>" http://127.0.0.1:8081/<эндпоинт загрузки каталога>
curl -X POST -H "<заголовок ключа API>: <ключ>" http://127.0.0.1:8081/<эндпоинт построения индекса>

Задачи выполняются фоновым воркером; ход выполнения виден в журнале контейнера фонового воркера.

4.7. Настройка reverse proxy

Настройте nginx: HTTPS-виртуальный хост с проксированием пути экземпляра на локальный порт контейнера api (в примере — 127.0.0.1:8080), перенаправлением HTTP→HTTPS и увеличенными таймаутами проксирования (рекомендуется не менее 300 с) с учётом длительности LLM-генерации. Укажите полученный публичный URL вебхука в настройках чат-платформы.

4.8. Настройка планировщика

Периодические операции запускаются планировщиком cron сервера приложений через HTTP-вызовы служебных защищённых эндпоинтов (их перечень приведён в документации дистрибутива). Рекомендуемое расписание:

5. Проверка работоспособности

Проверка выполняется последовательно по следующим шагам.

1. Состояние контейнеров. docker compose ps — все контейнеры в состоянии Up; в журналах сервисов отсутствуют ошибки запуска, веб-приложения сообщают о готовности, фоновый воркер — о подключении к брокеру очередей.
2. Аутентификация. HTTP-запрос к API-сервису без ключа API возвращает ошибку авторизации; с корректным ключом — успешный ответ. Это подтверждает работу контура защиты API.
3. Инструментальный слой. Запрос перечня MCP-инструментов поискового сервиса (служебный эндпоинт, ключ API обязателен) возвращает список инструментов (поиск товара, FAQ, справки и др.) с их JSON-схемами.
4. Данные каталога. После выполнения п. 4.6 вызов инструмента поиска товара с тестовым запросом возвращает карточки товаров; том векторной базы содержит файлы индекса.
5. Диалоговый конвейер. Отправка тестового сообщения в эндпоинт прямого чата API-сервиса возвращает осмысленный ответ ассистента; в журнале сервиса видны стадии конвейера (классификация намерения, вызовы инструментов, формирование ответа).
6. Хранилища. В MongoDB появились коллекции истории диалогов и статистики; в Redis/Valkey — ключи состояния сессии с заданным префиксом.
7. Сквозной сценарий (при подключённой чат-платформе). Сообщение, отправленное из тестового канала чат-платформы, доставляется вебхуком на публичный URL, обрабатывается конвейером, и ответ бота появляется в канале; команда передачи оператору переводит диалог на живого оператора.
8. Фоновые задачи. По расписанию планировщика в журналах фиксируется выполнение задач обновления фида и статистики; неактивный тестовый диалог автоматически закрывается по таймауту.

Успешное прохождение шагов 1–6 подтверждает работоспособность развёрнутого экземпляра ПО; шаги 7–8 подтверждают полноту интеграционной настройки.

6. Остановка, обновление и удаление

• Остановка: docker compose down в рабочем каталоге экземпляра (данные в СУБД и том векторной базы сохраняются).
• Обновление: загрузка новых версий образов (docker load или сборка), правка тега версии в docker-compose.yml, затем docker compose up -d.
• Удаление: docker compose down, удаление рабочего каталога экземпляра, удаление образов (docker rmi), при необходимости — удаление базы данных экземпляра в MongoDB и ключей с префиксом экземпляра в Redis/Valkey.