一、定位Runner与本地的核心环境差异 #

既然本地跑gitlab-ci-local没问题，但真实GitLab Runner失败，核心差异肯定在Runner的硬件/系统/底层依赖上，先做这些排查：

• 输出系统与硬件信息：在before_script里加命令，确认CPU架构、指令集是否和本地一致：

  uname -a
  cat /proc/cpuinfo | grep 'model name' | head -1
  

  比如本地是x86_64，Runner突然切换到arm64，会导致numpy/scipy的底层优化库行为差异。
• 检查数值计算后端：在after_script里添加Python代码，输出numpy/scipy的BLAS/LAPACK配置，和本地对比：

  python -c "import numpy; print(numpy.show_config())"
  python -c "import scipy; print(scipy.show_config())"
  

  不同后端（比如MKL vs OpenBLAS）的浮点计算精度、随机数实现可能有细微差别，这是数值测试失败的常见原因。
• 验证随机数确定性：在CI脚本里单独跑一个极简测试，对比本地输出：

  import numpy as np
  rng = np.random.default_rng(seed=42)
  print("随机数样本:", rng.normal(size=5))
  mat = rng.random((3,3))
  mat = mat + mat.T  # 构造对称矩阵
  vals, vecs = np.linalg.eigh(mat)
  print("eigh特征值:", vals)
  

  如果随机数样本一致但eigh结果有微差，说明是线性代数后端的问题；如果随机数都不一样，那要检查Runner的环境变量是否干扰了种子（比如PYTHONHASHSEED）。

二、针对具体失败案例的修复 #

1. scipy.optimize.leastsq的数值差异 #

• 放弃精确断言，改用pytest.approx()设置合理误差范围：

  # 原代码（易失败）
  assert result == expected_value
  # 修改后（鲁棒性强）
  assert result == pytest.approx(expected_value, rel=1e-5, abs=1e-8)
  

  不同数值后端的浮点计算本来就会有细微偏差，这是科学计算测试的标准做法。
• 固定求解器参数：给leastsq指定明确的收敛阈值（比如ftol=1e-10、xtol=1e-10），减少不同环境下的收敛差异。

2. numpy固定种子但eigh结果异常 #

• 同样用pytest.approx()断言特征值/特征向量，不要追求精确匹配：

  assert computed_eigenvalues == pytest.approx(expected_eigenvalues, rel=1e-6)
  

• 控制BLAS线程数：在CI的before_script里加环境变量，避免多线程计算导致的非确定性：

  export OPENBLAS_NUM_THREADS=1
  export MKL_NUM_THREADS=1
  export NPY_NUM_THREADS=1
  

  部分BLAS库在多线程模式下，计算顺序会随CPU调度变化，导致结果微差。

三、避免未来同类问题的预防措施 #

• 锁定全链路依赖：除了用uv.lock锁定Python包，还要固定CI使用的基础镜像版本（比如ghcr.io/astral-sh/uv:python3.10-bookworm-20240501，而不是动态的bookworm），防止系统底层库更新引入差异。
• 统一Runner环境：使用自托管Runner，确保硬件架构、系统版本、数值计算库和本地开发环境完全一致；如果用共享Runner，指定固定版本的Runner标签，避免自动升级带来的变化。
• 增强测试鲁棒性：所有涉及数值计算的测试，一律使用近似断言，禁止精确相等判断；对随机数相关测试，除了固定种子，还要验证关键统计特征（如均值、方差）而非单个样本值。
• 定期验证环境一致性：在CI脚本中加入步骤，对比本地和CI的关键环境参数（Python版本、numpy/scipy版本、BLAS后端），不一致则直接报错，提前发现问题。
• 缩短测试间隔：不要等两个月才跑CI，每次提交都触发测试，及时捕捉环境变化带来的问题。

附用户提供的CI配置（仅失败阶段）：

variables:
  BASE_LAYER: bookworm
  UV_LINK_MODE: copy
  UV_CACHE_DIR: .uv-cache

cache:
  - key:
      files:
        - uv.lock
    paths:
    - $UV_CACHE_DIR

workflow:
  auto_cancel:
    on_job_failure: all
    on_new_commit: interruptible

image: ghcr.io/astral-sh/uv:python3.10-$BASE_LAYER

before_script:
  - python --version
  - uv --version

after_script:
  - uv pip list

stages: [lint_test, test]

lint_test:
  stage: lint_test
  interruptible: true
  script:
    - uv tool run ruff format --diff 
    - uv tool run ruff check
    - uv run --with "[test]" pytest -vvv
    - uv cache prune --ci

内容的提问来源于stack exchange，提问作者ProodjePindakaas