MLflow 贡献指南从 Issue 提报到多语言开发测试的完整实践【免费下载链接】mlflowThe open source AI engineering platform for agents, LLMs, and ML models. MLflow enables teams of all sizes to debug, evaluate, monitor, and optimize production-quality AI applications while controlling costs and managing access to models and data.项目地址: https://gitcode.com/GitHub_Trending/ml/mlflow本篇指南以 MLflow 官方贡献文档CONTRIBUTING.md为核心骨架面向想要为 MLflow 提交代码、修复 Bug 或改进文档的开发者。你将完整掌握 MLflow 的治理架构与贡献流程、四大类 Issue 的处理方式以及 Python、JavaScript/UI、R、Java 四种语言的开发环境搭建、代码规范、测试运行与 PR 提交流程同时结合仓库内真实的配置文件与源码如 dev/dev-env-setup.sh、.pre-commit-config.yaml、tests/conftest.py进行纵深印证帮助你一次性打通从克隆仓库到首个 PR 合并的全链路。MLflow 的治理结构与核心维护团队MLflow 是一个由社区驱动的大型开源项目其治理由**技术指导委员会Technical Steering CommitteeTSC**负责当前成员包括 Patrick Wendell、Reynold Xin 与 Matei Zaharia。项目的创始技术章程见仓库根目录的 mlflow-charter.pdf。日常维护工作则由以下核心成员Core Members承担他们与数百名社区贡献者共同推动了项目的持续演进Harutaka Kawamura、Weichen Xu、Corey Zumar、Ben Wilson、Serena Ruan、Yuki Watanabe、Daniel Lok、Tomu Hirata、Matt Prahl、Gabriel Fu。理解这一结构的意义在于重大变更significant changes在实施前需要与 committer 达成一致而普通变更则可以更灵活地通过 PR 推进。下文将详细说明这一过程。贡献流程从 Issue 到 PR 合并第一步提交 IssueMLflow 的贡献流程始于提交 GitHub Issue。官方 Issue 政策见仓库根目录 ISSUE_POLICY.md将 Issue 划分为四类功能请求Feature requestsBug 报告Bug reports文档修复Documentation fixes安装问题Installation issues四类 Issue 的详细定义与生命周期都记录在上述政策文档中。第二步等待 Triage 与反馈MLflow committer 会依据 ISSUE_TRIAGE.rst 中的规则主动对 Issue 进行triage分流并回复。官方建议在开始实现功能或补丁之前先等待 committer 或社区成员的反馈。这一点对重大变更尤其重要——此类 Issue 在 triage 阶段通常会被打上needs design标签提示需要先产出设计方案。第三步以 PR 或 Plugin 形式提交变更与 committer 就实现策略达成一致后有两种提交方式向 MLflow 仓库提交 Pull Request官方建议从仓库 fork 的非 master 分支发起以独立 MLflow Plugin 形式发布适合那些可以不进入主仓库、独立迭代的功能。PR 合并后你的变更会自动进入下一个 MLflow 版本并记录在版本发布说明与仓库根目录的 CHANGELOG.md 中。贡献指南设计、兼容性与代码风格为重大变更编写设计文档以下类型的变更被官方明确建议先写设计、再动手实现triage 时会以needs design标签标注对MLflow REST API的变更或新增——REST API 被多种开源与商业平台实现任何改动都会影响这些平台因此官方鼓励开发者先充分探索替代方案引入新的用户面向 MLflow API——API 表面需要能泛化覆盖常见 ML 操作新 API 必须对 ML 开发者广泛有用、易用且简单强大为 MLflow新增库依赖修改关键内部抽象例如 Tracking Artifact Repository、Tracking Abstract Store 与 Model Registry Abstract Store后者位于 mlflow/store 目录下。保持向后兼容MLflow 用户的工作流高度依赖特定的平台与 API 行为因此所有变更都必须仔细评估向后兼容性。除公共 API 外代码中标注了developer_stable注解的 Python API 同样必须保持向后兼容——这类类或方法的功能性变更新增特性、修改行为等会被维护者严格审查并可能被要求追加兼容性测试。在仓库源码中该注解被用于 Tracking 相关的抽象接口例如 mlflow/tracking/context/abstract_context.py、mlflow/tracking/request_header/abstract_request_header_provider.py 等它们正是开发者稳定 API边界的典型代表。优先考虑以 MLflow Plugin 形式实现新功能MLflow Plugins 允许第三方模块与 MLflow 的许多组件集成使你可以独立于主仓库维护和迭代某些功能。以下四类变更特别适合做成 Plugin为 MLflow 制品artifacts支持新的存储平台为特定平台实现新的 Tracking 后端对应mlflow/store/tracking/abstract_store.py的 Abstract Store 抽象为特定平台实现新的 Model Registry 后端对应mlflow/store/model_registry/abstract_store.py的 Abstract Store 抽象自动捕获并记录特定环境中创建的 MLflow Runs 信息。MLflow 还维护了一份社区 Plugin 列表将自己的 Plugin 收录进去是让更多用户了解它的好途径。Python 风格指南Docstrings遵循 Google Python Style Guide代码格式CI 通过 pre-commit Git hooks 使用 prettier、blacken-docs、ruff 以及若干自定义 lint 脚本进行统一格式化。只要代码通过 CI 检查即视为格式正确。本仓库根目录的 .pre-commit-config.yaml 真实反映了这套 lint 体系除 ruff、prettier 外还串联了 mypy、taploTOML 格式、must-have-signoff提交签名校验、mlflow-typo拼写检查、protobuf 格式与 GitHub Actions 工作流校验等近 30 个钩子覆盖面远超文档描述的基础三件套。本地 lint 工具版本应与 CI 保持一致参照 requirements/lint-requirements.txt可用pip show ruff对比本地版本。设置仓库克隆与 submodule仓库包含子模块克隆时必须带上--recurse-submodules# 克隆仓库注意使用 SSH 方式HTTPS 方式可能在分支推送时出现权限错误 git clone --recurse-submodules gitgithub.com:username/mlflow.git # 添加上游仓库 cd mlflow git remote add upstream gitgithub.com:mlflow/mlflow.git如果此前克隆时未带--recurse-submodules补拉子模块git submodule update --init --recursive开发环境搭建与 Python 配置MLflow 的主体代码CLI、Tracking Server、Artifact Repositories 如 S3 或 Azure Blob Storage 后端以及 Python fluent、tracking、model API都是 Python 实现的。官方提供三种环境搭建方式GitHub Codespaces、自动化脚本dev-env-setup.sh、手动配置。标准化的环境能避免不必要的 CI 失败并让本地测试尽可能贴近 CI 执行环境。方式一GitHub Codespaces在 MLflow 仓库主页点击Code→Create codespace等待创建完成即可获得开箱即用的开发环境。方式二自动化脚本 dev-env-setup.sh仓库中的 dev/dev-env-setup.sh 脚本可以自动完成环境创建安装 pyenv若缺失、按最低支持 Python 版本创建 virtualenv、激活环境并安装开发所需依赖并附带断点续跑progress file机制。先查看其帮助dev/dev-env-setup.sh -h脚本实际支持的参数来自 dev/dev-env-setup.sh比文档示例更丰富参数含义默认值-d, --directory虚拟环境安装路径$MLFLOW_HOME/.venvs/mlflow-dev-f, --full安装全部开发依赖支持所有 flavor 与本地全量测试false-q, --quietpip 安装静默模式不输出 stdoutfalse-o, --override覆盖 Python 版本最低支持版本-c, --clean丢弃上次安装进度从头开始—-h, --help显示帮助—一个典型用法使用virtualenv并以最低支持 Python 版本构建环境确保兼容性dev/dev-env-setup.sh -d .venvs/mlflow-dev -q-q用于静默 pip 安装过程。官方建议跟随脚本的全部交互提示完成环境与 git 配置让后续 PR 流程更顺畅。隔离测试特定版本库的典型场景当需要验证某个功能与旧版本库的兼容性时不要污染主开发环境而是用脚本单独建一个可随意修改的环境。例如安装旧版scikit-learn做隔离测试dev/dev-env-setup.sh -d ~/.venvs/sklearn-test -q source ~/.venvs/sklearn-test/bin/activate pip freeze | grep scikit-learn scikit-learn1.0.2 pip install scikit-learn1.0.1 pip freeze | grep scikit-learn scikit-learn1.0.1方式三手动配置Conda / virtualenv适合使用 Conda 或习惯手动流程的开发者。先配置 git 身份用于签名提交git config --global user.name Your Name git config --global user.email yournameexample.com启用官方提供的 pre-commit 钩子它会在提交时校验 Signed-off 签名并执行ruff check --fix与ruff formatpre-commit install --install-hooks随后以源码方式安装 MLflow所有语言与 API 的开发测试都依赖此步官方推荐在独立 conda 环境中进行conda create --name mlflow-dev-env python3.8 conda activate mlflow-dev-env pip install -e .[extras] # 从当前 checkout 安装 mlflow 及部分实用扩展进行开发与测试还需安装测试依赖与测试插件pip install -r requirements/test-requirements.txt pip install -e .[extras] # 从当前 checkout 安装 mlflow pip install -e tests/resources/mlflow-test-plugin # 安装运行部分 MLflow 测试所需的 mlflow-test-plugin若 test requirements 安装失败可能需要先conda install cmakeonnx 依赖 cmake。另外请确保本机已安装 Docker最后安装 pytestpip install pytestJavaScript 与 UI 开发MLflow UI 使用 JavaScript 编写运行 dev server 与 tracking UI 需要yarn用yarn -v验证是否在 PATH 中。安装 Node 模块macOS 上先安装 node 模块所需的系统依赖brew install pixman cairo pango jpegLinux/Windows 用户请用各自平台的包管理器安装对应依赖。随后在仓库内安装 JS 依赖cd mlflow/server/js yarn install cd - # 返回仓库根目录如果修改了mlflow/server/js/package.json中的依赖需要在mlflow/server/js下运行yarn upgrade更新依赖。启动开发版 UI官方推荐运行 JavaScript Dev Server——否则 tracking 前端会请求mlflow/server/js/build目录下的文件而该目录并未纳入 git。需要在两个终端分别执行终端一启动 MLflow servermlflow server终端二启动 JS dev servercd mlflow/server/js yarn startDev Server 运行于http://localhost:3000MLflow server 运行于http://localhost:5000展示./mlruns中记录的 runs。注意部分 macOS 版本上 Airplay Receiver 进程默认占用 5000 端口会导致网络请求失败。可在系统设置中禁用该进程或改用其他端口例如mlflow server --port 8000。使用非默认端口时需在运行yarn start前设置环境变量MLFLOW_PROXYtracking_server_uriMLFLOW_DEV_PROXY_MODEfalse完整示例$ mlflow server --port 8000 ... (另一个终端) $ export MLFLOW_PROXYhttp://127.0.0.1:8000 $ export MLFLOW_DEV_PROXY_MODEfalse $ yarn install $ yarn start ... (UI 即可在 localhost:3000 访问)测试 React 组件测试文件应与组件放在同一目录例如CompareRunBox.test.js与CompareRunBox.js同目录然后在mlflow/server/js下运行# 运行 CompareRunBox.test.js 中的测试 yarn test CompareRunBox.test.js # 运行 CompareRunBox.test.js 中名称匹配 plot 的测试 yarn test CompareRunBox.test.js -t plot # 运行全部测试 yarn testLint JavaScript 代码在mlflow/server/js下运行注意该命令只修复可自动修复的问题如去除行尾空白yarn lint:fixR 语言贡献R 封装位于mlflow/R/mlflow包含 Projects、Tracking、Models 组件的 R 包装依赖 Python 包因此需先完成前述 Python 环境配置并安装 Python 包注意不要加-e标志因为 R 测试会通过 CLI 运行 MLflow UI基于开发 tracking server 时无法工作pip install .然后安装 R 及其构建依赖cd mlflow/R/mlflow NOT_CRANtrue Rscript -e install.packages(devtools, repos https://cloud.r-project.org) NOT_CRANtrue Rscript -e devtools::install_deps(dependencies TRUE)构建 R 客户端R CMD build .运行测试R CMD check --no-build-vignettes --no-manual --no-tests mlflow*tar.gz cd tests NOT_CRANtrue LINTR_COMMENT_BOTfalse Rscript ../.run-tests.R cd -运行 linterRscript -e lintr::lint_package()开发时若想让 R 端同步 Python 改动可在mlflow/R/mlflow下执行Rscript -e reticulate::conda_install(r-mlflow, ../../../., pip TRUE)R 代码命名与风格请遵循 Advanced R Style Guide。若 PR 涉及 API 变更需按Writing Docs一节重新生成并提交 API 文档。Java 贡献Java 代码位于mlflow/java/核心模块是 Java Tracking API 客户端mlflow/java/client。其他 Java 功能如制品存储依赖 Python 包因此同样先完成 Python 环境配置再安装 Java 8 JDK 与 Maven然后构建并测试cd mlflow/java mvn compile test涉及 API 变更的 PR 同样需要重新生成并提交 API 文档。Python 贡献测试编写与运行编写 Python 测试如果 PR 引入了尚无测试覆盖的代码如新增 flavor、为 flavor 增加 autolog 支持等应在tests下对应文件中补充测试若无合适文件则新建以test_前缀命名的文件pytest 会自动收集。需要 tracking URI 的测试可使用 pytest fixturetracking_uri_mock——它已由 tests/conftest.py 自动为每个测试建立测试运行前自动装配 mock tracking URI结束后自动拆除。默认情况下runs 会记录在每个测试独立的本地临时目录中并在测试结束后立即清理。如需禁用该行为为测试函数添加pytest.mark.notrackingurimock装饰器即可该 marker 在 conftest 中注册且tracking_uri_mock会检查该 marker 来决定是否装配 mock URI。运行 Python 测试先统一代码格式MLflow 使用 ruff 保证风格一致ruff format . ruff check .然后验证单测与 linter 全部通过pre-commit run --all-files pytest tests --quiet --requires-ssh --ignore-flavors --serve-wheel \ --ignoretests/examples --ignoretests/evaluate按目录或文件运行测试pytest tests/pyfunc注意部分模型测试隔离性不佳同一 Python 进程中运行可能 OOM直接执行pytest或pytest tests未必可行。运行多个模型测试时建议用独立的 pytest 调用例如pytest tests/sklearn pytest tests/tensorflow。涉及 API 新增或变更的 PR需要同步更新 Python 文档并提交。新增 Python Model Flavors 的工程配置为某个新框架添加 flavor 支持时需要修改 CI 配置让测试正确运行通常涉及.github/workflows/master.yml在带--ignore-flavors标志的 pytest 命令中把新 flavor 测试加入忽略列表并与其他框架测试一样为你的测试单独添加一条 pytest 命令避免 OOMrequirements/test-requirements.txt将框架及其版本加入依赖列表。Python Server构建 Protobuf 文件运行./dev/generate-protos.sh即可生成 protobuf 文件所需protoc版本为3.19.4可从 protobuf 官方发布页获取对应系统的安装包如 64 位 macOS 的protoc-3.19.4-osx-x86_64.zip。或者直接在 PR 上评论/autoformat自动编译 protobuf 并更新生成代码。更新后用./dev/test-generate-protos.sh验证.proto文件与生成代码保持同步。Python Server数据库 Schema 变更MLflow Tracking 组件支持将实验与 run 数据存入 SQL 后端。修改 tracking 数据库 schema 时需要基于 Alembic 生成迁移脚本Alembic 配置文件位于 mlflow/store/db_migrations/alembic.ini# 从项目根目录开始 $ pwd ~/mlflow $ cd mlflow # MLflow 依赖 Alembic 进行 schema 迁移 $ alembic -c mlflow/store/db_migrations/alembic.ini revision -m add new field to db Generating ~/mlflow/mlflow/store/db_migrations/versions/b446d3984cfa_add_new_field_to_db.py # 更新 schema 文件 $ ./tests/db/update_schemas.sh生成的迁移脚本如mlflow/store/db_migrations/versions/12341123_add_new_field_to_db.py需要你继续编辑以补充迁移逻辑。编写 MLflow 示例Examplesmlflow/examples目录收录了快速上手教程与各种展示 tracking、project、model flavors、model registry 与 serving 用例的简单示例。官方要求示例尽量简短、贴近真实用户工作流并说明如何运行。贡献新的 model flavor 示例先按Python Model Flavors完成配置在mlflow/examples/new-model-flavor创建目录并实现训练代码将目录内容转换成可执行的 MLflow Project补充README.md、MLproject、conda.yaml等文件再按mlflow/test/examples/README.md对应目录为 tests/examples在test/examples/test_examples.py中添加 pytest 条目最后在mlflow/examples/README.md中补充简介贡献 quickstart欢迎对quickstart/mlflow_tracking.py做使其更清晰、更简洁的修改对应文件位于 examples/quickstart/mlflow_tracking.py其他类别的示例在mlflow/examples/new-program-name创建有意义的目录并实现代码附带带运行说明的README.md同样添加 pytest 条目与 examples 总 README 简介。提交 PR 前务必验证所有 Python 测试通过。构建可分发产物若需从本地分支构建完整可用的 MLflow 版本用于测试或本地补丁修复先安装 Node 模块然后生成 JS 文件并构建 wheelcd mlflow/server/js yarn build cd - python -m build # 在 dist/ 下生成 pip 可安装的 wheel 与压缩源码包其他工程实践TOML 格式仓库使用 taplo 强制 TOML 格式一致对应钩子也已在 .pre-commit-config.yaml 中注册taplo format可先安装 taplo CLI。在 IDE 中排除符号链接mlflow/skinny是指向../mlflow的符号链接会导致搜索结果出现重复条目。排除方式VSCode设置中搜索search.followSymlinks并设为falsePyCharm右键skinny/mlflow选择Mark Directory as→Excluded。编写文档DocsMLflow 文档有两套独立构建系统API DocsAPI 参考由 Sphinx 管理内容主要来自以 reStructuredTextRST编写的 Python docstrings。构建说明见 docs/api_reference/README.mdMain Docs主文档含特性文档、教程等使用 Docusaurus 编写唯一前置条件是 NodeJS 18.0。入门说明见 docs/README.md。签署你的工作Sign your workMLflow 遵循 Developer Certificate of OriginDCO1.1 协议提交代码即表示你证明自己编写了该补丁或有权利以开源补丁形式提交。认证条款a–d的完整内容见原文档核心要点是每个 git commit message 都必须添加签名行Signed-off-by: Jane Smith jane.smithemail.com签名必须使用真实姓名不接受笔名或匿名贡献。配置好user.name与user.email后可用git commit -s自动签名。重要未签名的提交将导致 PR 无法合并仓库中的 pre-commit 配置.pre-commit-config.yaml 中的must-have-signoff钩子已在prepare-commit-msg阶段强制校验签名行从工具链层面保障了该规则。行为准则所有贡献者请遵守 MLflow 的贡献者公约行为准则详见仓库根目录 CODE_OF_CONDUCT.rst。【免费下载链接】mlflowThe open source AI engineering platform for agents, LLMs, and ML models. MLflow enables teams of all sizes to debug, evaluate, monitor, and optimize production-quality AI applications while controlling costs and managing access to models and data.项目地址: https://gitcode.com/GitHub_Trending/ml/mlflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考