LLMOps Python 包

本仓库包含一套基于最佳实践的 Python 代码库，旨在支持您的 LLMOps 项目。

该包利用多种 工具 和 技巧，以尽可能提升您在 LLMOps 方面的灵活性、健壮性和生产力。

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

本包是对以下资源的变体或分支，但专门针对 LLM 使用场景进行了优化：

相关资源：

• MLOps 编程课程（学习）：学习如何创建、开发和维护最先进的 MLOps 代码库。
• Cookiecutter MLOps 包（模板）：开始构建并部署用于 MLOps 任务的 Python 包和 Docker 镜像。

目录

• LLMOps Python 包
• 目录
• 安装
  • 先决条件
  • 安装
  • 后续步骤
• 使用
  • 配置
  • 执行
  • 自动化
  • 工作流
• 工具
  • 自动化
    • 提交：Commitizen
    • Git 钩子：Pre-Commit
    • 任务：PyInvoke
  • CI/CD
    • 运行器：GitHub Actions
  • CLI
    • 解析器：Argparse
    • 日志：Loguru
  • 代码
    • 覆盖率：Coverage
    • 编辑器：VS Code
    • 格式化：Ruff
    • 质量：Ruff
    • 安全：Bandit
    • 测试：Pytest
    • 类型检查：Mypy
    • 版本控制：Git
  • 配置
    • 格式：YAML
    • 解析器：OmegaConf
    • 读取器：Cloudpathlib
    • 验证器：Pydantic
  • 模型
    • 格式：Mlflow Model
    • 注册表：Mlflow Registry
    • 跟踪：Mlflow Tracking
  • 包
    • 演进：Changelog
    • 格式：Wheel
    • 管理工具：Poetry
    • 运行时：Docker
  • 编程
    • 语言：Python
    • 版本：Pyenv
  • 可观测性
    • 监控：Mlflow Evaluate
    • 基础设施：Mlflow 系统指标
  • 模型服务
    • 服务端点：Litserve
• 提示
  • 设计模式
    • 有向无环图
    • 程序服务
    • 软编码
    • SOLID 原则
    • IO 分离
  • Python 力量
    • 上下文管理器
    • Python 包
  • 软件工程
    • 代码类型检查
    • 配置类型检查
    • 面向对象
    • 语义版本控制
  • 测试技巧
    • 并行测试
    • 测试夹具
  • VS Code
    • 代码工作区
    • GitHub Copilot
• 资源
  • Python
  • AI/ML/MLOps

架构

RAG 评估

RAG 评估是通过生成一个 QA 答案对的合成数据集来完成的。该数据集作为基准，用于在部署不同 RAG 系统之前评估其性能。通过使用一致且受控的数据集，我们可以客观地比较各种 RAG 实现的有效性。

模型注册表

我们采用一种模式，将所有 LLM 链存储并记录在 Mlflow 中。每条链都会与 RAG 评估基准进行对比。如果某条链的表现优于之前的链，则会被注册并晋升到生产环境。这样可以确保只有表现最好的模型才会被部署。

守护机制

在生产环境中，守护机制非常重要，因为它可以防止模型出现意外或不良行为。

此 LLMOps 模板附带了用于 PII 和主题审查的守护机制配置文件，这些配置是在 Guardrails AI 的基础上构建的。

端点部署

拥有模型注册表对于管理和运行部署至关重要。在此架构中，我们使用 Litserve，它基于 FastAPI 构建，用于部署我们的 LLM。这种设置提供了灵活的部署选项，包括 Kubernetes 和 AWS Lambda，从而确保我们的模型能够高效地扩展和管理。

您可以在 /serving_endpoint 文件夹下查看如何提供模型服务以及在 AWS Fargate 上部署的代码模板。

模型监控

模型监控对于确保生产环境中大型语言模型（LLM）的性能和可靠性至关重要。持续的监控有助于检测诸如性能下降、异常行为等问题，这些问题可能会显著影响用户体验和业务成果。

我们使用 Mlflow Traces 来监控我们的 LLM。这使我们能够随着时间推移跟踪与模型相关的各种指标和日志。此外，我们还使用 Mlflow Evaluate 对这些跟踪记录进行评估，并以 LLM 本身作为评判者。这种设置确保了我们维持高标准的模型性能，并能快速识别和解决任何出现的问题。

LLMOps 设计模式

在该项目中，我们采用了与 Databricks 推荐非常相似的设计模式，即在每个模型部署之前先将其记录到 Mlflow 中。

这里的主要变化在于，我们的部署流水线以两个步骤的形式编排：注册、验证，最后在注册表上完成部署。我们不是监测数据漂移，而是测量 LLM 指标的变化；另外，我们目前没有使用 Mlflow AI Gateway（尽管未来可以考虑加入它或 LiteLLM）。

安装

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

前提条件

• Python>=3.10：以便利用最新功能和性能改进
• Poetry>=1.8.2：用于初始化项目的虚拟环境及其依赖项

请使用包管理器 Poetry：

LLM 凭证

要访问 Bedrock、OpenAI 或其他 LLM 提供商的服务，您需要设置相应的凭证。这些凭证将允许该软件包进行身份验证并与相应服务交互。在此代码模板中，我们使用了 Bedrock，但您可以根据需求自由更改。

以 AWS 为例：

环境变量： bash export AWS_ACCESS_KEY_ID=your_access_key_id export AWS_SECRET_ACCESS_KEY=your_secret_access_key export AWS_REGION=your_default_region

• 您可以轻松地将 ChatBedrock 替换为 ChatOllama 或其他提供商。

安装

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

# 使用 ssh（推荐）
$ git clone -
# 使用 https
$ git clone -

2. 使用 poetry 运行项目安装

$ cd llmops-python-package/
$ poetry install

3. 根据您的需求调整代码库

后续步骤

有许多方法可以将此软件包集成到您的 MLOps 平台中。

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

请随时修改软件包代码以满足您的特定需求。祝您好运！

使用说明

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

配置

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

# confs/deployment.yaml
job:
  KIND: DeploymentJob
  staging_alias: "champion"
  production_alias: "production"
  registry_model_name: "rag-chatbot-with-guardrails"
  llm_confs: "/confs/rag_chain_config.yaml"
  llm_model_code_path: "/src/llmops_project/models/chatbot_with_guardrails.py"
  vector_store_path: "http://localhost:6333"

此配置文件指示程序以相应参数启动 DeploymentJob。您可以在 src/[package]/pipelines/*.py 文件中找到程序的所有参数。

您还可以使用 poetry run llmops --schema 打印出该软件包支持的完整架构。

执行

在开发过程中，您可以使用 poetry 执行项目代码，推荐顺序如下：

$ poetry run llmops-project confs/generate_rag_dataset.yaml # 运行一次以生成 RAG 数据集
$ poetry run llmops-project confs/feature_eng.yaml # 创建向量数据库并注入文档
$ poetry run llmops-project confs/deployment.yaml # 将模型部署到模型注册表
$ poetry run llmops-project confs/monitoring.yaml # 每周监控模型推理

要部署服务端点，您可以使用以下自动化命令：

$ inv serve # 在端口 8000 上启动 Litserve 服务器

注意：您也可以按照 /serving_endpoint 下的说明，将其部署为容器或云端服务。

流水线

该项目采用管理器模式组织，每个管理器负责任务/作业之间的整个工作流编排。（在生产环境中，您可以使用 Airflow 等工具来实现此类功能）

生成 RAG 数据集

此流水线会在 /data/datasets/ 目录下生成一个 RAG QA 数据集。

特征工程

此流水线创建一个向量数据库实例，并以向量形式将文档注入其中。

部署

此流水线：

• 使用 Mlflow 注册模型
• 将模型提升至 champion 别名
• 验证模型的输入/输出及签名
• 在 Mlflow 注册表上设置标签 passed_tests，根据模型是否通过测试将其值设为 True 或 False
• 对我们先前创建的 QA 数据集进行 QA 事实性评估
• 根据评估结果，为模型分配标签 beats_threshold，值为 True 或 False
• 如果模型既 beats_threshold 又 passed_tests，则可将其提升至 production

在该流水线结束时，我们应该在模型注册表中拥有一个处于生产状态的模型版本。

监控

此流水线旨在作为每周作业运行，以监控模型在给定指标上的表现，例如默认指标，甚至使用大型语言模型作为评判者。

这些指标也会被保存并显示出来，以便您可以在其他地方的仪表板中加载它们。

在生产环境中，您可以将该项目构建、发布并作为一个 Python 包来运行：

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

您也可以将此包作为库安装并用于另一个 AI/ML 项目：

from [package] import pipelines

job = pipelines.DeploymentJob(...)
with job as runner:
    runner.run()

附加提示：

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

自动化

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

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

# 创建代码归档
$ inv packages
# 列出其他操作
$ inv --list

可用任务：

• checks.all (检查) - 运行所有检查任务。
• checks.code - 使用 ruff 检查代码。
• checks.coverage - 使用 coverage 检查覆盖率。
• checks.format - 使用 ruff 检查格式。
• checks.poetry - 检查 poetry 配置文件。
• checks.security - 使用 bandit 检查安全性。
• checks.test - 使用 pytest 检查测试。
• checks.type - 使用 mypy 检查类型。
• cleans.all (清理) - 运行所有工具和文件夹任务。
• cleans.cache - 清理缓存文件夹。
• cleans.coverage - 清理覆盖率工具。
• cleans.dist - 清理 dist 文件夹。
• cleans.docs - 清理文档文件夹。
• cleans.environment - 清理项目环境文件。
• cleans.folders - 运行所有文件夹任务。
• cleans.mlruns - 清理 mlruns 文件夹。
• cleans.mypy - 清理 mypy 工具。
• cleans.outputs - 清理输出文件夹。
• cleans.poetry - 清理 poetry 锁文件。
• cleans.pytest - 清理 pytest 工具。
• cleans.projects - 运行所有项目任务。
• cleans.python - 清理 Python 缓存和字节码。
• cleans.requirements - 清理项目需求文件。
• cleans.reset - 运行所有工具、文件夹和源文件任务。
• cleans.ruff - 清理 ruff 工具。
• cleans.sources - 运行所有源文件任务。
• cleans.tools - 运行所有工具任务。
• cleans.venv - 清理 venv 文件夹。
• commits.all (提交) - 运行所有提交任务。
• commits.bump - 提升软件包版本。
• commits.commit - 提交所有更改并附带消息。
• commits.info - 打印消息指南。
• containers.all (容器) - 运行所有容器任务。
• containers.build - 使用指定标签构建容器镜像。
• containers.compose - 启动 docker compose。
• containers.run - 使用指定标签运行容器镜像。
• docs.all (文档) - 运行所有文档任务。
• docs.api - 使用 pdoc 按照指定格式和输出目录记录 API 文档。
• docs.serve - 使用 pdoc 按照指定格式和计算机端口提供 API 文档服务。
• formats.all - （格式）运行所有格式任务。
• formats.imports - 使用 ruff 格式化 Python 导入语句。
• formats.sources - 使用 ruff 格式化 Python 源代码。
• installs.all (安装) - 运行所有安装任务。
• installs.poetry - 安装 poetry 包。
• installs.pre-commit - 在 git 上安装预提交钩子。
• mlflow.all (mlflow) - 运行所有 mlflow 任务。
• mlflow.doctor - 运行 mlflow doctor 诊断问题。
• mlflow.serve - 使用指定主机、端口和后端 URI 启动 mlflow 服务器。
• packages.all (包) - 运行所有打包任务。
• packages.build - 使用指定格式构建 Python 包。
• projects.all (项目) - 运行所有项目任务。
• projects.environment - 导出项目环境文件。
• projects.requirements - 导出项目需求文件。
• projects.run - 从 MLproject 文件运行 mlflow 项目。

工具

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

• 本项目中的大多数开发工具与 mlops-python 包中使用的工具相同。请参阅该资源，以获取有关这些工具背后动机的详细说明。

提示

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

设计模式

有向无环图

您应该使用有向无环图 (DAG) 来连接您的机器学习流水线步骤。

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

本包在 tasks/dags.py 中提供了一个简单的 DAG 示例。这种方法基于 PyInvoke。

在生产环境中，我们建议使用可扩展的系统，如 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.org 的代码归档（即 wheel 文件）
• 将 Python 包作为库安装（例如 pandas）
• 暴露脚本入口点，以运行 CLI 或 GUI

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

# 对于所有 Poetry 项目
poetry build
# 仅针对本项目
inv packages

软件工程

代码类型注解

你应该为你的 Python 代码添加类型注解，以使其更加健壮并明确地向用户展示其用途。

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

这段代码清晰地说明了方法的输入和输出，无论是对开发者还是类型检查器都十分有用。

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

配置类型注解

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

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 文件并进行验证。

面向对象编程

你应该使用面向对象编程，以利用 多态性 的优势。

结合 SOLID 原则，多态性使得你可以轻松地替换代码组件。

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

语义化版本控制

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

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

• 主版本（X）：重大发布，包含破坏性变更（即需要采取行动以适应的变化）
• 次版本（Y）：次要版本，包含新功能（即提供新的能力）
• 补丁版本（Z）：补丁版本，用于修复 bug（即纠正错误行为）

Poetry 和本包都利用语义化版本控制，让开发者能够控制新版本的采用速度。

测试技巧

并行测试

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

为此，可以使用 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

• https://github.com/krzjoa/awesome-python-data-science#readme
• https://github.com/ml-tooling/best-of-ml-python
• https://github.com/ml-tooling/best-of-python
• https://github.com/ml-tooling/best-of-python-dev
• https://github.com/vinta/awesome-python

AI/ML/MLOps

• https://github.com/josephmisiti/awesome-machine-learning
• https://github.com/visenger/awesome-mlops

llmops-python-package 快速上手指南

本指南帮助中国开发者快速搭建基于最佳实践的 LLMOps（大语言模型运维）项目。该工具包集成了模型注册、实验追踪、RAG 评估、护栏（Guardrails）及服务部署等功能。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows (WSL2 推荐)
• Python 版本：>= 3.10 (推荐使用 3.12 以获得最佳性能)
• 包管理器：Poetry >= 1.8.2
• LLM 凭证：需配置云厂商（如 AWS Bedrock, OpenAI 等）的访问密钥。

前置依赖安装

如果您尚未安装 Poetry，可以通过以下方式安装（国内用户若遇网络问题，可尝试使用国内镜像或代理）：

# 官方安装脚本
curl -sSL https://install.python-poetry.org | python3 -

# 验证安装
poetry --version

配置 LLM 凭证

本项目默认示例使用 AWS Bedrock。您需要在终端导出环境变量以进行认证：

export AWS_ACCESS_KEY_ID=your_access_key_id
export AWS_SECRET_ACCESS_KEY=your_secret_access_key
export AWS_REGION=your_default_region

提示：您可以轻松将代码中的 ChatBedrock 替换为 ChatOllama 或其他提供商以适应本地或国内模型服务。

安装步骤

1. 克隆项目

使用 Git 克隆仓库到本地：

# 推荐方式使用 SSH
git clone git@github.com:callmesora/llmops-python-package.git

# 或使用 HTTPS
git clone https://github.com/callmesora/llmops-python-package.git

2. 进入目录并安装依赖

进入项目文件夹并使用 Poetry 安装所有依赖及创建虚拟环境：

cd llmops-python-package/
poetry install

3. 验证安装

安装完成后，您可以查看支持的配置架构以验证环境是否正常：

poetry run llmops --schema

基本使用

本项目采用流水线（Pipeline）模式管理 RAG 生命周期。以下是标准的执行顺序，涵盖从数据生成到模型部署的全过程。

1. 生成 RAG 评估数据集

首先生成用于基准测试的合成问答数据集：

poetry run llmops-project confs/generate_rag_dataset.yaml

2. 特征工程与向量库构建

创建向量数据库实例并将文档注入为向量：

poetry run llmops-project confs/feature_eng.yaml

3. 模型部署与注册

运行部署流程，该步骤会自动完成以下操作：

• 使用 Mlflow 注册模型
• 验证模型输入/输出签名
• 基于生成的数据集评估模型质量（Factfulness）
• 若模型通过测试且超过阈值，则提升为 champion 或 production 版本

poetry run llmops-project confs/deployment.yaml

4. 启动推理服务

使用 Litserve（基于 FastAPI）在本地启动模型服务端点（默认端口 8000）：

inv serve

注意：生产环境中，您可参考 /serving_endpoint 目录下的配置，将服务部署至 Docker、Kubernetes 或 AWS Fargate。

5. 模型监控（可选）

定期运行监控任务，利用 Mlflow Traces 和 LLM 作为裁判来评估线上表现：

poetry run llmops-project confs/monitoring.yaml

配置文件说明

所有行为均可通过修改 confs/ 目录下的 YAML 文件进行定制。例如，编辑 confs/deployment.yaml 可更改模型名称、向量库地址及晋升策略：

# confs/deployment.yaml 示例
job:
  KIND: DeploymentJob
  staging_alias: "champion"
  production_alias: "production"
  registry_model_name: "rag-chatbot-with-guardrails"
  vector_store_path: "http://localhost:6333"