FunASR 桌面语音输入法实战指南快捷键录音、自动识别与光标粘贴全流程【免费下载链接】FunASROpen-source speech recognition toolkit for training, inference, streaming ASR, VAD, punctuation, speaker diarization pipelines, and OpenAI-compatible/MCP serving.项目地址: https://gitcode.com/GitHub_Trending/fun/FunASR导读本文基于 FunASR 仓库中的 examples/voice_input/README.md 及其核心实现 funasr_input.py系统讲解如何用 FunASR 搭建一个完全本地运行的桌面语音输入法按快捷键开始录音再按一次停止音频被送往本地 FunASR 服务完成识别识别文字自动粘贴到当前光标位置。读完本文你将掌握语音输入法的完整安装、配置、运行步骤理解录音 → 识别 → 粘贴的底层调用链并能按需切换 SenseVoice、Paraformer、Fun-ASR-Nano 等模型与 macOS/Linux/Windows 平台适配方案。一、项目定位本地优先的桌面语音输入工具examples/voice_input是一个独立于 FunASR 核心库之外的桌面端应用示例其定位是把 ASR 能力包装成“语音输入法”用户无需打开任何页面只要在当前任意应用中文档编辑器、聊天窗口、终端等按下快捷键说话再按一次快捷键识别出的文字就会自动出现在光标处。它由两部分组成语音输入客户端funasr_input.py负责录音、调起识别请求、将结果写入剪贴板并模拟粘贴FunASR 服务端funasr-server见 funasr/bin/server.py负责加载 ASR 模型、接收音频、返回识别文本。客户端与服务端之间通过OpenAI 兼容的 HTTP API通信这也是本示例最能体现 FunASR 工程化能力的地方——客户端甚至直接使用openai官方 Python SDK把 FunASR 服务当作一个本地版 Whisper API 来调用。二、安装与依赖2.1 服务端依赖服务端需要 FunASR 本体及其 Web 服务组件pip install funasr fastapi uvicorn python-multipart其中fastapi、uvicorn、python-multipart是funasr-server启动所必需的运行库。在 funasr/bin/server.py 中服务启动前会显式校验这些包是否可用缺失时会提示Error: funasr-server requires additional packages. Install with: pip install vllm fastapi uvicorn python-multipart注意若使用fun-asr-nano模型走 GPU 加速路径服务端还会按需加载 vLLM见下文架构部分建议一并安装vllm。2.2 客户端依赖语音输入客户端需要以下包pip install funasr sounddevice numpy pyperclip openai pynput各依赖在 funasr_input.py 中的职责依赖用途sounddevice采集麦克风音频PortAudio 绑定numpy音频帧的拼接与字节转换pyperclip将识别结果写入系统剪贴板openai以 OpenAI SDK 方式调用 FunASR 的/v1/audio/transcriptions接口pynput全局监听快捷键跨平台客户端在main()中会对这四个关键依赖sounddevice、pyperclip、openai、pynput逐一做ImportError检查并给出对应的安装提示缺失任何一个都会直接退出方便排查环境问题。三、三步启动从服务到输入法第一步启动 FunASR 服务funasr-server --device cuda # 或 --device cpufunasr-server的默认配置为host0.0.0.0、port8000、devicecuda、modelauto。其中modelauto的自动选择逻辑见 funasr/bin/_server_app.py 的create_app为设备为cuda*时自动加载fun-asr-nano走 vLLM 加速其他设备如 CPU时自动加载sensevoiceSenseVoiceSmall。服务启动后会在终端打印╔══════════════════════════════════════════════╗ ║ FunASR Server v... ║ ║ URL: http://0.0.0.0:8000/v1 ║ ║ Docs: http://0.0.0.0:8000/docs ║ ╚══════════════════════════════════════════════╝服务同时暴露 OpenAI 兼容接口/v1/audio/transcriptions与 FunASR 原生 REST 接口/asr并自带 FastAPI 的/docs交互式调试页面。第二步启动语音输入法cd examples/voice_input python funasr_input.py程序启动后会打印当前配置总览服务器地址、模型、快捷键、语言随后进入全局快捷键监听状态等待用户按键。第三步使用按CtrlShiftSpace开始录音终端显示 录音中... (再按快捷键停止)再按一次停止录音程序自动发送识别请求终端显示⏳ 识别中...识别成功后文字被复制到剪贴板并尽可能自动粘贴到当前光标位置终端显示✅ {识别文本}。整体工作流程可以概括为按快捷键 → 录音 → 再按快捷键 → 发送到 funasr-server → 识别 → 自动粘贴到光标位置四、配置选项详解语音输入客户端通过命令行参数进行配置参数定义位于 funasr_input.py 的argparse部分python funasr_input.py --server http://localhost:8000/v1 # 服务器地址 python funasr_input.py --model paraformer # 模型选择 python funasr_input.py --hotkey cmdshiftspace # macOS 快捷键 python funasr_input.py --lang zh # 语言全部参数及默认值参数默认值说明--serverhttp://localhost:8000/v1FunASR 服务的 OpenAI 兼容地址可指向远程 GPU 机器如--server http://gpu:8000/v1--modelsensevoice使用的 ASR 模型名需与服务端可加载模型对应--langauto语言提示如zh服务端会优先采用该提示否则回退到后端自动检测--rate16000录音采样率Hz--hotkeyctrlshiftspace切换录音状态的全局快捷键4.1 快捷键解析规则--hotkey支持连接的组合键解析逻辑在 funasr_input.py 中实现ctrl/control→ 左 Ctrl 键shift→ 左 Shift 键alt/option→ 左 Alt 键cmd/command/super→ Command/Super 键macOS 使用space→ 空格键其他字符 → 通过keyboard.KeyCode.from_char映射为普通按键。程序通过pynput的Listener全局监听按键当按下的按键集合恰好覆盖全部修饰键与主键时触发录音切换按键释放后清空当前修饰键状态。这也是 README 中--hotkey cmdshiftspace可以工作的原因。4.2 服务端参数与之配套funasr-server本身也提供完整参数funasr/bin/server.pyfunasr-server --host 127.0.0.1 --model sensevoice --device cpu funasr-server --host 127.0.0.1 --port 9000 # 自定义端口 funasr-server --host 127.0.0.1 --model paraformer funasr-server --host 127.0.0.1 --model-path /path/to/local/model # 本地模型路径 funasr-server --host 127.0.0.1 --model-path username/paraformer --hub hf funasr-server --host 127.0.0.1 --cors-origin http://localhost:3000服务端参数默认值说明--host0.0.0.0绑定地址--port8000监听端口--devicecuda推理设备cuda、cpu、mps--modelauto预加载模型auto、sensevoice、paraformer、fun-asr-nano、moss-transcribe-diarize--model-path无本地模型路径或模型 ID优先级高于--model--hubms模型仓库msModelScope或hfHugging Face--spk-modelcam说话人分离模型首次spktrue请求时懒加载--cors-origin关闭受信任的浏览器跨域来源可重复指定五、工作原理从麦克风到光标5.1 端到端架构[麦克风] → [本程序] → [funasr-server :8000] → [识别结果] → [粘贴到光标] ↑ 本地运行音频不出机器整个链路中麦克风音频由客户端进程采集通过网络发送给本地的funasr-server识别结果原路返回再由客户端完成粘贴。README 特别强调“本地运行音频不出机器”——因为服务与客户端都跑在本机音频数据不经过任何云端适用于对隐私敏感的输入场景。5.2 客户端内部流程源码级funasr_input.py 的核心逻辑分为四个阶段① 录音采集。首次按下快捷键后程序在后台线程中启动sounddevice的InputStream并以--rate默认 16000 Hz、单声道、int16的配置采集音频callback中通过线程锁保护的recording标志判断是否将数据帧追加进audio_frames列表sd.default.samplerate args.rate sd.default.channels 1 sd.default.dtype int16 stream sd.InputStream(callbackcallback) stream.start()② 内存 WAV 封装。再次按下快捷键停止录音后程序用numpy.concatenate合并所有音频帧并通过标准库wave模块在内存缓冲区io.BytesIO中写出 WAV 头与 PCM 数据——无需落盘临时文件wf.setnchannels(1) wf.setsampwidth(2) wf.setframerate(args.rate) wf.writeframes(audio_data.tobytes())③ OpenAI 兼容请求。客户端以OpenAI(base_urlargs.server, api_keynot-needed)创建客户端api_key仅为占位符本地服务不做鉴权然后调用音频转写接口result client.audio.transcriptions.create( modelargs.model, file(recording.wav, wav_buffer, audio/wav), ) text result.text.strip()这正是 FunASR 服务端 OpenAI 兼容能力的直接体现。服务端收到请求后会先将任意采样率的音频统一重采样为 16kHz 单声道 float32见 funasr/bin/_server_app.py 的prepare_audio_for_inference再交给模型推理。④ 剪贴板与模拟粘贴。识别文本先经pyperclip.copy写入剪贴板然后按平台尝试自动粘贴macOSosascript执行keystroke v using command downAppleScript 模拟 CmdVLinuxxdotool key ctrlv模拟 CtrlVWindows仅复制到剪贴板需手动CtrlV粘贴。5.3 服务端模型加载源码级服务端在 funasr/bin/_server_app.py 中维护了FALLBACK_CONFIGS决定不同模型名对应的底层模型与配套模块模型名底层模型配套模块sensevoiceiic/SenseVoiceSmallVADfsmn-vadmax_single_segment_time30000paraformerparaformer-zhVADfsmn-vad标点ct-puncmoss-transcribe-diarizeOpenMOSS-Team/MOSS-Transcribe-DiarizeHF联合转写与匿名说话人标注fun-asr-nanoFunAudioLLM/Fun-ASR-Nano-2512走 vLLM 引擎VADfsmn-vadvLLM 不可用时回退 AutoModel这些模型名在 funasr/cli.py 的MODEL_CONFIGS中也有对应的命令行映射两者保持一致的命名约定sensevoice/paraformer/paraformer-en/fun-asr-nano。服务端对语言提示的处理遵循“调用方显式语言 后端检测 unknown”的优先级resolve_transcription_language且会从 SenseVoice 文本中提取|zh|、|en|等语言标签extract_language_from_asr_text。六、支持平台与自动粘贴能力README 中给出明确的平台支持矩阵平台录音自动粘贴macOS✅✅ (AppleScript)Linux✅✅ (xdotool)Windows✅手动 CtrlV其中录音能力由sounddevicePortAudio跨平台提供自动粘贴的差异由 funasr_input.py 中基于sys.platform的分支实现darwin→ AppleScriptkeystroke v using command downlinux→xdotool key ctrlv失败时静默忽略识别文本仍保留在剪贴板中。Windows 平台只需手动按CtrlV识别结果同样已通过pyperclip进入剪贴板不影响使用。七、模型选择与性能参考7.1 支持模型README 给出客户端可指定的模型及其参考性能相对实时倍率RTF 倒数的量级数值来源于该文档的实测记录实际结果随硬件、音频长度浮动模型速度语言sensevoice默认170x GPU / 17x CPU中/英/日/韩/粤paraformer120x GPU / 15x CPU中/英fun-asr-nano17x GPU中/英/日 中文方言/口音7.2 如何按场景选模型结合 docs/model_selection.md 中的路由说明可以这样选择多语言、多口音场景选默认的sensevoice覆盖中/英/日/韩/粤且返回文本会剥离|zh|等富文本标签适合直接作为输入法文本中文普通话输入为主的场景选paraformer服务端会自动挂载fsmn-vad与ct-punc标点模型输出带标点的流畅中文GPU 环境 方言/口音需求选fun-asr-nano支持中文方言与口音GPU 下走 vLLM 加速。对于没有 GPU 的机器README 的延迟参考为 CPU 3-5 秒、GPU 说完后 1-2 秒出结果。实际使用时可在funasr-server启动命令中用--model显式指定模型如funasr-server --model paraformer --device cpu保证客户端--model与服务端可加载模型保持一致。八、常见问题Q: 需要网络吗不需要。funasr-server和语音输入法都在本地运行音频数据不出机器。Q: 支持哪些音频格式内部统一使用 WAV 16kHz、单声道、16-bit PCM客户端在内存中完成封装服务端也会自动将任意采样率重采样到 16kHz用户无需关心格式细节。Q: 延迟多少GPU 环境约在说完话后 1-2 秒出结果CPU 环境约 3-5 秒。Q: 启动时提示缺少依赖怎么办客户端缺少sounddevice/pyperclip/openai/pynput时会分别打印对应安装命令服务端缺少 FastAPI 组件时提示安装fastapi uvicorn python-multipart按提示补齐即可。Q: 识别失败如何排查客户端捕获异常后提示“请确认 funasr-server 正在运行”。可用curl或浏览器访问http://localhost:8000/docs检查服务是否存活并确认--server地址与funasr-server实际监听地址一致。九、延伸阅读examples/voice_input/funasr_input.py语音输入客户端完整实现funasr/bin/server.pyfunasr-server命令入口与全部启动参数funasr/bin/_server_app.pyOpenAI 兼容接口与模型加载、VAD、说话人分离的服务端实现docs/model_selection.md模型选型与各模型路由说明funasr/cli.py命令行模型配置映射sensevoice/paraformer/fun-asr-nano等。如果你希望在浏览器或第三方应用中复用这套识别能力FunASR 仓库还提供了 examples/openai_api 的完整服务端示例与 smoke test可直接替换语音输入客户端中的openaiSDK 调用方式将同样的 API 接入网页、聊天机器人或自动化工作流。【免费下载链接】FunASROpen-source speech recognition toolkit for training, inference, streaming ASR, VAD, punctuation, speaker diarization pipelines, and OpenAI-compatible/MCP serving.项目地址: https://gitcode.com/GitHub_Trending/fun/FunASR创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考