docs(cuda): описаны установка extra и проверка Windows DLL

2026-09-21 22:33:51 +03:00
1 parent 99ed5ed92f
commit 453b5d9dfa
@@ -8,7 +8,7 @@ transcribe meeting.mp4
 ```
 - **Полностью локально** — данные не покидают машину
- **Авто-ускорение** — NVIDIA CUDA при наличии GPU, иначе ONNX на CPU
+- **ONNX на CPU по умолчанию** — CUDA и OpenVINO включаются явно
 - **Батч-режим** — обработка нескольких файлов за один вызов
 - **Разделение говорящих** — локальная диаризация по флагу `--diarize`
 - **Из проводника Windows** — пункт Transcribe в меню «Отправить» ([установка](#контекстное-меню-проводника-windows))
@@ -50,18 +50,16 @@ transcribe --install-menu
 Подробнее — в разделе [контекстное меню проводника](#контекстное-меню-проводника-windows).
-**4. Ускорение (ставится автоматически):**
+**4. Выбор исполнения:**
- **NVIDIA CUDA** (GPU): если есть GPU — транскрипция в 5-10× быстрее
+- По умолчанию используется ONNX с GigaAM RNN-T на CPU, независимо от наличия
-  - **Windows**: `winget install -e --id Nvidia.CUDA --version 12.9` (от администратора), перезапустить терминал
+  NVIDIA. Эта модель понимает только русскую речь.
-  - **Linux / WSL2**: работает из коробки (нужен только драйвер: `nvidia-smi`)
+- Для других языков выбирайте Whisper явно:
- **Без NVIDIA GPU**: автоматически используется ONNX с GigaAM RNN-T на CPU.
+  `--device openvino-cpu --model medium` на x86 или `--device cpu --model medium`.
-  Эта модель понимает только русскую речь
+- OpenVINO для Intel GPU или x86 CPU доступен через `--device openvino`,
- **Другие языки без NVIDIA**: выбирайте Whisper явно —
+  `--device openvino-gpu` или `--device openvino-cpu`.
-  `--device openvino-cpu --model medium` на x86 или `--device cpu --model medium`
+- Для NVIDIA установите дополнительные библиотеки и выберите CUDA явно:
-  на любой платформе
+  [подключение CUDA](#подключение-cuda).
 - **OpenVINO** для Intel GPU или x86 CPU остаётся доступен через явный
  `--device openvino`, `--device openvino-gpu` или `--device openvino-cpu`
 **5. Готово:**
@@ -132,17 +130,73 @@ HuggingFace Hub использует симлинки для экономии м
 </details>
 ## Подключение CUDA
 Обычная установка не требует NVIDIA-пакетов. Extra `cuda` добавляет cuBLAS
 в окружение приложения на Linux/WSL x86_64 и Windows x64. Полный системный
 CUDA Toolkit и ручная правка системного PATH для этого пути не нужны.
 Совместимые GPU и драйвер NVIDIA необходимы отдельно: extra не устанавливает
 драйвер и не исправляет несовместимость старой видеокарты.
 Для установки из Git или подключения CUDA к уже установленной программе:
 ```bash
 uv tool install --python 3.13 --force "local-transcriber[cuda] @ git+https://git.dementev.space/ddmitry/local-transcriber.git"
 ```
 Из клона репозитория:
 ```bash
 uv tool install --python 3.13 --force ".[cuda]"
 ```
 Для локальной разработки:
 ```bash
 uv sync --extra cuda
 uv run --extra cuda transcribe meeting.mp4 --device cuda
 ```
 После установки extra выберите CUDA при запуске:
 ```bash
 transcribe meeting.mp4 --device cuda
 ```
 Либо задайте в `.transcriber.toml`:
 ```toml
 device = "cuda"
 ```
 Установка extra сама по себе не меняет `auto`: он всегда использует ONNX CPU.
 Явная CUDA при ошибке завершает обработку с исходной причиной и подсказкой,
 без молчаливого перехода на CPU. В батче ошибка учитывается для каждого файла.
 На Windows нужен также [Visual C++ Runtime x64](https://aka.ms/vs/17/release/vc_redist.x64.exe).
 Состав DLL проверен для закреплённых версий CTranslate2 и cuBLAS;
 реальный прогон нового пути на Windows без Toolkit пока не выполнен.
 Подробности и ограничения проверки — [ADR-001](docs/adr/001-cuda-bootstrap.md).
 При обновлении из старой установки:
 - Для CPU повторите обычную команду `uv tool install` с `--force` без `[cuda]`.
  В окружении разработки выполните `uv sync` — прежняя обязательная cuBLAS будет удалена.
 - Для CUDA повторите соответствующую команду выше. Старый автоматический выбор
  по `nvidia-smi` больше не действует; сохраните `device = "cuda"` в конфиге
  либо передавайте `--device cuda`.
 ## Использование
 ```bash
-# Простой запуск (CUDA medium или ONNX GigaAM RNN-T, язык ru)
+# Простой запуск (ONNX GigaAM RNN-T на CPU, язык ru)
 transcribe meeting.mp4
 # Указать язык
-transcribe lecture.mp3 --language en
+transcribe lecture.mp3 --device cpu --model medium --language en
 # Максимальное качество на NVIDIA GPU
-transcribe podcast.wav --model large-v3 --compute-type float16
+transcribe podcast.wav --device cuda --model large-v3 --compute-type float16
 # Максимальное качество на Intel GPU
 transcribe podcast.wav --model large-v3 --device openvino-gpu
@@ -243,7 +297,7 @@ transcribe --uninstall-menu
 | Опция | Сокращение | По умолчанию | Описание |
 |-------|-----------|-------------|----------|
 | `--model` | `-m` | medium (CUDA) / gigaam-v3-e2e-rnnt (ONNX) | Модель распознавания |
-| `--language` | `-l` | `ru` | Язык (ru, en, auto и др.); автоматический профиль без NVIDIA понимает только русский |
+| `--language` | `-l` | `ru` | Язык (ru, en, auto и др.); автоматический профиль понимает только русский |
 | `--output` | `-o` | `<файл>-transcript.md` | Путь к выходному файлу |
 | `--device` | `-d` | `auto` | Устройство (auto, cpu, cuda, openvino, openvino-gpu, openvino-cpu, onnx) |
 | `--compute-type` | — | float16 (CUDA) / int8 (ONNX/OpenVINO) / float32 (CPU) | Тип вычислений |
@@ -260,7 +314,7 @@ transcribe --uninstall-menu
 | CPU через ONNX | ✅ авто | ✅ авто | ✅ авто |
 | OpenVINO (x86 CPU) | ✅ явно | — | ✅ явно |
 | OpenVINO (Intel GPU) | ✅ явно | — | ✅ явно |
-| GPU (NVIDIA) | ✅ авто | — | ✅ (нужен CUDA 12) |
+| GPU (NVIDIA) | extra + явно (x86_64) | — | extra + явно (x64; прогон без Toolkit ожидается) |
 Данные по macOS основаны на доступности пакетов onnxruntime: прогонов на этой
 платформе не было.
@@ -269,9 +323,9 @@ transcribe --uninstall-menu
 <summary>Linux / WSL2</summary>
 - **Intel GPU** (Arc, встроенная графика) работает из коробки через OpenVINO
- **NVIDIA GPU** работает из коробки — cuBLAS ставится автоматически как зависимость
+- **NVIDIA GPU**: [extra `cuda` и явный выбор](#подключение-cuda), отдельно совместимый драйвер
- Нужен только драйвер NVIDIA (проверка: `nvidia-smi`)
+- `nvidia-smi` проверяет наличие драйвера, но не доказывает совместимость GPU с runtime
- На ARM (aarch64) cuBLAS через pip недоступен — нужен системный CUDA toolkit
+- CUDA extra на ARM (aarch64) этим проектом не поддерживается
 </details>
@@ -288,13 +342,9 @@ transcribe --uninstall-menu
 - CPU работает из коробки
 - **Intel GPU** (Arc, встроенная графика) работает из коробки через OpenVINO
- Для **NVIDIA GPU** нужен **CUDA 12** (ctranslate2 4.7 не совместим с CUDA 11 и 13):
+- **NVIDIA GPU**: [extra `cuda` и явный выбор](#подключение-cuda), отдельно совместимый драйвер
-  ```
+- Требуется Visual C++ Runtime x64; системный CUDA Toolkit не нужен для extra
-  winget install -e --id Nvidia.CUDA --version 12.9
+- Реальная транскрипция с extra без Toolkit пока не проверена на Windows
  ```
  > `winget install` требует запуска от имени администратора (elevated terminal).
  > `uv tool install` работает без админа (ставит в пользовательскую директорию).
 - После установки CUDA перезапустите терминал
 </details>
@@ -318,8 +368,8 @@ diarize = true
 `--diarize` и `--no-diarize` позволяют переопределить `diarize` из конфига для
 отдельного запуска.
-При `device = "auto"` выбирается CUDA, если доступен `nvidia-smi`, иначе ONNX.
+При `device = "auto"` всегда выбирается ONNX CPU, даже если доступны
-Явный `device` из CLI или конфига отключает этот автоматический выбор.
+`nvidia-smi` и extra `cuda`. Другие варианты выбираются явно из CLI или конфига.
 Каталоги моделей различаются между бэкендами, поэтому при закреплении `model`
 в конфиге рекомендуется явно закрепить и совместимый `device`. То же с языком:
 автоматический ONNX-профиль рассчитан на русскую речь, а для остальных языков
@@ -336,9 +386,9 @@ diarize = true
 ## Модели и GPU
 Рекомендации:
- **По умолчанию без CUDA:** ONNX `gigaam-v3-e2e-rnnt` — читаемый русский текст с
+- **По умолчанию:** ONNX `gigaam-v3-e2e-rnnt` — читаемый русский текст с
  пунктуацией почти без потери скорости относительно сырого `gigaam-v3`
- **Макс. качество (NVIDIA):** `large-v3` + `--compute-type float16`
+- **Макс. качество (NVIDIA):** `--device cuda --model large-v3 --compute-type float16`
 - **Макс. качество (Intel GPU):** `large-v3` + `--device openvino-gpu`
 - **Макс. скорость CPU (русский):** `--device onnx --model gigaam-v3` (17-29× RTF, без пунктуации; рекомендуется LLM-нормализация терминов после)
 - **Быстрый OpenVINO с низким WER:** `--device openvino-cpu --model large-v3-turbo --compute-type int8` (7,2× RTFx на контрольном Intel CPU; пунктуация может быть слабой)
@@ -49,7 +49,7 @@ transcribe <путь_к_файлу> [опции]
  --output, -o      Путь к выходному файлу
                    По умолчанию: <input_stem>-transcript.md
  --device, -d      Устройство (auto|cpu|cuda|onnx|openvino|openvino-gpu|openvino-cpu)
-                    По умолчанию: auto (CUDA при наличии, иначе ONNX CPU)
+                    По умолчанию: auto (всегда ONNX CPU)
  --compute-type    Тип вычислений
                    По умолчанию: float16 (CUDA) / int8 (ONNX)
  --verbose, -v     Подробный вывод (прогресс сегментов)
@@ -103,7 +103,7 @@ transcribe <путь_к_файлу> [опции]
 |---------------------------|---------------------------------------|
 | RTX 3060 + large-v3       | ~10-15x (1 час аудио ≈ 4-6 мин)      |
 | RTX 4050 + large-v3       | ~12-18x (1 час аудио ≈ 3-5 мин)      |
-| Quadro M3000M + large-v3  | ~3-5x (1 час аудио ≈ 12-20 мин)      |
+| Quadro M3000M + CUDA     | Не поддерживается текущей сборкой; см. [совместимость](gpu.md#совместимость-gpu) |
 | CPU + ONNX GigaAM RNN-T   | ~10-14x (1 час аудио ≈ 4-6 мин)      |
 | CPU + OpenVINO Turbo INT8 | ~7-10x (1 час аудио ≈ 6-9 мин)       |
 | CPU (modern) + large-v3   | ~0.5-1x (1 час аудио ≈ 60-120 мин)   |
@@ -115,7 +115,7 @@ transcribe <путь_к_файлу> [опции]
 |-------------------|-------|--------------------------|----------------------------|-------------------------|
 | RTX 3060          | 6 GB  | ✅                        | ✅ (впритык)                | int8 — безопасный выбор |
 | RTX 4050          | 6 GB  | ✅                        | ✅ (впритык)                | int8 — безопасный выбор |
-| Quadro M3000M     | 4 GB  | ✅                        | ⚠️ может OOM               | int8 обязательно        |
+| Quadro M3000M     | 4 GB  | ❌                        | ❌                         | ONNX CPU или OpenVINO   |
 | Без GPU           | —     | ONNX GigaAM INT8         | —                          | auto выбирает ONNX      |
 Device-aware дефолты выбирают `float16` для CUDA и `int8` для ONNX/OpenVINO.
@@ -123,7 +123,7 @@ Device-aware дефолты выбирают `float16` для CUDA и `int8` д
 ### 4.2. Требования к окружению
 - Python ≥ 3.13
- Для GPU: Linux/WSL2 — cuBLAS из nvidia-cublas-cu12 (ставится автоматически через `uv sync`); Windows — системный CUDA toolkit (см. ADR-001)
+- Для NVIDIA GPU на Linux/WSL x86_64 и Windows x64: совместимый драйвер, extra `cuda` и явный выбор CUDA (см. ADR-001); Windows также требует Visual C++ Runtime x64
 - Дисковое пространство для моделей: зависит от выбранного backend и модели
 - Выходные файлы: UTF-8 (явная кодировка при записи)
@@ -177,9 +177,9 @@ local-transcriber/
 | Качество распознавания русского текста | Среднее | large-v3 хорошо справляется с ru; при проблемах — попробовать `--language ru` вместо auto |
 | Нет разделения по спикерам | Низкое | Осознанно выведено за скоуп MVP; добавление diarization (pyannote.audio) — возможное расширение |
 | Первый запуск: долгая загрузка модели | Низкое | Прогресс-бар при скачивании; модели кешируются в `~/.cache/huggingface/` |
-| CUDA несовместимость на Windows | Среднее | Автоматический fallback на CPU + предупреждение; в README — инструкция по CUDA |
+| CUDA несовместимость на Windows | Среднее | Явная CUDA сохраняет причину ошибки; пользователь выбирает CPU или исправляет окружение по README |
 | Большие файлы (>2 часов) | Среднее | Учитывать память выбранного backend; чанкование рассматривается отдельно |
-| OOM на GPU с 4 GB VRAM | Среднее | CUDA использует float16; при OOM — fallback на CPU с предупреждением или явный более лёгкий профиль |
+| OOM на GPU с 4 GB VRAM | Среднее | CUDA использует float16; при OOM явной CUDA — ошибка с подсказкой выбрать меньшую модель или CPU |
 | Файл без речи (тишина, музыка, шум) | Низкое | Создаётся транскрипт с шапкой метаданных и `*Речь не обнаружена.*` в теле + предупреждение в stderr |
 ## 7. Вне скоупа MVP
@@ -1,78 +1,129 @@
-# ADR-001: Preload libcublas из pip-пакета для GPU на Linux/WSL2
+# ADR-001: Необязательная CUDA и загрузка cuBLAS из окружения
-**Статус**: Принято
+**Статус**: Принято; пересмотр обязательной cuBLAS от 2026-03-18
 **Дата**: 2026-03-18
 **Обновлено**: 2026-09-21, задача [#2](https://git.dementev.space/ddmitry/local-transcriber/issues/2)
 ## Контекст
-ctranslate2 (backend faster-whisper) в runtime делает `dlopen("libcublas.so.12")`,
+CTranslate2 загружает cuBLAS динамически и не поставляет её в своём wheel.
-но не бандлит эту библиотеку в свой wheel — ожидает её в системе.
+Прежняя обязательная зависимость добавляла около 581 MB скачивания на Linux
-Без установленного CUDA toolkit `uv run transcribe --device cuda` падает с ошибкой.
+x86_64, даже если пользователь работал только через ONNX CPU.
 Наличие `nvidia-smi` доказывает наличие утилиты драйвера, но не совместимость GPU
 с runtime. Автоматический выбор CUDA мог приводить к ошибке на старом GPU.
-Ключевые факты:
+Прежнее утверждение о недоступности Windows wheel `nvidia-cublas-cu12` было
- `libcuda.so.1` приходит от NVIDIA driver (всегда есть, если GPU есть)
+ошибочным: такой wheel есть и для закреплённой версии 12.9.1.4. Следовательно,
- `libcublas.so.12` отсутствует в wheel ctranslate2 на обеих платформах
+системный CUDA Toolkit не должен быть обязательным способом подключения Windows.
 - **cuDNN не нужен** — в `libctranslate2.so` ноль символов cudnn (проверено `nm -D` и `strings`)
 - На Windows ctranslate2 делает `os.add_dll_directory` в своём `__init__.py`,
  но только для DLL внутри пакета; `cublas64_12.dll` тоже не бандлится
 ## Решение
-### nvidia-cublas-cu12 как pip-зависимость
+CUDA подключается через extra `cuda` на Linux/WSL x86_64 и Windows x64.
 Драйвер NVIDIA остаётся внешним требованием; Windows также требует Visual C++
 Runtime x64. Установка extra не включает CUDA: пользователь выбирает её через
 CLI или TOML. `auto` всегда выбирает ONNX CPU, ASR и VAD получают явный
 `CPUExecutionProvider`. Команды установки и обновления — в
 [README](../../README.md#подключение-cuda).
-В `pyproject.toml`:
+CTranslate2 4.8.1 и cuBLAS 12.9.1.4 закреплены в `pyproject.toml`, чтобы
-```
+установка через `uv tool` и из клона использовала проверенное сочетание.
-"nvidia-cublas-cu12>=12.4; sys_platform == 'linux' and platform_machine == 'x86_64'"
+В cuBLAS 12.9.2.10 появилась дополнительная зависимость NVRTC. Обновление
-```
+версий требует повторной проверки библиотек и bootstrap; одного обновления
 lock-файла недостаточно.
-Нижняя граница `>=12.4` — ctranslate2 собран с CUDA 12.4. Пакет доступен только
+### Linux: preload по полному пути
 для Linux x86_64 (на Windows и macOS не устанавливается по platform marker).
-### ctypes.CDLL preload вместо LD_LIBRARY_PATH
+`_cuda_bootstrap.py` загружает `libcublas.so.12` через `ctypes.CDLL` с
 `RTLD_GLOBAL`. Линкер затем разрешает запрос CTranslate2 по soname.
 Изменение `LD_LIBRARY_PATH` внутри процесса не решает задачу: glibc кеширует
 пути поиска. Путь optional-пакета определяется через `nvidia.cublas.__path__`,
 что поддерживает namespace package без `__file__`.
-`_cuda_bootstrap.py` загружает `libcublas.so.12` по полному пути через
+### Windows: регистрация каталога и preload DLL
 `ctypes.CDLL(path, mode=RTLD_GLOBAL)` **до** первого `import ctranslate2`.
-Почему не `os.environ["LD_LIBRARY_PATH"]`: на Linux/glibc динамический линкер (`ld.so`)
+Bootstrap регистрирует `nvidia/cublas/bin` через `os.add_dll_directory`, затем
-кеширует пути поиска при старте процесса и **не перечитывает** `LD_LIBRARY_PATH`
+загружает по абсолютным путям сначала `cublasLt64_12.dll`, затем
-из environ в рамках уже запущенного процесса.
+`cublas64_12.dll`. Handles библиотек и регистрации каталога хранятся до
 завершения процесса. Повторный вызов не загружает их заново. Это обеспечивает
 доступность уже загруженных DLL для динамического загрузчика CTranslate2 и
 не требует изменения системного PATH.
-Почему `RTLD_GLOBAL`: без этого флага символы cublas не видны другим `.so`,
+Bootstrap вызывается только при создании CUDA-модели, до локального импорта
-загруженным позже (в т.ч. `libctranslate2.so`).
+`WhisperModel`. Если CTranslate2 ранее импортирован для декодирования аудио,
 preload всё равно выполняется до создания CUDA-модели. CPU-путь bootstrap не
 вызывает. Отсутствие optional-пакета безопасно: системная cuBLAS всё ещё может
 обслужить явно выбранную CUDA. Ошибка загрузки найденной Windows DLL сохраняется.
-Динамический линкер кеширует загруженные библиотеки по soname — когда ctranslate2
+### Ошибки и явный выбор
 потом вызовет `dlopen("libcublas.so.12")`, линкер вернёт уже загруженный handle.
-### strict_device для явного --device
+Явный `device` из CLI или TOML передаёт `strict_device=True` при загрузке и
 транскрипции. CUDA не заменяется молча на CPU. Подсказки различают отсутствие
 библиотек, проблемы драйвера, несовместимость GPU/runtime и нехватку памяти;
 исходное сообщение сохраняется. Неизвестная ошибка не получает произвольный
 совет установить Toolkit. Это одинаково для одного файла и батча.
-`--device cuda` / `--device cpu` → `strict_device=True` → CUDA-ошибка = raise, без fallback.
+Прежний механизм fallback оркестратора при `strict_device=False` сохранён
-`--device auto` → `strict_device=False` → текущее поведение с fallback на CPU.
+для существующих программных callers. Автоматический CLI-путь теперь ONNX,
 поэтому он не попадает в CUDA fallback.
-Мотивация: silent fallback для часового файла = 60 минут вместо 5.
+## Проверка зависимостей Windows
-## Последствия и tradeoffs
+Статическая проверка 2026-09-21: скачаны wheels из PyPI, проверены SHA-256,
 для DLL/PYD прочитаны PE imports через `objdump -p` и строки динамической
 загрузки. Модели распознавания не скачивались.
-**~400 MB на CPU-only Linux x86_64**: nvidia-cublas-cu12 ставится на все Linux x86_64,
+- `ctranslate2-4.8.1-cp313-cp313-win_amd64.whl`, SHA-256
-включая машины без GPU. Bootstrap при этом preload'ит libcublas (overhead ~1 ms),
+  `d52499f05a60a791aeadee28d609efa130142f376d1ea76b2b1c593bb01f8827`.
-но она не используется, т.к. ctranslate2 не получит запрос на CUDA device.
+  `ctranslate2.dll` содержит имена `cublas64_12.dll` и `nvcuda.dll`;
  ссылок на cuDNN и динамическую cudart в этой DLL не обнаружено.
  В wheel есть `cudnn64_9.dll`, но её наличие не означает использование
  cuDNN проверенной рабочей DLL. OpenMP DLL поставляется внутри wheel;
  импорты MSVCP/VCRUNTIME требуют Visual C++ Runtime.
 - `nvidia_cublas_cu12-12.9.1.4-py3-none-win_amd64.whl`, SHA-256
  `1e5fee10662e6e52bd71dec533fbbd4971bb70a5f24f3bc3793e5c2e9dc640bf`.
  DLL находятся в `nvidia/cublas/bin`. cuBLAS импортирует cuBLAS Lt и
  KERNEL32; cuBLAS Lt импортирует KERNEL32. `nvblas64_12.dll` не требуется
  проверенному пути CTranslate2.
-Альтернатива — `[project.optional-dependencies]` + `uv sync --extra cuda`,
+Основания: [CTranslate2 4.8.1 на PyPI](https://pypi.org/project/ctranslate2/4.8.1/#files),
-но тогда теряется zero-config UX. Для v1 оставляем как обязательную зависимость.
+[cuBLAS 12.9.1.4 на PyPI](https://pypi.org/project/nvidia-cublas-cu12/12.9.1.4/#files),
 [загрузчик CTranslate2](https://github.com/OpenNMT/CTranslate2/blob/v4.8.1/python/ctranslate2/__init__.py),
 [метаданные cuBLAS 12.9.2.10](https://pypi.org/pypi/nvidia-cublas-cu12/12.9.2.10/json).
-**Windows GPU**: nvidia-cublas-cu12 недоступен как pip-пакет для Windows.
+Это обоснование состава extra для конкретных wheels, а не подтверждение
-Единственный путь — системный CUDA toolkit (`choco install cuda` / `winget install -e --id Nvidia.CUDA`).
+транскрипции на Windows GPU. Реальный прогон Windows x64 с драйвером и extra,
-CLI выводит эту подсказку при CUDA-ошибке на `sys.platform == "win32"`.
+без Toolkit и ручной правки PATH, **не выполнен**. Linux-тесты с подменой
 Windows API не заменяют такую проверку.
-**Namespace package**: `nvidia.cublas` — namespace package (`__file__` is `None`),
+## Проверка поставки и поведения
 для определения директории используется `__path__[0]`, а не `__file__`.
-## Отклонённые альтернативы
+На Linux выполнены `uv run pytest`: 500 passed, 2 skipped. Пропуски —
 Windows-only кодировка OEM и интеграционный bootstrap без optional-пакета.
 До удаления cuBLAS интеграционный тест Linux bootstrap проходил.
 Обычный `uv sync --locked` удаляет прежнюю обязательную cuBLAS;
 `uv sync --extra cuda --locked --dry-run` возвращает её в план установки.
-| Альтернатива | Почему отклонена |
+Метаданные собранного wheel проверены для 12 сочетаний платформы, архитектуры
-|---|---|
+и extra. Полное разрешение зависимостей wheel через `uv pip compile` для Linux
-| `nvidia-cudnn-cu12` в зависимостях | ctranslate2 не использует cuDNN — ноль символов, проверено через `nm -D` |
+и Windows, с extra и без, подтверждает отсутствие NVIDIA-пакетов в обычной
-| Self-reexec с `LD_LIBRARY_PATH` | ctypes.CDLL решает задачу без перезапуска процесса; self-reexec создаёт проблемы с сигналами, tty, fd |
+установке и наличие только cuBLAS 12.9.1.4 при выборе extra.
-| `os.environ["LD_LIBRARY_PATH"] += ...` | glibc кеширует пути при старте, не перечитывает environ |
+
-| `DeviceResolution` dataclass + `resolve_device()` | Один `bool strict_device` решает ту же задачу проще |
+Формы `uv tool install` для клона, клона с extra и именованной Git-зависимости
-| ctranslate2 preflight (`get_supported_compute_types`) | Латентность; try/catch при загрузке модели не хуже |
+с extra проверены в отдельном временном каталоге tools. Для проверки самой
-| Bootstrap console_scripts entrypoint | Не нужен — достаточно вызова в начале `transcriber.py` |
+команды зависимости были исключены; их разрешение проверено отдельно выше.
 Git-транспорт проверялся через локальный репозиторий и ветку реализации,
 а не через ещё не опубликованную ветку на сервере. Версия uv — 0.12.17.
 ## Последствия и альтернативы
 - Обычная установка не требует NVIDIA-пакетов. FasterWhisper CPU сохраняется.
 - Дополнительные библиотеки скачиваются только по выбору пользователя.
 - Единый extra заменяет требование установить полный Toolkit на Windows;
  существующая системная установка библиотек остаётся допустимой.
 - Отклонено сохранение обязательной cuBLAS ради готовности CUDA сразу после
  установки: это увеличивает CPU-установку и не решает несовместимость GPU.
 - Отклонено автоматическое включение CUDA по драйверу или extra: установка
  библиотек не должна менять движок и модель по умолчанию.
 - Перезапуск процесса с `LD_LIBRARY_PATH` не нужен; явная загрузка библиотек
  решает проблему без изменения обработки сигналов и файловых дескрипторов.
 - CUDA extra на Windows ARM64, Linux ARM и macOS в эту задачу не входит.
@@ -2,7 +2,7 @@
 **Статус**: Принято
 **Дата**: 2026-03-21
-**Обновлено**: 2026-08-12
+**Обновлено**: 2026-09-21
 ## Контекст
@@ -32,8 +32,9 @@ Protocol вместо ABC — бэкенды не наследуются, дос
 ### Ленивые импорты
 Бэкенды импортируются только при выборе — `get_backend(device)` делает import внутри.
-Импорт faster-whisper запускает CUDA bootstrap (~1ms), импорт openvino-genai загружает ~50MB
+CUDA bootstrap вызывается только при создании CUDA-модели (см. ADR-001).
-shared libraries. Ни то, ни другое не должно происходить, если бэкенд не выбран.
+Импорт openvino-genai загружает ~50MB shared libraries и не должен происходить,
 если бэкенд не выбран.
 ### Device как селектор бэкенда
@@ -41,7 +42,7 @@ shared libraries. Ни то, ни другое не должно происхо
 - `cuda`, `cpu` → FasterWhisperBackend
 - `openvino` → OpenVINOBackend
 - `onnx` → OnnxAsrBackend
- `auto` → CUDA при наличии `nvidia-smi`, иначе ONNX на CPU
+- `auto` → ONNX на CPU независимо от `nvidia-smi` и установки extra
 ### load_model() — единственный владелец pipeline
@@ -54,7 +55,7 @@ CLI не вызывает ensure_model_available отдельно — это у
 Fallback живёт в `transcriber.py` (оркестратор), не в бэкендах:
 - CUDA ошибка → CPU (FasterWhisper)
 - OpenVINO ошибка → CPU (FasterWhisper)
- `strict_device=True` (явный `--device`) → ошибка без fallback
+- `strict_device=True` (явный device из CLI или TOML) → ошибка без fallback
 При fallback в батч-режиме обновляются model, backend, model_path и actual_device
 через TranscribeFileResult — следующий файл использует правильный бэкенд.
@@ -76,8 +77,8 @@ OpenVINO модели предквантизированы (int8/fp16), compute_
 ### Зависимости бэкендов по умолчанию
 faster-whisper, onnx-asr/onnxruntime и openvino-genai ставятся вместе. Модели
-скачиваются только для активного бэкенда. CUDA (`nvidia-cublas-cu12`) остаётся
+скачиваются только для активного бэкенда. cuBLAS подключается через extra `cuda`
-conditional для Linux x86_64. OpenVINO — conditional для x86_64/AMD64, кроме
+для Linux/WSL x86_64 и Windows x64 (см. ADR-001). OpenVINO — conditional для x86_64/AMD64, кроме
 macOS; ONNX обеспечивает автоматический CPU-путь на остальных платформах.
 ## Последствия
@@ -102,10 +102,12 @@ Mm-hmm-редукция и иностранные вставки **не обна
 ## Решение
 **Принять onnx-asr как CPU-бэкенд автоматического профиля.
-GigaAM v3 E2E RNN-T — модель по умолчанию на машинах без CUDA.**
+GigaAM v3 E2E RNN-T — модель автоматического профиля на всех машинах.**
-Порядок `--device auto`: CUDA при наличии `nvidia-smi`, иначе ONNX. OpenVINO и
+С 2026-09-21 `--device auto` всегда выбирает ONNX CPU; для ASR и VAD явно
-FasterWhisper CPU остаются доступными через явный CLI-аргумент или конфиг.
+передаётся `CPUExecutionProvider`, независимо от доступных providers. CUDA,
 OpenVINO и FasterWhisper CPU доступны через явный CLI-аргумент или конфиг.
 Подключение CUDA описано в [ADR-001](001-cuda-bootstrap.md).
 GigaAM понимает только русскую речь, поэтому для остальных языков автоматический
 профиль не годится — нужен явный Whisper. Несовместимый язык работу не
@@ -2,7 +2,7 @@
 ## Режимы `--device`
- `auto` (по умолчанию) — CUDA при наличии `nvidia-smi`, иначе ONNX на CPU
+- `auto` (по умолчанию) — всегда ONNX на CPU
 - `cuda` — строго NVIDIA GPU, ошибка если недоступен
 - `openvino` — авто-выбор OpenVINO GPU или CPU
 - `openvino-gpu` — строго Intel GPU через OpenVINO
@@ -13,8 +13,8 @@
 | Оборудование | Рекомендуемый `--device` | Бэкенд | Ожидаемая скорость |
 |---|---|---|---|
-| NVIDIA GPU (6+ GB VRAM) | `auto` / `cuda` | faster-whisper (CTranslate2) | 7-19x реалтайм |
+| NVIDIA GPU (6+ GB VRAM) | `cuda` + extra | faster-whisper (CTranslate2) | 7-19x реалтайм |
-| Любой CPU без NVIDIA | `auto` / `onnx` | ONNX GigaAM RNN-T | 10-14x реалтайм* |
+| Любой CPU | `auto` / `onnx` | ONNX GigaAM RNN-T | 10-14x реалтайм* |
 | Intel Arc iGPU / dGPU | `openvino-gpu` | OpenVINO GenAI (GPU) | TBD |
 | Intel/AMD x86 CPU | `openvino-cpu` | OpenVINO GenAI (CPU) | 3-10x реалтайм* |
 | Любой CPU, FasterWhisper | `cpu` | faster-whisper (CTranslate2) | ~1.5x реалтайм |
@@ -22,7 +22,7 @@
 \* По результатам контрольных прогонов на Intel и AMD CPU. Реальная скорость
 зависит от CPU, модели и записи.
-Автоматический профиль без NVIDIA рассчитан на русскую речь: GigaAM других
+Автоматический профиль рассчитан на русскую речь: GigaAM других
 языков не понимает. Для них берите Whisper — `openvino-cpu` на x86 или `cpu`
 на любой платформе.
@@ -211,22 +211,16 @@ SMT/Hyper-Threading не помогает — 16 потоков на 8-ядер
 ## Настройка по платформам
-### Linux / WSL2 (x86_64)
+Для Linux/WSL x86_64 и Windows x64 используется один extra `cuda` и явный
 выбор `--device cuda` либо `device = "cuda"` в TOML. Команды установки из Git,
 клона и для разработки приведены в [README](../README.md#подключение-cuda).
 Обычный запуск всегда использует ONNX CPU, независимо от драйвера и extra.
-Библиотека cuBLAS ставится автоматически (зависимость `nvidia-cublas-cu12` подтягивается при установке).
+Драйвер NVIDIA устанавливается отдельно. Полный системный CUDA Toolkit не
-Дополнительных шагов не требуется.
+нужен для пути через extra; на Windows требуется Visual C++ Runtime x64.
-
+Состав Windows DLL проверен статически; реальная транскрипция без Toolkit
-> На ARM (aarch64) cuBLAS через pip недоступен — нужен системный CUDA toolkit.
+пока не проверена. Версии и границы проверки — [ADR-001](adr/001-cuda-bootstrap.md).
-
+CUDA extra для ARM в этой задаче не поддерживается.
 ### Windows
 Нужен системный **CUDA 12** (ctranslate2 4.7 не совместим с CUDA 11 и 13):
 ```bash
 winget install -e --id Nvidia.CUDA --version 12.9   # требует запуска от имени администратора
 ```
 После установки перезапустите терминал.
 ## Совместимость GPU
@@ -331,14 +325,19 @@ threshold не помогла — проблема inherent для модели
 Убедитесь, что `nvidia-smi` возвращает информацию о GPU. Драйвер NVIDIA предоставляет `libcuda.so.1`,
 без которого CUDA не работает — его нельзя поставить через pip.
-### Windows: ошибка при загрузке модели на GPU
+### Отсутствующие библиотеки и несовместимый GPU
-GPU на Windows требует **CUDA 12** (ctranslate2 4.7 не совместим с CUDA 11 и 13). Установите:
+При отсутствии cuBLAS подключите extra в том окружении, откуда запускается
-```bash
+программа, по [инструкции README](../README.md#подключение-cuda).
-winget install -e --id Nvidia.CUDA --version 12.9   # требует запуска от имени администратора
+На Windows ошибка загрузки DLL может также означать отсутствие Visual C++ Runtime.
-```
+
-После установки перезапустите терминал.
+`no kernel image` / `invalid device function` означают несовместимость GPU
 с выбранной сборкой runtime. Установка extra её не исправит. Ошибки драйвера
 требуют проверки драйвера; нехватка VRAM — меньшей модели или явного выбора CPU.
 Исходная ошибка сохраняется. CLI/TOML с явной CUDA не переходят молча на CPU
 ни при загрузке, ни при распознавании.
 ### ARM (aarch64)
-cuBLAS через pip недоступен на ARM — нужен системный CUDA toolkit.
+CUDA extra не поддерживается проектом на этой архитектуре. Наличие отдельных
 NVIDIA wheels для ARM само по себе не подтверждает рабочий путь транскрипции.
@@ -1,6 +1,8 @@
 # Владение выполнением транскрипции
-**Статус:** согласовано для постановки задач. Реализация не начата.
+**Статус:** согласовано. Правила выбора исполнения и optional CUDA реализованы
 в #2; рефакторинг владения выполнением не начат. Windows GPU-прогон без Toolkit
 остаётся невыполненным (см. ADR-001).
 ## Зачем
@@ -14,11 +16,11 @@
 отдельно. Это увеличивает interface: caller должен знать порядок вызовов
 и поддерживать согласованность значений.
-`device` одновременно обозначает движок и аппаратное исполнение. Значение
+`device` одновременно обозначает движок и аппаратное исполнение. До #2 значение
-`onnx` выбирает adapter, но не закрепляет CPU: установленный `onnx-asr 0.12.0`
+`onnx` выбирало adapter, но не закрепляло CPU: `onnx-asr` по умолчанию использует
-по умолчанию использует доступные execution providers. При этом CLI безусловно
+доступные execution providers, хотя CLI писал `ONNX (CPU)`. В #2 для ASR и VAD
-пишет `ONNX (CPU)`. Параметр `cpu_threads` принимается ONNX adapter, но не
+закреплён CPU provider. Параметр `cpu_threads` всё ещё принимается ONNX adapter,
-используется при загрузке ASR и VAD.
+но не используется при загрузке ASR и VAD.
 ## Согласованные ограничения
@@ -72,7 +74,9 @@ model/backend/path/device. Locality — изменения загрузки и
 ## Выбор исполнения и ошибки
 Ручное включение CUDA состоит из двух явных действий: установки зависимостей
-и выбора CUDA через CLI либо TOML. CUDA не участвует
+и выбора CUDA через CLI либо TOML. Extra `cuda` поддерживает Linux/WSL x86_64
 и Windows x64 без обязательного системного Toolkit; совместимый драйвер
 устанавливается отдельно. CUDA не участвует
 в `auto`, даже если найден `nvidia-smi` или установлены её библиотеки.
 Так установка драйвера не меняет движок и модель по умолчанию.
@@ -121,7 +125,8 @@ Mock-тесты не подтверждают ускорение или совм
 ## Документация и прежние решения
 README должен различать обычную установку и подключение CUDA: дополнительные
-зависимости Linux/WSL, требования Windows, явный запуск, настройку TOML
+зависимости через один extra на Linux/WSL x86_64 и Windows x64, внешние
 требования драйвера и Visual C++ Runtime, явный запуск, настройку TOML
 и диагностику отсутствующих библиотек или несовместимого железа. Команды
 установки из клона и через `uv tool` проверяются при реализации. CUDA extra
 оформляется отдельным изменением, чтобы поставку можно было проверить