Tool KG

tool_kg 现在可以作为一个可单独复制、单独运行的知识图谱子项目使用。

适用场景：

• 你要把当前 tool_kg 整个目录复制出去，作为新的独立 repo
• 你要快速启动一个基于本地数据集的 Web3 安全知识图谱网站
• 你要继续基于 markdown 文档重建、清理、导入 pgvector 数据

这一版默认走 pgvector + 文件数据集 + FastAPI + 静态前端 路线，不依赖 Neo4j。

你要复制什么

直接复制整个 tool_kg/ 目录即可。

复制后的新仓库建议结构如下：

your-new-repo/
├── app.py
├── dataset_cleaner.py
├── dataset_repository.py
├── pgvector_builder.py
├── preprocessor.py
├── embedding_utils.py
├── web/
├── scripts/
├── data/
├── Dockerfile
├── docker-compose.yaml
├── pyproject.toml
└── README.md

说明：

• 新 repo 的根目录，就是当前这个 tool_kg 目录本身
• data/ 可以保留现成数据集，也可以后续自己重建
• 默认推荐直接带上 data/site_rebuilt_v2_clean，这样开箱即用

快速启动

方案 A：直接使用当前内置数据集启动

如果你复制时保留了 data/site_rebuilt_v2_clean，这是最快的启动方式。

1. 进入新 repo 根目录

cd your-new-repo

2. 安装依赖

uv sync

3. 启动站点

uv run serve-kg-web

4. 打开浏览器

http://127.0.0.1:8131/

默认会优先读取以下数据集目录：

• data/site_rebuilt_v2_clean
• data/site_clean_v4_soft
• data/site

也可以显式指定：

TOOL_KG_DATASET_DIR=./data/site_rebuilt_v2_clean uv run serve-kg-web

Windows PowerShell:

$env:TOOL_KG_DATASET_DIR = ".\data\site_rebuilt_v2_clean"
uv run serve-kg-web

方案 B：从 markdown 原材料重新构建

1. 构建原始数据集

uv run build-kg-pgvector --input ./docs --output ./data/site

2. 清理数据集

uv run clean-kg-pgvector --input ./data/site --output ./data/site_clean

3. 使用清理后的数据集启动

TOOL_KG_DATASET_DIR=./data/site_clean uv run serve-kg-web

Windows PowerShell:

$env:TOOL_KG_DATASET_DIR = ".\data\site_clean"
uv run serve-kg-web

Docker 启动

如果你想直接容器化运行：

docker compose up --build -d

访问地址：

http://127.0.0.1:8131/

说明：

• docker-compose.yaml 现在以当前目录为根目录构建
• 容器默认读取 /app/tool_kg/data/site_rebuilt_v2_clean
• 如果你要换数据集，只需要修改 TOOL_KG_DATASET_DIR

停止服务：

docker compose down

PostgreSQL / pgvector 导入

如果你还需要把生成的 SQL 导入 PostgreSQL：

1. 启动数据库

docker compose up -d pgvector

2. 导入当前数据集

uv run import-kg-pgvector --dataset-dir ./data/site_rebuilt_v2_clean

默认 DSN：

postgresql://postgres:postgres@localhost:5434/tool_kg

也可以通过环境变量覆盖：

TOOL_KG_PGVECTOR_DSN=postgresql://postgres:postgres@localhost:5434/tool_kg \
uv run import-kg-pgvector --dataset-dir ./data/site_rebuilt_v2_clean

CLI 命令

当前独立 repo 可直接使用这些命令：

• uv run serve-kg-web
• uv run build-kg-pgvector --input ./docs --output ./data/site
• uv run clean-kg-pgvector --input ./data/site --output ./data/site_clean
• uv run import-kg-pgvector --dataset-dir ./data/site_clean

这些命令既支持当前大仓库内运行，也支持把 tool_kg 拷贝成单独 repo 后运行。

推荐交付方式

如果你的目标是“拎包即走”，我建议直接把下面这些内容一起带走：

• 代码
• web/
• scripts/
• pyproject.toml
• Dockerfile
• docker-compose.yaml
• data/site_rebuilt_v2_clean
• README.md

这样新 repo 拿到手后只需要：

uv sync
uv run serve-kg-web

注意事项

• 当前 Web 展示站是基于文件数据集工作的，不要求必须先导入 PostgreSQL
• import-kg-pgvector 只在你确实要把 SQL 导入 pgvector 时才需要
• 如果你不想携带历史数据集，可以只保留 docs/，然后在新 repo 里重新构建
• 当前 tool_kg 目录里仍保留一些旧的 Neo4j / LightRAG 代码，但“开箱即用”的主路径已经是 pgvector + 文件站点