1. 项目概述
最近在项目开发中遇到了一个典型问题:随着项目文档越来越多(README、接口说明、部署手册、FAQ、PRD等),想要快速找到某个具体问题的答案变得异常困难。比如想知道"XX参数怎么配置"或者"某接口返回码什么意思",往往需要全局搜索、翻阅多个文档,甚至最后还是得去问同事。
直接把整份文档丢给大模型也不是理想的解决方案:
- 文档太长会超出token限制
- 关键段落没被喂给模型时,回答就会"凭感觉"
- 不同版本的文档混在一起时,模型容易给出错误答案
RAG(Retrieval-Augmented Generation)技术提供了一个相对优雅的解决方案:先把文档切块做向量索引;提问时先检索最相关的几段,再把"问题+相关片段"一起喂给模型生成答案。这相当于让模型学会"引用你给的证据",而不是试图记住所有内容。
本文将带你用30分钟搭建一个最小可用的RAG问答系统,包含以下核心组件:
- 文档清洗与切分(Markdown处理)
- FAISS向量索引构建
- SQLite元数据存储
- 问答API调用实现
- 效果对比与问题排查
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 技术方案选型
2.1 三种常见方案对比
在实现RAG系统时,主要有三种技术路线可选:
-
轻量级本地方案(本文采用)
- 组件:FAISS + SQLite + Python脚本
- 优点:依赖少、可离线保存索引、便于嵌入现有项目/CI流程
- 缺点:多用户并发、权限控制、增量更新等功能需要自行实现
-
全功能向量数据库方案
- 组件:Qdrant/Milvus/Elastic + LangChain/LlamaIndex框架
- 优点:功能全面、扩展性好
- 缺点:组件多、版本兼容问题多,对新手不友好
-
直接调用大模型
- 方法:直接把问题或整篇文档丢给大模型
- 优点:实现最简单
- 缺点:长文处理不可控、容易遗漏关键信息、复用性差、成本随输入暴涨
2.2 模型调用方案选择
在模型调用方面也有两种主要选择:
-
自建本地模型
- 工具:Ollama等
- 优点:完全自主可控
- 缺点:需要处理效果调优、显存管理、维护成本等问题
-
云API服务
- 优点:配置简单、参数调整方便、成本可控
- 缺点:依赖网络连接
本文示例代码将使用云API方式实现,但架构设计上可以轻松替换为本地模型。
3. 环境准备与依赖安装
3.1 基础环境要求
- 操作系统:Windows 11 / Ubuntu 22.04 / macOS均可
- Python版本:3.10+(推荐3.11)
- 主要依赖:
faiss-cpu:向量索引库numpy:数值计算openai:模型API调用(可替换为其他SDK)tqdm:进度条显示
3.2 安装步骤
bash复制# 创建并激活虚拟环境
python -m venv .venv
# Windows: .venv\Scripts\activate
source .venv/bin/activate
# 升级pip并安装依赖
pip install -U pip
pip install faiss-cpu numpy tqdm openai
常见问题处理:
- Windows上
faiss-cpu安装失败时,可以尝试:
- 使用WSL2环境
- 指定版本:
pip install faiss-cpu==1.7.4- 如需使用本地embedding模型,额外安装:
pip install sentence-transformers
4. 项目结构与文档准备
4.1 目录结构
建议按以下结构组织项目:
code复制rag_demo/
docs/
demo.md # 测试文档
rag.py # 主程序
.env # 环境变量配置(可选)
4.2 示例文档内容
docs/demo.md示例内容:
markdown复制# Demo 项目部署说明
## 启动
1. 安装依赖:pip install -r requirements.txt
2. 设置环境变量:APP_ENV=prod
3. 启动:python app.py --port 8080
## 配置项
- APP_ENV:prod 或 dev
- LOG_LEVEL:INFO/DEBUG
- REQUEST_TIMEOUT:单位秒,默认 30
## 常见错误
- 端口被占用
