从零搭建私有知识库 MCP：文档分块 → 向量化 → pgvector 入库 → TRAE 实时检索

从零搭建私有知识库 MCP：文档分块 → 向量化 → pgvector 入库 → TRAE 实时检索（以若依文档为例）

背景：用 TRAE / Cursor 写项目时，经常会问 AI“某个框架怎么配置”“某个功能怎么实现”，但 AI 给的答案往往基于通用知识，不一定符合你实际在用的框架版本、项目约定和团队规范。

解决方案：把框架文档通过 RAG 链路变成 AI 可实时检索的私有知识库，通过 MCP 协议接入 TRAE，让 AI 每次回答都基于你本地的真实文档。

本文技术栈：MinerU 在线版 + Python + PostgreSQL / pgvector + 硅基流动 Embedding API + Python MCP Server

完成后效果：在 TRAE 里提问时，AI 会先检索你的知识库，再基于命中的文档原文回答。对常见配置类、功能类、权限类问题，命中效果通常比较稳定。

说明：本文讲的是一套通用的私有知识库搭建方法，若依只是演示案例。你可以把它替换成任意框架文档、内部规范文档、组件库文档或业务资料。

如果你也遇到过下面这些情况，这篇文章基本就是给你写的：

• AI 能写代码，但一问到具体框架配置、权限控制、代码生成细节就开始“凭印象回答”
• 团队有自己的开发规范或内部文档，希望 AI 回答时优先参考本地资料
• 不想一开始就折腾本地大模型，只想先把“文档可检索”这件事跑通

读完你会得到 3 个明确结果：

• 知道为什么 PDF / 网页文档最好先转 Markdown，再做向量化
• 能独立把任意一套文档做成 PostgreSQL + pgvector 的本地知识库
• 能把检索能力通过 MCP 接进 TRAE，让 AI 在聊天时自动查文档再回答

---

一、整体思路：RAG + MCP 是什么

很多人搞混这两个概念，先说清楚：

RAG（Retrieval-Augmented Generation，检索增强生成）：不是让 AI 背下所有文档，而是在 AI 回答之前，先去知识库里"查一查"，找到最相关的段落，再让 AI 基于这些段落回答。这样既准确，又能随时更新文档。

MCP（Model Context Protocol）：Anthropic 提出的开放协议，相当于 AI 世界的"USB 接口标准"。有了 MCP，TRAE 里的 AI 可以调用任何外部工具——我们把“查文档”做成一个 MCP 工具，AI 判断需要时自动调用。

两者的关系：RAG 负责"怎么查得准"，MCP 负责"怎么让 AI 用上这个查询能力"。

完整数据流：

PDF / 网页文档
       │
       │  【第一步】MinerU 在线版解析
       ▼
Markdown 文件（结构化纯文本）
       │
       │  【第二步】01_chunk_docs.py  按标题分块
       ▼
data/chunks.json（130 个文本块）
       │
       │  【第三步】02_init_db.py  建表 + HNSW 索引
       ▼
PostgreSQL ruoyi_rag 库（doc_chunks 表）
       │
       │  【第四步】03_embed_and_store.py  调硅基流动 API 向量化 + 入库
       ▼
doc_chunks：每行 = 文本块 + 1024 维向量
       │
       │  【第五步】src/mcp_server.py  MCP 服务
       ▼
Python MCP Server（暴露 search_ruoyi_docs 工具）
       │
       │  【第六步】注册到 ~/.trae/mcp.json
       ▼
TRAE AI 实时语义检索你的本地文档

如果你只想先判断这套方案值不值得做，可以先看一句话结论：它不是让 AI “记住某份文档”，而是让 AI 在回答前先查你自己的文档，再基于原文回答。对开发场景来说，这往往比单纯换一个更强的模型更实用。

---

二、环境准备

说明：本文以 macOS + Python 3 + PostgreSQL 17 为演示环境，Windows / Linux 的整体步骤完全一致，主要差异在命令路径和安装方式。

Python 依赖

pip3 install psycopg2-binary requests mcp

库	用途
psycopg2-binary	连接 PostgreSQL
requests	调用硅基流动 Embedding API
mcp	实现 MCP Server 协议

无需安装 PyTorch 或任何本地模型，向量化完全通过硅基流动 API 完成，本机只需 Python 标准环境。

PostgreSQL + pgvector

PGSQL安装好以后，pgvector插件一定要记得安装。

硅基流动 API Key

登录 硅基流动 → 控制台 → API Keys，创建一个 Key，脚本中会用到。

本文使用 BAAI/bge-m3 模型，维度 1024，中文效果优秀，免费额度充足。

项目目录

mkdir -p ~/Desktop/demo/ruoyi-mcp-server/{scripts,src,data}
cd ~/Desktop/demo/ruoyi-mcp-server

---

三、第一步：准备 Markdown 文档（MinerU 在线版）

为什么必须是 Markdown，不能直接用 PDF？

这是 RAG 质量的基础，非常关键。

格式	问题
PDF	二进制格式，提取文字后换行错乱、代码块被拆散，无法识别章节边界
HTML	充满 <div> <span> 等标签噪音，干扰向量语义
Markdown	纯文本，## 标题天然是语义边界，代码块完整保留，AI 原生可读

核心逻辑：Markdown 的 ## 标题就是分块的天然切割线。## 多数据源配置 这一块切出来后，标题和内容都在同一个 Chunk 里，向量化后这个块的语义会非常贴近"若依多数据源配置"，用户问相关问题时更容易检索到它。

使用 MinerU 在线版转换

MinerU 在线版 是阿里巴巴提供的免费在线 PDF 解析服务，无需本地安装，直接上传 PDF 就能获得高质量 Markdown。

操作步骤：

1. 打开 https://mineru.net，登录账号（支持微信/邮箱注册）
2. 点击「上传文件」，上传若依框架的 PDF 文档
3. 等待解析完成（通常 1~3 分钟）
4. 点击「下载」→ 选择 Markdown 格式
5. 将下载的 .md 文件放入 ~/Desktop/demo/ruoyi/ 目录

本文已完成转换，文档来自 W3CSchool 若依在线文档，转换后共 5 个文件：

demo/ruoyi/
├── MinerU_markdown_后台手册_w3cschool_xxx.md    （1503 行）
├── MinerU_markdown_前端手册_w3cschool_xxx.md    （603 行）
├── MinerU_markdown_快速了解_w3cschool_xxx.md    （141 行）
├── MinerU_markdown_环境部署_w3cschool_xxx.md    （131 行）
└── MinerU_markdown_项目介绍_w3cschool_xxx.md

质量核查：打开 Markdown 文件，确认标题层级（# ## ###）正确，代码块完整，中文无乱码。这直接影响后续分块质量。

---

四、第二步：文本分块（Chunking）

为什么要分块？

向量化模型有长度限制，更重要的是，检索时返回的是整个 Chunk 作为上下文——Chunk 太长，大模型的上下文窗口装不下，且主题稀释导致检索不准。

本项目分块策略（按优先级）：

1. 以 # ## ### 标题为边界切割，每个标题对应一个块
2. 超过 800 字的块继续切割：
   • 纯 Markdown 表格（| 开头行超过 60%）→ 保留表头，每 20 行数据一组
   • 有段落分隔（双换行）→ 按段落切割，相邻块保留 1 段 overlap（重叠）防止信息断裂
   • 其他密集内容 → 按 40 行分组
3. 低于 40 字的块直接丢弃

overlap（重叠）的作用：相邻两块共享一个段落，避免关键信息恰好落在切割线上被拆散到两个块里。

运行脚本

打开 scripts/01_chunk_docs.py，找到顶部配置区域，只需确认 DOCS_DIR 路径正确：

# 指向你的 Markdown 文档目录
# 默认值是相对路径 ../../ruoyi，即项目同级的 ruoyi/ 文件夹
# 如果文档放在其他位置，改成绝对路径，例如：
# DOCS_DIR = "/Users/yourname/Documents/ruoyi-docs"
DOCS_DIR = os.path.join(os.path.dirname(__file__), "../../ruoyi")

确认路径正确后运行：

cd ~/Desktop/demo/ruoyi-mcp-server
python3 scripts/01_chunk_docs.py

预期输出：

找到 5 个 Markdown 文件，开始分块...

  [前端手册    ]  →   22 个块
  [后台手册    ]  →   30 个块
  [快速了解    ]  →    6 个块
  [环境部署    ]  →    6 个块
  [项目介绍    ]  →   66 个块

✅ 分块完成！总块数：130
   平均 368 字 / 最长 1387 字 / 最短 21 字
   输出：data/chunks.json

---

五、第三步：初始化数据库

为什么选 PostgreSQL + pgvector，而不是 ChromaDB？

方案	优点	缺点
ChromaDB	零配置，独立运行	与业务库割裂，不能 SQL 联查
Faiss	极快	纯内存，重启丢数据，无 SQL
PostgreSQL + pgvector	SQL 查询灵活，可与业务数据 JOIN	需安装 pgvector 扩展
Pinecone / Weaviate	云端全托管	收费，数据出境

而且电脑上已经安装了PGSQL，就直接用了。

关键概念：HNSW 索引

pgvector 0.5+ 支持 HNSW 索引，查询性能大幅优于之前的 IVFFlat：

索引	查询速度	精度	适用场景
HNSW	毫秒级	高	推荐，生产环境
IVFFlat	较慢	略低	数据量极大时

vector_cosine_ops 表示使用余弦相似度作为距离度量——只看向量方向，不受文本长短影响，适合语义检索。

运行脚本

打开 scripts/02_init_db.py，找到顶部配置区域。脚本支持环境变量优先，如果你已执行前面的 export，这里通常无需修改。如果你更习惯直接改源码，可重点确认 DB_CONFIG：

DB_CONFIG = {
    "host": os.getenv("PGHOST", "localhost"),
    "port": int(os.getenv("PGPORT", "5432")),
    "dbname": os.getenv("PGDATABASE", "ruoyi_rag"),
    "user": os.getenv("PGUSER", "your-pg-username"),
}
if os.getenv("PGPASSWORD"):
    DB_CONFIG["password"] = os.getenv("PGPASSWORD")

修改后运行：

python3 scripts/02_init_db.py

预期输出：

✅ 数据库初始化完成！
   pgvector 版本：0.8.1
   向量维度：1024
   doc_chunks 当前记录数：0

---

六、第四步：向量化并写入数据库

向量化原理

向量化（Embedding） 把文字转换成高维数字数组。语义相近的文字，向量在空间中的距离也近：

"若依如何配置多数据源"              →  [0.23, -0.41, 0.87, ...]  ← 1024 个数字
"application-druid.yml 数据源切换"  →  [0.21, -0.39, 0.85, ...]  ← 距离很近 ✓
"Bootstrap 表格初始化方法"           →  [-0.54, 0.12, -0.33, ...] ← 距离很远 ✗

检索时：把用户问题也向量化，在数据库中找余弦距离最小的那些块，就是最相关的内容。

硅基流动 BAAI/bge-m3

配置项	值
模型名	BAAI/bge-m3
向量维度	1024
语言支持	中英文双语，中文效果极佳
API 地址	https://api.siliconflow.cn/v1/embeddings
优势	无需本地 GPU，无需 PyTorch，纯 HTTP 调用，免费额度充足

运行脚本

打开 scripts/03_embed_and_store.py，脚本支持环境变量优先。如果你希望把配置写在源码里，再修改顶部配置区域：

# 推荐：环境变量优先
SILICONFLOW_API_KEY = os.getenv("SILICONFLOW_API_KEY", "your-siliconflow-api-key")

DB_CONFIG = {
    "host": os.getenv("PGHOST", "localhost"),
    "port": int(os.getenv("PGPORT", "5432")),
    "dbname": os.getenv("PGDATABASE", "ruoyi_rag"),
    "user": os.getenv("PGUSER", "your-pg-username"),
}
if os.getenv("PGPASSWORD"):
    DB_CONFIG["password"] = os.getenv("PGPASSWORD")

修改后运行：

python3 scripts/03_embed_and_store.py

预期输出：

📂 共 130 个 Chunk

🗄️  数据库已清空，开始写入...

   进度： 16 / 130  ( 12%)
   进度： 32 / 130  ( 24%)
   ...
   进度：130 / 130  (100%)

✅ 向量化入库完成！共写入 130 条记录

🔍 测试检索（查询：多数据源配置）...
   [项目介绍] 数据源配置  sim=0.753
   [后台手册] 多数据源    sim=0.667
   [后台手册] 多数据源    sim=0.663

验证入库效果

python3 scripts/04_inspect_db.py

脚本见 scripts/04_inspect_db.py。运行后显示库统计，可交互式输入检索词验证效果：

📊 数据库概览  总记录数：130

   后台手册         30 条
   项目介绍         66 条
   前端手册         22 条
   ...

🔍 输入检索词（直接回车退出）: Shiro权限控制

检索结果（Top 5）：
────────────────────────────────────────────────────────────
  [项目介绍] Shiro                相似度 0.7170
  [项目介绍] Shiro安全控制        相似度 0.6600
  [前端手册] 权限使用              相似度 0.6410
  ...

---

七、第五步：MCP Server

MCP 的工作方式

注册后，TRAE 每次启动会自动在后台拉起 MCP Server 进程，AI 需要查文档时自动调用：

用户问："若依怎么关掉登录验证码？"
    ↓
TRAE 判断：需要查询若依文档
    ↓
调用 MCP 工具 search_ruoyi_docs(query="关闭登录验证码")
    ↓
MCP Server 把问题向量化，查询 PostgreSQL 向量库
    ↓
返回 Top-5 相关文档块
    ↓
AI 基于文档原文给出准确回答

验证 Server 能正常启动

cd ~/Desktop/demo/ruoyi-mcp-server
python3 src/mcp_server.py
# 看到以下日志后 Ctrl+C 退出：
# WARNING:__main__:[ruoyi-docs MCP Server] 启动，等待 TRAE 连接...

脚本见 src/mcp_server.py。它也支持从环境变量读取 SILICONFLOW_API_KEY 和 DB_CONFIG，因此如果你已经按前文执行过 export，通常无需再改源码。

---

八、第六步：接入 TRAE

方法一：直接编辑配置文件

TRAE 的 MCP 全局配置文件位于 ~/.trae/mcp.json（注意全小写）。

如果文件不存在，先创建：

mkdir -p ~/.trae
touch ~/.trae/mcp.json

添加以下配置（已有其他 Server 只追加 ruoyi-docs 这一项）：

{
  "mcpServers": {
    "ruoyi-docs": {
      "command": "/absolute/path/to/python3，Python安装路径，配置了环境变量直接写python也行",
      "args": [
        "/absolute/path/to/ruoyi-mcp-server/src/mcp_server.py，mcp_server放的位置"
      ],
      "env": {
        "SILICONFLOW_API_KEY": "你的硅基流动 API Key",
        "PGHOST": "localhost",
        "PGPORT": "5432",
        "PGDATABASE": "ruoyi_rag，数据库名称",
        "PGUSER": "你的 PostgreSQL 用户名",
        "PGPASSWORD": "你的数据库密码"

      }
    }
  }
}

⚠️ 两处路径必须用绝对路径，不能用 ~：

• command：用 which python3 查找你的 Python 路径
• args[0]：填写 mcp_server.py 的绝对路径

macOS / Linux / Windows 都是同一个原则：不要照抄本文示例路径，替换成你自己机器上的实际绝对路径。

另外建议把 SILICONFLOW_API_KEY、PGHOST、PGUSER 等配置直接写进 env。原因很简单：TRAE 通常是图形界面启动的，不一定能继承你在终端里 export 的环境变量。把它们写进 mcp.json，MCP Server 启动时最稳。

查找 Python 路径：

which python3
# 输出示例：/Library/Frameworks/Python.framework/Versions/3.10/bin/python3

方法二：通过 TRAE 界面添加

TRAE → AI 面板 → 右上角齿轮图标 → MCP → 添加 MCP Servers → 手动输入配置

重启 TRAE，确认连接

完全退出 TRAE 再重新打开，进入 AI 面板 → 齿轮图标 → MCP，找到 ruoyi-docs：

• 🟢 Connected → 正常，可以使用
• 🔴 Error → 启动失败，在终端手动运行 python3 src/mcp_server.py 查看具体报错

---

九、验证效果

在 TRAE Chat 里直接用中文提问，AI 会自动调用工具检索文档再回答：

功能查询：

若依的代码生成功能怎么用？支持哪些数据库类型？

配置查询：

若依怎么关掉登录验证码？在哪个配置文件里改？

权限相关：

若依的按钮权限是怎么控制的？前端怎么判断用户是否有某个权限？

部署相关：

若依支持哪几种部署方式？jar 和 war 部署有什么区别？

Chat 里可以看到 AI 调用工具的完整过程：

正在使用工具 search_ruoyi_docs...
  查询："关闭登录验证码"

# 若依文档检索结果
查询：关闭登录验证码  命中：5 条

## 1. 验证码配置
> 来源：《后台手册》｜相似度：84.3%
（文档原文...）

---

根据若依框架文档，关闭验证码的方法是...

---

十、常见问题排查

1. psycopg2 安装失败

优先安装二进制包：

pip3 install psycopg2-binary

2. 查不到 vector 扩展

先执行：

psql -U 你的用户名 -d postgres \
  -c "SELECT name, default_version FROM pg_available_extensions WHERE name='vector';"

如果没有结果，说明你的 PostgreSQL 还没安装 pgvector。这时先补装扩展，再运行 scripts/02_init_db.py。

3. TRAE 里 ruoyi-docs 显示 Error

先在终端手动启动：

cd ~/Desktop/demo/ruoyi-mcp-server
python3 src/mcp_server.py

最常见的原因有 3 个：

• SILICONFLOW_API_KEY 没设置，或仍是占位值
• PostgreSQL 没启动，或 PGUSER / PGPASSWORD 配错
• ~/.trae/mcp.json 里填的 Python 路径、脚本路径不是绝对路径

如果你已经在终端里执行过 export，但 TRAE 里仍然报配置缺失，也别奇怪。很多桌面应用不会自动继承当前终端会话的环境变量，直接在脚本里面配置自己的数据库连接地址、用户名、密码等。

4. 检索效果不准

按顺序检查：

1. Markdown 转换质量是否足够好，标题层级是否正常
2. scripts/01_chunk_docs.py 的 DOCS_DIR 是否指向了正确目录
3. 是否已经重新执行 scripts/01_chunk_docs.py 和 scripts/03_embed_and_store.py
4. 提问时是否用了更明确的术语，例如“多数据源”“Shiro 权限”“代码生成”

5. 为什么不用 ChromaDB / Faiss / Pinecone？

本文不是说这些方案不好，而是这篇教程的目标是：尽量少引入新组件，让已有 PostgreSQL 环境的开发者最快跑通。如果你后续要做更大规模的知识库，再按团队场景替换底层向量存储即可。

---

十一、数据库结构

PostgreSQL 数据库结构：

数据库：ruoyi_rag
表：doc_chunks
  ├── id          TEXT          chunk_0000 / chunk_0001 ...
  ├── title       TEXT          来自 ## 标题
  ├── source      TEXT          来源文件名（后台手册 / 前端手册 ...）
  ├── content     TEXT          原始文本内容
  ├── char_count  INTEGER       字符数
  └── embedding   vector(1024)  向量（pgvector 类型）

索引：idx_doc_chunks_embedding（HNSW，余弦相似度）

---

十二、更新知识库

文档有更新，或需要补充团队自己的二次开发规范时：

cd ~/Desktop/demo/ruoyi-mcp-server

# 1. 把新 Markdown 文件放入 ruoyi/ 目录
# 2. 重新跑两个脚本即可
python3 scripts/01_chunk_docs.py        # 重新分块
python3 scripts/03_embed_and_store.py   # 重新向量化入库（自动清空旧数据）

无需重启 TRAE，MCP Server 每次检索实时查库，数据库更新后立即生效。

---

十三、扩展到任意框架文档

本套方案完全通用，适用于任何框架或业务文档（内部组件库、API 文档、业务规范等）：

步骤	操作
1	用 MinerU 在线版把文档转成 Markdown，放入新目录
2	修改 01_chunk_docs.py 顶部 DOCS_DIR 指向新目录
3	修改 02_init_db.py 和 03_embed_and_store.py 中 DB_CONFIG 的 dbname 换新库名
4	修改 mcp_server.py 中 Server 名称和工具描述
5	按顺序运行 4 个脚本
6	在 ~/.trae/mcp.json 中追加新条目

一套文档 = 一个数据库 = 一个 MCP Server 条目，团队成员各自配置 ~/.trae/mcp.json 即可共用同一套知识库服务。

---

写在最后

这套方案的关键，不在于“把 AI 训练得更聪明”，而在于把你团队真正依赖的文档，以结构化、可检索、可持续更新的方式接到 AI 身上。若依只是一个示例，你完全可以把它替换成公司内部规范、接口文档、前端组件库说明，甚至部署手册和排障手册。