Hugging Face's logo

zhou777
/
agent-l

TensorBoard
Safetensors
Model card Files
xet
 Metrics Community
agent-l / docs /reference /repo_map.md
zhou777's picture
zhou777
Add files using upload-large-folder tool
0525670 verified
preview code
|
Raw
History Blame Contribute Delete
10.2 kB

Repo Map

这个文档用于帮助后续代理快速识别仓库中的关键目录、关键脚本和推荐调用入口。

最高优先级上下文

新会话开始时优先阅读：

  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

论文对齐文档

  • docs/paper_alignment.md 记录 AgriAgent 论文构想、当前仓库可支撑的材料、尚未完成的实验，以及下一步最应该补齐的证据链。后续写论文或设计实验时应优先查看。

截至 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/
  • 实验 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/
  • 实验 A/B 三联对比图目录：runs/validation_compare/exp_a_vs_b_20260331_201545/
  • 当前验证推理入口：pipelines/run_validation_inference.py，默认支持 vllm 与 transformers 双后端，且已修复 assistant 输出模板丢失问题
  • 当前可视化入口：pipelines/visualize_validation_comparison.py
  • 当前重要回归测试：tests/test_semantic_evaluator.py，已覆盖字符串 bbox + think 包裹输出，以及 assistant 模板转显式 JSON 约束

顶层目录说明

agents/

放置核心智能体实现。

关键文件：

  • agents/cognitive_annotator.py 云端多模态标注智能体。输入图像，输出单图多目标结构化结果。
  • agents/multimodal_reviewer.py 审核智能体。负责 bbox 坐标转换、业务校验、超小框过滤。
  • agents/vlm_operator.py 训练操作器骨架；训练命令模板已先落在 scripts/，后续应回填这里。
  • agents/semantic_evaluator.py 语义评估器；当前已支持结构化 prediction vs reference 对比。
  • agents/orchestrator.py 闭环编排器骨架。

schemas/

放置当前数据契约定义。

关键文件：

  • schemas/annotation.py Raw annotation 相关 TypedDict。
  • schemas/review.py Silver record 相关 TypedDict。
  • schemas/dataset_record.py Gold 和训练样本相关 TypedDict。

说明：

  • 当前所有实现都应优先遵守这里的最新数据契约。

pipelines/

放置当前最重要的可执行数据流程脚本。

关键文件：

  • pipelines/gold_builder.py 从 Silver 聚合生成 Gold，并输出发布摘要与抽样检查。
  • pipelines/check_gold_regression.py 对比两版 Gold 发布摘要，输出回归检查结论。
  • pipelines/manual_qc.py 对 Silver 做按图抽样人工复核。
  • pipelines/evaluate_silver_dataset.py 对 Silver 做结构化评估和风险样本导出。
  • pipelines/clean_silver_dataset.py 对既有 Silver 做规则清洗和重建。
  • pipelines/evaluate_semantic_predictions.py 对结构化预测结果做逐图语义评估。
  • pipelines/export_swift_sft_dataset.py 将 Gold 导出为 Swift / Megatron-SWIFT grounding 训练数据，支持 official 和 attr_enhanced 两种实验模式。
  • pipelines/run_validation_inference.py 对 Swift val.jsonl 运行真实模型验证推理，当前已支持把 assistant 模板转成显式输出约束。
  • pipelines/visualize_validation_comparison.py 生成 GT / 实验 A / 实验 B 的三联对比图，便于肉眼排查空框、漏检和属性差异。

runs/

放置所有运行快照和产物。

当前重要子目录：

  • runs/silver/ Silver 主链路运行快照和数据集输出。
  • runs/evaluation/ Silver 评估摘要、报告和风险预览图。
  • runs/silver_cleaning/ Silver 清洗摘要和被丢弃记录。
  • runs/manual_qc/ 人工复核清单和预览图。
  • runs/gold/ 正式 Gold 发布目录。
  • runs/gold_regression/ Gold 回归检查报告。
  • runs/swift_data/ 训练数据导出结果，包括实验 A / B 两套 grounding 数据。

tests/

放置当前最小测试。

关键文件：

  • tests/test_reviewer.py reviewer 的 bbox 换算和超小框过滤测试。
  • tests/test_gold_builder.py Gold 聚合行为测试。
  • tests/test_gold_regression.py Gold 回归检查测试。
  • tests/test_semantic_evaluator.py 结构化语义评估测试。
  • tests/test_swift_sft_export.py Swift / Megatron-SWIFT 训练数据导出测试。

docs/

放置项目说明和协作文档。

关键文件：

  • docs/architecture.md
  • docs/roadmap.md
  • docs/current_status.md
  • docs/paper_alignment.md
  • docs/reference/repo_map.md
  • docs/deployment/deploy_linux.md

当前最重要的数据资产

原始全量新版 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

当前正式 Gold 基线

  • runs/gold/gold_release_v1/gold_dataset.jsonl

当前 Qwen3.5 训练数据

  • runs/swift_data/qwen3_5_35b_a3b_exp_a_official_v2/
  • runs/swift_data/qwen3_5_35b_a3b_exp_b_attr_v2/

当前训练脚本

  • scripts/train_qwen3_5_35b_a3b_exp_a_official.sh
  • scripts/train_qwen3_5_35b_a3b_exp_b_attr.sh

推荐调用入口

1. Silver 主链路 

python run_pipeline_silver.py --process-limit 10

常用环境变量：

  • QWEN_API_KEY
  • QWEN_BASE_URL
  • QWEN_MODEL
  • PROCESS_LIMIT
  • MIN_BBOX_1000_SIDE
  • MIN_BBOX_1000_AREA

2. 评估 Silver 数据集 

python -m pipelines.evaluate_silver_dataset \
  --silver-dataset-path <silver_jsonl_path> \
  --risk-sample-size 12

建议用途：

  • 新 Silver 重跑后第一时间做结构测评。
  • 导出高风险图做人工复核。
  • 对比原始 Silver 和 cleaned Silver 的质量变化。

3. 清洗既有 Silver 数据集 

python -m pipelines.clean_silver_dataset \
  --input <source_silver_jsonl> \
  --output <target_silver_jsonl> \
  --min-bbox-1000-side 20 \
  --min-bbox-1000-area 400

建议用途：

  • reviewer 规则升级后快速重建 Silver。
  • 不重新请求模型 API 的情况下发布 cleaned Silver 新版本。

4. 人工复核 

python -m pipelines.manual_qc \
  --silver-dataset-path <silver_jsonl_path> \
  --sample-size 12

建议用途：

  • 对小样本或高风险图做人工复核。
  • 重点检查 bbox grounding、target selection、成熟度与漏标/乱标。

5. Gold 构建 

python -m pipelines.gold_builder \
  --silver-dataset-path <silver_jsonl_path> \
  --output-dir runs/gold/gold_release_v1

建议用途：

  • 在 cleaned Silver 稳定后生成正式 Gold。
  • 统一产出 gold_dataset.jsonl、summary.json、report.md、sample_check.jsonl。
  • 保持训练格式生成逻辑不回流污染 Silver 阶段。

6. Gold 回归检查 

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

建议用途：

  • 发布新 Gold 前后对比图像数、目标数和分布漂移。
  • 检查路径重写和质量检查布尔项是否退化。
  • 生成 summary.json 和 report.md 作为版本说明附件。

7. Semantic Evaluator 

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

建议用途：

  • 比较模型结构化预测结果与 Gold 基线的差异。
  • 输出逐图结果、风险样本和整体摘要。
  • 为后续漏标挖掘与伪标签筛选提供基础评估层。

8. 导出 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_v1 \
  --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_v1 \
  --export-mode attr_enhanced

建议用途：

  • 将正式 Gold 转成 Swift / Megatron-SWIFT grounding 训练输入。
  • 保持训练格式转换与 Gold 发布逻辑解耦。
  • 对比官方一致版和属性增强版的训练收益。

9. 启动 Qwen3.5-35B-A3B 训练 

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

建议用途：

  • 当前优先跟踪实验 A 的正式训练，并统一查看 runs/logs/ 中的日志。
  • 实验 A 跑通后，再做实验 B 对照。
  • 训练相关命令、依赖安装与版本检查统一在 lsy-agent 中执行。
  • 正式训练默认使用 --attention_backend unfused。

后续代理必须遵守的事实

  • 当前任务是单图多目标，不是单图单目标。
  • 当前主链路不再包含病害字段。
  • bbox 在模型侧统一按 0-1000 相对坐标理解。
  • Silver 是每目标一行，Gold 是按图聚合。
  • 当前更推荐使用 cleaned Silver 作为后续构建和复核输入。
  • 评估与清洗都已有可直接调用的脚本，不需要重复手写临时分析逻辑。
  • 正式 Gold 基线已经是 runs/gold/gold_release_v1/，不是待完成事项。
  • 当前 Qwen3.5-35B-A3B 训练数据和训练脚本都已准备完成。
  • 训练环境 lsy-agent 已验收通过，实验 A 正式训练已进入 step 级训练循环。
  • Linux 迁移前后的标准运行说明见 docs/deployment/deploy_linux.md。