docs/architecture.md

# Architecture

## Goal

本仓库的目标不是单一检测器，而是一套围绕“结构化数据资产”持续演进的多模态闭环系统。

论文侧目标暂定为 `AgriAgent: Semantic-Aware Multi-Agent Annotation Distillation for Edge-Oriented Tomato Maturity Detection`。因此架构需要同时服务两个层面：

- 工程层：持续生产、审核、训练、评估和回流结构化农业视觉数据。
- 论文层：证明语义感知标注、多智能体审核闭环和边缘蒸馏能缓解半成熟模糊边界与边缘部署成本。

当前主问题定义是：

- 输入是一张西红柿图像。
- 输出是单图多目标的结构化认知结果。
- 每个目标需要至少包含 bbox、成熟度、遮挡程度和 reasoning。
- 上游模型 bbox 统一按 `0-1000` 归一化相对坐标理解。

## Stable Contract

当前主链路必须遵循以下稳定契约：

- 任务是“单图多目标”，不是旧版“单图单目标”。
- 当前阶段不再保留 `disease_suspicion`。
- annotator 输出的 bbox 是 `bbox_1000` 语义。
- reviewer 负责把 `bbox_1000` 转换为像素 `bbox`。
- Silver 以“每目标一行”的形式长期沉淀。
- Gold 以“按图聚合”的形式从 Silver 派生。
- 数据审核与训练格式生成保持解耦。

## Data Layers

### Raw Data

由云端多模态模型直接返回的单图多目标结构化结果。

特点：

- 每张图返回一个 `annotations` 数组。
- 每个目标只保留主链路需要的结构字段。
- 不含训练框架专用对话格式。

### Silver Data

由 reviewer 对 Raw Data 执行业务校验后得到的目标级记录。

特点：

- 每个目标一行。
- 同时保留 `bbox_1000` 和像素 `bbox`。
- 增加 `is_valid`、`invalid_reason`。
- 当前 reviewer 还会过滤明显不稳定的超小框。

### Gold Data

由 `gold_builder` 按 `image_path` 聚合同图多目标 Silver 后生成的训练样本。

特点：

- 聚合发生在独立阶段。
- 当前 Gold 仍基于 `bbox_1000` 组织目标。
- 训练模板转换不回流污染 Silver。

### Eval Data

用于质量分析、人工复核组织与未来模型评估的数据层。

当前已落地的 Eval 能力：

- `manual_qc.py` 导出人工复核清单和预览图。
- `evaluate_silver_dataset.py` 输出统计摘要、重复框分析和风险预览。

## Core Agents

### CognitiveAnnotatorAgent

职责：

- 调用云端 Qwen 兼容接口。
- 对单图输出多目标结构化结果。
- 返回 `0-1000` 归一化 bbox。
- 落 raw snapshot 以便追溯。

不负责：

- 像素 bbox 转换。
- 业务审核。
- 训练格式生成。

### MultimodalReviewAgent

职责：

- 校验 `target_index`、bbox、成熟度与 reasoning。
- 将 `bbox_1000` 转换为像素 `bbox`。
- 追加 `is_valid`、`invalid_reason`。
- 过滤超小框噪声。

当前默认超小框规则：

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

### VLMOperator

职责：

- 管理本地中型模型和边缘模型训练流程。
- 统一训练命令、产物目录、日志和元数据。
- 为论文中的中型模型训练、边缘小模型蒸馏和资源对照实验提供执行入口。

当前状态：

- 已具备训练计划、命令构造、目录规划、命令快照和元数据输出能力。
- 正式 Megatron-SWIFT 训练脚本仍主要落在 `scripts/`。
- 训练闭环尚未由 `Orchestrator` 自动触发。

### SemanticEvaluator

职责：

- 用中型模型做评估、漏标挖掘与伪标签筛选。
- 支撑论文中的 detection、maturity、occlusion 和风险样本分析。

当前状态：

- 已落地 reference / prediction 逐图结构化评估。
- 已支持 `bbox_1000` 与像素 bbox 坐标空间。
- 已支持真实模型验证推理后的结果评估。
- `evaluate_and_mine` 漏标挖掘入口仍未实现。

### Orchestrator

职责：

- 管理版本、轮次、触发条件和闭环状态机。

当前状态：

- 仍处于 skeleton 阶段。
- 论文草稿中的完整闭环目前应表述为架构设计目标，不能写成已完成工程事实。

## Paper-Oriented Architecture Mapping

论文方法章节建议按以下模块描述，并映射到当前工程：

- Dataset acquisition：对应 `clearn_base_data/`、`silver_dataset.jsonl`、`runs/gold/gold_release_v1/`。
- Semantic-aware annotation：对应 `CognitiveAnnotatorAgent` 输出的 `maturity_level`、`maturity_ratio`、`occlusion_degree`、`reasoning`。
- Review and data stratification：对应 `MultimodalReviewAgent`、`clean_silver_dataset.py`、`gold_builder.py`。
- Medium VLM training：对应 `export_swift_sft_dataset.py` 与 `scripts/train_qwen3_5_35b_a3b_*.sh`。
- Semantic evaluation：对应 `run_validation_inference.py`、`evaluate_semantic_predictions.py`、`visualize_validation_comparison.py`。
- Edge distillation：当前仍是待实现模块，需要后续补小模型训练、蒸馏和资源指标采集。

## Current Operational Pipelines

### 1. Silver 主链路

入口：`run_pipeline_silver.py`

流程：

1. 遍历图像目录。
2. 调 annotator 获取单图多目标 raw 输出。
3. 调 reviewer 转换 bbox 并做规则校验。
4. 逐条写入 Silver JSONL。
5. 输出 `summary.json`、`progress.json`、失败日志。

当前工程特征：

- 已支持更稳定的 CLI 参数。
- 不再依赖硬编码 API key。
- 统一通过环境变量读取凭证。

### 2. Silver 清洗重建

入口：`pipelines/clean_silver_dataset.py`

用途：

- 不重新请求模型 API。
- 直接对既有 Silver 按最新 reviewer 规则重建。
- 适合在 reviewer 规则升级后快速发布 cleaned Silver。

### 3. Silver 评估

入口：`pipelines/evaluate_silver_dataset.py`

输出：

- `summary.json`
- `report.md`
- `high_iou_pairs.jsonl`
- `moderate_iou_pairs.jsonl`
- `preview_images/`

说明：

- 它是当前最推荐的结构化数据评估入口。
- 后续大模型或代理应优先调用它，而不是临时手写统计逻辑。

### 4. 人工复核

入口：`pipelines/manual_qc.py`

用途：

- 从 Silver 中按图抽样。
- 导出多目标框预览图。
- 支持检查 bbox grounding、target selection、成熟度和漏标/乱标。

### 5. Gold 构建

入口：`pipelines/gold_builder.py`

用途：

- 过滤有效 Silver 记录。
- 按图聚合多目标。
- 生成 Gold 样本。

## Current Engineering Snapshot

截至 2026-03-19，当前仓库状态可概括为：

- 新版多目标 Silver 主链路已完成全量运行。
- 原始全量 Silver 为 `23222` 条记录。
- reviewer 已加入超小框抑制规则。
- 已重建出 cleaned Silver，共 `22793` 条记录。
- 评估脚本、清洗脚本、Gold 构建脚本、人工复核脚本都具备可复用 CLI。
- 已补 `requirements.txt`、`.env.example`、`docs/deployment/deploy_linux.md`，仓库已基本具备 Linux 迁移条件。

## Source Of Truth

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

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`