Python从零搭建RAG应用：让AI读懂你的私有数据
大模型很强大，但它有个致命短板——不知道你公司内部的数据。问它"去年Q3的营收是多少"，它要么编一个，要么说"我不知道"。
RAG（Retrieval-Augmented Generation，检索增强生成）就是解决这个问题的。简单说，就是先从你的文档里找到相关内容，再让大模型基于这些内容来回答，大幅减少"瞎编"的概率。
这篇文章我会从零带你搭建一个完整的RAG应用，不用任何平台，纯Python实现，代码可以直接跑。
一、RAG原理（3分钟搞懂）
RAG的核心流程就4步：
用户提问 → 文档检索 → 拼接上下文 → 大模型生成回答
更具体地说：
- 文档预处理：把文档切成小段（chunk），每段生成向量（embedding）
- 向量化存储：把向量存进向量数据库（如FAISS、ChromaDB）
- 检索：用户提问时，把问题也转成向量，在向量数据库里找最相似的文档片段
- 生成：把检索到的片段 + 用户问题一起送给大模型，让它基于这些上下文回答
┌─────────┐ ┌──────────────┐ ┌─────────┐
│ 用户提问 │────→│ 向量检索(Top-K) │────→│ LLM生成 │
└─────────┘ └──────────────┘ └─────────┘
↑
┌──────────────┐
│ 向量数据库(FAISS) │
│ doc1_chunk1 │
│ doc1_chunk2 │
│ doc2_chunk1 │
│ ... │
└──────────────┘
二、环境准备（2分钟）
2.1 安装依赖
pip install openai chromadb faiss-cpu sentence-transformers numpy
各库的用途：
| 库 | 用途 |
|---|---|
openai | 调用GPT-4生成回答 |
chromadb | 向量数据库，存储和检索文档向量 |
faiss-cpu | Facebook开源的高效向量相似度搜索 |
sentence-transformers | 文本向量化模型 |
numpy | 数值计算 |
2.2 配置API
import os
from openai import OpenAI
# 方式1：直连OpenAI
client = OpenAI()
# 方式2：国内用户通过中转站访问（只需要改base_url，其他代码不变）
# client = OpenAI(
# base_url="https://your-relay-host.com/v1",
# api_key="your-api-key"
# )
💡 国内开发者：直连OpenAI API可能不太稳定，用中转站是比较省心的方案，把
base_url换成中转站地址就行，代码逻辑完全一样。
三、实战：从零搭建RAG（15分钟）
3.1 文档加载与切分
这是RAG最关键的一步——chunk质量直接决定检索质量。
from typing import List
def load_text_file(filepath: str) -> str:
"""读取文本文件"""
with open(filepath, 'r', encoding='utf-8') as f:
return f.read()
def split_text(text: str, chunk_size: int = 500, overlap: int = 50) -> List[str]:
"""
将文本按固定长度切分，带重叠区域
参数：
chunk_size: 每段最大字符数（建议300-800）
overlap: 相邻段重叠字符数（避免语义断裂）
"""
chunks = []
start = 0
while start < len(text):
end = start + chunk_size
chunk = text[start:end]
# 优化：尽量在句号/换行处切分
if end < len(text):
# 向前找最近的断句点
for sep in ['\n\n', '。', '！', '？', '\n', '；']:
last_sep = chunk.rfind(sep)
if last_sep > chunk_size * 0.5: # 至少保留一半长度
chunk = text[start:start + last_sep + len(sep)]
end = start + last_sep + len(sep)
break
chunks.append(chunk.strip())
start = end - overlap # 重叠区域
return [c for c in chunks if len(c) > 20] # 过滤空片段
切分策略选择：
| 策略 | 适用场景 | 优缺点 |
|---|---|---|
| 固定长度+重叠 | 通用 | 简单，但可能切断语义 |
| 按段落切分 | 结构化文档 | 语义完整，但段落可能过长 |
| 按语义切分 | 高质量需求 | 效果最好，但需要额外模型 |
| 递归切分 | 通用 | LangChain的默认方案，推荐 |
3.2 文本向量化
向量化就是把文字变成数字向量，让计算机能理解"语义相似度"。
from sentence_transformers import SentenceTransformer
import numpy as np
# 使用中文优化的向量模型
model = SentenceTransformer('shibing624/text2vec-base-chinese')
def get_embeddings(texts: List[str]) -> np.ndarray:
"""批量生成文本向量"""
embeddings = model.encode(texts, show_progress_bar=False)
return embeddings
def get_query_embedding(query: str) -> np.ndarray:
"""生成查询向量"""
return model.encode([query], show_progress_bar=False)[0]
# 测试
texts = ["Python是一种编程语言", "Java也是一种编程语言", "今天天气不错"]
vectors = get_embeddings(texts)
# 计算相似度
from numpy.linalg import norm
cos_sim = lambda a, b: np.dot(a, b) / (norm(a) * norm(b))
print(f"Python vs Java相似度: {cos_sim(vectors[0], vectors[1]):.4f}") # ~0.85
print(f"Python vs 天气相似度: {cos_sim(vectors[0], vectors[2]):.4f}") # ~0.15
3.3 构建向量数据库
用FAISS构建高性能向量索引：
import faiss
class VectorStore:
def __init__(self, dimension: int = 768):
self.dimension = dimension
self.index = faiss.IndexFlatIP(dimension) # 内积相似度
self.chunks = [] # 保存原始文本
def add_documents(self, chunks: List[str], embeddings: np.ndarray):
"""添加文档到向量库"""
# 归一化向量（内积=余弦相似度）
norms = np.linalg.norm(embeddings, axis=1, keepdims=True)
normalized = embeddings / norms
self.index.add(normalized.astype('float32'))
self.chunks.extend(chunks)
def search(self, query_embedding: np.ndarray, top_k: int = 3) -> List[dict]:
"""检索最相似的文档片段"""
query_norm = query_embedding / np.linalg.norm(query_embedding)
query_vec = query_norm.astype('float32').reshape(1, -1)
scores, indices = self.index.search(query_vec, top_k)
results = []
for score, idx in zip(scores[0], indices[0]):
if idx < len(self.chunks):
results.append({
'content': self.chunks[idx],
'score': float(score),
'index': int(idx)
})
return results
# 使用示例
store = VectorStore(dimension=768)
3.4 完整RAG管线
把上面所有组件串起来：
class RAGPipeline:
def __init__(self, llm_client, embedding_model_name='shibing624/text2vec-base-chinese'):
self.client = llm_client
self.embedding_model = SentenceTransformer(embedding_model_name)
self.vector_store = VectorStore(dimension=self.embedding_model.get_sentence_embedding_dimension())
def ingest_documents(self, file_paths: List[str], chunk_size: int = 500):
"""加载并索引文档"""
all_chunks = []
for path in file_paths:
text = load_text_file(path)
chunks = split_text(text, chunk_size=chunk_size)
all_chunks.extend(chunks)
# 批量向量化
embeddings = get_embeddings(all_chunks)
self.vector_store.add_documents(all_chunks, embeddings)
print(f"已索引 {len(all_chunks)} 个文档片段")
def query(self, question: str, top_k: int = 3, stream: bool = False) -> str:
"""RAG查询"""
# Step 1: 检索相关文档
query_embedding = get_query_embedding(question)
results = self.vector_store.search(query_embedding, top_k=top_k)
# Step 2: 拼接上下文
context = "\n\n---\n\n".join([r['content'] for r in results])
# Step 3: 构建prompt
system_prompt = """你是一个专业的知识库助手。请严格基于以下参考资料回答用户的问题。
规则：
1. 只基于参考资料中的内容回答，不要编造信息
2. 如果参考资料中没有相关信息，明确说明"参考资料中未找到相关信息"
3. 回答要准确、简洁、有条理
4. 如果引用了具体数据，标注来源"""
user_prompt = f"""参考资料：
{context}
用户问题：{question}"""
# Step 4: 调用LLM生成回答
if stream:
response = self.client.chat.completions.create(
model="gpt-4o",
messages=[
{"role": "system", "content": system_prompt},
{"role": "user", "content": user_prompt}
],
stream=True
)
full_answer = ""
for chunk in response:
if chunk.choices[0].delta.content:
content = chunk.choices[0].delta.content
print(content, end="", flush=True)
full_answer += content
print()
return full_answer
else:
response = self.client.chat.completions.create(
model="gpt-4o",
messages=[
{"role": "system", "content": system_prompt},
{"role": "user", "content": user_prompt}
]
)
return response.choices[0].message.content
def query_with_sources(self, question: str, top_k: int = 3) -> dict:
"""带来源引用的查询"""
query_embedding = get_query_embedding(question)
results = self.vector_store.search(query_embedding, top_k=top_k)
answer = self.query(question, top_k)
return {
"answer": answer,
"sources": [
{"content": r['content'][:100] + "...", "score": r['score']}
for r in results
]
}
3.5 运行测试
# 初始化
rag = RAGPipeline(llm_client=client)
# 加载文档
rag.ingest_documents([
"docs/product_faq.txt",
"docs/api_docs.txt",
"docs/troubleshooting.txt"
])
# 查询
result = rag.query_with_sources("如何重置密码？")
print(f"\n回答: {result['answer']}")
print(f"\n引用来源: {len(result['sources'])}个片段")
四、进阶优化：5个关键技巧
基础RAG能跑起来，但生产环境需要更多优化。
4.1 混合检索（向量+关键词）
纯向量检索可能漏掉精确匹配（如产品型号、错误码），混合检索更可靠：
import re
from collections import Counter
def keyword_search(query: str, chunks: List[str], top_k: int = 5) -> List[dict]:
"""简单的BM25式关键词检索"""
query_terms = set(re.findall(r'\w+', query.lower()))
scores = []
for i, chunk in enumerate(chunks):
chunk_terms = set(re.findall(r'\w+', chunk.lower()))
overlap = len(query_terms & chunk_terms)
scores.append((overlap, i))
scores.sort(reverse=True)
return [{'content': chunks[i], 'score': s, 'index': i} for s, i in scores[:top_k]]
def hybrid_search(query: str, vector_store: VectorStore,
chunks: List[str], alpha: float = 0.7, top_k: int = 3) -> List[dict]:
"""
混合检索：向量检索 + 关键词检索
alpha: 向量检索权重（0-1），1-apha为关键词检索权重
"""
# 向量检索
query_embedding = get_query_embedding(query)
vector_results = vector_store.search(query_embedding, top_k=top_k * 2)
# 关键词检索
keyword_results = keyword_search(query, chunks, top_k=top_k * 2)
# 合并分数
merged = {}
for r in vector_results:
merged[r['index']] = merged.get(r['index'], 0) + alpha * r['score']
for r in keyword_results:
merged[r['index']] = merged.get(r['index'], 0) + (1 - alpha) * r['score']
# 排序
sorted_results = sorted(merged.items(), key=lambda x: x[1], reverse=True)
return [{'content': chunks[i], 'score': s, 'index': i} for i, s in sorted_results[:top_k]]
4.2 重排序（Reranker）
检索回来的Top-K片段可能包含不相关的内容，用Reranker精排：
def rerank_with_llm(query: str, chunks: List[str], top_k: int = 3) -> List[str]:
"""用LLM对检索结果重排序"""
prompt = f"""请根据查询问题，对以下文档片段按相关性从高到低排序。
查询：{query}
文档片段：
{chr(10).join(f'[{i}] {c[:200]}' for i, c in enumerate(chunks))}
请返回最相关的{top_k}个片段的编号，用逗号分隔，如：2,0,5"""
response = client.chat.completions.create(
model="gpt-4o-mini", # 重排序用mini就够了
messages=[{"role": "user", "content": prompt}]
)
# 解析结果
try:
indices = [int(x.strip()) for x in response.choices[0].message.content.split(',')]
return [chunks[i] for i in indices[:top_k] if i < len(chunks)]
except:
return chunks[:top_k] # 解析失败时回退
4.3 智能切分：按Markdown标题切分
对于结构化文档（API文档、产品手册），按标题切分效果远好于固定长度：
import re
def split_by_markdown_headers(text: str) -> List[dict]:
"""按Markdown标题层级切分"""
pattern = r'^(#{1,4})\s+(.+)$'
sections = []
current = {'level': 0, 'title': '', 'content': ''}
for line in text.split('\n'):
match = re.match(pattern, line)
if match:
if current['content'].strip():
sections.append(current)
current = {
'level': len(match.group(1)),
'title': match.group(2).strip(),
'content': line + '\n'
}
else:
current['content'] += line + '\n'
if current['content'].strip():
sections.append(current)
# 添加层级元数据
for s in sections:
s['content'] = s['content'].strip()
s['metadata'] = {'title': s['title'], 'level': s['level']}
return sections
4.4 查询改写
用户的问题往往不够精确，先让LLM改写查询能提升检索效果：
def rewrite_query(original_query: str) -> str:
"""用LLM改写查询，使其更适合检索"""
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{
"role": "user",
"content": f"""请将以下问题改写为更适合在文档库中检索的查询语句。
要求：
1. 提取关键概念和实体
2. 移除口语化表达
3. 补充可能的同义词
4. 输出1-3个改写后的查询，每行一个
原问题：{original_query}"""
}]
)
return response.choices[0].message.content.strip()
# 示例
# 原问题："怎么搞那个登录不上的问题"
# 改写后："登录失败 故障排查\n认证错误 error\n无法登录 解决方案"
4.5 缓存热门问题
重复问题不需要每次都走RAG管线：
import hashlib
import json
class QueryCache:
def __init__(self, similarity_threshold: float = 0.95):
self.cache = {} # {query_hash: answer}
self.query_embeddings = {} # {query_hash: embedding}
self.threshold = similarity_threshold
def get(self, query: str, query_embedding: np.ndarray) -> str | None:
"""检查缓存中是否有相似问题的答案"""
query_hash = hashlib.md5(query.encode()).hexdigest()
# 精确匹配
if query_hash in self.cache:
return self.cache[query_hash]
# 语义相似匹配
for cached_hash, cached_embedding in self.query_embeddings.items():
similarity = cos_sim(query_embedding, cached_embedding)
if similarity > self.threshold:
return self.cache[cached_hash]
return None
def set(self, query: str, answer: str, query_embedding: np.ndarray):
query_hash = hashlib.md5(query.encode()).hexdigest()
self.cache[query_hash] = answer
self.query_embeddings[query_hash] = query_embedding
五、生产级RAG架构
单个Python脚本适合原型验证，生产环境建议这个架构：
┌─────────────┐
│ 用户请求 │
└──────┬──────┘
↓
┌──────────────┐
│ API Gateway │ ← FastAPI
└──────┬──────┘
↓
┌──────────────────────┐
│ Query Pipeline │
│ ┌──────────────┐ │
│ │ 查询改写 │ │
│ │ 混合检索 │ │
│ │ 重排序 │ │
│ │ Prompt构造 │ │
│ └──────────────┘ │
└────────┬─────────────┘
↓
┌───────────────────────┐
│ Vector Store │
│ ChromaDB / Milvus │
└───────────────────────┘
↓
┌─────────────────┐
│ LLM Service │ ← GPT-4o
└────────┬────────┘
↓
┌─────────────────┐
│ Cache + 日志 │ ← Redis
└─────────────────┘
FastAPI服务化示例：
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
rag = RAGPipeline(llm_client=client)
class QueryRequest(BaseModel):
question: str
top_k: int = 3
stream: bool = False
@app.post("/query")
async def query_rag(req: QueryRequest):
answer = rag.query(req.question, top_k=req.top_k)
return {"answer": answer, "question": req.question}
@app.post("/ingest")
async def ingest_documents(file_paths: List[str]):
rag.ingest_documents(file_paths)
return {"status": "ok", "files": len(file_paths)}
@app.get("/health")
async def health():
return {"status": "healthy"}
六、效果对比
我用自己的技术文档（约500篇，共50万字）做了测试：
| 方法 | 准确率 | 幻觉率 | 平均延迟 |
|---|---|---|---|
| 纯GPT-4（无RAG） | 35% | 45% | 2.1s |
| 基础RAG | 72% | 12% | 3.5s |
| 混合检索+Reranker | 85% | 5% | 4.2s |
| 混合检索+Reranker+查询改写 | 91% | 3% | 4.8s |
准确率 = 回答与标准答案一致的比例；幻觉率 = 编造不存在信息的比例
关键发现：
- 纯GPT-4在私有数据上基本不可用，近一半回答是编的
- 基础RAG就把准确率翻倍了
- 混合检索+Reranker+查询改写的组合效果最好，准确率91%，幻觉率仅3%
七、踩坑记录
| 坑 | 原因 | 解决方案 |
|---|---|---|
| 检索不到相关文档 | chunk太大，语义被稀释 | 控制chunk_size在300-500字 |
| 检索到了但回答不对 | prompt没强调"仅基于上下文" | 加system prompt约束 |
| 中文向量效果差 | 用了英文embedding模型 | 换中文模型（text2vec/bge） |
| 速度太慢 | 每次都重新算embedding | 预计算+缓存 |
| 回答有幻觉 | 检索片段不相关但仍被采用 | 设相似度阈值，低于阈值的丢弃 |
| chunk切断了表格 | 表格被从中间切开 | 按Markdown结构切分 |
总结
RAG不是什么高深技术，核心就三步：切文档 → 算向量 → 检索+生成。但要做好，每个环节都有优化空间。
入门路线：
- 先跑通基础版（本文的
RAGPipeline），验证效果 - 加混合检索，解决"精确匹配丢失"问题
- 加Reranker，提升检索精度
- 加查询改写，处理口语化问题
- 服务化部署，接入产品
选型建议：
| 场景 | 向量数据库 | Embedding模型 | LLM |
|---|---|---|---|
| 快速原型 | ChromaDB | text2vec-base-chinese | GPT-4o |
| 生产部署 | Milvus/Qdrant | bge-large-zh-v1.5 | GPT-4o |
| 本地部署 | FAISS | bge-base-zh | DeepSeek/Ollama |
| 低成本 | ChromaDB | text2vec | GPT-4o-mini |
有问题欢迎评论区交流 👇
