This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Установка и запуск

Данная страница описывает процедуры развёртывания сервера GigaAM-Multilingual ASR в контейнерной среде (Docker Compose или ручной сборка) и инструкции по подготовке моделей.

Требования

Для работы сервера необходимы следующие компоненты:

• Python 3.10+ (в Docker-образе используется Python 3.12).
• Node.js 20+ (требуется только для CI/CD процессов генерации документации, не нужен для запуска самого сервиса).
• Git для получения исходного кода.
• Docker Engine и Docker Compose (рекомендуемый способ запуска).
• NVIDIA Driver версии 580 или новее (для GPU-ускорения).
• nvidia-container-toolkit (на хосте с GPU).
• Доступ к интернету для скачивания моделей из Hugging Face при первой настройке.

Подготовка моделей

Модели распознавания речи и детектора активности голоса (Silero VAD) не включены в Docker-образ и должны быть размещены на хосте. Сервер ожидает их наличие в структуре каталогов ./models относительно корня проекта.

Автоматическое скачивание

Используйте скрипт download_models.py для загрузки всех необходимых компонентов:

# Установите зависимость для скачивания (если ещё не установлена)
pip install huggingface-hub

# Скачайте модели в каталог ./models
python3 scripts/download_models.py ./models

Скрипт создаст следующую структуру файлов:

• ./models/gigaam-onnx/gigaam-multilingual-large-ctc/ — модель large (600M).
• ./models/gigaam-onnx/gigaam-multilingual-ctc/ — модель small (220M).
• ./models/vad/silero_vad.onnx — модель Silero VAD.

Общий размер скачиваемых данных составляет около 810 МБ. Если требуется загрузить только одну из моделей, используйте переменную окружения ASR_MODELS:

# Только large модель
ASR_MODELS=large python3 scripts/download_models.py ./models

# Только small модель
ASR_MODELS=small python3 scripts/download_models.py ./models

Развёртывание через Docker Compose (рекомендуется)

Это основной метод запуска в производственной среде. Файл docker-compose.yml уже настроен для автоматической сборки образа и монтирования моделей.

1. Клонируйте репозиторий:

   git clone https://git.maydayoffice.kz/maydayoffice/gigaam-asr-server.git
   cd gigaam-asr-server
   

2. Подготовьте модели (см. раздел выше):

   python3 scripts/download_models.py ./models
   

3. Запустите сервис:

   docker compose up -d --build
   

Сервер будет доступен на порту 43000 (маппинг на внутренний порт 8000). Для проверки статуса выполните:

curl http://localhost:43000/health

Использование готового образа

Если вы хотите использовать предварительно собранный образ из Forgejo Container Registry вместо локальной сборки, измените секцию image в docker-compose.yml или используйте команду docker run:

# Скачайте образ
docker pull git.maydayoffice.kz/maydayoffice/gigaam-asr-server:v0.1.4

# Запустите контейнер
docker run -d --gpus all -p 43000:8000 --name gigaam-asr \
  -v "$PWD/models:/models:ro" \
  git.maydayoffice.kz/maydayoffice/gigaam-asr-server:v0.1.4

Ручная сборка Docker-образа

При необходимости можно собрать образ вручную, минуя Compose.

1. Соберите образ:

   docker build -t gigaam-asr .
   

2. Запустите контейнер:
   • Для GPU:

     docker run -d --gpus all -p 8000:8000 -v /path/to/models:/models:ro gigaam-asr
     

   • Для CPU:

     docker run -d -p 8000:8000 -e GIGAAm_CUDA=0 -v /path/to/models:/models:ro gigaam-asr
     

Подробности о процессе сборки, включая установку зависимостей и выполнение тестов, описаны в файле Dockerfile.

Запуск без Docker (локальная установка)

Для разработки или отладки можно запустить сервер напрямую из Python-окружения.

1. Создайте виртуальное окружение и установите зависимости:

   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt
   

2. Скачайте модели:

   python3 scripts/download_models.py ./models
   

3. Запустите сервер:

   # Для GPU (автоматическое определение CUDA)
   python3 -m gigam_asr.server
   
   # Для принудительного использования CPU
   GIGAAm_CUDA=0 python3 -m gigam_asr.server
   

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

После запуска убедитесь, что сервер отвечает на запросы.

1. Проверка здоровья:

   curl http://localhost:43000/health
   

   Ожидаемый ответ содержит список загруженных моделей и статус ok.

2. Список моделей:

   curl http://localhost:43000/v1/models
   

3. Тестовое распознавание: Используйте любой аудиофайл (mp3, wav, ogg и т.д.):

   curl http://localhost:43000/v1/audio/transcriptions \
     -F file=@test_audio.mp3 \
     -F model=gigaam-multilingual-large-ctc
   

   Пример ответа:

   {
     "text": "Привет мир",
     "model": "gigaam-multilingual-large-ctc",
     "latency_s": 1.25
   }
   

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

Основные параметры настройки задаются через переменные окружения. Полный список описан в разделе Конфигурация. Наиболее важные для запуска:

Переменная	Значение по умолчанию	Описание
GIGAAm_CUDA	auto	Управление использованием GPU (1 — включить, 0 — отключить, auto — автоопределение).
MODELS	gigaam-multilingual-large-ctc,gigaam-multilingual-ctc	Список моделей для загрузки.
API_KEYS	(пусто)	Список Bearer-токенов для авторизации. Если пусто, авторизация отключена.
PORT	8000	Порт, на котором слушает сервер внутри контейнера.

Диагностика

• Ошибки загрузки моделей: Убедитесь, что структура каталога ./models соответствует ожиданиям (см. Подготовка моделей). Проверьте права доступа к файлам.
• Проблемы с GPU: Убедитесь, что установлен nvidia-container-toolkit и драйвер NVIDIA поддерживает CUDA 13. Проверьте вывод docker info на наличие GPU-устройств.
• Логирование: Просмотрите логи контейнера командой docker logs gigaam-asr или docker compose logs.

Для дополнительной информации об архитектуре см. Архитектура, а для деталей API — Справочник API.