docs/deployment/deploy_linux.md

# Linux Deploy

这份文档面向把仓库迁移到 Linux 服务器后的首次部署。

如果你准备做首次受控实验，建议同时阅读：

- `docs/deployment/linux_first_experiment_checklist.md`

## 1. 系统要求

建议环境：

- Python 3.10 或 3.11
- `pip`
- 能访问 DashScope 兼容接口的网络环境

如果只跑当前数据生产与评估链路，不需要 GPU。

## 2. 克隆仓库

```bash
git clone <your-repo-url>
cd agent-base
```

## 3. 创建虚拟环境

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

## 4. 配置环境变量

先复制模板：

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

然后至少配置：

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

如果不使用 `.env` 自动加载，就在 shell 中手动导出：

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

## 5. 小样本冒烟测试

建议先做受控试跑：

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

如果你希望显式指定目录：

```bash
python run_pipeline_silver.py \
  --image-dir ./clearn_base_data \
  --process-limit 10
```

## 6. 清洗已有 Silver

```bash
python -m pipelines.clean_silver_dataset \
  --input runs/silver/full_rerun_xxx/silver_dataset.jsonl \
  --output runs/silver/cleaned/silver_dataset.jsonl \
  --min-bbox-1000-side 20 \
  --min-bbox-1000-area 400
```

## 7. 评估 Silver

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

## 8. 生成 Gold

```bash
python -m pipelines.gold_builder \
  --silver-dataset-path runs/silver/cleaned/silver_dataset.jsonl \
  --output-dir runs/gold/gold_release_v1
```

建议把正式 Gold 当作一个发布目录，而不是单个 JSONL 文件。当前默认会同时生成：

- `gold_dataset.jsonl`
- `summary.json`
- `report.md`
- `sample_check.jsonl`

## 9. 人工复核抽样

```bash
python -m pipelines.manual_qc \
  --silver-dataset-path runs/silver/cleaned/silver_dataset.jsonl \
  --sample-size 12
```

## 10. 当前建议的服务器工作流

1. 先跑小样本 Silver。
2. 再做评估与人工复核。
3. 确认质量后跑全量 Silver。
4. 用 `clean_silver_dataset.py` 产出 cleaned Silver。
5. 以 cleaned Silver 为默认输入生成 Gold。

## 11. 迁移前后最需要注意的点

- 不要在代码里写死 API key。
- 不要依赖 Windows 路径。
- 后续默认优先使用 cleaned Silver，而不是历史旧 Silver。
- 训练格式转换只放在 Gold 阶段，不要混入 Silver 阶段。