LLM-Wiki 知识库搭建指南

本指南基于实际项目经验，记录如何用 VitePress 搭建一个维护友好、可扩展的 AI 知识库。内容覆盖从 LLM Wiki 理念理解、数据摄取、内容管理、自动化工作流到持续部署的完整链路。

什么是 LLM Wiki

LLM Wiki 是 Andrej Karpathy 提出的一种基于 LLM 的个人知识库构建模式，核心思想是：让 LLM Agent 增量式地构建和维护一个持久化的、结构化的 Markdown 文件集合。

与传统 RAG 的核心差异：

维度	传统 RAG	LLM Wiki
知识持久性	查询后丢弃，无积累	知识被编译并持续维护
交叉引用	查询时动态发现	已预先建立，随时可用
矛盾处理	每次查询可能得出不同结论	矛盾已被标注和解决
综合深度	受限于检索片段数量	反映所有已读内容的综合
查询延迟	检索 + 生成	直接搜索 wiki 页面 + 生成

本知识库（AIKB）正是 LLM Wiki 模式的一个实践实例。

整体流程概览

三层架构：

原始数据层：用户精心策划的源文档集合（论文、文章、图片、数据文件），不可变
Wiki 层：由 LLM/人工生成的 Markdown 文件目录，包含实体、概念、比较、指南页面
Schema 层：配置文件定义 wiki 的结构、约定、工作流

第一步：数据摄取（Ingest）

摄取流程

将新数据源加入知识库的标准流程：

1. 阅读源文档 → 提取关键要点
2. 判断需要新增还是更新现有页面
3. 编写/更新 wiki 页面
4. 更新相关页面的交叉引用
5. 更新分类索引页
6. 更新首页统计
7. 记录摄取日志

内容分类决策

同一个信息可以归入不同类型，根据焦点决定：

信息焦点	归类	示例
谁做了什么	实体	OpenAI 发布 GPT-4o
原理是什么	概念	Transformer 架构详解
该选哪个	比较	GPT-4o vs Claude vs Gemini
怎么做	指南	搭建 RAG 系统步骤

一个源可能触及 10-15 个 wiki 页面。可以逐一手动监督摄取，也可以批量无监督摄取。

实际操作示例

以"添加 DeepSeek-R1 相关内容"为例：

1. 阅读 DeepSeek-R1 技术报告
2. 新增/更新实体页面: [[deepseek]]
3. 新增概念页面: [[grpo]]（如果尚不存在）
4. 更新比较页面: [[reasoning-models-comparison]]
5. 更新实体索引: wiki/entities/index.md
6. 更新首页统计: wiki/index.md
7. 记录日志: schema/log.md

第二步：选择静态站点生成器

方案对比

方案	优势	劣势	适用场景
VitePress	极速、Vue 生态、可定制	需要一定前端知识	技术团队、需要定制化
Docusaurus	React 生态、插件丰富	构建较慢、体积较大	React 团队、需要 blog 功能
MkDocs	极简、Python 生态	定制能力有限	简单文档、非前端团队
Notion / 语雀	无需部署、即时协作	定制受限、数据锁定	个人笔记、小团队
自研	完全可控	开发成本高	大规模、特殊需求

推荐 VitePress：

静态生成，极快加载
Markdown 原生支持，内容编写无门槛
Vue 扩展，可定制 wikilink、自定义提示等组件
内置搜索（基于 minisearch）

第三步：架构设计

目录结构

页面结构规范

每个 Markdown 文件必须包含：

markdown

---
title: 页面标题
description: 页面描述（用于 SEO 和搜索）
created: YYYY-MM-DD
updated: YYYY-MM-DD
type: entity | concept | comparison | guide
tags: [tag1, tag2]
confidence: high | medium | low
---

# 页面标题

> 引言：用一段话概括页面核心内容

## 正文结构
...

## 相关页面
- related-page-1 — 简短描述
- related-page-2 — 简短描述

## 参考来源
- Author (Year). "Title." Source.

关键规范：

frontmatter title 和 H1 # Title 必须同时存在且内容匹配
description 控制在 160 字符以内，用于搜索结果展示
type 字段用于后续筛选和统计
相关页面部分建立页面间的知识网状结构

Wikilink 系统

实现 page-slug 语法，自动解析为链接：

typescript

// .vitepress/theme/wikilinks.ts
const wikilinks: Record<string, { section: string; title: string }> = {
  'transformer': { section: 'concepts', title: 'Transformer' },
  'openai':      { section: 'entities', title: 'OpenAI' },
  'rag-vs-long-context': { section: 'comparisons', title: 'RAG vs Long Context' },
  'rag-system-guide':    { section: 'guides',    title: 'RAG 系统搭建入门指南' },
}

实现要点：

使用 Markdown-it 插件在渲染时替换 ... 为链接
无匹配的 wikilink 保持原样，避免链接断裂
支持自定义标题：自定义标题

第四步：内容管理工作流

批量创建流程

新增页面需要同步更新 5 个位置：

1. 页面本身     → wiki/{section}/page-slug.md
2. Wikilink 映射  → .vitepress/theme/wikilinks.ts
3. Sidebar 配置   → .vitepress/config.mts
4. 分类索引页    → wiki/{section}/index.md
5. 首页统计      → wiki/index.md

建议：一次性批量创建多个页面，然后统一部署，避免频繁构建。

内容质量控制

检查项	标准	工具
标题完整性	frontmatter + H1 必须存在	手动检查
链接有效性	无死链、无断链	`vitepress build` 报错
格式一致性	标点、空行、排版统一	Prettier / markdownlint
术语翻译	中英文术语统一	术语表
信息准确性	数据、日期、人名核实	交叉验证

版本控制策略

第五步：构建与部署

构建脚本

bash

#!/bin/bash
# scripts/build-and-deploy.sh

set -e

echo "=== Building VitePress site ==="
npm run build

echo "=== Deploying to nginx web root ==="
sudo cp -r .vitepress/dist/* /usr/local/nginx/html/

echo "=== Done ==="
echo "Site deployed to https://your-domain.com"

CI/CD 配置

建议使用 GitHub Actions 自动化：

yaml

# .github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run build
      - name: Deploy to server
        run: |
          rsync -avz --delete .vitepress/dist/ user@server:/usr/local/nginx/html/

或本地定时部署（如果使用自建服务器）：

bash

# 添加到 crontab，每日自动构建
0 3 * * * cd /path/to/aikb && bash scripts/build-and-deploy.sh >> /var/log/aikb-deploy.log 2>&1

nginx 配置示例

nginx

server {
    listen 80;
    server_name ai.pinkoculture.com;
    
    root /usr/local/nginx/html;
    index index.html;
    
    # 静态资源缓存
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
    
    # 单页应用路由
    location / {
        try_files $uri $uri/ /index.html;
    }
    
    # 压缩
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml;
}

扩展功能

搜索优化

VitePress 内置搜索基于 minisearch，可通过配置优化：

typescript

// .vitepress/config.mts
export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local',
      options: {
        miniSearch: {
          options: {
            // 搜索字段权重
            fields: ['title', 'titles', 'text'],
            storeFields: ['title', 'titles'],
          },
        },
      },
    },
  },
})

自定义组件示例

知识卡片组件：

vue

<!-- .vitepress/theme/components/InfoCard.vue -->
<template>
  <div class="info-card" :class="type">
    <div class="title">{{ title }}</div>
    <div class="content"><slot /></div>
  </div>
</template>

使用：

markdown

:::info 关键洞察
这是一个重要的发现...
:::

分析与统计

可通过脚本自动生成统计信息：

bash

# 统计页面数量
find wiki -name "*.md" | wc -l

# 统计各分类数量
find wiki/entities -name "*.md" | wc -l
find wiki/concepts -name "*.md" | wc -l
find wiki/comparisons -name "*.md" | wc -l
find wiki/guides -name "*.md" | wc -l

# 检查无效 wikilink
node scripts/check-wikilinks.js

常见问题

构建失败

问题：vitepress build 报错

解决：

检查 Markdown 语法（特别是 frontmatter）
确认所有 wikilink 在映射表中定义
检查自定义组件的导入路径

搜索不工作

问题：本地搜索无结果

解决：

确认 themeConfig.search.provider 设置为 'local'
检查是否有 exclude 配置过滤了目标页面
清除浏览器缓存重试

部署后样式丢失

问题：CSS 或 JS 未加载

解决：

检查 base 配置是否与部署路径匹配
确认 nginx 正确配置静态资源缓存
检查文件权限

与其他类型页面的关联

指南页面不应独立存在，而应与知识库的其他部分形成网状关联：

指南页面	关联实体	关联概念	关联比较
本指南	vitepress	LLM Wiki	—
RAG 系统搭建入门指南	—	Retrieval Augmented Generation	RAG vs Long Context
AI Agent 开发入门指南	—	AI Agents	Workflow vs Agent

关联原则：

指南引用实体："这个工具由 OpenAI 提供"
指南引用概念："本指南基于 Transformer Architecture 架构"
指南引用比较："具体选型参见推理框架深度对比"
概念引用指南："实践方面参见 RAG 系统搭建入门指南"

参考资源

Karpathy, A. (2026). LLM Wiki: A pattern for building personal knowledge bases using LLMs. GitHub Gist. https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f
VitePress 官方文档
Markdown 语法指南
Vue 3 组件开发

LLM-Wiki 知识库搭建指南 ​

什么是 LLM Wiki ​

整体流程概览 ​

第一步：数据摄取（Ingest） ​

摄取流程 ​

内容分类决策 ​

实际操作示例 ​

第二步：选择静态站点生成器 ​

方案对比 ​

第三步：架构设计 ​

目录结构 ​

页面结构规范 ​

Wikilink 系统 ​

第四步：内容管理工作流 ​

批量创建流程 ​

内容质量控制 ​

版本控制策略 ​

第五步：构建与部署 ​

构建脚本 ​

CI/CD 配置 ​

nginx 配置示例 ​

扩展功能 ​

搜索优化 ​

自定义组件示例 ​

分析与统计 ​

常见问题 ​

构建失败 ​

搜索不工作 ​

部署后样式丢失 ​

与其他类型页面的关联 ​

相关页面 ​

参考资源 ​

LLM-Wiki 知识库搭建指南

什么是 LLM Wiki

整体流程概览

第一步：数据摄取（Ingest）

摄取流程

内容分类决策

实际操作示例

第二步：选择静态站点生成器

方案对比

第三步：架构设计

目录结构

页面结构规范

Wikilink 系统

第四步：内容管理工作流

批量创建流程

内容质量控制

版本控制策略

第五步：构建与部署

构建脚本

CI/CD 配置

nginx 配置示例

扩展功能

搜索优化

自定义组件示例

分析与统计

常见问题

构建失败

搜索不工作

部署后样式丢失

与其他类型页面的关联

相关页面

参考资源