如何给Soup贡献代码AGENTS.md规范、pytest smoke测试与CI矩阵完整指南【免费下载链接】SoupFine-tune LLMs from one YAML. Layer streaming trains an 8B model on a 4 GB laptop GPU.项目地址: https://gitcode.com/GitHub_Trending/soup12/SoupSoup 是一个 CLI 优先的大模型微调工具Python 3.10Apache-2.0 许可一份 YAML 即可启动训练层流式layer streaming技术甚至能在 4 GB 显存的笔记本上微调 8B 模型。想给 Soup 贡献代码本指南带你走通完整链路读懂 AGENTS.md 贡献规范、本地跑通 pytest 测试套件与 smoke 冒烟测试、再理解 GitHub Actions 上 9 格 CI 矩阵是怎么守护每一次提交的。贡献前必读AGENTS.md 规范速览AGENTS.md 是仓库根目录的开发者快速参考卡也面向 AI 编码代理。三条核心命令命令作用pip install -e .[dev]可编辑安装 测试依赖pytest、ruff、mypy、pre-commit 等pytest tests/ -v --tbshort运行测试套件smoke 冒烟测试默认排除ruff check src/soup_cli/ tests/Lint 检查提交前必须干净四条必须遵守的代码约定配置Pydantic v2 定义在 src/soup_cli/config/schema.py是所有配置字段的唯一事实来源懒加载torch、transformers、peft、trl、mlx等重依赖只在函数内部导入绝不在模块顶层——这是 CLI 秒开的秘密输出一律用rich.console.Console禁止裸print()路径安全用os.path.realpathos.path.commonpath做路径包含校验Path.resolve() relative_to()在 Windows 短文件名下会坏。此外行宽 100ruff 启用E, F, I, N, W规则。改功能前先读 docs/README.md 中对应主题的页面完整贡献流程与项目结构见 CONTRIBUTING.md。本地验证虚拟环境与 pytest smoke 测试一键安装开发环境python3 -m venv .venv source .venv/bin/activate # Windows 用 .venv\Scripts\activate pip install -e .[dev]虚拟环境不是可选项较新的 Debian/Ubuntu 遵循 PEP 668直接向系统 Python 装包会被拒绝。.[dev]会顺带拉入完整训练栈torch、transformers、peft、trl、datasets、bitsandbytes、accelerate。理解测试标记unit / integration / smokepyproject.toml 的[tool.pytest.ini_options]定义了 3 个标记这是理解本地测试行为的关键smoke慢速冒烟测试会下载模型并真实训练默认跳过unit快速隔离测试不碰子进程、网络或真实模型integration涉及真实子进程、SQLite、文件系统或 HTTP。默认配置为-m not smoke且要求覆盖率不低于 77%。tests/test_smoke_train.py 用微型模型 tiny-gpt2 验证配置 → 数据加载 → 模型搭建 → 训练 → 输出的完整链路整份文件被标记为pytest.mark.smoke。常用测试命令pytest tests/ -v --tbshort # 全量测试不含 smoke pytest tests/test_config.py -v # 单个测试文件 pytest tests/test_data.py::test_detect_alpaca_format -v # 单条测试 pytest tests/ --covsoup_cli --cov-reporthtml # 带覆盖率 pytest -m smoke -v # 显式跑慢速冒烟测试 日常开发建议改完先跑单文件测试快速反馈推 PR 前再跑一遍全量 ruff check。CI 矩阵解析9 格测试 4 类专项任务CI 定义在 .github/workflows/ci.yml每次 push 与 PR 触发。主测试矩阵是3 个 Python 版本 × 3 个操作系统UbuntuWindowsmacOSPython 3.10✅✅✅Python 3.11✅✅✅Python 3.12✅✅✅矩阵细节很能体现项目对跨平台的重视强制PYTHONUTF81Windows 默认 cp1252 编码在导入上游包时会翻车这是实测踩坑后的修复fail-fast: false某一格红了不影响其余 8 格保证拿到全部信号Hugging Face 模型缓存预先预热 指数退避重试单次 429 限流不会拖红整次运行。矩阵之外还有 4 类专项任务lintruff 检查src/soup_cli/ scripts/ tests/ benchmarks/Python 3.11必过pytorch-smoke每个 PR 跑真实 PyTorch SFT DPO 训练管线即-m smoke单独成任务以免 9 格各跑一遍mlx-smoke在 Apple Silicon runner 上验证 MLX 后端独立安装、与 PyTorch 栈互不污染transformers-floor按 .github/constraints/transformers-floor.txt 固定依赖版本装包守住兼容性下限。并发策略也值得注意同一分支的新运行会取消 PR 上未完成的旧运行省资源但main分支的运行绝不取消——发布流程要求在待打标签的确切提交上有绿色矩阵。提交 PR 前的完整检查清单按 .github/pull_request_template.md 与 CONTRIBUTING.mdruff check src/soup_cli/ scripts/ tests/通过pytest tests/ -v通过需要时更新README.md与 docs/ 对应页面添加 changelog 片段关于 changelog用户可见的 PR 不直接编辑CHANGELOG.md而是在changelog.d/最新版本号/PR编号.类别.md添加片段类别为added、changed、deprecated、removed、fixed、security格式与校验规则见 changelog.d/README.md。新手友好如何迈出第一步认领 issue在 issue 下评论即视为认领评论就是记录缺硬件的 issue 提前说明即可分支命名feature/你的功能名或fix/你的修复名测试先行TDD先写测试再实现到通过Conventional Commitsfeat:、fix:、docs:、test:等前缀让提交信息自解释。 推荐的新手贡献方向新模型 recipe在 src/soup_cli/recipes/ 添加流行模型配置、文档完善、测试补充、带good first issue标签的 bug 修复。每次合并后你会被列入 CONTRIBUTORS.md 与 CHANGELOG 署名贡献的署名是项目的基本约定。祝你的第一个 PR 一次通过 9 格矩阵【免费下载链接】SoupFine-tune LLMs from one YAML. Layer streaming trains an 8B model on a 4 GB laptop GPU.项目地址: https://gitcode.com/GitHub_Trending/soup12/Soup创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考