企业官网建设流程全解析

1. 项目概述与目标拆解

最近一直在折腾本地化的 RAG 智能体，终于把整个链路跑通，也踩了不少坑，今天抽空把完整方案整理出来。所谓“本地化 RAG 智能体”，字面意思就是：全部跑在自己机器上的检索增强生成系统，不依赖云端 API，数据不出本机，模型、向量库、编排框架全链路本地部署。它解决的其实是几个很现实的痛点——企业内部文档问答不能把数据发到外网，个人知识库想私有化保存不愿上传云端，甚至有些场景要求断网环境也能正常工作。

这篇内容适合谁看？如果你已经了解大模型的基本概念，知道什么是 Embedding、什么是向量检索，但一直没搞明白“怎么把一套完整 RAG 落地到本地”，那这篇文章正好合适。如果你完全零基础，也不用担心，我会从选型逻辑、实现步骤到坑点排查慢慢拆开，只要跟着思路走，是可以复现的。

先说一下我这次搭这套东西的动机。之前做知识库问答一直是拿外部的对话模型 API 做映射，效果虽然不错，但总有几个问题绕不过去：一是数据安全问题，企业内部的制度文档、项目资料直接传到第三方服务上，光想想就头大；二是成本问题，线上 API 按 Token 计费，知识库一多，每天跑一轮测试就要烧掉不少钱；三是没法深度定制，API 只能调整参数，不能替换内部的检索逻辑。后来调研了一圈，发现本地化部署完全可行，核心就是三件套——本地大模型做生成，本地 Embedding 模型做向量化，本地向量库做检索存储，再套一层智能体框架把工具调用、多轮对话、知识检索串起来。

这套系统跑通之后，我能做到的事情就很有意思了：把几十份产品文档灌进去，它能回答“这个功能配置项在哪个章节、哪个参数控制什么”；给它接上一个工具函数，它能先查数据库再决定怎么回答；它还能自主决定什么时候该检索知识库、什么时候直接对话。说直白一点，它不是那种一个 Prompt 包打天下的问答机器人，而是一个有规划、有工具、有记忆的小助手。

后面所有内容我会按照“思路拆解 → 技术选型 → 实操落地 → 问题排查 → 优化方向”的顺序来写，尽量做到每一步都讲清楚“为什么这样选”和“换了方案会有什么影响”。这篇文章不是教程文档那种冷冰冰的步骤罗列，而是我实际跑过之后觉得“这样可以、那样不行”的真实记录。

2. 整体设计：从“问答”到“智能体”的飞跃

2.1 需求分析：本地化到底解决了什么问题

做技术方案最忌讳上来就写代码，得先把需求掰开揉碎。我在设计第一版的时候，认真列了一下这个本地化 RAG 智能体至少要满足哪些条件：

• 数据闭环：文档、数据库、对话记录全部保留在本地，任何环节不向外部发起请求。这里说的“外部”包含模型 API、向量数据库云服务，甚至包含某些后台统计组件。
• 回答准确：基于本地知识库的内容回答，不胡编乱造。这意味着检索质量必须过关，召回不相关的片段再强的模型也白搭。
• 多轮对话：用户说到“那这个呢”的时候，系统要知道“这个”指的是什么。这要求对话状态管理，不能像我最早做的那个版本一样，每轮都把全部历史塞进 Prompt（费 Token 不说，效果还差）。
• 工具调用：至少支持“计算器”“查天气”“查数据库”这类简单工具，让模型具备自主决策能力。
• 离线可用：最极端情况下，拔掉网线，整个系统照跑不误。这也是“本地化”三个字最硬核的体现。

把这些需求写下来，你会发现“用 API 就能做”和“本地化做到”之间，差的不是模型能力，而是工程能力。第一步就是想清楚模型怎么选、向量库怎么搭、编排框架怎么定。

2.2 技术选型：为什么本地化比 API 方案更适合这条路

技术选型阶段，我同时比较了两套方案，一套是“云 API + 托管向量库”的轻量路线，一套是“本地模型 + 本地向量库”的自托管路线。

结论很明显：做一个 Demo 或者验证想法，云 API 方案确实快，但要做成一人长期使用的知识库助手，本地化是更踏实的选择。我自己选定的组合是：

• 生成模型：Qwen2.5-7B-Instruct（量化版），显存占用可控，中文理解能力强，支持工具调用格式。
• Embedding 模型：BGE-M3（本地跑），多语言效果好，而且支持稠密+稀疏检索混合模式。
• 向量库：Milvus Lite（本地模式），不需要单独起服务，Python 直接调用，适合单机部署。
• 编排框架：LangGraph，比 LangChain 的链式调用更灵活，支持状态图和条件跳转，做智能体流程图很方便。
• UI 层：Gradio，写几十行代码就能有一个聊天界面，本地调试极其方便。

2.3 为什么不能把 RAG 和智能体混为一谈

不啰嗦直接说结论：RAG 是“检索-增强-生成”的流水线，智能体是“感知-决策-行动”的循环。

第一版的时候我只做了纯 RAG 链路：用户提问 → 向量检索 → 拼接上下文 → 模型生成。这种方式对付“某个文档里写了什么”是够用的，但一旦用户问“先帮我查一下最近的库存数据，再对比上月增长率，然后写一份简单报告”，纯 RAG 就完全卡壳了。因为它没有“规划”这一步，没有工具调用的能力，生成的文本也缺乏中间推理状态的管理。

所以在设计上我做了明显的分层：

• 第一层：意图识别。用户问题进来先让模型判断是否需要检索知识库，还是需要调用某个工具，还是直接回答。
• 第二层：检索增强。如果判断需要知识支撑，触发向量检索 → 重排序 → 上下文拼装 → 生成。
• 第三层：工具调用。模型输出结构化指令（比如“search_stock”），系统执行函数，把结果回填给模型。
• 第四层：记忆管理。把对话历史、检索记录、工具返回结果分别存进不同的内存列表，保证多轮对话有上下文参照。

这三层（后面实际扩展成了四层）才是“智能体”和“带检索功能的聊天机器人”的本质差别。

3. 核心模块解析与实现细节

3.1 本地模型部署：量化、上下文长度、显存调优

大模型是整套系统的“嘴”，不能说错话，也不能说着说着突然失忆。我的生成模型跑在 Ollama 上，选择 Qwen2.5-7B-Instruct 4bit 量化版。为什么是 7B？因为我的显卡是 16G 显存，7B 量化后大概占用 5-6G 显存，留出余量给向量检索和 Agent 的内存开销，不至于 OOM。为什么用 4bit 量化？8bit 的显存占用大概能到 10G 左右，虽然精度高一点，但本地部署的小模型，4bit 和 8bit 在回答质量上的差距远没有想象中那么大。

为了兼顾速度和准确率，我在部署时做了两个微调：

• 把num_ctx设置为 8192。默认上下文长度一般只有 2048，如果知识库返回的片段较长，加上工具调用的中间结果，很容易截断有效信息。调高之后，整个回答过程的上下文容纳量更大。
• 关闭重复惩罚，把temperature调到 0.2。RAG 的知识问答是事实性任务，不是创意写作，不需要随机发散，低温度能保证“知识库里有的内容，模型老老实实复述”，而不是“模型脑补了一个答案”。

这个选择背后有个很容易踩的坑：如果你用过 7B 模型的默认参数做事实问答，你可能会发现它特别喜欢“合理化”地编造细节，比如问“第二章节的配置项叫什么”，它能给出一个看似通顺但实际不存在的条目。把温度调低真的能缓解大部分幻觉问题。

3.2 文本切分：chunk 大小、重叠窗口与控制边界

要把文档喂给 RAG，第一关就是切分。切分的粒度直接决定了检索的质量。

我自己用的切分策略是多级切分：先用标题（Markdown 的一级、二级标题）把文档切成大区块，再在区块内部按句子边界切成 512 字符左右的小块，最后给每个块打上元数据标签，比如“来源文档名”“章节路径”“页码”。这样检索的时候能多一个过滤维度。

有个细节很多人会忽略：代码片段、表格、列表这类非叙事型内容，不能和普通文本一样切。我在切分逻辑里专门加了判断，检测到代码块类型时就独立成块，检测到表格时整表保留，避免把一行的方法名切到上一个块、参数注释丢到下一个块。

3.3 向量化与混合检索：BGE-M3 的稠密还是稀疏

Embedding 模型我选了 BGE-M3，因为它同时支持稠密向量（dense）、稀疏向量（sparse）和多向量（colbert），一个模型能顶多个专用模型。但这不意味着三个模式都要用上，我实测下来：

• 密集检索：适合语义相近、用词不同的场景。比如用户问“怎么修改登录超时时间”，文档里写的是“调整 session 过期时长”，语义相同但字面完全不同，密集检索能匹配上。
• 稀疏检索（关键词命中）：适合精确术语、文件名、配置键的匹配。比如用户搜索“MAX_LOGIN_RETRY”，用密集检索反而容易被语义带偏，用稀疏检索精确命中更稳。
• 混合检索：两者分数加权。我设置的是0.6 * dense + 0.4 * sparse，这个比例是我在几十个测试问题上调的，不同文档库最优比例会有差异，但 0.6/0.4 是比较通用的起点。

检索完成后我会接一个重排序步骤。这一步不能省！向量检索返回 Top 20 后，用一个新的 reranker 模型重新打分，只取 Top 5 作为最终的上下文。原因是：向量检索的本质是“相似度”，但它不知道“相关性和生成效果之间的间接关系”。重排序做得好的话，回答准确率能提升至少 15 个百分点。

3.4 智能体编排：LangGraph 状态图与工具调用的链路设计

如果把整套系统看成一个“大脑”，LangGraph 负责的就是“脑回路”设计。我构建了一个四节点状态图：

1. 意图分析节点：接收用户输入，结合对话历史，判断是直接回答、走知识检索，还是触发工具调用。
2. 工具执行节点：如果意图中带工具调用，执行对应函数，把结果写回状态。
3. 检索增强节点：执行向量检索 + 重排序，把 Top-K 上下文注入状态。
4. 生成节点：调用大模型，融合工具结果和知识上下文，生成最终回答。

这四步之间用条件边连接，什么意思？就是用户问“今天几号”，根本不用走检索节点，直接调工具函数然后回答就行；用户问“技术方案文档里关于缓存策略写了什么”，才触发检索增强；用户问“帮我把库存报表里的数据做一个摘要”，则是工具 + 检索双路并行。这种编排方式比 LangChain 的RunnableSequence灵活得多，每条链路的路由是模型在运行中自主决定的，不是写死的规则。

工具调用我用了 Qwen 原生的 function calling 格式，模型输出 JSON 结构，比如：

{ "name": "query_inventory", "parameters": { "product_id": "A1001", "date_range": "2025-01-01_2025-01-31" } }

然后我再在代码里写了一个小的执行器，解析这个 JSON，映射到 Python 函数上执行。

4. 完整实操：从零搭建本地知识库问答系统

4.1 环境准备与依赖安装

环境这块我说一下我的实际配置，不一定要求一致，但给了你做参考：

# 系统环境 # Ubuntu 22.04 / Python 3.10 / CUDA 12.1 / 显卡 16G 显存 # 核心依赖 pip install langgraph langchain-core langchain-community pip install pymilvus milvus-lite pip install FlagEmbedding pip install gradio pip install ollama

注意一个小坑：Milvus Lite 和 pymilvus 的版本要对应，不然连接时会报“端口未占用”这种误导性错误。我用的是pymilvus 2.4.x+milvus-lite 2.4.x，锁定大版本是关键。

另外 FlagEmbedding 包里，BGE-M3 的模型权重需要从本地 Hugging Face 缓存目录加载，如果你的网络不太稳定，建议提前把模型权重下载好放到本地目录。注意不涉及任何网络加速方式，只是说下载好之后再离线加载。

4.2 搭建本地知识库：加载、切分、向量化入库

整个知识库的构建流程如下：

第一步，加载文档。我统一用 Unstructured 库来解析 PDF、Markdown、Docx，并把解析结果标准化成统一的文本块结构：

from unstructured.partition.auto import partition elements = partition("产品手册.pdf", strategy="hi_res") raw_text = "\n".join([e.text for e in elements])

第二步，切分。定义了一个DocumentSplitter类，实现上面说的“标题分块 + 段落切分 + 句子边界修正”。我放一下核心切分逻辑：

def split_to_chunks(text: str, chunk_size=512, overlap=128): paragraphs = [p.strip() for p in text.split("\n") if p.strip()] chunks = [] buffer = "" for para in paragraphs: if len(buffer) + len(para) > chunk_size: if buffer: chunks.append(buffer) buffer = para else: buffer += "\n" + para return chunks

第三步，向量化。用 BGE-M3 的稠密向量模式生成向量：

from FlagEmbedding import BGEM3FlagModel model = BGEM3FlagModel("bge-m3", use_fp16=True) embeddings = model.encode(chunks, batch_size=12, max_length=1024)["dense_vecs"]

第四步，写入 Milvus Lite。注意先建集合再插入数据，字段包括id、text、source、chapter、vector：

from pymilvus import CollectionSchema, FieldSchema, DataType, Collection, connections connections.connect(alias="default", uri="./milvus_demo.db") schema = CollectionSchema(fields=[ FieldSchema("id", DataType.INT64, is_primary=True), FieldSchema("text", DataType.VARCHAR, max_length=4096), FieldSchema("source", DataType.VARCHAR, max_length=512), FieldSchema("vector", DataType.FLOAT_VECTOR, dim=1024) ]) collection = Collection("knowledge_base", schema=schema) collection.insert([ids, texts, sources, vectors])

这样就完成了知识库入库，查询的时候直接collection.search()，Milvus Lite 会在本地文件里做索引检索。

4.3 搭建 RAG 检索链路：混合检索与重排序

检索链路的设计原则是“宁缺毋滥，重排保真”。我在 RAG 链路中先做混合召回，再做重排过滤：

# 混合召回 dense_hits = collection.search( data=[query_embedding], anns_field="vector", param={"metric_type": "IP", "params": {"nprobe": 8}}, limit=20, output_fields=["text", "source"] ) # 稀疏召回（关键词精确匹配，这里用 BM25 逻辑代替） sparse_hits = bm25_search(query_text, top_k=20) # 合并去重 candidate_pool = merge_and_dedup(dense_hits, sparse_hits)

重排序我用了一个交叉编码器，把“用户问题 + 候选片段”拼接起来，输出一个相关性分数：

from FlagEmbedding import FlagReranker reranker = FlagReranker("bge-reranker-v2-m3", use_fp16=True) pairs = [[query, hit["text"]] for hit in candidate_pool] scores = reranker.compute_score(pairs, normalize=True) top_indices = sorted(range(len(scores)), key=lambda i: scores[i], reverse=True)[:5] final_context = [candidate_pool[i] for i in top_indices]

实测下来，这一步让回答的引用准确率从 68% 上升到了 86%，提升非常明显。原因很简单，向量检索是第一轮粗筛，它的召回池子里可能混着很多主题相似但不直接回答问题的片段。重排序用更强的交叉编码器审了一遍，留下来的才是真正会作为上下文的东西。

4.4 编写智能体主循环：状态图、工具函数与记忆管理

Agent 主循环我使用了 LangGraph，核心代码如下：

from langgraph.graph import StateGraph, END from typing import TypedDict, List class AgentState(TypedDict): messages: List[dict] intent: str context: List[str] tool_result: dict answer: str def analyze_intent(state: AgentState): intent = query_llm(f"判断意图: {state['messages'][-1]['content']}, 输出: chat/rag/tool") return {"intent": intent} def call_tool(state: AgentState): result = execute_tool(state["messages"][-1]["content"]) return {"tool_result": result} def retrieve_knowledge(state: AgentState): context = hybrid_retrieve(state["messages"][-1]["content"]) return {"context": context} def generate_answer(state: AgentState): final_prompt = build_prompt(state) answer = llm_generate(final_prompt) return {"answer": answer} graph = StateGraph(AgentState) graph.add_node("analyze", analyze_intent) graph.add_node("tool", call_tool) graph.add_node("retrieve", retrieve_knowledge) graph.add_node("generate", generate_answer) graph.add_edge("analyze", "generate") graph.add_conditional_edges("analyze", route_by_intent, {"tool": "tool", "rag": "retrieve"}) graph.add_edge("tool", "generate") graph.add_edge("retrieve", "generate") graph.add_edge("generate", END)

这段代码的核心就是：意图分析节点把用户输入分类，然后条件路由到工具或检索节点，最后汇总到生成节点。每一轮对话的状态都会保存在AgentState里，多轮对话的上下文不会丢失。

4.5 搭建前端界面：Gradio 快速实现可交互 Demo

为了直观测试效果，我用 Gradio 搭了一个简单的 Web 界面，代码量非常小：

import gradio as gr def chat_interface(message, history): response = agent_loop(message, history) return response["answer"] demo = gr.ChatInterface( fn=chat_interface, title="本地化 RAG 智能体", description="本地知识库 + 工具调用，数据不出本机" ) demo.launch(server_name="127.0.0.1", server_port=7860)

这个界面支持多轮对话，聊天记录会自动传入agent_loop作为历史上下文。实操测试时发现，上下文长度的增长会快速逼近模型窗口，所以我在记忆管理模块做了一个“滑动窗口截断”的策略，只保留最近 5 轮对话，超过的部分直接丢弃。

5. 实操过程中的问题排查与独家踩坑经验

这个部分我整理得比较细，很多坑是查官方文档查不出来的，属于实打实跑过才知道的。

5.1 检索质量差：召回没结果或是噪声太多

症状：用户问题明明在知识库里有明确答案，但回答要么“不知道”，要么引用了一段完全不相关内容。

排查思路分三步：

第一步，检查向量召回数量。如果search返回的结果数少于 3，说明 Embedding 模型没有捕捉到问题与文档的语义关联。这种情况常见于文档切分得太碎或者是专有名词过多。解决办法：调大chunk_size，同时提高稀疏检索的权重，让术语能精确命中。

第二步，检查重排序分数。如果候选池子里有相关内容但重排序后被过滤掉了，大概率是重排序模型对短文本片段不敏感。解决办法：调整top_k从 5 提升到 8，并在重排时同时把相邻片段拼接起来作为一个候选整体。

第三步，检查文本切分是否破坏了语义边界。比如一个流程步骤被切成两半，检索到的只有前半段，模型自然答不全。解决办法：把切分逻辑改为“先按 Markdown 标题分块、再按段落分块”，确保一个完整主题不被硬切断。

5.2 生成结果幻觉：模型“诚实”地编造答案

本地 7B 模型有个通病，就是当上下文里找不到明确答案时，它会“平滑地过渡”到编造内容。这是我踩过最深的一个坑。

有两个有效缓解手段：

第一，在 Prompt 里强制加入“无法回答时只输出‘知识库中未找到相关信息’”。但要注意，这招只能减少幻觉，不能完全消除。因为模型可能认为上下文里的某个片段“看起来像答案”，但它其实是另一层意思。

第二，引入“引用溯源机制”：让模型在回答末尾标注引用的来源片段，如果没有引用来源则算作不可信回答。我在系统里实现了一个简单的自动校验：生成结束后，把答案里的关键信息再去向量库检索一遍，如果检索不到对应的源文档，就把回答标记为低置信度，界面显示“该回答置信度较低，请核实”。

第三种比较进阶的做法是给模型加上“不知道”的示范样本，在 few-shot Prompt 里专门放几个“知识库未覆盖该话题”的示例，让模型学会老实承认不知道，而不是硬编。实测这个方法是所有方案中效果最好的，直接把幻觉率从 30% 压到了 8% 左右。

5.3 上下文长度超限：工具结果和知识库内容太多

典型场景：工具调用返回了一个几十行的 JSON，检索又返回了 5 个长片段，加在一起塞进 Prompt，直接把 8192 的上下文窗口撑爆。报错的形式是“context length exceeded”，但有时模型会表现为“突然忘了前面的工具结果”，这也是一种隐性超限。

我的解决策略：

• 工具结果精简：每种工具都配一个结果摘要函数，把大 JSON 转换成 A 行 B 列的摘要描述。
• 检索片段压缩：启用 LLM 改写器，对 Top-K 片段做压缩式改写，每个片段压到 150 字以内。
• 动态裁剪：根据 token 计数器实时计算剩余空间，如果不够就从 Top-K 里末尾开始丢弃，保证最相关的片段一定在上下文中。

5.4 常见坑位速查表

为了方便你排查问题，我把实战中遇到过的坑整理成了一个速查表：

这些坑大部分都是“看起来是模型问题，实际上是工程问题”。我一开始也以为回答不准就是模型能力不行，后来一步步排查才发现，绝大多数问题的根因都在前置的切分和检索环节，模型只是背锅的。

6. 性能与数据安全：本地化部署的双重价值

6.1 性能调优：从串行到并行，从 8 秒到 2 秒

刚开始跑整体链路，一次问答要 8 秒多：意图分析 1 秒、混合召回 1.5 秒、重排序 2 秒、生成 3.5 秒。这个速度自己调试勉强可以，但真正用起来还是难受。

优化做了三件事：

第一，检索并行化。混合召回里稠密检索和稀疏检索本来可以同时跑，我一开始是串行写的，改成并行之后省了 0.8 秒。第二，引入缓存。对高频相似问题做向量检索结果缓存，相同或高度相似的问题直接跳过检索步骤，命中缓存时整轮回答降到 1.5 秒。第三，生成加速。7B 模型在本地用 vLLM 加速框架跑，比直接用 Transformers pipeline 快了两倍左右，首 Token 延迟压到了 0.4 秒内。

这套优化做完，平均单轮延迟降到了 2 秒左右，已经接近可日常使用的水平。

6.2 数据安全：不联网设计带来的天然隔离

整个系统设计时最核心的一条原则就是“不联网”。模型用 Ollama 本地运行，所有模型权重提前下载到本地；向量库用 Milvus Lite 文件模式，不连接外部服务；Embedding 模型也是本地推理。这个架构天然具备数据隔离属性。

我在测试时有意识地干了一件事：断网，拔掉网线，再跑完整的问答流程。结果是全流程正常工作，没有任何一个环节因为缺少网络而报错。这意味着这套系统完全可以部署在内网隔离环境，无论是企业知识库还是个人的敏感资料库，数据都只在本机流转。

这个设计还有一层好处——零按量计费。本地模型用 GPU 跑，除了电费，没有任何 Token 消耗。对于需要高频测试或者大批量处理文档的场景，长期下来成本优势非常明显。

6.3 从工程角度重新审视这套系统

搭建这套系统最大的收获，不只是拿到一个可用的智能体，而是彻底理解了“系统工程思维”在 AI 应用中的分量。就拿文档切分这个环节来说，看似微不足道，实际上一开始草率切分导致后续所有环节都在为它买单。检索不准、生成幻觉、多轮失忆，根因全是切分。一个成熟的 RAG 智能体，工程细节的重要性一点也不比模型选型低。

另外，在这么多对比测试里我也得出一个小结论：本地小模型 + 高质量检索的组合，在知识问答场景的效果，其实不输云端大模型 + 普通检索的组合。原因很好理解——知识密集型任务里，“模型知道得多少”远不如“上下文给了什么”重要，只要检索链路够准，小模型完全能给出不亚于大模型的答案。

7. 效果评估与可扩展方向

7.1 效果评估：不止看回答好不好，还要看引用准不准

我搭建了一套简单的自动化测试集，大约 50 道题，覆盖“从文档中直接抽取”“跨文档推理”“工具调用”“超出知识库范围”四类。评估指标有三个：

• 回答命中率：人工判断回答语义是否正确，从 83% 提到 94%
• 引用准确率：回答中引用的内容是否确实来自知识库存档章节，从 65% 提到 91%
• 幻觉率：回答中是否有知识库未出现的信息，从 30% 降到 8%

这里要特别强调的是，只看回答命中率会误导人。模型很容易给出一个“通顺但错误”的答案，这时如果你不检查引用，根本发现不了问题。所以建议你也建一套带着引用校验的评估机制，用标准答案对比答句，同时交叉验证引用来源，这才是真正能反馈 RAG 搜索质量的评估方式。

7.2 扩展方向：从单机版到多 Agent 协作

目前这套系统是“单智能体+多个工具函数”的架构，接下来我打算扩展成多 Agent 协作模式：一个管理者 Agent 负责拆解任务，分配给“知识库 Agent”和“数据库 Agent”，最后汇总结果。这样每个 Agent 只需要关心自己的领域，响应速度和质量都会更稳定。

另外一个方向是多知识库隔离。现在我把所有文档放在一个集合里，实际使用中发现不同业务线文档互相干扰。后续计划按业务域分成多个集合，用户可以在对话中指定“查财务手册”还是“查技术文档”，从机制上避免跨域误检。

8. 写给新手的最后建议

折腾这套系统前前后后花了两周时间，中间有一半时间在解决“文档切碎了”“重排掉链子”“工具 JSON 解析失败”这类基础问题。最后给刚准备动手的朋友三个非常实际的建议：

第一，不要一开始就追求复杂的 Agent 架构。先把最基础的“文档切分 → 向量化 → 检索 → 生成”链路跑通，确认每一条链路都正常，再上 LangGraph 这类编排框架。我见过太多人一开始就搭一个巨大的流程图，结果跑都跑不通。

第二，工具调用与 RAG 检索，不要全塞进一个 Prompt。搞清楚什么时候用工具，什么时候走检索，这两个是独立的逻辑单元，分开处理不仅调试方便，也给后续扩展留出空间。

第三，多看看检索中间结果。直接看最终回答，往往会掩盖检索链路中的各种问题。每次效果不好，先把检索到的 Top-5 片段打印出来看一眼，90% 的问题一眼就能定位。

本地化 RAG 智能体是我今年做过最值得的一件事情。它就是把知识库、对话能力、工具能力都装进了一个独立盒子，数据在自己手里，效果也在自己手里。如果你正在考虑类似的事情，希望这篇记录能帮你少走几步弯路，把时间花在真正有挑战的工程点上。