企业官网建设流程全解析

我最近在整理一套 production agentic RAG 的实战课程笔记，起因很直接：团队里好几个项目都卡在同一个地方——本地 Demo 跑得飞快，一进生产环境就各种翻车。检索结果乱飘、回答胡说八道、数据量稍微涨一点延迟就压不住，最后所有人都在质疑 RAG 是不是根本不适合生产。我见过太多团队死磕 Prompt、换模型、调 Chunk 大小，搞了一个月还是没进展，为什么？因为大家默认把 RAG 当成一个"检索 + 生成"的拼装玩具，而不是一个需要端到端设计的数据系统。这篇文章就是我从零搭 production agentic RAG 系统的完整经验分享，覆盖 Agent 工作流的构建、RAG 知识库与 KG 知识库、结构化知识库的选型边界、在 Mac 上的本地搭建调试、多模态图片如何处理，以及生产环境最容易被忽略的评估和监控。适合所有正在做 RAG 落地、或者准备把 RAG 推向生产的工程师。

1. 为什么你的 RAG 一上生产就卡住：先拆解"生产"这个词

先说一个反直觉的现象：很多人本地写得津津有味的 RAG Demo，放到生产环境之后第一周就开始被用户投诉。不是模型变笨了，也不是服务器不够用，而是 Demo 环境里那些没人明说的隐藏假设，到了生产环境集体失效。

1.1 教程类 Demo 的隐藏假设

你看过的主流 RAG 教程，基本都有一个共同套路：拿几十页干净 PDF，分割成 Chunk，嵌入向量，然后问你"巴菲特是哪一年出生的"这种单跳问题。这个流程跑通非常爽，但它默认了几个事情：

• 语料量小（几百到几千 Chunk），向量检索随便召回都能撞到正确答案；
• 文档格式工整，没有扫描件、表格、页眉页脚、代码片段混排；
• 用户问题措辞规范，不会出现口语化表达、错别字、指代不明；
• 单个问题只依赖一段上下文，不需要跨多个文档做推理。

这些假设在生产环境几乎一个都不成立。生产环境的知识库可能是几百万个 Chunk，文档是乱七八糟的 PDF、Word、HTML、Markdown、Excel 混着来，用户问的问题一半带着错别字或者口语化缩略语。于是你会发现，教程里的"三板斧"（加载、分割、嵌入）根本扛不住。

1.2 "Building for Production 卡住"的真正卡点

我观察下来，团队真正卡住的地方通常不在模型，而在三件事：召回质量、数据管道、评估闭环。

召回质量是最容易被低估的。很多人以为换个更好的 Embedding 模型就万事大吉，实际上一半以上的召回失败是 chunking 策略导致的。生产文档里经常出现"标题和正文分离""表格被切开""长段落语义断裂"的情况，这些都不是 Embedding 模型能解决的，而是文档结构解析层面的事。我后面会专门讲 chunking 和混合检索的取舍，这里先记住一个结论：召回是 RAG 系统的地基，地基不牢，Agent 再聪明也没用。

数据管道则是另一个隐蔽的卡点。生产环境的知识库是持续更新的，不是一次索引完就结束。我见过一个项目，文档更新后只跑了增量写入，没做旧 Chunk 的删除和去重，结果同一份内容在向量库里躺着好几个版本，召回时重复结果占满 Top-K，真正的答案反而排不进去。这个坑不是靠调参能填上的，必须把"采集-解析-切分-嵌入-入库-失效处理"当成一条完整的数据工程链路来设计。

至于评估闭环，更是一言难尽。大多数团队在没想清楚"什么算回答得好"的情况下就开始调优，结果就是今天换个 Embedding 觉得好一点，明天改个 Prompt 又觉得回去了，完全靠感觉迭代。生产级 RAG 必须把评估当成第一等公民，我到最后一部分会给出可落地的评估方案。

2. Agentic RAG：从"检索一次就生成"到"多轮决策工作流"

2.1 为什么单次检索注定不够用

传统的 RAG 是"Retrieve-Read"两步走：查一次向量库，把 Top-K 拼进上下文，让模型生成。但真实业务问题很少这么简单，最常见的两种情况会直接击穿单次检索：

第一种是多跳问题。比如"我们上季度卖得最好的产品，它的供应商是哪家？"这种问题需要先从销售记录里找到产品名，再去供应商数据库里查信息，最后还可能要去产品文档里确认细节。一次向量检索只能覆盖其中一跳，答案必然残缺。

第二种是意图混杂的问题。比如用户问"这个功能怎么收费，另外帮我看看有没有 API 可以对接"，这是一个问题里同时包含价格问答和接口文档查询两种意图。单次检索只会把两种内容混在一起给模型，结果两边都答不好。

Agentic RAG 的核心思路，就是把"检索"从一个动作变成一个过程：模型（或者一个编排层）先理解问题，再制定检索计划，按计划调用不同的工具，拿到中间结果后决定是继续检索、改写查询还是直接生成。本质上，这是一个"感知-决策-行动"的循环。

2.2 Agentic RAG 的核心循环与路由设计

我用的循环结构并不复杂，五个步骤反复迭代：

1. Query Understanding：把用户原始问题做意图识别和查询改写，拆出实体、时间范围、限定条件；
2. Routing：根据意图决定走哪个检索通道（向量库、关键词、SQL、知识图谱、外部 API）；
3. Tool Calling：调用对应检索工具，拿到结果后评估信息够不够；
4. Verification：对检索结果做相关性验证，过滤掉无关内容；
5. Generation：信息充分后，让 LLM 基于检索结果生成最终回答，并给出引用来源。

这里面最关键也最容易翻车的是 Routing 这一层。很多人一开始就把所有检索通道塞给 Agent 让它自己选，结果 Agent 在几十个工具里选择困难，延迟和错误率双双爆炸。我的经验是：先做一层硬路由（规则或轻量分类模型），把明显的问题类型分流，例如涉及数值聚合的直接走 SQL，涉及关系推理的走知识图谱，其余的才进入向量检索通道。Agent 的灵活性应该留给"同一类问题内部的策略调整"，而不是"在完全不同的检索范式之间乱跳"。

2.3 一个最小可运行的 Agentic RAG 闭环

直接上代码。我自己常用的骨架逻辑是这样的，基于 LangGraph 或者纯手写状态机都可以，核心是把状态显式管理起来：

from dataclasses import dataclass, field from typing import Any, Callable @dataclass class AgentState: query: str sub_queries: list = field(default_factory=list) retrieved_docs: list = field(default_factory=list) answer: str = None done: bool = False def query_understanding(state: AgentState) -> AgentState: # 用LLM拆解子问题，也可以在这里做实体识别和查询改写 state.sub_queries = decompose_query(state.query) return state def route(state: AgentState) -> AgentState: # 硬路由：判断每个子问题该走哪个检索器 sub_queries_with_routes = [] for q in state.sub_queries: route_name = classifier(q) # vector / sql / kg / web sub_queries_with_routes.append((q, route_name)) state.sub_queries = sub_queries_with_routes return state def retrieve(state: AgentState) -> AgentState: for q, route_name in state.sub_queries: retriever: Callable = RETRIEVERS[route_name] docs = retriever(q) state.retrieved_docs.extend(docs) return state def verify(state: AgentState) -> AgentState: # 相关性与去重，决定是否继续检索 state.retrieved_docs = filter_relevant(state.query, state.retrieved_docs) if not enough_info(state.retrieved_docs): state.sub_queries = expand_query(state.query) # 重新改写继续 return route(state) return state def generate(state: AgentState) -> AgentState: state.answer = llm_generate(state.query, state.retrieved_docs) state.done = True return state def run_agent(initial_query: str): state = AgentState(query=initial_query) while not state.done: state = query_understanding(state) state = retrieve(state) state = verify(state) return generate(state)

这套闭环的价值在于，每个环节都留了状态钩子，生产环境里可以做 tracing、做干预、做人工回退。不要迷信 Agent 框架的"自动规划"，在当前模型能力下，把规划逻辑显式写清楚，远比让模型自由发挥稳定。

2.4 实测中的几个坑

Agentic RAG 跑起来之后，最常踩的坑有三个。

第一个是循环失控。Agent 在信息不足时会不断改写查询、反复检索，开销成倍增长。我一般会加两个保险：最大迭代次数（3-5 轮足够）和置信度阈值（检索结果的相关性打分低于某个值就直接放弃，转答"我暂时无法回答"）。

第二个是上下文污染。每轮检索回来的文档都堆进上下文，最后的 prompt 又长又乱，模型反而被噪音带偏。正确做法是每轮检索后都做一次压缩或者重排，只保留真正相关的片段，控制最终输入模型的上下文长度。

第三个是成本失控。每个子问题都是一次 LLM 调用，遇到复杂问题可能调十几轮，账单飞涨。我的做法是分级处理：简单问题直接走单次 RAG，只有被识别为复杂问题的才进入 Agent 循环。生产系统不追求每个问题都用最"聪明"的路线，而是用最经济的路线。

3. 知识库选型：KG 知识库、RAG 知识库、结构化知识库到底怎么分

这个问题的搜索热度一直很高，说明大家在选型时确实迷茫。我直接给结论：这三种知识库解决的是不同层面的问题，不是互相替代的关系，而是互相补充的关系。

3.1 三种知识库的本质区别

RAG 知识库，本质上是"非结构化文本 + 向量索引"。它的对象是自然语言文档，优势是部署快、对语义相似性问题友好，比如"有没有可以离线运行的 OCR SDK"，这种问题靠向量相似度就能召回不错的候选。但它的弱点是：没有全局一致性，同一个实体在不同文档里可能有不同叫法；也不擅长精确计算和聚合，比如"今年 5 月一共处理了多少工单"，向量检索根本答不上来。

KG 知识库，本质上是"实体 + 关系 + 属性"的图结构。它适合回答关系推理类问题，比如"A 公司的股东里有没有 B 公司的关联方"，这类问题需要沿着边一跳一跳地走。KG 的优势是精确、可解释、支持多跳推理，劣势也一样明显：构建成本高，需要做实体抽取、关系抽取、对齐消歧，而且知识覆盖率永远赶不上文档库——你不可能把每一段话都抽成三元组。

结构化知识库，本质上是"表 + SQL + 维度模型"。它适合做聚合统计、精确值查询，比如"各区域的销售额排名""单价在 100 到 200 之间的商品列表"。结构化知识库通常不直接面向用户，而是作为 RAG 或 Agent 背后的一个工具通道，通过 Text-to-SQL 暴露给模型使用。

3.2 一个对比表格帮你快速选型

我给团队定的选型逻辑是三步走：先看用户问题里有多少比例是"精确计算类"和"关系推理类"，如果超过三成，就必须引入结构化通道或 KG 通道；再看现有数据基础，如果根本没有干净的关系型数据，那就别硬上 KG，先把 RAG 做好；最后做融合，把不同知识源挂到 Agent 的工具列表里，让路由层决定怎么查。

3.3 Ontology 在 RAG 里的真实角色

热词里出现了 ontology rag，值得单独说一下。很多人把 Ontology（本体）理解成知识图谱的"增强版"，其实不够准确。Ontology 是 KG 的"模式层"——它定义了实体类型、关系类型、属性约束，相当于给图数据画了一张"类图"。没有 Ontology 的 KG 是一堆松散的节点和边，有了 Ontology，语义才是完备的。

在 RAG 场景里，Ontology 的真正价值有两个。第一是约束 Text-to-Query 的生成质量。当我们要把自然语言问题翻译成图查询语言时，如果 Ontology 给了明确的实体类型和关系类型，LLM 就不会凭空捏造不存在的属性名，而是严格从 Ontology 里选择。第二是给 RAG 召回做语义对齐。比如用户问"谁负责这个模块"，Ontology 如果定义了"人-负责-模块"这个关系，路由层就能直接知道该走 KG 而不是向量检索。

实践上，小规模团队不需要从零构建一套完整 Ontology。我的建议是：先画一个极简版本，覆盖 Top 20 的实体类型和 Top 50 的关系类型，够用就行；然后在使用过程中持续扩充。追求一步到位的 Ontology 反而会陷入建模地狱。

4. 技术栈选型与 Mac 本地搭建：别在这一步卡太久

4.1 框架选择的真实经验

RAG 框架这两年变化太快，我直接给筛选标准：第一，看团队成员的熟悉度和社区活跃度；第二，看是否可以被"拆掉"——也就是说框架的各个组件能否独立替换。我自己在 LangChain、LlamaIndex、Haystack 里都写过生产代码，结论是：LangChain 生态最大但抽象层太厚，适合快速原型；LlamaIndex 对文档加载和索引管道的控制力更强；Haystack 在生产管线方面更克制、更工程化。

但说实话，生产项目到后期基本都是"半自研"状态：用框架做基础组件，用自研代码做路由、评估和监控。框架的作用是让你不用重复造轮子，而不是替你解决业务问题。如果你发现自己在框架里疯狂写 workaround，那就说明框架选错了，或者你的依赖太深了。

4.2 在 Mac 上搭建 RAG 知识库：M 系列芯片实战

"怎么在 Mac 上搭建 RAG 知识库"这个热搜词背后，其实有大量开发者在本地实验。我自己主力机是 M 系列芯片的 MacBook，跑本地 RAG 的体验还算顺畅，但有几个经验值得说。

第一，模型尽量选 MLX 格式。Apple Silicon 上用 MLX 框架跑量化后的模型，推理速度和显存占用都比 PyTorch 原生好很多。以 7B-8B 规模的模型为例，Q4 量化后在 32GB 内存的机器上基本能跑出可用速度；如果内存只有 16GB，建议用 3B-4B 模型或者干脆走 API。

第二，Embedding 模型不要贪大。很多人在本地跑 embedding 模型，动辄上 billion 参数，其实没必要。本地开发阶段，用 100M-300M 参数的模型（比如 bge-small、bge-base 系列）完全够用，召回效果和生产环境的差距主要靠后续的 rerank 和混合检索来弥补。

第三，向量数据库的选型。本地实验我推荐 Chroma 或 LanceDB，零配置、文件即数据库；需要接近生产环境的性能测试，就上 Qdrant 或 Milvus 的 Docker 版。不建议一上来就搭分布式向量库，那是自找麻烦。

简单列一个我在 Mac 上的搭建路径，供参考：

# 1. 安装 Python 环境和依赖 python3 -m venv rag-course source rag-course/bin/activate pip install llama-index chromadb sentence-transformers # 2. 用 Ollama 加载本地 LLM（MLX 加速） brew install ollama ollama pull qwen2.5:7b-instruct-q4_K_M # 3. 最小 RAG 管道 python - <<'EOF' from llama_index.core import SimpleDirectoryReader, VectorStoreIndex from llama_index.vector_stores.chroma import ChromaVectorStore import chromadb docs = SimpleDirectoryReader("./knowledge_base").load_data() client = chromadb.PersistentClient(path="./kb_db") vstore = ChromaVectorStore(chroma_collection=client.get_or_create_collection("kb")) index = VectorStoreIndex.from_documents(docs, vector_store=vstore) engine = index.as_query_engine() print(engine.query("你们的退款政策是什么？")) EOF

这套路径能让你在半天内跑通本地实验。但我要强调一句：本地跑通只是起点，生产环境的差距在工程层面的数据管道、监控、评测和灰度策略，这些才是你后面真正要花时间的地方。

4.3 Mac 本地调试的几个常见坑

第一个坑是依赖冲突。RAG 生态的 Python 包更新极快，昨天能跑的版本今天装了新包就崩。我的习惯是用独立的 venv 加 requirements lock 文件管理，不要图方便把包装进全局环境。

第二个坑是 Metal 加速相关的兼容问题。有时候同样的代码，在 Intel Mac 上能跑，在 M 系列上反而报错，多半是 PyTorch 版本和 MPS 后端的兼容问题。遇到这种情况，先降级 PyTorch 版本，或者直接用 CPU 推理做验证，别在环境问题上耗时间。

第三个坑是分块效果不可见。很多人用默认的 chunk_size 和 chunk_overlap 就完事，结果检索效果差却不知道源头在哪。我强烈建议本地搭建阶段就用一个可视化工具打印 chunk 详情，肉眼检查切分结果是否符合文档结构。这一步花的十分钟，能省掉后面调优的三天。

5. 多模态问题：RAG 知识库到底能不能存图片

"rag 知识库能存储图片嘛"这个问题问的人很多，答案是有条件的：能，但要分清楚你存的是什么。

5.1 图片在 RAG 里的三种处理方式

第一种是"存图片 + 存对应的文本说明"。这是最务实也最稳定的方案。图片本身不进向量库，但图片的文件路径、OCR 文本、图片标题、人工撰写的描述等作为文本元数据存入向量库。用户问"那个流程图里第三步是什么"，检索系统把"流程图第三步"和 OCR 文本对应上，再返回图片路径给前端展示。这个方案的优点是工程简单、召回可控，缺点是依赖图片有足够好的文本描述。

第二种是"存图片的向量嵌入"。用 CLIP 这类多模态模型把图片编码成向量，和文本向量放在同一个向量空间里，检索时文本向量直接和图片向量算相似度。这个方案支持"用文字搜图片"和"用图片搜图片"，体验更自然，但坑在于多模态嵌入模型的选择和召回阈值调优都需要经验，而且图片向量没法直接回答文字问题，还是要配合多模态 LLM 才能生成文本回答。

第三种是"让多模态 LLM 直接读图"。像 GPT-4V、Qwen-VL 这类模型可以把图片作为输入的一部分，在 Agent 循环里把图片路径直接传给模型。这个方案最灵活，支持"看图回答问题"，但成本最高、延迟最大。生产中通常只对少数关键图片走这条路，不会把所有图片都塞进上下文。

5.2 我的建议：混合索引，图片和文本分开管

我的生产方案是二选一的混合：索引两条线并行，文本线负责语义检索，图片线负责视觉检索，最终由路由层决定哪条线介入。

具体来说，文本线里给每张图片建立一个"图片卡片"文本块，包含图片标题、OCR 文本、关联文档上下文；视觉线用 CLIP 把图片嵌入独立向量集。当用户问题里出现明确的视觉词汇（"截图里面""流程图""UI 界面"），路由层优先查视觉线，再用多模态 LLM 做最终理解；其他情况只走文本线。

另外一个重要的点是：图片入库前的清洗很关键。扫描件先 OCR，带文字的截图先提字幕，分辨率过低的需要预处理增强。跳过这些步骤直接入库，检索回来的图片质量差，后续怎么优化都没用。

6. 生产级 Agentic RAG 的评估、监控与迭代路径

最后这部分是很多人最想要的"生产经验"。别急着调 Prompt，先搭好评估和监控，否则你永远在暗箱里调优。

6.1 离线评估：先把"好"定义清楚

离线评估分三层：检索质量、生成质量、流程质量。

检索质量用标准信息检索指标，比如 Recall@K、MRR、NDCG。我在实践中特别看重 Recall@K 的一个变体：答案片段是否出现在 Top-K 里。如果答案片段根本不在召回结果里，那后面生成环节再使劲也没用。

生成质量主打三个维度：忠实度（回答是否严格基于检索到的文档，有没有编造）、相关性（是否回答了用户的问题，有没有跑题）、完整性（是否覆盖了问题要求的全部要点）。忠实度是目前 RAG 系统最大的短板，大模型很容易在上下文里挑一段顺眼的就开编，所以忠实度评估必须单独盯紧。

流程质量针对 Agentic RAG 特殊设计：路由准确率（该走向量的时候有没有走错通道）、工具调用成功率、循环轮数分布、超时率。这些指标直接反映 Agent 编排层的稳定性。

6.2 评估集怎么建：从生产日志里挖

很多人问评估集怎么来。我的回答：第一优先从生产日志里挖真实用户问题，脱敏后人工标注标准答案和检索相关文档集合；第二优先让业务专家构造"困难问题集"，专门覆盖多跳、比较、边界情况；实在没有积累的，再考虑用 LLM 辅助生成候选问题，但必须人工复核。

一个可落地的操作是：给评估集每个问题打标签，标注问题类型（单跳、多跳、比较、聚合、模糊），这样迭代时能精确看到你的系统在哪种问题类型上表现差，而不是笼统地看一个总分。

6.3 线上监控：不能只看用户点踩

线上监控至少要覆盖三层。第一层是日志与追踪，每个请求的完整链路都要能回溯：查询改写了什么、路由走了哪条、检索了哪些文档、模型生成了什么、引用来源是哪些。没有链路追踪，线上出了问题你根本无从排查。第二层是质量信号，包括用户反馈（点赞点踩）、引用有效性（引用的文档片段是否真的支撑了回答）、超时和错误率。第三层是数据漂移，监控知识库更新频率、Embedding 分布变化、用户查询词汇漂移，这些能提前预警系统退化。

我特别强调引用来源的监控：生产 RAG 系统必须强制带引用，没有引用的回答一律视为不合格。这既是合规要求，也是质量抓手，因为你可以自动化校验回答中的关键断言是否真的在引用文档里出现。

6.4 一条务实的学习路径

如果你想系统地把 production agentic RAG 搭起来，我建议按这个次序走，不要跳级：

1. 先把单次 RAG 做扎实：掌握文档解析、chunking、Embedding 选型、混合检索、rerank；
2. 建立离线评估集和评估脚本，从第一天就记录每次迭代的指标变化；
3. 再上 Agentic 编排：路由、查询改写、多轮循环，每一步都用 Tracing 观察；
4. 然后引入多知识源：结构化通道、KG 通道，逐步让路由层处理复杂问题；
5. 最后做生产化加固：数据管道自动化、监控告警、成本治理、灰度发布。

这套路径我反复验证过，相比一上来就铺 Agent 框架，它能让你每一步都走得比较稳。很多项目翻车都是因为第 2 步没做就急着跳到了第 3 步，结果系统烂在哪里都说不清楚。

最后分享一点个人体会：我在做这套课程的过程中最大的收获，其实是把"RAG 是一个检索系统"这个认知彻底改成了"RAG 是一个数据系统"。检索、生成只是表象，真正决定生产成败的是你对数据的理解、对评估的坚持、以及对工程细节的耐心。如果你现在正被某个 RAG 问题卡住，别急着换模型，先回过头看看你的数据管道和评估闭环是不是健全——十有八九，答案就在那里。