zhou777/agent-l

# 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 上首次部署

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

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

2. Silver 小样本试跑

python run_pipeline_silver.py --process-limit 10

3. 评估 cleaned Silver

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

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，检查回归

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

6. 评估结构化预测结果

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 训练数据

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

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/，便于后续排查与复盘。

conda activate lsy-agent
bash scripts/train_qwen3_5_35b_a3b_exp_a_official.sh

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