NeMo Speech 开源协作实战：从 PR 规范、测试与 CI 到代码风格与命名约定

NeMo Speech 开源协作实战从 PR 规范、测试与 CI 到代码风格与命名约定【免费下载链接】SpeechA scalable generative AI framework built for researchers and developers working on Large Language Models, Multimodal, and Speech AI (Automatic Speech Recognition and Text-to-Speech)项目地址: https://gitcode.com/GitHub_Trending/nem/Speech本文基于 NeMo Speech 仓库的 CONTRIBUTING.md 展开系统讲解向该项目提交 Pull Request 的完整流程DCO 签名要求、本地单元测试运行方式含 CPU 模式与模型下载开关、由 copy-pr-bot 驱动的 GitHub CI 触发机制以及类命名约定、Python 代码风格black/isort等工程规范。读完本文你将能够独立完成一次符合项目要求、可通过 CI 检查并送审的 PR。Pull Request 基本准则NeMo 的全部开发都在公开进行社区贡献被明确欢迎。所有 PR 必须指向main分支且提交前需满足以下要点见 CONTRIBUTING.md单一职责一个 PR 只做一件事必须能清晰回答“这个 PR 是干什么的”通读规范阅读下文所述的 General Principles 与代码风格指南签名提交使用git commit -s为每个 commit 添加签名测试先行确保相关单元测试本地全部通过后再发出 PR发起 PR 并请求 Review。DCO 签名Signed-off-by所有贡献都必须签署开发者原创证书Developer Certificate of Origin 1.1。具体做法是在每次提交时通过git commit -s为 commit 追加Signed-off-bytrailer以此确认贡献内容完全或部分由你本人创建且有权以仓库文件所示的开源许可证提交或者基于你有权修改的、受适当开源许可保护的前作并以相同许可证提交或者由已完成上述认证的其他人直接提供且你未做修改你理解本项目及贡献内容均为公开贡献记录包括你提交的所有个人信息含 sign-off将被无限期保存。完整 DCO 1.1 文本随仓库维护在 CONTRIBUTING.md 中可据此核对你所认证的四项声明。本地单元测试的运行方式贡献前最重要的验证手段是跑通相关测试。仓库给出三档运行姿势# 快速本地测试开发中随时跑 pytest # 没有 NVIDIA GPU 时 # pytest -m not pleasefixme --cpu path/to/relevant_tests# 完整测试包含预训练模型下载 pytest -m not pleasefixme --with_downloads path/to/relevant_tests其中path/to/relevant_tests应替换为具体测试目录例如tests/collections/asr。测试标记与 CI 脚本对照--with_downloads并非普通选项而是 tests/conftest.py 中注册的自定义 pytest 选项带with_downloads标记的用例在未加该选项时会被跳过提示需要--with_downloads才会从云端下载并缓存模型。仓库的测试套件中标记为pleasefixme的用例属于已知待修复项因此在日常运行中统一用-m not pleasefixme排除。各测试子集在 CI 中的真实运行方式可参考 tests/functional_tests/ 下以L0_Unit_Tests_开头的脚本。以 tests/functional_tests/L0_Unit_Tests_CPU_ASR_1.sh 为例ASR 第一片 CPU 单测的实际命令为CUDA_VISIBLE_DEVICES NEMO_NUMBA_MINVER0.53 coverage run -a --data-file/workspace/.coverage --source/workspace/ -m pytest \ tests/collections/asr \ --shard-id0 --num-shards6 \ -m not pleasefixme --cpu --with_downloads --relax_numba_compat从中可以读出几个与本地开发直接相关的细节CUDA_VISIBLE_DEVICES屏蔽 GPU配合--cpu标记实现纯 CPU 运行--shard-id0 --num-shards6将同一测试目录按 6 片分片并行执行本地跑全量时可以不必分片分片仅是 CI 提速手段--relax_numba_compat是 tests/conftest.py 中定义的兼容性放宽开关会调用 numba 工具将兼容性检查设为非严格模式用coverage run收集覆盖率并落盘到/workspace/.coverage。原文档特别提醒不同测试子集可能要求不同的环境变量如这里的NEMO_NUMBA_MINVER0.53因此在动手跑某个目录前先查对应L0_Unit_Tests_*.sh脚本中的完整命令是最稳妥的做法。例如L0_Unit_Tests_CPU_Core.sh、L0_Unit_Tests_GPU_ASR_1.sh等脚本分别覆盖 core、ASR、TTS、SpeechLM2 等不同模块的 CPU/GPU 配置。GitHub CI 的触发与运行机制NeMo 的 CI 由 copy-pr-bot 应用驱动该 bot 会把每个 PR 镜像到pull-request/number分支并在推送时触发 workflow。CI自动运行需同时满足以下全部条件PR 内每个 commit 均为 GPG 签名对应 GitHub 的 commit signature verification 机制每个 committer 都是 NVIDIA-NeMo GitHub 组织成员或被列为additional_trusteePR 的 commit 数不超过 249 个。任一条件不满足时copy-pr-bot 会发评论并跳过分支创建CI 不会运行。此时由维护者任何具有 write 权限及以上的成员在 PR 下手动评论触发/ok to test sha其中sha为 PR HEAD commit 的完整或缩写 SHAbot 同样接受/okay to test与/ok-to-test两种写法。若后续有新 push只要 PR 仍处于可信状态bot 会自动同步否则需再次评论新 HEAD 的/ok to test sha。测试与 Lint 的执行规则按变更文件选择性运行CI 依据 PR 变更的文件范围挑选要跑的测试套件某些变更例如仅更新文档可能一条测试都不跑Lint 检查对变更代码执行 flake8 与 pylint任何 lint 错误都需要解决。可以给 PR 加skip-linting标签来忽略 lint 错误但这明确不被鼓励discouraged端到端夜间套件若希望在自己的 PR 上运行 nightly e2e 测试需在 CI 启动前给 PR 加上Run e2e nightly标签。标签只在每次运行起始的pre-flightjob 读取一次因此必须赶在 CI 开始前加好如果加标签时 CI 已在运行需要取消当前 workflow 并通过 push 新 commit 重新触发。CI 相关的 workflow 定义位于仓库的.github/workflows/目录例如 code-linting.yml、cicd-main-unit-tests.yml、cicd-approve-test-queue.yml 等文件可结合上文描述对照实际配置理解各 job 职责端到端测试脚本则集中在 tests/e2e_nightly/ 目录。该找谁 ReviewCONTRIBUTING.md 明确给出送审联系人NeMo core 与 ASR 相关 PRnithinraokTTS 相关 PRblisc。注意有时会有人自行认领 Review 你的 PR遇到这种情况请等待其完成 Review 后再推进。所有 PR 必须在通过全部自动检查与同侪评审后才可合并。通用工程原则贡献代码应遵循七条通用原则原文照录要点User-oriented面向用户宁可多写后台代码也要让最终用户用得轻松Robust健壮让用户难以犯错Well-tested测试充分添加简单、快速的单元测试并为端到端功能考虑增加 CI 测试Reusable可复用每段代码都要考虑未来的复用方式并让复用最容易Readable可读代码以易读为先Legal合法即使只从网络复制一行代码也要确认其许可与 NeMo 支持的许可证兼容并标注出处与链接Sensible合理代码必须讲得通若认为某段代码可能引起困惑就写注释解释。类命名约定与代码库实例命名约定是本项目风格中最具体、也最容易在 Review 中被挑出的部分原文规则为任何位置都不允许使用 “I”、“Interface”、“NM”、“NeMo” 等前后缀核心接口用极简命名Typing、Cloud、Serialization、FileIO核心类用尽可能简单的名字NeuralModule、Model、Graph、Dataset、Loss、ModuleModel 层次结构中的抽象类使用Model后缀MyModel的配置类应命名为MyModelConfig叶子层 Neural Module 类不加任何后缀如AudioPreprocess叶子层 Dataset 用Dataset后缀如AudioToSpeechLabelDataset叶子层 Loss 用Loss后缀如CTCLoss叶子层 Model 不带后缀直接用名称如QuartzNet。这些约定在当前代码库中可以得到逐条印证约定仓库中的实例核心类NeuralModulenemo/core/classes/module.py 中class NeuralModule(Module, Typing, Serialization, FileIO)核心类Modelnemo/core/classes/common.py 中class Model(Typing, Serialization, FileIO, HuggingFaceFileIO)叶子 Dataset 加Dataset后缀nemo/collections/asr/data/audio_to_label.py 中class AudioToSpeechLabelDataset叶子 Loss 加Loss后缀nemo/collections/asr/losses/ctc.py 中class CTCLoss(nn.CTCLoss, Serialization, Typing)叶子 Module 无后缀nemo/collections/asr/modules/audio_preprocessing.py 中class AudioPreprocessor(NeuralModule, ABC)从源码结构看接口Typing、Serialization、FileIO以 Mixin 形式混入核心类与叶子类这与“核心接口用简单名字”的约定一致新贡献的代码只要保持这一继承与命名模式就能与既有体系自然融合。Python 代码风格black isort 自动化检查项目以black为风格指南并且通过 setup.py 内置的StyleCommand统一封装检查与修复。该命令接受两个选项见 setup.pyscope作用范围指定文件或目录fix为真时就地修复问题否则以--check --diff模式只检查并打印差异。标准用法在 NeMo 仓库根目录下执行# 检查改动文件是否通过风格检查 python setup.py style --scope path/to/changed/files # 未通过时自动修复 python setup.py style --scope path/to/changed/files --fix从 setup.py 的实现可以看到style命令实际按顺序执行isort与black两个检查器不带--fix时二者都以--check --diff运行任一项非零退出则打印FAIL并以对应返回码退出因此提交前跑一遍--fix再复验是最省事的流程。除自动化工具外CONTRIBUTING.md 还列出一系列人工风格守则值得逐条对照对用户暴露的每个类与方法都要写 docstring对用户暴露的每个类与方法都使用 Python 3 类型标注避免from X import *除非在X.py中定义了__all__最小化使用**kwargs优先raise Error而非assert写if X: raise Error而不是assert X优先用类而非独立函数方法应当原子化单个方法不超过 75 行大约一屏不滚动方法参数多到一行放不下时每个参数独占一行每个目录都要添加__init__.py优先使用 f-string 而非格式化字符串优先用 logger 而非 print可使用from nemo.utils import logging提供的 logger对应 nemo/utils/nemo_logging.py私有函数以_开头不得在其宿主文件之外被调用多行注释使用而非连续的#。Collections模块的逻辑分组CONTRIBUTING 定义了 Collection 概念Collection 是对相关 Neural Module 的逻辑分组按领域或语义聚合模块向某个 collection 贡献模块时必须确认它确实属于该类别如果想开创一个新 collection 并回馈平台项目同样欢迎。这与仓库的实际目录结构一一对应nemo/collections/ 下划分为asr、tts、audio、common、speechlm2等子包每个子包内部再按models、modules、data、losses等层次组织例如nemo/collections/asr/models/、nemo/collections/asr/modules/。从源码结构看新模块落在哪个 collection、哪一层直接决定了它被测试脚本、文档与 API 索引归入哪个领域这也是 CI “按变更文件选择测试套件”能够工作的前提。提交前自检清单综合原文档要求建议发出 PR 前逐项确认PR 指向main且只解决一件事每个 commit 都执行过git commit -s产生Signed-off-by且已做 GPG 签名目标测试目录已通过本地pytest必要时按 tests/functional_tests/ 中对应L0_Unit_Tests_*.sh补齐环境变量与选项python setup.py style --scope 改动范围全部 PASSflake8/pylint 无新增告警不使用skip-linting标签或确有充分理由新代码符合类命名约定无 NM/NeMo 前后缀、后缀规则正确已按 core/ASR 或 TTS 的分工 对应 Reviewer如需 e2e 夜间测试Run e2e nightly标签已在 CI 启动前加好。遵循以上流程一次面向 NeMo Speech 的贡献就能同时满足署名合规、测试通过、风格一致与领域归属正确四项硬指标显著降低 Review 往返成本。【免费下载链接】SpeechA scalable generative AI framework built for researchers and developers working on Large Language Models, Multimodal, and Speech AI (Automatic Speech Recognition and Text-to-Speech)项目地址: https://gitcode.com/GitHub_Trending/nem/Speech创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考