Hugging Face's logo

NLP-beginner
/
cs3319-project2

Model card Files
xet
 Community
cs3319-project2 / docs /diagrams /README.md
NLP-beginner's picture
NLP-beginner
CS3319 Project 2 final deliverable (public F1 = 0.96626)
f28d994
preview code
|
Raw
History Blame Contribute Delete
6.8 kB

科研流程图与架构图（CS3319 推荐系统）

本目录存放本项目「方法 / 架构 / 依赖」的可维护矢量图。所有图都以源文件形式保存在 src/，由 scripts/render_diagrams.sh 一键渲染为 SVG / PDF 到 svg/、pdf/。 图只表达关键模块（不堆砌全部代码文件），可直接放入论文或课程报告。

设计原则：源文件即真相，SVG/PDF 是构建产物。改图就改 src/ 里的源文件，再重渲染。 切勿手工编辑 svg/、pdf/ 里的产物——下次渲染会被覆盖。

目录结构 

docs/diagrams/
├── src/                         # 图的源文件（编辑这些）
│   ├── pipeline.mmd             # Mermaid：整体实验流程
│   ├── architecture.d2          # D2：系统分层架构
│   ├── dependencies.dot         # Graphviz：关键模块运行时依赖
│   ├── architecture_c4.puml     # C4-PlantUML：系统主架构图（论文主图）
│   └── architecture_c4_features.puml  # C4-PlantUML：259 维特征构成
├── svg/                         # 渲染产物（自动生成，勿手改）
├── pdf/                         # 渲染产物（自动生成，勿手改）
└── README.md                    # 本文件
scripts/render_diagrams.sh       # 一键渲染脚本

五张图分别表达什么

文件 工具 表达内容 论文用途
pipeline.mmd Mermaid 端到端实验流程：数据 → 确定性划分(seed=202) → 6 个 Stage-1 分数源 → 259 维特征 → LightGBM 二级堆叠 → rank-cutoff 决策 → 提交。用 contrib 类高亮高阶传播这一核心贡献。 方法流程图（Flow）
architecture.d2 D2 分层系统架构：Data Layer / Deterministic Split / Stage-1 Suite / Stage-2 Meta-learner / Decision / Output 七层 + Shared Infrastructure（两个 load_module 共享库、特征缓存、无 utils 的代码复用约定）。 系统架构图
dependencies.dot Graphviz 关键模块运行时依赖：用 importlib load_module() 互相加载的真实关系。粗深色边 = 最终堆叠器加载各生产者；实线绿边 = 生产者间复用；点线灰边 = 扇入共享库。带图例。 工程/可复现性说明
architecture_c4.puml C4 Container 系统主架构图（论文主图）：外部（异构图 + 榜单）↔ 系统边界（Two-Stage Stacking Recommender）。Stage-1 用 Container_Boundary 收纳 6 个 Component（LightGCN / BPR-MF / Random Walk / Content / Explicit / High-order（核心贡献）），经 Feature Cache → Meta-Learner → Decision → 输出。标注公开 F1 = 0.96626、验证 F1 = 0.966874。 论文主图（Main Figure）
architecture_c4_features.puml C4 Component 259 维特征构成：把主图里的「特征向量」放大，标注每组特征的维度（X_base 84-d = 4+18+8+3+43+4+4，再 +rich 18 +RW 77 +agg 11 +undir 24 +dir 45 = 259），汇入 LightGBM。 方法细节图

为什么用三种工具：Mermaid 适合「方法流程」（GitHub/Typora 直接预览）；D2 适合「分层架构」；Graphviz 适合「依赖网络」；C4-PlantUML 适合「面向论文的专业架构主图」（有外系统边界、图例、规范的容器/组件抽象）。

如何重新渲染（一键） 

# 渲染全部源文件 → SVG + PDF
bash scripts/render_diagrams.sh

# 只渲染 SVG（跳过 PDF，更快）
bash scripts/render_diagrams.sh --svg

脚本特性：

  • 优雅降级：某个工具没装，会被跳过并提示，不会中断整体运行；装好后重跑即可补齐。
  • 自动取工具：
    • plantuml.jar 缺失时自动从 GitHub 下载到 scripts/.cache/plantuml.jar。
    • d2 缺失时（Windows）尝试 scoop install d2。
    • mmdc 缺失时回退到 npx --yes @mermaid-js/mermaid-cli。
  • 逐图打勾/叉：末尾打印 SVG: N PDF: M failed: K 汇总。

渲染产物：docs/diagrams/svg/*.svg 与 docs/diagrams/pdf/*.pdf。

单独渲染某一类（手工命令） 

# Mermaid
mmdc -i docs/diagrams/src/pipeline.mmd -o docs/diagrams/svg/pipeline.svg
# D2
d2 docs/diagrams/src/architecture.d2 docs/diagrams/svg/architecture.svg
# Graphviz
dot -Tsvg docs/diagrams/src/dependencies.dot -o docs/diagrams/svg/dependencies.svg
# PlantUML / C4（注意：它在源文件旁输出，需手动移动）
cd docs/diagrams/src && \
  java -jar ../../scripts/.cache/plantuml.jar -tsvg architecture_c4.puml && \
  mv architecture_c4.svg ../svg/

如何更新一张图

  1. 编辑 docs/diagrams/src/ 下对应的源文件。
  2. 核对事实：图里的数字（如 259 维构成、136,484 验证对、F1）必须与代码 / 报告一致。
    • 259 维构成见 reports/final_report.md 与 code/high_order_graph_stack.py。
    • 依赖关系改了，先在 code/ 里 grep -n "load_module" 确认，再改 dependencies.dot。
  3. bash scripts/render_diagrams.sh 重渲染。
  4. 打开 svg/*.svg 目视检查布局/文字是否溢出；必要时调源文件里的 skinparam/classes/rankdir。

改图时的常见注意点（踩过的坑）

  • C4-PlantUML 的 include：!include <C4/C4_Container> 不定义 Component 宏；要用 Component(...) 必须用 !include <C4/C4_Component>（它向下包含 Container→Context，定义全部宏）。System_Boundary 是带下划线的（不是 SystemBoundary）。
  • D2：stroke-dash 只接受单个 0–10 的数字（不是 CSS 的 4 3）；没有 note shape，注释用 shape: text。
  • Graphviz：依赖图刻意用三种边样式 + constraint=false 控制层级，避免「毛线球」；加边前想清楚属于哪一类。

工具安装（一次性）

工具 安装 用途
Mermaid CLI npm i -g @mermaid-js/mermaid-cli .mmd → SVG（首次会拉 puppeteer chromium）
D2 Windows: scoop install d2 · macOS: brew install d2 .d2 → SVG
Graphviz Windows: scoop install graphviz · macOS: brew install graphviz .dot → SVG
PlantUML scoop install temurin21-jdk（或任意 JDK）；jar 由脚本自动下载 .puml → SVG（C4 stdlib 已内置于 jar）

本目录的图已在 Windows + bash 环境下验证全部可渲染（Graphviz 14.1.1、mmdc 11.15.0、d2 0.7.1、PlantUML 1.2026.6）。

与其它文档的关系

  • 图里的方法叙事与 reports/final_report.md、docs_first_principles/ 一致。
  • 259 维特征构成与 docs_first_principles/_fact_sheet.md（数值唯一真相源）对齐。
  • 若数值有出入，以 _fact_sheet.md 和代码为准，并回头修正这里的图。