mlops-python-package

mlops-python-package 是一个专为机器学习运维（MLOps）打造的 Python 项目模板，旨在帮助团队快速启动并标准化数据管道与模型开发流程。它解决了 MLOps 实践中常见的代码结构混乱、工具链分散以及缺乏统一规范等痛点，让开发者无需从零搭建基础设施，即可拥有具备生产级质量的代码库。

这款工具特别适合从事机器学习工程化的开发人员、数据科学家以及希望构建稳健 AI 平台的团队使用。其核心亮点在于“开箱即用”的最佳实践集成：在代码质量方面，内置了 Ruff 格式化、Mypy 类型检查及 Pytest 测试框架；在配置管理上，结合 OmegaConf 与 Pydantic 实现灵活且安全的参数验证；同时原生支持 MLflow 进行模型追踪与注册，并配备 GitHub Actions 自动化流水线。此外，它还提供了从数据校验（Pandera）到文档生成的完整工具链。通过 mlops-python-package，用户可以专注于核心算法与业务逻辑，轻松构建灵活、健壮且易于维护的机器学习系统。

某金融科技公司的数据科学团队正在构建一个实时反欺诈模型，需要频繁迭代算法并满足严格的合规审计要求。

没有 mlops-python-package 时

环境混乱难复现：每位成员自行配置依赖和目录结构，导致“在我机器上能跑”的代码无法在测试或生产环境中运行。
质量管控靠人工：缺乏统一的代码格式化、类型检查和安全性扫描流程，低级错误常流入生产环节，引发线上故障。
模型追踪缺失：实验参数、数据集版本和模型指标散落在本地笔记或临时文件中，无法满足审计对模型全生命周期可追溯的要求。
部署流程繁琐：从代码提交到生成 Docker 镜像缺乏自动化流水线，每次发布需手动打包，耗时且容易出错。

使用 mlops-python-package 后

标准化项目骨架：直接套用预置的最佳实践模板，统一了配置管理（OmegaConf）、数据结构（Pandera）和日志规范，确保任何环境下一键复现。
自动化质量门禁：集成 Ruff、Mypy 和 Bandit 等工具至 Git 钩子与 CI 流程，自动拦截格式错误、类型不匹配及安全漏洞，代码质量显著提升。
全链路模型治理：内置 MLflow 支持，自动记录实验轨迹、注册模型版本并关联数据血缘，轻松生成符合合规要求的审计报告。
一键持续交付：基于 GitHub Actions 构建标准化流水线，实现从代码提交到 Wheel 包发布及 Docker 镜像构建的全自动化，发布效率提升数倍。

mlops-python-package 通过提供一套工业级的标准模板与自动化工具链，将碎片化的 MLOps 实践转化为高效、可靠且可审计的工程体系。

MLOps Python 包

此仓库包含一个基于最佳实践的 Python 代码库，旨在支持您的 MLOps 计划。

该包利用多种工具和技巧来使您的 MLOps 体验尽可能灵活、稳健且高效。

您可以将此包用作 MLOps 工具箱或平台的一部分（例如，模型注册表、实验跟踪、实时推理等）。

相关资源：

LLMOps 编码包（示例）：包含最佳实践和工具的示例，用于支持您的 LLMOps 项目。
MLOps 编码课程（学习）：学习如何创建、开发和维护最先进的 MLOps 代码库。
Cookiecutter MLOps 包（模板）：开始构建和部署用于 MLOps 任务的 Python 包和 Docker 镜像。
智能体技能（资源）：通过标准化的 MLOps 和编码技能提升您的 AI 智能体能力。

安装

本节详细介绍了启动您的 MLOps 项目所需的条件、操作步骤及后续安排。

先决条件

Python>=3.13：以充分利用最新功能和性能改进
uv>=0.5.5：用于初始化项目的虚拟环境及其依赖项

安装

将此 GitHub 仓库克隆到您的计算机

# 推荐使用 SSH
$ git clone git@github.com:fmind/mlops-python-package
# 或使用 HTTPS
$ git clone https://github.com/fmind/mlops-python-package

使用 uv 运行项目安装

cd mlops-python-package/
uv sync

根据您的需求调整代码库

后续步骤

在此基础上，您可以通过多种方式将此包集成到您的 MLOps 平台中。

例如，您可以使用 Databricks 或 AWS 作为计算平台和模型注册表。

具体如何调整包中的代码以适配您的目标解决方案，完全取决于您自己。祝您成功！

使用方法

本节介绍如何配置项目代码并在您的系统上执行它。

配置

您可以在 confs/ 文件夹中添加或编辑配置文件，以更改程序的行为。

# confs/training.yaml
job:
  KIND: TrainingJob
  inputs:
    KIND: ParquetReader
    path: data/inputs_train.parquet
  targets:
    KIND: ParquetReader
    path: data/targets_train.parquet

此配置文件指示程序启动一个 TrainingJob，包含两个参数：

inputs: 包含模型输入的数据集
targets: 包含模型目标的数据集

您可以在 src/[package]/jobs/*.py 文件中找到程序的所有参数。

您还可以使用 uv run bikes --schema 打印该包支持的完整模式。

执行

在开发过程中，您可以使用 uv 来执行项目代码：

uv run [package] confs/tuning.yaml
uv run [package] confs/training.yaml
uv run [package] confs/promotion.yaml
uv run [package] confs/inference.yaml
uv run [package] confs/evaluations.yaml
uv run [package] confs/explanations.yaml

在生产环境中，您可以将项目构建、打包并作为 Python 包运行：

uv build
uv publish # 可选
python -m pip install [package]
[package] confs/inference.yaml

您也可以将此包安装为库，供其他 AI/ML 项目使用：

from [package] import jobs

job = jobs.TrainingJob(...)
with job as runner:
    runner.run()

附加提示：

您可以通过命令行使用 --extras 标志传递额外的配置
- 可用于传递运行时值（例如，先前作业执行的结果）
您可以在命令行中传递多个配置文件，它们会从左到右合并
- 您可以定义作业之间共享的通用配置（例如，模型参数）
由于 Pydantic 的区分联合类型，将自动选择正确的作业任务
- 这是运行应用程序支持的任何作业（训练、调参等）的绝佳方式

自动化

此项目包含多项自动化任务，可轻松重复常见操作。

您可以通过命令行或 VS Code 扩展调用这些操作。

# 执行项目 DAG
$ just project
# 创建代码归档
$ just package
# 列出其他操作
$ just

可用任务：

default # 显示帮助信息

[check]
check # 运行检查任务
check-code # 检查代码质量
check-coverage numprocesses="auto" cov_fail_under="80" # 检查代码覆盖率
check-format # 检查代码格式
check-security # 检查代码安全
check-test numprocesses="auto" # 检查单元测试
check-type # 检查代码类型

[clean]
clean # 运行清理任务
clean-build # 清理构建文件夹
clean-cache # 清理缓存文件夹
clean-constraints # 清理约束文件
clean-coverage # 清理覆盖率文件
clean-docs # 清理文档文件夹
clean-environment # 清理环境文件
clean-mlruns # 清理 mlruns 文件夹
clean-mypy # 清理 mypy 文件夹
clean-outputs # 清理输出文件夹
clean-pytest # 清理 pytest 缓存
clean-python # 清理 Python 缓存
clean-requirements # 清理需求文件
clean-ruff # 清理 ruff 缓存
clean-venv # 清理 venv 文件夹

[commit]
commit-bump # 提升包版本
commit-files # 提交包
commit-info # 获取提交信息

[doc]
doc # 运行文档任务
doc-build format="google" output="docs" # 构建文档
doc-serve format="google" port="8088" # 提供文档服务

[docker]
docker # 运行 Docker 任务
docker-build tag="latest" # 构建 Docker 镜像
docker-compose # 启动 Docker Compose
docker-run tag="latest" # 运行最新版 Docker 镜像

[format]
format # 运行格式化任务
format-import # 格式化代码导入
format-source # 格式化代码源

[install]
install # 运行安装任务
install-hooks # 安装 Git 钩子
install-project # 安装项目
install-rulesets # 安装 GitHub 规则集

[mlflow]
mlflow # 运行 MLflow 任务
mlflow-doctor # 运行 MLflow 医生
mlflow-serve host="127.0.0.1" port="5000" uri="./mlruns" # 启动 MLflow 服务器

[package]
package # 运行打包任务
package-build constraints="constraints.txt" # 构建 Python 包
package-constraints constraints="constraints.txt" # 构建包约束

[project]
project # 运行项目任务
project-environment # 导出环境文件
project-requirements # 导出需求文件
project-run job # 使用 MLflow 运行项目作业

工作流

此包在 .github/workflows 中支持两个 GitHub 工作流：

check.yml: 在每次 Pull Request 上验证包的质量
publish.yml: 在代码发布时构建并发布文档和包。

您可以使用并扩展这些工作流来自动化重复性的包管理任务。

工具

本节旨在鼓励使用开发者工具来提升您的编码体验。

自动化

预定义的操作，用于自动化您的项目开发。

AI 助手：Gemini Code Assist

动机：
- 提高您的编码效率
- 获取代码建议和补全
- 减少审查代码的时间
局限性：
- 可能生成错误的代码、评论或摘要

提交：Commitizen

动机：
- 格式化您的代码提交
- 生成标准的变更日志
- 与 SemVer 和 PEP 440 良好集成
局限性：
- 新用户的学习曲线较长
替代方案：
- 自己动手 (DIY)

Dependabot：Dependabot

动机：
- 避免安全问题
- 避免破坏性更改
- 更新您的依赖项
局限性：
- 可能破坏您的代码
替代方案：
- 自己动手 (DIY)

Git 钩子：Pre-Commit

动机：
- 在提交前本地检查您的代码
- 避免在 CI/CD 上浪费资源
- 可以执行额外的动作（例如，清理文件）
局限性：
- 在提交前增加开销
替代方案：
- Git 钩子：使用起来不太方便

任务：Just

动机：
- 自动化项目工作流
- 语法清晰，优于其他工具
- 在功能强大与简单易用之间取得了良好平衡
局限性：
- 大多数开发者并不熟悉
替代方案：
- Make：最流行，但语法糟糕
- PyInvoke：符合 Python 风格，但冗长且不够直观

CI/CD

在代码推送和发布时执行自动化工作流。

运行器：GitHub Actions

动机：
- 原生集成于 GitHub
- 工作流语法简单
- 如有需要可进行大量配置
局限性：
- SaaS 服务
替代方案：
- GitLab：可部署在本地

CLI

与系统命令行界面（CLI）的集成。

解析器：Argparse

动机：
- 提供 CLI 参数
- 内置于 Python 运行时
- 对于提供配置已足够
局限性：
- 对于高级解析较为冗长
替代方案：
- Typer：代码类型化更胜一筹
- Fire：简单但无类型化
- Click：更为冗长

日志记录：Loguru

动机：
- 向用户展示进度
- 开箱即用，效果良好
- 日志语法更加清晰
局限性：
- 不允许偏离基础用法
替代方案：
- Logging：默认可用，但显得有些过时

代码

项目源代码的编辑、验证和版本控制。

覆盖率：Coverage

动机：
- 报告被测试覆盖的代码
- 确定待测试的代码路径
- 向用户展示代码成熟度
局限性：
- 无
替代方案：
- Pytest Cov：一个使用 coverage.py 来衡量代码覆盖率的 Pytest 插件。

编辑器：VS Code

动机：
- 开源
- 免费、简单且开源
- 拥有优秀的 Python 开发插件
局限性：
- 需要为 Python 进行一些配置
替代方案：
- PyCharm：功能强大，但价格昂贵
- Vim：我非常喜欢它，不过也有 VS Code 插件
- Spacemacs：我更喜欢它，但并非所有人都喜欢 LISP

格式化：Ruff

动机：
- 相较于其他工具速度极快
- 不必浪费时间整理代码
- 使代码更具可读性和可维护性
局限性：
- 仍处于 0.x 版本，但采用率越来越高
替代方案：
- YAPF：配置选项过多，而你可能并不需要
- Isort + Black：速度较慢，且需使用两种工具

质量：Ruff

动机：
- 提升代码质量
- 相较其他工具速度极快
- 与 VS Code 的出色集成
局限性：
- 无
替代方案：
- PyLint：系统过于复杂且运行缓慢
- Flake8：插件过多，实践中我更倾向于 Pylint

安全性：Bandit

动机：
- 检测安全问题
- 作为 linting 解决方案的补充
- 使用和启用都不算复杂
局限性：
- 无
替代方案：
- 无

测试：Pytest

动机：
- 编写测试，否则将付出代价
- 极易编写新的测试用例
- 拥有大量优秀的插件（xdist、sugar、cov 等）
局限性：
- 默认不支持并行执行
替代方案：
- Unittest：语法更为冗长，趣味性较低

类型检查：Mypy

动机：
- 静态类型检查很酷！
- 可以明确类型用途
- Python 的官方类型检查工具
局限性：
- 复杂类型检查可能会带来额外开销
替代方案：
- PyRight：由微软负责大型代码库的检查
- PyType：由 Google 负责大型代码库的检查
- Pyre：由 Facebook 负责大型代码库的检查

版本控制：Git

动机：
- 如果不进行版本控制，那真是愚蠢
- 最流行的源代码管理工具（还能有什么选择呢？）
- 提供钩子，可在特定事件发生时执行自动化操作
局限性：
- Git 可能比较难掌握：https://xkcd.com/1597/
替代方案：
- Mercurial：过去很喜欢它，但现在 Git 才是唯一的选择

配置

管理项目的配置文件，以便调整执行行为。

格式：YAML

动机：
- 在不修改代码的情况下改变执行方式
- 语法易读，支持注释
- 可以使用 OmegaConf <3
局限性：
- Python 默认不支持 YAML
替代方案：
- JSON：无注释，语法更为冗长
- TOML：不太适合配置合并或共享

解析器：OmegaConf

动机：
- 解析并合并 YAML 文件
- 功能强大，不会妨碍你的工作
- 几行代码就能完成大量任务
局限性：
- 不支持远程文件（如 s3、gcs 等）
  - 可以将其与 cloudpathlib 结合使用
替代方案：
- Hydra：功能强大，但会干扰你的工作
- DynaConf：更适合应用程序开发

文件读取器：Cloudpathlib

动机：
- 从云存储中读取文件
- 与云平台的集成更好
- 支持多个平台：AWS、GCP 和 Azure
局限性：
- 目前对 Python 类型的支持还不够完善
替代方案：
- 云 SDK（GCP、AWS、Azure 等）：厂商专用，对于此任务来说过于复杂

验证器：Pydantic

动机：
- 在执行前验证配置
- Pydantic 应该是内置的（就这么简单）
- 极大地增强你的 Python 类
局限性：
- 无
替代方案：
- Dataclass：更简单，但功能弱得多
- Attrs：没有验证功能，使用起来也不太直观

数据

定义数据集，以提供数据输入和输出。

容器：Pandas

动机：
- 将数据文件加载到内存中
- Python 的通用数据交换格式
- 最流行的选择
局限性：
- 存在许多陷阱 gotchas
替代方案：
- Polars：更快、更安全，但集成较少
- Pyspark：功能强大、流行、分布式，但开销较大
- Dask、Ray、Modin、Vaex 等：集成度较低（尽管外观上与 Pandas 类似）

格式：Parquet

动机：
- 将数据存储在磁盘上
- 列式存储（非常适合分析）
- 比基于文本的格式更高效、更安全
局限性：
- 无
替代方案：
- CSV：人类可读，但这也是其唯一优点
- Avro：适合行式工作流的良好替代方案

模式：Pandera

动机：
- 为 DataFrame 提供类型注解
- 明确数据字段的含义
- 支持 Pandas 及其他库 others
局限性：
- 无
替代方案：
- Great Expectations：功能强大，但集成难度大得多

文档

生成并分享项目文档。

API：pdoc

动机：
- 与他人共享文档
- 工具简单，仅用于生成 API 文档
- 快速完成任务，不拖后腿
局限性：
- 仅支持 API 文档（即无法生成自定义文档）
替代方案：
- Sphinx：功能更全面，但对于简单项目来说过于复杂
- Mkdocs：功能更全面，但设置更为繁琐

格式：Google

动机：
- 公认的 docstring 风格
- 是所有选项中最易编写的
- 为了简洁，我通常只写一行
局限性：
- 无
替代方案：
- Numpy：编写起来较困难
- Sphinx：风格过于繁复

托管：GitHub Pages

动机：
- 设置简单
- 免费且便捷
- 与 GitHub 无缝集成
局限性：
- 仅支持静态内容
替代方案：
- ReadTheDocs：提供更多功能

模型

处理机器学习模型的工具集。

评估：Scikit-Learn Metrics

动机：
- 提供常用指标
- 避免重复造轮子
- 避免实现错误
局限性：
- 可选择的指标种类有限
替代方案：
- 自行实现：用于自定义指标

格式：Mlflow Model

动机：
- 标准化的机器学习模型格式
- 存储模型依赖项
- 拥有强大的社区生态
局限性：
- 无
替代方案：
- Pickle：开箱即用，但不适合大型数组
- ONNX：非常适合深度学习，但与其他框架的兼容性无法保证 no guaranteed compatibility for the rest

注册表：Mlflow Registry

动机：
- 保存和加载模型
- 将生产环境与消费环境分离
- 流行、开源，可在本地系统上运行
局限性：
- 无
替代方案：
- Neptune.ai：SaaS 解决方案
- Weights and Biases：SaaS 解决方案

追踪：Mlflow Tracking

动机：
- 跟踪指标和超参数
- 可以比较不同模型的表现
- 流行、开源，可在本地系统上运行
局限性：
- 无
替代方案：
- Neptune.ai：SaaS 解决方案
- Weights and Biases：SaaS 解决方案

包

定义并构建现代 Python 包。

变更日志：Changelog

动机：
- 向用户传达变更信息
- 可以使用 Commitizen 更新
- 遵循 Keep a Changelog 的标准化格式
局限性：
- 无
替代方案：
- 无

格式：Wheel

动机：
- 具有多项优势 has several advantages
- 创建源代码归档
- 当前最现代的 Python 格式
局限性：
- 不包含 C/C++ 依赖项（例如 CUDA）
  - 即在这种情况下应使用 Docker 容器
替代方案：
- Source：较旧的格式，功能较弱
- Conda：速度慢且难以管理

管理器：uv

动机：
- 定义并构建 Python 包
- 快速且符合标准的包管理器
- 将所有元数据打包成一个静态文件
局限性：
- 无法添加 Python 之外的依赖项（例如 CUDA）
  - 即在这种情况下应使用 Docker 容器
替代方案：
- Setuptools：动态文件速度较慢且风险较高
- Poetry：该包的前身解决方案
- Pdm、Hatch、PipEnv：https://xkcd.com/1987/

运行时：Docker

动机：
- 创建隔离的运行环境
- 容器已成为事实上的标准
- 可以将 C/C++ 依赖项随项目一起打包
局限性：
- 有些公司可能会阻止使用 Docker Desktop，此时应考虑其他替代方案
替代方案：
- Conda：解析速度慢且资源占用高

编程

选择你的编程环境。

语言：Python

动机：
- 非常适合 AI/ML 项目
- 功能强大，拥有丰富的工具支持
- 数百个优秀的库
局限性：
- 如果没有 C 绑定，性能较慢
替代方案：
- R：专用语言
- Julia：专用语言

版本：Uv

动机：
- 在不同 Python 版本之间切换
- 允许选择最佳版本
- 支持全局和局部调度
局限性：
- 需要进行一些 shell 配置
替代方案：
- 手动安装：耗时较长
- PyEnv：基于 shell，需要更多设置

可观测性

可复现性：Mlflow Project

动机：
- 共享通用的项目格式
- 确保项目可以被重复使用
- 避免项目执行中的随机性
局限性：
- Mlflow Project 最适合小型项目
替代方案：
- DVC：同时管理数据和模型
- Metaflow：专注于机器学习
- Apache Airflow：适用于大型项目

监控：Mlflow Evaluate

动机：
- 计算模型指标
- 使用阈值验证模型
- 进行训练后的评估
局限性：
- Mlflow Evaluate 的功能相比其他工具较为有限
替代方案：
- Giskard：开源核心且功能非常全面
- Evidently：开源工具，提供更丰富的指标
- Arize AI：功能更强大，但灵活性较低
- Graphana：需要自行完成所有工作

告警：Plyer

动机：
- 解决方案简单
- 在系统上发送通知
- 跨平台：Mac、Linux、Windows
局限性：
- 不应用于大型项目
替代方案：
- Slack：面向聊天的解决方案
- Datadog：面向基础设施的解决方案

血缘关系：Mlflow Dataset

动机：
- 将信息存储在 Mlflow 中
- 跟踪运行时数据集的元数据
- 保留数据集来源的 URI（例如网站）
局限性：
- 功能不如其他解决方案丰富
替代方案：
- Databricks Lineage：仅限于 Databricks
- OpenLineage 和 Marquez：开源且灵活

可解释性：SHAP

动机：
- 最流行的工具包
- 支持多种模型（线性模型等）
- 可通过 SHAP 模块与 Mlflow 集成
局限性：
- 处理大规模数据集时速度极慢
- Mlflow SHAP 模块尚不成熟
替代方案：
- LIME：目前已不再维护

基础设施：Mlflow System Metrics

动机：
- 跟踪基础设施信息（RAM、CPU 等）
- 与 Mlflow 跟踪系统集成
- 提供硬件洞察
局限性：
- 功能不如其他解决方案成熟
替代方案：
- Datadog：流行且成熟的解决方案

技巧

本节提供一些技巧和窍门，以提升开发体验。

AI/ML 实践

数据目录

应将数据指针与其访问方式解耦。

在代码中，您可以使用标签（如 inputs、targets）来引用数据集。

然后，可以在配置文件中将这些标签与具体的读写器实现关联：

  inputs:
    KIND: ParquetReader
    path: data/inputs_train.parquet
  targets:
    KIND: ParquetReader
    path: data/targets_train.parquet

在此软件包中，实现位于 src/[package]/io/datasets.py，并通过 KIND 来选择。

超参数优化

应使用优化搜索方法为模型选择最佳超参数。

对于最简单的项目，可以使用 sklearn.model_selection.GridSearchCV 来遍历整个搜索空间。

此软件包在 src/[package]/utils/searchers.py 中提供了该超参数搜索功能的简单接口。

对于更复杂的项目，建议采用更复杂的策略（如贝叶斯优化）和相应的软件包（如 Optuna）。

数据划分

应将数据集合理划分为训练集、验证集和测试集。

训练集：用于拟合模型参数
验证集：用于寻找最佳超参数
测试集：用于评估最终模型性能

各集合应互斥，且测试集绝不能用作训练输入！

此软件包在 src/[package]/utils/splitters.py 中实现了一种简单的确定性划分策略。

设计模式

有向无环图

应使用有向无环图（DAG）连接您的 ML 流水线步骤。

DAG 可以表达步骤之间的依赖关系，同时保持每个步骤的独立性。

此软件包在 tasks/project.just 中提供了一个 DAG 示例。该方法基于 Just，并在上述自动化部分进行了说明。

在生产环境中，我们建议使用可扩展的系统，如 Airflow、Dagster、Prefect、Metaflow 或 ZenML。

程序服务

应为程序的执行提供一个全局上下文。

有多种方法，如单例模式、全局变量或组件模式。

此软件包受到 Clojure mount 的启发，在 src/[package]/io/services.py 中提供了实现。

软编码

应将程序实现与程序配置分离。

向用户暴露配置可以让用户在不修改代码的情况下影响程序的行为。

此软件包旨在将尽可能多的参数暴露给用户，并将其存储在 confs/ 文件夹中。

SOLID 原则

你应该实现 SOLID 原则，以使你的代码尽可能灵活。

单一职责原则：一个类只负责一项职责。每当需求发生变化时，只需修改一个类即可。
开闭原则：类对被他人使用持开放态度；但对被他人修改则持封闭态度。
里氏替换原则：任何子类都可以替换其父类。子类继承了父类的行为。
接口隔离原则：当类之间相互承诺时，应将这些承诺（接口）拆分为多个小的、更易理解的接口。
依赖倒置原则：当类之间以非常具体的方式交互时，它们会相互依赖，从而导致难以更改。相反，类应该通过接口或抽象基类进行交互，这样即使类本身发生变化，只要遵守接口约定，就不会影响整体。

在实践中，这意味着你可以使用接口来定义软件契约，并轻松切换其实现。

例如，你可以在 src/[package]/jobs/*.py 中实现多个任务，并在配置中灵活切换它们。

要了解更多关于本包所选机制的信息，可以查阅 Pydantic 标记联合体的文档。

IO 分离

你应该将与外部世界交互的代码与其他部分分离。

外部环境往往杂乱无章且充满风险：文件缺失、权限问题、磁盘空间不足等。

为了隔离这些风险，你可以将所有相关代码放入一个 io 包中，并使用接口来管理。

Python 功能

上下文管理器

你应该使用 Python 上下文管理器来控制和增强代码的执行流程。

Python 提供了上下文管理器，可用于扩展代码块的功能。例如：

# 在 src/[package]/scripts.py 中
with job as runner:  # 上下文
    runner.run()  # 在上下文中执行

这种模式与功能强大的编程模式 Monad 具有相似的优势。

该包使用 src/[package]/jobs/*.py 来处理异常和提供服务。

Python 包

你应该创建 Python 包，以便为他人提供库和应用程序。

在你的 AI/ML 项目中使用 Python 包具有以下优势：

构建可上传到 PyPI 的代码归档（即 wheel 文件）。
将 Python 包作为库安装（例如，像 pandas 一样）。
暴露脚本入口点，以运行 CLI 或 GUI。

使用 uv 构建 Python 包时，只需在终端中输入以下命令：

# 对于所有 uv 项目
uv build
# 仅针对该项目
inv packages

软件工程

代码类型注解

你应该为你的 Python 代码添加类型注解，使其更加健壮并明确地向用户传达意图。

Python 提供了 typing 模块用于添加类型提示，并使用 mypy 来检查这些类型提示。

# 在 src/[package]/core/models.py 中
@abc.abstractmethod
def fit(self, inputs: schemas.Inputs, targets: schemas.Targets) -> "Model":
    """根据给定的输入和目标拟合模型。"""

@abc.abstractmethod
def predict(self, inputs: schemas.Inputs) -> schemas.Outputs:
    """根据给定的输入生成输出。"""

这段代码清晰地说明了方法的输入和输出，既便于开发者理解，也便于类型检查工具验证。

该包旨在为所有函数和类添加类型注解，以提升开发体验并在运行前发现错误。

配置类型注解

你应该为你的配置添加类型注解，以避免程序运行时出现异常。

Pydantic 允许定义类，在程序启动时验证配置的有效性。

# 在 src/[package]/utils/splitters.py 中
class TrainTestSplitter(Splitter):
    shuffle: bool = False  # 必填项（时间敏感）
    test_size: int | float = 24 * 30 * 2  # 2 个月
    random_state: int = 42

这段代码明确了预期的配置值，有助于避免本可以避免的错误。

该包结合 OmegaConf 和 Pydantic，以尽早解析并验证 YAML 配置文件。

数据框类型注解

你应该为你的数据框添加类型注解，以明确其字段并进行验证。

Pandera 支持 Pandas 及其他库（如 PySpark）的数据框类型注解：

# 在 src/package/schemas.py 中
class InputsSchema(Schema):
    instant: papd.Index[papd.UInt32] = pa.Field(ge=0, check_name=True)
    dteday: papd.Series[papd.DateTime] = pa.Field()
    season: papd.Series[papd.UInt8] = pa.Field(isin=[1, 2, 3, 4])
    yr: papd.Series[papd.UInt8] = pa.Field(ge=0, le=1)
    mnth: papd.Series[papd.UInt8] = pa.Field(ge=1, le=12)
    hr: papd.Series[papd.UInt8] = pa.Field(ge=0, le=23)
    holiday: papd.Series[papd.Bool] = pa.Field()
    weekday: papd.Series[papd.UInt8] = pa.Field(ge=0, le=6)
    workingday: papd.Series[papd Bool] = pa.Field()
    weathersit: papd.Series[papd.UInt8] = pa.Field(ge=1, le=4)
    temp: papd.Series[papd.Float16] = pa.Field(ge=0, le=1)
    atemp: papd.Series[papd Float16] = pa.Field(ge=0, le=1)
    hum: papd.Series[papd Float16] = pa.Field(ge=0, le=1)
    windspeed: papd.Series[papd Float16] = pa.Field(ge=0, le=1)
    casual: papd.Series[papd UInt32] = pa.Field(ge=0)
    registered: papd.Series[papd UInt32] = pa.Field(ge=0)

这段代码定义了数据框的字段及其约束条件。

该包鼓励为 src/[package]/core/schemas.py 中使用的每个数据框添加类型注解。

面向对象编程

你应该使用面向对象编程，以充分利用多态性。

结合 SOLID 原则，多态性使得代码组件的替换变得非常容易。

class Reader(abc.ABC, pdt.BaseModel):

    @abc.abstractmethod
    def read(self) -> pd.DataFrame:
        """从数据集中读取数据框。"""

这段代码使用 abc 模块定义了一个包含读写方法的数据集接口。

该包尽可能多地定义类接口，以为你的 AI/ML 项目提供直观且可替换的组件。

语义版本控制

你应该使用语义版本控制来传达你发布的版本之间的兼容性级别。

语义版本控制（SemVer）提供了一个简单的模式来传达代码变更。对于包 X.Y.Z：

主版本（X）：包含破坏性变更的主版本发布（即需要用户采取相应行动）
次版本（Y）：包含新功能的次版本发布（即提供了新的能力）
修订版本（Z）：用于修复 bug 的修订版本发布（即修正了错误行为）

Uv 和这个包都采用了语义版本控制，以便开发者能够控制新版本的采用速度。

测试技巧

并行测试

你可以并行运行测试，以加快对代码库的验证速度。

为此，可以使用 pytest-xdist 插件来扩展 Pytest。

该包默认在其自动化任务中启用了 Pytest。

测试夹具

你应该使用夹具为你的测试定义可重用的对象和操作。

夹具可以为你的测试用例准备对象，例如数据框、模型、文件等。

该包在 tests/conftest.py 中定义了夹具，以提升你的测试体验。

VS Code

代码工作区

你可以使用 VS Code 工作区来为你的项目定义配置。

代码工作区可以启用某些功能（如格式化）并设置默认解释器。

{
 "settings": {
  "editor.formatOnSave": true,
  "python.defaultInterpreterPath": ".venv/bin/python",
    ...
 },
}

该包定义了一个工作区文件，你可以从 [package].code-workspace 加载它。

GitHub Copilot

你可以使用 GitHub Copilot 将你的编码效率提高 30%。

GitHub Copilot 凭借其智能补全功能，极大地提升了开发效率。

你只需一次编码实践，就能很快熟悉它的用法。

VSCode VIM

你可以使用 VIM 键绑定更高效地导航和修改代码。

学习 VIM 是投身 IT 行业的一项绝佳投资。它能使你的工作效率提升 30%。

与 GitHub Copilot 相比，掌握 VIM 需要更多时间。不过，你可以在一个月内看到回报。

资源

本节提供了构建 Python 以及 AI/ML/MLOps 相关软件包的资源。

Python

AI/ML/MLOps

MLOps Python Package 快速上手指南

本指南旨在帮助开发者快速搭建基于最佳实践的 MLOps Python 项目环境，并运行核心任务。

环境准备

在开始之前，请确保您的系统满足以下要求：

操作系统: Linux, macOS 或 Windows (WSL2 推荐)
Python: 版本需 >= 3.13 (以利用最新性能特性)
uv: 版本需 >= 0.5.5 (用于极速管理虚拟环境和依赖)
- 安装 uv: curl -LsSf https://astral.sh/uv/install.sh | sh
- 国内加速: 如遇网络问题，可配置 UV_INDEX_URL 环境变量指向国内镜像源（如清华源）：
```
export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
```

安装步骤

1. 克隆项目

将代码仓库克隆到本地：

# 推荐使用 SSH
git clone git@github.com:fmind/mlops-python-package.git
# 或使用 HTTPS
git clone https://github.com/fmind/mlops-python-package.git

2. 初始化环境与同步依赖

进入项目目录并使用 uv 同步环境。该命令会自动创建虚拟环境并安装所有必要的依赖包。

cd mlops-python-package/
uv sync

3. (可选) 安装 Git Hooks

为了在提交代码时自动进行格式检查和质量验证，建议安装预提交钩子：

uv run just install-hooks

基本使用

本项目通过 YAML 配置文件驱动不同的 MLOps 任务（如训练、调优、推理等）。

1. 查看配置结构

您可以查看 confs/ 目录下的配置文件，例如 confs/training.yaml：

# confs/training.yaml
job:
  KIND: TrainingJob
  inputs:
    KIND: ParquetReader
    path: data/inputs_train.parquet
  targets:
    KIND: ParquetReader
    path: data/targets_train.parquet

2. 运行任务

使用 uv run 执行具体的 MLOps 任务。请将 [package] 替换为实际的项目包名（通常在 pyproject.toml 中定义）。

开发模式运行：

# 运行模型调优
uv run [package] confs/tuning.yaml

# 运行模型训练
uv run [package] confs/training.yaml

# 运行模型推理
uv run [package] confs/inference.yaml

# 运行模型评估
uv run [package] confs/evaluations.yaml

命令行传参技巧：

使用 --extras 传递运行时动态参数。
支持同时传入多个配置文件，后者会覆盖前者配置（从左到右合并）。

3. 常用自动化命令

项目内置了 just 工具来简化常见操作：

# 运行完整的项目工作流 (DAG)
just project

# 构建 Python 分发包
just package

# 启动本地 MLflow 服务
just mlflow-serve

# 查看所有可用命令
just

4. 作为库调用

您也可以将此包作为库集成到其他 AI 项目中：

from [package] import jobs

# 实例化任务
job = jobs.TrainingJob(...)

# 执行任务
with job as runner:
    runner.run()

使用场景