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. 克隆仓库

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

3. 创建虚拟环境

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

4. 配置环境变量

先复制模板：

cp .env.example .env

然后至少配置：

• QWEN_API_KEY
• QWEN_BASE_URL
• QWEN_MODEL

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

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

5. 小样本冒烟测试

建议先做受控试跑：

python run_pipeline_silver.py --process-limit 10

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

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

6. 清洗已有 Silver

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

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

8. 生成 Gold

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. 人工复核抽样

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 阶段。