跳转至

快速开始

本指南将引导您完成诺贝尔奖知识图谱项目的环境搭建和流水线运行。

前置条件

要求 版本 用途
Python >= 3.12 运行环境
uv 最新版 包管理工具
OpenAI API Key — LLM 概念抽取（阶段 2b）

安装步骤

1. 克隆仓库

git clone https://github.com/example/nobel-kg.git
cd nobel-kg

2. 安装依赖

uv add polars pandas pyarrow networkx pyvis plotly requests openai pyyaml python-dotenv tqdm scikit-learn pymupdf

3. 配置环境变量

在项目根目录创建 .env 文件：

OPENAI_API_KEY=sk-your-api-key-here
OPENAI_BASE_URL=https://api.openai.com/v1  # 可选：自定义端点

4. 验证数据

确认数据目录包含所需文件：

ls data/26963326/db_data/
# 期望：author.csv, award_info.csv, institution.csv, laureate.csv, ...

ls data/26963326/json/
# 期望：award_details.json, laureate_info.json, publication_records.json

运行流水线

完整运行

uv run python main.py

将依次执行全部 6 个阶段：

  1. 阶段 1 — 数据加载与清洗
  2. 阶段 1.5 — 内容富化（Semantic Scholar + OA PDF）
  3. 阶段 2a — OpenAlex 概念富化
  4. 阶段 2b — LLM 概念抽取
  5. 阶段 3+4 — 知识图谱构建
  6. 阶段 5 — 可视化
  7. 阶段 6 — 洞见分析

运行特定阶段

# 仅运行数据加载
uv run python main.py --phase 1

# 仅运行图谱构建
uv run python main.py --phase 3

# 仅运行可视化
uv run python main.py --phase 5

跳过可选步骤

# 跳过 LLM 抽取（节省 API 费用）
uv run python main.py --skip-llm

# 跳过内容富化
uv run python main.py --skip-enrich

运行单个模块

每个模块也可以独立运行：

uv run python -m src.data_loader
uv run python -m src.openalex_enricher
uv run python -m src.concept_extractor
uv run python -m src.graph_builder
uv run python -m src.visualize
uv run python -m src.insight_analyzer

查看输出

可视化

启动本地 HTTP 服务查看交互式 HTML 可视化：

python3 -m http.server 8765 --directory output/viz

在浏览器中打开：

报告

洞见报告以 Markdown 格式生成：

cat output/reports/insight_report.md

知识图谱

图谱数据以多种格式存储：

# 完整图谱（JSON）
output/graph/knowledge_graph.json

# 单独的节点/边文件
output/graph/nodes.json
output/graph/edges.json

# GraphML 格式（适用于 Gephi、Cytoscape 等）
output/graph/knowledge_graph.graphml

# 简化概念图（仅概念节点）
output/graph/concept_graph_simplified.json
output/graph/concept_graph_simplified_nodes.json
output/graph/concept_graph_simplified_edges.json
output/graph/concept_graph_simplified.graphml

样本模式

默认情况下，流水线在样本模式下运行，使用跨 4 个领域的 5 位代表性得主：

ID 姓名 领域 年份
745 A. Michael Spence 经济学 2001
102 Aage N. Bohr 物理学 1975
779 Aaron Ciechanover 化学 2004
114 Abdus Salam 物理学 1979
843 Ada E. Yonath 化学 2009

这会生成一个可管理规模的图谱（约 97 个节点、181 条边），适合开发和测试。

常见问题

缺少 API Key

如果出现 OpenAI API key not found 错误，请确保 .env 文件包含有效的 OPENAI_API_KEY。

大型 JSON 文件

publication_records.json 文件大小为 2.3 GB。流水线使用流式/样本加载来保持合理的内存使用。

速率限制

OpenAlex API 和 Semantic Scholar API 有速率限制。流水线内置了自动限速和缓存机制来优雅地处理这一问题。

下一步