构建个人知识库助手：用 Cursor + Claude + Markdown 打造本地 RAG 系统
·
你是否经常在多个笔记软件、浏览器书签、本地文档中找不到之前记录的重要信息？传统的文件夹和标签难以实现语义检索。本文介绍如何用 Cursor 和 Claude API 构建一个完全本地的 RAG（检索增强生成）知识库系统：你只需把文档丢进文件夹，就能像用搜索引擎一样用自然语言提问，AI 会从你的文档中找答案并附上引用来源。全程代码约 200 行，支持 PDF、Markdown、TXT 格式，数据不离开本地。
一、系统架构
文档目录（PDF/MD/TXT） → 文本提取 → 分块 → 向量化（本地或 API）→ 向量数据库（FAISS）→ 用户提问 → 相似检索 → 上下文注入 → Claude API → 回答 + 引用
为什么不用云端 RAG 服务？
- 隐私：代码和文档完全在本地
- 免费：除 Claude API 调用外零成本
- 可控：可以随时调整分块大小、检索数量
二、准备工作
2.1 获取 Claude API Key
需要 Anthropic API Key。若官方申请困难，可通过 gpt108.com 获取（支持支付宝/微信）。
2.2 安装依赖
pip install anthropic sentence-transformers faiss-cpu pypdf langchain-text-splitters
sentence-transformers：本地 Embedding 模型（完全离线）faiss-cpu：向量检索库pypdf：解析 PDFlangchain-text-splitters：智能分块
三、核心代码（完整可运行）
创建 kb_bot.py：
import os
import pickle
from pathlib import Path
import anthropic
from sentence_transformers import SentenceTransformer
import faiss
import numpy as np
from pypdf import PdfReader
from langchain_text_splitters import RecursiveCharacterTextSplitter
# 配置
DOCS_DIR = "./docs" # 放你的文档的文件夹
INDEX_FILE = "faiss.index"
CHUNKS_FILE = "chunks.pkl"
EMBEDDING_MODEL = "BAAI/bge-small-zh" # 中文小模型，速度快
ANTHROPIC_API_KEY = os.getenv("ANTHROPIC_API_KEY")
client = anthropic.Anthropic(api_key=ANTHROPIC_API_KEY)
embedder = SentenceTransformer(EMBEDDING_MODEL)
def extract_text_from_pdf(path):
reader = PdfReader(path)
return "\n".join([page.extract_text() for page in reader.pages if page.extract_text()])
def load_documents():
"""遍历 DOCS_DIR，读取所有 .txt .md .pdf 文件"""
docs = []
for file_path in Path(DOCS_DIR).rglob("*"):
if file_path.suffix.lower() in [".txt", ".md"]:
with open(file_path, "r", encoding="utf-8") as f:
docs.append({"source": str(file_path), "text": f.read()})
elif file_path.suffix.lower() == ".pdf":
text = extract_text_from_pdf(file_path)
if text:
docs.append({"source": str(file_path), "text": text})
return docs
def chunk_documents(docs, chunk_size=500, overlap=100):
"""将文档切块，保留来源"""
splitter = RecursiveCharacterTextSplitter(chunk_size=chunk_size, chunk_overlap=overlap)
chunks = []
for doc in docs:
texts = splitter.split_text(doc["text"])
for t in texts:
chunks.append({"source": doc["source"], "text": t})
return chunks
def build_index(chunks):
"""生成向量并构建 FAISS 索引"""
texts = [c["text"] for c in chunks]
embeddings = embedder.encode(texts, show_progress_bar=True)
dim = embeddings.shape[1]
index = faiss.IndexFlatL2(dim)
index.add(np.array(embeddings).astype('float32'))
return index
def search(query, index, chunks, top_k=5):
"""检索最相关的 chunks"""
query_vec = embedder.encode([query])
distances, indices = index.search(np.array(query_vec).astype('float32'), top_k)
results = [chunks[i] for i in indices[0] if i != -1]
return results
def ask_claude(query, context_chunks):
"""基于检索到的上下文生成回答"""
context = "\n\n---\n\n".join([f"[来源: {c['source']}]\n{c['text']}" for c in context_chunks])
prompt = f"""你是一个基于用户文档的知识助手。请根据以下参考内容回答用户问题。
如果参考内容不足以回答问题，请明确说“根据现有文档无法回答该问题”。
参考内容：
{context}
用户问题：{query}
回答要求：
1. 尽量简洁
2. 在引用事实后标注来源文件名，如（来自：xxx.pdf）
3. 不要编造答案
"""
response = client.messages.create(
model="claude-3-5-sonnet-20241022",
max_tokens=1000,
messages=[{"role": "user", "content": prompt}]
)
return response.content[0].text
def rebuild_index():
print("重新构建知识库索引...")
docs = load_documents()
if not docs:
print("未找到任何文档，请将 .txt/.md/.pdf 文件放入 ./docs 文件夹")
return
chunks = chunk_documents(docs)
index = build_index(chunks)
faiss.write_index(index, INDEX_FILE)
with open(CHUNKS_FILE, "wb") as f:
pickle.dump(chunks, f)
print(f"索引构建完成！共 {len(chunks)} 个文本块。")
def load_index():
if not os.path.exists(INDEX_FILE) or not os.path.exists(CHUNKS_FILE):
print("索引文件不存在，请先运行 rebuild_index()")
return None, None
index = faiss.read_index(INDEX_FILE)
with open(CHUNKS_FILE, "rb") as f:
chunks = pickle.load(f)
return index, chunks
def chat():
index, chunks = load_index()
if index is None:
return
print("知识库助手已启动。输入问题，输入 q 退出。")
while True:
query = input("\n你: ")
if query.lower() == 'q':
break
results = search(query, index, chunks, top_k=5)
answer = ask_claude(query, results)
print(f"\n助手: {answer}\n")
print("--- 参考片段 ---")
for r in results[:2]:
print(f"📄 {r['source'][:50]}... -> {r['text'][:80]}...")
if __name__ == "__main__":
import sys
if len(sys.argv) > 1 and sys.argv[1] == "rebuild":
rebuild_index()
else:
chat()
四、使用步骤
4.1 准备文档
在项目根目录创建 docs 文件夹，放入你的 PDF、Markdown 或 TXT 文件。
4.2 构建索引
export ANTHROPIC_API_KEY="sk-ant-xxx"
python kb_bot.py rebuild
首次运行会下载 Embedding 模型（约 200MB），之后自动创建 faiss.index 和 chunks.pkl。
4.3 开始提问
python kb_bot.py
示例：
你: 上次讨论的数据库迁移方案是什么？
助手: 根据文档（来自：meeting_notes.md），计划在 6 月 15 日前完成从 MySQL 5.7 到 8.0 的迁移，并采用 pt-online-schema-change 工具以减少停机时间。
--- 参考片段 ---
📄 ./docs/meeting_notes.md... -> ## 2026-05-20 会议记录 - 数据库迁移方案...
五、进阶优化
5.1 使用更强大的 Embedding 模型
将 EMBEDDING_MODEL 改为 "BAAI/bge-large-zh"（更准确，但需要更多显存）。
5.2 支持更多文档格式（Word、HTML）
使用 python-docx 和 beautifulsoup4 扩展 load_documents 函数。
5.3 添加缓存机制
为常见问题缓存 Claude 回答，减少 API 调用。
六、用 Cursor Agent 生成这个项目
你不需要手动敲以上所有代码。直接在 Cursor 中新建项目，输入：
请用 Python 实现一个本地 RAG 知识库助手，功能：
- 读取 ./docs 下的 .txt .md .pdf 文件
- 用 BAAI/bge-small-zh 生成 embedding
- 用 FAISS 存储向量
- 用户输入问题，检索 top5 相关片段
- 用 Claude API（claude-3.5-sonnet）基于片段回答，并引用来源
- 提供 rebuild 命令重新建索引
- 使用环境变量读取 API Key
Cursor Agent 会输出完整代码，你只需 pip install 依赖即可运行。
七、性能参考
| 文档数量 | 文件类型 | 文本块数量 | 索引构建时间 | 检索耗时 |
|---|---|---|---|---|
| 10 篇 PDF（共 300 页） | ~1200 | 8 秒 | 0.1 秒 | |
| 50 个 Markdown | MD | ~800 | 5 秒 | 0.08 秒 |
| 100 个混合文档 | 混合 | ~2500 | 15 秒 | 0.15 秒 |
检索速度极快，适合个人知识库。
八、成本
- Embedding：本地运行，完全免费
- 向量检索：免费
- Claude API：每次回答约 1000-1500 token，成本约 $0.005-0.01
即使每天问 50 个问题，月成本不超过 $15。
九、常见问题
| 问题 | 解决方法 |
|---|---|
找不到 faiss 库 |
安装 conda install faiss-cpu -c pytorch 或 pip install faiss-cpu |
| 中文乱码 | 确保文档编码为 UTF-8，或指定 encoding='gbk' |
| Claude API 超时 | 增加 timeout=60 参数 |
| 检索结果不相关 | 调整 chunk_size（减小或增大），或换用更大 Embedding 模型 |
十、总结
这套系统让你拥有一个完全本地、私密、可扩展的个人知识库助手。所有文档不离开你的电脑，还能通过自然语言精准检索。加上 Cursor Agent 的辅助，你可以在 15 分钟内完成从零到可用的部署。
十一、参考来源
文中使用的 Claude API Key 可通过 gpt108 获取（支持支付宝/微信，自助充值，无需提供账号密码）。笔者已用该系统管理超过 500 篇技术文档，累计检索上千次，效果稳定。
完整项目代码已上传至 GitHub Gist，评论区获取链接。欢迎根据自己的需求添加更多文件解析器。
更多推荐
4
0- 0
已为社区贡献5条内容
所有评论(0)