CVC - Classification of Voice Commands

Мини-сервис для классификации голосовых команд (SetFit). Обучает модель на малом датасете и классифицирует текстовые команды. Создан для использования в проекте навыка для Sber Salute.

Стек технологий

Категория	Технологии
ML	SetFit, PyTorch, sentence-transformers, Hugging Face Hub, scikit-learn, datasets
API	FastAPI, Uvicorn
Данные	SQLite, pandas, PyYAML
Интерфейсы	REST API, CLI (Python)
Инфраструктура	Docker
Разработка	pytest, ruff, httpx

Оглавление

Раздел	Содержание
Стек технологий	ML, API, данные, инфраструктура
Быстрый старт	Запуск за 3 шага (Docker)
Установка и запуск	CPU / CUDA / ROCm, Docker, локально
Использование	CLI, Python-клиент, библиотека
Конфигурация и API	config.yaml, эндпоинты
Данные	Формат датасета, параметры обучения
Разработка	Тесты, линт, структура проекта
CI/CD	Пайплайн и ссылка на настройку
Лицензия	MIT

Быстрый старт

1. Создайте .env с HF_TOKEN и HF_REPO_ID (токен, модель — принять условия).

2. Соберите и запустите контейнер:

   docker-compose up -d

3. Сервер: http://localhost:20001. Документация API: http://localhost:20001/docs

Остановка: docker-compose down.

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

Требование: Hugging Face

Модель google/embeddinggemma-300M требует авторизации. В корне проекта создайте .env:

HF_TOKEN=your_token_here
HF_REPO_ID=your-username/model-name

Варианты установки

Вариант	Команда	Примечание
CPU	pip install -r requirements-docker.txt	По умолчанию
NVIDIA CUDA	Сначала PyTorch с CUDA, затем pip install -r requirements-cuda.txt	CUDA 12.4+, PyTorch 2.6+
AMD ROCm	Драйвер AMD PyTorch Edition, Python 3.12, затем pip install -r requirements-rocm.txt	Только Windows

Docker

• Образ — CPU-only. Для GPU запускайте приложение локально (CUDA/ROCm).
• Запуск: docker-compose up -d. Volumes: ./models, ./checkpoints, ./cache/huggingface, ./db.

Локальный запуск

python -m commands_classifier.cli serve

Опции: --host, --port, --config. БД создаётся при первом запуске, данные из data/ или CSV из config.yaml.

Использование

CLI

После запуска сервера (Docker или локально):

python -m commands_classifier.client predict --text "равняйся" [--show-confidence]
python -m commands_classifier.client predict --file commands.txt
python -m commands_classifier.client train [--batch-size 32 --iterations 30]
python -m commands_classifier.client train-status
python -m commands_classifier.client examples list
python -m commands_classifier.client examples add --text "команда" --command "label"
python -m commands_classifier.client examples delete --id 1
python -m commands_classifier.client health
python -m commands_classifier.client metrics
python -m commands_classifier.client reset
python -m commands_classifier.client load-from-hf [--repo-id "username/model-name"]
python -m commands_classifier.client load-from-hf-status
python -m commands_classifier.client command-feedback   # репорт «исправить команду» из RDS-2P-Salute

По умолчанию клиент подключается к http://localhost:20001 (флаг --url для другого адреса).

Python

• API-клиент: CVCApiClient(base_url) — методы predict, predict_batch, embed, train, get_training_status, get_examples, add_example, delete_example, health, metrics, reset, load_from_hf, get_load_from_hf_status, get_command_feedback.
• Библиотека (без сервера): CommandsClassifier() + load_dataset(path) → train(texts, labels), predict(text), save(path), load(path).

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

config.yaml

Основные параметры:

server:
  host: "0.0.0.0"
  port: 20001

model:
  path: "models/my_model"
  name: "google/embeddinggemma-300M"
  confidence_threshold: 0.5
  cache_dir: "models/.cache"

database:
  path: "db/training_data.db"
  csv_migration_path: "data"

# Опционально: URL репорта «исправить команду» из RDS-2P-Salute (по умолчанию: rds-2p-salute-app:8000)
# command_feedback:
#   url: "http://rds-2p-salute-app:8000/v1/admin/command-feedback"

training:
  iterations: 20
  epochs: 1
  batch_size: 32
  learning_rate: 2e-5

Эндпоинты (API v1)

Все ручки версионированы префиксом /v1.

Метод	Путь	Описание
POST	/v1/embed	Эмбеддинги (TEI)
GET	/v1/health	Проверка работоспособности
GET	/v1/metrics	Счётчики примеров и статус обучения
POST	/v1/predict	Классификация одного текста
POST	/v1/predict/batch	Batch классификация
POST	/v1/train	Запуск обучения (фоновый)
GET	/v1/train/status	Статус обучения
GET, POST, DELETE	/v1/examples, /v1/examples/{id}	Обучающие примеры
POST	/v1/reset	Сброс обучения (удаление модели, пометка примеров как необученных)
POST	/v1/load_from_hf	Загрузка модели с Hugging Face
GET	/v1/load_from_hf/status	Статус загрузки
GET	/v1/command-feedback	Репорт «исправить команду» из RDS-2P-Salute (прокси)

Интерактивная документация: http://localhost:20001/docs. Устройство (CPU/CUDA/ROCm) определяется при запуске автоматически.

Данные

Формат датасета

Для миграции при старте — CSV или JSON в data/ или путь в config.yaml (database.csv_migration_path).

CSV: колонки text, command.

JSON: список объектов {"text": "...", "command": "..."} или объект с массивами {"text": [...], "command": [...]}.

Параметры обучения

--iterations, --epochs, --batch-size, --learning-rate. Значения по умолчанию — в config.yaml (секция training).

Разработка

Тесты и линт

Используется образ cvc-dev (docker-compose.dev.yml):

docker compose -f docker-compose.yml build cvc-api
docker compose -f docker-compose.yml -f docker-compose.dev.yml build cvc-dev

docker compose -f docker-compose.yml -f docker-compose.dev.yml run --rm cvc-dev ruff check .
docker compose -f docker-compose.yml -f docker-compose.dev.yml run --rm cvc-dev pytest tests/ -v --tb=short --cov=commands_classifier --cov-report=term-missing

Структура проекта

CVC/
├── config.yaml
├── requirements-docker.txt | requirements-cuda.txt | requirements-rocm.txt
├── commands_classifier/     # Код: model, dataset, db, cli, client, api/
├── data/                    # CSV/JSON для миграции
├── models/                  # Сохранённые модели
├── db/                      # SQLite (training_data.db)
├── tests/
└── docs/                    # cicd_setup.md и др.

CI/CD

Пайплайн .github/workflows/deploy.yml:

• При каждом push — тесты (линт + pytest в Docker).
• Job Train and Publish — при метке [retrain] в сообщении коммита или при ручном запуске (Actions → Run workflow). Секреты: HF_TOKEN, HF_REPO_ID.
• Уведомления в Telegram при успешной и неуспешной сборке (опционально: секреты TELEGRAM_TOKEN, TELEGRAM_TO). Подробнее: docs/telegram_notifications.md.

Подробная настройка (self-hosted runner, GPU, секреты): docs/cicd_setup.md.

Лицензия

MIT

Проект создан с использованием нейросетей.