研究提案

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

提出一种基于 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 万个候选仓库。

🔄 [v2 改进]

可行性估算修正（第一性原理推导）

原方案估计「有技术图表的高质量仓库约 10 万+」，「最终约 320K 三元组」，这两个数字缺乏依据，且严重乐观。以下通过逐层采样推导修正估算：

漏斗推导（基于 GitHub 公开数据）：

  • GitHub 上 star > 500 的 Python/JS 仓库：约 50,000 个（可通过 GitHub API 验证）
  • 其中 README 含图片（任意图片）的比例：约 40% = 20,000 个
  • 其中含「技术图表」（非截图、非 badge、非 logo）的比例：约 10% = 2,000 个
    • 这个比例来自实际采样：大多数仓库的 README 图片是徽章（build passing、npm version 等）或产品截图
    • 真正的架构图、数据流图、类图在 README 中出现频率较低，即使在高质量仓库中
  • 图表能精确对应到代码模块/函数的比例：约 20% = 400 个
    • 大多数架构图描述的是「系统整体」而非「某个模块」，精确对齐极难
    • 能做到文件级对齐的，已经是最乐观估算

修正后的规模估算：

  • 核心高质量三元组（精确对齐）：约 400-2,000 个（而非原方案的 320K）
  • 宽松对齐（文件级，不要求精确）：约 5,000-20,000 个

结论：规模重新定位

按原方案的「320K 三元组」目标构建训练数据集，当前技术能力下不可行。

核心高质量三元组约 400-2,000 个的规模，不足以构成独立的训练数据集，但足以构成：

  1. 一个高质量的评测集（evaluation benchmark）
  2. 一个 few-shot 示例库
  3. 与其他多模态数据（如 SciGraphQA）合并后的补充数据

建议：将本方案的定位从「大规模训练数据」调整为「精品评测集 + 种子数据」（见 3.6 节）

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. 置信度过滤：对齐得分低于阈值的样本标记为低质量，不进入训练集主集（保留用于研究）。

🔄 [v2 改进]

代码-图表对齐的粒度策略（明确化）

原方案中「代码-图表对齐」的粒度目标模糊——既提到文件路径匹配，又提到函数级匹配，但两者的难度和准确率差异巨大。以下明确对齐粒度策略：

对齐粒度的选择：

粒度可行性准确率估算建议
文件级对齐✅ 可行60-70%优先执行
模块级对齐⚠️ 困难30-40%仅在文件级成功后尝试
函数级对齐❌ 极难<10%放弃

为什么放弃函数级对齐：

  • 架构图中的「组件」通常对应一个服务或模块，而不是一个函数
  • 函数级对齐需要理解「图中的哪个方框对应哪个函数」，这本身就需要专家判断
  • 即使用 LLM 辅助，函数级对齐的噪声会导致训练数据引入错误的语义关联，反而有害

只做文件级对齐的具体操作：

  1. 从 OCR 结果提取组件名（如 UserService、Redis Cache、API Gateway）
  2. 在仓库文件树中匹配对应的目录或文件（src/user/、src/cache/）
  3. 将该目录下的 README 和主要代码文件摘要作为「代码描述」
  4. 对齐粒度声明为「图表-目录级」，不要求函数级精确性

人工验证（必须）：

  • 每条三元组必须经过具备工程背景的标注员确认对齐质量
  • 验证问题：「这张图描述的系统，确实对应到这个代码目录吗？」
  • 评分标准：完全对应（3分）/ 部分对应（2分）/ 不对应（1分，丢弃）
  • 仅保留评分 ≥ 2 的三元组进入数据集

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，但在技术图表领域已是目前最大的人工标注替代数据集，且每条样本包含代码锚点，语义深度远超现有数据集。

🔄 [v2 改进]

规模估算说明（第一性原理修正版）

注意：上表（原方案数据）的估算存在严重乐观偏差，请参阅 3.1 节的修正估算。

修正后的现实规模预测：

阶段候选量通过率预计保留说明
GitHub star>500 仓库~50,000-50,000可通过 API 验证
README 含技术图表（非 badge/截图）50,000~4%~2,000实际比例远低于预期
OCR 质量过滤2,000~70%~1,400
文件级代码对齐（score>0.6）1,400~30%~420函数级放弃，文件级通过率约30%
人工验证（评分≥2）420~70%~300 个这是核心高质量三元组

修正结论：

  • 现实可期的规模是约 300-500 个精标三元组（而非 320K）
  • 这个规模不足以作为训练数据，但完全足够作为高质量评测集

3.5 质量验证

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

3.6 重新定位：精品评测集（v2 新增）

🔄 [v2 改进]

建议将本方案重新定位为「高质量技术图表理解评测集」

基于 3.1 节的规模修正和 3.2 节的对齐粒度分析，本方案的可行落地形式应从「大规模训练数据」调整为「精品评测集」：

重新定位的理由：

  1. 可行规模（300-500 个三元组）不足以支撑训练数据的用途
  2. 精标三元组的质量极高（人工验证过对齐），用于评测的可信度远高于自动标注的大规模数据
  3. 现有多模态模型在技术图表理解上没有可靠的评测集，这个空缺比缺少训练数据更急迫

精品评测集的设计思路：

  • 规模目标：50-500 个精心标注的三元组（而非追求 10 万+）
  • 每条三元组附带 3-5 个问答对（覆盖从图表读取到架构推理的不同难度）
  • 问答类型：
    • Q1：「图中哪个组件负责 X 功能？」（组件识别，基础）
    • Q2：「A 到 B 的数据流经过哪些中间节点？」（路径推理，中等）
    • Q3：「根据图表，如果 X 组件宕机，哪些功能会受影响？」（故障分析，高阶）
  • 评测基准：现有多模态模型（GPT-4V、LLaVA、InternVL）在这个评测集上的基准分数，用于衡量模型进步

如果未来想扩展为训练数据：

  • 需要开发新的对齐方法（可能需要专门的技术图表理解模型辅助对齐）
  • 或转向合成数据路径：从真实代码自动生成架构图 + 对应代码描述（反向生成，质量可控）
  • 当前阶段，合成数据路径比爬取路径更可行

评估闭环：如何验证评测集的有效性

  • 验证方式 1：专家评审——5 位具备 3 年以上软件工程经验的工程师，对每个问答对独立评分（1-5），目标平均分 ≥ 4.0
  • 验证方式 2：模型区分度——强模型（GPT-4V）和弱模型（LLaVA-7B）在评测集上的得分差距应 ≥ 20 个百分点
  • 验证方式 3：因果验证——用少量精标数据 fine-tune 基础模型，检验评测集上的分数是否与实际工程问题解决能力相关

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万样本）上验证对齐质量，再决定是否全量推进，会是更稳健的执行策略。

🔄 [v2 改进]

小结补充：v2 版本的核心调整

v2 评审的核心结论是：这个方向是对的，但规模预期需要大幅下调，定位需要从「训练数据」调整为「评测集」。

下调理由：

  1. 第一性原理推导的规模（300-500 个精标三元组）与原方案声称的 320K 相差 3 个数量级
  2. 代码-图表对齐在函数级不可行，文件级对齐的准确率也只有 30-40%
  3. 版权风险在商用场景下是致命障碍

调整后的可行路径：

  • 短期（3 个月）：构建 50-500 个精标三元组，作为技术图表理解评测集，发表评测基准论文
  • 中期（6-12 个月）：探索合成数据路径（从代码生成对应架构图），规避版权和对齐问题
  • 长期：如果合成数据路径验证有效，才回头考虑大规模爬取训练数据的可行性

原始版本：code-diagram-alignment-multimodal-data