📚 Groq Spell Checker для NVDA

Полная документация и руководство пользователя

Версия 1.0

📖 Обзор дополнения

Groq Spell Checker — это профессиональное дополнение для NVDA (NonVisual Desktop Access), которое использует искусственный интеллект от Groq для проверки орфографии и пунктуации текста, а также для голосового ввода с высокой точностью распознавания.

Дополнение предназначено для пользователей, которым требуется:

• Быстрая проверка орфографии в выделенном тексте
• Точное распознавание речи для голосового ввода
• Минимальное вмешательство в исходный текст при коррекции
• Поддержка нескольких языков для распознавания речи
• Интеграция с современными AI-моделями через Groq API

Важная особенность: Дополнение исправляет ТОЛЬКО орфографию и пунктуацию, не изменяя слова, их порядок или смысл текста. Это строгий корректор, а не редактор контента.

⚙️ Требования и совместимость

Системные требования:

• Операционная система: Windows 10 или новее
• NVDA: Версия 2023.1 или новее
• Интернет-соединение: Обязательно для работы с API Groq
• Микрофон: Для использования функции голосового ввода
• Память: Не менее 50 МБ свободного места

Требования к учетной записи:

• Действующий API ключ от Groq (бесплатный или платный)
• Учетная запись на console.groq.com

Внимание: Дополнение использует внешние API сервисы. При отсутствии интернет-соединения функции проверки орфографии и голосового ввода работать не будут.

📦 Установка дополнения

Шаг 1: Скачайте файл дополнения (.nvda-addon) с официального сайта или репозитория

Шаг 2: Откройте NVDA и перейдите в меню:

NVDA → Инструменты → Установить дополнение

Шаг 3: Выберите скачанный файл дополнения и нажмите "Открыть"

Шаг 4: Подтвердите установку и перезапустите NVDA при запросе

Шаг 5: После перезапуска дополнение будет готово к настройке

Совет: Перед установкой закройте все программы, которые могут блокировать доступ NVDA к файловой системе.

🔑 Настройка API ключа Groq

Для работы дополнения необходим API ключ от Groq. Вот как его получить:

Шаг 1: Перейдите на сайт console.groq.com

Шаг 2: Зарегистрируйтесь или войдите в свою учетную запись

Шаг 3: В меню выберите "API Keys" или "Ключи API"

Шаг 4: Нажмите "Create API Key" или "Создать API ключ"

Шаг 5: Введите название ключа (например, "NVDA Spell Checker")

Шаг 6: Скопируйте сгенерированный ключ (он будет показан только один раз!)

Шаг 7: Вставьте ключ в настройках дополнения (см. раздел "Настройки")

Важно: Бесплатный тариф Groq предоставляет ограниченное количество запросов в минуту. Для интенсивного использования рассмотрите платные тарифы.

Безопасность: Никогда не делитесь своим API ключом и не публикуйте его в открытых источниках. Ключ должен быть известен только вам.

⚙️ Настройки дополнения

Для доступа к настройкам дополнения выполните:

NVDA → Настройки → Параметры → Категория "Groq Spell Checker"

Основные настройки:

Groq API ключ

Описание: Ваш персональный API ключ от Groq

Формат: Строка текста

По умолчанию: Пусто

Модель для текста

Описание: Выбор AI-модели для проверки орфографии

Доступные варианты:

• llama-3.1-8b-instant (рекомендуется, быстрая)
• llama-3.1-70b-versatile (более точная, но медленнее)
• llama-3.3-70b-versatile (самая точная)
• mixtral-8x7b-32768 (универсальная)
• gemma2-9b-it (компактная)

По умолчанию: llama-3.1-8b-instant

Строгий режим

Описание: Исправлять только явные орфографические ошибки

При включении: Исправляются только очевидные ошибки (опечатки)

При выключении: Более агрессивная коррекция с учетом контекста

По умолчанию: Включено

Настройки голосового ввода:

Включить голосовой ввод

Описание: Активация функции голосового ввода

По умолчанию: Включено

Модель для распознавания речи

Описание: Выбор модели Whisper для распознавания речи

Доступные варианты:

• whisper-large-v3-turbo (рекомендуется, быстрая и точная)
• whisper-large-v3 (высокая точность)
• whisper-large-v2 (предыдущая версия)
• whisper-medium (средняя точность)
• whisper-small (компактная)
• whisper-base (базовая)
• whisper-tiny (минимальная)

По умолчанию: whisper-large-v3-turbo

Язык распознавания

Описание: Язык для распознавания речи

Доступные языки:

Автоопределение

Русский

Английский

Испанский

Французский

Немецкий

Итальянский

Китайский

Японский

Корейский

Арабский

Турецкий

Португальский

По умолчанию: Автоопределение

Автоматически вставлять распознанный текст

Описание: Автоматическая вставка текста после распознавания

При включении: Текст сразу вставляется в текущее поле

При выключении: Текст копируется в буфер обмена

По умолчанию: Включено

Совет: Для начала используйте настройки по умолчанию. После тестирования можно настроить параметры под свои нужды.

⌨️ Назначение горячих клавиш

Для использования функций дополнения необходимо назначить горячие клавиши:

Шаг 1: Откройте настройки NVDA:

NVDA → Настройки → Жесты ввода

Шаг 2: В дереве категорий найдите "Groq Spell Checker"

Шаг 3: Разверните категорию и выберите нужную команду

Шаг 4: Нажмите "Добавить" и введите желаемую комбинацию клавиш

Шаг 5: Повторите для всех необходимых команд

Доступные команды:

Совет: Используйте комбинации с NVDA+Shift для избежания конфликтов с другими дополнениями.

🚀 Использование функций

1. Проверка орфографии

Шаг 1: Выделите текст в любом приложении (Word, браузер, блокнот)

Шаг 2: Нажмите назначенную горячую клавишу для проверки орфографии

Шаг 3: Дождитесь звукового сигнала и сообщения о начале проверки

Шаг 4: После завершения проверки исправленный текст будет скопирован в буфер обмена

Шаг 5: Вставьте исправленный текст в нужное место (Ctrl+V)

Ограничения: Максимальная длина текста для проверки — 5000 символов. Для более длинных текстов разбейте их на части.

2. Голосовой ввод

Шаг 1: Убедитесь, что микрофон подключен и настроен

Шаг 2: Перейдите в поле, куда нужно ввести текст

Шаг 3: Нажмите назначенную горячую клавишу для начала записи (прозвучит высокий тон)

Шаг 4: Начните говорить — NVDA сообщит "Запись началась. Говорите..."

Шаг 5: Нажмите ту же горячую клавишу для остановки записи (прозвучит низкий тон)

Шаг 6: Дождитесь распознавания речи — текст будет автоматически вставлен или скопирован в буфер

Примеры работы:

Совет для голосового ввода: Говорите четко, в нормальном темпе. Избегайте фонового шума. Для лучшего распознавания укажите язык в настройках, если он известен.

🔧 Устранение неполадок

Распространенные проблемы и решения:

❌ "Неверный API ключ Groq"

Причина: Неправильный или устаревший API ключ

Решение:

1. Проверьте правильность ввода ключа в настройках
2. Убедитесь, что ключ активен в консоли Groq
3. Сгенерируйте новый ключ и обновите настройки

❌ "Превышен лимит запросов"

Причина: Исчерпан лимит запросов по тарифу

Решение:

1. Подождите 1-2 минуты перед следующим запросом
2. Проверьте текущие лимиты в консоли Groq
3. Рассмотрите переход на платный тариф при частом использовании

❌ "Таймаут подключения"

Причина: Проблемы с интернет-соединением или сервером Groq

Решение:

1. Проверьте интернет-соединение
2. Попробуйте позже — возможны временные проблемы на сервере
3. Убедитесь, что брандмауэр не блокирует соединение

❌ Голосовой ввод не работает

Причина: Проблемы с микрофоном или настройками

Решение:

1. Проверьте, включен ли голосовой ввод в настройках дополнения
2. Убедитесь, что микрофон подключен и выбран как устройство записи
3. Проверьте настройки приватности Windows (доступ к микрофону)
4. Протестируйте микрофон в других приложениях

❌ "Пустой результат" после проверки

Причина: Текст слишком короткий или содержит только специальные символы

Решение:

1. Убедитесь, что выделен текст, а не пустое пространство
2. Проверьте, что текст содержит буквы, а не только цифры или символы
3. Попробуйте проверить другой текст для тестирования

Логирование ошибок:

Для диагностики сложных проблем включите расширенное логирование:

В логах NVDA ищите записи с префиксом "Groq": ERROR - Groq API error (model

llama-3.1-8b-instant): ... INFO - Starting spell check... DEBUG - Full error: traceback.format_exc()

Совет: Перед обращением за помощью соберите информацию из логов NVDA (NVDA → Инструменты → Просмотр лога).

❓ Часто задаваемые вопросы

Q: Дополнение бесплатное?

A: Да, дополнение полностью бесплатное. Однако для его работы необходим API ключ от Groq, который имеет бесплатный лимит, но также предоставляет платные тарифы для увеличения лимитов.

Q: Какие языки поддерживаются?

A: Проверка орфографии работает для многих языков, но лучше всего справляется с русским и английским. Голосовой ввод поддерживает 13 языков (см. раздел "Настройки").

Q: Сохраняется ли конфиденциальность моих данных?

A: Текст и аудио передаются на серверы Groq для обработки. Рекомендуем ознакомиться с политикой конфиденциальности Groq. Не используйте дополнение для конфиденциальной информации.

Q: Можно ли использовать дополнение офлайн?

A: Нет, дополнение требует интернет-соединения для работы с API Groq. Офлайн-функции не предусмотрены.

Q: Какой максимальный размер аудио для распознавания?

A: Максимальный размер аудиофайла — 25 МБ. Обычно это соответствует записи длиной до 10-15 минут, в зависимости от качества.

Q: Почему исправленный текст не вставляется автоматически?

A: По соображениям безопасности и контроля, исправленный текст копируется в буфер обмена. Вы можете вставить его вручную (Ctrl+V) или настроить автоматическую вставку для голосового ввода.

Q: Как сбросить настройки дополнения?

A: Удалите раздел groqSpellChecker из конфигурационного файла NVDA (nvda.ini) или используйте кнопку "Сбросить" в настройках категории.

🔬 Технические детали

Архитектура дополнения:

• Основной класс: GlobalPlugin — точка входа
• Проверка орфографии: StrictSpellChecker — основной механизм коррекции
• Голосовой ввод: VoiceInputHelper — управление записью аудио
• Потоки: SpellCheckThread и VoiceInputThread — асинхронная обработка
• Настройки: SettingsPanel — графический интерфейс настроек

Используемые API:

• Groq Chat API: https://api.groq.com/openai/v1/chat/completions
• Groq Audio API: https://api.groq.com/openai/v1/audio/transcriptions

Таймауты:

• Текстовые запросы: 30 секунд
• Аудио запросы: 120 секунд

Формат промптов:

Строгий режим: ИСПРАВЬ ТОЛЬКО ОРФОГРАФИЧЕСКИЕ ОШИБКИ И ЗНАКИ ПРЕПИНАНИЯ. НЕ

МЕНЯЙ: Слова, порядок слов, смысл текста... # Обычный режим: Исправь орфографические ошибки и пунктуацию в тексте ниже. ВАЖНО: Не меняй слова и их порядок...

📝 История изменений

Версия 1.0 (Текущая)

• Первоначальный выпуск
• Базовая проверка орфографии и пунктуации
• Голосовой ввод с поддержкой 13 языков
• Настройка моделей Groq и Whisper
• Строгий и обычный режимы коррекции
• Полная интеграция с NVDA
• Интерфейс настроек на русском языке

Планируемые обновления:

• Пакетная обработка текста
• Кэширование результатов
• Поддержка дополнительных языков
• Интеграция с облачными хранилищами
• Расширенные настройки форматирования

🆘 Поддержка и обратная связь

Если у вас возникли проблемы или есть предложения по улучшению:

• Официальный репозиторий: Проверьте Issues на GitHub
• Форум NVDA: Раздел дополнений
• Email поддержки: zloi.tg.of@gmail.com
• Документация Groq: docs.groq.com

При обращении за помощью укажите:

1. Версию NVDA
2. Версию дополнения
3. Операционную систему
4. Точное описание проблемы
5. Шаги для воспроизведения
6. Соответствующие записи из лога NVDA

© 2025 Groq Spell Checker for NVDA By Zloy Ltd. Все права защищены.

Дополнение распространяется под лицензией GNU General Public License v2.

Groq является торговой маркой Groq, Inc. NVDA является торговой маркой NV Access.