Skip to content

README_CN.md

Latest commit

 

History

History
295 lines (218 loc) · 8.72 KB

README_CN.md

File metadata and controls

295 lines (218 loc) · 8.72 KB

RAG Builder Skill

作者：Leo Yuan Tsao

English | 中文

一个高级 AI 技能，用于构建生产级 RAG（检索增强生成）知识库。支持实体去重、领域自适应实体类型、自学习类型系统和交互式知识图谱可视化。

基于 LightRAG 构建。

✨ 功能特性

🔄 实体去重

自动检测并合并重复实体，支持多种策略：

  • 子串匹配 — "Dante" + "Dante Alighieri" → 合并
  • 编辑距离相似度 — "Virgil" + "Virgilius" → 合并
  • 基于上下文消歧 — 比较实体描述内容
  • 三种合并策略：conservative（保守）、smart（智能，默认）、aggressive（激进）

🎯 领域自适应实体类型

自动检测文档领域并生成合适的实体类型：

领域 示例类型
文学 Character, Location, Event, Literary_Work, Symbol, Creature
医学 Disease, Symptom, Treatment, Drug, Anatomy, Biomarker
法律 Case, Court, Judge, Party, Statute, Precedent
商业 Company, Product, Technology, Market, Strategy, Metric
科学 Theory, Experiment, Researcher, Method, Finding, Hypothesis
历史 Person, Event, Location, Organization, Time_Period, Artifact
技术 Technology, Product, Algorithm, Protocol, Platform, Tool

对于未预设的领域，系统会通过 LLM 自动分析并生成定制类型。

🧠 自学习类型系统

系统从每次构建中学习：

  1. 捕获 LLM 返回的实体类型
  2. 标准化类型名称（book/work → Book_Work）
  3. 统计使用频率
  4. 自动将高频类型合并到模板
  5. 为后续构建优化类型列表

越用越智能！

📊 交互式可视化

自动生成交互式知识图谱浏览器：

  • 实体类型颜色编码 — 每种类型有独特颜色
  • 点击查看详情 — 点击节点查看描述、类型和关联实体
  • 类型筛选栏 — 按类型过滤节点
  • 可折叠面板 — 左侧边栏和右侧详情面板可隐藏
  • 搜索 — 按名称查找实体
  • 拖拽缩放 — 自由探索图谱

📁 广泛的文件格式支持

支持 40+ 种文件格式的文本提取：

格式 扩展名 依赖
PDF .pdf PyPDF2
Word .docx python-docx
PowerPoint .pptx python-pptx
Excel .xlsx .xls openpyxl
EPUB .epub ebooklib
MOBI / AZW3 .mobi .azw3 Calibre 或 mobi
纯文本 .txt .md .json .csv .yaml .xml ... —
代码 .py .js .ts .java .go .rs .cpp ... —

所有依赖首次使用时自动安装。

🚀 安装

Claude Code / Anthropic CLI

git clone https://github.com/yuancafe/rag-builder.git
cp -r rag-builder/skills/rag-builder ~/.claude/skills/

StepFun / 小跃

git clone https://github.com/yuancafe/rag-builder.git
cp -r rag-builder/skills/rag-builder ~/.stepfun/skills/

其他 AI Agent

git clone https://github.com/yuancafe/rag-builder.git
cp -r rag-builder/skills/rag-builder ~/.agents/skills/

前置依赖

pip install lightrag-hku networkx python-Levenshtein

可选依赖（需要时自动安装）：

pip install PyPDF2 python-docx python-pptx openpyxl ebooklib beautifulsoup4

📖 使用方法

快速开始（Python）

import os, sys, asyncio

sys.path.insert(0, os.path.expanduser("~/.stepfun/skills/rag-builder/scripts"))
from rag_builder_advanced import RAGBuilder

# 设置 API Key（支持任何 OpenAI 兼容端点）
os.environ["OPENAI_API_KEY"] = "your-api-key"
os.environ["OPENAI_BASE_URL"] = "https://api.openai.com/v1"

async def main():
    builder = RAGBuilder(
        files=["document.pdf", "notes.md"],
        output_dir="./my_rag",
        auto_detect_domain=True,        # 自动检测领域
        deduplicate_entities=True,      # 实体去重
        generate_visualization=True,    # 生成可视化
    )
    await builder.build()

asyncio.run(main())

命令行使用

# 构建 RAG
python3 rag_builder_advanced.py document.pdf -o ./my_rag --auto-detect

# 检测领域并生成实体类型
python3 domain_detector.py document.pdf -n 12 -o domain.json

# 分析重复实体
python3 entity_deduplicator.py ./my_rag/rag_database -t 0.85

# 为已有 RAG 生成可视化
python3 generate_visualization.py ./my_rag/rag_database -o ./my_rag/visualization

# 提取任意文件的文本
python3 extract_text.py document.epub

配置选项

RAGBuilder(
    files=["doc1.pdf", "doc2.docx"],   # 输入文件（支持任意格式）
    output_dir="./my_rag",              # 输出目录

    # 领域与实体类型
    auto_detect_domain=True,            # 通过 LLM 自动检测领域
    custom_entity_types=None,           # 或手动指定：["Person", "Location", ...]

    # 去重
    deduplicate_entities=True,          # 启用实体合并
    similarity_threshold=0.85,          # 相似度阈值（0.0–1.0）
    merge_strategy="smart",             # "conservative" | "smart" | "aggressive"

    # 可视化
    generate_visualization=True,        # 生成交互式查看器

    # API（任何 OpenAI 兼容端点）
    llm_model="gpt-4o-mini",
    embedding_model="text-embedding-3-small",
    api_key=os.environ["OPENAI_API_KEY"],
    base_url="https://api.openai.com/v1",
)

📂 输出结构

my_rag/
├── rag_database/                    # LightRAG 知识库
│   ├── vdb_entities.json            # 实体向量
│   ├── vdb_relationships.json       # 关系向量
│   ├── vdb_chunks.json              # 文本块向量
│   ├── graph_chunk_entity_relation.graphml  # 知识图谱
│   └── kv_store_*.json              # 键值存储
├── visualization/                   # 交互式查看器
│   ├── index.html                   # 在浏览器中打开
│   ├── graph_data.json              # 图数据
│   └── entity_details.json          # 实体描述
├── reports/
│   ├── deduplication_log.json       # 实体合并历史
│   ├── learning_log.json            # 类型学习结果
│   └── entity_analysis.json         # 实体统计
└── config.json                      # 构建配置

查看可视化

cd my_rag/visualization
python3 -m http.server 8888
# 打开 http://localhost:8888/index.html

🧠 自学习系统

技能维护一个模板文件（entity_type_templates.json），随使用不断优化：

第 1 次构建：8 种类型（预设）→ LLM 返回新类型 → 学习 +3
第 2 次构建：11 种类型 → LLM 返回更多 → 学习 +2
第 5 次构建：15 种类型 → 针对你的领域高度优化

管理学习到的类型

# 查看当前模板
python3 entity_type_learner.py show --domain literature

# 获取优化后的类型列表
python3 entity_type_learner.py optimize --domain medicine

# 从构建日志中学习
python3 entity_type_learner.py learn --log build.log --domain science --auto-merge

🔧 支持的 LLM 提供商

任何 OpenAI 兼容 API 均可使用：

提供商 Base URL 模型
OpenAI https://api.openai.com/v1 gpt-4o-mini, gpt-4o
NVIDIA https://integrate.api.nvidia.com/v1 meta/llama-3.1-8b-instruct
Ollama（本地） http://localhost:11434/v1 llama2, mistral
Azure https://<endpoint>.openai.azure.com/ gpt-4o
Together AI https://api.together.xyz/v1 meta-llama/Llama-3-8b 
export OPENAI_API_KEY="your-key"
export OPENAI_BASE_URL="https://api.openai.com/v1"

📁 文件结构

skills/rag-builder/
├── SKILL.md                         # 技能定义（供 AI Agent 读取）
├── ENTITY_TYPE_LEARNING.md          # 自学习功能文档
├── entity_type_templates.json       # 领域模板（自动更新）
└── scripts/
    ├── rag_builder_advanced.py      # 主构建器（RAGBuilder 类）
    ├── generate_visualization.py    # 交互式可视化生成器
    ├── domain_detector.py           # 领域检测与类型生成
    ├── entity_deduplicator.py       # 实体去重工具
    ├── entity_type_learner.py       # 自学习类型系统
    ├── extract_text.py              # 通用文本提取器
    └── rag_builder.py               # 简易构建器（旧版）

📄 许可证

MIT License

👤 作者

Leo Yuan Tsao — GitHub

🙏 致谢