Установка программного обеспечения SpeechSense Hybrid

Модуль SpeechSense Hybrid разворачивается с помощью Helm-чарта, который устанавливает верхнеуровневые компоненты и микросервисы.

• Микросервисы
• Архитектура микросервисов
• Helm-чарт микросервисов
• Переменные среды для запуска сервисов
• Дополнительные компоненты

МикросервисыМикросервисы

1. classifiersConnector — хранит пользовательские классификаторы. Переводит задачу на расчет классификаторов по тексту диалога в формат, понятный сервису классификации.
2. lobby — операции с пространствами, проектами и подключениями.
3. talkRouter — ставит задачи алгоритмам, сохраняет текущее состояние диалога.
4. speechkitConnector — переводит общую задачу на транскрибацию в формат, понятный для SpeechKit Hybrid.
5. userCustomization.
6. talkStatistics — рассчитывает статистики диалогов.
7. summarizationConnector — запрашивает суммаризацию у YandexGPT.
8. embeddingConnector — рассчитывает эмбеддинги по тексту. Хранит эмбеддинги диалога.
9. talkSearch — поиск диалогов.
10. talkReports — составление отчетов.
11. gptConnector.
12. iamAgent.
13. keycloak.
14. dataUI.

Архитектура микросервисовАрхитектура микросервисов

Архитектура микросервисов и их взаимодействие изображены на следующей диаграмме.

Helm-чарт микросервисовHelm-чарт микросервисов

Данный helm-чарт устанавливает верхнеуровневые компоненты из поставки модуля SpeechSense Hybrid.

Пререквизиты к установке микросервисовПререквизиты к установке микросервисов

Для установки helm-чарта должны быть выполнены следующие условия:

1. Развернут YandexGPT (входит в поставку). Есть сетевая доступность с использованием TLS до эндпоинта прокси-сервиса для маршрутизации запросов к моделям.

2. Развернут SpeechKit Hybrid (входит в поставку). Есть сетевая доступность с использованием TLS до эндпоинта прокси-сервиса для маршрутизации запросов к STT-бэкенду.

3. Развернут кластер PostgreSQL 15 с объемом свободного места 256 ГБ SSD, процессорными мощностями 12 vCPU, оперативной памятью 48 ГБ RAM.

   Рекомендуется сделать отказоустойчивую децентрализованную конфигурацию кластера в трех разных сетевых зонах. В кластере созданы базы данных talk-analytics, talk-classifiers, user-customizations, talk-speechkit и gpt-db. Создан пользователь pg-admin. Пользователю выделены права владельца пяти созданных баз данных.

4. Развернут кластер PostgreSQL 16.2 с объемом свободного места 10 ТБ SSD, процессорными мощностями 12 vCPU, оперативной памятью 48 ГБ RAM.

   Рекомендуется сделать отказоустойчивую децентрализованную конфигурацию кластера в трех разных сетевых зонах. В кластере созданы базы данных talk-db, summarization-db и embedding-db. Создан пользователь talk-db-user. Пользователю выделены права владельца пяти созданных баз данных.

5. Развернуто s3-совместимое хранилище. В хранилище созданы бакеты talks-s3-bucket с ограничением занятого места 30 ТБ и неограниченным временем жизни объектов и export-talks-s3-bucket с ограничением занятого места 1 ТБ и ограничением времени жизни объекта 1 день. Для сетевого хранилища заданы CORS-правила:

   {
         allowed_headers = ["*"]
         allowed_methods = ["PUT"]
         allowed_origins = ["<URL портала SpeechSense>"]
         expose_headers  = []
         max_age_seconds = 0
   }
   

6. Развернут кластер Apache Kafka® версии не ниже 3.3 из 6 рабочих нод с тремя нодами ZooKeeper.

   Конфигурация:

   • Рабочие ноды: процессорные мощности 12 vCPU, 48 ГБ RAM, 360 ГБ SSD.
   • Ноды ZooKeeper: процессорные мощности 2 vCPU, 8 ГБ RAM, 360 ГБ SSD.
   • Фактор репликации — 3, число партиций топиков по умолчанию — 15.

   В Apache Kafka® должны быть предварительно созданы следующие топики:

   • talk-analytics.task.new
   • talk-analytics.transcribe.in
   • talk-analytics.transcribe.out
   • talk-analytics.simple-audio-analyser.in
   • talk-analytics.simple-audio-analyser.out
   • talk-analytics.points.in
   • talk-analytics.points.out
   • talk-analytics.summarization.in
   • talk-analytics.summarization.out
   • talk-analytics.classifiers.in
   • talk-analytics.classifiers.out
   • talk-analytics.talk.updated
   • talk-analytics.topology.events
   • talk-analytics.classifiers.update
   • talk-analytics.embedding.in
   • talk-analytics.embedding.out
   • talk-analytics.statistics.in
   • talk-analytics.statistics.out
   • talk-analytics.translate.in
   • talk-analytics.translate.out

   Данные топики можно создать с помощью утилит командной строки для работы с Apache Kafka®. Например, с использованием следующего bash-скрипта:

   #!/bin/bash
   
   set -e
   set -u
   
   if ${KAFKA_HOME}/bin/kafka-cluster.sh cluster-id --bootstrap-server "${BOOTSTRAP_SERVER}"; then
       ${KAFKA_HOME}/bin/kafka-topics.sh --create --topic 'talk-analytics.task.new' --bootstrap-server "${BOOTSTRAP_SERVER}" --partitions 15 --replication-factor 3
       ${KAFKA_HOME}/bin/kafka-topics.sh --create --topic 'talk-analytics.transcribe.in' --bootstrap-server "${BOOTSTRAP_SERVER}" --partitions 15 --replication-factor 3
       ${KAFKA_HOME}/bin/kafka-topics.sh --create --topic 'talk-analytics.transcribe.out' --bootstrap-server "${BOOTSTRAP_SERVER}" --partitions 15 --replication-factor 3
       ${KAFKA_HOME}/bin/kafka-topics.sh --create --topic 'talk-analytics.simple-audio-analyser.in' --bootstrap-server "${BOOTSTRAP_SERVER}" --partitions 15 --replication-factor 3
       ${KAFKA_HOME}/bin/kafka-topics.sh --create --topic 'talk-analytics.simple-audio-analyser.out' --bootstrap-server "${BOOTSTRAP_SERVER}" --partitions 15 --replication-factor 3
       ${KAFKA_HOME}/bin/kafka-topics.sh --create --topic 'talk-analytics.points.in' --bootstrap-server "${BOOTSTRAP_SERVER}" --partitions 15 --replication-factor 3
       ${KAFKA_HOME}/bin/kafka-topics.sh --create --topic 'talk-analytics.points.out' --bootstrap-server "${BOOTSTRAP_SERVER}" --partitions 15 --replication-factor 3
       ${KAFKA_HOME}/bin/kafka-topics.sh --create --topic 'talk-analytics.summarization.in' --bootstrap-server "${BOOTSTRAP_SERVER}" --partitions 15 --replication-factor 3
       ${KAFKA_HOME}/bin/kafka-topics.sh --create --topic 'talk-analytics.summarization.out' --bootstrap-server "${BOOTSTRAP_SERVER}" --partitions 15 --replication-factor 3
       ${KAFKA_HOME}/bin/kafka-topics.sh --create --topic 'talk-analytics.classifiers.in' --bootstrap-server "${BOOTSTRAP_SERVER}" --partitions 15 --replication-factor 3
       ${KAFKA_HOME}/bin/kafka-topics.sh --create --topic 'talk-analytics.classifiers.out' --bootstrap-server "${BOOTSTRAP_SERVER}" --partitions 15 --replication-factor 3
       ${KAFKA_HOME}/bin/kafka-topics.sh --create --topic 'talk-analytics.talk.updated' --bootstrap-server "${BOOTSTRAP_SERVER}" --partitions 15 --replication-factor 3
       ${KAFKA_HOME}/bin/kafka-topics.sh --create --topic 'talk-analytics.topology.events' --bootstrap-server "${BOOTSTRAP_SERVER}" --partitions 15 --replication-factor 3
       ${KAFKA_HOME}/bin/kafka-topics.sh --create --topic 'talk-analytics.classifiers.update' --bootstrap-server "${BOOTSTRAP_SERVER}" --partitions 15 --replication-factor 3
       ${KAFKA_HOME}/bin/kafka-topics.sh --create --topic 'talk-analytics.embedding.in' --bootstrap-server "${BOOTSTRAP_SERVER}" --partitions 15 --replication-factor 3
       ${KAFKA_HOME}/bin/kafka-topics.sh --create --topic 'talk-analytics.embedding.out' --bootstrap-server "${BOOTSTRAP_SERVER}" --partitions 15 --replication-factor 3
       ${KAFKA_HOME}/bin/kafka-topics.sh --create --topic 'talk-analytics.statistics.in' --bootstrap-server "${BOOTSTRAP_SERVER}" --partitions 15 --replication-factor 3
       ${KAFKA_HOME}/bin/kafka-topics.sh --create --topic 'talk-analytics.statistics.out' --bootstrap-server "${BOOTSTRAP_SERVER}" --partitions 15 --replication-factor 3
       ${KAFKA_HOME}/bin/kafka-topics.sh --create --topic 'talk-analytics.translate.in' --bootstrap-server "${BOOTSTRAP_SERVER}" --partitions 15 --replication-factor 3
       ${KAFKA_HOME}/bin/kafka-topics.sh --create --topic 'talk-analytics.translate.out' --bootstrap-server "${BOOTSTRAP_SERVER}" --partitions 15 --replication-factor 3
   else
     exit 1
   fi
   
   

7. Развернут кластер OpenSearch версии не ниже 2.12 из 3 data-нод, 3 нод с ролью manager и одной ноды с ролью dashboard.

   Рекомендуется сделать отказоустойчивую децентрализованную конфигурацию кластера с data-нодами и manager-нодами в трех разных сетевых зонах.

   Конфигурация:

   • Data-ноды: 24 vCPU, 96 ГБ RAM и 1 ТБ SSD.
   • Manager-ноды: 4 vCPU, 16 ГБ RAM, 16 ГБ SSD.
   • Dashboard-ноды: 4 vCPU, 16 ГБ RAM, 16 ГБ SSD.

8. Развернут кластер ClickHouse® версии не ниже 25.3 из 3 шардов и 3 нод ZooKeeper.

   Рекомендуется сделать отказоустойчивую децентрализованную конфигурацию кластера в трех разных сетевых зонах.

   Конфигурация:

   • Шарды: 64 vCPU, 256 ГБ RAM, 1 ТБ SSD.
   • Ноды ZooKeeper: 8 vCPU, 32 ГБ RAM, 16 ГБ SSD.

9. Развернут кластер Kubernetes с версией мастер-узла и рабочих узлов не ниже 1.32.

   Рекомендуется сделать отказоустойчивую децентрализованную конфигурацию кластера в трех разных сетевых зонах. Требуется создать 24 рабочих узла.

   Конфигурация:

   • Мастер-узел: 2 vCPU и 8 ГБ RAM.
   • Группа узлов: 28 vCPU, 56 ГБ RAM, 64 ГБ HDD.
   • CIDR кластера задать как 10.20.0.0/16, CIDR сервисов — как 10.21.0.0/16.

   Требуется наличие сетевого доступа между всеми ресурсами и кластером Kubernetes. При использовании TLS-соединения требуется наличие клиентского сертификата для доступа к ресурсу.

   Требуется доступ от кластера Kubernetes до Container Registry с образами микросервисов.

Порядок установки Helm-чартаПорядок установки Helm-чарта

Кластер Kubernetes может находиться в закрытом контуре сети, но должен иметь публичный IP-адрес в данном контуре. Кроме того, предполагается наличие возможности задать DNS-имена для публичных IP-адресов в данном контуре. Например, с помощью локального DNS-сервера в закрытой подсети.

Установка выполняется с компьютера с настроенной утилитой kubectl, утилитой helm и сетевым доступом к кластеру Kubernetes.

1. Установите helm-чарт ProjectContour:

   helm repo add projectcontour https://projectcontour.io/helm-chart
   helm repo update
   

   helm install contour projectcontour/contour -n projectcontour --create-namespace
   

   Проверка корректной установки:

   kubectl get svc -n projectcontour
   

   • сервис envoy должен быть доступен через LoadBalancer.

2. Актуализируйте секреты в файле values.sample.yaml в секции global.secrets:

   Название секрета	Описание
   PG_USERNAME	Имя пользователя PostgreSQL
   PG_PASSWORD	Пароль пользователя PostgreSQL
   KAFKA_USERNAME	Имя пользователя Apache Kafka®
   KAFKA_PASSWORD	Пароль пользователя Apache Kafka®
   S3_ACCESS_KEY	Ключ доступа к S3
   S3_SECRET_KEY	Приватный ключ доступа к S3
   CLICKHOUSE_USERNAME	Имя пользователя ClickHouse®
   CLICKHOUSE_PASSWORD	Пароль пользователя ClickHouse®
   OPENSEARCH_USERNAME	Имя пользователя OpenSearch
   OPENSEARCH_PASSWORD	Пароль пользователя OpenSearch
   KC_BOOTSTRAP_ADMIN_USERNAME	Имя администратора Keycloak
   KC_BOOTSTRAP_ADMIN_PASSWORD	Пароль администратора Keycloak
   keycloak_service_client-id	Имя клиента Keycloak
   keycloak_service_client-secret	Секрет клиента Keycloak
   KEYCLOAK_OIDC_SECRET	Секрет OIDC Keycloak
   API_KEY	API-ключ сервисного аккаунта

3. Заполните параметры в файле values.sample.yaml:

   Полный путь к параметру	Описание	Пример значения
   global.crLink	ссылка на Container Registry	cr.yandex/crp838mmkhvh5r1ajfeo
   global.env.spring_cloud_stream_kafka_binder_brokers	строка подключения к брокерам Apache Kafka®	kafka-0.kafka-headless-srv.ta-resources.svc.cluster.local:9092,kafka-1.kafka-headless-srv.ta-resources.svc.cluster.local:9092,kafka-2.kafka-headless-srv.ta-resources.svc.cluster.local:9092
   global.env.spring_cloud_stream_kafka_binder_configuration_security_protocol	протокол подключения к брокерам Apache Kafka®	PLAINTEXT
   global.env.spring_datasource_hikari_data-source-properties_ssl	использовать ли SSL-подключение к PostgreSQL	true
   global.env.spring_datasource_hikari_data-source-properties_sslmode	уровень SSL-подключения к PostgreSQL	require
   global.env.s3_storage_endpoint	эндпоинт S3	https://s3.example.com
   global.env.security_serviceAccountToken	api-ключ сервисного аккаунта	YT*****************************************Q==
   services.classifiersConnector.env.classifiers_host	хост API-метода лемматизации YandexGPT	lemmatization-backend.speechkit.svc.cluster.local
   services.classifiersConnector.env.classifiers_port	порт API-метода лемматизации YandexGPT	17004
   services.classifiersConnector.env.spring_datasource_url	jdbc-строка подключения к БД talk-classifiers	jdbc:postgresql://postgres-srv.ta-resources.svc.cluster.local:5432/talk-classifiers
   services.lobby.env.spring_datasource_url	jdbc-строка подключения к БД talk-analytics PostgreSQL	jdbc:postgresql://postgres-srv.ta-resources.svc.cluster.local:5432/talk-analytics
   services.talkRouter.env.spring_datasource_url	jdbc-строка подключения к БД talk-db PostgreSQL	jdbc:postgresql://postgres-srv.ta-resources.svc.cluster.local:5432/talk-db
   services.speechkitConnector.env.speechkit_stt_host	Хост эндпоинта прокси SpeechKit Hybrid	api-proxy-stt.speechkit.svc.cluster.local
   services.speechkitConnector.env.speechkit_stt_port	Порт эндпоинта прокси SpeechKit Hybrid	8443
   services.speechkitConnector.env.operation_host	Хост эндпоинта прокси SpeechKit Hybrid	api-proxy-stt.speechkit.svc.cluster.local
   services.speechkitConnector.env.operation_port	Порт эндпоинта прокси SpeechKit Hybrid	8443
   services.speechkitConnector.env.spring_datasource_url	jdbc-строка подключения к БД talk-speechkit PostgreSQL	jdbc:postgresql://postgres-srv.ta-resources.svc.cluster.local:5432/talk-speechkit
   services.userCustomization.env.spring_datasource_url	jdbc-строка подключения к БД user-customizations PostgreSQL	jdbc:postgresql://postgres-srv.ta-resources.svc.cluster.local:5432/user-customizations
   services.summarizationConnector.env.operation_host	Хост эндпоинта прокси YandexGPT	fm-api-proxy.yagpt.svc.cluster.local
   services.summarizationConnector.env.operation_port	Порт эндпоинта прокси YandexGPT	8443
   services.summarizationConnector.env.gpt_host	Хост эндпоинта прокси YandexGPT	fm-api-proxy.yagpt.svc.cluster.local
   services.summarizationConnector.env.gpt_port	Порт эндпоинта прокси YandexGPT	8443
   services.summarizationConnector.env.spring_datasource_url	jdbc-строка подключения к БД summarization-db PostgreSQL	jdbc:postgresql://postgres-srv.ta-resources.svc.cluster.local:5432/summarization-db
   services.embeddingConnector.env.spring_datasource_url	jdbc-строка подключения к БД embedding-db PostgreSQL	jdbc:postgresql://postgres-srv.ta-resources.svc.cluster.local:5432/embedding-db
   services.embeddingConnector.env.gpt_host	Хост эндпоинта прокси YandexGPT	fm-api-proxy.yagpt.svc.cluster.local
   services.embeddingConnector.env.gpt_port	Порт эндпоинта прокси YandexGPT	8443
   services.talkSearch.env.opensearch_hosts	Эндпоинт кластера OpenSearch	opensearch-cluster.opensearch.svc.cluster.local:9200
   services.talkSearch.env.OPENSEARCH_ENDPOINT	Эндпоинт кластера OpenSearch	opensearch-cluster.opensearch.svc.cluster.local:9200
   services.talkReports.env.clickhouse_url	jdbc-строка подключения к кластеру ClickHouse®	jdbc:clickhouse://clickhouse-service.clickhouse.svc.cluster.local:8123/?distributed_directory_monitor_batch_inserts=1
   iamAgentKeycloak.env.keycloak_server-url	URL Keycloak	https://keycloak.example.com
   keycloak.env.KC_HOSTNAME	URL Keycloak	keycloak.example.com
   keycloak.env.KC_DB_URL	jdbc-строка подключения к БД Keycloak PostgreSQL	jdbc:postgresql://postgres-srv.ta-resources.svc.cluster.local:5432/keycloak?targetServerType=master
   dataUI.env.BACKEND_PATH	URL сетевого балансировщика ProjectContour	envoy.example.com
   dataUI.env.KEYCLOAK_OIDC_BASE_URL	URL UI SpeechSense Hybrid	https://speechsense.example.com
   dataUI.env.KEYCLOAK_OIDC_ISSUER_BASE_URL	URL настроек получения опций от Keycloak	https://keycloak.example.com/realms/speechsense

4. Сохраните файл values.sample.yaml под именем values.yaml и установите helm-чарт микросервисов SpeechSense Hybrid:

   cp ./services-helm/values.sample.yaml ./services-helm/values.yaml
   helm upgrade --install talk-analytics-services ./services-helm --namespace ta-services --create-namespace
   

Переменные среды для запуска сервисовПеременные среды для запуска сервисов

Общие переменные средыОбщие переменные среды

Данные переменные пробрасываются во все микросервисы SpeechSense Hybrid.

kafka-0.kafka-headless-srv.ta-resources.svc.cluster.local:9092,kafka-1.kafka-headless-srv.ta-resources.svc.cluster.local:9092,kafka-2.kafka-headless-srv.ta-resources.svc.cluster.local:9092

Параметры сервисов по умолчаниюПараметры сервисов по умолчанию

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

В таблице ниже приведены параметры по умолчанию для всех микросервисов. Параметры по умолчанию для индивидуальных сервисов приведены в соответствующих им разделах.

Секреты микросервисовСекреты микросервисов

В кластере k8s создается один секрет global-secrets со всеми секретами из файла values.yaml. В микросервисы передаются требуемые секреты как переменные среды. Полный список секретов:

classifiersConnectorclassifiersConnector

Переменные среды для запускаПеременные среды для запуска

Переменные по умолчаниюПеременные по умолчанию

lobbylobby

Переменные среды для запускаПеременные среды для запуска

Переменные по умолчаниюПеременные по умолчанию

talkRoutertalkRouter

Переменные среды для запускаПеременные среды для запуска

Переменные по умолчаниюПеременные по умолчанию

speechkitConnectorspeechkitConnector

Переменные среды для запускаПеременные среды для запуска

Переменные по умолчаниюПеременные по умолчанию

userCustomizationuserCustomization

Переменные среды для запускаПеременные среды для запуска

Переменные по умолчаниюПеременные по умолчанию

talkStatisticstalkStatistics

Переменные среды для запускаПеременные среды для запуска

Переменные по умолчаниюПеременные по умолчанию

summarizationConnectorsummarizationConnector

Переменные среды для запускаПеременные среды для запуска

Переменные по умолчаниюПеременные по умолчанию

embeddingConnectorembeddingConnector

Переменные среды для запускаПеременные среды для запуска

Переменные по умолчаниюПеременные по умолчанию

talkSearchtalkSearch

Переменные среды для запускаПеременные среды для запуска

Переменные по умолчаниюПеременные по умолчанию

talkReportstalkReports

Переменные среды для запускаПеременные среды для запуска

iamAgentiamAgent

Переменные среды для запускаПеременные среды для запуска

keycloakkeycloak

Переменные среды для запускаПеременные среды для запуска

dataUIdataUI

Переменные среды для запускаПеременные среды для запуска

Дополнительные компонентыДополнительные компоненты

Помимо helm-чарта в составе модуля SpeechSense Hybrid поставляются специальные версии компонентов YandexGPT и SpeechKit Hybrid, необходимые для работы ПО. В ходе развертывания они устанавливаются в кластере Kubernetes.