.gitlab-ci.yml是gitlab ci/cd的核心配置文件，必须置于项目根目录，定义stages、jobs、variables、cache、before_script及rules等，实现分层测试（cpu单元测试+gpu轻量训练）、环境隔离与精准触发。
代码提交后自动跑测试，不是“能不能”，而是“怎么配得稳、跑得准、反馈快”。关键不在堆功能，而在分层验证、环境隔离和触发精准。
配置核心文件 .gitlab-ci.yml
这个 YAML 文件必须放在项目根目录，GitLab 会自动识别并启动流水线。它定义了阶段（stages）、作业（jobs）、运行环境和执行逻辑。
- 每个 job 属于一个 stage，比如 test、build、deploy，stage 内 jobs 默认并行，stage 之间顺序执行
- 用 variables 统一管理环境变量（如 PYTHON_VERSION、CI_REGISTRY）
- 用 cache 缓存 pip/conda 包或构建产物，避免每次重装依赖
- before_script 是公共前置操作，比如激活虚拟环境、安装基础依赖
设置触发条件，避免无效流水线
不是每次 push 都该跑完整流程。合理使用 rules 或 only/except 控制触发时机，节省资源也提升响应速度。
- 仅在 main 分支或合并请求（MR）时运行训练验证： rules: - if: '$CI_COMMIT_BRANCH == "main" || $CI_PIPELINE_SOURCE == "merge_request_event"'
- 打 tag 时才部署生产环境： rules: - if: $CI_COMMIT_TAG
- 跳过带特定关键词的提交（如 [skip ci]）： rules: - if: $CI_COMMIT_MESSAGE !~ /\[skip ci\]/
分层测试：CPU 快检 + GPU 小训
LoRA 类项目尤其需要两级验证——光跑通 import 不代表能训，光训通小数据也不代表配置无硬伤。
- 单元测试（CPU 环境）：检查脚本导入、参数解析、函数签名、mock 数据加载逻辑，用 pytest 运行，几秒内出结果
- 轻量训练验证（GPU 环境）：用 2–4 张图+1 轮迭代跑通全流程，验证 config 加载、auto_label、train.py 启动、输出目录生成，不追求指标，只保通路
- 两个 job 分属不同 stage，失败即中断后续，避免浪费 GPU 时间
确保环境一致性，杜绝“本地能跑”陷阱
CI 失败常因环境差异，不是代码问题。容器化 + 显式声明是解法。
- 指定 runner 标签（如 tags: - gpu-runner-small），让任务落到预装 CUDA/cuDNN 的机器上
- 用 conda 或 venv 显式创建隔离环境，不依赖系统 Python 或全局包
- requirements.txt 必须锁定关键版本（transformers==4.40.2、peft==0.11.1），避免自动升级引入 break change
- 若用 Docker，基础镜像优先选官方 PyTorch CUDA 镜像（如 pytorch/pytorch:2.3.0-cuda12.1-cudnn8-runtime）
