4. 环境准备与依赖安装

本章将系统讲解 XGBoost 精算模型从开发到部署所需的环境搭建与核心依赖安装。正确的环境隔离与版本管理是保障模型可复现、服务稳定的第一道防线。本节内容覆盖 Python 虚拟环境创建、CPU/GPU 双模式配置、以及 Flask/FastAPI/ONNX Runtime 等关键库的安装验证。

4.1 Python 虚拟环境搭建

推荐使用 conda 或 venv 创建独立环境，避免包版本冲突。以下以 conda 为例，创建名为 xgb_serving 的环境，指定 Python 3.9 版本（XGBoost 1.7+ 与 Python 3.9-3.11 兼容性最佳）。

# 创建虚拟环境
conda create -n xgb_serving python=3.9 -y

# 激活环境
conda activate xgb_serving

# 验证 Python 版本
python --version
# 输出: Python 3.9.18

4.2 核心库安装与版本验证

下表列出精算模型 Serving 场景下各核心库的推荐版本与安装命令。请严格按照顺序安装，避免依赖冲突。

# 批量安装（推荐使用 requirements.txt）
pip install xgboost==1.7.6 flask==2.3.3 fastapi==0.104.1 uvicorn==0.24.0 onnxruntime==1.16.3 pandas==2.1.4 numpy==1.24.3

# 验证安装版本
python -c "import xgboost; print('XGBoost:', xgboost.__version__)"
python -c "import flask; print('Flask:', flask.__version__)"
python -c "import fastapi; print('FastAPI:', fastapi.__version__)"
python -c "import onnxruntime; print('ONNX Runtime:', onnxruntime.__version__)"

4.3 GPU 与 CPU 环境配置差异

精算模型在训练阶段通常使用 GPU 加速，而在生产 Serving 阶段可能因成本或延迟要求选择 CPU。两种环境的配置差异集中在 XGBoost 与 ONNX Runtime 的安装选项上。

4.3.1 CPU 环境配置

CPU 环境安装最为简单，无需额外驱动依赖。ONNX Runtime 使用 CPU 执行提供程序，适合延迟不敏感或成本受限的精算批处理场景。

# CPU 环境安装（默认即为 CPU 版本）
pip install xgboost onnxruntime

# 验证使用 CPU 执行提供程序
python -c "
import onnxruntime as ort
print('Available providers:', ort.get_available_providers())
# 输出应包含 'CPUExecutionProvider'
"

4.3.2 GPU 环境配置

GPU 环境需要额外安装 CUDA 工具包、cuDNN 库以及 XGBoost/ONNX Runtime 的 GPU 变体。以下为完整安装步骤。

# 步骤1：确认 CUDA 版本（以 CUDA 11.8 为例）
nvidia-smi
# 输出中查看 CUDA Version: 11.8

# 步骤2：安装 GPU 版 XGBoost
pip install xgboost==1.7.6 --force-reinstall

# 步骤3：安装 GPU 版 ONNX Runtime
pip install onnxruntime-gpu==1.16.3

# 步骤4：验证 GPU 可用性
python -c "
import xgboost as xgb
print('XGBoost GPU support:', xgb.build_info())
# 输出应包含 'USE_CUDA': 'ON'

import onnxruntime as ort
print('GPU providers:', ort.get_available_providers())
# 输出应包含 'CUDAExecutionProvider'
"

4.4 环境配置架构总览

下图展示了从开发环境到生产 Serving 的完整依赖链路与配置决策点。绿色节点为推荐路径，橙色节点为可选优化路径。

4.5 常见安装问题与解决方案

以下列表汇总了精算团队在环境配置中最常遇到的 5 类问题及对应解决步骤。

• 问题1：XGBoost GPU 版本安装后仍使用 CPU
  原因：系统 CUDA 路径未正确加载。
  解决：执行 export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH 并重新安装 XGBoost。
• 问题2：ONNX Runtime GPU 版本找不到 CUDAExecutionProvider
  原因：onnxruntime-gpu 与 CUDA 版本不匹配。
  解决：卸载后安装与 CUDA 对应的版本，如 CUDA 11.8 对应 onnxruntime-gpu==1.15.1。
• 问题3：Flask 与 FastAPI 端口冲突
  原因：两个服务尝试绑定同一端口。
  解决：在启动命令中指定不同端口，如 --port 5000 和 --port 8000。
• 问题4：pandas 读取精算数据时内存溢出
  原因：数据集过大且未使用分块读取。
  解决：使用 pd.read_csv(chunksize=10000) 或转换为 Parquet 格式。
• 问题5：conda 环境激活后 pip 安装的包找不到
  原因：conda 与 pip 混合使用时环境隔离失效。
  解决：始终在激活环境后使用 python -m pip install 而非直接 pip install。

# environment.yml
name: xgb_serving
channels:
  - conda-forge
  - defaults
dependencies:
  - python=3.9
  - pip
  - pip:
    - -r requirements.txt

# requirements.txt
xgboost==1.7.6
flask==2.3.3
fastapi==0.104.1
uvicorn==0.24.0
onnxruntime==1.16.3
pandas==2.1.4
numpy==1.24.3

4.6 环境验证脚本

完成安装后，建议执行以下综合验证脚本，确保所有组件可正常加载且 GPU 配置生效（如适用）。

# validate_env.py
import sys
import numpy as np
import pandas as pd
import xgboost as xgb
import flask
import fastapi
import onnxruntime as ort

print("=" * 50)
print("精算模型 Serving 环境验证")
print("=" * 50)

# 1. Python 版本
print(f"[OK] Python: {sys.version}")

# 2. 数据科学库
print(f"[OK] NumPy: {np.__version__}")
print(f"[OK] Pandas: {pd.__version__}")

# 3. XGBoost
print(f"[OK] XGBoost: {xgb.__version__}")
if hasattr(xgb, 'build_info'):
    info = xgb.build_info()
    print(f"     GPU Support: {info.get('USE_CUDA', 'N/A')}")

# 4. API 框架
print(f"[OK] Flask: {flask.__version__}")
print(f"[OK] FastAPI: {fastapi.__version__}")

# 5. ONNX Runtime
print(f"[OK] ONNX Runtime: {ort.__version__}")
providers = ort.get_available_providers()
print(f"     Providers: {providers}")
if 'CUDAExecutionProvider' in providers:
    print("[OK] GPU 推理可用")
else:
    print("[INFO] 仅 CPU 推理可用")

print("=" * 50)
print("环境验证完成，所有组件就绪！")
print("=" * 50)