Skip to content

documentation.md

Latest commit

 

History

History
394 lines (304 loc) · 17.5 KB

documentation.md

File metadata and controls

394 lines (304 loc) · 17.5 KB
Raw

农业多模态视觉数据集知识库

本文档是项目核心知识库，旨在为数据集的构建、使用和未来发展提供一个清晰、连贯且全面的指南。它整合了项目的所有历史记录、处理流程、设计规范和战略规划。请在执行后更新此文档。

目录

<a id="sec-1"></a>

1. 项目愿景与核心战略

本项目的核心目标是构建一个高质量、大规模、多模态的农业视觉知识库，而不仅仅是一个简单的图像分类数据集。所有的数据处理和标注工作都应服务于这一最终愿景。其核心战略原则包括：

  1. 统一的多模态标注范式:

    • 目标: 将每一张图片转化为包含丰富信息的“图像-文本对 + 标签”样本。
    • 实现: 为每张图片生成中英双语的图像描述 (Caption)和问答对 (VQA)。

  2. 建立统一的本体 (Ontology):

    • 所有数据源的“作物”、“病害”、“是否健康”等标签必须规范化，确保跨数据源的一致性。详细的中英文对照表见 附录 B。

  3. 数据质量优先:

    • 通过严格的去重、模糊检测和尺寸过滤，剔除低质量样本。
    • 色彩空间统一为 sRGB，训练分辨率建议不低于 448x448。

  4. 可追溯性与可复现性:

    • 所有数据处理步骤、脚本和参数都必须被记录。
    • 通过文件名中的来源标签，确保每一张图片都能追溯到其原始出处。

<a id="sec-2"></a>

2. 数据集架构与核心规范

所有贡献者和使用者都必须严格遵守以下架构和规范。

<a id="sec-2-1"></a>

2.1 目录结构

数据集目录结构：

datasets/
├── crops/      # 农作物图像
├── pests/      # 农业害虫图像
└── diseases/   # 植物病害图像

完整项目目录结构：

dataset_web/
├── datasets/                      # 标准化数据根目录
│   ├── crops/                     # 农作物图像
│   ├── pests/                     # 农业害虫图像
│   └── diseases/                  # 植物病害图像
├── scripts/                       # 数据处理脚本(分阶段组织)
│   ├── 00_utilities/              # 监控、启动、状态检查脚本
│   ├── 01_scraping/               # 网络爬虫相关脚本
│   ├── 02_ingest_and_merge/       # 数据导入与合并
│   ├── 03_cleaning/               # 数据清洗、去重、审核
│   ├── 04_llm_enhancement/        # LLM语义验证与增强
│   └── 05_index_and_stats/        # 索引生成与统计分析
├── llm_tools/                     # LLM验证与描述生成工具
├── web_scraper/                   # 爬虫项目与缓存
├── docs/                          # 文档目录
│   ├── documentation.md           # 核心知识库(本文件)
│   ├── timeline.md                # 时间线与里程碑
│   ├── pest_manual_review.html    # 人工审核界面
│   ├── archive/                   # 历史文档与备份
│   │   ├── reports/               # 历史报告归档
│   │   └── backups/               # 数据备份文件
│   ├── dev_notes/                 # 开发笔记与记忆库
│   └── technical/                 # 技术文档
├── stats_reports/                 # 统计报表输出目录
├── mappings/                      # 类别映射表(crop/disease/pest)
├── sources/                       # 原始数据来源清单
├── logs/                          # 任务与审计日志
├── paper/                         # 论文相关资料
├── web-bundles/                   # Web资源打包文件
├── data.jsonl                     # 全量多模态索引
├── data_holdout_web.jsonl         # 网爬保留集(验证用)
└── data.sample.jsonl              # 小样本示例

<a id="sec-2-2"></a>

2.2 文件命名规范

所有数据集中的文件必须遵循以下格式，文件名全部小写：

<类别名>__<来源标签>__<uuid>.<ext>

  • <类别名>: 文件所属的标准化类别名称（英文），例如 corn rust leaf。
  • <来源标签>: 两个下划线包围的来源标识符，用于数据溯源。常见标签包括 __cd__ (Crop Diseases), __pd__ (PlantDoc), __kd__ (Kaggle), __ac__ (Crops), __ap__ (Pests), __web__ (网络爬虫)。
  • <uuid>: 一个唯一的标识符，防止文件名冲突。
  • <ext>: 小写的文件扩展名，例如 jpg。

<a id="sec-2-3"></a>

2.3 数据标注范式 (JSONL 格式)

所有图像的元数据和文本标注都存储在统一的 data.jsonl 文件中。每一行代表一个样本，包含 image, task, text, answer, lang, split, 和 labels 等字段。其中 labels 对象包含了从目录和文件名中解析出的详细信息，如根目录、类名、具体实体、是否健康、来源等。

<a id="sec-3"></a>

3. 数据处理工作流 (Playbook)

这是一个从零开始处理和整合新数据源的标准化流程。

<a id="sec-3-1"></a>

3.1 合并新数据源

  • 策略: 始终采用“拷贝而非移动”的策略，将新数据拷贝到 datasets/ 目录中，以保留原始数据。
  • 脚本: 使用 scripts/02_ingest_and_merge/merge_*.py 系列脚本，并在脚本中定义好新旧类别名的映射关系。

<a id="sec-3-2"></a>

3.2 标准化文件名

  • 目的: 对新合入的、文件名不规范的数据进行统一重命名。
  • 脚本: scripts/03_cleaning/bulk_rename_by_class.py
  • 用法: python3 scripts/03_cleaning/bulk_rename_by_class.py --root <target_dir> --tag <source_tag>

<a id="sec-3-3"></a>

3.3 数据清洗

  • 目的: 移除低质量、重复或损坏的图像。
  • 脚本: scripts/03_cleaning/deduplicate_images.py
  • 核心功能:
    • 尺寸过滤: 剔除小于 min-width 和 min-height 的图像。
    • 模糊检测: 推荐使用 --blur-method both，结合拉普拉斯方差和 Tenengrad 梯度能量，减少误判。
    • 重复检测: 使用感知哈希 (pHash/aHash) 检测并剔除重复或高度相似的图像。
  • 安全操作: 强烈建议首次运行使用 --action move，将待删除文件移动到 .trash/ 文件夹中供人工复核。

<a id="sec-3-4"></a>

3.4 人工核验（网页）（已弃用，可以后续做数据验证）

  • 目的: 在并入主数据集前进行人工快速抽查/核验，剔除无关或版权不明的图片。
  • 工具: docs/pest_manual_review.html (前端) + scripts/03_cleaning/pest_review_server.py (后端)。
  • 流程:
    1. 使用 scripts/03_cleaning/generate_pest_review_manifest.py 生成待审核图片清单。
    2. 启动 pest_review_server.py 后端服务，它会加载 VLM 模型进行智能分析。
    3. 在浏览器中打开 pest_manual_review.html，进行批量审核、分析和标记。
    4. 审核完成后，导出审核结果 JSON 文件。
    5. 使用 scripts/02_ingest_and_merge/import_reviewed_pests.py 或 scripts/02_ingest_and_merge/import_llm_verified_scraped.py 将通过审核的图片正式导入 datasets/ 目录。

<a id="sec-3-5"></a>

3.5 LLM 语义验证与描述增强（已经用llm替代人工核验）

  • 目的: 利用多模态大模型（VLM）对图像进行最后一次智能审核，确保内容与标签匹配，并生成更丰富的描述。

  • 脚本: llm_tools/verify_and_describe.py

  • 核心功能:

    • 并发处理: 利用多线程并发调用 VLM API，大幅提升处理速度。
    • 语义验证与质量过滤: 自动隔离内容不符或质量低下的图片。
    • 描述增强: 为通过验证的图片生成中英双语描述，并存为 .json 元数据文件。
    • 智能分类: 将验证失败的图片根据模型判断的 actual_class 归类到 .rejected_by_llm/ 目录，为数据挽救提供可能。

<a id="sec-3-6"></a>

3.6 生成数据索引 (JSONL)

  • 目的: 为清洗干净的数据集生成包含多模态标注的 data.jsonl 索引文件。
  • 脚本: scripts/05_index_and_stats/build_jsonl.py
  • 核心功能:
    • 扫描 datasets/ 下的所有图像及其 .json 元数据。
    • 根据文件名和本体，自动生成中英双语的 Caption 和 VQA 样本。
    • 若存在 LLM 生成的 .json 文件，则优先使用其中更高质量的文本描述。
    • 按类别进行分层抽样，划分 train, val, test 集。
    • 支持 --holdout-source <src> 仅导出指定来源样本（如 web），用于跨来源测试集构建，并且已经生成了一个data_holdout_web.jsonl。

<a id="sec-3-7"></a>

3.7 数据采集策略

  • 目的: 为缺失或数据量不足的类别补充高质量图片。
  • 主力数据源: GBIF / iNaturalist。通过 agri_sites 爬虫 (web_scraper/scraper/spiders/agriculture_sites_spider.py) 访问，是专业生物学数据库，图片质量高且有科学分类，特别适合害虫、植物病害等专业类别。
  • 补充数据源: Unsplash API。通过 unsplash_api 爬虫 (web_scraper/scraper/spiders/unsplash_api_spider.py) 访问，图片艺术质量高，适合通用农业场景，但有速率限制 (50次/小时)。
  • 备选方案: Pixabay API 和 Pexels API。两者均为免费、高质量的图片库，API 限制宽松，是未来可考虑的优秀补充数据源。

<a id="sec-4"></a>

4. 模型训练与评测路线图（仅建议）

  • 视觉编码器选型: 推荐 CLIP/SigLIP ViT-L/14, EVA-02, CoCa 等。输入分辨率建议 ≥ 448x448。
  • 多模态架构选型: 推荐 LLaVA, InternVL, Qwen-VL, InstructBLIP 等。
  • 训练策略: 建议采用三阶段训练范式：1) 视觉-文本对齐预训练 (Caption) → 2) 指令微调 (VQA) → 3) 下游任务微调。
  • 评测指标: 分类任务 (Top-1/Top-5 准确率)、VQA 任务 (EM/F1 分数)，并进行混淆矩阵、跨域泛化和失效分析。

<a id="sec-5"></a>

5. 未来规划与待办事项 (TODOs)

数据集优化建议 📊

已完成任务 ✅

  • ✅ 跨来源测试集 (web holdout, 2025-11-06): 生成 data_holdout_web.jsonl，仅含 web 来源样本（约 133,133 条），用于跨来源泛化评估。
  • ✅ 统计报告生成 (2025-11-06): 实现 scripts/05_index_and_stats/generate_stats.py，生成4个CSV报告：
    • counts_by_class.csv (465个类别统计)
    • counts_by_source.csv (9个来源统计)
    • counts_by_split.csv (train/val/test划分统计)
    • class_source_pivot.csv (类别×来源交叉透视表)
    • 数据集总览: 160,643张唯一图片，990,256条JSONL记录（平均每张图片6.2个标注）

待完成任务！

首要优先

** 高价值补全**

  • 数据质量审计工具
    • 目标：提升数据一致性与可训练性。
    • 文档出处：docs/documentation.md:240
    • 建议实现三个无损/可回滚的工具（先 dry-run 模式）：
      • EXIF 方向修正：遍历图片，应用 ImageOps.exif_transpose，仅在需要时写回；输出审计日志。
      • sRGB 统一：将非 sRGB 转换（保留副本到 .normalized/ 或原地写回需确认）。
      • **命名规范校验器：检查小写、**source 标记、合法扩展名、UUID 形态；输出违规清单 CSV。
    • 注意：图像就地改写属潜在高风险操作，执行前需确认路径与回滚策略。

** 模型与发布准备**

  • 模型训练准备
    • 动作建议：
      • 基线实验配置（LLaVA/InternVL/Qwen-VL）模板与数据加载脚本。
      • 训练/评估分布复核（与 stats 报告联动）。
  • 发布资料
    • 目标：面向公开或内部复用
    • 动作建议：完善 README/许可证/统计报告/数据卡（Data Card），补全 docs/documentation.md 的执行痕迹。

模型训练准备 🚀

数据集已就绪,可直接用于:

  1. 基线模型训练 (LLaVA/InternVL/Qwen-VL)
  2. 多模态预训练实验
  3. Caption生成任务 (99.8% LLM高质量描述)
  4. 视觉问答任务 (VQA)
  5. 数据集公开发布准备 (README, LICENSE, 统计报告)

<a id="data-sources"></a>

数据来源与合并历史（概览）

  1. Agricultural-crops: Kaggle Link
  2. agricultural-pests-image-dataset: Kaggle Link
  3. Agriculture crop images: Kaggle Link
  4. PlantDoc-Dataset: GitHub Link
  5. Agriculture Crops Dataset: Kaggle Link
  6. Top Agriculture Crop Disease: Kaggle Link
  7. 140-most-popular-crops-image-dataset: Kaggle Link
  8. PlantVillage Dataset: Kaggle Link (License: CC BY-NC-SA 4.0)
  9. New Plant Diseases / Plant Pathology: Kaggle 数据与竞赛数据集汇总。

时间线与关键处理日志已迁移至精简文档：docs/timeline.md。此处仅保留数据源概览以避免文档膨胀。

<a id="app-b"></a>

附录 B：中英文类目总表 (Ontology)

这是项目的核心本体，定义了所有目录和类别的中英文标准名称。

  • 根目录:

    • datasets/crops: 农作物 (Crops)
    • datasets/pests: 害虫 (Pests)
    • datasets/diseases: 病害 (Diseases)

  • Diseases 目录:

    • Apple Scab Leaf: 苹果黑星病
    • Apple leaf: 苹果叶
    • Apple rust leaf: 苹果锈病叶
    • Bell_pepper leaf: 甜椒叶
    • Bell_pepper leaf spot: 甜椒叶斑病
    • Blueberry leaf: 蓝莓叶
    • Cherry leaf: 樱桃叶
    • Corn Gray leaf spot: 玉米灰斑病
    • Corn leaf: 玉米叶
    • Corn leaf blight: 玉米叶枯病
    • Corn rust leaf: 玉米锈病叶
    • Peach leaf: 桃叶
    • Potato leaf: 马铃薯叶
    • Potato leaf early blight: 马铃薯早疫病
    • Potato leaf late blight: 马铃薯晚疫病
    • Raspberry leaf: 覆盆子叶
    • Rice brown spot: 稻褐斑病
    • Rice leaf: 稻叶
    • Rice leaf blast: 稻叶稻瘟病
    • Rice neck blast: 稻穗颈稻瘟病
    • Soyabean leaf: 大豆叶
    • Squash Powdery mildew leaf: 南瓜白粉病叶
    • Strawberry leaf: 草莓叶
    • Sugarcane bacterial blight: 甘蔗细菌性叶枯病
    • Sugarcane leaf: 甘蔗叶
    • Sugarcane red rot: 甘蔗红腐病
    • Tomato Early blight leaf: 番茄早疫病叶
    • Tomato Septoria leaf spot: 番茄叶斑病（Septoria）
    • Tomato leaf: 番茄叶
    • Tomato leaf bacterial spot: 番茄细菌性斑点病
    • Tomato leaf late blight: 番茄晚疫病叶
    • Tomato leaf mosaic virus: 番茄花叶病毒
    • Tomato leaf yellow virus: 番茄黄化病毒叶
    • Tomato mold leaf: 番茄霉病叶
    • Tomato two spotted spider mites leaf: 番茄二斑叶螨危害叶
    • Wheat brown rust: 小麦褐锈病
    • Wheat leaf: 小麦叶
    • Wheat yellow rust: 小麦黄锈病
    • grape leaf: 葡萄叶
    • grape leaf black rot: 葡萄黑腐病

  • Crops 目录:

    • Cherry: 樱桃
    • Coffee-plant: 咖啡树
    • Cucumber: 黄瓜
    • Fox_nut(Makhana): 芡实（鸡头米）
    • Lemon: 柠檬
    • Olive-tree: 橄榄树
    • Pearl_millet(bajra): 珍珠粟（Bajra）
    • Tobacco-plant: 烟草
    • almond: 杏仁（扁桃）
    • banana: 香蕉
    • cardamom: 小豆蔻
    • chilli: 辣椒
    • clove: 丁香
    • coconut: 椰子
    • cotton: 棉花
    • gram: 鹰嘴豆（Gram）
    • jowar: 高粱（Jowar）
    • jute: 黄麻
    • maize: 玉米
    • mustard-oil: 芥籽（油用）
    • papaya: 木瓜
    • pineapple: 菠萝
    • rice: 稻（大米）
    • soyabean: 大豆（脚本同时识别 soybean 变体）
    • sugarcane: 甘蔗
    • sunflower: 向日葵
    • tea: 茶树
    • tomato: 番茄
    • vigna-radiati(Mung): 绿豆（豇豆属）
    • wheat: 小麦

  • Pests 目录:

    • ants: 蚂蚁
    • bees: 蜜蜂
    • beetle: 甲虫
    • caterpillar: 毛虫（鳞翅目幼虫）
    • earthworms: 蚯蚓
    • earwig: 蠼螋
    • grasshopper: 蝗虫
    • moth: 蛾
    • slug: 鼻涕虫
    • snail: 蜗牛
    • wasp: 黄蜂
    • weevil: 象鼻虫