LLM-подключения и распознавание речиLLM connections and speech recognition

1. Подключения LLM1. LLM connections

Откройте Настройки → Настройки LLM. Каждое подключение хранит тип provider, endpoint, выбранную модель и параметры доступа. Поддерживаются:Open Settings → LLM settings. Each connection stores its provider type, endpoint, selected model and access parameters. Supported connections are:

• OpenAI, Anthropic, Gemini, OpenRouter;
• Ollama иand LM Studio;
• любой совместимый с OpenAI endpoint;a custom OpenAI-compatible endpoint;
• LiteLLM Proxy — показывается в advanced-режиме.shown in advanced mode.

Запросы выполняются через общий LiteLLM runtime. Сохранение строки готового подключения сразу запускает access/catalog check. В generic profile editor кнопка проверки сначала сохраняет текущую форму и API key, затем выполняет probe — это не read-only действие. Ошибка credentials, endpoint или capability не переключает запрос на другой профиль.Requests run through the shared LiteLLM runtime. Saving a predefined connection row immediately starts an access/catalog check. In the generic profile editor, Check first saves the current form and API key and then runs the probe; it is not read-only. A credential, endpoint or capability error does not reroute the request to another profile.

Подтверждённый access/model list хранится только в текущем экземпляре connection service. После нового запуска настроенная модель может показываться как «доступ не проверен». Профильная manual model добавляется в успешный каталог, даже если provider её не перечислил. Для роли cv список фильтруется эвристикой по имени/metadata, но при отсутствии vision-кандидатов показывает весь список: наличие в combo и общий test не доказывают поддержку изображений или structured response.Verified access/model state lives only in the current connection-service instance. After a new launch, a configured model may be shown as access not verified. The profile's manual model is appended to a successful catalogue even when the provider did not list it. For the cv role, the list uses a name/metadata heuristic but falls back to the full list when no vision candidate is found; presence in the combo and a general test do not prove image or structured-response support.

2. Назначение профиля роли2. Assigning profiles to roles

Одно подключение не обязано обслуживать всю программу. Роль выбирает profile/model для конкретного контура; отдельную capability или safety policy сама роль не создаёт:One connection does not have to serve the whole product. A role selects a profile/model for a specific path; the role itself does not create a separate capability or safety policy:

• assistant — встроенный AI Assistant;the built-in AI Assistant;
• cv — CV auto-tune, планирование pipeline и Action CV/VLM;CV auto-tune, pipeline planning and Action CV/VLM;
• codegen — Screph Code;
• semantic_selection — семантический выбор элементов;semantic element selection;
• test — проверка подключения и модели.connection and model testing.

При сохранении первого profile пустые роли cv, test и semantic_selection назначаются ему автоматически; codegen — только если соответствующий UI включён. Роль assistant автоматически не заполняется. Это initial assignment, а не runtime fallback. Удаление profile очищает все роли, которые на него ссылаются.When the first profile is saved, empty cv, test and semantic_selection roles are assigned to it automatically; codegen is included only when that UI is enabled. The assistant role is not filled automatically. This is initial assignment, not runtime fallback. Deleting a profile clears every role that references it.

Если профиль роли отключён, удалён или недоступен, соответствующая операция завершается понятной ошибкой. Resolution order: явно переданные profile/model, затем role profile/model, затем default model самого profile. Проверьте роль отдельно даже тогда, когда само подключение успешно проходит общий test.If a role profile is disabled, deleted or unavailable, the related operation fails clearly. Resolution order is explicit request profile/model, then role profile/model, then the profile's default model. Test the role separately even when the base connection passes its general check.

3. Ключи, локальная работа и передача данных3. Keys, local operation and data transfer

• LLM и current voice API keys сохраняются через system keyring; в Windows-сборке это Windows Credential Manager с service name Screph. Обычный profile payload в ScrephData/settings_modules/settings.json содержит provider kind, model, endpoint, timeout и roles, но не значение API key.LLM and current voice API keys are stored through the system keyring; in the Windows build this is Windows Credential Manager under service name Screph. The ordinary profile payload in ScrephData/settings_modules/settings.json contains provider kind, model, endpoint, timeout and roles, but not the API-key value.
• Если keyring недоступен, сохранение секрета завершается ошибкой: plaintext fallback в обычный settings JSON не используется. Environment variables остаются явным runtime-source и могут наследоваться дочерними процессами.If the keyring is unavailable, saving a secret fails: there is no plaintext fallback to ordinary settings JSON. Environment variables remain an explicit runtime source and may be inherited by child processes.
• Ollama и LM Studio позволяют оставить запросы на локальной машине, если сервис и модель действительно запущены локально.Ollama and LM Studio can keep requests on the local machine when the service and model are actually running locally.
• Облачный профиль может передавать prompt, выбранный context и изображения provider. Конкретный состав зависит от функции и её privacy/attachment settings.A cloud profile may send the prompt, selected context and images to its provider. The exact payload depends on the capability and its privacy/attachment settings.
• В AI Assistant отправка изображений и артефактов выключена по умолчанию. У Action CV default block_unredacted блокирует provider call; roi_only закрашивает всё вне ROI, а allow_unredacted является явным разрешением исходного кадра. Prompt также включает type/time/source действия, key/button и координаты при наличии, ROI hint, frame metadata/hashes, response contract и каталог разрешённых методов.In AI Assistant, image and artifact sharing is off by default. Action CV defaults to block_unredacted, which blocks the provider call; roi_only paints over everything outside the ROI, while allow_unredacted explicitly permits the original frame. Its prompt also includes action type, time and source, key or button and coordinates when present, the ROI hint, frame metadata and hashes, the response contract and the allowed method catalogue.

Когда общий LLM request действительно получает image_path, Screph читает файл, преобразует его в RGB JPEG, уменьшает максимум до 1024×1024 с quality 85 и отправляет base64 data URL с detail=low. Для CV/image request profile timeout заменяется transport timeout в 120 минут; число retries остаётся request/profile setting и передаётся LiteLLM.When a shared LLM request actually receives an image_path, Screph reads the file, converts it to RGB JPEG, downsizes it to at most 1024×1024 at quality 85 and sends a base64 data URL with detail=low. For a CV/image request, the profile timeout is replaced by a 120-minute transport timeout; retry count still comes from the request/profile setting and is passed to LiteLLM.

Успешные ответы общего runtime добавляют локальную строку в ScrephData/llm/usage_events.jsonl: feature, profile, model, tokens, рассчитанную cost, latency и status. Prompt/response text туда не пишется. Автоматического retention и кнопки очистки нет; исключения до создания response обычно в этот файл не попадают, поэтому это не полный billing/error ledger.Successful shared-runtime responses append a local row to ScrephData/llm/usage_events.jsonl containing feature, profile, model, tokens, calculated cost, latency and status. Prompt/response text is not written there. There is no automatic retention or clear button, and exceptions raised before a response exists are generally absent, so it is not a complete billing or error ledger.

Где хранятся секреты и как их удалить →Where secrets are stored and how to remove them →

4. Распознавание речи4. Speech recognition

Откройте Настройки → Распознавание речи. Раздел содержит вкладки настройки и теста; выбранный recognizer используется голосовыми аннотациями. Реализованы provider-aware adapters для:Open Settings → Speech recognition. The section includes settings and test tabs; voice annotations use the selected recognizer. Provider-aware adapters are implemented for:

• Vosk — локальные batch и streaming режимы; нужны voice.local, микрофон и подходящая языковая модель.local batch and streaming modes; requires voice.local, a microphone and a matching language model.
• Yandex — SDK, streaming или async в зависимости от доступной конфигурации.SDK, streaming or async depending on the available configuration.
• Google Cloud — явно выбранное облачное распознавание и его credentials/capabilities.explicitly selected cloud recognition and its credentials/capabilities.
• OpenAI — распознавание через настроенный provider path.recognition through its configured provider path.

Не каждый provider поддерживает каждый режим. Loader проверяет выбранную capability и показывает unavailable, если streaming/async/backend path для этой конфигурации не реализован или недоступен; он не подменяет provider локальным Vosk.Not every provider supports every mode. The loader checks the selected capability and reports it as unavailable when a streaming/async/backend path is not implemented or available for that configuration; it does not replace the provider with local Vosk.

5. Настроить и проверить голос5. Configure and test voice

1. Выберите recognizer и его режим. Для Vosk сначала подготовьте voice.local на вкладке зависимостей.Select a recognizer and mode. For Vosk, prepare voice.local on the Dependencies tab first.
2. Укажите модель, регион, endpoint или credentials, которые требует выбранный provider.Enter the model, region, endpoint or credentials required by that provider.
3. Разрешите приложению доступ к микрофону в Windows и выберите правильное input device.Allow microphone access in Windows and select the correct input device.
4. На вкладке Тест распознавания запишите короткую фразу и проверьте transcript, язык и задержку.On the Recognition test tab, record a short phrase and verify transcript, language and latency.
5. Только после теста включайте голосовую аннотацию в рабочем проекте.Enable voice annotation in a working project only after that test.

6. Быстрая диагностика6. Quick diagnostics

• Модель не появилась:Model is not listed: проверьте endpoint и connection test; для локального сервиса убедитесь, что он запущен.check the endpoint and connection test; for a local service, verify that it is running.
• CV видит другое подключение:CV uses another connection: проверьте назначение роли cv, а не только последний отредактированный профиль.check the cv role assignment, not just the last edited profile.
• Vosk не запускается:Vosk does not start: перепроверьте voice.local, путь к языковой модели и microphone permission.re-probe voice.local, the language-model path and microphone permission.
• Cloud speech возвращает capability error:Cloud speech returns a capability error: выберите поддерживаемый режим для provider; ошибка не означает автоматического перехода в batch или на другой сервис.select a supported mode for the provider; the error does not mean Screph switched to batch or another service.