本地私有知识库搭建：MCP + pgvector + TRAE 实时检索全攻略

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

熟悉我的人都知道，我最近一直在折腾本地知识库，倒不是嫌云端方案不好，而是手里有一堆技术文档、项目笔记和内部规范，实在不方便传到第三方服务上做向量化检索。本地跑的方案试了不少，从最开始的纯文件检索到后来用 sqlite-vec，再到现在的 pgvector，踩了一圈坑之后，最终搭了一套"文档分块 → 向量化 → pgvector 入库 → TRAE 实时检索"的完整链路，也就是标题里写的这套东西。如果你是做技术写作、知识管理，或者纯粹想让 AI 编程工具（比如 TRAE、Cursor 这类）能直接回答你私有文档里的问题，那这篇文章值得花十分钟看完。

先说这个项目能解决什么问题。简单讲，它让 TRAE（字节出的 AI IDE）在聊天或写代码时，能通过 MCP 协议实时检索你本地的 PostgreSQL 数据库里存好的文档向量，然后基于检索结果回答你的问题。整个过程完全本地化，数据不出机器，文档更新后重新分块入库即可，不需要训练模型，也不依赖任何第三方知识库 API。

再说适合谁来参考。我默认你有基本的 Python 和 SQL 基础，知道什么是 Embedding、什么是向量数据库。如果你连这些概念都还没摸清楚，也没关系，我在文章里会用比较直白的话解释每一步在干什么。这套方案的最终效果是：你在 TRAE 里输入"我们项目的部署文档里关于环境变量配置写了什么"，它能直接基于你的私有文档给出带上下文的回答，而不是瞎编。

1. 内容整体设计与思路拆解

1.1 为什么选 MCP + pgvector + TRAE 这个组合

MCP（Model Context Protocol）是 Anthropic 在 2024 年底推出来的一个开放协议，通俗地说，它给 AI 应用和外部工具之间定了一套"插头标准"。以前你想让 AI 读数据库、查文件、调接口，每个工具都要单独开发对接方式，现在只要工具方实现一个 MCP Server，任何支持 MCP 的客户端（TRAE、Claude Desktop、Cursor 等）都能直接连上。这个"一次实现、到处复用"的特性，是我选它做知识库接口的核心原因。

pgvector 是 PostgreSQL 的向量检索扩展，它最大的优势是"不引入新组件"。很多团队本来就在用 PostgreSQL 存业务数据，装上 pgvector 之后，同一个数据库里既能存普通关系数据，又能存向量数据，事务、备份、权限体系全部复用。对比专门的向量数据库（比如 Milvus、Qdrant），pgvector 在小规模知识库场景下的性价比非常高，数据量在百万条向量以下时性能完全够用。

TRAE 这边，它原生支持 MCP 插件机制，配置一个 JSON 文件就能连上自建的 MCP Server，不需要写任何插件代码。这一点比在 Cursor 里折腾自定义工具要省事很多。把这三个东西串起来，得到的是一条"文档管理在 PostgreSQL、语义检索在本地、AI 问答在 TRAE"的干净链路。

1.2 核心链路拆解：分块、向量化、入库、检索四步走

整套系统可以抽象成四个环节：文档分块（Chunking）、向量化（Embedding）、向量入库（Ingestion）、实时检索（Retrieval）。

文档分块解决的是"长文档怎么切"的问题。直接拿整篇文档去生成向量，效果通常很差，因为 Embedding 模型对输入长度有限制，而且太长的一段话里包含多个主题，向量会被"平均"得面目全非。分块策略直接决定了检索质量的上限。

向量化解决的是"文本怎么变成数字"的问题。我们会用 Embedding 模型把每一段文本转换成一个高维向量（比如 768 维或 1536 维），语义相近的文本在向量空间里的距离也近。这一步是整个链路里唯一需要模型推理的地方，所以一般都建议本地跑小模型，或者调用 API。

向量入库解决的是"向量存到哪里、怎么查得快"的问题。pgvector 提供 vector 数据类型和 IVFFlat、HNSW 两种索引，我们把分块文本和它的向量一起写入 PostgreSQL，然后建好索引，等检索时用余弦距离或欧氏距离做相似度搜索。

实时检索解决的是"用户在 TRAE 里怎么用"的问题。我们会写一个 MCP Server，向外暴露一个 search_knowledge 工具，TRAE 收到用户提问后，调用这个工具，把问题转成向量，去数据库里搜出最相关的几段文本，再连同上下文一起交给大模型生成回答。

这四个环节环环相扣，任何一个环节出了问题，后面全白搭。下面我按顺序拆开讲。

2. 环境准备与基础工具安装

2.1 PostgreSQL 安装与 pgvector 扩展部署

我测试时用的是 PostgreSQL 14.24.2 + pgvector 0.7.x，这两个版本在 Windows 和 Linux 下都验证过。如果你用的是 macOS，Homebrew 装 postgresql@14 然后 brew install pgvector 也能搞定，但下面我以 Windows 为主讲一遍，因为问这个问题的多半是 Windows 用户。

bash复制# 如果已经装了 PostgreSQL，只是缺 pgvector，直接执行：
cd /tmp
git clone --branch v0.7.4 https://github.com/pgvector/pgvector.git
cd pgvector
make
make install

Windows 用户一般没有 make 环境，偷懒的方式是用 PostgreSQL 官方安装包附带的 Stack Builder，或者直接用别人编译好的安装包。更推荐的做法是去找跟你的 PostgreSQL 大版本号匹配的 pgvector 预编译包，比如 `pgvect