Хаттама AI

Локальное приложение для расшифровки встреч, подготовки протоколов и проверки поручений. FastAPI + SQLite + браузерный интерфейс. По умолчанию распознавание аудио и анализ текста выполняются через отдельно настроенные OpenAI-совместимые API.

Быстрый запуск

Python 3.11–3.12. В текущем окружении .venv уже установлено. Заполните адреса, модели и ключи в backend/.env по LOCAL_API.md.

powershell -ExecutionPolicy Bypass -File scripts/run.ps1

Откройте http://127.0.0.1:8000. Один сервер, один worker. Остановка — Ctrl+C в терминале. Cloudflare для текущего сценария не используется. Записи и документы хранятся локально; аудио и текст передаются выбранным API-провайдерам.

Для новой установки:

powershell -ExecutionPolicy Bypass -File scripts/setup.ps1 -Python python
Copy-Item backend/.env.example backend/.env
# Заполните backend/.env, затем запустите scripts/run.ps1.

Linux: bash scripts/setup.sh, создайте backend/.env, затем bash scripts/run.sh. Для аудио-API Whisper-модель не нужна. FFmpeg используется для подготовки файлов; при отсутствии системного бинарника доступен imageio-ffmpeg. Для PDF на Linux нужен DejaVu Sans или кириллический TTF через PDF_FONT.

Режимы ИИ

Два независимых выбора при загрузке:

Этап	По умолчанию	Локальная альтернатива
Распознавание аудио	API: ASR_API_URL / ASR_API_MODEL / ASR_API_KEY	faster-whisper, WHISPER_MODEL
Анализ текста	HYBRID: LLM_HYBRID_URL / LLM_HYBRID_MODEL / LLM_API_KEY	LOCAL — локальный LLM; RULES — правила

Передача аудио и текста подтверждается отдельно. Автоматического переключения провайдеров нет. Ключи находятся только в backend/.env, не в браузере и не в Git. API распознавания должен поддерживать verbose_json и сегменты с временными метками. Подробная настройка, ограничения и восстановление: LOCAL_API.md.

Локальная модель small уже установлена в текущем окружении. Для новой установки офлайн-распознавания: .venv/Scripts/python.exe scripts/download_model.py --model small. LOCAL требует отдельного локального LLM по LLM_LOCAL_URL; RULES не требует LLM.

Проверки

.venv/Scripts/python.exe -m pytest -q
npm.cmd run check --prefix frontend
npm.cmd test --prefix frontend

Тесты API используют имитацию провайдера и не расходуют ключи или квоту. Результаты и границы проверки: VALIDATION.md. GitHub Actions запускает backend и Chromium после push/PR. Локальные тесты качества ASR с отдельной моделью и разрешёнными речевыми записями выполняются дополнительно. Браузерный runner использует собственный временный порт и данные; он не подключается к рабочему приложению и не читает ключи из backend/.env.

Жұмыс жолы

1. WAV/MP3/MP4, атау, кездесудің нақты күні/уақыты, IANA белдеуі және қатысушыларды енгізіңіз. Уақыт — жүктеу уақыты емес.
2. Файл кездейсоқ серверлік атпен сақталады. FFmpeg толық аудионы mono 16 kHz WAV-қа декодтайды; шектен ұзақ/бұзылған файл қабылданбайды. Әдепкі шек 250 MB және 4 сағат.
3. SQLite кезегі → декодтау → faster-whisper → қолмен сөйлеуші белгілеу → талдау → тексеру. UI тек нақты орындалатын кезеңдерді көрсетеді.
4. Сол жақта аудио және сегменттер; оң жақта түйін, шешімдер/ұсыныстар, тапсырмалар. Дәлел батырмасы аудионы тиісті уақытқа жылжытып, сегментті белгілейді.
5. Мәтінді, сөйлеушіні, сегмент тілін, түйінді, шешімдерді, сұрақтар мен тапсырмаларды өңдеңіз. Тіл автоматты анықталған файл тілімен толтырылмайды: бастапқы мәні unknown.
6. Тапсырмада орындаушы, күтілетін нәтиже немесе мерзім айтылмаса, «Жазбада көрсетілмеген» деп растаңыз. Дәлелдерді тексеріп, тапсырманы растаңыз. Дереккөз өзгерсе, барлық туынды нәтиже қайта тексеруді қажет етеді. Өзгерген дәйексөзді сегмент тізімінен қайта қосып жаңартыңыз.
7. Өзгерістерді сақтаңыз; одан кейін тексерілген өрістерді растаңыз және нұсқаны бекітіңіз. Бекіту — immutable snapshot, электрондық қолтаңба немесе тексерілген тұлға емес.
8. Кейінгі түзетулер — жаңа черновик. DOCX/PDF үшін ағымдағы жоба немесе нақты бекітілген нұсқаны таңдаңыз. Транскриптті экспортқа қоспауға болады.

Деректер мен қалпына келтіру

data/khattama.db, data/uploads/ жергілікті сақталады. Жеке деректер дискіде шифрланбайды; қолжетімділікті ОЖ құралдарымен шектеңіз. Қолданба нұсқалары мен аудит сол SQLite ішінде. Резервтік көшірме үшін серверді тоқтатып, data каталогын толық көшіріңіз.

Жұмыс бір background thread арқылы өңделеді. OS file lock қосарланған worker-ді, SQLite атомдық claim қайталама тапсырма алуды тежейді. Процесс өшсе, келесі іске қосылу processing жұмыстарын қайта кезекке қояды. Транскрипт дайын болса checkpoint-тен, әйтпесе ASR басынан жалғасады. ASR ішіндегі ішінара сегменттер сақталмайды. Қайта талдау бөлек candidate жасайды; қолмен түзетулер тек салыстырудан кейін айқын «Қолдану» әрекетімен ауысады, ескі мәтін аудитте қалады.

meetings_v2, versions_v2, audit_v2 кестелері қолданылады. Бұрынғы прототип кестелері өшірілмейді және v2 интерфейсіне автоматты көшірілмейді: онда кездесу күні мен дәлелдер болмаған. Ескі деректерді жаңа бекітілген нұсқа деп көрсетуге болмайды.

Талдау шектеулері

• Автоматты диаризация іске қосылмаған. backend/diarization.py ауыстырылатын интерфейс береді; қазіргі провайдер аттарды ойдан қоспайды. Сөйлеушілерді сегмент бойынша қолмен атауға болады. Бұрынғы F0 кластерлеуі сенімді диаризация ретінде қолданылмайды және алынып тасталды.
• RULES шағын командалық үлгілерді ғана қамтиды. Айдана, подготовь смету жұмаға дейін. Жоқ, дүйсенбіге ауыстырайық. бір тапсырма мен екі дәлелге біріктіріледі. Бөлек, іргелес өзгерту/жою репликалары қолданылады; қатысы белгісіз түзетулер сұрақ болып қалады. Барлық шығарылған тапсырма адам тексеруін талап етеді.
• Орындаушы сөйлеушіден алынбайды. Есімнің септік жалғауы автоматты өзгертілмейді. LLM атауы/мерзімі дәйексөзден табылмаса, өріс бос қалады.
• RU/KK апта күндері, бүгін/ертең, санмен және кейбір сөзбен берілген күн аралықтары, ISO және сандық күндер қолдау табады. «Апта соңына дейін», «келесі апта», осы күнмен сәйкес апта күні — екіұшты, нақты күні null. Барлық күн сөздік формалары қамтылмаған.
• Ұзын транскрипт сегмент бойынша бөліктерге бөлінеді, әр бөлік өңделеді. Алдыңғы тапсырмалар жинақталады; JSON мен дәйексөздер тексеріледі, ең көбі екі жауап әрекеті. Шығыс шегінен асқанда нақты қате шығады, үнсіз қысқарту жоқ. Аралық LLM бөлік checkpoint-тері сақталмайды.
• Транскрипт LLM үшін сенімсіз дерек ретінде беріледі, бірақ prompt injection-ді толық жоюға кепіл жоқ. Автоматты құрал орындау/хат жіберу жоқ; барлық қорытындыны адам бекітеді.
• Жұмыс орындалуы open / in_progress / done / cancelled. Кешігу белдеу күні бойынша есептеледі; мерзімсіз және аяқталған/жойылған тапсырмалар кешіккен емес.

Тексеру

.\.venv\Scripts\python.exe -m pytest -q
node --check frontend/app.js
node --check frontend/editor.js
node --check frontend/shared.js

Нақты орындалған тексерулер мен шектеулер: VALIDATION.md.

Тесттер мерзімдерді, RU/KK/mixed мәтіндік мысалдарды, дәлелдерді, келісімді, LOCAL URL шектеуін, қате модель/LLM-ді, кезек қалпына келуін, нұсқаларды, экспорт пен Range-ді қамтиды. Мәтіндік fixtures ASR сапасын тексермейді.

Нақты RU/KK/mixed ASR тексеру үшін samples/ru.wav, samples/kk.wav, samples/mixed.wav және бірдей атаулы .txt эталондарын өзіңіздің рұқсат етілген жазбаларыңызбен беріңіз. tests/test_audio.py үлгілер жоқ болса skip жасайды, жасанды нәтиже қоспайды. Нақты сапа тесті эталон сөздерінің қателік үлесін есептейді; автоматты нәтиже сапасына жалпы кепілдік бермейді.

Қысқа демонстрация

1. Өз жазбаңызды RULES режимінде жүктеңіз (LLM-сіз толық жергілікті жол). Күнді 2026-09-23 деп берсеңіз, «жұма» 25 қыркүйекке сәйкес келеді.
2. Өңдеу кезеңдерін көрсетіңіз. Үнсіз файлда хаттама жасалмайтынын тексеріңіз.
3. Транскрипт пен дәйексөзді тыңдап салыстырыңыз, орындаушыны сөйлеушіден бөлек тексеріңіз.
4. Тапсырманы түзетіп сақтаңыз, белгісіз өрісті растаңыз; барлық материалды тексеріп нұсқаны бекітіңіз.
5. Транскриптті өзгертіңіз: қайта тексеру қажет. Алдыңғы бекітілген DOCX/PDF өзгермейді.
6. Қайта талдаудың бөлек салыстыру нәтижесін және тапсырмалар тізілімін көрсетіңіз.

Техникалық негіздер: faster-whisper жергілікті модель, Starlette Range қолдауы.