企业官网建设流程全解析

这次我们来看一个RAG 知识库问答系统的完整搭建过程。项目核心是把本地文档变成可检索、可问答的私有知识库，并接入 Deepseek 大模型完成回答生成。整个方案不依赖本地高性能显卡，Deepseek 通过 API 远程调用，普通开发机就能跑通，适合第一次接触 RAG 的开发者直接照着做。

先给结论：这套 RAG 问答系统最大的特点，是把“检索”和“生成”拆成了两条链路。文档先经过切分、向量化、入库三个步骤进入向量数据库；用户提问时，系统先从库里检索出最相关的片段，再把这些片段连同问题一起交给 Deepseek 生成答案。相比直接问大模型，RAG 能显著减少幻觉，回答内容有依据，也能覆盖模型训练数据之外的私有资料。

文章会带你完成：环境准备、Deepseek API 配置、文档加载与文本切分、向量化入库、相似度检索、Prompt 构造、Web 问答界面、API 接口封装和批量问答脚本。源码结构按模块拆分，可以直接复制运行，也可以改造成自己的项目。适合正在学习大模型应用开发、准备搭建企业文档问答系统，或者想理解 RAG 原理的读者。

1. 核心能力速览

这套 RAG 知识库问答系统覆盖了从文档处理到问答输出的完整链路，核心能力如下表：

从资源角度看，嵌入模型体积在百 MB 级别，向量数据库按磁盘文件存储，整体占用很小。Deepseek API 按 token 计费，日常测试成本不高。真正需要关注的是文档质量和切分策略，这两个因素对检索效果影响最大。

2. RAG 工作原理与项目架构

RAG 全称 Retrieval-Augmented Generation，检索增强生成。它解决的核心问题是：大模型训练数据有截止时间，不知道你的私有文档内容，直接提问只会得到通用回答，甚至编造答案。RAG 的做法是在生成之前增加一个检索环节，先把相关文档片段找出来，再让大模型基于这些片段回答。

完整流程分成七个环节：

1. 加载文档：读取 docs 目录下的 txt、md、pdf、docx 文件。
2. 文本切分：把长文本切成固定长度的片段，片段之间保留重叠区域。
3. 向量化：用嵌入模型把每个文本片段转换成一串浮点数向量。
4. 向量入库：把向量和原始文本、来源信息一起存入 Chroma 向量数据库。
5. 问题向量化：用户提问时，用同一个嵌入模型把问题转换为向量。
6. 相似度检索：在向量数据库中查找与问题向量最相似的 Top-K 个片段。
7. 生成回答：把检索结果拼进 Prompt，调用 Deepseek 生成最终答案。

这里有两个关键概念需要理解。

第一个是嵌入模型。它把文本映射到高维向量空间，语义相近的文本向量距离更近。项目采用 bge-small-zh-v1.5，专门针对中文优化，体积小，CPU 推理速度快，适合作为入门默认选择。

第二个是向量数据库。它负责存储向量并支持近似最近邻检索。Chroma 是纯 Python 实现的持久化向量库，无需额外部署服务，对初学者友好，生产环境可以考虑替换为 Milvus 或 pgvector。

在实际选型时，经常有人把 RAG 和微调放在一起对比。两者定位不同：

对一个私有知识库问答系统来说，RAG 是性价比最高的方案。你不需要训练模型，只需要管理好文档和索引。

3. 适用场景与使用边界

3.1 适合什么场景

RAG 知识库问答系统适合下面这些场景：

• 企业产品手册问答：把操作手册、FAQ 文档导入，员工或客户可以直接提问。
• 论文与报告分析：批量导入 PDF，快速总结核心观点、查找具体数据。
• 内部制度查询：公司制度、流程文档数量多，关键词搜索不好用，RAG 能理解语义。
• 教学演示：作为大模型应用入门项目，理解检索、向量、生成三条链路。
• 垂直领域客服：把业务知识库接入，自动回答常见问题，降低人工成本。

3.2 不适合什么场景

这套方案也有明显的边界：

• 需要严格多轮对话记忆的场景，需要额外设计会话历史管理，当前版本只支持单轮问答。
• 对回答实时性要求极高的场景，每次检索都会增加几百毫秒延迟。
• 需要模型进行复杂数值计算或逻辑推理的场景，检索增强带来的收益有限。
• 知识库规模很大的场景，几十万条文本需要考虑向量索引分片和更专业的数据库。

3.3 合规与安全边界

使用 Deepseek API 时，用户问题和检索到的文档片段会发送到远程模型服务。如果知识库包含内部机密、个人隐私或未公开的商业资料，要么对内容脱敏后再入库，要么改用本地部署的模型，比如使用 Ollama 运行开源模型，完全离线推理。

另外，文档来源必须确认有合法使用权。不要把自己没有版权的书籍、付费课程资料或未授权内部文件直接灌入知识库。发布或商用前，需要对回答内容做人工复核，防止生成内容包含敏感信息或侵权内容。

4. 环境准备与前置条件

4.1 基础环境检查

开始之前，先确认本机环境满足以下条件：

• 操作系统：Windows 10/11、Ubuntu 20.04+、macOS 均可。
• Python 版本：建议 3.9 到 3.11，避免使用过新的 Python 版本导致依赖包不兼容。
• 网络：需要访问 HuggingFace 下载嵌入模型，同时访问 Deepseek API。
• 磁盘空间：预留 2GB 以上，模型文件加向量数据库足够。
• GPU：非必须，嵌入模型在 CPU 上运行完全没问题。

4.2 获取 Deepseek API Key

打开 Deepseek 开放平台，注册账号后创建 API Key。需要关注三个信息：

• API Key：格式为 sk- 开头的字符串，保存好不要泄露。
• Base URL：接口地址为 https://api.deepseek.com。
• 模型名称：deepseek-chat 对应通用对话模型，deepseek-reasoner 对应推理模型。

建议把 API Key 写入环境变量，不要硬编码在代码里提交到公开仓库。

# Windows PowerShell $env:DEEPSEEK_API_KEY="sk-你的key" # Linux / macOS export DEEPSEEK_API_KEY="sk-你的key"

4.3 创建项目目录结构

按照下面的结构创建项目目录，源码和文档分开管理：

rag-project/ ├── config.py # 全局配置 ├── ingest.py # 文档加载、切分、向量化、入库 ├── query.py # 检索 + Deepseek 生成 ├── app.py # Gradio Web 界面 ├── api_server.py # FastAPI 接口服务 ├── batch_qa.py # 批量问答脚本 ├── requirements.txt # Python 依赖 ├── docs/ # 待入库的知识文档 └── data/ └── chroma_db/ # 向量数据库文件

5. 从零搭建 RAG 知识库问答系统

5.1 创建虚拟环境并安装依赖

为了让项目环境干净，先创建 Python 虚拟环境：

cd rag-project python -m venv venv # Windows venv\Scripts\activate # Linux / macOS source venv/bin/activate

在 requirements.txt 中写入以下依赖：

sentence-transformers==2.7.0 chromadb==0.5.5 openai>=1.40.0 pypdf>=4.0.0 python-docx>=1.1.0 gradio>=4.0.0 fastapi>=0.115.0 uvicorn>=0.30.0 requests>=2.32.0

安装依赖：

pip install -r requirements.txt

首次运行时会自动下载 bge-small-zh-v1.5 模型，如果 HuggingFace 下载失败，可以通过环境变量配置镜像源。

5.2 编写全局配置文件

创建 config.py，集中管理所有参数。这样后续调整切分长度、检索数量和模型名称，只需要改一个文件。

import os # Deepseek 配置 DEEPSEEK_API_KEY = os.getenv("DEEPSEEK_API_KEY", "sk-你的key") DEEPSEEK_BASE_URL = "https://api.deepseek.com" DEEPSEEK_MODEL = "deepseek-chat" # 嵌入模型 EMBEDDING_MODEL = "BAAI/bge-small-zh-v1.5" # 文本切分参数 CHUNK_SIZE = 300 CHUNK_OVERLAP = 50 # 检索参数 TOP_K = 3 # 路径配置 DOCS_DIR = "./docs" CHROMA_DB_DIR = "./data/chroma_db" COLLECTION_NAME = "my_kb"

CHUNK_SIZE 控制每个文本片段的最大长度，CHUNK_OVERLAP 是相邻片段之间的重叠区域。重叠的目的是避免一句话被从中间切断，保证语义完整性。对 bge-small 模型，建议片段长度不要超过 512，300 是一个比较稳妥的起点。

5.3 实现文档加载与文本切分

创建 ingest.py，实现文档加载和文本切分逻辑。这里先实现 txt、md、pdf 三种格式，docx 可以通过 python-docx 扩展。

import os import uuid from pathlib import Path from sentence_transformers import SentenceTransformer import chromadb from pypdf import PdfReader import config embedder = SentenceTransformer(config.EMBEDDING_MODEL) client = chromadb.PersistentClient(path=config.CHROMA_DB_DIR) collection = client.get_or_create_collection(config.COLLECTION_NAME) def split_text(text: str) -> list[str]: chunks = [] start = 0 while start < len(text): end = start + config.CHUNK_SIZE chunks.append(text[start:end]) start = end - config.CHUNK_OVERLAP return chunks def load_document(file_path: str) -> str: suffix = Path(file_path).suffix.lower() if suffix in (".txt", ".md"): with open(file_path, "r", encoding="utf-8") as f: return f.read() if suffix == ".pdf": reader = PdfReader(file_path) return "\n".join(page.extract_text() or "" for page in reader.pages) raise ValueError(f"暂不支持的文件类型: {suffix}") def main(): docs_dir = Path(config.DOCS_DIR) if not docs_dir.exists(): docs_dir.mkdir(parents=True) for file_path in docs_dir.rglob("*"): if file_path.suffix.lower() not in (".txt", ".md", ".pdf"): continue text = load_document(str(file_path)) chunks = split_text(text) if not chunks: print(f"文档为空: {file_path}") continue embeddings = embedder.encode(chunks, normalize_embeddings=True).tolist() ids = [str(uuid.uuid4()) for _ in chunks] metadatas = [{"source": str(file_path)} for _ in chunks] collection.add( ids=ids, documents=chunks, metadatas=metadatas, embeddings=embeddings ) print(f"已入库: {file_path}，切分 {len(chunks)} 块") if __name__ == "__main__": main()

这段代码做了四件事：加载文档、切分文本、生成向量、写入向量数据库。需要注意的是 collection.add 时手动传入了 embeddings，这是为了避免 Chroma 使用默认的英文嵌入模型，保证中文向量质量。

5.4 实现检索与 Deepseek 生成

创建 query.py，这是系统的核心查询模块。它包含两部分逻辑：从向量库检索相关片段，调用 Deepseek 生成回答。

from openai import OpenAI from sentence_transformers import SentenceTransformer import chromadb import config embedder = SentenceTransformer(config.EMBEDDING_MODEL) client = chromadb.PersistentClient(path=config.CHROMA_DB_DIR) collection = client.get_or_create_collection(config.COLLECTION_NAME) llm_client = OpenAI( api_key=config.DEEPSEEK_API_KEY, base_url=config.DEEPSEEK_BASE_URL ) SYSTEM_PROMPT = """你是一个严谨的知识库问答助手。 请严格基于下面的参考资料回答用户问题。 如果参考资料无法支撑回答，请直接说明“根据当前知识库无法回答”，不要编造。 回答中可以引用参考资料编号，例如 [1]。 参考资料： {context} """ def retrieve(query: str, top_k: int = None) -> tuple[list[str], list[dict]]: top_k = top_k or config.TOP_K query_embedding = embedder.encode([query], normalize_embeddings=True).tolist() result = collection.query( query_embeddings=query_embedding, n_results=top_k ) return result["documents"][0], result["metadatas"][0] def answer(question: str, top_k: int = None) -> dict: docs, metas = retrieve(question, top_k) context = "\n\n".join( f"[{i + 1}] {doc}" for i, doc in enumerate(docs) ) prompt = SYSTEM_PROMPT.format(context=context) resp = llm_client.chat.completions.create( model=config.DEEPSEEK_MODEL, messages=[ {"role": "system", "content": prompt}, {"role": "user", "content": question} ], temperature=0.3 ) return { "answer": resp.choices[0].message.content, "references": [ {"source": meta.get("source"), "chunk": doc} for meta, doc in zip(metas, docs) ] } if __name__ == "__main__": q = input("请输入问题：") result = answer(q) print("回答：", result["answer"]) print("参考来源：") for ref in result["references"]: print("-", ref["source"])

这个模块把 RAG 最核心的链路串起来了：问题转化为向量、向量库检索、Prompt 构造、大模型生成、返回来源引用。返回的 references 字段让回答可追溯，这是 RAG 系统相比裸调大模型最明显的优势。

5.5 启动 Web 问答界面

创建 app.py，使用 Gradio 搭建一个可交互的 Web 界面。这样不需要写前端代码，就能在浏览器里测试问答效果。

import gradio as gr from query import answer def chat(message, history): result = answer(message) ref_text = "\n".join(f"- {r['source']}" for r in result["references"]) return f"{result['answer']}\n\n参考来源：\n{ref_text}" demo = gr.ChatInterface( fn=chat, title="RAG 知识库问答系统", description="本地向量检索 + Deepseek 生成" ) if __name__ == "__main__": demo.launch(server_name="127.0.0.1", server_port=7860)

启动后浏览器访问 http://127.0.0.1:7860 就能进入问答页面。如果 7860 端口被占用，修改 server_port 参数即可。

python ingest.py python app.py

首次运行 ingest.py 会下载嵌入模型，之后每次新增文档重新运行一遍就能把新文档加入向量库。

6. 功能测试与效果验证

系统跑起来之后，需要从多个角度验证效果。建议准备一份测试问题清单，覆盖下面几种类型：

6.1 验证检索质量

在 query.py 中单独调用 retrieve 函数，查看问题检索到的片段是否相关：

python -c "from query import retrieve; docs, metas = retrieve('产品支持哪些导出格式'); print(docs[0]); print(metas[0])"

如果检索结果不相关，优先检查三点：

1. 文档切分是否合理：片段太短丢失上下文，太长引入噪声。
2. 问题表述是否偏离文档用词：RAG 依赖语义相似度，如果问题和文档完全没有共同表述，召回率会下降。
3. 嵌入模型是否匹配语言：中文文档应使用中文优化模型，目前配置符合。

6.2 验证生成质量

生成质量取决于两个因素：检索到的片段质量，以及 Prompt 约束能力。当前系统提示词要求模型严格基于资料回答，不能编造。如果 Deepseek 输出了资料中没有的信息，说明 Prompt 约束还不够强，可以补充“如果资料与问题无关，请返回无法回答”这类指令。

6.3 常见失败场景

从测试经验来看，最容易出现的问题有两个。第一，PDF 是扫描件或图片型 PDF，extract_text 提取不到内容，这种情况需要先做 OCR。第二，chunk 把完整句子切断，导致检索到的内容残缺，可以通过增大 CHUNK_OVERLAP 缓解。

7. 接口 API 与批量问答

7.1 FastAPI 接口封装

创建 api_server.py，把查询能力封装成 HTTP 接口，方便其他系统集成。

from fastapi import FastAPI from pydantic import BaseModel from query import answer app = FastAPI() class AskRequest(BaseModel): question: str top_k: int = 3 class ReferenceItem(BaseModel): source: str chunk: str class AskResponse(BaseModel): answer: str references: list[ReferenceItem] @app.post("/api/ask", response_model=AskResponse) def ask(req: AskRequest): result = answer(req.question, req.top_k) return result if __name__ == "__main__": import uvicorn uvicorn.run(app, host="127.0.0.1", port=8000)

启动接口服务：

python api_server.py

接口保存后，用 curl 测试：

curl -X POST http://127.0.0.1:8000/api/ask \ -H "Content-Type: application/json" \ -d '{"question": "产品支持哪些导出格式", "top_k": 3}'

返回格式示例：

{ "answer": "根据资料，产品支持 PDF 和 PNG 两种导出格式。", "references": [ { "source": "docs/product_manual.md", "chunk": "导出功能支持 PDF 和 PNG 格式..." } ] }

7.2 批量问答脚本

当需要一次性测试几十个问题时，手动在页面输入太慢。创建 batch_qa.py 批量调用接口并保存结果：

import json import time import requests API_URL = "http://127.0.0.1:8000/api/ask" questions = [ "产品有哪些功能？", "如何导出文件？", "支持哪些操作系统？", "有没有命令行版本？" ] results = [] for q in questions: try: r = requests.post(API_URL, json={"question": q}, timeout=120) r.raise_for_status() data = r.json() results.append({ "question": q, "answer": data["answer"], "references": data["references"] }) except Exception as e: results.append({ "question": q, "error": str(e) }) time.sleep(1) # 控制请求频率 with open("batch_results.json", "w", encoding="utf-8") as f: json.dump(results, f, ensure_ascii=False, indent=2) print(f"完成，共处理 {len(results)} 个问题，结果已保存到 batch_results.json")

批量任务需要注意三点：请求之间增加延时，避免触发 API 限流；每次请求设置超时时间；记录错误信息，方便排查单个问题失败原因。如果问题数量很大，可以改成从 CSV 文件读取问题列表，逐行处理。

7.3 文档批量入库

文档入库本身也支持批量。只需要把多个文档放入 docs 目录，运行一次 ingest.py 就会全部处理。如果要支持增量更新，需要引入文档 hash 去重，避免重复入库同样的内容。一个简单的方案是检查文件修改时间或计算文件 MD5 值，只有变化过的文件才重新入库。

8. 资源占用与性能观察

8.1 模型加载阶段

首次运行 ingest.py 或 query.py 时，会加载嵌入模型到内存。bge-small-zh-v1.5 模型文件约 100MB 级别，对内存的占用不大。同时 Chroma 持久化客户端会打开向量数据库文件，文件大小取决于文档数量。整个系统的资源占用集中在嵌入模型和向量数据库，Deepseek 部分只需要发送 HTTP 请求，本地不产生推理负载。

8.2 推理阶段

用户提问时，系统依次执行：问题向量化、向量库检索、Deepseek API 调用。前两步在本地 CPU 完成，耗时通常在几百毫秒到一两秒，取决于知识库大小和检索数量。最后一步是远程 API 调用，延迟取决于网络状况和 Deepseek 服务负载。

8.3 观察资源占用的方法

在 Linux 下可以用 top 或 htop 查看内存和 CPU 占用，Windows 直接打开任务管理器。如果本地跑了大模型，再用 nvidia-smi 观察显存占用。这套 RAG 方案本身不需要 GPU，所以不用太关注显存，但要注意网络请求的稳定性。

8.4 性能优化方向

如果知识库变大导致检索变慢，可以考虑几个方向：使用更小的嵌入模型减少向量化耗时；降低 TOP_K 减少检索输出量；使用 GPU 给嵌入模型加速；如果文本条目超过十万，可以迁移到 Milvus 这类专业向量数据库。

9. 常见问题与排查方法

下面是搭建和运行过程中最常遇到的问题，按照表格逐项排查：

如果启动服务时提示端口占用，Windows 可以用下面的命令找到占用进程：

netstat -ano | findstr :7860

然后把对应进程结束，或者直接换一个端口。

10. 最佳实践与使用建议

10.1 数据管理规范

建议把 docs 目录按主题分子目录存放，例如 docs/product、docs/faq、docs/operation。入库时在 metadatas 中加入更丰富的标签字段，比如部门、文档类型、更新时间，这样检索时可以按条件过滤，提高精确度。

10.2 切分策略调整

文本切分是 RAG 效果的关键变量。当前按固定字符切分的好处是简单，但会把段落、列表、表格拆散。对于结构化文档，建议按 Markdown 标题或段落先做一级切分，再对长段落做二次切分。具体做法是优先按\n\n分割，超过最大长度再按句子拆。

10.3 重排序与混合检索

当知识库文档较多时，单纯靠向量检索可能出现召回不准的问题。可以引入 Rerank 模型对 Top-20 结果重新排序，取前 3 条输入给大模型。也可以把 BM25 关键词检索和向量检索做混合，兼顾精确匹配和语义理解。这是 RAG 系统从入门走向工程化的必经一步。

10.4 接口服务安全

api_server.py 目前绑定 127.0.0.1，只能本机访问。如果要做内部服务，建议加上访问令牌校验，并控制接口并发。不要把接口直接暴露到公网，否则可能被滥用产生大量 API 费用。

10.5 隐私与版权合规

再次强调，通过 Deepseek API 调用会把检索到的文档片段发送到远程服务。处理机密文档时，建议使用本地部署模型替换远程 API。相关资料、文档的收集和入库，必须确认版权和使用授权，避免侵权风险。

11. 总结与下一步

这套 RAG 知识库问答系统最值得尝试的点，在于用最低的硬件成本跑通了一套完整的知识库问答链路。你不需要 GPU，不需要大模型训练基础，只要会一点 Python，就能把本地文档变成可检索、可问答、可追溯来源的智能问答系统。

建议先验证两个核心功能：一是文档入库后，检索结果是否准确命中问题对应的内容；二是 Deepseek 生成的回答是否严格基于检索片段。这两个点决定了整套系统的上限。

最容易踩的坑有两个：第一个是 PDF 文档解析后是空内容，导致检索不到任何信息；第二个是文本切分不当，把完整句子切断，导致回答质量下降。

后续可以沿着三个方向继续扩展：接入 Rerank 模型提升检索精度；增加多轮对话历史管理，让系统支持追问；把 Deepseek API 替换为本地模型，实现完全离线部署。如果你正在做 RAG 项目，建议把这套代码作为起点，一步步改造成适合自己的生产级系统。