基于RAG与本地大模型的轻量级智能文档问答系统实践

1. 项目概述：当文档中心遇上AI大脑

最近在折腾一个挺有意思的事儿：给公司内部的文档中心装个“AI大脑”。说白了，就是让员工能像跟一个懂行的同事聊天一样，直接问文档里的问题，而不是在成百上千个PDF、Word、Markdown文件里大海捞针。这个想法源于一个非常实际的痛点：我们团队的知识库越建越大，新员工入职要花一两周时间才能摸清门道，老员工找一份半年前的会议纪要或者某个技术方案的具体参数，也得翻半天。传统的全文搜索，关键词对不上就歇菜，体验很差。

于是，RAG（检索增强生成）技术就成了一个很自然的选择。它不像直接拿大语言模型做“通才”，而是让模型在回答时，能精准地“参考”我们指定的文档内容，生成更准确、更相关的答案。市面上已经有不少成熟的RAG框架和商业方案，但要么太重，部署维护成本高；要么太“黑盒”，定制化困难，数据安全也让人心里打鼓。所以，我的目标很明确：设计并实现一个轻量、开源、可私有化部署的智能问答助手，核心是在有限的资源下，做出最实用的效果，并且把整个过程中的关键设计与取舍记录下来。

这个项目不追求技术上的炫酷，而是聚焦于解决实际问题。我会带你走一遍从架构设计、工具选型、到具体实现和调优的完整过程，重点分享那些“为什么这么选”的思考，以及踩过坑后总结出的实操心得。无论你是想给自己团队搭建一个类似的工具，还是单纯对RAG的落地实践感兴趣，相信都能从中找到一些直接的参考。

2. 核心思路与架构设计：在轻量与效果间寻找平衡点

设计一个RAG系统，本质上是在解决三个核心问题：怎么存（文档处理与向量化）、怎么找（检索相关片段）、怎么答（生成最终回复）。而“轻量”这个约束，会让每一个环节的选择都变得需要权衡。

2.1 整体架构设计

我设计的架构遵循了经典RAG的流水线，但在每个组件上都做了轻量化考量：

1. 文档加载与解析：支持多种格式（PDF, Word, Markdown, TXT），将非结构化文本提取出来。
2. 文本分割：把长文档切成语义连贯的小片段（Chunk），这是影响检索精度的关键一步。
3. 向量化嵌入：使用嵌入模型将文本片段转换为向量（一组数字），存入向量数据库。
4. 检索：将用户问题也向量化，在向量数据库中查找最相似的几个文本片段。
5. 提示工程与生成：将检索到的片段和用户问题组合成一个清晰的提示，交给大语言模型生成最终答案。
6. 交互前端：一个简单的Web界面，用于提问和展示答案。

轻量化的核心思想是：优先选用成熟、高效、资源占用少的开源组件，避免引入复杂的依赖链和重型基础设施。

2.2 关键设计取舍

这里就遇到了第一个，也是最重要的取舍：本地模型 vs. 云端API。

• 云端API（如OpenAI GPT, Claude）：优点显而易见，效果顶级，开箱即用，无需担心算力。但缺点同样致命：数据隐私（文档内容上传到第三方）、持续成本（按token收费，长期使用是一笔开销）、网络依赖和定制化限制。
• 本地开源模型：数据完全私有，一次部署长期使用，可深度定制。但挑战在于：需要本地GPU或足够强的CPU，模型效果和速度可能不及顶级API，并且需要一定的运维知识。

对于“给文档中心装AI大脑”这个场景，数据隐私和长期成本往往是首要考虑因素。因此，我选择了本地开源模型路线。这意味着我们需要在效果上做出一些妥协，并通过后续的优化手段来弥补。

第二个重要取舍是：向量数据库的选择。

• 重型专业库（如Milvus, Weaviate）：功能强大，支持海量数据、高性能检索和复杂过滤。但它们通常需要单独部署，依赖数据库服务，增加了系统复杂度。
• 轻量嵌入式库（如Chroma, FAISS）：可以作为一个Python库直接集成到应用中，数据常驻内存或保存为本地文件。部署简单，零外部依赖，非常适合中小规模文档库（比如万级以下文档片段）。

为了极致轻量化和简化部署，我选择了Chroma。它足够简单，API友好，并且提供了持久化到磁盘的能力，重启应用后数据不会丢失。对于初期验证和中小型知识库来说，它完全够用。如果未来数据量暴涨，再迁移到更专业的数据库也不迟，Chroma良好的接口设计使得这种迁移成本相对较低。

3. 技术栈选型与工具链搭建

基于上述设计，我敲定了以下技术栈，每一款工具都是经过同类产品对比和实际测试后选出的。

3.1 核心组件选型解析

1. 文档处理与分割：LangChain & 自定义分割器

   • 为什么是LangChain？虽然我们的目标是轻量，但LangChain在文档加载、文本分割方面提供了极其丰富和统一的接口，能省去大量造轮子的时间。我们只使用它“工具链”的这一小部分，不引入其复杂的Agent或Chain逻辑，避免臃肿。
   • 分割策略的取舍：LangChain提供了多种文本分割器（RecursiveCharacterTextSplitter,CharacterTextSplitter等）。我选择了RecursiveCharacterTextSplitter，因为它会优先按段落、句子等自然边界分割，比单纯按固定字符数切割更能保证语义的完整性。这里的关键参数是chunk_size（片段大小）和chunk_overlap（片段重叠）。经过测试，对于技术文档，chunk_size=500（字符数），chunk_overlap=50是一个不错的起点。重叠部分能防止关键信息被割裂在两个片段边缘。

2. 嵌入模型：all-MiniLM-L6-v2

   • 这是Hugging Face上的一款明星级轻量嵌入模型。选择它基于以下几点：
     • 体积小：模型文件仅80MB左右，在CPU上也能快速运行。
     • 质量与速度平衡：在标准基准测试中，其效果对于同尺寸模型来说非常出色，足以满足大部分检索需求。
     • 通用性强：在多语言和多种文本类型上都有不错的表现。
   • 相比于更大的模型（如text-embedding-ada-002的API或bge-large等），它在精度上略有牺牲，但换来了部署的便捷性和极低的资源消耗，完美契合“轻量”主题。

3. 大语言模型：ChatGLM3-6B 或 Qwen1.5-7B

   • 这是整个系统中最吃资源的部分，也是效果的关键。在开源6B-7B量级的模型中，我主要对比了这两款：
     • ChatGLM3-6B：对中文支持非常友好，对话格式设计得好，指令跟随能力强。在消费级GPU（如RTX 4060 8G）上可以量化后流畅运行。
     • Qwen1.5-7B：来自阿里的模型，在中文理解和生成能力上同样顶尖，上下文长度支持更长（可达32K），对于需要参考多篇长文档的场景更有优势。
   • 取舍点：如果更看重部署简便性和中文对话手感，选ChatGLM3；如果文档很长且需要更强的长文本理解，选Qwen1.5。我最终选择了Qwen1.5-7B-Chat的4位量化版本（GPTQ或AWQ），这样可以在8GB显存的GPU上运行，甚至用大内存CPU勉强跑起来。

4. 向量数据库：Chroma

   • 如前所述，选择Chroma就是选择简单。它直接使用all-MiniLM-L6-v2模型进行向量化并存储，无需额外配置嵌入终端。其persist_directory参数可以将数据保存在本地，实现了数据的持久化。

5. 后端与前端：FastAPI + Streamlit

   • FastAPI：用于构建高性能的API服务，处理文档上传、索引构建和问答的核心逻辑。它异步特性好，自动生成API文档，开发效率高。
   • Streamlit：快速构建数据应用的原型。用它可以几乎零前端代码量，快速做出一个包含文件上传、问题输入和答案展示的Web界面，非常适合内部工具演示和初期使用。

注意：模型量化是本地部署的关键技巧。直接加载7B的FP16原模型需要约14GB显存。通过GPTQ/AWQ等量化技术，可以将模型压缩到4位精度，在几乎不损失效果的情况下，将显存需求降低到6GB以下，使得在消费级显卡上运行成为可能。

3.2 环境搭建实操步骤

假设我们已经在本地准备好Python环境（建议3.9+），下面是一步步的搭建过程。

# 1. 创建项目目录并进入 mkdir lightweight-rag-assistant && cd lightweight-rag-assistant # 2. 创建虚拟环境（可选但推荐） python -m venv venv # Windows: venv\Scripts\activate # Linux/Mac: source venv/bin/activate # 3. 安装核心依赖 pip install langchain langchain-community chromadb pypdf python-docx markdown pip install sentence-transformers # 用于运行all-MiniLM嵌入模型 pip install fastapi uvicorn streamlit pip install transformers accelerate # 用于运行本地LLM # 4. 安装模型运行时依赖（以Qwen1.5为例，使用AutoGPTQ量化版本） pip install auto-gptq optimum # 如果需要CPU推理，可以安装llama.cpp的Python绑定：pip install llama-cpp-python

依赖选择的心得：langchain-community包包含了LangChain对各种社区工具（如Chroma）的集成，比安装完整的langchain包更轻量。sentence-transformers库是运行all-MiniLM模型最方便的方式。

4. 核心模块实现与代码解析

接下来，我们分模块实现这个智能问答助手的核心功能。我会给出关键代码并解释其背后的逻辑。

4.1 文档加载与处理模块

这个模块负责读取各种格式的文档，并将其转换为统一的纯文本。

# document_processor.py from langchain_community.document_loaders import PyPDFLoader, Docx2txtLoader, TextLoader, UnstructuredMarkdownLoader from langchain.text_splitter import RecursiveCharacterTextSplitter from typing import List import os class DocumentProcessor: def __init__(self, chunk_size=500, chunk_overlap=50): self.text_splitter = RecursiveCharacterTextSplitter( chunk_size=chunk_size, chunk_overlap=chunk_overlap, length_function=len, separators=["\n\n", "\n", "。", "！", "？", "；", "，", " ", ""] ) def load_and_split(self, file_path: str) -> List[str]: """根据文件后缀名选择加载器，加载并分割文档""" _, ext = os.path.splitext(file_path) ext = ext.lower() if ext == '.pdf': loader = PyPDFLoader(file_path) elif ext in ['.docx', '.doc']: loader = Docx2txtLoader(file_path) elif ext == '.md': loader = UnstructuredMarkdownLoader(file_path) elif ext == '.txt': loader = TextLoader(file_path, encoding='utf-8') else: raise ValueError(f"Unsupported file type: {ext}") documents = loader.load() # 将Document对象列表转换为纯文本列表 texts = [doc.page_content for doc in documents] # 进一步分割成长度合适的片段 all_splits = [] for text in texts: splits = self.text_splitter.split_text(text) all_splits.extend(splits) return all_splits

关键点解析：

1. RecursiveCharacterTextSplitter的separators参数是关键。我这里的顺序是优先按双换行（段落）、单换行、句号等分割，最后才是空格和空字符。这个顺序对中文文档的语义保持很重要。
2. 加载后先拿到每页的文本，再统一进行分割，避免了某些加载器（如PDF）可能返回的页面内容过长的问题。
3. 返回的是纯文本字符串列表，而不是LangChain的Document对象，这是为了后续更灵活地处理，也减少依赖。

4.2 向量数据库构建模块

这个模块负责将文本片段转换为向量，并存储到Chroma中。

# vector_store.py from sentence_transformers import SentenceTransformer import chromadb from chromadb.config import Settings import uuid class VectorStoreManager: def __init__(self, persist_dir="./chroma_db", embedding_model_name='sentence-transformers/all-MiniLM-L6-v2'): self.persist_dir = persist_dir # 初始化嵌入模型 self.embedding_model = SentenceTransformer(embedding_model_name) # 初始化Chroma客户端，设置持久化目录 self.client = chromadb.PersistentClient(path=persist_dir, settings=Settings(allow_reset=True)) # 获取或创建集合（类似数据库的表） self.collection = self.client.get_or_create_collection(name="knowledge_base") def add_documents(self, texts: List[str], metadatas: List[dict] = None): """将文本列表添加到向量数据库""" if not texts: return # 生成嵌入向量 embeddings = self.embedding_model.encode(texts).tolist() # 生成唯一ID ids = [str(uuid.uuid4()) for _ in range(len(texts))] # 如果没有提供元数据，则创建空列表 if metadatas is None: metadatas = [{} for _ in range(len(texts))] # 批量添加到集合 self.collection.add( embeddings=embeddings, documents=texts, metadatas=metadatas, ids=ids ) print(f"Added {len(texts)} documents to the vector store.") def search(self, query: str, top_k: int = 5) -> List[dict]: """检索与查询最相关的top_k个文本片段""" # 将查询语句也转换为向量 query_embedding = self.embedding_model.encode([query]).tolist() # 执行搜索 results = self.collection.query( query_embeddings=query_embedding, n_results=top_k ) # 整理返回结果 retrieved_docs = [] if results['documents']: for doc, distance in zip(results['documents'][0], results['distances'][0]): retrieved_docs.append({ 'content': doc, 'score': 1 - distance # Chroma返回的是余弦距离，转换为相似度分数 }) return retrieved_docs

关键点解析：

1. 使用PersistentClient并指定path，这样Chroma会把数据（包括向量和元数据）保存在本地磁盘，下次启动时可以直接加载，无需重新构建。
2. SentenceTransformer模型第一次运行时会从Hugging Face下载，可以提前下载好（model.save(‘local_path’)）以加速后续加载。
3. 搜索返回的distances是余弦距离（0表示完全相同，2表示完全相反）。我们将其转换为相似度分数（1 - distance），更符合直觉。
4. 这里没有对元数据（如来源文件名、页码）做复杂处理，但在实际应用中，强烈建议在metadatas中记录这些信息，便于后续追溯答案来源。

4.3 大语言模型集成与问答生成模块

这是智能的核心，负责将检索到的上下文和用户问题组合，交给LLM生成答案。

# rag_engine.py from transformers import AutoTokenizer, AutoModelForCausalLM, pipeline import torch class RAGEngine: def __init__(self, vector_store_manager, model_path="Qwen/Qwen1.5-7B-Chat-GPTQ-Int4"): self.vs_manager = vector_store_manager # 加载量化模型和分词器 self.tokenizer = AutoTokenizer.from_pretrained(model_path, trust_remote_code=True) # 注意：使用device_map="auto"让transformers自动分配模型层到GPU/CPU self.model = AutoModelForCausalLM.from_pretrained( model_path, device_map="auto", trust_remote_code=True, torch_dtype=torch.float16 # 即使量化，也建议使用半精度 ) # 创建文本生成管道 self.pipeline = pipeline( "text-generation", model=self.model, tokenizer=self.tokenizer, max_new_tokens=512, # 生成答案的最大长度 temperature=0.1, # 低温度使输出更确定、更聚焦 do_sample=True ) def generate_prompt(self, query: str, contexts: List[str]) -> str: """构建给LLM的提示词模板""" context_str = "\n\n".join([f"[参考内容 {i+1}]: {ctx['content']}" for i, ctx in enumerate(contexts)]) prompt = f"""你是一个专业的文档问答助手。请严格根据以下提供的参考内容来回答问题。如果参考内容中没有明确答案，请直接说“根据提供的资料，我无法回答这个问题”，不要编造信息。 参考内容： {context_str} 问题：{query} 请根据上述参考内容，用中文给出清晰、准确的答案：""" return prompt def ask(self, query: str, top_k: int = 5) -> dict: """核心问答流程：检索 -> 构造提示 -> 生成""" # 1. 检索相关文档片段 contexts = self.vs_manager.search(query, top_k=top_k) if not contexts: return {"answer": "未在知识库中找到相关信息。", "sources": []} # 2. 构建提示 prompt = self.generate_prompt(query, contexts) # 3. 调用模型生成答案 response = self.pipeline(prompt)[0]['generated_text'] # 提取模型生成的答案部分（去除我们给的提示） answer = response[len(prompt):].strip() # 4. 整理结果，包含答案和来源（这里简化，只返回内容片段） sources = [ctx['content'][:100] + "..." for ctx in contexts] # 截取片段预览 return { "answer": answer, "sources": sources, "relevant_contexts": contexts # 包含完整内容和相似度分数 }

关键点解析：

1. 模型加载：device_map=”auto”是神器，它会自动将模型的不同层分配到可用的GPU和CPU内存上，尽可能利用现有硬件。torch_dtype=torch.float16能减少内存占用并加速推理。
2. 提示工程：这是RAG效果的生命线。我的模板强调了三点：
   • 角色设定：让模型进入“文档助手”的角色。
   • 指令明确：“严格根据参考内容”，并指示在无答案时拒绝回答，这是为了减少模型“幻觉”（胡编乱造）。
   • 结构化上下文：清晰地将参考内容和问题分开，便于模型理解。
3. 参数设置：temperature=0.1让生成结果更稳定、更忠于上下文。对于知识问答，我们不需要太多的创造性。max_new_tokens控制了答案长度，可根据需要调整。
4. 答案提取：由于我们使用了text-generation管道，它会把完整的对话（包括我们的提示）都生成出来。所以需要截取提示之后的部分作为答案。

4.4 服务层与Web界面集成

最后，我们用FastAPI提供后端API，用Streamlit快速搭建一个前端。

# main_api.py (FastAPI后端) from fastapi import FastAPI, File, UploadFile, HTTPException from fastapi.middleware.cors import CORSMiddleware import os from document_processor import DocumentProcessor from vector_store import VectorStoreManager from rag_engine import RAGEngine import shutil app = FastAPI(title="轻量RAG问答助手API") app.add_middleware(CORSMiddleware, allow_origins=["*"], allow_methods=["*"], allow_headers=["*"]) # 初始化核心组件 doc_processor = DocumentProcessor() vs_manager = VectorStoreManager() rag_engine = RAGEngine(vs_manager) UPLOAD_DIR = "./uploaded_docs" os.makedirs(UPLOAD_DIR, exist_ok=True) @app.post("/upload/") async def upload_and_index(file: UploadFile = File(...)): """上传文件并构建索引""" if not file.filename: raise HTTPException(status_code=400, detail="No file uploaded.") file_path = os.path.join(UPLOAD_DIR, file.filename) with open(file_path, "wb") as buffer: shutil.copyfileobj(file.file, buffer) try: texts = doc_processor.load_and_split(file_path) vs_manager.add_documents(texts, metadatas=[{"source": file.filename}] * len(texts)) return {"message": f"File '{file.filename}' processed and indexed successfully.", "chunks": len(texts)} except Exception as e: raise HTTPException(status_code=500, detail=f"Processing failed: {str(e)}") finally: # 可选：处理完后删除上传的临时文件 os.remove(file_path) @app.post("/ask/") async def ask_question(query: str): """提出问题并获取答案""" if not query: raise HTTPException(status_code=400, detail="Query cannot be empty.") result = rag_engine.ask(query) return result @app.get("/health") async def health_check(): return {"status": "healthy"}

# app.py (Streamlit前端) import streamlit as st import requests import json st.set_page_config(page_title="轻量RAG文档助手", layout="wide") st.title("📚 给文档中心装个AI大脑") API_BASE = "http://localhost:8000" # 假设FastAPI后端运行在此 # 侧边栏：文件上传 with st.sidebar: st.header("📤 上传文档") uploaded_file = st.file_uploader("选择PDF、Word、TXT或MD文件", type=['pdf', 'docx', 'txt', 'md']) if uploaded_file is not None and st.button("上传并构建索引"): files = {"file": (uploaded_file.name, uploaded_file.getvalue())} with st.spinner(f"正在处理 {uploaded_file.name} ..."): response = requests.post(f"{API_BASE}/upload/", files=files) if response.status_code == 200: st.success(f"处理成功！生成了 {response.json()['chunks']} 个文本片段。") else: st.error(f"处理失败：{response.text}") # 主界面：问答 st.header("💬 智能问答") question = st.text_input("请输入你的问题：", placeholder="例如：我们项目的技术架构是什么？") if st.button("获取答案") and question: with st.spinner("正在思考..."): response = requests.post(f"{API_BASE}/ask/", json={"query": question}) if response.status_code == 200: result = response.json() st.subheader("答案：") st.write(result["answer"]) with st.expander("查看参考来源"): for i, source in enumerate(result["sources"]): st.caption(f"**来源片段 {i+1}:** {source}") else: st.error("请求失败，请检查后端服务。")

部署与运行：

1. 在一个终端启动FastAPI后端：uvicorn main_api:app --reload --host 0.0.0.0 --port 8000
2. 在另一个终端启动Streamlit前端：streamlit run app.py
3. 打开浏览器访问Streamlit提供的地址（通常是http://localhost:8501）。

至此，一个完整的、轻量级的本地RAG智能问答助手就搭建完成了。你可以通过前端上传公司的技术文档、产品手册、会议纪要等，然后像聊天一样提问了。

5. 效果调优与避坑指南

项目跑起来只是第一步，要让它真正好用，还需要大量的调优和“填坑”。下面是我在实践中总结的几个关键点和常见问题。

5.1 检索质量优化：让AI找到对的“参考资料”

检索是RAG的基石，如果检索到的片段不相关，再强的LLM也无力回天。

1. 文本分割（Chunking）是玄学：

   • 问题：固定大小的分割会切断完整的句子或段落，导致语义破碎。
   • 优化：除了调整chunk_size和chunk_overlap，可以尝试更智能的分割器，如按Markdown标题分割（MarkdownHeaderTextSplitter），或者使用语义分割模型（如semantic-text-splitter），虽然会慢一些，但效果更好。我的经验是，对于结构清晰的文档，优先按标题分割；对于普通文本，RecursiveCharacterTextSplitter配合合适的separators是性价比最高的选择。

2. 嵌入模型的选择与微调：

   • 问题：通用的嵌入模型对特定领域（如医疗、法律）术语不敏感。
   • 优化：如果效果不佳，可以考虑在领域数据上微调嵌入模型（如使用SentenceTransformers的训练框架），但这需要额外的数据和计算资源。一个更轻量的方法是关键词增强：在将文本存入向量库和查询时，自动提取或补充一些关键词，与原始文本拼接后再向量化，能有效提升专业术语的匹配度。

3. 混合检索（Hybrid Search）：

   • 问题：纯向量检索可能错过关键词完全匹配但语义相似度不高的内容。
   • 优化：结合传统的BM25等关键词检索。可以先进行关键词检索，再进行向量检索，然后对两者的结果进行重排序（Rerank）。Chroma本身不支持BM25，但可以集成rank_bm25这样的库，自己实现一个简单的混合检索逻辑。对于初期项目，可以先用纯向量检索，如果发现很多问题明显有关键词但没被检索到，再考虑引入混合检索。

5.2 生成质量优化：让AI“好好说话”

即使找到了对的资料，LLM也可能答非所问或胡编乱造。

1. 提示工程精细化：

   • 指令要强硬：在提示词中反复强调“严格根据参考内容”、“不要编造”、“如果不知道就说不知道”。可以尝试不同的措辞，找到模型最“听话”的版本。
   • 提供格式示例：对于需要列表、步骤或特定格式的答案，可以在提示词中给一个例子（Few-Shot Prompting）。
   • 角色扮演：让模型扮演“严谨的技术专家”、“耐心的客服”等角色，有时能显著改变回答的语气和准确性。

2. 上下文管理与压缩：

   • 问题：检索到的top_k个片段可能很长，超过模型的上下文窗口，或者包含冗余信息。
   • 优化：不是简单地把所有片段拼接起来。可以尝试：
     • 重排序后只取前N个：根据与问题的相似度分数，只取分数最高的前2-3个。
     • 摘要压缩：用一个更小的模型（如T5）先对检索到的长片段进行摘要，再将摘要送入主LLM。这增加了复杂度，但在上下文窗口紧张时很有效。

3. 后处理与引用：

   • 要求模型引用来源：在提示词中要求模型在答案中注明“根据参考内容1”，并在前端高亮显示对应的原文片段。这不仅能增加可信度，也方便用户追溯核查。
   • 答案校验：对于关键事实，可以设计简单的规则或再用一次LLM调用，判断答案是否真的来源于提供的上下文。

5.3 性能与成本优化：让系统跑得又快又省

1. 模型量化与推理加速：

   • GPTQ/AWQ量化：如前所述，这是在消费级硬件上运行7B以上模型的必备技能。通常4位量化能在效果损失极小的情况下，将显存需求降低至1/3。
   • 推理框架：使用vLLM或llama.cpp等高性能推理框架，可以大幅提升生成速度（吞吐量）。vLLM的PagedAttention技术对长上下文和并发特别友好。

2. 向量检索加速：

   • 索引优化：Chroma默认使用HNSW索引，对于百万级以下的数据量足够快。如果数据量极大，可以考虑专门优化的向量数据库，但那就违背“轻量”初衷了。
   • 缓存：对常见问题（FAQ）的问答对进行缓存，可以瞬间返回答案，减轻模型负担。

3. 异步处理：

   • 文档索引（向量化）是耗时操作。一定要做成异步任务，上传文件后立即返回成功，后台慢慢处理，避免HTTP请求超时。

5.4 常见问题排查实录

下面是一个我遇到过的典型问题及解决方法的速查表：

6. 开源与扩展：从玩具到工具

这个项目的代码，我已经整理并开源在GitHub上。开源的目的是提供一个清晰、可运行的起点，让大家能快速理解RAG的核心流程，并基于自己的需求进行修改。

项目的开源地址：你可以在主要的代码托管平台搜索lightweight-rag-assistant找到它。仓库里包含了完整的代码、更详细的配置说明和一个docker-compose.yml文件，可以一键部署所有服务。

如何从这个“轻量版”扩展到更实用的场景？

1. 支持更多数据源：目前支持本地文件上传。可以轻松集成langchain的更多加载器，支持从Confluence、Notion、GitHub Wiki、企业微信直接同步文档。
2. 加入对话历史：当前的每次问答都是独立的。可以引入简单的对话记忆（如保存最近几轮问答到session），让模型能进行多轮对话，理解指代（如“上面的方案”）。
3. 实现权限控制：不是所有文档都对所有人可见。可以在元数据中加入权限标签，在检索前或生成后对结果进行过滤。
4. 构建更友好的前端：用Vue/React替换Streamlit，实现更美观、交互性更强的界面，支持对话式UI、来源高亮、反馈按钮（对答案点赞/点踩，用于后续优化）。
5. 接入监控与评估：加入日志系统，记录所有问答对。定期抽样评估答案质量，这是迭代优化系统最重要的数据来源。

最后的个人体会：搭建一个RAG系统，从零到一跑通流程并不难，难的是让它在实际业务场景中稳定、可靠、高效地运行。最大的感触就是没有银弹，所有的设计都是权衡。用本地小模型，就得在提示工程和检索质量上多下功夫；追求轻量部署，就得接受功能上的某些限制。这个项目展示的是一条务实的技术路径：在资源有限的情况下，通过合理的组件选型和细致的调优，完全能够构建出一个解决实际问题的AI助手。它可能不如ChatGPT知识渊博，但对于你喂给它的专属文档，它能做到更精准、更可控。