第3章 环境搭建与依赖安装：Python、PyTorch、TensorFlow、certify

模型边界确认算法的工程落地，首先需要一个干净、可复现的运行时环境。本章在Ubuntu 22.04 / Windows 11 + WSL2 上进行演示，所有依赖版本均已锁死，避免随机升级带来的兼容性问题。工程团队应依据SOP严格锁定次版本号，日常迭代由CI/CD自动验证。

3.1 环境总览与版本约束

组件 推荐版本 最低版本 用途
Python 3.10.12 3.9.0 主语言，所有绑定层
PyTorch 2.1.2+cu121 1.13.0 动态图训练与边界探索
TensorFlow 2.15.0 2.10.0 生产级静态图推理
certify 1.3.4 1.2.0 随机平滑边界认证核
CUDA 12.1 11.8 GPU加速（可选但推荐）
团队约定：所有依赖版本写入 requirements.txt 及 environment.yml，每次合并MR前执行 pip install -r requirements.txt --dry-run 检查版本冲突。

3.2 安装流程（命令级SOP）

以下步骤按工程流水线顺序编排，每个命令前标注责任人角色。

  1. 基础设施（SRE/DevOps）：创建 Python 3.10 虚拟环境并激活。
conda create -n model_boundary python=3.10.12 -y
conda activate model_boundary
  1. 基础设施（SRE/DevOps）：确认 GPU 驱动及 CUDA 工具链可用，
nvidia-smi
nvcc --version

若输出为空，降级为 CPU 版本，并修改后续安装命令中的 cu121 为 cpu。

  1. 算法工程师：安装 PyTorch（带 CUDA 12.1 支持），
pip install torch==2.1.2+cu121 torchvision==0.16.2+cu121 torchaudio==2.1.2+cu121 \
  --index-url https://download.pytorch.org/whl/cu121
  1. 算法工程师：安装 TensorFlow，
pip install tensorflow==2.15.0
  1. 算法工程师 / 测试工程师：安装 certify 库及核心依赖，
pip install certify==1.3.4 numpy scipy matplotlib tqdm
  1. 质量保证（QA）：全量验证安装版本，
python -c "import torch; print('PyTorch', torch.__version__, 'CUDA', torch.version.cuda)"
python -c "import tensorflow as tf; print('TF', tf.__version__)"
python -c "import certify; print('certify', certify.__version__)"
常见错误：“symbol cublasLtGetStatusString version libcublasLt.so.11 not defined”。解决方式是重装对应 CUDA 版本的 PyTorch，或者使用 export LD_LIBRARY_PATH=$CONDA_PREFIX/lib:$LD_LIBRARY_PATH 临时修复。此问题通常由 conda 默认 libstdc++ 版本不匹配导致，工程上应统一使用 conda install -c conda-forge gcc=12.1.0 锁定 ABI。

3.3 依赖关系与版本决策矩阵

certify 库对不同框架的底层调用路径不同，其安装依赖具有隐式传递性。工程团队应理解以下依赖链，避免“缺库而不自知”。

certify 子模块 依赖框架 核心依赖 可选依赖
certify.smoothing PyTorch torch, numpy, scipy tqdm（可视化）
certify.inference TensorFlow tensorflow, numpy trtexec（TensorRT）
certify.bound 独立（NumPy） scipy, matplotlib joblib（并行）
certify.visualize 独立 matplotlib, seaborn ——

3.4 环境搭建架构图

下图展示从裸机到可运行的模型边界确认环境的完整栈式依赖关系，以及各工程角色在此流程中的职责分界。

模型边界确认环境搭建架构与职责划分 环境搭建架构与工程职责划分 基础设施层 — SRE/DevOps Python 3.10.12 / conda 虚拟环境 PyTorch 2.1.2 CUDA 12.1 Backend TensorFlow 2.15.0 XLA / TFRT Backend certify 1.3.4 边界认证核 numpy, scipy, matplotlib, tqdm 模型边界确认算法执行环境 随机平滑 · 边界上下界 · 认证测试 SRE 固化镜像 算法/QA 安装 + 版本锁 测试 集成验证 GPU vs CPU

3.5 验证脚本与集成测试

安装完成后，执行下列集成测试脚本，确认三个框架均可正确调用 certify 的边界核。该脚本应纳入 CI 流水线作为冒烟测试。

#!/usr/bin/env python3
# file: verify_environment.py
# 用途：快速冒烟测试，验证基础依赖完整性

import sys, numpy as np

# PyTorch + certify.smoothing
try:
    import torch
    from certify.smoothing import Smooth
    model = lambda x: torch.argmax(torch.randn(1, 10), dim=1)
    smoother = Smooth(model, num_classes=10, sigma=0.25)
    x = torch.randn(1, 3, 32, 32)
    pred, radius = smoother.predict(x, n=100, alpha=0.001)
    print(f"[PASS] certify.smoothing: pred={pred}, radius={radius:.4f}")
except Exception as e:
    print(f"[FAIL] certify.smoothing: {e}")
    sys.exit(1)

# TensorFlow + certify.inference
try:
    import tensorflow as tf
    from certify.inference import ClassifierWrapper
    tf_model = tf.keras.Sequential([tf.keras.layers.Dense(10)])
    wrapper = ClassifierWrapper(tf_model, input_shape=(784,))
    x_tf = np.random.randn(1, 784).astype(np.float32)
    logits = wrapper.predict(x_tf)
    print(f"[PASS] certify.inference: logits shape {logits.shape}")
except Exception as e:
    print(f"[FAIL] certify.inference: {e}")
    sys.exit(1)

# certify.bound 纯 NumPy 运算
try:
    from certify.bound import compute_certified_radius
    counts = np.random.randint(0, 100, size=(10,))
    r = compute_certified_radius(counts, n_total=1000, alpha=0.05)
    print(f"[PASS] certify.bound: radius={r:.4f}")
except Exception as e:
    print(f"[FAIL] certify.bound: {e}")
    sys.exit(1)

print("=" * 40)
print("所有边界模块验证通过，环境就绪。")

3.6 常见错误与诊断表

错误现象 根因 责任人 修复命令/操作
ImportError: libcudart.so.11.0 CUDA版本不匹配 SRE 安装对应CUDA toolkit，或重新安装PyTorch CPU版
certify.smoothing 预测为 NaN 模型输出概率未归一化 算法 确保模型输出层为 softmax 或 log_softmax
TensorFlow OOM 且无 GPU 默认占用全部显存/内存 QA/算法 设置 tf.config.set_visible_devices([], 'GPU')
certify.bound 报 binom.ppf 溢出 n_total 过小或 alpha 过大 算法 增加 n_total ≥ 1000，alpha ≤ 0.05

3.7 性能与稳定性优化

  • CUDA 可复现性：在代码首部固定 torch.backends.cudnn.deterministic = True 和 torch.backends.cudnn.benchmark = False。虽损失约10%吞吐，但保证边界曲线可复现。
  • 多进程隔离：certify 的蒙特卡洛采样阶段开销大，建议使用 joblib 或 torch.multiprocessing 并行。注意设置 torch.set_num_threads(1) 避免 OpenMP 争抢。
  • 裁剪 TensorFlow 日志：os.environ['TF_CPP_MIN_LOG_LEVEL'] = '3' 屏蔽 INFO/WARNING，仅保留 ERROR 等级，减少CI日志噪音。
  • 依赖锁定：统一使用 pip freeze > requirements-lock.txt 记录精确版本，MR合并前对比 diff，禁止引入未审查的间接依赖。

3.8 工程职责划分 SOP 快照

SOP-BE-03-001：环境搭建流水线责任矩阵
  1. SRE/Infra：提供预装 CUDA 12.1 + Python 3.10 的基础 Docker 镜像，上传至内部 Registry；每两周更新基镜像并扫描 CVE。
  2. 算法工程师：在基镜像上使用 pip install -r requirements.txt 安装 Python 依赖，并将 Dockerfile 提交至代码仓库 env/ 目录。
  3. QA/测试：执行章节 3.5 的 verify_environment.py 冒烟测试，通过后标记镜像为 boundary-env:stable-{date}。
  4. DevOps：将稳定镜像写入 CI 配置 .gitlab-ci.yml 或 Jenkinsfile 的 image 字段，确保构建与训练环境一致。
此流程被固化在 docs/sops/env_setup_sop.md，每次迭代需通过 Code Review 更新。

至此，环境搭建环节全部完成。下一阶段将基于此环境进行标准输入准备与格式化（第4章）。所有工程交付物（requirements.txt、Dockerfile、SOP文档）需在 MR 提交前使用 verify_environment.py 自检。

← 上一章 📖 返回目录 下一章 →