README.md

# agent-base

本仓库用于构建一个面向精准农业场景的多模态大模型闭环系统，当前聚焦于西红柿的单图多目标认知标注、审核、数据构建、训练评估与边缘部署前置实验。

当前论文构想暂定为 `AgriAgent: Semantic-Aware Multi-Agent Annotation Distillation for Edge-Oriented Tomato Maturity Detection`。仓库工程应围绕三条主线推进：

1. 语义感知自动标注：用云端 VLM 的颜色比例、遮挡程度和 reasoning 缓解半成熟边界模糊。
2. 多智能体闭环数据生产：按 Raw / Silver / Gold / Eval 分层沉淀结构化资产，保持审核和训练格式转换解耦。
3. 边缘导向蒸馏：用中型 VLM 做训练、评估和漏标挖掘，再将能力压缩到低资源小模型。

论文框架、当前证据和待补实验见 `docs/paper_alignment.md`。

## 截至 2026-03-31 的最新状态

- 正式实验 A 已完整训练结束，产物目录为 `runs/mid/qwen3_5_35b_a3b_exp_a_official/v4-20260323-201311/`。
- 当前推荐实验 A 验证模型目录为 `runs/mid/qwen3_5_35b_a3b_exp_a_official/v4-20260323-201311/checkpoint-151-merged/`。
- 已补齐验证集推理链路：`prepare_validation_reference -> run_validation_inference -> evaluate_semantic_predictions`。
- 验证推理当前默认支持 `vllm` 与 `transformers` 双后端，默认走 `vllm`。
- 已修复验证解析 bug：模型输出中的字符串形式 `bbox_2d`（如 `"[290, 526, 380, 754]"`）现在可被正确解析，不再出现“模型明明输出了框但评估结果全 0”的假象。
- 实验 A 当前有效验证结果：`precision=0.9145`、`recall=0.8857`、`f1=0.8999`、`avg_iou_on_matched=0.9074`。
- 实验 A 验证结果目录：`runs/validation_eval/qwen3_5_35b_a3b_exp_a_official/`。
- `tests/test_semantic_evaluator.py` 已新增回归测试，覆盖 `think` 包裹 + 字符串 bbox 的真实模型输出格式。
- 实验 B 已完成正式训练，产物目录为 `runs/mid/qwen3_5_35b_a3b_exp_b_attr/v1-20260331-192847/`，merged 模型目录为 `runs/mid/qwen3_5_35b_a3b_exp_b_attr/v1-20260331-192847/checkpoint-145-merged/`。
- 实验 B 首轮验证结果目录为 `runs/validation_eval/qwen3_5_35b_a3b_exp_b_attr/`，当前结果为 `precision=0.9341`、`recall=0.3699`、`f1=0.53`、`occlusion_accuracy_on_matched=0.7953`。
- 已确认首轮实验 B 结果不能直接视为模型真实退化，主要问题是验证推理阶段丢失了 `assistant` 输出模板，导致属性增强版样本更容易输出长段分析文本并出现 `parse_failure_count=26`。
- `run_validation_inference.py` 已在 `2026-03-31` 修复为：保留原始用户问题，并把 `val.jsonl` 中的 `assistant` 模板转成额外的显式 JSON 输出约束。
- 与该修复对应的回归测试已加入 `tests/test_semantic_evaluator.py`。
- 当前待办不是继续改训练，而是在 GPU 空闲后重跑实验 B 验证推理，确认修复后 detection recall 和 parse failure 是否回升。

## 当前稳定数据契约

当前主链路严格遵循以下事实：

- 标注任务已经从“单图单目标”切换为“单图多目标”。
- 当前阶段不再保留 `disease_suspicion` 字段。
- 模型输出的 bbox 统一按 `0-1000` 归一化相对坐标理解。
- reviewer 负责把 `bbox_1000` 转换为像素 `bbox`。
- `silver_dataset.jsonl` 采用“每个目标一行”的沉淀方式。
- `gold_builder` 按 `image_path` 聚合同图多目标 Silver 记录，再生成单图 Gold 样本。
- 正式 Gold 发布除 `gold_dataset.jsonl` 外，还应同时输出 `summary.json`、`report.md`、`sample_check.jsonl`。

## 论文结果对应关系

当前仓库已能支撑论文中的数据集、系统架构和中型模型验证部分：

- Gold v1：`2620` 张图像、`22793` 个目标，平均每图 `8.6996` 个目标。
- 成熟度分布：`未成熟=14397`、`半成熟=3566`、`完熟=4830`。
- 遮挡分布：`无=9727`、`轻度=9554`、`重度=3512`。
- 实验 A 检测基线：`precision=0.9145`、`recall=0.8857`、`f1=0.8999`。
- 实验 B 首轮显示属性表达有潜力：`occlusion_accuracy_on_matched=0.7953`，但当前低召回受验证输出协议影响，需要重跑。

论文草稿中提到的边缘 `0.8B/2B` 蒸馏、跨作物泛化和完整消融实验仍未完成，当前文档不得把这些写成已验证结论。

## 截至 2026-03-20 的当前状态

### 1. 数据链路状态

仓库当前已经具备一条可运行的新版多目标数据链路：

- `run_pipeline_silver.py`：生成 Silver
- `pipelines/clean_silver_dataset.py`：清洗已有 Silver
- `pipelines/evaluate_silver_dataset.py`：评估 Silver
- `pipelines/manual_qc.py`：人工复核抽样
- `pipelines/gold_builder.py`：构建 Gold
- `pipelines/check_gold_regression.py`：对比两版 Gold 发布结果，检查是否存在明显回归
- `pipelines/evaluate_semantic_predictions.py`：对结构化预测结果做逐图语义评估

当前推荐下游优先使用 cleaned Silver，而不是原始全量 Silver。

### 2. 现有数据资产

- 原始全量 Silver：`runs/silver/full_rerun_20260311_210637/silver_dataset.jsonl`
- cleaned Silver：`runs/silver/full_rerun_20260311_210637_cleaned/silver_dataset.jsonl`
- Silver 清洗摘要：`runs/silver_cleaning/silver_clean_20260311_223551/summary.json`
- cleaned Silver 评估摘要：`runs/evaluation/silver_eval_20260311_223604/summary.json`

当前 cleaned Silver 规模：

- 记录数：`22793`
- 清洗掉记录：`429`
- 其中超小框剔除：`424`

### 3. 正式 Gold 发布状态

当前已经基于 cleaned Silver 发布正式 Gold：

- 正式 Gold：`runs/gold/gold_release_v1/gold_dataset.jsonl`
- 发布摘要：`runs/gold/gold_release_v1/summary.json`
- 发布报告：`runs/gold/gold_release_v1/report.md`
- 抽样检查：`runs/gold/gold_release_v1/sample_check.jsonl`

当前 `gold_release_v1` 规模：

- 图像数：`2620`
- 目标数：`22793`
- 平均每图目标数：`8.6996`

说明：

- Gold 构建阶段已支持把历史 Windows `image_path` 重写为当前 Linux 可用路径。
- 原始路径会保存在 `source_image_path` 中，便于后续追溯。
- 当前 `gold_release_v1` 已可作为后续训练和评估的正式基线。

### 4. 训练数据与训练脚本准备状态

当前已经基于 `gold_release_v1` 导出两套 `Qwen3.5-35B-A3B` 训练数据：

- 实验 A（官方一致版）：
  - `runs/swift_data/qwen3_5_35b_a3b_exp_a_official_v2/train.jsonl`
  - `runs/swift_data/qwen3_5_35b_a3b_exp_a_official_v2/val.jsonl`
- 实验 B（属性增强版）：
  - `runs/swift_data/qwen3_5_35b_a3b_exp_b_attr_v2/train.jsonl`
  - `runs/swift_data/qwen3_5_35b_a3b_exp_b_attr_v2/val.jsonl`

两套数据共同遵循以下原则：

- 检测主格式走 Swift / Megatron-SWIFT grounding 兼容格式。
- `objects.bbox` 保持像素绝对框，交给 `ms-swift` 自动处理。
- Qwen3.5 的 bbox 输出仍按 `0-1000` 归一化相对坐标理解。
- 实验 A 只保留 `bbox_2d + label`。
- 实验 B 在 `bbox_2d + label` 基础上额外增加 `attribute_text`。

当前也已补齐两套训练脚本：

- `scripts/train_qwen3_5_35b_a3b_exp_a_official.sh`
- `scripts/train_qwen3_5_35b_a3b_exp_b_attr.sh`

### 5. 训练环境准备状态

当前已完成独立训练环境 `lsy-agent` 的准备和验收：

- Python：`3.11.15`
- `torch 2.10.0+cu128`
- `ms-swift 4.0.2`
- `transformers 5.3.0`
- `deepspeed 0.18.8`
- `flash-linear-attention 0.4.2`
- `flash_attn 2.8.3`
- `causal_conv1d 1.6.1`

已验证：

- `torch.cuda.is_available()` 为 `True`
- `flash_attn` 可导入
- `causal_conv1d` 可导入

当前训练环境统一约定为 `lsy-agent`，不要再混用历史 `lsy` 环境。

当前已额外完成并验证：

- `transformer_engine 2.12.0` 可在 `lsy-agent` 中导入
- `megatron-core 0.16.1` 已安装
- 训练脚本已统一把控制台日志落盘到 `runs/logs/`
- 当前正式实验 A 默认改为 `--attention_backend unfused`，以绕过本机 `flash` backend 不可用的问题

截至 `2026-03-23`，实验 A 正式训练已在 `lsy-agent` 中成功拉起并进入 step 级训练循环，最新日志位于 `runs/logs/tomato-exp-a-official_20260323-201257.log`。

### 6. 服务器迁移准备状态

为了迁移到 Linux 服务器，当前仓库已经补齐：

- `requirements.txt`
- `.env.example`
- `docs/deployment/deploy_linux.md`
- 最小测试：`tests/test_reviewer.py`、`tests/test_gold_builder.py`
- 更稳定的 CLI 入口：`run_pipeline_silver.py`、`pipelines/gold_builder.py`、`pipelines/manual_qc.py`

另外，仓库中原来本地烟测脚本里的明文 key 已被移除，统一改为走环境变量。

## 当前推荐调用方式

### 1. Linux 上首次部署

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

然后按 `docs/deployment/deploy_linux.md` 配置环境变量与运行顺序。

### 2. Silver 小样本试跑

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

### 3. 评估 cleaned Silver

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

### 4. 构建正式 Gold

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

默认不传 `--output-dir` 时，会自动生成 `runs/gold/gold_release_<timestamp>/` 发布目录。

### 5. 对比两版 Gold，检查回归

```bash
python -m pipelines.check_gold_regression \
  --baseline runs/gold/gold_release_v1 \
  --candidate runs/gold/gold_release_v2
```

### 6. 评估结构化预测结果

```bash
python -m pipelines.evaluate_semantic_predictions \
  --reference-dataset-path runs/gold/gold_release_v1/gold_dataset.jsonl \
  --prediction-dataset-path runs/predictions/model_a_predictions.jsonl
```

### 7. 导出 Qwen3.5 训练数据

```bash
python -m pipelines.export_swift_sft_dataset \
  --gold-dataset-path runs/gold/gold_release_v1/gold_dataset.jsonl \
  --output-dir runs/swift_data/qwen3_5_35b_a3b_exp_a_official_v2 \
  --export-mode official
```

```bash
python -m pipelines.export_swift_sft_dataset \
  --gold-dataset-path runs/gold/gold_release_v1/gold_dataset.jsonl \
  --output-dir runs/swift_data/qwen3_5_35b_a3b_exp_b_attr_v2 \
  --export-mode attr_enhanced
```

### 8. 启动 Qwen3.5-35B-A3B 训练

训练日志会自动写入 `runs/logs/`，便于后续排查与复盘。



```bash
conda activate lsy-agent
bash scripts/train_qwen3_5_35b_a3b_exp_a_official.sh
```

```bash
conda activate lsy-agent
bash scripts/train_qwen3_5_35b_a3b_exp_b_attr.sh
```

说明：

- 当前脚本基于官方 `Qwen3.5-35B-A3B` + Megatron-SWIFT 最佳实践整理。


## 下一步最合理的计划

1. 在 GPU 空闲后，基于已修复的验证推理请求构造重跑实验 B。
2. 重新对比实验 A / B，整理成论文表格：detection、maturity、occlusion、parse failure。
3. 对三联图和风险样本做错误归类，重点分析半成熟、遮挡和密集目标。
4. 补一个可复现的颜色比例一致性检查，用于支撑 `Semantic-Aware Annotation Strategy`。
5. 明确边缘模型路线，优先完成一个小模型训练与资源指标采集。
6. 将 `SemanticEvaluator.evaluate_and_mine` 落地为漏标挖掘流程。
7. 在结果稳定后设计消融实验：去语义标注、去审核 Agent、去漏标挖掘、去蒸馏。

## 新会话建议先读

1. `AGENTS.md`
2. `README.md`
3. `docs/architecture.md`
4. `docs/roadmap.md`
5. `docs/current_status.md`
6. `docs/paper_alignment.md`
7. `docs/reference/repo_map.md`
8. `docs/deployment/deploy_linux.md`