企业官网建设流程全解析

RAG 可能是 2024 到 2025 年大模型落地最实在的一条技术路线。它不要求你重新训练模型，也不要求你有几十张显卡，而是通过“先检索、后生成”的方式，把企业自己的知识库接进大模型，让模型回答问题时不再凭空发挥。这次我们从零开始，把一套完整的 RAG 系统拆开讲清楚：环境怎么搭、组件怎么选、检索质量怎么看、接口怎么暴露、企业内部怎么落地，整个过程按可实操的流程走，不绕弯。

如果你关心本地部署、批量知识导入、接口调用、检索效果评估，这篇文章可以直接收藏。文中的代码和配置我尽量给到可直接替换的程度，实际路径和模型名称需要根据你本机环境调整。

1. RAG 核心能力速览

在动手之前，先明确 RAG 系统到底解决什么问题。普通大模型只能依赖训练时见过的数据，企业私有文档、实时数据、最新制度文件它都看不到。RAG 的思路是：接到用户问题后，先从知识库中检索出相关片段，再把片段和问题一起交给大模型生成答案，相当于给模型配了一个“开卷考试资料库”。

下面用一张表把 RAG 系统的核心能力列清楚，方便你快速判断自己需要哪部分。

自动补全界面显示的颜色与内容含义根据实际配置决定：如果模型文件放在本地，需要重点看磁盘空间和显存占用；如果使用大模型 API，则主要关注请求频率和 Token 消耗。

2. RAG 工作原理与系统架构

很多初学者把 RAG 简单理解成“把文档喂给模型”，这个理解不准确。RAG 的完整链路比这复杂，但拆开看并不难。

2.1 完整流程拆解

一套典型的 RAG 系统包含以下环节：

1. 文档接入：读取 PDF、Word、Markdown 等文件，处理表格、图片、页眉页脚等复杂元素。
2. 文本清洗：去除无关信息，保留正文结构和上下文。
3. 文本切分：把长文档切分成合适长度的文本块（Chunk），控制每个块的字符数和前后重叠。
4. 向量化：用嵌入模型（Embedding Model）把文本块转换为向量，每个块对应一个向量表示。
5. 向量存储：把向量写入向量数据库，同时保存原文和元数据，供后续检索和展示引用来源。
6. 检索：用户提问时，先把问题向量化，再在向量库中做相似度检索，选出最相关的 TopK 个文本块。
7. 重排序：用重排序模型对检索结果做二次打分，把真正相关的片段排到前面。
8. 生成：将用户问题和检索到的片段拼接到 Prompt 中，交给 LLM 生成带依据的回答。

这个流程不是固定死的。有些系统会跳过重排序，有些系统会加入混合检索（关键词 BM25 + 向量检索），还有系统会在检索前做意图识别和问题改写。企业级实现通常会逐步叠加这些组件。

2.2 常见架构选型

根据企业技术栈不同，RAG 落地主要有三种方向：

方案一：框架快速搭建

使用 LangChain、LlamaIndex、Dify 等框架，将文档加载、切分、向量化、检索、生成流程串起来。适合快速验证和中小规模知识库。Dify 这类平台还自带可视化界面，业务人员也能参与配置。

方案二：自研服务封装

使用 FastAPI 自己封装文档处理、向量库操作、检索问答服务。适合需要深度定制、要求精细控制检索逻辑和数据权限的企业。这种方案对工程能力要求更高，但可控性最好。

方案三：组件化组合

向量库使用 Milvus、Qdrant、Elasticsearch 等成熟组件，嵌入模型和 LLM 通过 API 服务接入，自己只写编排层。适合已有基础设施的团队，便于和现有权限体系、日志系统对接。

从零基础入门的角度，建议先用框架跑通端到端流程，再逐步替换底层组件，理解每个环节的职责。

2.3 关键设计点：文本切分与向量检索

RAG 效果好不好，一半取决于文本切分是否合理，另一半取决于检索质量。

文本切分不是简单按固定字符数切。不同文档类型适合不同策略：

• Markdown 文档按标题、段落、代码块结构切。
• PDF 文档需要先做版面分析，区分正文、表格、页眉页脚。
• Word 文档优先按段落和标题层级切。
• 代码仓库按文件、函数、类切。

切分参数中，chunk_size和chunk_overlap最常用。chunk_size决定每个文本块的最大字符数，chunk_overlap决定相邻块之间重叠多少字符，重叠可以避免关键内容恰好落在切分边界上导致检索丢失。

向量检索方面，核心是相似度计算方式。常见指标包括余弦相似度、内积、欧几里得距离。绝大多数应用使用余弦相似度，因为它不受向量长度影响，适合比较语义相关性。

注意：向量维度由嵌入模型决定，常见模型输出 768 维、1024 维或 1536 维向量，选向量库时不需要自定维度，按模型输出配置就行。

3. RAG 本地部署环境准备

不同团队的技术栈不一样，这里给出一套通用环境准备清单，覆盖开发机、云服务器和 Windows 本地三种情况。

3.1 硬件要求

如果你的机器显存不够，也可以把嵌入模型放在 CPU 上跑，LLM 使用云端 API，这样本地只需要处理文档解析和向量检索，对硬件要求明显降低。

3.2 软件依赖

RAG 系统通常依赖以下软件组件：

1. Python 3.9 或更高版本，建议 3.10 或 3.11，兼容性更好。
2. pip 包管理工具，用于安装依赖。
3. Git，用于克隆项目代码。
4. CUDA 和 cuDNN，如果使用本地 GPU 跑大模型。
5. PyTorch，嵌入模型和 LLM 的推理基础。
6. 向量数据库，如 Milvus、Qdrant、Chroma、FAISS。FAISS 是本地文件型向量库，适合入门；Milvus 适合企业级大规模部署。
7. 文档解析库，如 PyMuPDF、pdfplumber、python-docx、pandas，根据文档格式选择。
8. 大模型推理框架，如 vLLM、Ollama、Xinference，用于部署本地 LLM 服务。

3.3 Python 虚拟环境

建议使用虚拟环境隔离项目依赖，避免和系统 Python 环境冲突。

python -m venv rag_env source rag_env/bin/activate # Linux/macOS rag_env\Scripts\activate # Windows

激活后，后续所有 pip 安装命令都在虚拟环境中执行。

3.4 拉取项目代码示例

以自研 FastAPI 服务为例，项目骨架大致如下：

git clone https://github.com/your-team/rag-project.git cd rag-project pip install -r requirements.txt

如果你的项目是内部仓库，your-team/rag-project需要替换为真实地址。如果只用 Dify 或 LangChain，不需要另外拉项目，按官方文档启动即可。

4. RAG 系统安装部署与启动

这里以一套典型的“FastAPI + FAISS + 本地嵌入模型 + OpenAI 兼容接口”结构为例，逐步完成从安装到启动。这个结构适合入门，也能平滑迁移到 Milvus 和 vLLM 生产环境。

4.1 安装核心依赖

pip install fastapi uvicorn langchain langchain-community pip install sentence-transformers pip install faiss-cpu pip install pypdf pdfplumber python-docx pip install requests openai

如果使用 GPU 加速嵌入模型，可把faiss-cpu换成适合本机 CUDA 版本的faiss-gpu，并把sentence-transformers的推理设备设置为 CUDA。

4.2 准备嵌入模型

嵌入模型推荐使用BAAI/bge-base-zh-v1.5或BAAI/bge-m3，这类中文嵌入模型在文本检索任务上表现稳定，且支持直接通过 Hugging Face 或 ModelScope 下载。

from sentence_transformers import SentenceTransformer # 首次运行会下载模型，后续从本机缓存加载 embedding_model = SentenceTransformer("BAAI/bge-base-zh-v1.5")

如果下载模型比较慢，可以通过 ModelScope 镜像下载，或者提前手动下载后放到本地目录，加载时传本地路径即可。

4.3 文档解析与切分

文档解析的关键是保留有效内容、丢掉无效杂质。PDF 解析常见方式有两种：pdfplumber 适合处理文本型 PDF，PyMuPDF 适合批量提取和简单版面操作。

from langchain_community.document_loaders import PyPDFLoader from langchain.text_splitter import RecursiveCharacterTextSplitter loader = PyPDFLoader("knowledge_base/公司制度手册.pdf") documents = loader.load() text_splitter = RecursiveCharacterTextSplitter( chunk_size=500, chunk_overlap=50, separators=["\n\n", "\n", "。", "！", "？", "；", "，", " ", ""], ) chunks = text_splitter.split_documents(documents) print(f"切分后文本块数量: {len(chunks)}")

切分参数需要根据文档类型调整。chunk_size=500适合一般企业文档；代码类文档可以适当调小；长表格建议单独抽取，不要混在正文里切。

4.4 创建向量库并写入文档

把文本块向量化后写入 FAISS 向量库，同时保存原文，方便检索后展示引用来源。

from langchain.vectorstores import FAISS from langchain.embeddings import HuggingFaceEmbeddings # 使用本地嵌入模型 embeddings = HuggingFaceEmbeddings( model_name="BAAI/bge-base-zh-v1.5", encode_kwargs={"normalize_embeddings": True}, ) # 创建并持久化向量库 vectorstore = FAISS.from_documents(chunks, embeddings) vectorstore.save_local("vector_store/faiss_index")

这一步生成的faiss_index文件夹包含向量索引和文档元数据，后续启动问答服务时直接加载即可，不需要重复向量化。

4.5 启动问答服务

使用 FastAPI 封装一个简单的问答接口，支持“上传文档 + 检索 + 生成”的完整流程。

from fastapi import FastAPI, File, UploadFile from pydantic import BaseModel from langchain.vectorstores import FAISS from langchain.embeddings import HuggingFaceEmbeddings from langchain.chains import RetrievalQA from langchain.llms import OpenAI app = FastAPI(title="RAG 问答服务") embeddings = HuggingFaceEmbeddings( model_name="BAAI/bge-base-zh-v1.5", encode_kwargs={"normalize_embeddings": True}, ) vectorstore = FAISS.load_local( "vector_store/faiss_index", embeddings, allow_dangerous_deserialization=True, ) # 这里使用 OpenAI 兼容接口，可替换为本地模型服务地址 llm = OpenAI( base_url="http://localhost:8000/v1", api_key="EMPTY", model_name="qwen2.5-7b-instruct", ) qa_chain = RetrievalQA.from_chain_type( llm=llm, retriever=vectorstore.as_retriever(search_kwargs={"k": 4}), return_source_documents=True, ) class QueryRequest(BaseModel): question: str @app.post("/ask") def ask(request: QueryRequest): result = qa_chain.invoke({"query": request.question}) return { "answer": result["result"], "source_documents": [doc.page_content for doc in result["source_documents"]], }

这里base_url指向本地大模型服务地址，也可以换成任意 OpenAI 兼容的云端 API。如果没有本地模型，可以把llm替换为ChatOpenAI并填入真实的 API Key。

4.6 启动服务

uvicorn main:app --host 0.0.0.0 --port 8000 --reload

服务启动后，访问http://127.0.0.1:8000/docs可以看到 Swagger 接口文档，直接在里面调试。

如果端口被占用，换一个端口即可：

uvicorn main:app --host 0.0.0.0 --port 8001 --reload

5. RAG 功能测试与效果验证

服务启动后，不要急着部署，先做一轮完整的功能测试。RAG 系统的验证重点不仅是“模型能不能回答”，而是“回答有没有依据、引用是否准确、检索是否命中”。

5.1 检索命中测试

目的：确认向量库能检索到正确文档片段。

操作步骤：

1. 准备 10 到 20 个常见问题。
2. 对每个问题，调用向量库检索接口，检查返回的 TopK 片段是否包含正确答案。
3. 统计“第一个片段就命中正确答案”的比例。

如果命中率很低，优先检查文本切分是否合理。比如文档中一个问题的答案被切成了两半，检索自然找不到完整内容。

5.2 端到端问答测试

目的：验证“问题 -> 检索 -> 生成 -> 引用”全链路是否可用。

输入示例：

{ "question": "公司员工的年假天数是如何规定的？" }

预期结果：

• 返回内容包含具体年假天数。
• 返回内容包含引用来源，能看到该答案来自哪份文档。
• 回答内容能在检索片段中找到依据，不是模型凭空生成。

判断成功标准：

• 不出现“我是 AI，我不知道”这类无效回答。
• 不出现与文档内容相悖的编造信息。
• 引用来源和最终答案匹配。

5.3 知识库指标评估

RAG 系统的线上效果可以用几个核心指标来衡量：

建议建立一个固定测试集，重复改动切分参数、检索 TopK、重排序策略后，统一跑测试集对比指标，不要用单独一两个问题拍脑袋判断效果。

5.4 长文档与多轮对话测试

RAG 在长文档场景下的常见问题是：知识库内容很多，一个问题可能涉及多个文档。这时候需要测试：

1. 问题跨多个文档时，能否把所有相关内容都检索出来。
2. 多轮对话时，上一轮的检索结果是否影响下一轮回答。
3. 重复提问时，回答是否稳定，是否出现“这次一个答案、下次另一个答案”的情况。

多轮对话需要自己维护历史消息并重新检索，普通 single-turn RAG 是做不到的。如果要实现多轮，需要增加一个“问题改写”步骤：把“它的有效期是多长”改写成包含上上文主题的完整问题，再去做检索。

6. RAG 接口 API 与批量任务

RAG 系统只做本地调试还不够，企业落地需要把能力暴露成接口，让其他系统调用。同时，知识库不能每次手工导入，批量更新是刚需。

6.1 接口设计建议

一套完整的 RAG 服务接口至少包含以下能力：

6.2 批量上传接口示例

import os import glob from fastapi import FastAPI, File, UploadFile from langchain_community.document_loaders import PyPDFLoader from langchain.text_splitter import RecursiveCharacterTextSplitter app = FastAPI() @app.post("/batch_upload") async def batch_upload(directory: str): # 目录路径需要按实际环境校验，防止路径穿越 files = glob.glob(os.path.join(directory, "*.pdf")) all_chunks = [] for file in files: loader = PyPDFLoader(file) documents = loader.load() text_splitter = RecursiveCharacterTextSplitter( chunk_size=500, chunk_overlap=50, ) chunks = text_splitter.split_documents(documents) all_chunks.extend(chunks) # 增量写入向量库 vectorstore.add_documents(all_chunks) vectorstore.save_local("vector_store/faiss_index") return {"processed": len(files), "chunks": len(all_chunks)}

这里的关键是增量入库。企业知识库每天都有新文档，不能每次全量重建。FAISS 支持add_documents，Milvus 和 Qdrant 也支持增量写入。加入文档级元数据（如文件名、更新时间、部门归属）是后续做权限控制的基础。

6.3 curl 调用示例

启动服务后，可以用 curl 测试问答接口：

curl -X POST "http://127.0.0.1:8000/ask" \ -H "Content-Type: application/json" \ -d '{"question": "绩效考核周期是多久？"}'

6.4 Python 调用示例

如果你是接口调用方，可以用 requests 调通后集成到自己的系统里：

import requests url = "http://127.0.0.1:8000/ask" payload = { "question": "员工入职需要提交哪些材料？" } response = requests.post(url, json=payload, timeout=120) if response.status_code == 200: data = response.json() print("答案:", data["answer"]) print("来源:", data["source_documents"]) else: print("请求失败:", response.status_code)

6.5 批量任务设计注意点

批量导入不是简单地循环调用接口，要注意以下几点：

1. 文件格式校验：只接受白名单后缀，防止异常文件进入解析流程。
2. 幂等处理：同一份文档重复导入时，先比对文件名和摘要，避免重复向量占空间。
3. 失败重试：单个文件解析失败不能影响整个批次。
4. 日志和任务状态：每个导入批次记录进度，方便排查。

{ "batch_id": "20250301_001", "total_files": 200, "success_count": 198, "failed_count": 2, "failed_files": ["坏文件1.pdf", "坏文件2.pdf"] }

7. RAG 资源占用与性能观察方法

RAG 系统的性能瓶颈通常不在写代码，而在资源调度。下面给出一套观察方法和常见优化方向，具体数值需要在你的机器上实测确认。

7.1 显存占用观察

RAG 全链路中，显存占用主要来自两部分：

1. 嵌入模型：体积小，显存占用通常很低，几百 MB 量级。
2. LLM 推理模型：体积大，7B 模型量化后通常需要 6G 到 12G 显存，14B 模型需要更多。

观察显存最直接的方式是使用nvidia-smi：

watch -n 1 nvidia-smi

重点观察：

• 首次请求时显存是否暴涨，服务是否稳定。
• 并发请求时显存是否超过显卡上限。
• 多次请求后是否有显存泄漏。

如果显存不足，优先尝试：

• 使用 4-bit 量化模型。
• 降低最大生成长度。
• 限制并发请求数。
• 将嵌入模型放在 CPU 上推理，把 GPU 让给 LLM。

7.2 CPU 与 GPU 推理差异

嵌入模型在 CPU 上推理也能接受，文档量不大时性能差距不明显。但 LLM 的 CPU 推理速度会明显慢于 GPU，尤其在生成长回答时。

如果你只有 CPU，建议使用云端大模型 API，本地只做文档解析和向量检索，这样流程能跑通，只是请求要经过网络。

7.3 检索性能与文档量的关系

向量检索速度随文档量增加而变慢，但大多数企业场景在几十万级文本块下，FAISS 的检索延迟仍然很低。真正影响性能的是：

• 文档解析时长：PDF 页数多时，解析耗时明显。
• 向量化时长：文本块数量大时，向量化需要较长时间，建议提前离线完成。
• 重排序耗时：加入 rerank 模型后，首 token 延迟会增加几十到几百毫秒，需要权衡。

7.4 如何降低响应延迟

1. 向量化提前做：文档入库时一次完成向量化，问答阶段只做检索和生成。
2. 结果缓存：热门问题可以缓存答案，避免重复请求 LLM。
3. 限制检索范围：按知识库分类或部门过滤，减少不相关向量参与计算。
4. 使用流式输出：大模型生成答案时启用 SSE 流式返回，用户感知延迟更低。

7.5 端口与进程管理

本地反复调试时，uvicorn --reload可能留下残留进程，导致端口被占用：

lsof -i :8000 kill -9 <PID>

Windows 下可以这样查：

netstat -ano | findstr :8000 taskkill /PID <PID> /F

8. 常见问题与排查方法

RAG 系统涉及多个组件，遇到问题时不要慌，先确定问题出在哪个环节：文档解析、文本切分、向量化、检索还是生成。

排错顺序建议：先看日志，再测检索，最后看生成。很多 RAG 问题根源在检索环节，生成只是把检索到的错误内容换了种说法。

9. RAG 最佳实践与企业级落地建议

从零基础到可以 demo，很多团队一两天就能跑通。但要把 RAG 真正用到企业内部，还需要在工程和合规层面做更多工作。

9.1 分阶段推进

第一阶段，先搭最小可用版本，用少量测试文档验证流程，重点观察检索命中率和回答质量。

第二阶段，扩大知识库范围，建立评估测试集，反复调整切片策略、检索策略和 Prompt，直到效果稳定。

第三阶段，接入权限控制，按部门、角色限制文档可见范围。企业知识库中不是每个人都能看所有文档，如果没有权限隔离，RAG 会导致严重的信息泄露。

第四阶段，完善日志和监控，记录每次问答的检索结果、引用来源和用户反馈，持续优化。

9.2 文本切分经验总结

从实际项目经验看，文本切分不要一刀切使用固定字符数，推荐按文档类型配置：

• 规章制度类文档：按章节和条款切，保留条款编号。
• 产品手册类文档：按功能模块切，保留小标题。
• 技术文档：按代码块和说明段落切。
• 聊天记录类数据：按会话和消息组切。

切分后一定要做抽样检查，至少人工看 20 到 50 个文本块，确认没有语义断开和关键信息丢失。

9.3 检索增强的进阶手段

如果基础向量检索命中率不够，可以逐级增加以下手段：

1. 混合检索：向量检索 + BM25 关键词检索，用 RRF 算法合并排序。适合专业术语多、命名实体固定的场景。
2. 重排序：使用bge-reranker等重排序模型对 TopK 结果二次打分，可以明显提升排序准确率，但会增加延迟。
3. 问题改写：多轮对话和口语化提问时，先把问题改写成规范、完整的检索语句，再进向量库查询。
4. 元数据过滤：按文档类型、部门、时间范围缩小检索范围，提升精确度。
5. Agent 化检索：当问题复杂、需要多步查询或访问多个知识库时，可以让 LLM 决定先检索哪个库、接着查什么，这就是目前热门的 Agentic RAG 方向。

9.4 合规与安全边界

这一条要反复强调。RAG 系统接入企业私有数据后，需要满足三个底线：

1. 数据授权：导入知识库的文档必须有合法来源和处理授权，不能把未授权抓取的他人文档、版权内容直接放进知识库。
2. 隐私保护：涉及个人隐私、经营敏感信息的内容，要按最小必要原则管理访问范围，避免员工通过 RAG 越权获取数据。
3. 内容审核：RAG 输出内容需要记录引用来源，防止大模型生成“有依据编造”的误导信息。涉及人脸、声音、医疗、金融等敏感场景时，还要做更严格的人工复核。

如果知识库包含涉密或受控内容，更要在网络隔离、接口鉴权、日志留存方面同步建设。RAG 本身是工具，做得好能帮人，管不好会变成泄露渠道。

10. 总结与下一步

从零开始搭建一套 RAG 系统，核心路径已经清楚了：文档接入 -> 文本切分 -> 向量化 -> 向量存储 -> 检索 -> 重排序 -> LLM 生成 -> 接口服务。这套流程不依赖豪华硬件，普通开发机就能跑通，企业生产环境则需要在向量库、权限、日志和评估体系上补齐。

建议你上手时先做三件事：

第一，准备一份你熟悉的领域文档，按文章中第四部分的代码跑一遍完整流程，确认自己能说清每个环节在做什么。

第二，建一个 20 个问题的固定测试集，分别测试基础检索、跨文档查询和长文档问答，记录指标变化，这是后续优化的起点。

第三，把服务部署成 HTTP 接口，用 curl 和 Python 各调一次，确认接口能通、结果能解析，然后再考虑把批量导入和权限控制加进来。

最容易踩的坑通常是文本切分不合理和检索命中率低。与其急着堆模型，不如先用测试集诊断检索质量，再决定是否加强重排序或混合检索。

下一步可以关注三个方向：把 FAISS 换成 Milvus 或 Qdrant，解决更大规模向量存储问题；接入 vLLM 或 Ollama 部署本地 LLM，减少对外部 API 的依赖；引入 Agentic RAG，让系统能处理多跳检索和复杂任务拆分。这套路径走完，基本就到了企业级 RAG 的实战门槛。