268 lines
13 KiB
Markdown
268 lines
13 KiB
Markdown
# Meeting Protocol Service — Design Spec
|
||
|
||
Сервис транскрибации аудио/видео записей встреч и автоматической генерации протоколов с использованием локальной модели Whisper и внешних LLM.
|
||
|
||
## 1. Цели и контекст
|
||
|
||
- Автоматизация создания протоколов по записям встреч (внутренних и с клиентами)
|
||
- Протоколы клиентских встреч — основа для результирующей документации по обследованию процессов
|
||
- Бесплатная локальная транскрибация (Whisper на GPU)
|
||
- Генерация протоколов через бесплатные/платные LLM API
|
||
- Веб-интерфейс + полнофункциональные боты в Telegram и Lensa
|
||
- Хранение кода и версионирование в Gitea на http://78.153.7.224:3000
|
||
|
||
## 2. Архитектура
|
||
|
||
### Подход: модульный монолит
|
||
|
||
Единый деплой с изолированными модулями, общение между которыми — через очереди задач (Celery/Redis). Каждый модуль можно выделить в отдельный сервис при необходимости.
|
||
|
||
### Модули
|
||
|
||
| Модуль | Ответственность |
|
||
|--------|----------------|
|
||
| **API** | REST endpoints, авторизация (JWT), загрузка файлов, раздача SPA |
|
||
| **Транскрибация** | Извлечение аудио (FFmpeg), транскрибация (faster-whisper на GPU) |
|
||
| **Протоколирование** | Вызов LLM, применение шаблонов промптов, экспорт DOCX/PDF/MD |
|
||
| **Мессенджеры** | Telegram бот (aiogram 3.x), Lensa бот (SDK/webhook), общий MessengerService |
|
||
|
||
### Поток обработки записи
|
||
|
||
1. Загрузка файла (web / telegram / lensa)
|
||
2. Извлечение аудио из видео (FFmpeg) — Celery task
|
||
3. Транскрибация (faster-whisper large-v3, GPU) — Celery task
|
||
4. Генерация протокола (LLM через LiteLLM) — Celery task
|
||
5. Сохранение результата, уведомление пользователя
|
||
6. Экспорт по запросу (DOCX/PDF/MD)
|
||
|
||
### Асинхронная обработка
|
||
|
||
Все тяжёлые операции (шаги 2-4) выполняются в Celery workers и не блокируют API. Пользователь получает обновления о прогрессе через polling (web) и push-уведомления (мессенджеры).
|
||
|
||
## 3. Модель данных
|
||
|
||
### User
|
||
- `id` UUID PK
|
||
- `username` str unique
|
||
- `email` str unique
|
||
- `password_hash` str
|
||
- `role` enum: admin, user (расширяемо)
|
||
- `is_active` bool
|
||
- `created_at` timestamp
|
||
|
||
### Recording
|
||
- `id` UUID PK
|
||
- `user_id` FK → User
|
||
- `title` str
|
||
- `file_path` str
|
||
- `file_size` bigint
|
||
- `duration` interval
|
||
- `format` str (mp4, webm, mp3, wav, ogg)
|
||
- `source` enum: web, telegram, lensa
|
||
- `status` enum: uploaded, processing, done, error
|
||
- `created_at` timestamp
|
||
|
||
### Transcription
|
||
- `id` UUID PK
|
||
- `recording_id` FK → Recording (1:1)
|
||
- `text` text
|
||
- `segments` JSONB (массив сегментов с таймкодами)
|
||
- `language` str
|
||
- `whisper_model` str
|
||
- `processing_time` interval
|
||
- `created_at` timestamp
|
||
|
||
### Protocol
|
||
- `id` UUID PK
|
||
- `transcription_id` FK → Transcription
|
||
- `template_id` FK → PromptTemplate
|
||
- `content` JSONB (структурированный по разделам)
|
||
- `raw_text` text
|
||
- `llm_model` str
|
||
- `status` enum: generating, done, error
|
||
- `created_at` timestamp
|
||
- `updated_at` timestamp
|
||
|
||
### PromptTemplate
|
||
- `id` UUID PK
|
||
- `name` str
|
||
- `description` str
|
||
- `type` enum: client_survey, client_intro, internal, custom
|
||
- `system_prompt` text
|
||
- `user_prompt` text
|
||
- `output_schema` JSONB (описание ожидаемых разделов)
|
||
- `is_default` bool
|
||
- `created_at` timestamp
|
||
|
||
### ExportFile
|
||
- `id` UUID PK
|
||
- `protocol_id` FK → Protocol
|
||
- `format` enum: docx, pdf, md
|
||
- `file_path` str
|
||
- `file_size` bigint
|
||
- `created_at` timestamp
|
||
|
||
### Связи
|
||
|
||
```
|
||
User 1→N Recording 1→1 Transcription 1→N Protocol 1→N ExportFile
|
||
PromptTemplate 1→N Protocol
|
||
```
|
||
|
||
## 4. Предустановленные шаблоны протоколов
|
||
|
||
### 4.1 Обследование процессов клиента
|
||
|
||
Разделы:
|
||
1. Дата, участники, тема встречи
|
||
2. Описание обследуемого процесса (задачи бизнеса, подпроцесс)
|
||
3. Текущее состояние (as-is)
|
||
4. Выявленные проблемы / узкие места
|
||
5. Договорённости и решения
|
||
6. Открытые вопросы (о которых не договорились)
|
||
7. Задачи с ответственными и сроками
|
||
8. Следующие шаги
|
||
|
||
### 4.2 Вводная встреча-знакомство с клиентом
|
||
|
||
Разделы:
|
||
1. Дата, участники, тема встречи
|
||
2. Верхнеуровневые цели клиента
|
||
3. Параметры будущего проекта
|
||
4. Бюджетные ограничения
|
||
5. Ограничения по срокам
|
||
6. Лица, принимающие решения (ЛПР)
|
||
7. Бенефициары
|
||
8. Лица, влияющие на принятие решения
|
||
9. Договорённости и решения
|
||
10. Открытые вопросы
|
||
11. Следующие шаги
|
||
|
||
### 4.3 Внутренняя рабочая встреча
|
||
|
||
Разделы:
|
||
1. Дата, участники, тема
|
||
2. Обсуждённые вопросы
|
||
3. Выявленные проблемы
|
||
4. Принятые решения
|
||
5. Открытые вопросы
|
||
6. Задачи с ответственными и сроками
|
||
7. Следующие шаги
|
||
|
||
### 4.4 Кастомный шаблон
|
||
|
||
Пользователь может создать свой шаблон с произвольными разделами и промптом через веб-интерфейс или бот.
|
||
|
||
## 5. Веб-интерфейс
|
||
|
||
### Страницы
|
||
|
||
| Страница | Функционал |
|
||
|----------|-----------|
|
||
| **Записи** | Список записей с фильтрами по источнику/дате, загрузка файлов, статус обработки |
|
||
| **Протоколы** | Просмотр, редактирование, экспорт (DOCX/PDF/MD), перегенерация с другим шаблоном |
|
||
| **Шаблоны** | Управление промптами, создание кастомных шаблонов, предпросмотр |
|
||
| **Настройки** | LLM провайдер/модель, API-ключи, retention period, очистка данных, профиль |
|
||
|
||
### Навигация
|
||
|
||
Шапка: логотип, разделы (Записи, Протоколы, Шаблоны, Настройки), индикатор занятого дискового пространства ("Занято: N ГБ"), профиль пользователя.
|
||
|
||
### Стек фронтенда
|
||
|
||
- React + TypeScript
|
||
- Vite (сборка)
|
||
- Tailwind CSS
|
||
- React Query (работа с API)
|
||
- React Router
|
||
|
||
## 6. Интеграция с мессенджерами
|
||
|
||
### Сценарий работы
|
||
|
||
1. Пользователь отправляет файл в бот
|
||
2. Бот предлагает выбрать тип протокола (inline-кнопки)
|
||
3. Бот показывает прогресс обработки
|
||
4. Бот отправляет готовый протокол + кнопки: экспорт (DOCX/PDF/MD), перегенерация, открыть в вебе
|
||
|
||
### Команды бота
|
||
|
||
**Основные:** `/start` (авторизация), `/upload` (или просто отправить файл), `/list` (записи), `/protocols` (протоколы)
|
||
|
||
**Работа с протоколами:** `/view [id]`, `/export [id] [формат]`, `/regenerate [id]`, `/templates`
|
||
|
||
**Настройки:** `/settings` (шаблон по умолчанию), `/help`, `/logout`
|
||
|
||
### Технические детали
|
||
|
||
- **Telegram** — aiogram 3.x, webhook mode через FastAPI, inline-кнопки
|
||
- **Lensa** — SDK/webhook интеграция с аналогичным интерфейсом
|
||
- **MessengerService** — общий слой абстракции, единая логика для обоих мессенджеров
|
||
- **Лимит файлов** — Telegram Bot API ограничивает 50 МБ; для больших файлов — ссылка на веб-загрузку
|
||
- **Авторизация** — привязка аккаунта мессенджера к учётной записи через `/start` (логин/пароль)
|
||
|
||
## 7. Авторизация
|
||
|
||
- Базовая: логин/пароль, JWT-токены
|
||
- Роли: admin, user (расширяемо в будущем)
|
||
- Все авторизованные пользователи видят все протоколы
|
||
- Привязка аккаунтов мессенджеров к учётной записи
|
||
- Подготовлена структура для расширения ролевой модели (поле role — enum, легко расширить)
|
||
|
||
## 8. Управление хранилищем
|
||
|
||
- **Retention policies** — настраиваемый срок хранения для записей, транскрипций и экспортов (по умолчанию: 90 дней)
|
||
- **Ручная очистка** — админ может удалить старые данные из настроек (записи + связанные файлы)
|
||
- **Автоочистка** — Celery beat задача по расписанию удаляет данные старше retention period
|
||
- **Индикатор** — в шапке навигации отображается занятое место ("Занято: N ГБ")
|
||
- **Стратегия хранения** — SSD для активных данных (ОС, Docker, БД), HDD для архива (старые записи)
|
||
|
||
## 9. Деплой
|
||
|
||
### Сервер
|
||
|
||
- **Адрес:** 78.153.7.224
|
||
- **ОС:** Windows (Docker Desktop установлен, PostgreSQL и другие сервисы уже развёрнуты)
|
||
- **CPU:** Intel i9-10900 (10 ядер, 2.8 GHz)
|
||
- **RAM:** 32 GB
|
||
- **GPU:** NVIDIA RTX 3070 Ti (8 GB VRAM)
|
||
- **Хранилище:** 1 TB SSD + 1 TB HDD
|
||
|
||
### Docker Compose — контейнеры
|
||
|
||
| Контейнер | Назначение |
|
||
|-----------|-----------|
|
||
| `app` | FastAPI + Uvicorn, API + раздача SPA, port 8000 |
|
||
| `worker` | Celery worker с GPU доступом (Whisper + LLM вызовы) |
|
||
| `beat` | Celery beat — планировщик (автоочистка, scheduled tasks) |
|
||
| `redis` | Redis 7 — брокер задач + кэш |
|
||
| `db` | PostgreSQL 16 |
|
||
| `nginx` | Reverse proxy, static files, port 80/443 |
|
||
|
||
### Распределение ресурсов
|
||
|
||
- **GPU (8 GB VRAM)** — faster-whisper large-v3 (~3 GB модель, остальное — буфер)
|
||
- **RAM** — ~4 GB PostgreSQL, ~2 GB Redis, ~4 GB FastAPI + workers, ~8 GB Whisper worker, остальное — ОС
|
||
- **CPU** — 10 ядер достаточно для параллельной работы API + воркеров
|
||
|
||
### Портативность
|
||
|
||
Архитектура на Docker Compose полностью переносима: `docker-compose.yml` + `.env` → `docker compose up -d` на любом сервере. При отсутствии GPU на целевом сервере — переключение faster-whisper на CPU-режим через переменную окружения.
|
||
|
||
### CI/CD
|
||
|
||
- Код — Gitea на http://78.153.7.224:3000
|
||
- Деплой — `docker compose up -d --build` (ручной или через Gitea webhook)
|
||
- Миграции — `alembic upgrade head` при старте контейнера `app`
|
||
|
||
## 10. Технологический стек — сводка
|
||
|
||
| Слой | Технологии |
|
||
|------|-----------|
|
||
| Backend | Python 3.11+, FastAPI, Uvicorn, Celery, Redis, SQLAlchemy, Alembic, Pydantic v2 |
|
||
| AI/ML | faster-whisper large-v3, CUDA 12 + cuDNN, FFmpeg, LiteLLM |
|
||
| Frontend | React, TypeScript, Vite, Tailwind CSS, React Query, React Router |
|
||
| Мессенджеры | aiogram 3.x (Telegram), Lensa SDK/webhook |
|
||
| Экспорт | python-docx (DOCX), WeasyPrint (PDF), Jinja2 (шаблоны) |
|
||
| Инфра | Docker, Docker Compose, NVIDIA Container Toolkit, Nginx, Gitea, Alembic |
|