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、去漏标挖掘和去蒸馏的消融实验。