Установка и эксплуатация

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

1. Комплект поставки

Манифесты поставки — это манифесты облачной установки правообладателя, в них записаны её адреса и сервисы. Перед применением заказчик приводит их к своей установке:

• адреса образов — на версии из реестра поставки;
• значения, записанные в манифестах сервера и обработчика очередей прямо: FRONTEND_URL, SHOPS_DOMAIN, R2_ENDPOINT, R2_PUBLIC_URL, SMTP_HOST, SMTP_PORT, SMTP_USE_TLS, SMTP_START_TLS — на свои (значение в манифесте главнее значения в секрете); LLM_MODEL_QUERY — на имя своей модели либо удалить;
• ссылки на ключи секрета yandex-gpt-api-key, yandex-gpt-folder-id, yandex-maps-api-key и на секрет metrika-credentials — удалить: они нужны только облачной установке, а без них в кластере поды не запускаются;
• в манифесте панели управления — удалить NEXT_PUBLIC_API_URL и NEXT_PUBLIC_YM_COUNTER_ID и задать параметры PARSEWISE_* из раздела 3;
• шаблон секретов — заполнить своими значениями и применить; в нём все секреты, которые читают манифесты поставки, в том числе app-config-full с параметрами SECRET_KEY, DOCS_USERNAME, DOCS_PASSWORD, EMAIL_FROM, INGRESS_LB_IP, LLM_BASE_URL;
• параметры сервисов, которые заказчик не использует, — удалить: приём платежей через Robokassa, Яндекс Метрику;
• образец политики доступа бакета — подставить имя своего бакета и учётную запись сервера; он написан для Yandex Object Storage, в другом хранилище те же правила доступа (раздел 2) задаются его средствами;
• для адресов проектов вида проект.домен — выпустить сертификат на *.домен через cert-manager с проверкой DNS01 у своего DNS-провайдера и указать его в 06a-ingress-shops.yaml.

Манифесты маркетингового сайта, документации и мониторинга в поставку не входят.

Образы передаются архивом OCI для загрузки в реестр заказчика либо через реестр образов правообладателя.

Образы собираются из зеркал правообладателя: базовые образы, пакеты Python и пакеты npm при сборке не загружаются из публичных репозиториев. Для обработки аудио и видео в образ сервера входит ffmpeg из дистрибутива Debian. Модель векторизации при установке и запуске не загружается. Процессы в контейнерах сервера и панели управления работают от непривилегированного пользователя.

2. Требования к среде

Каждый под сервера и обработчика очередей открывает до 40 подключений к PostgreSQL. При большом числе реплик рекомендуется пул соединений, например PgBouncer или Odyssey.

Вычислительные ресурсы

Сумма запросов ресурсов без системных компонентов Kubernetes: около 5,8 vCPU и 14,9 ГиБ памяти при минимальном числе реплик, около 21,1 vCPU и 47,6 ГиБ при максимальном. Узел должен вмещать под векторизации с запросом памяти 2,5 ГиБ.

Конфигурация, на которой программа эксплуатируется правообладателем: 4–10 узлов по 4 vCPU и 8 ГиБ с автоматическим добавлением узлов; основная и векторная базы — отдельные кластеры PostgreSQL 15 по 2 vCPU и 8 ГиБ с диском 20 ГиБ и автоматическим увеличением до 64 ГиБ; Valkey 7.2 — 2 vCPU и 4 ГиБ.

3. Настройка

Параметры сервера, обработчика очередей и планировщика задаются переменными окружения — из секретов Kubernetes или значениями в манифестах (раздел 1). Все три развёртывания получают одинаковые параметры подключения к базам, Redis и объектному хранилищу.

Обязательные

Параметры FRONTEND_URL, EMAIL_FROM, SHOPS_DOMAIN и INGRESS_LB_IP имеют значения по умолчанию, указывающие на облачную установку правообладателя, поэтому в установке заказчика их необходимо задать.

Языковая модель

Сервисы компании OpenAI программой не используются: «OpenAI-совместимый» — это только формат программного интерфейса, который поддерживают vLLM и другие серверы моделей. Имена openai и OPENAI_API_KEY сохранены по этому формату.

Векторизация

Необязательные

Панель управления и виджет

Панель управления читает параметры установки из переменных окружения контейнера при запуске. Незаданная переменная оставляет значение, с которым собран образ; переменная с пустым значением отключает соответствующую функцию. Образ собран со значениями облачной установки правообладателя — счётчик Яндекс Метрики, приложения Яндекс ID и VK ID, адрес виджета на releases.parsewise.ru, — поэтому в установке заказчика PARSEWISE_YM_COUNTER_ID, PARSEWISE_YANDEX_CLIENT_ID и PARSEWISE_VK_CLIENT_ID задаются явно, своими значениями или пустыми, а PARSEWISE_WIDGET_SCRIPT_URL — адресом виджета в инфраструктуре заказчика.

Виджет получает адрес сервера программного интерфейса параметром apiUrl в window.ParsewiseConfig на странице, вместе с идентификатором проекта shopId; ссылку на политику обработки персональных данных — параметром privacyPolicyUrl или из настроек проекта.

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

4. Установка

1. Подготовить PostgreSQL: основную и векторную базы. В векторной базе должен быть доступен тип vector. Если его нет, программа выполняет CREATE EXTENSION IF NOT EXISTS vector; если у роли приложения нет такого права, администратор базы выполняет CREATE EXTENSION vector заранее.
2. Подготовить Redis и бакет S3-совместимого объектного хранилища; настроить правила CORS и доступ к объектам бакета по разделу 2.
3. Загрузить образы в реестр, доступный кластеру, и указать их адреса в манифестах.
4. Создать пространство имён и секреты с параметрами из раздела 3.
5. Указать в манифесте маршрутизации доменные имена программного интерфейса и панели управления, настроить TLS.
6. Применить манифесты. При запуске сервер создаёт недостающие таблицы основной базы и применяет миграции, входящие в образ; векторное хранилище создаёт свои таблицы и индексы.
7. Разместить файлы виджета на статическом сервере или в объектном хранилище заказчика.
8. Проверить установку:
   • все поды в состоянии готовности; поды векторизации загружают модель до трёх минут;
   • запрос GET /v1/public/health к серверу программного интерфейса возвращает {"status": "ok"};
   • в журнале сервера есть строка Alembic migrations applied (head reached) и нет сообщений Alembic upgrade failed и ошибок pgvector.

5. Начало работы

1. Войти в панель управления и создать проект.
2. Настроить персону ассистента: имя, аватар и правила ответов.
3. Наполнить базу знаний: загрузить файлы, импортировать товары или профили из файла либо подключить источник по ссылке.
4. Пригласить участников команды и назначить роли.
5. Подключить виджет на страницы сайта или личного кабинета:

<script>
  window.ParsewiseConfig = {
    shopId: "ИДЕНТИФИКАТОР_ПРОЕКТА",
    apiUrl: "https://АДРЕС_СЕРВЕРА_API",
  };
</script>
<script async src="https://АДРЕС_СТАТИКИ/widget.iife.js"></script>

Подробный порядок работы в панели управления — в Руководстве пользователя и администратора.

6. Эксплуатация