docs/paper_alignment.md

# Paper Alignment

本文档用于把当前论文构想与仓库工程状态对齐。论文暂定题目为：

`AgriAgent: Semantic-Aware Multi-Agent Annotation Distillation for Edge-Oriented Tomato Maturity Detection`

## 论文主线

论文不应被写成“单次模型训练报告”，而应围绕一套面向精准农业的闭环系统展开：

1. 使用云端 VLM 对番茄图像做语义感知自动标注，尤其处理未成熟、半成熟、完熟之间的连续颜色过渡。
2. 使用多智能体数据链路把 Raw / Silver / Gold / Eval 数据分层沉淀，避免把业务校验与训练格式转换混在一起。
3. 使用中型开源 VLM 做训练、评估、漏标挖掘和伪标签候选筛选。
4. 将中型或云端模型的判别能力蒸馏到边缘小模型，服务农业采摘机器人、无人机巡检等低算力场景。
5. 用检测指标、语义属性指标、资源占用指标和消融实验证明闭环设计的有效性。

截至 2026-05-24，后续训练和实验推进计划已整理到 `docs/analysis/training_timeline_20260524.md`。当前论文叙事应避免把“语义增强”简化为“在检测输出中加入自然语言属性”。更稳妥的表述是：利用 LLM / VLM 的先验知识进行数据生产、语义审核、风险判定、漏标挖掘、伪标签筛选和边缘蒸馏。

## 建议论文贡献

当前仓库最适合支撑以下三个贡献点：

1. 提出 AgriAgent 多智能体闭环框架，覆盖自动标注、审核清洗、Gold 构建、训练导出、模型验证和后续漏标挖掘。
2. 提出语义感知成熟度标注策略，用颜色占比、遮挡程度和 reasoning 辅助约束半成熟等模糊边界。
3. 面向边缘部署做模型压缩与蒸馏实验，在保持检测性能的同时降低参数量、显存占用和推理延迟。

其中第 1 点和第 2 点已有较强工程基础；第 3 点仍需要后续补实验。

## 当前仓库已能支撑的论文材料

### 数据集与标注资产

- cleaned Silver：`22793` 条有效目标记录。
- Gold v1：`2620` 张图像、`22793` 个目标、平均每图 `8.6996` 个目标。
- 成熟度分布：
  - `未成熟`: `14397`
  - `半成熟`: `3566`
  - `完熟`: `4830`
- 遮挡分布：
  - `无`: `9727`
  - `轻度`: `9554`
  - `重度`: `3512`

这些数字可用于论文的 `Image Dataset Acquisition and Characteristics` 小节。

### 已完成实验

实验 A：官方一致版 grounding 格式，仅监督 `bbox_2d + label`。

- 模型：`Qwen3.5-35B-A3B`
- 验证集：`128` 张图像、`1111` 个参考目标。
- 结果：`precision=0.9145`、`recall=0.8857`、`f1=0.8999`、`avg_iou_on_matched=0.9074`。
- 解析失败：`3` 个样本。

实验 B：属性增强版，在 `bbox_2d + label` 基础上额外监督 `attribute_text`。

- 模型：`Qwen3.5-35B-A3B`
- 首轮结果：`precision=0.9341`、`recall=0.3699`、`f1=0.53`、`occlusion_accuracy_on_matched=0.7953`。
- 解析失败：`26` 个样本。
- 当前结论：首轮低召回主要受验证推理输出协议影响，不能直接判定属性增强路线失败。

### 已落地工程链路

- `CognitiveAnnotatorAgent`：云端 VLM 冷启动标注。
- `MultimodalReviewAgent`：规则审核、bbox 坐标转换、超小框过滤。
- `gold_builder`：从 Silver 独立构建 Gold。
- `export_swift_sft_dataset`：导出官方一致版和属性增强版训练数据。
- `run_validation_inference`：真实模型验证推理，支持 `vllm` 和 `transformers`。
- `evaluate_semantic_predictions` / `SemanticEvaluator`：逐图结构化评估。
- `visualize_validation_comparison`：GT / 实验 A / 实验 B 三联图对比。
- `VLMOperator`：已有训练计划、命令快照、产物目录和元数据输出能力。

## 与论文草稿的差距

论文草稿中有几项目前还不能直接声称已经完成：

1. `0.8B/2B` 边缘小模型训练和蒸馏尚未完成。
2. 漏标挖掘与伪标签回流目前只有评估基础，`evaluate_and_mine` 仍未实现。
3. Orchestrator 仍是状态机骨架，尚未真正串起版本推进和触发条件。
4. 半成熟语义规则仍停留在工程字段和属性文本层面，缺少独立的颜色统计一致性检查。
5. 消融实验尚未系统落地，包括去语义标注、去审核 Agent、去漏标挖掘、去蒸馏。
6. 跨作物泛化实验尚未开始。
7. 边缘资源指标尚未采集，包括参数量、显存、延迟、吞吐和部署约束。

## 建议论文结构与仓库对应关系

### 1 Introduction

对应仓库重点：

- 强调半成熟边界模糊、人工标签噪声和农业边缘部署成本。
- 用当前数据分层设计说明本文不是单一检测器，而是数据生产与模型压缩闭环。

### 2 Materials and Methods

对应仓库重点：

- 数据集：引用 Gold v1 的图像数、目标数、成熟度分布和遮挡分布。
- 多智能体架构：对应 `agents/` 与 `pipelines/`。
- 语义感知标注：对应 `maturity_ratio`、`occlusion_degree`、`reasoning`、`attribute_text`。
- 闭环蒸馏：当前只能写为方法设计和待完成实验，除非后续完成小模型训练。

### 3 Results

当前可先写：

- Gold v1 数据质量与分布。
- 实验 A 的有效检测基线。
- 实验 B 的首轮属性收益与验证协议问题。
- 三联图可视化作为错误案例分析材料。

后续需补：

- 修复协议后的实验 B 重跑结果。
- 0.8B/2B 或实际选定边缘模型结果。
- 与 YOLO 系列、RT-DETR 或其他农业检测基线的对照。
- 消融实验。

### 4 Discussion

建议讨论：

- 语义标注对半成熟边界的价值。
- 数据分层对可追溯性和迭代训练的价值。
- 中型 VLM 与边缘小模型之间的部署折中。
- 当前验证协议、伪标签质量和跨作物泛化的限制。

### 5 Conclusion

结论需要随着实验完成程度收敛。当前阶段可以准备叙事，但不能提前写成已经完成边缘蒸馏和跨作物泛化。

## 当前下一步

最优先事项不是继续扩写论文，也不是继续盲目训练新的属性增强模型，而是把论文中最关键的可验证实验补齐：

1. 将 A official、B full、B-lite、B old + `occlusion_only` 整理成同口径论文表格。
2. 基于同一批 risk cases 做半成熟、遮挡、密集场景、小目标和 bbox 偏移的错误案例归类。
3. 实现 `SemanticVerifier` 和 `ConsistencyChecker`，将语义信息从检测输出中解耦，转为后验验证、风险筛选和伪标签过滤。
4. 实现半成熟颜色比例一致性检查，为 `Semantic-Aware Annotation Strategy` 提供可复现实证。
5. 将 `SemanticEvaluator.evaluate_and_mine` 从预留接口推进到可运行漏标挖掘流程。
6. 基于语义过滤后的候选样本构建 Gold v2 candidate 或 Pseudo-Gold v1。
7. 训练 C closed-loop 版本，验证闭环数据回流是否提升番茄检测和成熟度判断。
8. 明确边缘模型型号，训练一个小模型版本并采集显存、延迟和吞吐指标。
9. 在核心结果稳定后，再设计去语义标注、去审核 Agent、去漏标挖掘和去蒸馏的消融实验。