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. 虚拟环境与依赖安装

```bash
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. 环境变量检查

先复制模板：

```bash
cp .env.example .env
```

至少确认以下变量可用：

- `QWEN_API_KEY`
- `QWEN_BASE_URL`
- `QWEN_MODEL`

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

```bash
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. 先跑最小单元测试

```bash
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 张以内：

```bash
python run_pipeline_silver.py --process-limit 10
```

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

```bash
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 结果继续：

```bash
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

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

检查点：

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

## 10. 构建 Gold

```bash
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