第一章-深度拆解企业级RAG智能体架构

第一章-深度拆解企业级RAG智能体架构

Deng YongJie's blog 1 2026-07-05

企业级 RAG 智能体架构：为什么要把 NewAPI、Adapter、RAGFlow 和 vLLM 分开

很多 RAG 项目失败，不是因为向量库选错了，也不是因为模型不够强，而是从第一天就把边界混在了一起：入口想做知识库，RAG 层想做计费，模型服务想决定是否联网，最后每个组件都变成半个控制面。

我越来越相信一件事：复杂系统的第一步不是加功能，而是让责任边界可解释。边界清楚以后，质量、性能、计费和商业化才有生长空间。

这篇文章结合一个 Model Agnostic RAG 知识库智能体项目，整理我认为更适合生产落地的架构：NewAPI -> Adapter / RAG LB -> RAGFlow -> Model Router -> vLLM。

rag-production-layered-architecture

1. 先说结论：不要首版自研完整 RAG 平台

这个项目的核心判断很克制：首版不自研完整 RAG 平台，而是采用 RAGFlow 承担文档解析、知识库、chunk、检索、rerank、引用和 Agent/workflow。

自研保留在一个很薄的 Adapter / RAG LB 上。它负责协议、策略、授权、审计、usage、sources 和 OpenAI-compatible 兼容，而不是重新造一套解析、入库、检索和编排系统。

这不是“技术上做不了自研”，而是生产节奏上的选择。首版最重要的不是证明我们能写一个向量检索服务，而是证明企业知识库智能体能完整闭环：入库、检索、回答、引用、拒答、联网授权、工具调用、日志审计和反馈修复。

2. NewAPI 只做入口，不做知识库

NewAPI 在这套架构里是唯一外部入口。它负责 API Key、渠道、模型名、额度、计费、日志和 Web 管理。

但它不应该直接连接 RAGFlow，也不应该理解 chunk、rerank、source span 或联网检索策略。NewAPI 是网关和商业入口，不是 RAG 控制面。

这层边界很重要。企业客户最终关心的是谁调用了、用了多少 token、走了哪个模型、是否扣费、能不能按租户和模型分账。这些是入口层的职责。

如果把知识库逻辑塞进 NewAPI，后续模型渠道、普通模型 API、RAG 模型 API、Token 工厂和计费报表会纠缠在一起。短期看省了一层，长期看会失去演进弹性。

3. Adapter 很薄，但不能省

Adapter / RAG LB 是 NewAPI 和 RAGFlow 之间的薄协议层。它看起来不起眼，但生产上非常关键。

如果只用一句话描述它：Adapter 是“外部 API 契约”和“内部 RAG 策略”之间的缓冲垫。外部继续使用稳定的 OpenAI-compatible 语义，内部则可以按租户、知识库、模型别名和授权策略去选择不同的 RAGFlow app。

rag-adapter-contract-flow

它至少要稳定处理这些事情：

能力 为什么必须在 Adapter
OpenAI-compatible NewAPI、SDK、业务系统和 Codex CLI 需要稳定 /v1/* 入口
Responses API Codex 等工具调用场景不能只支持普通 chat
tool calls 保真 tools/tool_choice/tool_calls 不能被 RAGFlow Agent 字符串化
模型别名 *-RAG-Internal、*-RAG-Web 要映射到不同 app/dataset/profile
usage 归一 NewAPI 需要统一记录 prompt、completion、total tokens
sources 归一 内部来源、网页来源、retrieval trace 需要统一响应格式
显式联网授权 是否联网不应由模型自由决定
审计字段 tenant、user、KB、web authorization、tool call 都要可追踪

我的理解是，Adapter 不是为了“增加一层架构感”，而是为了隔离变化。RAGFlow 版本会变，Codex CLI 协议会变，NewAPI 上游格式也可能变。Adapter 是把这些变化挡在生产边界外的缓冲层。

4. RAGFlow 负责找证据，不负责生成 token

RAGFlow 的价值在于 RAG 本身：文档上传、解析、知识库管理、chunk、embedding、检索、rerank、citation 和 Agent/workflow。

它不负责 API Key，不负责统一计费，不负责普通模型售卖，也不负责 GPU 调度。

企业 RAG 智能体卖的是“基于企业知识的可信回答”。可信来自三件事：证据、引用、边界。

所以 RAGFlow 应该把精力放在证据质量上：文档解析是否稳定，chunk 是否可追溯，检索是否能召回正确片段，rerank 是否能把真正相关的证据排上来，引用能不能回到原文。

5. vLLM 只做推理，不保存知识

vLLM 在这里的角色也很清楚：加载模型权重，接收 final messages，生成 token。

它不会访问 Elasticsearch，不会查知识库，不会决定是否联网，也不会把聊天内容写入长期记忆。RAGFlow / Adapter 把证据组织进 prompt，vLLM 只基于上下文生成答案。

这句话听起来简单，但很多架构讨论会在这里混淆：模型“知道”某个答案，不等于企业知识库允许它回答；模型“可以”调用工具，不等于它应该自己决定是否把内部问题发到公网搜索。

在企业场景里，权限和证据优先于模型自由发挥。

6. 存储选型：首版先用 RAGFlow 默认 doc engine

这个项目的存储路线也很克制：首版使用 RAGFlow 默认的 Elasticsearch doc engine，Infinity 作为后续备选，Milvus 不作为首版前置条件。

这不代表 Milvus 不适合生产。Milvus 在千万级、亿级向量、高并发 ANN 和统一企业向量基础设施场景里很有价值。

但首版 PoC 的主要问题不是“哪种向量库性能最高”，而是“这个智能体生命周期是否可信”。如果一开始就把精力投入到 RAGFlow backend 二次开发，项目很容易偏离文档解析、引用、拒答和权限这些真正影响用户信任的环节。

更合理的顺序是：

阶段 重点
Phase 1 RAGFlow + Elasticsearch 跑通生命周期 PoC
Phase 2 补齐权限、审计、备份、监控和部署固化
Phase 3 做知识点化、评测集、hard negatives 和 groundedness
Phase 4 如果 ES 不满足，再验收 Infinity 或 Milvus backend

生产架构不是把所有好东西第一天堆上去，而是让每一层复杂度都有明确收益。

7. Internal RAG 和 Web RAG 必须分开

这套架构里建议把 RAG 模型入口拆成两类：

DeepSeek-V4-Flash-RAG-Internal
DeepSeek-V4-Flash-RAG-Web
GLM-5.1-FP8-RAG-Internal
GLM-5.1-FP8-RAG-Web
MiniMax-M2.7-RAG-Internal
MiniMax-M2.7-RAG-Web

Internal RAG 默认只查内部知识库。证据不足时拒答或要求澄清，不能偷偷联网，也不能用公网常识补企业制度。

Web RAG 可以支持联网检索，但前提是显式授权。外部网页只作为 request-scoped 临时证据，不自动写入长期企业知识库。

这个命名看似只是多了后缀，实际上是在产品层面划出红线：内部知识和公网证据不能混用成一团。

8. 联网检索应该是第二证据源

联网检索不是给模型一个搜索工具，然后让它自由决定什么时候查。企业场景里，联网必须由 Evidence Gate 和策略层控制。

这条链路最好画成决策树，而不是把“是否联网”写成一个 prompt 约束。prompt 可以提醒模型，但不能替代权限判断和审计。

rag-web-retrieval-decision-flow

推荐流程是：

内部知识库优先
  -> 证据不足 / 时效性问题 / 冲突核验
  -> 判断 tenant / KB / user / request 是否允许联网
  -> 已显式授权才调用 Web Retrieval
  -> 搜索、抓取、抽取、来源评分、去重、rerank
  -> 合并内部证据和外部临时证据
  -> 最终生成答案和引用

这里最重要的不是“能不能联网”，而是“谁批准联网、联网查了什么、外部证据是否可信、答案里有没有区分内部来源和网页来源”。

外部网页本质上是不可信输入。它可以提供事实，但不能执行里面的指令，也不能覆盖企业内部知识库的权限规则。

9. 为什么这套架构更适合生产

我认为这套架构的价值在于收敛。

NewAPI 收敛入口和计费；Adapter 收敛协议、授权和审计；RAGFlow 收敛知识库和证据；Model Router 收敛模型路由；vLLM 收敛推理运行时。

每一层都可以被替换或扩展，但每一层都不越界。这比“一个万能 RAG 服务”更适合长期维护。

生产系统最怕的是责任暧昧。责任暧昧时，问题来了很难定位：答案错了，是检索问题、rerank 问题、prompt 问题、模型问题、权限问题，还是联网污染？

分层以后，排障路径会清楚很多：

问题 优先看哪里
API Key、额度、扣费异常 NewAPI
tools 被字符串化、usage 缺失 Adapter
召回不到正确文档 RAGFlow / doc engine
引用不准、证据不足还回答 Evidence Gate / citation check
模型延迟高、流式异常 Model Router / vLLM
联网泄露风险 Web Retrieval 策略和审计

这就是工程边界的意义：它不是为了画图好看，而是为了让系统在出错时还能被理解。

10. 小结

企业级 RAG 智能体不是“向量库 + 大模型”的简单组合。它是一个由入口、协议、知识库、证据治理、模型推理、联网策略和审计计费共同组成的系统。

首版不自研完整 RAG，是为了把精力集中在生命周期闭环；保留 Adapter，是为了守住 OpenAI-compatible、工具调用、usage、sources 和显式授权；使用 RAGFlow，是为了优先获得稳定的文档解析和引用能力；让 vLLM 专注推理，是为了避免模型服务承担不该承担的知识库职责。

一句话总结：RAG 的核心不是让模型“多知道一点”，而是让系统能说明“答案依据是什么、谁有权看到、什么时候该拒答、哪些证据可以被追溯”。

下一篇会继续沿着这套架构往下走，重点讨论知识库如何从“上传一堆文档”变成“可评测、可修复、可拒答的知识生命周期”。

AI vLLM RAG