Open-RealtimeASR-UI 用户说明书

简体中文 | English

1. 简介

1.1 软件概述

Open-RealtimeASR-UI（简称 ORI）是一款面向中文用户的 Windows 桌面语音听写工具，定位为 Windows 11 原生 Win+H 语音输入的开源替代方案：按下全局热键开始说话，语音经云端或本地识别引擎实时转写为文字，直接注入当前光标所在位置。

• 五大识别引擎，右键热切换——四家云端厂商（阿里云百炼 / 腾讯云 / 讯飞 / 火山引擎豆包）密钥自备 + 本地 FunASR 完全离线，切换无需重启；
• 听写链路的每个环节可调——注入方式、断句节奏、逐字上屏、打断方式、底噪校准全部可配，并为游戏、管理员权限窗口等场景做了专门适配；
• AI 能力——AI 修正、语音命令、端到端语音对话均为可选功能，默认关闭，开启后只连接您自行配置的服务。

1.2 适用环境与兼容性

说明：

• 不同引擎的可用性取决于密钥配置与网络连通性，未配置密钥的引擎默认从菜单中隐藏
• 打包版（exe）不含本地 FunASR 引擎（funasr + torch 体积过大未打包），如需离线识别请自行安装。

1.3 部署形态与使用方式

ORI 支持两种启动方式：

• 打包版（zip）：下载 Release 的 zip 解压后双击 ORI.exe 即用（_internal\ 目录须与 exe 同在）。
• 源码版：pip install -r requirements.txt 后通过 python -m asr_voice.main 或 start.bat 启动。

1.4 功能体系概览

2. 使用前说明

2.1 运行环境要求

在使用 ORI 前，建议确认当前环境满足以下基本条件：

• 操作系统为 Windows 10 / 11（桌面端）
• 具备可用的麦克风设备，且系统麦克风权限已放行
• 使用云端引擎时，具备访问对应厂商服务（阿里云 / 腾讯云 / 讯飞 / 火山引擎）的网络条件
• 使用打包版时无需 Python 环境；使用源码版时需 Python 3.10+

建议的使用环境如下：

• 安静或中等噪声环境，佩戴耳机进行听写，以屏蔽扬声器播放声音的干扰，避免误识别
• 使用全局热键的场景下，避免与系统或其他软件的全局热键冲突
• 使用 AI 修正、语音命令等依赖 LLM 的功能时，具备访问对应 API 地址的网络条件

说明：

• 不同引擎的识别精度、延迟与费用各不相同，详见第 6 章
• 部分功能需要先配置密钥或开启对应开关后方可使用

2.2 使用前准备

为保证安装与首次使用过程顺利，建议在安装前完成以下准备工作：

1. 确认系统与麦克风
   确认 Windows 版本、麦克风可用性，并在 系统 → 隐私 → 麦克风 中确认桌面应用麦克风权限已开启。
2. 准备识别引擎密钥（云端引擎）
   云端引擎需在各厂商控制台自费开通对应服务并获取密钥，各厂商基本都有一定的体验或免费额度： - 阿里云百炼：api_key（sk- 开头），从 阿里云百炼控制台 获取 - 腾讯云：secret_id + secret_key + app_id，从 腾讯云控制台 获取 - 讯飞：讯飞开放平台-实时语音转写大模型版app_id + api_key + api_secret；讯飞开放平台-实时语音转写标准版 std_app_id + std_api_key - 火山引擎：新版 api_key；旧版 app_id + access_token 火山方舟控制台
3. 准备耳机（推荐）
   扬声器外放会与麦克风形成回声干扰，建议使用耳机收听设备声音，没有也无所谓。
4. 备份重要配置
   在修改 config.yaml前，建议备份当前配置文件，便于出现问题后快速恢复。

2.3 风险提示

• 云端引擎：使用阿里云百炼 / 腾讯云 / 讯飞 / 火山引擎等云端引擎时，费用由对应厂商按各自计费规则收取；使用前请确认已开通并了解计费标准
• 剪贴板操作：开启「保留剪贴」时，识别结果会覆盖剪贴板中的图片 / 文件等内容；关闭时程序会尽量恢复剪贴板原内容，但图片 / 文件无法安全还原，会自动降级为逐字输入；「游戏模式」开启时直接覆盖剪贴板且不恢复原内容
• 逐字输入模拟键盘：simulate_keys 方式会模拟键盘按键，在部分程序（如游戏、安全软件保护的应用）中可能失效或被拦截
• 全局热键：ORI 依赖全局热键监听，部分安全软件可能拦截；热键被其他程序占用时需更换
• 麦克风常驻预热：开启 audio.warmup_capture 后，程序会持续占用麦克风（任务栏麦克风图标常亮），系统其他录音应用可能受到影响
• AI 修正 / 语音命令：会把识别文本发送到所配置的 LLM 服务（OpenAI 兼容接口），请自行评估隐私与合规风险

3. 安装与首次使用

3.1 源码方式运行

操作流程：

1. 克隆仓库并进入项目目录
2. 安装依赖：pip install -r requirements.txt
3. 启动程序：python -m asr_voice.main，或双击 start.bat

说明：

• start.bat 会自动按 python.local.bat → .venv\Scripts\python.exe → py -3 → python 的顺序查找 Python 解释器，找不到时会给出安装指引
• python.local.bat 可配置本机 Python 绝对路径（gitignored，不会提交）
• 首次运行会自动在 config\config.yaml 生成配置文件（基于 config\config.example.yaml 模板）

3.2 打包版（zip）运行

操作流程：

1. 获取 Release 的 zip（或自行构建，见下文），解压到任意目录
2. 双击解压目录中的 ORI.exe 启动（_internal\ 目录须与 exe 同在）
3. 首次启动会在 exe 同目录自动生成 config.yaml（目录不可写时退到 ~/.asr_voice\config.yaml）

自行构建方式：

build.bat  

注意：打包版目前不含本地 FunASR 引擎

3.3 本地 FunASR 引擎安装（可选）

# CPU
pip install funasr torch torchaudio

# GPU（CUDA 11.8 示例）
pip install torch torchaudio --index-url https://download.pytorch.org/whl/cu118
pip install funasr

说明：

• 模型首次使用时自动从 ModelScope 下载到 ~/.cache/modelscope/
• 程序启动即后台预热（CPU 约 3~8 秒 / GPU 约 1~3 秒），就绪后悬浮条提示
• 离线使用请提前下载 paraformer-zh-streaming 模型放入该缓存目录
• 本地引擎仅在源码版可用
• 仓库不内置、不分发模型权重 需要用户自行下载，三种方式： 1. 自动下载：留空 funasr.local_dir，首次使用时程序自动从所选渠道下载 2. 本地目录：自行下载权重后，把 funasr.local_dir 填为权重目录绝对路径（直接本地加载，不联网）

3.4 首次启动与初始化

首次启动时，建议重点确认以下内容：

• 程序正常启动，悬浮条正常显示（静默启动参数 --hidden 除外）
• 首次运行自动生成 config.yaml，位置见 12.1 节
• 未配置密钥时，程序会正常启动并提示配置密钥
• 录音热键（默认 Ctrl+G）注册成功

首次启动后通常需要进行以下基础操作：

1. 配置识别引擎密钥
   默认引擎为阿里云百炼，至少填入一个引擎的密钥（或切换到本地 FunASR）。

2. 确认麦克风设备
   在 设置 → 录音检测 中选择正确的麦克风设备（默认使用系统默认输入设备）。

3. 验证一次录音
   按下 Ctrl+G 说话，再按一次停止，确认文字成功注入目标输入框。

3.5 配置识别引擎密钥

ORI 的云端引擎密钥可通过设置界面或直接编辑配置文件两种方式写入。

方式一：设置界面（推荐）

1. 悬浮条右键 → 设置
2. 进入「引擎密钥」页
3. 展开对应引擎卡片，填入密钥
4. 点击保存

方式二：直接编辑 config.yaml

1. 设置界面右上角点击「打开配置文件」胶囊按钮（用系统默认编辑器打开）
2. 填入密钥字段并保存，程序会自动热加载

说明：

• 未配置密钥的引擎组默认从右键菜单隐藏（当前使用中的引擎组除外）
• 各引擎密钥字段与获取方式见 6.3 ~ 6.6 节

3.6 验证首次录音

首次成功配置后，建议按以下步骤完整验证一次听写流程：

1. 打开任意可输入文字的窗口（如记事本）并聚焦
2. 按 Ctrl+G 开始录音，悬浮条出现，状态点变为聆听/识别态
3. 正常语速说几句话，观察悬浮条文字预览与输入框中文字的实时上屏
4. 再按 Ctrl+G 停止，确认最终文本完整注入
5. 检查悬浮条无错误提示（橙色状态点 + 错误信息）

若过程中出现问题，请参考第 13 章故障排查。

4. 主界面说明

4.1 悬浮条布局

悬浮条由以下部分组成：

悬浮条交互：

• 左键拖动：移动窗口位置（持久化，重启后保持）
• 右下角拖动手柄：调整窗口大小（持久化）
• 右键：弹出完整功能菜单
• 极简主题：正方形悬浮窗 + 中央声纹波形 + 上方气泡文本，整窗即启停按钮

4.2 状态提示

悬浮条通过状态点与文字预览反馈程序状态：

开启 AI 修正后，每句话修正完成会出现三态提示（详见 7.6 节）。

4.3 右键菜单

右键菜单是 ORI 的主要操作入口，悬浮条与托盘共用同一份菜单。

菜单结构自上而下：

说明：

• 引擎菜单分组顺序可在 设置 → 通用设置 → 引擎排序 调整
• 未配置密钥的引擎组默认隐藏，当前引擎组始终可见

4.4 系统托盘

4.5 设置界面概览

设置界面共 8 个页面：

细节说明：

• 标题栏「打开配置文件」按钮用系统默认编辑器打开 config.yaml，保存后自动热加载
• 标题栏「还原默认」按钮把 config.yaml 恢复为出厂默认（历史记录、自定义短语与提示词版本不受影响），确认后热加载生效并关闭设置窗口
• 部分设置（如热键、主题）需重启程序后生效，界面有对应提示
• 保存机制为逐字段行级写回（保留注释），写后回读校验，失败自动回滚

5. 语音输入基础使用

5.1 开始与停止录音

按下全局热键（默认 Ctrl+G）开始录音，再按一次停止，最终文本注入当前光标位置。

一次完整的听写流程：

1. 聚焦目标输入位置（任意可输入文字的程序）
2. 按 Ctrl+G → 悬浮条出现，开始录音
3. 正常语速说话 → 中间结果逐字实时上屏
4. 再按 Ctrl+G（或静音超时 / 录音时长上限）→ 停止录音，最终文本注入

补充说明：

• 热键可在 设置 → 通用设置 → 热键 修改（需重启生效），避免与系统/其他软件冲突
• 无语音超过设定秒数自动停止（默认 10 秒，可配，0=不自动停止）
• 单次录音默认最长 60 秒强制收尾，可在 设置 → 录音检测 → 录音时长上限 修改（0=不限时）
• ASR 建连瞬时失败会自动重试 3 次（间隔 2 秒）

5.2 长按说话

默认关闭。开启方式：右键悬浮条 → 程序行为 → 长按录音，或 设置 → 通用设置 → 热键 → 长按说话。

• 录音：按住录音热键说话，松手立即停止并上屏。按住期间不会因静默自动停止 （只有 60 秒硬上限仍在）。
• 语音模式：按住对话热键才开麦克风，松手关闭。没按住时麦克风完全不上行 （Hermes 例外，见下），所以外放时 AI 的声音不会被自己的麦克风收进去， 也无需再开「半双工」。AI 正在说话时按下热键会打断它（豆包 / 阿里云支持打断； Hermes 是「说完才提交」，不适用）。
• 轻点不算录音：按下时间短于阈值（默认 300 毫秒，可在设置页调整）的轻点被 完全丢弃——不连接服务端、不上屏，因此误触不会产生任何费用。
• 悬浮条会显示「准备中」→「录音中」，可据此判断是否按上。内置主题（浅色/深色/极简） 用状态点表示，暗红=准备中、正红=录音中。
• Hermes 对话下松手后可能多等几百毫秒才出结果（本地判停需要一点静音时间）。 Hermes 的识别在本机进行，所以按住期间照常逐字上屏；只是这一句要等你松手之后 才会发给 AI。
• 开启长按后，「半双工」开关不再生效（职责已被长按闸门覆盖）。

5.3 实时上屏与逐字同步

「说到哪，字就到哪」是 ORI 的核心体验：中间结果逐字实时写入输入框，新增内容直接追加，ASR 回头修正才退格重打。

相关配置项：

逻辑锁说明：AI 修正启用、注入方式为剪贴输入、游戏模式启用、或语音命令启用时，「逐字同步」会被强制视为关闭（对应锁解除后自动恢复）。原因：

• 剪贴输入每次注入都覆盖剪贴板，无法支持中间结果增量追加
• AI 修正需要对完整句子做后台修正，中间结果上屏会造成退格重打的跳动
• 语音命令句的中间帧可能因同音误识别残留在输入框
• 游戏模式强制整段粘贴注入，与中间结果增量追加不兼容

5.4 文本注入方式

ORI 提供两种把识别结果送进目标程序的方式，右键菜单「注入逻辑」切换。

相关行为：

• 游戏模式：右键菜单「注入逻辑 ▸ 游戏模式」开启后，识别结果强制经剪贴板粘贴注入，不做任何降级、粘贴后不恢复剪贴板——用于逐字输入无效的游戏等自绘输入框（此类输入框不读无扫描码的合成键击）。开启期间「注入方式」锁定为剪贴输入、「逐字同步」锁定关闭（关闭游戏模式后自动恢复原状态）；对连粘贴都不支持的目标程序无效。若目标游戏以管理员运行（常见于带反作弊的客户端），本程序也需以管理员运行才能注入，否则合成按键会被 Windows 静默丢弃——检测到时悬浮条会自动提示；开启游戏模式时若当前不是管理员，还会主动询问是否以管理员身份重启程序（选「立即提权」即弹 UAC，确认后由提权实例接管，游戏模式保持开启；选「暂不」或 15 秒不理会则仅收起询问）。游戏模式会随配置保留到下次启动，而提权只活一个进程生命周期——故重启后若游戏模式仍开且本次未提权，启动时会再问一次同样的询问（静默启动不弹）；不想每次被问可在设置「通用设置」开「永久以管理员身份启动」
• 保留剪贴 = 开：识别结果留在剪贴板，Ctrl+V 可随时重复粘贴；但会覆盖剪贴板中的图片 / 文件
• 保留剪贴 = 关（默认）：粘贴后自动恢复剪贴板原内容；剪贴板里是图片 / 文件（无法安全还原）时自动降级为逐字输入
• 粘贴延迟：写入剪贴板后等待多久再模拟粘贴（默认 50ms，10~1000ms 可调），部分程序响应慢可适当加大

5.5 打断与取消

说错了可以反悔：录音中触发打断操作，本次未上屏的内容全部丢弃。

两种打断方式（右键菜单「打断方式」，可同时开启）：

5.6 VAD 语音检测与底噪校准

ORI 使用能量检测（VAD）自动断句：说话停顿超过设定时长算一句结束；不说话超过设定秒数自动停止录音。

VAD 相关参数（设置 → 录音检测 → 语音检测）：

底噪自动校准：每次录音开头约 1 秒自动校准环境底噪，底噪高时自动上调静音阈值，避免 VAD 卡死——在嘈杂环境下尤其有用，无需手动反复调阈值。

5.7 麦克风常驻预热

开启麦克风常驻后，麦克风一直"热着"——按下热键前约 400ms 的声音也会被带上，开口的第一个字不会被吞掉。

相关机制：

• 麦克风常驻预热（audio.warmup_capture，默认关）：后台预开采集流 + 预滚缓冲（保留按下热键前约 400ms 音频）
• ASR 后台建连：握手期间的音频先存着，连上后补发
• 代价：任务栏麦克风图标常亮（程序在持续占用麦克风）；关闭更省电，但可能吞首字

5.8 暂停播放与全局静音

录音期间可以自动中断后台音频，防止麦克风拾入背景声、干扰说话，停止录音自动恢复。两个开关均默认关闭，可单独或同时使用。

• 暂停播放：右键菜单「程序行为 ▸ 暂停播放」或设置页「录音检测」开启。录音开始时真暂停正在播放的媒体（停在当前进度），停止录音后从断点续播。覆盖带媒体控制的应用（浏览器、主流音乐/视频播放器）；游戏等无媒体控制的应用无法暂停，这是系统限制。
• 全局静音：仅设置页「录音检测」提供。录音期间静音全部后台声音（含游戏本体），停止录音后恢复。可单独使用，也可与「暂停播放」叠加（暂停管断点续播、静音管彻底无声）；游戏内录音建议配合「游戏模式」使用。注意：录音的几秒内完全听不到任何背景声（游戏里突然静音可能影响听声辨位）；程序若在录音中被强制结束（杀进程），静音状态可能残留，重新打开程序录一次音或手动调回相应程序音量即可恢复。另可勾选「仅游戏模式下静音」：开启后全局静音只在游戏模式也开着时执行，避免日常录音（写作/聊天）误静音音乐和视频；暂停播放不受此限制。

两个开关在每次录音开始时按当前状态生效；录音中途切换不影响当前会话，停止时仍会恢复本次会话实际做过的动作。

6. 识别引擎

6.1 引擎总览

云端引擎需在各厂商控制台自费开通对应服务；本地 FunASR 引擎完全免费离线。

打包版（exe）目前不含本地 FunASR 引擎，选 FunASR 会提示改用云端引擎或源码方式运行。

6.2 引擎切换

切换方式：悬浮条右键 → 识别引擎 → 选择目标分类，即点即换。

云引擎在菜单里按分类档渲染（每组以灰色禁用项作分组标题，组顺序跟随 ui.engine_order）：

相关说明：

• 分类名后带当前绑定的模型：阿里云用中文短名（如「大模型版 · Qwen Audio」），腾讯云用英文模型 ID（如「大模型2.0 · 16k_zh_en_2.0」）
• 未配置密钥的引擎组默认隐藏（当前引擎组除外）；FunASR 无密钥概念，按依赖是否安装显示「（需安装）」
• 显隐三级控制（设置 → 通用设置 → 引擎排序）：ui.engine_show_<provider> 按厂商整组隐藏；ui.engine_hidden_models 按模型 ID 逐项隐藏（逗号分隔，空=全部显示）；密钥未配置的组照旧隐藏
• 引擎分组顺序与显隐可在 设置 → 通用设置 → 引擎排序 调整（每组可展开逐模型开关）

模型 ID 中英对照（腾讯云三档候选可在设置页「引擎参数」下拉选择；阿里云两档为固定映射）：

讯飞/火山的菜单分类名即档位（见上表），无需另对照。

6.3 阿里云百炼

默认引擎。相关配置（config.yaml → aliyun）：

6.4 腾讯云

相关配置（config.yaml → tencent）：

6.5 讯飞

讯飞开放平台 提供两套独立版本与密钥（config.yaml → xfyun）：

6.6 火山引擎豆包

火山方舟控制台 获取密钥，火山引擎豆包流式 ASR 有 1.0（bigasr）与 2.0（seedasr）两代，两代各自独立配置计费方式（config.yaml → volcengine）：

说明：计费方式须分别与控制台购买的资源包一致；右键菜单切换版本时会自动套用对应版本的计费方式。

6.7 本地 FunASR

完全离线、无需密钥的本地引擎。识别全在本机完成，适合无网络、涉密或不想付费的场景。

相关配置（config.yaml → funasr）：

注意事项：

• 安装依赖：pip install funasr torch torchaudio（GPU 版本见 3.3 节）
• 模型首次使用自动从 ModelScope 下载到 ~/.cache/modelscope/，离线使用需提前下载
• 打包版不含此引擎，需源码方式运行

7. AI 修正

7.1 功能简介

AI 修正（默认关闭）在识别完成后调用大模型对文本进行润色：修正同音错别字、补全标点、去除口癖。

兼容 OpenAI 协议——OpenAI / DeepSeek / Moonshot / 智谱 / 通义 / 本地 Ollama / vLLM 等，改个 base_url 就能接入。

推荐 DeepSeek ，根据文档直接获取端点和 API 密钥。

7.2 开启与接入

开启方式：

1. 右键菜单 → 注入逻辑 → 勾选「AI 修正」
2. 或 设置 → AI 修正 → 启用 AI 修正 → 保存

接入配置（设置 → 引擎密钥 → 通用 AI 接口，或 config.yaml → llm）：

7.3 两种上屏方式

建议：日常聊天用默认方式；写文档等看重成稿质量、不那么赶的场景开启「修正后上屏」。

7.4 批量修正

攒几句一起送修，省 API 调用次数。

机制说明：

• 静音触发与无语音超时独立工作：静音触发管 LLM 批次送修时机，无语音超时管录音会话何时停止
• 录音停止（含无语音超时）时，累积队列中未送修的句子会强制送修（flush_pending），不丢句
• 批量修正时程序会在 prompt 末尾自动追加"逐句逐行返回"要求，并校验返回行数与句数一致；LLM 合并/吞句时整批放弃替换保留原文——宁可不修、不丢句
• batch_idle_ms 只在累积模式（batch_sentences ≥ 2）下起作用；中文口语句间自然停顿约 0.3~1 秒，推荐 1~2 秒

7.5 自定义提示词

• 必须包含 {text} 占位符——否则 LLM 收不到待修正文本，会返回"请提供需要修正的文本"
• 设置界面只能填单行；想用多行需手动编辑 config.yaml，用 YAML 块标量 |：

llm:
  prompt: |
    你是语音识别文本修正器。
    - 修正同音错别字
    - 补全标点
    文本：
    {text}

• 留空则使用内置模板（已含 {text} 占位符）
• 设置界面支持自定义提示词版本管理（版本下拉 + 新增/保存/删除），内置方案不可改

7.6 如何确认 AI 修正已生效

开启后每说一句话，悬浮条会出现三态提示（1~2 秒后消失）：

什么都没提示 = AI 修正未真正启用，检查 llm.enable 开关和 api_key 是否已填。

8. 语音命令

8.1 功能简介

语音命令（默认关闭）让你"动口不动手"：录音中句首说触发词（默认「听我说」）即进入命令态——这句话不上屏、不进历史、不送 AI 修正，直接当指令执行。

开启方式：右键菜单「注入逻辑 ▸ 语音命令」。

8.2 触发方式

容错机制：开着 AI 修正时，触发词被识别成同音字（如"之嘛开们"）会先进修正管道，修正版拼回触发词后二次检测命令，照样执行。

8.3 本地命令参考

本地命令识别快、不花钱，中英文变体均可说，不区分大小写。完整命令参考表在 设置 → 语音命令 → 命令参考（可展开收起）。

匹配优先级：本地命令表 > 自定义短语 > AI 命令。未命中时提示："没听懂。按键/设置直接说，AI 处理说\"帮我\"+指令"。

8.4 AI 命令

AI 命令（需配置 llm.api_key）：「听我说 帮我 + 指令」处理当前选中的文字——读取选区 → 大模型变换 → 原地替换，选中文本和剪贴板都会被妥善还原。

相关配置（config.yaml → commands）：

8.5 自定义短语

说「触发词 + 短语名」（如"听我说 我的邮箱"）插入预设文本。

• 需开启 设置 → 语音命令 → 自定义短语 开关
• 词表两列表格（短语名/短语内容）+ 添加/删除，存于状态目录 phrases.json
• 精确匹配、无拼音容错；查表优先于短语

8.6 与「逐字同步」的互斥关系

命令句的中间帧可能因同音误识别残留在输入框（顶掉你选中的文字），因此语音命令与「逐字同步」不能同时开启：开启任一个会询问后自动关闭另一个（记住了原偏好，关掉时自动恢复）。

9. 实时语音对话

9.1 功能简介

按 Ctrl+Shift+H 直接和 AI 语音聊天：豆包与 Qwen 由端到端语音大模型直接理解并语音回复，AI 播报中随时开口即可打断（barge-in）；Hermes 由本机识别、文字回复（见 9.10 节）。均为多轮连续对话。

语音对话支持三家服务提供商，三选一（dialog.provider，设置 → 语音模式 → 对话提供商）：

三家互斥：切换提供商后设置页「语音模式」字段组随之显隐；共用 enable / output_device / half_duplex / auto_reconnect 四项配置（Hermes 半双工恒开、自动重连不适用，见 9.10 节）。

与听写模式（第 5 章）的定位区别：

• 对话内容显示在悬浮条气泡卡片中，用「你 / AI」角色色带区分双方（青绿=你、紫=AI）；AI 回复流式逐行更新、说完定稿，点击气泡可展开/收起全文
• 对话与录音互斥：录音中按对话热键会被忽略并提示；对话中按录音热键同样忽略并提示，两侧都不抢占
• 计费遵循服务端规则：一次完整对话（进入到退出）计一次 query——豆包以火山控制台账单为准，Qwen 以阿里云百炼账单为准；Hermes 为自建服务，无计费

9.2 开通与密钥

本节为豆包提供商的接入说明；使用阿里云 Qwen-Audio Realtime（dialog.provider: "aliyun"）见 9.9 节。

1. 在火山引擎语音控制台（console.volcengine.com/speech）开通「豆包端到端实时语音大模型」
2. 密钥两种鉴权方式（与识别引擎的火山密钥同源通用）： - 新版单密钥：api_key（控制台「API Key 管理」生成） - 旧版双密钥：app_id + access_token（应用详情页，须来自同一应用）
3. 三个密钥字段留空 = 自动复用「引擎密钥」页的火山配置——已配好火山识别的用户开箱即用，不用填两遍

设置 → 语音模式 → 接入 组内有「测试连接」按钮：用当前填写的密钥完成一次完整握手（开会话后立即收尾），成功时显示报障必备的 X-Tt-Logid，失败时给出具体原因（未开通 / 密钥无效 / 网络不通）。

9.3 进入与退出

进入对话（任一入口）：

• 按对话热键，默认 Ctrl+Shift+H（设置 → 语音模式 → 对话热键 可改；留空 = 只不注册该热键，菜单与悬浮条入口仍在；修改需重启生效）
• 悬浮条右键菜单勾选「语音模式」

退出对话（任一方式）：

• 再按一次对话热键
• 右键菜单取消勾选「语音模式」
• 对 AI 说「退出」或「再见」（可在会话行为关闭；Hermes 为本机 ASR 识别后匹配，同样生效）
• 点击悬浮条启停按钮（对话中按钮图标变为停止符号，即「退出对话」）
• Hermes 专属：思考中（AI 生成回复期间）按一次热键 = 取消本轮并回到聆听（服务端经 /stop 真正停住，不会后台继续跑），连按两次 = 退出对话

整体关闭语音对话：设置 → 语音模式 → 接入 → 启用语音模式（或 config.yaml 的 dialog.enable: false）。关闭后右键菜单「语音模式」项、对话热键与悬浮条对话入口全部下线，等于这个功能不存在；本设置页保留，随时可重新开启。改动立即生效（菜单每次右键重建、热键随配置热加载重注册），无需重启。

与「对话热键留空」的区别：留空只关掉热键这一个入口，菜单和悬浮条仍可进入对话；总开关是整体下线。

对话进行中关掉总开关不会把人困住：启停按钮与热键仍能正常退出当前对话，只是退出后不能再进入。

9.4 对话状态与打断

悬浮条状态点四种对话态，思考与播报刻意分色（同色会让人以为卡住了）：

打断（barge-in）：默认全双工——AI 播报中直接开口说话即可打断并接管对话，无需等它说完。

Hermes 无语音回复，故不会出现「AI 播报」态：思考完成、回复文本定稿后直接回到聆听（状态机制豆包/Qwen 四态通用，Hermes 只走其中三态）。

§9.5~§9.7 为豆包 S2S 专属字段；阿里云 Qwen 的对应字段见 §9.9，Hermes 见 §9.10。

9.5 模型与人设

人设字段按版本二选一生效：

• O2.0：bot_name（AI 自称，≤20 字符）、system_role（角色/职责/口吻描述）、speaking_style（语气偏好，如「轻松幽默，多用短句」）
• SC2.0：character_manifest（角色描述，如「你是古风书童，说话半文半白」，可含动作与表情描述），与上面三个互斥

9.6 音色与播报

• 音色（dialog.speaker）：下拉含 7 个官方音色（vv / 小何 / 云舟 / 小天 4 个中文，Tim / Dacey / Stokie 3 个英文）；SC2.0 克隆音色（saturn_ 或 S_ 开头）直接在输入框手填名称
• 语速 / 音量（dialog.speech_rate / dialog.loudness_rate）：范围 [-50, 100]，正值加快/增亮，仅 2.0 版本模型生效
• 播放设备（dialog.output_device）：AI 语音从哪个设备播出，默认跟随系统输出；下拉展开时自动刷新（支持热插拔）

9.7 会话行为

9.8 常见问题

• 进入对话提示「请先填写语音模式密钥」：三密钥留空且「引擎密钥」页也没有可用火山密钥；到设置 → 语音模式 填写，或先配好火山识别密钥
• 提示「录音中，请先停止录音」/「对话中，请先退出对话」：两模式互斥的正常表现，先退出当前模式
• AI 总是被「自己打断」：外放拾音导致，开半双工或改用耳机（见 9.4 节）
• AI 接话太快/太慢：调判停窗口 end_smooth_window_ms（见 9.4 节）
• 连接失败/频繁报错：先用「测试连接」自查并记下 logid；对照错误提示（如「对话配置有误」检查模型与人设，「长时间无交互」属正常释放，自动重连会接管）
• 换音色/改人设不生效：部分参数在建会话时下发，退出对话重新进入即可
• 切换提供商后设置项对不上：provider 切换后设置页「语音模式」字段组随之显隐（豆包组 / Qwen 组 / Hermes 组互斥），属正常现象；部分参数在建会话时下发，重新进入对话生效
• Qwen 上下文没续上：Qwen 无跨连接续接（重连即新会话），跨次记忆仅豆包支持（keep_context）；单会话内历史轮数由 max_history_turns 控制
• Hermes 进入对话提示未配置：dialog.hermes.base_url / api_key 未填（api_key 即服务器 ~/.hermes/.env 的 API_SERVER_KEY）；鉴权失败提示「Hermes 鉴权失败：请检查 API Key」
• Hermes 没有声音：属正常现象——Hermes 不提供音频（audio_api=false），回复以文字显示在悬浮条气泡；TTS 为后续预留
• Hermes 回答慢：自建服务器的模型生成耗时（实测纯文本单轮 5.5~7.9 秒），可调 turn_timeout_ms，但别调太小；思考中想反悔按一次对话热键取消本轮
• Hermes 服务端会话越来越多：Hermes 会话只在服务端累积、客户端不关闭删除（每轮进入新建会话，标题自动加唯一后缀避免重复），属服务端特性，可在 Hermes 侧自行清理

9.9 阿里云 Qwen-Audio Realtime（提供商二）

语音对话的第二家提供商：阿里云百炼 Qwen-Audio Realtime 端到端语音大模型。在 设置 → 语音模式 → 对话提供商 切换为「阿里云」即可（dialog.provider: "aliyun"），设置页下方字段组随之切换为 Qwen 专属配置。

开通与密钥

1. 在 阿里云百炼控制台 开通「Qwen-Audio Realtime」服务
2. API Key（dialog.qwen.api_key）：填百炼 API Key（sk- 开头）；留空自动复用「引擎密钥」页的阿里云配置——与阿里云识别共用同一把钥匙，已配好阿里云识别的用户开箱即用
3. 接入区域（dialog.qwen.region，设置 → 语音模式 → Qwen 接入 → 接入区域）： - legacy（默认）：旧域名公共端点，免 WorkspaceId - beijing / singapore：新域名独享端点，必须填写 WorkspaceId（百炼控制台右上角「业务空间」查看）
4. 「测试连接」：用当前填写的密钥完成一次完整握手，成功显示 session=<id>（对应豆包的 X-Tt-Logid，报障时使用），失败给出具体原因

模型与人设

收音与判停

会话行为

与豆包的关键差异

三家共用 dialog.enable 总开关；豆包与 Qwen 共用 output_device / half_duplex / auto_reconnect；Hermes 半双工恒开、无音频输出、自动重连不适用。对话状态四态与打断行为（9.4 节）对三家同样适用（Hermes 无「AI 播报」态）。

9.10 Hermes Agent（提供商三）

语音对话的第三家提供商：用户自建的 hermes-agent API server（NousResearch 开源 agent，OpenAI 兼容 HTTP）。与前两家性质不同——Hermes 是纯文本 agent（带完整工具集、记忆、人格），不提供任何音频能力（实测 capabilities audio_api=false / realtime_voice=false），所以断句与识别由 ORI 在本机补齐：本地 VAD 断句 + 对话专属 ASR 识别 → 文本发给 Hermes → 文字回复。自建自用，无任何计费。

开通与密钥

1. 在服务器上部署 hermes-agent 并启动 API server（见其官方文档）
2. 设置 → 语音模式 → 对话提供商 切换为「Hermes Agent（自建）」（dialog.provider: "hermes"）
3. 填写配置（dialog.hermes，设置 → 语音模式 → Hermes 接入）： - base_url：服务地址，如 http://192.168.1.10:8642（不含 /v1，误填会自动剥掉） - api_key：即服务器 ~/.hermes/.env 里的 API_SERVER_KEY（无鉴权的自建服务可留空）
4. 「测试连接」对 Hermes 不适用（按钮只给中性提示）：请直接按对话热键实连一次验证

对话专属识别

Hermes 的输入文字来自 ORI 自己的 ASR 引擎，「对话专属识别」（dialog.asr，设置 → 语音模式 → 对话专属识别）可以给对话单独指定引擎，不影响听写：

典型用法：听写用中文引擎、对话用中英混说引擎，两者互不牺牲。

会话行为

10. 设置界面说明

10.1 通用设置

10.2 引擎密钥

手风琴卡片布局，当前引擎卡片默认展开，顺序随引擎排序设置：

• 腾讯云：SecretId / SecretKey / AppID（密码框）
• 阿里云百炼：API Key（sk- 开头）
• 讯飞（大模型版 / 标准版两小节）：大模型版 AppID / APIKey / APISecret；标准版 AppID / APIKey
• 火山引擎（新版 / 旧版鉴权两小节）：新版 API Key；旧版 App ID / Access Token
• 通用 AI 接口（排在厂商卡之后）：API 地址 / API Key / 模型，语音 AI 功能共用（语音命令「帮我」与 AI 修正都读这里）；「检测连通性」用当前填写的地址/密钥/模型发最小请求，成功/失败即时提示原因

10.3 引擎参数

手风琴卡片布局，顺序随引擎排序设置：

• 腾讯云：三档分类调用模型（大模型2.0 / 大模型1.0 / 通用引擎 各自下拉选模型）、语气词过滤（不过滤/部分/全部）、标点过滤（不过滤/句末/所有）、数字格式（中文数字/阿拉伯数字）、敏感词过滤（不过滤/过滤/替换为 *）、热词表、自学习模型
• 阿里云百炼：语气词过滤（开关）、断句静音时长（200~6000ms）、热词表、语言提示（如 zh / zh,en）
• 讯飞（大模型版 / 标准版）：引擎版本切换；大模型版语气词过滤；标准版识别语言（中文/中英混合、英文）、标点过滤、语气词过滤、垂直领域（court/edu/finance/medical/tech）
• 火山引擎（豆包 1.0 / 2.0）：两代各自计费方式（按时长/按并发）、口语顺滑、二次识别
• FunASR 本地：模型、运行设备（自动/CPU/GPU CUDA）、识别窗口（默认 600ms/低延迟 480ms/高准确 720ms）、热词、本地模型目录（用户自行下载的权重路径；高级项 funasr.model_hub / funasr.model_revision 仅配置文件可用）

打包版（exe）不含本地引擎依赖，此卡片仅显示一句不可用说明；本地识别请以源码方式运行。

10.4 AI 修正

接口地址 / 密钥 / 模型与连通性检测在「引擎密钥 → 通用 AI 接口」配置（与语音命令「帮我」共用），本页只管修正行为。

10.5 语音命令

10.6 录音检测

10.7 语音模式

分组设置项（详细用法与示例见第 9 章）。默认提供商为豆包 S2S；切换「对话提供商」后下方字段组整体切换（豆包 / Qwen / Hermes 互斥显隐）：

provider = 阿里云（Qwen）时的字段组（dialog.qwen，与上方豆包组互斥显隐）：

• Qwen 接入：接入区域（legacy 公共端点 / beijing / singapore 独享端点）、WorkspaceId（新域名必填）、API Key（留空自动复用「引擎密钥」页阿里云配置）
• Qwen 模型与人设：模型（Plus / Flash）、音色（5 个官方龙系音色）、系统指令（人设/风格）
• Qwen 收音与判停：判停方式（server_vad 可调阈值与静音时长 / smart_turn 模型自动判停）、VAD 阈值（-1.0~1.0）、判停静音（200~6000ms）
• Qwen 会话行为：语音情感、历史轮数（1~50）、联网搜索（仅 Plus/Flash）

provider = Hermes（自建）时的字段组（dialog.hermes + dialog.asr，与上方两组互斥显隐）：

• Hermes 接入：服务地址（http://host:port，误填 /v1 自动剥掉）、API Key（服务器 ~/.hermes/.env 的 API_SERVER_KEY）、模型名（保留字段，当前版本不随请求发出）、会话标题（留空=服务端无标题）、识别容错提示（system_hint）、连接超时、单轮超时
• 对话专属识别：对话识别引擎（留空=跟随顶层「识别引擎」；可选腾讯云/阿里云）、对话模型档、语种、热词（字段含义见 9.10 节）

10.8 关于

• 头部卡：圆角图标 + "Open-RealtimeASR-UI" + 版本号
• 折叠卡：
• 关于本应用：定位与流程说明
• 开源组件：CPython / PySide6 / sounddevice / PortAudio / CFFI / numpy / keyboard / pyperclip / websockets / PyYAML / FunASR / PyTorch 及许可证
• 联系方式：哔哩哔哩空间动态（打开链接）
• 日志与排障：日志保留天数（1~365）、打开日志目录、清空日志

11. 主题与个性化

11.1 内置主题

切换方式：右键菜单 → 主题颜色，或 config.yaml → ui.theme_name（重启生效）。

11.2 扩展主题包

内置主题之外，支持外部主题包扩展：把主题包放入 themes/ 目录即可，重启后生效，无需改代码。

主题包机制：

• 结构：themes/<包名>/theme.yaml（必填 bg/text/accent），投放即生效
• 特性模块缺失时自动跳过该主题，不影响程序启动
• 主题名与内置重名时跳过
• 打包版主题目录在 exe 同目录，源码版在项目根目录
• 精简构建（build.bat lite）物理排除 DLC 主题

11.3 字体设置

字体三选一（优先级从高到低，运行时也可通过右键菜单「选择字体文件」即时切换）：

1. font_file：任意 .ttf / .otf 文件绝对路径（推荐非系统安装字体）
2. font_family：系统已装字体的 family 名（如 Microsoft YaHei UI）
3. 都不填：使用内置默认字体（阿里巴巴普惠体 3.0 Medium；字体文件缺失时退回 Qt 默认字体）

11.4 悬浮条外观调整

12. 配置说明

12.1 配置文件查找顺序

配置文件为 YAML 格式，查找顺序：

打包版（frozen）：

1. exe 同目录 config.yaml
2. exe 同目录 config/config.yaml

源码版：

1. 项目根 config/config.yaml
2. 项目根 config.yaml

共同兜底：

3. 当前工作目录 config/config.yaml
4. 当前工作目录 config.yaml
5. 用户主目录 ~/.asr_voice/config.yaml

首次运行自动生成：无配置文件时复制内置模板——打包版优先生成到 exe 同目录（不可写时退 ~/.asr_voice/config.yaml），源码版生成到 config/config.yaml（已 gitignore）。

加载合并：默认值（defaults.py）← config.yaml（深合并 + 类型归一化）。

状态目录（paths.state_dir）：打包版 <exe 目录>/.asr_voice/，源码版 ~/.asr_voice/——存放 history.json、state.json、phrases.json、prompts.json、menu_icons/。打包版与源码版状态互不共享。

12.2 常用配置字段

完整字段及注释见 config/config.example.yaml。常用配置：

热键实现：含修饰键的组合（Ctrl/Alt/Shift/Win + 主键）走 Windows 原生 RegisterHotKey，不挂钩子、不改动修饰键状态，因此不会出现"按过一次 Shift 之后系统一直认为 Shift 按着"的修饰键滞留；组合已被其他程序占用时会注册失败并提示换组合。只有单个普通键（删除键打断用的 Backspace/Delete）走键盘钩子，且只监听不拦截。

13. 常见问题与故障排查

13.1 程序无法启动

可能原因与排查：

• 源码版缺依赖：确认已 pip install -r requirements.txt，Python 版本 ≥ 3.10
• 配置文件损坏：删除/备份 config.yaml 后重新启动自动生成；打包版会在启动时弹窗提示配置加载失败（退出码 3）
• 核心模块导入失败：源码版确认 asr_voice 包结构完整（退出码 4）
• 双击 exe 无反应：查看 exe 同目录 logs/ 下日志；确认 exe 所在目录可写（不可写时配置会退到 ~/.asr_voice/config.yaml）
• 安全软件拦截：部分安全软件会拦截键盘钩子与托盘程序，添加信任后重试

13.2 热键无效或冲突

• 含修饰键的热键由 Windows 原生 RegisterHotKey 注册，不需要管理员权限（含 Win 键的组合同样可用）
• 热键被其他程序（含系统）占用时注册失败并提示更换热键；按提示换一个组合即可（录音热键失败会弹窗并以退出码 3 结束）
• 修改热键后需重启程序生效
• 建议避免与系统 / 常用软件全局热键冲突（如系统 Win+H 本身）

13.3 识别没有文字输出

按以下顺序排查：

1. 密钥：确认当前引擎密钥已正确填入（设置 → 引擎密钥），密钥错误时悬浮条会显示错误信息
2. 网络：确认可访问对应厂商服务（公司网络/防火墙可能拦截）
3. 麦克风：设置 → 录音检测 选择正确设备；确认系统麦克风权限已放行；观察录音时状态点是否变红（未变红说明没有采到声音）
4. VAD 阈值：说话声低于判定阈值会被当静音，适当调低「语音判定阈值」
5. 引擎版本：切换其他引擎验证是引擎问题还是通用问题
6. 日志：查看 logs/asr_voice.log 中报错信息（打包版在 exe 同目录 logs/，源码版在项目根 logs/）

13.4 首字被吞 / 漏字

• 确认「麦克风常驻」（audio.warmup_capture）已开启——预滚缓冲保留按下热键前约 400ms 音频
• 若关闭了麦克风常驻，按下热键后稍顿再开口可缓解
• 逐字输入在部分程序中会丢字，可切换为剪贴输入（微信/企业微信已自动切换）
• 讯飞 / 阿里等引擎的断句参数影响中间结果节奏，可按需调整「断句静音时长」

13.5 AI 修正没有反应

• 先确认是否真的启用：开启后每句话应有悬浮条三态提示（见 7.6 节）；什么提示都没有 = 未启用，检查 llm.enable 与 api_key
• 提示「AI 修正失败（保留原文）」：检查 base_url / model / api_key / 网络；超时（默认 3 秒）可适当调大 timeout_ms
• 自定义 prompt 必须包含 {text} 占位符，否则 LLM 收不到待修正文本
• 本地 Ollama 用户：确认 Ollama 服务已启动，base_url 为 http://localhost:11434/v1

13.6 语音命令不生效

• 确认「语音命令」已在右键菜单勾选（commands.enable=true）
• 触发词需在句首；连说方式为「触发词 + 命令」一步到位
• 触发词被识别成同音字时，需要开着 AI 修正才能二次修正检测；否则说慢一点、发音清晰一些
• 与「逐字同步」互斥：开启语音命令会自动关闭逐字同步，属正常现象
• AI 命令（"帮我"类）需配置 llm.api_key

13.7 剪贴板被覆盖

• 「保留剪贴」默认关：粘贴后自动恢复剪贴板原内容
• 开启「保留剪贴」后识别结果会占用剪贴板（覆盖图片/文件），Ctrl+V 可随时重复粘贴
• 复制图片后立即语音输入导致图片丢失：多为开启了「保留剪贴」，右键菜单关闭即可避免

13.8 FunASR 相关异常

• 打包版选不了 FunASR：打包版不含本地引擎，需源码方式运行（见 3.3 节）
• 依赖未安装：右键菜单显示"（需安装）"，执行 pip install funasr torch torchaudio
• 首次识别慢：模型首次使用自动下载（~/.cache/modelscope/），离线环境请提前下载
• 启动变慢：preheat=true 启动即预热模型（CPU 3~8 秒），可关闭改为首次录音才加载
• GPU 环境：device 设为 cuda 更快；无 GPU 时设为 cpu
• 本地引擎识别能力与云端大模型有差距（设置 → 关于 → 本地离线引擎 有说明）

13.9 游戏内无法输入文字

逐字输入基于无扫描码的合成键击（KEYEVENTF_UNICODE），游戏等自绘输入框的输入管道（Raw Input / DirectInput / 扫描码）不读取这类事件——日志可见「注入开始/完成」且无失败记录，但游戏内不出字。

• 右键菜单「注入逻辑 ▸ 游戏模式」开启后强制走剪贴板粘贴；聊天框支持粘贴的游戏即可上屏
• 目标游戏以管理员运行（常见于带反作弊的客户端）：Windows 的 UIPI 权限隔离会静默丢弃普通权限进程发出的合成输入，手动按键不受影响。程序内三种提权方式：① 开启「游戏模式」时按悬浮条询问选「立即提权」（游戏模式随重启保留时，启动后也会再问一次）；② 右键菜单「程序行为 ▸ 程序提权」（一次性，弹 UAC 后由提权实例接管）；③ 设置「通用设置」顶部的「永久以管理员身份启动」（建登录计划任务，之后每次启动都是管理员且不弹 UAC）。也可在资源管理器右键 exe 选「以管理员身份运行」。可在任务管理器「详细信息」页查看目标进程的「已提升」列确认；日志「游戏模式发送 Ctrl+V」行的「权限差」字段同刻取证（True=目标高权限、合成输入必被丢弃）
• 若粘贴也无效，说明目标输入框连剪贴板粘贴都不支持，暂无通用解法
• 注意：游戏内退格同样无效，游戏模式下 AI 修正替换不可用

14. 附录

14.1 常见术语说明

14.2 默认值速查

14.3 退出码说明

命令行参数：--config <路径>（指定配置文件）、--hidden（静默启动仅托盘）、--replace（接管模式：提权重启/自启切换时通知旧实例退出，待单实例锁释放后接管）。

14.4 参考链接

• 项目仓库：见 README.md
• 配置模板：config/config.example.yaml
• 阿里云百炼控制台：https://bailian.console.aliyun.com
• 阿里云 Qwen-Audio Realtime 文档：https://help.aliyun.com/zh/model-studio/qwen-asr-realtime-interaction-process
• 腾讯云密钥管理：https://console.cloud.tencent.com/cam/capi
• 腾讯云 ASR 控制台：https://console.cloud.tencent.com/asr
• 讯飞实时语音转写：https://console.xfyun.cn
• 火山引擎语音控制台：https://console.volcengine.com/speech

License 与免责声明

本项目以 Apache License 2.0 开源。

• 云端识别引擎（阿里云百炼 / 腾讯云 / 讯飞 / 火山引擎豆包）均为各厂商官方服务，使用前需自备密钥并按各厂商计费规则自费开通，产生的费用与合规责任由使用者自行承担。
• 本地 FunASR 引擎完全离线免费：工具包代码为 MIT，paraformer-zh-streaming 模型权重为 Apache-2.0（以官方模型卡为准），版权归 FunASR / ModelScope 相关方所有。本仓库不内置、不分发模型权重，由用户自行下载；如需商用分发权重，请锁定 funasr.model_revision 并按 Apache-2.0 履约。
• 本项目通过官方接口调用上述服务；厂商接口变动可能导致对应引擎暂时不可用，请以各厂商最新文档为准。
• 第三方组件（PySide6 / sounddevice / FunASR 等）的完整许可清单、版权署名与商用合规说明见仓库 THIRD_PARTY_NOTICES.md。