数学分析知识图谱（BUAA 工科数学分析 · 上下册）

项目简介

本项目是一个面向《工科数学分析》（北航上下册）的本地知识图谱系统：把课程的知识点、定理与方法整理成可交互浏览的语义网络，并在其上接入本地大模型，完成知识图谱约束的错题分析。整个系统零数据库、可完全离线运行——不依赖 Neo4j、向量库或外网 CDN。

两种使用方式：

• 📖 静态浏览版（serve.sh）：纯前端渲染图谱，支持逐级展开、语义关系彩色编码与筛选、多跳邻域浏览、BFS 路径查询，以及基于图谱关系的学习路径助手（先修补全 / 推荐路径 / 易混淆提醒）。
• 🤖 AI 错题分析版（serve_ai.sh）：在浏览功能之上接入本地 Ollama。自研召回管线（IDF 稀疏检索 + 题型结构规则 + 领域消歧 + 层级先验）先选出候选知识点，再约束 LLM 只能在候选范围内选考点，后端二次校验丢弃幻觉节点；Ollama 不可用时自动降级为本地文本匹配。

所有图谱数据收录在 data/kg.json 中：

• 课程：北京航空航天大学 · 工科数学分析（上 + 下）
• 节点：约 580 个（根 → 册 → 章 → 节 → 知识点）
• 关系：约 630 条，覆盖 7 种语义关系（PREREQUISITE_OF / USED_IN / GENERALIZES / SPECIAL_CASE_OF / SIMILAR_TO / EASILY_CONFUSED_WITH / RELATED_TO）

项目结构

KG_GroupWork/
├── README.md
├── .gitignore
│
├── data/
│   ├── build_kg.py              # 知识图谱主数据源；用 Python 注册节点和关系
│   └── kg.json                  # 生成后的图谱数据；前端和后端共同读取
│
├── viewer/
│   ├── index.html               # 图谱浏览器页面结构
│   ├── styles.css               # 前端样式
│   ├── app.js                   # 图谱渲染、查询、学习助手、错题分析交互逻辑
│   └── vendor/
│       └── cytoscape.min.js     # 本地化 Cytoscape.js，保证离线可视化
│
├── code/
│   └── problem_analyzer_server.py  # AI 版本地后端: 静态服务 + Ollama 错题分析API             
├── serve.sh / serve.bat            # 静态浏览版启动脚本            
├── serve_ai.sh / serve_ai.bat      # 带本地 LLM 错题分析的启动脚本
└── 展示题目.md                      # 现场演示可用题目与讲解提示

快速开始

静态浏览版：

./serve.sh           # macOS / Linux
# 或：
serve.bat            # Windows

启动后浏览器打开：http://127.0.0.1:8000/viewer/

带本地 LLM 错题分析版： 需要下载 Ollama 以及本地大模型. 请确保本地有足够大的显存/内存以运行本地模型!

ollama run qwen2.5:7b    # 确认本地模型已可用；已下载过模型的话可跳过.

./serve_ai.sh            # macOS / Linux
# 或：
serve_ai.bat             # Windows

同样访问：http://127.0.0.1:8000/viewer/

AI 版额外需要：

• Python 3
• Ollama
• 本地模型：qwen2.5:7b

不需要 BGE、向量数据库、Neo4j 或额外 Python 依赖库。图谱渲染依赖的 Cytoscape.js 已放在 viewer/vendor/cytoscape.min.js，页面不再依赖 CDN。

如果使用 qwen3.5:9b、qwen3:14b 这类响应较慢的模型，可以调大等待时间：

OLLAMA_MODEL=qwen3.5:9b OLLAMA_TIMEOUT=420 ./serve_ai.sh

你能在浏览器里做什么

• 左侧树：按「数学分析 → 上册 / 下册 → 章 → 节 → 知识点」逐级展开
• 顶部搜索：输入「泰勒公式」「Stokes」「条件收敛」「可微」等任意片段，回车定位
• 中间图：选中节点后立即展示周围 N 跳邻居（默认 2 跳），不同语义关系不同颜色；根节点会自动提升到 3 跳以展示到「节」层
• 图中边标签：语义关系会显示为中文标签（前置 / 应用于 / 推广 / 特例 / 类比 / 易混淆 / 相关）
• 顶部图例：勾选 / 取消任意语义类型，即时筛选图
• 「显示父子层级」开关：开启后会把 CONTAINS 父子边也画出来（默认关闭，专注于语义关系）
• 右侧详情：节点简介 + 按关系类型分组列出所有邻居，点击邻居即可跳转
• 右侧学习路径助手：基于增强关系自动生成先修补全、推荐路径、应用方向与易混淆/类比提醒
• 顶部「图谱查询」按钮：支持节点关键词查询、关系实例查询和 4 跳内路径查询，查询结果可点击并在图中高亮
• 顶部「错题分析」按钮：打开错题分析浮层，粘贴一道数学题后系统会调用本地 Ollama，在知识图谱候选节点范围内输出考点权重、条件检查、补救路径和图谱依据，并高亮相关节点；错题分析窗口支持拖拽移动、右下角自由缩放，并会自动读取本地 Ollama 模型列表

图谱查询

点击顶部「图谱查询」可以打开查询浮层。查询完全在前端基于 data/kg.json 完成，不依赖后端或数据库。

• 节点查询：输入关键词，匹配节点 id、名称、简介和层级路径；支持轻量模糊匹配。
• 关系查询：输入头节点（选填）、关系类型、尾节点（选填）。头/尾为空时，会返回该关系类型下的所有实例；关系类型下拉框会自动读取当前图谱中的全部关系类型。
• 路径查询：输入起点和终点，系统会先做轻量模糊匹配并显示实际匹配到的图谱节点，再用 BFS 在用户选择的最大跳数内查找一条最短路径。路径搜索允许沿边的两个方向导航，但结果会用 → / ← 标明图谱中真实边方向。

查询结果可以点击，点击后会自动定位图谱并高亮对应节点或边。

学习路径助手

选中任意知识点后，右侧会出现「学习路径助手」。它完全基于 data/kg.json 中的增强关系进行确定性分析，不调用 LLM，也不需要后端服务。

• 先补基础：优先沿 PREREQUISITE_OF、USED_IN、GENERALIZES 的反向关系寻找当前知识点的可能前置。
• 推荐路径：将前置知识、当前知识点和后续应用串成一条可点击路径。
• 应用方向：沿 USED_IN、PREREQUISITE_OF、SPECIAL_CASE_OF 寻找学完当前知识点后的应用或后续主题。
• 易混淆 / 类比：沿 EASILY_CONFUSED_WITH、SIMILAR_TO、RELATED_TO 给出辨析和类比提醒。

当推荐内容较多时，学习路径助手卡片内部会独立滚动，不会撑爆右侧详情栏。

错题分析 Agent

AI 版服务由 code/problem_analyzer_server.py 提供。它同时承担两件事：

1. 像 serve.sh 一样提供 viewer/ 静态页面。
2. 提供 POST /api/analyze-problem，调用本地 Ollama 做知识图谱约束下的错题分析。
3. 提供 GET /api/models，自动读取本地 Ollama 已部署模型，供前端下拉选择。

推荐示例：(更多例子, 详见 展示题目.md)

设函数 $f(x)$ 定义如下：$$f(x) = \begin{cases} x^2 \sin\left(\frac{1}{x}\right), & x \neq 0 \\ 0, & x = 0 \end{cases}$$ 请求出函数 $f(x)$ 在 $x=0$ 处的导数 $f'(0)$，并说明求解依据

系统逻辑：

题目文本
→ 分词：正则抽拉丁词/数字 + 中文 2~4 gram 滑窗（不做词典分词/词性识别）
→ 对每个节点的富文本（名称 + summary + 层级路径 + 关系 note）打分：
    · IDF 加权的词项重合（稀有专业术语权重高，"函数/求"等高频词自动趋近 0）
    · 节点名整体命中题面（强信号）
    · 题型识别规则：识别"分段点求导/振荡极限/瑕积分/交错级数/泰勒…"等结构特征，
      注入对应标准考点术语去匹配节点（补上题面字面没写的考点名）
    · 领域消歧：按题面是级数(∑)还是积分(∫)，对同名跨章考点加权/降权
    · 层级先验：偏向"知识点/节"，弱化"册/根"
→ 取 top-36 文本命中，再沿图谱对其中最强 8 个做 1 跳邻域扩散（邻居按 0.4× 分入池）
→ 得到 top-k 候选知识点
→ 把候选知识点 ID 列表交给本地部署的大模型, 比如 qwen2.5:7b
→ 要求模型只能从候选 ID 中选择考点并输出 JSON
→ 后端再次校验 ID，丢弃模型编造的节点
→ 前端展示考点权重、条件检查、解题提示、易错点和图谱依据
→ 图谱中用醒目的外框/光圈高亮命中的节点和直接关系

召回打分逻辑全部在 retrieve_candidates() 及其依赖 tokens() / concept_signals() / domain_scope() 中，不针对演示题写死任何节点 id。

这不是让大模型自由聊天，而是让大模型完成「题目 → 图谱节点」的映射。模型输出会被限制在 data/kg.json 的节点名单内，因此答辩时可以解释为：LLM 负责理解题面和组织语言，知识图谱负责约束考点范围和提供可视化依据。

如果 Ollama 没启动或模型超时，系统会自动降级为本地文本匹配结果，并在前端提示 warning；此时不会生成 LLM 解释，但仍能展示候选考点和图谱高亮。

错题分析窗口可以通过顶部「错题分析」按钮打开；窗口内的「关闭」只是隐藏到后台，不会中断正在进行的 Ollama 分析。等结果生成后，再点顶部「错题分析」按钮即可重新打开查看。窗口可以直接拖动标题栏或边缘改变位置，也可以拖动右下角改变大小。窗口移动范围是浏览器视口，而不是中间图谱区域。底部模型下拉框会自动加载 ollama list 对应的本地模型；如果刚下载了新模型，可以点「刷新」重新读取。

想改 / 加节点和关系？

编辑 data/build_kg.py，然后重新生成 JSON：

python3 data/build_kg.py

脚本会打印节点 / 关系数和按类型的分布统计，所有引用错误（不存在的 id、自环、重复边）会立刻报错。data/kg.json 直接 overwrite。

想微调关系中文显示？

图谱边上的中文标签和说明在 viewer/app.js 顶部的 RELATION_UI 中维护：

PREREQUISITE_OF: { label: "前置", desc: "A 是理解 B 的前置知识。" }

如果想把「应用于」改成「用于」，或把「前置」改成「先修」，直接改这个表即可。

设计取舍

• JSON 不手写：build_kg.py 用函数注册节点 / 关系，重复 id、悬挂引用、自环立即抛错；维护成本远低于直接编辑 JSON。
• LLM 只作为可选下游应用：静态浏览器仍可零后端运行；错题分析需要 serve_ai 和本地 Ollama。
• 不做 BGE / 向量库：错题分析用 IDF 加权的稀疏检索 + 题型识别规则 + 领域消歧召回候选节点，再让 LLM 在候选 ID 内选择，避免为了效果堆依赖；召回不含针对演示题的硬编码，换同类新题同样适用。
• 零数据库 / 可离线演示：Cytoscape.js 已本地化到 viewer/vendor/，无需 Neo4j，也不需要访问外网加载前端依赖。
• 浅色阅读界面：保持课程资料浏览的清爽感；颜色编码 7 种关系类型(CONTAINS 包含关系不显示颜色)，肉眼易辨。

验证

python3 -c "import json; data = json.load(open('data/kg.json')); print(data['stats'])"

启动 server 后，搜索「泰勒公式」/「Stokes 公式」/「条件收敛」三个查询点，应能看到合理的局部子图、中文边标签、按类型分组的邻居，以及右侧学习路径助手。

AI 版可额外验证：

python3 code/problem_analyzer_server.py --port 8000 --model qwen2.5:7b

打开 http://127.0.0.1:8000/viewer/，在「错题分析」中粘贴一道题并点击「分析考点」。若 Ollama 正常运行，状态栏会显示 “Ollama 已完成图谱约束分析”；若未运行，则会显示降级 warning。

汇报内容/讲稿:

https://mcnt03ebjjux.feishu.cn/wiki/PUzZwg15siPkVpkB41gcMOV7nvh?pre_pathname=%2Fdrive%2Fhome%2F

讲稿已更新, 调整了结构, 更加清晰. 请以飞书文档为PPT/项目解释的唯一依据.