# wiki-mvp

**Repository Path**: mengl248/wiki-mvp

## Basic Information

- **Project Name**: wiki-mvp
- **Description**: LLM Wiki 知识库系统 MVP
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-07-10
- **Last Updated**: 2026-07-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LLM Wiki 知识库系统 MVP

<p align="center">
  <img src="https://img.shields.io/badge/Python-3.10+-3776AB?logo=python&logoColor=white" alt="Python 3.10+">
  <img src="https://img.shields.io/badge/FastAPI-0.115+-009688?logo=fastapi&logoColor=white" alt="FastAPI">
  <img src="https://img.shields.io/badge/Vue_3-ElementPlus-4FC08D?logo=vue.js&logoColor=white" alt="Vue 3 + Element Plus">
  <img src="https://img.shields.io/badge/License-MIT-green.svg" alt="MIT License">
</p>

> 基于 Andrej Karpathy 的核心洞察——**“LLM 本质上是互联网文本的有损压缩，它本身就是一部模糊的维基百科”**——将 LLM 的参数化知识显式化为可查询、可标注、可追溯的 Wiki 知识库。

**LLM Wiki** 是一个轻量级、零数据库、全异步的 LLM 知识库系统。它通过上传文档、生成词条、三层降级问答、知识图谱、健康检查与审计日志，把分散的 LLM 参数知识沉淀为结构化的团队知识资产。

---

## 目录

- [项目简介](#项目简介)
- [功能特性](#功能特性)
- [项目结构](#项目结构)
- [快速开始](#快速开始)
- [配置说明](#配置说明)
- [使用指南](#使用指南)
  - [1. 智能问答](#1-智能问答)
  - [2. 文档管理](#2-文档管理)
  - [3. 词条管理](#3-词条管理)
  - [4. 知识图谱](#4-知识图谱)
  - [5. Wiki 健康检查](#5-wiki-健康检查)
  - [6. 重复词条检测](#6-重复词条检测)
  - [7. LLM 调用审计](#7-llm-调用审计)
- [LLM Wiki 与 RAG 知识库对比](#llm-wiki-与-rag-知识库对比)
- [系统架构](#系统架构)
- [API 接口](#api-接口)
- [常见问题](#常见问题)
- [贡献指南](#贡献指南)
- [相关项目](#相关项目)
- [License](#license)

---

## 项目简介

在传统的 RAG 系统中，知识被切割为离散的文本块，检索结果往往缺乏上下文关联和结构化解释。LLM Wiki 的解决思路是：

1. **把 LLM 的参数化知识“显式化”**：通过提示工程让 LLM 生成结构化百科词条。
2. **把文档内容“词条化”**：上传文档后，自动提取关键概念生成 Wiki 词条。
3. **用 [[双向链接]] 构建知识网络**：词条之间通过交叉引用形成图谱，自动计算反向链接。
4. **三层降级问答**：Wiki 词条 → RAG 文档 → 参数化兜底，确保任何情况下都能回答。
5. **持续审计与治理**：健康检查、重复检测、LLM 调用审计，让知识库可维护、可追溯。

> 💡 适合场景：团队内部知识沉淀、产品文档问答、技术方案库、面试/学习笔记库。

---

## LLM Wiki 与 RAG 知识库对比

LLM Wiki 并非替代 RAG，而是与之互补。RAG 擅长「原文级精确召回」，LLM Wiki 擅长「概念级结构化理解」。理解二者差异，有助于选择合适的知识管理策略，或组合使用。

### 核心理念差异

| 维度 | RAG 知识库 | LLM Wiki |
|------|-----------|----------|
| **知识形态** | 离散文本块（chunks） | 结构化百科词条（title + summary + sections） |
| **知识来源** | 仅限已上传文档 | 文档提取 + LLM 参数化知识显式化 |
| **检索粒度** | 段落级（500~1000 字 chunk） | 概念级（整篇词条主题） |
| **上下文关联** | 各 chunk 相互独立 | `[[双向链接]]` 构建知识网络 |
| **答案质量** | 忠于原文，但可能碎片化 | 结构化、连贯，但可能引入 LLM 主观判断 |
| **可维护性** | 文档更新即生效 | 词条可审核、可标注争议、可追溯演化 |
| **知识发现** | 被动检索（问什么查什么） | 主动显式化（LLM 补全参数知识盲区） |

### 架构对比

```
┌─────────────────────┐         ┌─────────────────────┐
│      RAG 知识库      │         │     LLM Wiki        │
├─────────────────────┤         ├─────────────────────┤
│ 文档 → 分块 → 向量   │         │ 主题/文档 → 词条生成  │
│        ↓             │         │        ↓             │
│  query → 向量检索    │         │  query → 词条检索     │
│        ↓             │         │   (向量+关键词融合)    │
│   拼接 chunks → LLM  │         │        ↓             │
│        ↓             │         │  词条上下文 → LLM     │
│   生成答案 + 引用     │         │        ↓             │
└─────────────────────┘         │  生成答案 + 词条溯源  │
                                │  + 知识图谱 + 审计    │
                                └─────────────────────┘
```

### 适用场景对比

| 场景 | 推荐 | 原因 |
|------|------|------|
| 法律/合规文档精确问答 | RAG | 必须忠于原文，不容许 LLM 改写 |
| 技术方案库、最佳实践沉淀 | LLM Wiki | 需要结构化、可关联、可演化 |
| 产品手册 FAQ | 两者结合 | RAG 保原文准确，Wiki 提供概念导航 |
| LLM 参数知识固化（如框架对比） | LLM Wiki | 文档中本无此内容，需 LLM 显式化 |
| 海量文档全文检索 | RAG | chunk 级检索效率更高 |
| 团队知识图谱构建 | LLM Wiki | 双向链接天然形成知识网络 |

### 本项目的融合策略

LLM Wiki 采用**三层降级**策略，将两者优势结合：

```
用户提问
  │
  ├─ Layer 1: LLM Wiki 词条检索（概念级，结构化）
  │     命中 → 基于词条生成答案（带词条溯源）
  │
  ├─ Layer 2: RAG 文档检索（段落级，忠于原文）  ← 可选，需启用 RAG 桥接
  │     命中 → 基于文档生成答案（带原文引用）
  │
  └─ Layer 3: 参数化兜底（LLM 直接回答）
        未命中 → 标注「参数化知识」，提示归档为词条
```

> 💡 若已部署 [KB-MVP](#相关项目) RAG 系统，启用 `RAG_BRIDGE_ENABLED=true` 即可让 Wiki 在未命中时自动回退到 RAG 检索，实现「概念级 + 原文级」双重保障。

---

## 功能特性

| 功能模块 | 说明 |
|----------|------|
| **文档上传与解析** | 支持 PDF / Word / TXT / Markdown，自动解析为结构化 blocks |
| **词条生成（双模式）** | 从主题生成（参数化知识）或从文档生成（内容提取），SSE 实时进度 |
| **三层降级问答** | Wiki → RAG → 参数化兜底，答案附来源卡片，可溯源 |
| **知识图谱** | 基于 `[[双向链接]]` 构建图，社区检测 / 枢纽 / 孤立节点 / 悬空链接 |
| **Wiki 健康检查** | 6 类诊断：孤儿页面、悬空引用、内容矛盾、过时内容、链接拼写错误、LLM 语义建议 |
| **重复词条检测** | 倒排索引粗筛 + LLM 精排，支持一键合并 |
| **LLM 调用审计** | 每次调用记录 prompt/response/duration/tokens/status，可展开查看详情 |
| **问答归档** | 有价值的问答可一键归档为 Wiki 词条 |
| **多信号融合检索** | 向量相似度 + 5 路关键词打分 + RRF 融合 |
| **零数据库** | 全部 JSON 持久化，无 MySQL / Redis / SQLite，克隆即用 |
| **多供应商适配** | LLM 与 Embedding 独立配置，支持 DeepSeek / GLM / DashScope / Ollama |

---

## 项目结构

```
wiki-mvp/
├── app/                         # 后端核心模块
│   ├── __init__.py
│   ├── config.py                # 配置加载（.env）
│   ├── llm_provider.py          # LLM 适配层（异步 AsyncOpenAI）
│   ├── embedding_provider.py    # Embedding 适配层（异步）
│   ├── document_loader.py       # 文档解析（PDF/Word/TXT/MD → blocks）
│   ├── wiki_generator.py        # 词条生成引擎（增量整合 + 交叉链接）
│   ├── wiki_store.py            # JSON 持久化 + numpy 向量检索
│   ├── wiki_engine.py           # 核心编排：问答/生成/链接/归档/合并
│   ├── wiki_lint.py             # Wiki 健康检查（6 类诊断）
│   ├── wiki_log.py              # 操作日志（时间线）
│   ├── wiki_scoring.py          # 多信号关键词打分 + RRF 融合
│   ├── wiki_graph.py            # 知识图谱引擎
│   ├── wiki_dedup.py            # 重复词条检测
│   ├── wiki_audit.py            # LLM 调用审计
│   ├── wiki_safe_io.py          # 原子文件写入 + 路径遍历保护
│   ├── wiki_schema.py           # Wiki 结构规范（Schema 配置）
│   ├── rag_bridge.py            # RAG 集成适配层（可选）
│   ├── api.py                   # API 路由（31 个接口）
│   └── main.py                  # 应用入口
├── static/
│   └── wiki.html                # 前端界面（零构建单文件）
├── data/                        # 运行时数据（自动创建）
│   ├── docs/                    # 上传的原始文档
│   ├── documents/               # 文档解析结果（JSON）
│   ├── entries/                 # 词条 JSON + 索引
│   └── store/                   # 向量数据
├── docs/
│   └── screenshots/             # 界面截图（README 配图）
├── main.py                      # 根入口
├── .env.example                 # 配置示例
├── .gitignore
├── requirements.txt
├── start.bat                    # Windows 一键启动
├── start.sh                     # macOS/Linux 一键启动
└── README.md                    # 本文件
```

---

## 快速开始

### 环境要求

- Python 3.10+
- 网络（调用 LLM / Embedding API）
- LLM API Key（推荐 DeepSeek / GLM / DashScope）

### 1. 克隆与安装

```bash
cd wiki-mvp

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt
```

### 2. 配置环境变量

```bash
cp .env.example .env
```

编辑 `.env`，至少配置 LLM 与 Embedding 各一项：

```bash
# ===== LLM（推荐 DeepSeek）=====
LLM_PROVIDER=deepseek
LLM_MODEL=deepseek-chat
LLM_API_KEY=sk-xxxxxxxxxxxx
LLM_BASE_URL=https://api.deepseek.com
LLM_TEMPERATURE=0.5

# ===== Embedding（推荐 DashScope 或 Ollama）=====
# 方式一：DashScope（线上 API）
EMBEDDING_PROVIDER=dashscope
EMBEDDING_MODEL=text-embedding-v2
DASHSCOPE_API_KEY=sk-xxxxxxxxxxxx

# 方式二：Ollama（本地，零成本）
# EMBEDDING_PROVIDER=ollama
# EMBEDDING_MODEL=nomic-embed-text
```

### 3. 启动服务

```bash
# 方式一：一键脚本
start.bat          # Windows
./start.sh         # macOS/Linux

# 方式二：直接运行
python main.py

# 方式三：模块方式
python -m app.main
```

访问 **http://127.0.0.1:8889**

> 🌐 启动后会自动加载本地模型配置与词条索引，首次运行会创建 `data/` 目录。

---

## 配置说明

### 常见配置组合

| 组合 | LLM | Embedding | 适用场景 |
|------|-----|-----------|----------|
| **高性价比（推荐）** | DeepSeek | Ollama 本地 | 线上对话 + 本地向量化，零向量成本 |
| **全线上** | DeepSeek | DashScope | 无需本地 GPU，部署最简 |
| **GLM 全家桶** | GLM | GLM | 智谱生态统一 |
| **全本地** | Ollama | Ollama | 零 API 费用，需本地 GPU |

### Ollama 本地配置示例

```bash
# 1. 安装 Ollama 后拉取模型
ollama pull qwen2.5:7b           # 对话模型
ollama pull nomic-embed-text     # 向量模型

# 2. 配置 .env
LLM_PROVIDER=ollama
LLM_MODEL=qwen2.5:7b
LLM_BASE_URL=http://localhost:11434

EMBEDDING_PROVIDER=ollama
EMBEDDING_MODEL=nomic-embed-text
EMBEDDING_BASE_URL=http://localhost:11434

# 本地部署无需 API Key
```

### 可选配置项

```bash
# RAG 桥接（可选）
RAG_BRIDGE_ENABLED=false
KB_MVP_URL=http://localhost:8000

# 相似度阈值
SIMILARITY_THRESHOLD=0.35
TOP_K=5

# 日志级别
LOG_LEVEL=INFO
```

---

## 使用指南

界面采用左侧导航 + 右侧内容区的模块化布局，支持 **💬 问答 / 📄 文档 / 📖 词条 / 🔍 检查 / 🌐 图谱 / 🔄 去重 / 📝 日志 / ⚙️ 审计** 八大模块并行操作。

### 1. 智能问答

在问答模块输入问题，系统会自动按以下优先级回答：

1. 命中 Wiki 词条 → 基于词条生成答案
2. 命中 RAG 文档 → 基于文档生成答案（需启用 RAG 桥接）
3. 未命中 → 参数化兜底，并提示“是否生成正式词条？”

每个答案上方都会显示**来源卡片**，包含来源名称、类型、置信度与匹配度。点击词条类来源可侧边预览对应词条，点击文档类来源可查看原文。

![智能问答界面](docs/screenshots/01-chat.png)

> 图中左侧为会话列表，右侧消息区展示回答与来源卡片。来源卡片可点击跳转到对应词条或文档。

---

### 2. 文档管理

#### 上传文档

- 支持 **PDF / Word / TXT / Markdown** 四种格式。
- 上传后自动解析为结构化 blocks，保留页码与段落信息。

#### 生成/重新生成词条

每个文档卡片会显示**生成状态**：

- `○ 未生成`：尚未基于该文档生成词条，点击“生成”创建。
- `✓ 已生成`：已生成对应词条，点击“重新生成”可更新，点击“查看词条”可预览。

文档状态自动与词条关联，删除文档时会级联删除其生成的词条，并清理其他词条中的引用。

![文档管理界面](docs/screenshots/02-docs.png)

> 文档列表展示生成状态、文件类型、页数、字数与词条入口。已生成词条支持“重新生成”或“查看词条”。

---

### 3. 词条管理

词条是系统的核心知识单元，包含：

- **标题**
- **摘要**
- **章节**（多级内容）
- **关键词**（用于检索与交叉引用）
- **相关主题**（`[[双向链接]]`）
- **来源文档**（doc_id）
- **审核状态**（auto_verified / verified / disputed）

#### 生成方式

1. **从主题生成**：输入主题，LLM 从参数化知识生成结构化百科词条。
2. **从文档生成**：选择文档，系统基于文档内容提取关键概念并生成词条。

生成过程采用 SSE 推送进度，右下角任务追踪器实时显示当前步骤。

![词条详情界面](docs/screenshots/03-wiki.png)

> 右侧展示词条摘要、章节、关键词与引用关系。支持人工审核（通过/争议/编辑）。

---

### 4. 知识图谱

基于词条正文中的 `[[双向链接]]` 构建知识图谱，可视化呈现：

- **节点**：每个词条
- **边**：词条之间的引用关系
- **社区检测**：不同颜色表示不同知识社区
- **枢纽节点**：被大量引用的核心词条
- **孤立节点**：未被链接的词条
- **悬空链接**：指向不存在的词条的引用

![知识图谱界面](docs/screenshots/04-graph.png)

> 图谱展示 5 个节点、3 条连接、1 个社区、1 个孤立节点，密度 30%。点击节点可预览词条，点击“问题发现”查看悬空链接。

---

### 5. Wiki 健康检查

点击“检查”模块的“运行检查”，系统会对所有词条进行 6 类诊断：

| 问题类型 | 说明 | 优先级 |
|----------|------|--------|
| 孤儿页面 | 没有被其他词条引用的孤立内容 | 中 |
| 悬空引用 | 引用了不存在的词条 | 高 |
| 内容矛盾 | 不同词条间存在相互矛盾的描述 | 高 |
| 过时内容 | 可能过时的信息 | 低 |
| 链接拼写错误 | `[[链接]]` 与已有词条标题近但不匹配 | 中 |
| 语义建议 | LLM 对内容结构、关联的优化建议 | 低 |

![Wiki 健康检查](docs/screenshots/05-lint.png)

> 检查结果按高/中/低优先级聚合，每类问题给出修复建议（如“创建 [LangChain使用指南] 词条或移除该引用”）。

---

### 6. 重复词条检测

系统通过两阶段算法检测重复或高度相似的词条：

1. **倒排索引粗筛**：快速找出共享关键词的候选对。
2. **LLM 精排**：由 LLM 判断内容是否真正重复。

检测完成后，可对重复词条执行**合并操作**：保留一个词条，将被合并词条的内容（章节、关键词、相关主题）并入，并自动转移反向链接与引用关系。

![重复词条检测](docs/screenshots/06-dedup.png)

> 当前示例中未检测到重复词条。若检测到重复候选，每对会提供“保留 A 删 B”或“保留 B 删 A”的合并按钮。

---

### 7. LLM 调用审计

审计模块记录每一次 LLM 调用，帮助分析成本、排查问题：

- 总调用数、错误率、平均耗时、总 Token 数
- 按操作类型分布（Wiki 问答、RAG 问答、生成、检查、去重、补全等）
- 每条调用记录可展开查看：
  - 会话 ID
  - 用户问题
  - 耗时（ms）
  - 输入 / 输出 Token 估算
  - 状态与错误信息
  - 完整 Prompt 与 Response

![LLM 调用审计](docs/screenshots/07-audit.png)

> 审计面板展示 43 次总调用、0% 错误率、平均 6468ms 耗时、总 Token 44808。点击单条可展开查看会话、问题、Prompt 与 Response。

---

## 系统架构

### 三层降级问答

```
用户提问
    │
    ▼
Layer 2: 检索 Wiki 词条库
    ├── 命中（相似度 >= 0.35 或关键词强命中）→ 基于词条生成答案
    │
    └── 未命中 ↓
         │
         ▼
Layer 3: 检索 RAG 知识库（如启用）
    ├── 命中 → 基于文档生成答案
    │
    └── 未命中 ↓
         │
         ▼
Layer 1: 参数化兜底
    └── LLM 直接从参数知识回答
        标注「[参数化知识]」
        提示「是否生成正式词条？」
```

### 审核流程

```
词条生成 → auto_verified（自动验证，默认可用）
    │
    ├── 用户发现错误 → 标记 disputed（有争议）→ 需人工介入
    │
    └── 人工确认 → verified（已确认，最高可信度）
         或 人工编辑 → human_curated + verified
```

### 异步架构

| 层 | 异步方案 |
|----|----------|
| LLM 调用 | `AsyncOpenAI` 原生异步流式 |
| Embedding | `AsyncOpenAI` / `asyncio.to_thread`（DashScope） |
| 文件 I/O | 大文件 `asyncio.to_thread`，小文件直接读取 |
| 文档解析 | `asyncio.to_thread`（PyMuPDF / python-docx） |
| RAG 检索 | `httpx.AsyncClient` 原生异步 |
| 并发保护 | `asyncio.Lock` 保护向量库写入 |

---

## API 接口

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/documents/upload` | 上传文档 |
| GET | `/api/documents` | 文档列表 |
| GET | `/api/documents/{doc_id}` | 文档详情 |
| DELETE | `/api/documents/{doc_id}` | 删除文档及关联词条 |
| POST | `/api/wiki/generate-from-topic` | 从主题生成词条（SSE） |
| POST | `/api/wiki/generate-from-doc` | 从文档生成词条（SSE） |
| GET | `/api/wiki/list` | 词条列表 |
| GET | `/api/wiki/{title}` | 词条详情 |
| DELETE | `/api/wiki/{title}` | 删除词条及清理引用 |
| POST | `/api/wiki/{title}/review` | 审核词条 |
| POST | `/api/wiki/dedup` | 检测重复词条 |
| POST | `/api/wiki/dedup/merge` | 合并重复词条 |
| POST | `/api/wiki/lint` | 运行 Wiki 健康检查 |
| POST | `/api/ask` | 智能问答（SSE 流式） |
| GET | `/api/models` | 当前模型配置 |
| GET | `/api/log` | 操作日志 |
| GET | `/api/audit` | LLM 调用审计日志 |

完整 API 文档：http://127.0.0.1:8889/docs

---

## 常见问题

### Q1: 启动时报错 `ModuleNotFoundError: No module named 'xxx'`

确认已激活虚拟环境并执行：

```bash
pip install -r requirements.txt
```

部分依赖（如 PyMuPDF）需要正确安装 Visual C++ 运行时（Windows）。

### Q2: LLM 调用返回超时或错误

检查 `.env` 中：

- `LLM_API_KEY` 是否有效且未过期
- `LLM_BASE_URL` 是否正确（DeepSeek 为 `https://api.deepseek.com`）
- 网络是否能访问对应 API
- 若使用 Ollama，确认本地服务已启动

### Q3: 相似度阈值如何调整？

编辑 `.env`：

```bash
SIMILARITY_THRESHOLD=0.35   # 阈值越低，召回越多；越高，精度越高
TOP_K=5                     # 返回候选词条数
```

### Q4: 删除文档或词条后，图谱中仍有孤立节点或悬空链接？

删除操作会清理 backlinks 与正文中的 `[[链接]]`。清理后请刷新图谱页面，或在“图谱”模块点击“重建反向链接”同步。

### Q5: 是否支持多用户并发？

支持。后端采用 FastAPI 全异步架构，文件写入使用 `asyncio.Lock` 保护向量库，会话隔离通过 session_id 实现。当前版本为单文件持久化，适合个人或小团队使用。

### Q6: 如何接入自有 RAG 知识库？

在 `.env` 中启用：

```bash
RAG_BRIDGE_ENABLED=true
KB_MVP_URL=http://localhost:8000
```

系统将在 Wiki 未命中时，把查询转发到 KB-MVP 服务。

---

## 贡献指南

欢迎提交 Issue 和 PR！在贡献之前，请阅读以下规范。

### 提交 Issue

- 使用中文或英文描述问题
- 提供复现步骤、期望行为与实际行为
- 附上相关日志或截图

### 提交 PR

1. Fork 本仓库
2. 创建功能分支：`git checkout -b feature/your-feature-name`
3. 编写代码，确保通过 Python 语法检查
4. 提交更改：`git commit -m "feat: your description"`
5. 推送分支：`git push origin feature/your-feature-name`
6. 发起 Pull Request

### 代码规范

- 使用 Python 3.10+ 类型注解
- 异步函数优先使用 `async/await`
- 文件写入必须通过 `wiki_safe_io` 的原子写入接口
- 新增 API 需在 `api.py` 注册，并在 `README.md` 更新接口表
- 前端改动为单文件 `static/wiki.html`，保持零构建

### 开发调试

```bash
# 启动开发模式（自动重载，可选）
uvicorn app.main:app --host 0.0.0.0 --port 8889 --reload
```

---

## 相关项目

**KB-MVP** 是本项目的姊妹项目——一个轻量级私有 RAG 知识库问答系统，支持文档上传、分块向量化、答案引用溯源与高亮定位。LLM Wiki 可通过 RAG 桥接与其配合使用，实现「Wiki 词条优先 → RAG 文档 → 参数化兜底」的完整问答链路。

- [GitHub 仓库](https://github.com/your-username/kb-mvp)
- [Gitee 仓库](https://gitee.com/mengl248/kb-mvp)

---

## License

[MIT](LICENSE)

---

> 如果你在使用过程中遇到问题，欢迎提交 Issue。如需 RAG 知识库问答能力，可搭配上方的 [KB-MVP](#相关项目) 项目使用。