docs/deployment/linux_first_experiment_checklist.md

Linux First Experiment Checklist

这份清单面向仓库首次迁移到 Linux 服务器后的受控实验。

目标不是一次性跑完整闭环，而是先确认当前已经稳定的 Silver -> cleaned Silver -> Eval -> Gold 链路可以在服务器上可靠运行。

1. 打包前检查

• 确认仓库内包含以下文件：
• AGENTS.md
• README.md
• requirements.txt
• .env.example
• run_pipeline_silver.py
• docs/deployment/deploy_linux.md
• docs/current_status.md
• 确认需要随仓库一起带到服务器的数据目录是否已经准备好：
• clearn_base_data/ 或你自己的图片目录
• 如需直接复用历史结果，再带上对应 runs/ 目录
• 确认仓库中不存在明文 API key。
• 确认本次实验默认使用的输入数据是 cleaned Silver，而不是历史旧 Silver。

2. 服务器环境检查

• Linux 服务器已安装 Python 3.10 或 3.11。
• 可以创建虚拟环境。
• 可以访问 DashScope 兼容接口。
• 如果只跑当前数据生产、清洗、评估、Gold 构建链路，不要求 GPU。
• 如果后续要做真实训练，再单独确认 CUDA、显卡驱动和训练框架环境。

3. 仓库落地后检查

进入仓库根目录后先确认以下路径存在：

• run_pipeline_silver.py
• agents/
• pipelines/
• schemas/
• tests/
• docs/

再重点确认图片目录：

• 默认代码路径是 ./clearn_base_data
• 如果服务器上不打算使用这个目录名，首次运行时必须显式传 --image-dir

4. 虚拟环境与依赖安装

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt

检查点：

• pip install -r requirements.txt 无报错
• python --version 符合预期

5. 环境变量检查

先复制模板：

cp .env.example .env

至少确认以下变量可用：

• QWEN_API_KEY
• QWEN_BASE_URL
• QWEN_MODEL

如果不依赖 .env 自动加载，就手动导出：

export QWEN_API_KEY="your-key"
export QWEN_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
export QWEN_MODEL="qwen3.5-plus"

检查点：

• 变量已经在当前 shell 中生效
• 不要把 key 写回脚本

6. 先跑最小单元测试

python -m unittest tests.test_reviewer
python -m unittest tests.test_gold_builder

通过标准：

• tests.test_reviewer 通过
• tests.test_gold_builder 通过

这一步通过，说明 reviewer 和 gold builder 的最小基础能力在当前服务器环境里是通的。

7. 首次 Silver 小样本冒烟

推荐先控制在 10 张以内：

python run_pipeline_silver.py --process-limit 10

如果图片目录不是默认的 ./clearn_base_data，显式指定：

python run_pipeline_silver.py \
  --image-dir ./your_image_dir \
  --process-limit 10

检查点：

• 运行过程没有 import 错误
• API 调用可以成功返回
• runs/silver/ 下生成新的 run 目录
• run 目录中出现：
• silver_dataset.jsonl
• summary.json
• progress.json
• pipeline.log
• 输出记录里包含：
• bbox_1000
• 像素 bbox
• is_valid

8. 清洗小样本 Silver

用刚生成的 Silver 结果继续：

python -m pipelines.clean_silver_dataset \
  --input runs/silver/<your_run>/silver_dataset.jsonl \
  --output runs/silver/<your_run>_cleaned/silver_dataset.jsonl \
  --min-bbox-1000-side 20 \
  --min-bbox-1000-area 400

检查点：

• 清洗脚本能正常读取输入 JSONL
• 输出 cleaned Silver 成功生成
• 清洗摘要存在

9. 评估 cleaned Silver

python -m pipelines.evaluate_silver_dataset \
  --silver-dataset-path runs/silver/<your_run>_cleaned/silver_dataset.jsonl \
  --risk-sample-size 12

检查点：

• 评估摘要成功生成
• 能看到有效记录、风险样本或重复框统计
• bbox 没有明显越界或整体空跑

10. 构建 Gold

python -m pipelines.gold_builder \
  --silver-dataset-path runs/silver/<your_run>_cleaned/silver_dataset.jsonl \
  --output-dir runs/gold/gold_release_v1

检查点：

• runs/gold/gold_release_v1/gold_dataset.jsonl 成功生成
• 同目录下同时出现 summary.json、report.md、sample_check.jsonl
• Gold 按图聚合，而不是按目标逐行输出
• messages 中 assistant 内容仍使用结构化 annotations

11. 首次实验通过标准

满足以下条件，就可以认为“Linux 首次受控实验通过”：

• 依赖安装成功
• 环境变量配置成功
• 最小单元测试通过
• Silver 小样本冒烟通过
• cleaned Silver 生成成功
• cleaned Silver 评估成功
• Gold 构建成功

12. 暂时不要误判为已完成的部分

以下能力目前还不应视为“服务器上可直接开展完整实验”：

• SemanticEvaluator 真实可用
• Orchestrator 闭环状态机可用
• 完整自动化漏标挖掘回流
• 真实 GPU 训练已在服务器验证完成

也就是说，当前最稳妥的实验边界仍然是：

1. 小样本 Silver
2. cleaned Silver
3. Eval
4. Gold
5. 再决定是否继续接训练

13. 建议的首次实验顺序

按下面顺序最稳：

1. 安装依赖
2. 配置环境变量
3. 跑最小测试
4. 跑 Silver 小样本
5. 清洗 Silver
6. 评估 cleaned Silver
7. 构建 Gold
8. 人工抽样复核
9. 再决定是否上更大批量实验

14. 实验后建议保留的产物

首次实验结束后，建议保留以下目录和文件，方便回溯：

• runs/silver/...
• runs/evaluation/...
• runs/silver_cleaning/...
• runs/gold/...
• 对应的 summary.json
• 首次实验时使用的环境变量说明，但不要保存明文 key