docs/current_status.md

# Current Status

## 全量标注修订闭环（2026-05-31）

A official、B full 和 B-lite 已完成 `2620` 图全量推理。基于三组预测与 `gold_release_v1`
的差异，已将“漏标挖掘”升级为“标注修订挖掘”：

- 全量候选：`2694`
- 明确新增漏标：`1479`
- 局部重叠待判定：`1075`
- 疑似粗框拆分：`132`
- 边界扩张复核：`8`

保守分流结果：

- 自动接受新增：`123`
- VLM Judge：`1995`
- 暂缓：`576`

值得视觉复核的 `1995` 个候选聚合为 `1978` 个 VLM case。其中包含 `176` 个
`support>=3` 但仍存在属性冲突、贴边或密集风险的候选。粗框拆分会按旧 GT 聚合，
禁止直接 append。
详细流程见 `docs/analysis/full_annotation_revision_workflow_20260531.md`。

## 最新推进计划（2026-05-24）

当前项目核心目标应表述为：利用 LLM / VLM 的先验知识，构建低人工参与的多 Agent 农业视觉闭环，围绕番茄目标检测、成熟度判断、语义审核、训练评估、漏标挖掘、伪标签回流和跨作物迁移持续迭代。

详细训练与实验时间表已沉淀到 `docs/analysis/training_timeline_20260524.md`。

第一版统一错误分析已完成：

- 分析脚本：`pipelines/analyze_validation_runs.py`
- 可视化脚本：`pipelines/visualize_error_analysis.py`
- 漏标候选挖掘脚本：`pipelines/mine_missing_label_candidates.py`
- 分析文档：`docs/analysis/error_analysis_20260524.md`
- 漏标候选文档：`docs/analysis/missing_label_candidates_20260524.md`
- 结构化输出：`runs/analysis/validation_error_analysis_20260524/`
- 漏标候选输出：`runs/analysis/missing_label_candidates_20260524/`
- 人工复核图：`runs/analysis/validation_error_analysis_20260524/visual_review_images/`
- 高清 300 DPI 人工复核图：`runs/analysis/validation_error_analysis_20260524/visual_review_images_300dpi/`
- 覆盖运行：A official、B full rerun、B old + `occlusion_only`、B-lite dataset。

当前分析结论：

- F1 最好的口径仍是 B old + `occlusion_only`，`f1=0.9046`。
- 遮挡属性最好的口径是 B full rerun，`occlusion_acc=0.7463`。
- 成熟度准确率最高的是 A official，`maturity_acc=0.9408`。
- B-lite 能学习遮挡属性，但没有超过 A official 的检测和成熟度基线。
- 人工复核前 10 张最高风险图后，发现 GT 漏标较明显，模型多出的框多数更像真实番茄候选，而非明显误检。
- 基于多模型预测与 Gold v1 差异，已挖掘出 `227` 个聚类漏标候选，其中 `22` 个被四个模型共同支持，`46` 个被三个模型共同支持。
- 后续应优先做漏标候选挖掘、Gold v1 Review、半成熟颜色一致性检查和语义后验验证。

人工复核记录：

- `docs/reviews/people/validation_error_analysis_20260524.md`
- `docs/reviews/people/validation_error_analysis_20260524_summary.md`

最近最应该做的不是继续盲目训练新的属性增强模型，而是：

1. 人工优先复核 `runs/analysis/missing_label_candidates_20260524/preview_images/` 中 support=4 和 support=3 的漏标候选。
2. 将候选标记为 accepted / rejected / uncertain，形成 Gold v1 Review。
3. 建立 Gold v1 Review 层，保留 Gold v1 不变，避免破坏数据可追溯性。
4. 实现 `SemanticVerifier` 和 `ConsistencyChecker`，把语义从检测输出文本中解耦出来。
5. 落地半成熟颜色比例一致性检查，为语义感知标注提供可复现实证。

当前策略应固定为：检测输出保持简单，语义信息进入数据生产、审核、风险判定、伪标签筛选和蒸馏过程。

## 论文对齐状态（2026-05-01）

当前论文构想已明确为 `AgriAgent: Semantic-Aware Multi-Agent Annotation Distillation for Edge-Oriented Tomato Maturity Detection`。

仓库当前能够支撑论文中的以下部分：

- 多智能体数据生产框架：`annotator -> reviewer -> cleaner -> gold_builder -> exporter -> evaluator` 已有可运行脚本。
- 语义感知数据资产：结构化记录已包含 `maturity_level`、`maturity_ratio`、`occlusion_degree` 和 `reasoning`，训练导出已支持 `attribute_text`。
- 中型 VLM 训练和验证：实验 A 已形成有效检测基线，实验 B 已完成首轮属性增强验证。
- 论文数据统计：Gold v1 包含 `2620` 张图像和 `22793` 个目标。

仓库当前尚不能支撑论文中的以下结论：

- 不能声称已经完成 `0.8B/2B` 边缘小模型蒸馏。
- 不能声称漏标挖掘和伪标签回流已经进入闭环。
- 不能声称跨作物泛化已经验证。
- 不能声称完整消融实验已经完成。

因此，后续写论文时应把上述内容区分为“已验证结果”和“待完成实验”。

## 最新实验更新（2026-05-04）

实验 B-lite 已完成训练与验证。B-lite 是实验 B 的简化语义版本，只保留遮挡 `attribute_text`，去掉局部颜色自由文本。

关键路径：

- 数据目录：`runs/swift_data/qwen3_5_35b_a3b_exp_b_lite_v1/`
- 训练日志：`runs/logs/tomato-exp-b-lite_20260504-214709.log`
- 合并模型：`runs/mid/qwen3_5_35b_a3b_exp_b_lite/v0-20260504-214725/checkpoint-147-merged/`
- dataset 格式验证：`runs/validation_eval/qwen3_5_35b_a3b_exp_b_lite_v0_20260504_2206_dataset/`
- official 格式验证：`runs/validation_eval/qwen3_5_35b_a3b_exp_b_lite_v0_20260504_2239_official/`
- 详细记录：`docs/experiments/experiment_b_lite_training_20260504.md`

主要结果：

| 实验 | precision | recall | f1 | maturity_acc | occlusion_acc |
|---|---:|---:|---:|---:|---:|
| A official baseline | 0.9145 | 0.8857 | 0.8999 | 0.9408 | 0.0 |
| B full attribute rerun | 0.8668 | 0.9253 | 0.8951 | 0.8998 | 0.7463 |
| B old checkpoint + occlusion_only prompt | 0.9046 | 0.9046 | 0.9046 | 0.9107 | 0.6975 |
| B-lite trained + dataset format | 0.876 | 0.9091 | 0.8922 | 0.8909 | 0.7351 |
| B-lite trained + official format | 0.8573 | 0.9082 | 0.882 | 0.8396 | 0.0229 |

当前结论：B-lite 说明遮挡语义本身可学，但只删除颜色自由文本不足以稳定提升检测与成熟度主任务。当前最强口径仍是旧 B checkpoint 配合 `occlusion_only` 推理协议。

## 当前阶段

截至 2026-03-31，仓库已经进入“新版多目标 Silver 链路可运行、可评估、可清洗、正式 Gold 已发布、实验 A 已完成训练与验证、实验 B 已完成训练并进入验证口径修正阶段”的阶段。

当前已经稳定下来的事实：

- 标注任务是“单图多目标”，不是旧版“单图单目标”。
- `disease_suspicion` 已从主链路移除。
- 模型输出 bbox 统一按 `0-1000` 归一化相对坐标理解。
- reviewer 负责把 `bbox_1000` 转换为像素 `bbox`。
- Silver 数据按“每个目标一行”沉淀。
- Gold 数据按 `image_path` 聚合同图多目标 Silver 记录生成。
- 数据验证与训练格式转换保持解耦。

## 截至 2026-03-31 的最新更新

- 正式实验 A 已训练完成，训练日志为 `runs/logs/tomato-exp-a-official_20260323-201257.log`。
- 实验 A 的 merged 模型目录为 `runs/mid/qwen3_5_35b_a3b_exp_a_official/v4-20260323-201311/checkpoint-151-merged/`。
- 已完成实验 A 验证集推理与评估闭环，结果目录为 `runs/validation_eval/qwen3_5_35b_a3b_exp_a_official/`。
- 实验 A 当前有效检测指标：`precision=0.9145`、`recall=0.8857`、`f1=0.8999`、`avg_iou_on_matched=0.9074`。
- 验证链路已切到支持 `vllm` / `transformers` 双后端，默认 `vllm`。
- 已确认一个关键兼容点：模型原始响应中的 `bbox_2d` 常以字符串形式出现；`run_validation_inference.py` 已修复解析逻辑，支持字符串 bbox。
- 与解析修复对应的单测已加入 `tests/test_semantic_evaluator.py`。
- 当前评估结果中的 `occlusion_accuracy_on_matched=0.0`，主要原因不是检测框失败，而是当前输出里缺少可对齐的遮挡属性。
- 实验 B 已完成正式训练，训练日志为 `runs/logs/tomato-exp-b-attr_20260331-192847.log`。
- 实验 B 的 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/`。
- 实验 B 首轮结果为：`precision=0.9341`、`recall=0.3699`、`f1=0.53`、`avg_iou_on_matched=0.9013`、`occlusion_accuracy_on_matched=0.7953`。
- 已确认实验 B 首轮低召回不能直接解释为模型能力退化。更直接的问题是：验证推理阶段丢失了 `val.jsonl` 中的 `assistant` 输出模板，导致属性增强版样本更容易输出长段分析文本，当前 `parse_failure_count=26`。
- `run_validation_inference.py` 已于 `2026-03-31` 修复为：保留原始用户问题，并把 `assistant` 模板转换为额外的显式 JSON 输出约束。
- 与该修复对应的回归测试已加入 `tests/test_semantic_evaluator.py`。
- 当前阻塞点不是代码，而是外部残留 `vllm` 进程占满 4 张卡；待 GPU 空闲后，需要重跑实验 B 验证推理再做正式 A/B 结论。

## 当前 A/B 验证结论应如何理解

当前对实验 A / B 的理解应分成两层：

- 第一层是“已确认事实”：
  - 实验 A 的 detection 基线已成立，当前仍以 `f1=0.8999` 为主对照。
  - 实验 B 的首轮评估显示属性表达能力明显增强，`occlusion_accuracy_on_matched=0.7953`。
- 第二层是“尚不能下最终结论的部分”：
  - 实验 B 首轮 `recall=0.3699` 与 `parse_failure_count=26` 明显异常。
  - 该异常与验证推理阶段没有把属性增强版输出模板显式传给模型高度相关。
  - 因此，当前不能直接下结论说 `attribute_text` 方案在 detection 上失败；应在修复后的同口径验证下重新比较。

## 当前工作区与历史路径说明

当前文档中的部分 Silver 历史路径来自更完整的运行工作区；在当前轻量工作区内，这些目录不一定都被保留。

当前已经核实的事实：

- 仓库根目录 `silver_dataset.jsonl` 是一份可直接使用的 cleaned Silver 快照。
- 该文件当前统计为 `22793` 条记录、`22793` 条有效记录，与 cleaned Silver 的正式统计一致。
- 仓库根目录同时保留了与 cleaned Silver 评估/清洗对应的一组快照文件：
  - `summary.json`
  - `dropped_records.jsonl`
  - `high_iou_pairs.jsonl`
  - `moderate_iou_pairs.jsonl`
- `runs/gold/gold_release_v1/summary.json` 中记录的 `source_dataset_path` 是仓库根目录 `silver_dataset.jsonl`，这反映的是当前工作区里实际用于构建 Gold 的输入文件。

因此，在当前工作区里应这样理解：

- 文档中提到的 `runs/silver/full_rerun_20260311_210637_cleaned/silver_dataset.jsonl` 是历史命名路径。
- 当前实际可用、且已被 Gold 发布元数据引用的 cleaned Silver 输入是仓库根目录 `silver_dataset.jsonl`。

## 当前可用链路

当前已经具备一条完整的新版数据链路：

- `run_pipeline_silver.py`
  负责从图像目录生成 Silver。
- `pipelines/clean_silver_dataset.py`
  负责在不重打云端 API 的前提下，按最新 reviewer 规则重建 cleaned Silver。
- `pipelines/evaluate_silver_dataset.py`
  负责对 Silver 做结构化评估、导出风险样本和预览图。
- `pipelines/manual_qc.py`
  负责对 Silver 做按图抽样人工复核。
- `pipelines/gold_builder.py`
  负责按图聚合有效 Silver，生成正式 Gold 发布目录与摘要产物。
- `pipelines/check_gold_regression.py`
  负责对比两版 Gold 发布结果，检查规模退化、分布漂移和路径可读性。
- `pipelines/evaluate_semantic_predictions.py`
  负责对结构化 prediction 和 reference 结果做逐图对比。
- `pipelines/export_swift_sft_dataset.py`
  负责将 Gold 导出为 Swift / Megatron-SWIFT grounding 训练数据。

## 数据资产现状

### 原始全量新版 Silver

- 路径：`runs/silver/full_rerun_20260311_210637/silver_dataset.jsonl`
- 图像数：`2620`
- 记录数：`23222`
- 有效记录：`23217`
- 无效记录：`5`

对应运行摘要：

- `runs/silver/silver_20260311_210638/summary.json`

### 原始全量 Silver 评估结果

- 路径：`runs/evaluation/silver_eval_20260311_222107/summary.json`
- 平均每图目标数：`8.8615`
- 面积占比 `<0.003` 的小框占比：`16.3242%`
- 面积占比 `<0.001` 的超小框占比：`4.0918%`
- 高 IoU 重复框对数：`12`

结论：

- bbox 换算稳定。
- 中密度图像的 target selection 和 grounding 已明显改善。
- 极拥挤图像中仍存在超小框噪声。

### cleaned Silver

为收敛拥挤场景中的超小框噪声，reviewer 已补入默认过滤规则：

- `MIN_BBOX_1000_SIDE=20`
- `MIN_BBOX_1000_AREA=400`

基于新规则重建后的 cleaned Silver：

- 路径：`runs/silver/full_rerun_20260311_210637_cleaned/silver_dataset.jsonl`
- 清洗摘要：`runs/silver_cleaning/silver_clean_20260311_223551/summary.json`
- 记录数：`22793`
- 剔除记录数：`429`
- 其中超小框剔除：`424`

cleaned Silver 复评结果：

- 路径：`runs/evaluation/silver_eval_20260311_223604/summary.json`
- 平均每图目标数：`8.6996`
- 面积占比 `<0.003` 的小框占比：`14.7677%`
- 面积占比 `<0.001` 的超小框占比：`2.3384%`
- 高 IoU 重复框对数：`11`

当前建议：

- 后续 Gold 构建、抽样复核和新会话分析，优先使用 cleaned Silver。
- 原始全量 Silver 继续保留，作为上游可追溯资产。

## Gold 数据资产现状

当前已经基于 cleaned Silver 发布正式 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 发布事实：

- Gold 已支持正式发布目录，不再只是临时训练中间文件。
- 构建阶段已支持将历史 Windows 图片路径重写为当前 Linux 可用路径。
- 原始路径保存在 `source_image_path` 中，便于跨平台追溯。
- `gold_release_v1` 已可作为后续训练、评估和版本回归检查的基线。

## 训练数据资产现状

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

### 实验 A：官方一致版

- 路径：`runs/swift_data/qwen3_5_35b_a3b_exp_a_official_v2/`
- 数据文件：
  - `train.jsonl`
  - `val.jsonl`
  - `summary.json`
  - `report.md`

### 实验 B：属性增强版

- 路径：`runs/swift_data/qwen3_5_35b_a3b_exp_b_attr_v2/`
- 数据文件：
  - `train.jsonl`
  - `val.jsonl`
  - `summary.json`
  - `report.md`

两套数据共同事实：

- 都基于 Gold 生成，不回流污染 Silver。
- 都兼容 Swift / Megatron-SWIFT grounding 格式。
- `objects.bbox` 使用像素绝对框，由 `ms-swift` 自动处理坐标缩放。
- Qwen3.5 模型侧 bbox 仍按 `0-1000` 相对坐标理解。
- 实验 A 仅监督 `bbox_2d + label`。
- 实验 B 额外引入 `attribute_text`，用于对照离散语义属性是否带来收益。

## 工程状态

### 已完成

- 新版 `annotator -> reviewer -> silver -> gold_builder` 契约已经对齐。
- reviewer 已支持 `bbox_1000 -> bbox` 转换和超小框抑制。
- Silver 评估脚本和 Silver 清洗脚本已具备可复用 CLI。
- Gold 构建脚本已支持正式发布目录、JSON 摘要、Markdown 报告和抽样检查清单。
- Gold 回归检查脚本已可对比两版发布结果，检查规模退化、分布漂移和路径可读性。
- `SemanticEvaluator` 第一版已支持 reference/prediction 逐图对比、风险样本导出与摘要生成。
- Swift / Megatron-SWIFT 训练数据导出脚本已支持 `official` 和 `attr_enhanced` 两种实验模式。
- `Qwen3.5-35B-A3B` 的 Megatron-SWIFT 训练脚本已补齐：
  - `scripts/train_qwen3_5_35b_a3b_exp_a_official.sh`
  - `scripts/train_qwen3_5_35b_a3b_exp_b_attr.sh`
- 本地烟测脚本中的明文 API key 已移除，统一改为环境变量。
- 关键脚本已补齐更稳定的 CLI 参数。
- 已补 `requirements.txt`、`.env.example`、`docs/deployment/deploy_linux.md`。
- 已补最小测试：
  - `tests/test_reviewer.py`
  - `tests/test_gold_builder.py`
  - `tests/test_gold_regression.py`
  - `tests/test_semantic_evaluator.py`
  - `tests/test_swift_sft_export.py`

### 已验证

- 关键 Python 脚本已通过 `py_compile`。
- `python -m unittest discover tests -v` 已通过。
- 关键 CLI 帮助入口已可正常调用。
- `run_validation_inference.py` 新增“把 assistant 模板转成显式 JSON 输出约束”的回归测试已通过。
- 训练环境 `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`

## Linux 迁移准备状态

当前仓库已经基本具备迁移到 Linux 服务器的条件，已补齐：

- `requirements.txt`
- `.env.example`
- `docs/deployment/deploy_linux.md`
- 面向 CLI 的运行入口
- 最小测试

迁移前仍建议在 Linux 干净虚拟环境中补一轮完整小样本冒烟：

1. Silver 小样本试跑
2. Silver 清洗
3. Silver 评估
4. Gold 构建

## 训练准备状态

当前训练侧已经完成：

1. Gold -> Swift / Megatron-SWIFT grounding 数据导出
2. 实验 A / B 两套训练数据生成
3. `Qwen3.5-35B-A3B` Megatron-SWIFT 训练脚本补齐
4. 独立 conda 训练环境 `lsy-agent` 验收通过

当前训练侧已不再停留在“环境准备”阶段，而是进入了真实开训与兼容性收敛阶段：

- 统一训练环境为 `lsy-agent`
- 已安装 `transformer_engine 2.12.0` 与 `megatron-core 0.16.1`
- 已安装 `CUDA toolkit 12.8` 以匹配 `torch 2.10.0+cu128` 的编译环境
- 训练日志已统一落盘到 `runs/logs/`
- 由于本机 `flash` attention backend 不可用，正式训练默认切换为 `unfused`
- 实验 A 正式训练已于 `2026-03-23` 成功进入 step 级训练循环，最新日志为 `runs/logs/tomato-exp-a-official_20260323-201257.log`

## 当前下一步计划

1. 等 GPU 空闲后，基于已修复的 `run_validation_inference.py` 重跑实验 B 验证推理。
2. 在同口径下重新对比实验 A / B，重点看 `parse_failure_count`、`recall`、`f1`、`maturity_accuracy_on_matched` 和 `occlusion_accuracy_on_matched`。
3. 将实验 A / B 结果整理成论文表格，并保留验证命令、模型路径和 summary 路径。
4. 对 `runs/validation_compare/exp_a_vs_b_20260331_201545/` 中的三联图做错误案例归类。
5. 补半成熟颜色比例一致性检查，形成可复现的语义标注质量指标。
6. 将 `SemanticEvaluator.evaluate_and_mine` 落地为漏标挖掘与伪标签候选筛选。
7. 明确边缘小模型路线，推进蒸馏或小模型 SFT，并采集资源指标。
8. 在核心结果稳定后再做消融实验和跨作物泛化实验。

## 新会话建议

新的编码会话进入仓库时，建议优先阅读：

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`