SenseVoice 贡献者指南：从开发环境搭建、模型原理到提交高质量 PR 的完整实战

人工智能大模型语音音频微调本地部署【免费下载链接】SenseVoiceOpen-source SenseVoiceSmall model for Mandarin, Cantonese, English, Japanese, and Korean ASR, language ID, emotion recognition, and audio event detection.项目地址https://gitcode.com/gh_mirrors/se/SenseVoice点击查看免费下载导读本文以仓库根目录的 CONTRIBUTING.md 为骨架系统讲解 SenseVoiceSmall 开源语音模型的本地开发环境搭建、CPU/GPU 运行方式、Issue 与 Pull Request 协作规范并结合 model.py、api.py、finetune.sh、Dockerfile 等仓库源码深入剖析模型架构、训练数据格式与容器化部署细节。读完本文你将能独立完成从克隆仓库→跑通推理→定位问题→提交修复的完整贡献闭环。一、开工前的准备环境依赖与开发环境搭建1.1 前置条件Prerequisites官方贡献指南对开发环境的要求非常精简只有三条依赖项说明Python 3.8运行时与训练脚本的基线版本Git版本管理与 Fork/PR 工作流必需CUDA 兼容 GPU可选仅用于加速推理与微调没有 GPU 也完全可以在 CPU 上运行仓库 requirements.txt 给出了更精确的依赖清单其中值得注意的版本约束包括torch2.12.1与torchaudio2.11.0README 注释明确指出若使用 CUDA 特定版本需要先安装匹配的 torch/torchaudio 组合funasr1.3.26SenseVoice 的推理与训练都深度依赖 FunASR 框架模型注册、CTC 解码、后处理均来自 funasr这一最低版本要求同时被 tests/test_funasr_requirement.py 中的test_funasr_minimum_version_matches_current_examples测试所固化modelscope/huggingface_hub模型权重通过 ModelScope 或 HuggingFace Hub 拉取numpy1.26.4对 NumPy 版本做了上限约束避免与 torch 生态的兼容性问题fastapi0.111.1与gradio分别支撑 API 服务与 WebUI 界面。1.2 四步搭建开发环境按照 CONTRIBUTING.md 的步骤一个干净的开发环境只需四条命令# 1. Fork 并克隆仓库 git clone https://github.com/your-username/SenseVoice.git cd SenseVoice # 2. 创建虚拟环境Windows 下激活命令为 venv\Scripts\activate python3 -m venv venv source venv/bin/activate # 3. 安装依赖 pip install -r requirements.txt # 4. 验证安装 python -c from funasr import AutoModel; print(Installation successful)需要提醒的是当前仓库镜像所在的分支以main为主干Fork 之后记得从main创建自己的开发分支见下文 PR 章节。如果此前安装过旧版 funasr应使用pip install -U funasr1.3.26升级——这一升级提示同样被测试用例test_readmes_explain_upgrade_for_existing_installs验证为 README 三语版本README.md、README_zh.md、README_ja.md的硬性要求。二、没有 GPU 也能跑CPU 运行全方案2.1 直接推理设置 device 为 cpuCONTRIBUTING.md 给出的最小 CPU 推理代码为model AutoModel( modeliic/SenseVoiceSmall, trust_remote_codeTrue, devicecpu, )其中trust_remote_codeTrue是关键模型的自定义代码即本仓库根目录的 model.py内含 SANM 编码器等仓库外不存在的结构需要从远端拉取并本地执行。仓库 demo1.py 展示了完整的 FunASR AutoModel 调用范式——除了model与device还会挂接 VAD 模型from funasr import AutoModel from funasr.utils.postprocess_utils import rich_transcription_postprocess model_dir iic/SenseVoiceSmall model AutoModel( modelmodel_dir, trust_remote_codeTrue, remote_code./model.py, vad_modelfsmn-vad, vad_kwargs{max_single_segment_time: 30000}, devicecuda:0, ) res model.generate( inputf{model.model_path}/example/en.mp3, cache{}, languageauto, # zh, en, yue, ja, ko, nospeech use_itnTrue, batch_size_s60, merge_vadTrue, merge_length_s15, ) text rich_transcription_postprocess(res[0][text]) print(text)将device换成cpu即可在无 GPU 机器上运行。这里的language支持auto/zh/en/yue/ja/ko/nospeech与 api.py 中的Language枚举完全一致。2.2 CPU 模式启动 FastAPI 服务贡献指南同时给出了 API 服务的 CPU 启动方式export SENSEVOICE_DEVICEcpu fastapi run --port 50000SENSEVOICE_DEVICE是贯穿全仓库的运行时开关api.py 第 29 行读取该环境变量并默认回退到cuda:0Dockerfile 则将其默认值设为auto。这意味着你可以在不改代码的前提下通过环境变量切换推理后端设备这也是容器化部署中最重要的可配置项之一。三、如何正确贡献Issue 与 PR 协作规范3.1 报告 Bug四个必备要素CONTRIBUTING.md 要求 Bug 报告遵循以下流程先检索已有 Issue避免重复提交使用 Bug Report 模板保证信息结构统一附上完整环境信息操作系统、Python 版本、PyTorch 版本、GPU 型号、CUDA 版本提供最小可复现代码——这是定位问题的关键参考 demo1.py 或 demo2.py 中十余行的最小调用即可。注意由于仓库镜像环境的限制报告者应优先在本仓库的 Issue 区提交并在描述中说明依赖版本便于维护者用相同环境复现。3.2 解决 Issue 的验收标准指南特别强调了一条容易被忽视的社区规范合并的 PR、绿色的 main 分支或已发布的 release本身并不能证明问题已被解决。一个 Issue 应保持打开状态直到满足以下任一条件报告者在受影响的工作流上确认修复生效或维护者复现了原始失败、在公开可用版本中验证修复、将证据记录在 Issue 中并留出合理的反馈窗口。当修复需要随版本发布时应在 Issue 中链接发布版本并请报告者重新测试后再关闭若仓库提供了 waiting-for-feedback 标签应优先使用该标签而不是把沉默当作确认。3.3 提交 Pull Request 的五步流程# 1. Fork 仓库后从 main 创建新分支 git checkout -b your-branch-name # 2. 做出修改保持 commit 聚焦且原子化 # 3. 运行测试确保没有破坏任何功能 # 4. 推送 fork向 upstream main 分支发起 PR # 5. 在 PR 描述中清楚说明改了什么、为什么改仓库根目录的 tests/ 目录就是测试你的修改的直接依据例如tests/test_funasr_requirement.py校验 README 与 requirements 中 funasr 版本声明的同步性tests/test_long_audio_no_vad.py验证 long_audio_no_vad.py 长音频处理逻辑tests/test_canonical_qwenaudio_links.py 等校验文档链接与仓库契约。若你的改动涉及推理链路建议在本地先跑通 demo1.pyFunASR AutoModel 路径与 demo2.py直接模型推理路径两条入口再提交 PR。3.4 欢迎的贡献类型与代码风格指南明确欢迎以下五类贡献类型具体方向Bug 修复关注带bug标签的 open issue文档改进错别字、澄清说明、补充示例、翻译新示例情绪识别、事件检测、多语种转写等不同用法的 demo 脚本性能优化推理速度或内存占用的优化测试覆盖单元测试与集成测试代码风格要求为遵循仓库现有模式、尽量使用类型注解、新函数/类补充 docstring、单行不超过 120 字符。这些约束在 model.py 与 api.py 中都能看到具体实践。四、仓库结构地图每个文件是干什么的CONTRIBUTING.md 给出了官方目录结构说明结合仓库实际可整理如下SenseVoice/ ├── model.py # 核心 SenseVoiceSmall 模型编码器、CTC 解码器、情绪/事件 embedding ├── api.py # FastAPI 推理服务 ├── webui.py # Gradio Web 界面 ├── demo1.py # 使用 FunASR AutoModel 的推理示例 ├── demo2.py # 直接模型推理支持时间戳输出 ├── export.py # ONNX 模型导出 ├── export_meta.py # 模型重建的导出工具 ├── finetune.sh # 带 DeepSpeed 支持的微调脚本 ├── requirements.txt # Python 依赖 ├── Dockerfile # Docker 构建配置 ├── data/ # 示例训练与验证数据train_example.jsonl / val_example.jsonl ├── utils/ # 工具frontend、ONNX 推理、CTC 对齐、导出 ├── deepspeed_conf/ # DeepSpeed 配置ds_stage1.json ├── runtime/ # llama.cpp 生态的 C 推理实现GGUF 转换、VAD、server └── image/ # 文档图片几处容易被忽略但值得深入的点训练数据格式data/train_example.jsonl 采用逐行 JSON 结构每行包含key、text_language如|en|、|zh|、|ko|、emo_target如|NEUTRAL|、event_target如|Speech|、with_or_wo_itn、target转写文本、target_len、source_len等字段。这些|...|标记与模型输出中的标签体系一一对应是理解数据标注与模型预测格式的关键ONNX 导出链路export.py 与 utils/export_utils.py、utils/model_bin.py 配合可将模型导出为 ONNX 格式C 运行时runtime/ 目录包含 llama.cpp 生态的convert-funasr-to-gguf.py、sensevoice-server等实现是了解边缘部署路径的入口。五、理解模型非自回归编码器的多任务输出5.1 模型能输出什么CONTRIBUTING.md 明确 SenseVoice 是一个非自回归的编码器-only 模型一次性输出四类信息语音转写ASR支持 50 种语言情绪标签HAPPY、SAD、ANGRY、NEUTRAL、FEARFUL、DISGUSTED、SURPRISED音频事件标签BGM、Speech、Applause、Laughter、Cry、Sneeze、Breath、Cough语种识别Language ID普通话、英语、粤语、日语、韩语。5.2 架构与解码原理模型采用SANMSelf-Attention with Normalized Memory编码器 CTC 解码的结构。关键设计是输出 token 分工前 4 个编码器输出 token 用于预测情绪与事件标签其余 token 产生转写文本。从源码结构看model.py 完整实现了这套架构几个核心组件与文档描述一一对应SinusoidalPositionEncoder第 18-48 行基于正弦/余弦位置编码将位置信息注入输入序列MultiHeadedAttentionSANM第 74 行起SANM 注意力层在标准多头注意力forward_attention第 169 行之外额外引入forward_fsmn第 122 行——一个基于深度可分离卷积nn.Conv1dgrouped convolution的 FSMN 记忆模块两者的输出相加第 226 行att_outs fsmn_memory既保留全局注意力能力又注入局部时序建模EncoderLayerSANM第 294 行起编码器层支持normalize_before预归一化、随机深度stochastic depth、以及流式推理所需的forward_chunk带 k/v cache 的块式前向。5.3 后处理rich transcription 与标签清理无论是 demo 脚本还是 API 服务输出文本都经过rich_transcription_postprocess来自funasr.utils.postprocess_utils清洗。在 api.py 中还可以看到更细的流程原始输出raw_text保留clean_text通过正则r\|.*\|剔除所有标签text则是富文本后处理的结果。webui.py中还定义了情绪/事件的 emoji 映射字典如|HAPPY|→ 用于界面展示。六、Docker 部署GPU 与 CPU 两种运行模式CONTRIBUTING.md 给出了三种 Docker 用法# 构建 docker build -t sensevoice . # GPU 运行 docker run --gpus all -p 50000:50000 sensevoice # CPU 运行 docker run -e SENSEVOICE_DEVICEcpu -p 50000:50000 sensevoice结合 Dockerfile 可以还原镜像内部的完整设计基础镜像pytorch/pytorch:2.12.1-cuda12.6-cudnn9-runtime自带 CUDA 12.6 运行时系统依赖安装ffmpeg与libsndfile1音频解码依赖依赖分层缓存先只拷贝requirements.txt安装依赖再拷贝其余代码利用 Docker 层缓存加速重复构建模型预加载可选注释掉的RUN python -c from funasr import AutoModel; AutoModel(modeliic/SenseVoiceSmall)可在构建期预下载权重减少运行时首启等待健康检查内置HEALTHCHECK每 30 秒探测http://127.0.0.1:50000/启动命令CMD [uvicorn, api:app, --host, 0.0.0.0, --port, 50000]即直接运行 api.py 中定义的 FastAPI 应用。容器默认开放 50000 端口与本地fastapi run --port 50000的端口保持一致便于本地与容器行为对齐。七、提交前自检清单与常见问题7.1 贡献前 Checklist结合 CONTRIBUTING.md 与仓库现状提交 PR 前建议逐项确认环境已复现pip install -r requirements.txt可完整通过两条推理路径均正常python demo1.pyAutoModel VAD 链路与python demo2.py直接SenseVoiceSmall.from_pretrainedm.inference含output_timestampTrue时间戳输出都能跑通版本声明同步若改动涉及 funasr 或 torch 依赖同步更新 requirements.txt 与三语 README避免触发 tests/test_funasr_requirement.py 的断言失败运行相关测试至少执行你改动所影响的 tests/ 下测试代码风格合规类型注解、docstring、行宽 ≤ 120PR 描述完整说明 What 与 Why附上复现/验证证据。7.2 常见问题速查模型权重下载失败确认网络可访问 ModelScope/HuggingFace或参考 webui.py 中第 25-35 行的 fallback 逻辑——在线拉取失败时回退到本地缓存目录~/.cache/modelscope/hub/models/iic/SenseVoiceSmall/并设置disable_updateTrue保持离线音频采样率不符api.py 内部统一用torchaudio.transforms.Resample将任意输入重采样到 16 kHzTARGET_FS 16000并做单声道化.mean(0)若你在自定义脚本中直接调用m.inference需自行保证 16 kHz 单声道输入想微调模型参考 finetune.sh 与 data/ 下的 jsonl 示例数据训练/验证集结构见上文第四节。八、协议与社区8.1 许可约定CONTRIBUTING.md 明确一旦向本项目贡献代码即视为同意你的贡献与项目采用相同的许可证。仓库根目录的 LICENSE 为 Apache-2.0模型权重与 FunASR 生态的许可见 FunASR 官方声明Dockerfile 中的镜像 label 也标注了org.opencontainers.image.licensesApache-2.0。8.2 获取帮助使用仓库的 Issue 区提交问题参考模板中的 Bug Report 与 Questions 模板社区联系方式见 README.md#community含钉钉群等渠道对应 image/dingding_sv.png 等文档截图。结语SenseVoice 的贡献链路并不复杂克隆 → 跑通 demo → 定位问题 → 用最小改动修复 → 用测试与双推理路径验证 → 提交清晰描述的 PR。本文所涉及的源码证据model.py、api.py、demo1.py、demo2.py、finetune.sh、Dockerfile、tests/、data/都已按仓库根目录相对路径给出读者可以在继续阅读时随手打开对照让每一步贡献都有据可依。赞分享人工智能大模型语音音频微调本地部署【免费下载链接】SenseVoiceOpen-source SenseVoiceSmall model for Mandarin, Cantonese, English, Japanese, and Korean ASR, language ID, emotion recognition, and audio event detection.项目地址https://gitcode.com/gh_mirrors/se/SenseVoice点击查看免费下载相关推荐mirai 贡献开发指南从搭建构建环境到提交高质量 PR 的完整实战mirai 贡献开发指南从搭建构建环境到提交高质量 PR 的完整实战 mirai 是一个高效率 QQ 机器人支持库其仓库由 mirai core 核心 A即时通讯howdoi 贡献者指南从开发环境搭建、本地运行到提交高质量 PR 的完整实战howdoi 贡献者指南从开发环境搭建、本地运行到提交高质量 PR 的完整实战 导读 本文面向想要为 howdoi https://link.gitcode.开发工具CLIhowdoi 贡献指南从搭建开发环境到提交高质量 PR 的完整实践howdoi 贡献指南从搭建开发环境到提交高质量 PR 的完整实践 本指南以仓库文档 docs/contributing_to_howdoi.md https开发工具CLI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考