maydayoffice/gigaam-asr-server
Watch
3
0
Fork
You've already forked gigaam-asr-server
 0
Code Issues Pull requests 5 Releases 5 Packages 1 Wiki Activity Actions
Page: ci cd
Pages
Home api reference architecture ci cd configuration installation overview performance testing
5 ci cd
AI Wiki Bot edited this page 2026-09-16 19:34:21 +00:00
Unescape Escape
Table of contents
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.

CI/CD и автоматизация

Система непрерывной интеграции и доставки (CI/CD) проекта GigaAM-Multilingual ASR Server реализована на платформе Forgejo Actions. Конвейеры отвечают за контроль качества кода, сборку и публикацию Docker-образов в Container Registry, а также генерацию технической документации (wiki) с помощью LLM.

Состав конвейеров

В каталоге .forgejo/workflows/ находятся три файла конфигурации:

  1. Lint — статический анализ кода Python.
  2. Build and Push Docker Image — сборка контейнера и его публикация.
  3. Generate AI Wiki — автоматическая генерация документации.

Статический анализ (Lint)

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

Этот конвейер запускается при каждом создании Pull Request в ветку main. Он обеспечивает соблюдение стандартов стиля кода до того, как изменения будут объединены.

Инструментарий

  • Ruff: быстрый линтер и форматтер для Python.

Логика работы

  1. Проверяется наличие изменений в PR.
  2. Устанавливается пакет ruff.
  3. Выполняется команда ruff check . --output-format=github.
  4. Результаты отображаются в интерфейсе Forgejo как комментарии к строкам кода (inline annotations).

Настройки линтера заданы в файле pyproject.toml:

  • Длина строки: 110 символов.
  • Правила: E, F, W, I, B (pycodestyle, pyflakes, warning, isort, flake8-bugbear).
  • Исключение для server.py: правило B008 (вызовы функций в значениях по умолчанию аргументов FastAPI).

Сборка и публикация Docker-образа

Конфигурация: ci-cd.yml

Главный производственный конвейер. Он собирает образ приложения и публикует его во внутренний реестр контейнеров Forgejo.

Триггеры

  • Push в main: при изменении файлов, исключая .forgejo/, .github/, docs/ и *.md.
  • Push тегов v*: например, v0.1.4.
  • Workflow Dispatch: ручной запуск из веб-интерфейса с возможностью указать произвольный тег (custom_tag).

Этапы выполнения

1. Подготовка окружения

  • Используется self-hosted раннер с поддержкой Docker.
  • Настраивается Docker Buildx для оптимизированной сборки.
  • Выполняется вход в реестр git.maydayoffice.kz с использованием секрета REGISTRY_TOKEN.

2. Извлечение метаданных

  • Версия приложения извлекается из поля version в файле pyproject.toml.
  • Этот номер передается в Dockerfile как ARG APP_VERSION для корректной маркировки образа (OCI labels).

3. Генерация тегов

Действие docker/metadata-action формирует список тегов для публикации:

  • Если собрано из тега (например, v0.1.4) → тег 0.1.4.
  • Если собрано из ветки main → тег latest.
  • При ручном запуске с параметром custom_tag → добавляется этот тег.

4. Сборка и пуш

  • Действие docker/build-push-action выполняет сборку контекста.
  • Включено кэширование слоев (cache-from: type=gha, cache-to: type=gha,mode=max), что значительно ускоряет повторные сборки.
  • Образ публикуется сразу в реестр (push: true).

Особенности Dockerfile

Файл Dockerfile настроен следующим образом:

  • Базовый образ: nvidia/cuda:13.3.1-runtime-ubuntu24.04.
  • Модели не включаются в образ (чтобы не раздувать его размер). Они монтируются в контейнер во время запуска (см. Установка и запуск).
  • Перед финализацией образа выполняются юнит-тесты (pytest), что гарантирует работоспособность собираемого артефакта.

Автоматическая генерация документации (Wiki)

Конфигурация: wiki-gen.yml

Этот конвейер использует внешний инструмент wiki-gen для создания структурированной документации на основе исходного кода.

Триггеры

  • Push тегов v*: документация регенерируется только при релизе, чтобы избежать лишних затрат на LLM-вызовы при каждой коммитте.
  • Workflow Dispatch: возможность принудительно обновить вики вручную.

Процесс работы

  1. Checkout основного репозитория: код gigaam-asr-server.
  2. Checkout генератора: отдельное действие клонирует репозиторий maydayoffice/wiki-gen в папку .wiki-gen/.
    • Важно: папка .wiki-gen/ автоматически исключается из анализа инструментом Repomix, поэтому код самого генератора не попадает в итоговую документацию.
  3. Подготовка среды:
    • Создается виртуальное окружение Python (venv).
    • Устанавливаются зависимости генератора (litellm, python-slugify).
  4. Генерация:
    • Запускается скрипт generate_wiki.py.
    • Инструмент упаковывает исходники (Repomix), отправляет их в LLM (через OpenAI-совместимый эндпоинт) и получает Markdown-страницы.
    • Язык генерации задан как ru (русский).
  5. Публикация:
    • Сгенерированные страницы пушатся в скрытый wiki-репозиторий Forgejo (.wiki.git) с использованием токена WIKI_TOKEN.

Необходимые секреты и переменные

Для работы этого конвейера в настройках репозитория должны быть определены:

  • secrets.WIKI_TOKEN: Personal Access Token (PAT) с правом записи в wiki.
  • secrets.WIKI_API_KEY: ключ доступа к LLM-сервису.
  • vars.WIKI_LLM_MODEL: название модели.
  • vars.WIKI_API_BASE: URL API LLM-сервиса.

Результатом работы является актуальная техническая документация, доступная на странице Wiki проекта.

Схема взаимодействия

graph TD
    Commit[Коммит в main или тег v*] --> Trigger{Тип события}
    
    Trigger -->|Pull Request| Lint[Lint Workflow]
    Lint --> Ruff[Ruff Check]
    Ruff --> Report[Отчет в PR]
    
    Trigger -->|Push main / Tag / Manual| Build[Build & Push Workflow]
    Build --> Checkout[Checkout Code]
    Checkout --> BuildX[Setup Buildx]
    BuildX --> Login[Login to Registry]
    Login --> Meta[Extract Version & Tags]
    Meta --> DockerBuild[Docker Build & Push]
    DockerBuild --> Registry[Forgejo Container Registry]
    
    Trigger -->|Tag v* / Manual| Wiki[Wiki Gen Workflow]
    Wiki --> FetchGen[Fetch wiki-gen tool]
    FetchGen --> Pack[Pack Source with Repomix]
    Pack --> LLMCall[LLM Generation]
    LLMCall --> SyncWiki[Sync to Wiki Repo]
    SyncWiki --> Docs[Project Documentation]

Рекомендации по использованию

  1. Версионирование: Используйте семантическое версионирование для тегов (например, v0.1.5). Это обеспечит корректную публикацию образа с понятным номером версии и обновление документации.
  2. Обновление зависимостей: Проект поддерживает Renovate (renovate.json). Автоматические PR для обновления зависимостей пройдут через конвейер Lint и, после слияния, запустят сборку нового образа.
  3. Проверка образа: После успешного прохождения конвейера Build and Push убедитесь, что новый тег появился в реестре: 
    docker pull git.maydayoffice.kz/maydayoffice/gigaam-asr-server:<новая_версия>
  4. Документация: Если вы внесли значительные изменения в архитектуру или API, рекомендуется вручную запустить конвейер Generate AI Wiki (Workflow Dispatch), чтобы обновить справку, даже если тег еще не был создан.