研究提案

[WIP] 代码-图表三元对齐：技术图表理解的多模态训练数据构建

提出一种基于 GitHub 开源仓库的多模态训练数据构建方案，通过爬取 README 中的技术图表并与对应代码对齐，形成「代码描述↔图像↔图表文字」三元组，以填补现有多模态数据集在技术图表理解上的缺口。

多模态 训练数据 代码理解 技术图表 数据构建

[WIP] 代码-图表三元对齐：技术图表理解的多模态训练数据构建

1. 动机：多模态模型的技术图表盲区

当前主流多模态大模型（如 GPT-4V、LLaVA、InternVL）在自然图像理解上表现出色，但面对技术图表时往往力不从心。所谓”技术图表”，指软件工程中常见的架构图、数据流图、类图、时序图、状态机图等——这类图表的理解高度依赖领域知识与符号语义，而非视觉感知能力本身。

具体表现为：

  • 节点与边的语义混淆：模型往往只能描述”有几个方框、几条箭头”，无法理解箭头方向代表的调用关系或数据流向。
  • 图例与标签忽视：图中关键标注（如服务名、接口名、延迟标注）常被忽略或误读。
  • 结构关系推理缺失：无法回答”哪个组件是单点故障”或”A 调用 B 还是 B 调用 A”这类结构性问题。

根源在于训练数据的分布性缺失。现有大规模多模态预训练数据集（CC3M、LAION-400M、WIT）的图文对几乎全部来自网页爬取，天然偏向照片、插图、海报等自然图像，而技术图表在其中占比极低，且即便存在，对应的 alt-text 或 caption 也是泛化描述（如”a system architecture diagram”），缺乏结构化技术语义。

这一缺口导致：即便模型规模增大，技术图表理解能力也难以通过自然涌现弥补，必须从数据层面系统性解决。

2. 与现有方法的对比

2.1 通用多模态数据集的局限

数据集规模图像类型Caption 质量
CC3M3.3M自然图像为主网页 alt-text，泛化
LAION-400M400M自然图像为主噪声大，无技术内容
WIT11.5MWikipedia 图片百科描述，极少技术图表
DataComp1B+网页爬取混合过滤后仍缺技术深度

这些数据集的共同问题不在规模，而在语义层次：caption 描述的是图像的表层视觉特征，而非图表背后的系统语义。一个微服务架构图，在 LAION 里的 caption 可能只是”a diagram showing microservices”，无法告诉模型”API Gateway 在最前面，后面是三个无状态服务，共享一个 Redis 缓存”。

2.2 代码相关多模态工作的局限

近年来出现了一些专注于代码或图表理解的多模态工作：

  • ChartQA / FigureQA：专注于折线图、柱状图等统计图表，属于”数据可视化”而非”系统设计图”，语义完全不同。
  • CodeVQA：将代码截图与问题配对，但图像是代码文本截图，本质上是 OCR 任务，不涉及图表结构理解。
  • SciGraphQA：针对学术论文中的图表，以实验结果图为主，技术架构图极少。
  • MMCode：以代码生成为目标，图像侧是题目截图，同样是文本图像而非结构图表。

这些工作或聚焦于统计图表、或以代码文本截图为主，均未触及软件工程架构图理解这一核心场景。更重要的是，它们缺少一个关键维度：与实际代码实现的对齐。

2.3 本方案的差异化定位

本方案的核心创新在于三元对齐：

代码描述（Code Description）
        ↕
    图像（Diagram Image）
        ↕
图表文字说明（Diagram Caption / In-figure Text）

三者共同构成一个互相印证、语义一致的训练样本。现有工作最多做到图像与 caption 的二元对，本方案增加了”实际代码”这一锚点，使得图表语义有了可核实的技术来源，而不是依赖人工标注或 LLM 凭空生成。

3. 具体方案

3.1 数据来源

目标：GitHub 上同时满足以下条件的开源仓库：

  • README.md 中包含至少一张技术图表（架构图/流程图/类图/时序图）
  • 图表来源是项目自身的设计，非外部引用
  • 仓库有实质性代码（非文档站、非 awesome-list）

这类仓库数量庞大。仅在 GitHub 上，含图片的 README 仓库估计超过 2000 万个，其中架构类图表的比例保守估计在 5-10%，即约 100-200 万个候选仓库。

3.2 采集 Pipeline

Step 1：仓库筛选

利用 GitHub REST API / GraphQL API 批量筛选：

  • Star 数 ≥ 50（过滤废弃项目）
  • 仓库含 README.md 且 README 长度 > 500 字符
  • README 中含 <img> 标签或 Markdown 图片语法 ![...](...)
  • 主语言为代码类语言（Python/Java/Go/TypeScript 等，排除纯文档仓库）
  • 排除 fork 仓库（避免重复）

Step 2：图表类型识别

下载 README 中的图片后，使用分类模型（可基于 CLIP fine-tune）判断图表类型：

  • 架构图（有节点+箭头+标签）
  • 流程图（有菱形判断框）
  • 类图/ER 图（有属性列表）
  • 时序图（有时间轴/泳道）
  • 非目标图（截图、logo、badge 等）

过滤掉非目标类型图像，对目标图表进行后续处理。

Step 3：OCR + LLM 解析图表文字

  • 使用 PaddleOCR 或 Tesseract 提取图中所有文字（节点名、边标签、图例等）
  • 将 OCR 结果与图像一起输入多模态 LLM（如 GPT-4V 或 InternVL），生成结构化描述：
    • 组件列表
    • 连接关系（有向/无向）
    • 推测的系统层次（前端/后端/存储/外部依赖）

Step 4：代码-图表对齐

这是 pipeline 中最难的一步。策略：

  1. README 上下文锚定：图表在 README 中的前后文本通常描述了它对应哪个模块，先提取图片周围 ±200 token 的文字作为候选上下文。
  2. 文件路径匹配：OCR 提取的组件名与仓库文件树做模糊匹配（如图中出现”UserService” → 搜索 **/user*service* 文件）。
  3. 代码摘要生成：对匹配到的代码文件，使用 LLM 生成结构化摘要（类名、函数签名、依赖关系），与图表描述做语义相似度计算（embedding cosine similarity）。
  4. 置信度过滤：对齐得分低于阈值的样本标记为低质量，不进入训练集主集（保留用于研究）。

3.3 三元数据结构

每条训练样本存储为如下 JSON 格式：

{
  "id": "gh-torvalds-linux-readme-img-003",
  "source": {
    "repo": "github.com/netdata/netdata",
    "readme_path": "README.md",
    "image_url": "https://raw.githubusercontent.com/netdata/netdata/master/docs/img/architecture.svg",
    "commit_sha": "a3f2b1c"
  },
  "diagram": {
    "type": "architecture",
    "image_local_path": "images/gh-netdata-arch-003.png",
    "ocr_texts": ["Agent", "Cloud", "Dashboard", "Metrics DB", "Alert Manager"],
    "structured_description": "Netdata 采集架构：本地 Agent 负责指标采集并上报至 Cloud，Cloud 聚合后推送 Dashboard 展示，告警由 Alert Manager 独立处理。",
    "in_figure_caption": "Netdata Architecture Overview"
  },
  "code": {
    "aligned_files": [
      "src/collectors/README.md",
      "src/database/engine/README.md",
      "src/health/README.md"
    ],
    "code_summary": "Agent 模块实现在 src/collectors，使用插件机制支持多数据源；存储引擎在 src/database/engine，基于 TSDB；告警逻辑在 src/health，支持自定义规则。",
    "alignment_score": 0.87
  },
  "readme_context": {
    "surrounding_text": "Netdata is a distributed, real-time performance and health monitoring platform. The following diagram shows how the components interact:",
    "section_heading": "## Architecture"
  },
  "metadata": {
    "language": "C",
    "stars": 68000,
    "diagram_complexity": "high",
    "quality_tier": "A"
  }
}

3.4 数据规模估算

阶段候选量通过率预计保留
GitHub 含图仓库~20M-20M
图表类型过滤20M~8%1.6M 图
OCR 质量过滤1.6M~60%~960K
代码对齐（score>0.7）960K~40%~380K
人工抽查后最终380K~85%~320K 三元组

320K 高质量三元组在规模上虽不及 LAION，但在技术图表领域已是目前最大的人工标注替代数据集，且每条样本包含代码锚点，语义深度远超现有数据集。

3.5 质量验证

  • 自动评估：随机抽样 1% 样本，用 GPT-4V 判断三元组的一致性（图-描述对是否准确）
  • 人工评估：每种图表类型各抽 200 条，由具备工程背景的标注员评分
  • 下游任务验证：用该数据集 fine-tune 一个基础多模态模型，在 ChartQA 和自建技术图表 QA 测试集上验证提升幅度

4. 客观评价

4.1 真正有价值的地方

这个方案最实质的贡献在于提供了技术图表语义的代码锚点——这是人工标注几乎无法规模化实现的。图表和代码同时存在于开源仓库，天然形成弱监督信号，不需要雇佣领域专家逐条标注。这种”在野数据”（in-the-wild data）的构建思路，比合成数据更接近真实分布，训练出的模型泛化性更强。

此外，三元结构本身就是一种新的监督信号形式，可以支撑多种训练目标：图文对齐（对比学习）、图表 QA（指令微调）、代码-图表相互生成（条件生成）。

4.2 主要挑战和可能失败的地方

代码-图表对齐是瓶颈。大量仓库的架构图与代码之间没有明确的文字桥接，自动对齐的噪声可能远高于预期。一个常见情况是：图表描述的是系统的”理想设计”，而代码实现已经偏离；或者图表是跨仓库的集成架构，本仓库只是其中一个组件。

图表类型分布不均。架构图容易找，时序图和类图在 README 里出现频率低得多，导致数据集分布偏斜，可能对特定类型图表过拟合。

OCR 在矢量图/SVG 上效果不稳定。GitHub README 中大量图表是 SVG 格式，直接 OCR 可能失效，需要额外的 SVG 解析路径，工程复杂度倍增。

规模估算过于乐观。实际代码对齐得分能超过 0.7 的比例可能远低于 40%，最终高质量样本可能只有 50K-100K，规模优势消失。

版权风险。GitHub 仓库的 README 图片存在多种授权协议，商用时需要逐一核查，这在大规模数据集构建中是严重的法律障碍。

4.3 适合与不适合的场景

适合：

  • 有较强工程能力（爬虫、OCR、NLP pipeline）的研究团队
  • 目标是改善代码助手的图表理解能力（如 GitHub Copilot 类产品）
  • 愿意接受 50-100K 规模、高质量样本作为 fine-tune 数据的场景
  • 学术研究，尤其是”软件工程 + 多模态”交叉方向

不适合：

  • 期望短期内拿到 1M+ 干净数据的工程项目（timeline 不现实）
  • 需要商业闭源部署的团队（版权问题未解决前风险高）
  • 对图表类型覆盖度要求全面均衡的产品场景（分布偏斜难以快速解决）
  • 没有工程资源维护爬取和对齐 pipeline 的小团队

小结

这个方案瞄准的是一个真实存在、且目前确实没有好解法的数据缺口。核心思路——用开源代码仓库作为技术图表的免费标注来源——在方向上是正确的。但落地路径上，代码-图表自动对齐的噪声控制和规模预期管理，将是决定这个方案成败的关键变量。如果能在小规模（1万样本）上验证对齐质量，再决定是否全量推进，会是更稳健的执行策略。