• 人工智能
• 大模型
• 语音
• 音频
• 微调
• 本地部署

导读

本文以仓库根目录的 CONTRIBUTING.md 为骨架，系统讲解 SenseVoiceSmall 开源语音模型的本地开发环境搭建、CPU/GPU 运行方式、Issue 与 Pull Request 协作规范，并结合 model.py、api.py、finetune.sh、Dockerfile 等仓库源码，深入剖析模型架构、训练数据格式与容器化部署细节。读完本文，你将能独立完成从"克隆仓库→跑通推理→定位问题→提交修复"的完整贡献闭环。

一、开工前的准备：环境依赖与开发环境搭建

1.1 前置条件（Prerequisites）

官方贡献指南对开发环境的要求非常精简，只有三条：

仓库 requirements.txt 给出了更精确的依赖清单，其中值得注意的版本约束包括：

• torch>=2.12.1与torchaudio>=2.11.0：README 注释明确指出，若使用 CUDA 特定版本，需要先安装匹配的 torch/torchaudio 组合；
• funasr>=1.3.26：SenseVoice 的推理与训练都深度依赖 FunASR 框架（模型注册、CTC 解码、后处理均来自 funasr），这一最低版本要求同时被 tests/test_funasr_requirement.py 中的test_funasr_minimum_version_matches_current_examples测试所固化；
• modelscope/huggingface_hub：模型权重通过 ModelScope 或 HuggingFace Hub 拉取；
• numpy<=1.26.4：对 NumPy 版本做了上限约束，避免与 torch 生态的兼容性问题；
• fastapi>=0.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 "funasr>=1.3.26"升级——这一升级提示同样被测试用例test_readmes_explain_upgrade_for_existing_installs验证为 README 三语版本（README.md、README_zh.md、README_ja.md）的硬性要求。

二、没有 GPU 也能跑：CPU 运行全方案

2.1 直接推理：设置 device 为 "cpu"

CONTRIBUTING.md 给出的最小 CPU 推理代码为：

model = AutoModel( model="iic/SenseVoiceSmall", trust_remote_code=True, device="cpu", )

其中trust_remote_code=True是关键：模型的自定义代码（即本仓库根目录的 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( model=model_dir, trust_remote_code=True, remote_code="./model.py", vad_model="fsmn-vad", vad_kwargs={"max_single_segment_time": 30000}, device="cuda:0", ) res = model.generate( input=f"{model.model_path}/example/en.mp3", cache={}, language="auto", # "zh", "en", "yue", "ja", "ko", "nospeech" use_itn=True, batch_size_s=60, merge_vad=True, merge_length_s=15, ) 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_DEVICE=cpu fastapi run --port 50000

SENSEVOICE_DEVICE是贯穿全仓库的运行时开关：api.py 第 29 行读取该环境变量并默认回退到"cuda:0"，Dockerfile 则将其默认值设为auto。这意味着你可以在不改代码的前提下，通过环境变量切换推理后端设备，这也是容器化部署中最重要的可配置项之一。

三、如何正确贡献：Issue 与 PR 协作规范

3.1 报告 Bug：四个必备要素

CONTRIBUTING.md 要求 Bug 报告遵循以下流程：

1. 先检索已有 Issue，避免重复提交；
2. 使用 Bug Report 模板，保证信息结构统一；
3. 附上完整环境信息：操作系统、Python 版本、PyTorch 版本、GPU 型号、CUDA 版本；
4. 提供最小可复现代码——这是定位问题的关键，参考 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.py（FunASR AutoModel 路径）与 demo2.py（直接模型推理路径）两条入口，再提交 PR。

3.4 欢迎的贡献类型与代码风格

指南明确欢迎以下五类贡献：

代码风格要求为：遵循仓库现有模式、尽量使用类型注解、新函数/类补充 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 架构与解码原理

模型采用SANM（Self-Attention with Normalized Memory）编码器 + CTC 解码的结构。关键设计是输出 token 分工：前 4 个编码器输出 token 用于预测情绪与事件标签，其余 token 产生转写文本。

从源码结构看，model.py 完整实现了这套架构，几个核心组件与文档描述一一对应：

• SinusoidalPositionEncoder（第 18-48 行）：基于正弦/余弦位置编码，将位置信息注入输入序列；
• MultiHeadedAttentionSANM（第 74 行起）：SANM 注意力层，在标准多头注意力（forward_attention，第 169 行）之外，额外引入forward_fsmn（第 122 行）——一个基于深度可分离卷积（nn.Conv1d，grouped 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_DEVICE=cpu -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(model='iic/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 前建议逐项确认：

1. 环境已复现：pip install -r requirements.txt可完整通过；
2. 两条推理路径均正常：python demo1.py（AutoModel + VAD 链路）与python demo2.py（直接SenseVoiceSmall.from_pretrained+m.inference，含output_timestamp=True时间戳输出）都能跑通；
3. 版本声明同步：若改动涉及 funasr 或 torch 依赖，同步更新 requirements.txt 与三语 README，避免触发 tests/test_funasr_requirement.py 的断言失败；
4. 运行相关测试：至少执行你改动所影响的 tests/ 下测试；
5. 代码风格合规：类型注解、docstring、行宽 ≤ 120；
6. PR 描述完整：说明 What 与 Why，附上复现/验证证据。

7.2 常见问题速查

• 模型权重下载失败：确认网络可访问 ModelScope/HuggingFace；或参考 webui.py 中第 25-35 行的 fallback 逻辑——在线拉取失败时回退到本地缓存目录~/.cache/modelscope/hub/models/iic/SenseVoiceSmall/，并设置disable_update=True保持离线；
• 音频采样率不符：api.py 内部统一用torchaudio.transforms.Resample将任意输入重采样到 16 kHz（TARGET_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.licenses="Apache-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/）都已按仓库根目录相对路径给出，读者可以在继续阅读时随手打开对照，让每一步贡献都有据可依。

• 人工智能
• 大模型
• 语音
• 音频
• 微调
• 本地部署