4、回放验证环境搭建：Python虚拟环境配置、依赖库安装与版本锁定策略

回放验证环境的可复现性是数据质量保障的基石。若环境依赖不一致，同一份回放脚本在不同机器上可能输出截然不同的验证结果，导致误判或漏判。本节将指导你从零搭建一个隔离、可复现的 Python 虚拟环境，并锁定所有关键依赖库的版本。

4.1 环境隔离方案对比

Python 生态中主流的虚拟环境管理工具有多种，下表从隔离粒度、性能与团队协作角度进行对比，帮助你根据项目规模选择最合适的方案。

4.2 虚拟环境创建与激活

以下步骤以 Python 3.9+ 为例，在项目根目录下创建隔离环境。

# 1. 创建虚拟环境（在项目根目录执行）
python -m venv .venv_xgb_replay

# 2. 激活环境（Linux/macOS）
source .venv_xgb_replay/bin/activate

# 3. 激活环境（Windows PowerShell）
.venv_xgb_replay\Scripts\Activate.ps1

# 4. 确认环境已切换
which python   # Linux/macOS
where python   # Windows
# 输出应指向 .venv_xgb_replay 目录下的解释器

4.3 核心依赖库安装与版本锁定

回放验证环境需要安装以下四类核心库。安装顺序遵循“先基础后上层”的原则，避免依赖冲突。

# 升级 pip 至最新版本
pip install --upgrade pip

# 安装基础数值计算库
pip install numpy==1.24.3
pip install pandas==2.0.3

# 安装机器学习模型库
pip install xgboost==2.0.3

# 安装数据质量验证框架
pip install great_expectations==0.18.8

# 安装辅助工具（可选但推荐）
pip install pyarrow==14.0.1   # 加速 Parquet 文件读写
pip install scikit-learn==1.3.2  # 用于模型评估指标计算

安装完成后，立即执行版本锁定，生成可复现的依赖清单。

# 生成精确版本锁定文件
pip freeze > requirements_xgb_replay.txt

# 查看锁定文件内容（示例）
cat requirements_xgb_replay.txt

锁定文件应包含所有直接依赖及其传递依赖的精确版本号。以下是一个典型的锁定文件片段：

great-expectations==0.18.8
numpy==1.24.3
pandas==2.0.3
xgboost==2.0.3
scikit-learn==1.3.2
pyarrow==14.0.1
# ... 其他传递依赖（altair, jinja2, marshmallow 等）

4.4 版本锁定策略与冲突排查

版本锁定不是简单的“记下版本号”，而是需要遵循一套可追溯、可回滚的策略。下表总结了三种常见锁定策略及其适用场景。

4.5 依赖冲突排查流程

当安装过程中出现版本冲突时，按以下步骤排查：

1. 查看冲突信息：pip 会在报错中明确提示冲突的包名和版本要求。
2. 检查 XGBoost 兼容性：访问 XGBoost 官方文档的“Python Package”章节，确认当前版本对 numpy/pandas 的最低要求。
3. 使用 pipdeptree 可视化依赖树：pip install pipdeptree && pipdeptree 可以展示所有包的依赖关系，快速定位冲突源头。
4. 降级或升级冲突包：优先调整非核心库（如 altair、jinja2）的版本，避免改动 numpy/pandas/xgboost 的主版本号。
5. 重新锁定：解决冲突后，再次执行 pip freeze > requirements_xgb_replay.txt 更新锁定文件。

4.6 环境搭建流程总览

下图展示了从创建虚拟环境到锁定依赖的完整流程，以及各步骤之间的依赖关系。

4.7 环境验证脚本

完成安装后，执行以下验证脚本，确保所有核心库可正常导入且版本符合预期。

# validate_env.py
import sys
import numpy as np
import pandas as pd
import xgboost as xgb
import great_expectations as ge

print(f"Python 版本: {sys.version}")
print(f"NumPy 版本: {np.__version__}")
print(f"Pandas 版本: {pd.__version__}")
print(f"XGBoost 版本: {xgb.__version__}")
print(f"Great Expectations 版本: {ge.__version__}")

# 快速功能验证：创建简单 DataFrame 并执行 Great Expectations 检查
df = pd.DataFrame({"col1": [1, 2, 3], "col2": ["a", "b", "c"]})
ge_df = ge.from_pandas(df)
result = ge_df.expect_column_values_to_be_in_set("col1", [1, 2, 3])
assert result.success, "Great Expectations 基础验证失败！"

print("所有依赖库安装正确，环境验证通过！")