企业官网建设流程全解析

1. Agent 时代的基础设施到底在变什么

1.1 从“模型为中心”到“数据与执行环境为中心”的迁移

过去两年，大家聊 AI 基础设施，话题基本围着模型转：参数量、上下文长度、推理吞吐、显存占用。但真正把 Agent 跑起来的人会发现，模型只是其中一个零件，而且往往不是最卡脖子的那个。一个能稳定完成任务的 Agent，背后需要的是数据供给、工具调用、状态管理、沙盒执行、可观测性这一整套东西。模型换一版，可能只是效果从 70 分到 78 分；但数据管道断一次、工具调用超时一次、沙盒权限配错一次，整个任务直接归零。

我自己的体感是，Agent 把基础设施的重心从“推理”推向了“执行”。传统推理服务是无状态的：请求进来，算完返回，结束。Agent 是有状态的、多轮的、会对外部世界产生副作用的。它要读文件、查数据库、调 API、写代码、跑测试，每一步都可能失败，每一步都需要被记录和回滚。这就意味着基础设施要解决的核心问题变了：不再是“怎么把一次前向算得更快”，而是“怎么让一个会犯错、会重试、会调用外部资源的智能体，在可控、可观测、可复现的前提下把活干完”。

这个转变带来的直接后果是，数据层和基础设施层的重要性被重新定价。以前数据是训练的燃料，现在数据同时是 Agent 的“记忆”和“感知”。向量库、图数据库、对象存储、消息队列、沙盒运行时，这些原本属于后端工程师工具箱的东西，现在成了 Agent 工程师的日常。热搜里频繁出现的“agent框架与编排”“dify智能体平台”“agent沙盒”这些词，本质上都是在回应同一个问题：Agent 需要一个什么样的运行底座。

1.2 为什么“数据·智能·进化”是一条递进链而不是三个并列词

标题里这三个词不是随便排的，它们是一条因果链。数据是原料，智能是加工能力，进化是持续迭代的机制。缺了任何一环，Agent 都只能停在 demo 阶段。

先说数据。Agent 的数据和传统大数据有重叠但不完全一样。传统大数据强调规模、吞吐、批处理；Agent 的数据强调时效、结构、可检索、可追溯。一个客服 Agent 需要的是最新的产品文档和工单历史，而不是三年前的离线报表。一个代码 Agent 需要的是当前仓库的 AST、依赖图和测试结果，而不是全网的代码语料。所以 Agent 时代的数据基础设施，关键词是“近实时”和“上下文相关”。

再说智能。这里的智能不只是模型能力，还包括编排逻辑、工具选择、错误恢复、多 Agent 协作。热搜里“吴恩达 agent 教程”“agent框架”“hermes智能体”这些内容，讨论的其实都是怎么把模型能力组织成可用的工作流。一个裸模型再强，如果没有合理的编排，面对一个需要五步操作的任务也会中途迷路。

最后说进化。Agent 不是部署完就完事的系统，它需要从每次执行中学习：哪些工具调用失败了、哪些提示词导致了幻觉、哪些数据检索没命中。这些反馈要回流到数据层和编排层，形成闭环。没有进化机制的 Agent，本质上是一个昂贵的 if-else。热搜里“deepseek公开ai智能体训练新方法”这类内容，关注的就是这个闭环怎么建。

1.3 这套基础设施适合谁来上手

如果你是一个后端工程师，想往 Agent 方向转，这套东西对你来说门槛最低，因为你已经懂服务治理、懂数据库、懂消息队列，缺的只是把模型当成一个特殊依赖来编排。如果你是一个算法工程师，模型侧你很熟，但沙盒、权限、状态持久化这些工程问题可能是你的盲区，需要补。如果你是一个产品或者创业者，理解这套基础设施的边界，能帮你判断哪些需求现在能做、哪些还做不了，避免被 demo 误导。

我写这篇东西的出发点，是把“Agent 时代的数据与 AI 基础设施”这个听起来很虚的标题，拆成能落地、能复现、能避坑的具体内容。下面会从整体设计思路、核心细节、实操过程、问题排查几个角度展开，尽量做到你看完能自己搭一个最小可用的 Agent 运行底座。

2. 整体架构设计与选型背后的取舍

2.1 分层思路：表示层、应用层、领域层、基础设施层怎么切

热搜里出现了“表示层 应用层 领域层 基础设施层”这组词，这其实是经典的分层架构，放到 Agent 场景里依然适用，但每层的职责需要重新定义。

表示层在 Agent 场景里不只是 UI，还包括各种交互入口：聊天窗口、API 网关、CLI、甚至另一个 Agent 的调用请求。这一层的核心职责是协议转换和会话管理，把不同来源的输入统一成内部消息格式。

应用层负责编排。它决定一个任务怎么拆、调哪个 Agent、用哪个工具、失败了怎么重试。这一层是 Agent 的“大脑皮层”，也是变化最频繁的一层。我建议把编排逻辑和具体工具实现分开，编排层只依赖工具接口，不依赖工具内部细节，这样换工具的时候不用动编排。

领域层是业务语义的沉淀。比如“订单”“工单”“代码仓库”这些概念，以及围绕它们的规则。这一层决定了 Agent 能不能理解业务，而不是只会调 API。很多 Agent 项目失败，就是因为跳过了领域层，直接让模型对着原始数据硬猜。

基础设施层是底座：模型推理服务、向量库、关系库、对象存储、消息队列、沙盒运行时、可观测性组件。这一层要稳、要可替换、要有降级方案。我的经验是，基础设施层的组件选型要保守，不要追新，因为 Agent 本身已经够不稳定了，底座再飘就没法排查问题。

2.2 编排框架怎么选：自研、LangChain 类、还是 Dify 类平台

这是被问得最多的问题。我的看法是要看你的团队构成和迭代速度。

自研编排的优点是可控，缺点是慢。你需要自己实现工具注册、状态机、重试、超时、日志，这些加起来至少是几周的工作量。适合的场景是：你的业务流程非常特殊，现有框架表达不了，或者你对性能和可观测性有极高要求。

LangChain 这类代码框架的优点是灵活，缺点是抽象层多，出问题的时候调用栈很深，排查成本高。适合的场景是：你的团队有较强的工程能力，需要精细控制每一步。

Dify 这类平台的优点是上手快，可视化编排，适合快速验证。缺点是深度定制受限，复杂逻辑表达起来别扭。适合的场景是：你在做 MVP，或者业务逻辑相对标准。

我实际的做法是混合：用代码框架做核心编排，用平台做外围的配置管理和运营界面。核心逻辑必须能进版本控制、能写单测，这部分不能交给可视化平台。

2.3 数据层选型：向量库、图库、关系库各管什么

Agent 的数据需求是混合的，没有单一存储能全包。

向量库管语义检索。用户问“怎么退款”，你要能召回“退货流程”的文档，这靠关键词匹配做不到。选型上，小规模用 pgvector 就够了，别一上来就上专用向量库，运维成本不划算。规模上来了再考虑 Milvus、Qdrant 这类。

关系库管结构化状态。会话历史、任务状态、工具调用记录、权限配置，这些都需要事务保证。Postgres 基本能覆盖大部分场景，别为了“大数据”而用分布式数据库，单机 Postgres 能扛的量比很多人想象的大。

图库管关系推理。当你的 Agent 需要处理“A 依赖 B，B 依赖 C，C 出问题会影响谁”这类问题时，图结构比关系表更自然。但图库的运维门槛高，除非确实有强关系推理需求，否则用关系库加递归查询也能凑合。

对象存储管原始文件。文档、图片、代码仓库快照、执行产物，这些放 S3 兼容存储里，便宜且可靠。

2.4 沙盒执行环境：为什么它是 Agent 基础设施的必选项

热搜里“agent沙盒”“agent execution terminated due to error”这些词，说明很多人已经在踩沙盒的坑了。沙盒的必要性在于：Agent 会执行代码、会调系统命令、会访问网络，这些操作如果不隔离，轻则污染环境，重则造成安全事故。

沙盒方案大致分三档。最轻的是进程级隔离，用子进程加资源限制，优点是快，缺点是隔离不彻底。中间是容器级隔离，用 Docker 或类似方案，隔离性和启动速度平衡得比较好，是大多数场景的推荐选择。最重的是虚拟机级隔离，隔离最彻底，但启动慢、资源开销大，适合高风险场景。

我的建议是默认用容器级，给每个任务分配一个短生命周期的容器，任务结束就销毁。容器镜像要预装好常用工具，但不要预装敏感凭证，凭证通过运行时注入，且要有过期时间。

3. 核心细节解析与实操要点

3.1 数据管道的近实时化：从 T+1 到分钟级

Agent 对数据时效的要求比传统分析高得多。用户问“我昨天的订单到哪了”，你给 T+1 的数据就是错的。所以数据管道要从批处理转向流批一体。

具体做法上，我会把数据源分成三类。第一类是变更频繁的业务数据，用 CDC 捕获变更，推到消息队列，再由消费者写入检索库。第二类是文档类数据，用定时增量抓取，配合内容哈希去重。第三类是外部 API 数据，用缓存加过期策略，避免每次都打外部接口。

这里有个容易忽略的点：数据写入检索库和写入关系库要保证最终一致，但不要追求强一致。Agent 场景下，几秒的数据延迟通常可以接受，但写入失败必须能重试和告警。我见过因为一条数据写入失败导致整个检索结果缺失，进而让 Agent 给出错误答案的案例。

3.2 上下文构建：检索、裁剪、排序的三步法

Agent 的上下文窗口是稀缺资源，怎么把最相关的信息塞进去，直接决定效果。

第一步是检索。向量检索召回语义相关的，关键词检索召回精确匹配的，两者结果做融合。融合算法用 RRF 就够，不用上太复杂的。

第二步是裁剪。召回的文档往往很长，要按段落切分，只保留和问题最相关的段落。切分粒度上，我倾向于按语义边界切，比如按标题、按段落，而不是固定字数切，因为固定字数会把一句话切断，影响模型理解。

第三步是排序。把裁剪后的片段按相关性排序，最相关的放最前面。这里可以用一个小的重排模型，也可以用简单的规则，比如包含问题关键词的加权。重排模型效果好但增加延迟，规则快但粗糙，看你的延迟预算。

提示：上下文构建的每一步都要记录日志，包括召回了哪些、裁剪掉了哪些、最终排序是什么。出问题的时候，这些日志是唯一能帮你定位的线索。

3.3 工具调用的可靠性设计：超时、重试、幂等

Agent 调工具失败是常态，不是异常。设计的时候要假设每次调用都可能失败。

超时设置上，读操作可以短一点，比如 5 秒；写操作要长一点，因为可能涉及事务，但也不能无限等，一般 30 秒封顶。超时后要能取消底层操作，否则会留下僵尸任务。

重试策略上，区分可重试错误和不可重试错误。网络超时、限流可以重试；参数错误、权限不足重试也没用。重试要加退避，避免雪崩。

幂等是最容易被忽略的。如果一个写操作重试了两次，会不会产生两条记录？所以每个写工具都要支持幂等键，调用方生成唯一键，服务端根据键去重。这个设计在 Agent 场景下尤其重要，因为 Agent 可能会因为超时而重试，但它不知道第一次其实成功了。

3.4 状态管理与可观测性：让每次执行都能复盘

Agent 的执行是有状态的，状态管理做不好，就会出现“上次聊到一半，这次接不上”的问题。

状态分几层。会话状态是用户维度的，包括历史消息、偏好设置。任务状态是单次执行维度的，包括当前步骤、已完成步骤、中间结果。工具状态是调用维度的，包括请求参数、响应、耗时。

可观测性上，我建议至少记录三类数据：trace，把一次任务的所有步骤串起来；metric，统计成功率、延迟、token 消耗；log，记录详细内容用于排查。这三类数据要能通过一个 trace id 关联起来，否则排查的时候要在多个系统之间跳。

注意：日志里不要记录敏感信息，比如用户密码、完整身份证号。Agent 的日志量很大，一旦泄露影响面也大。脱敏要在写入前做，不要指望事后清理。

4. 实操过程与核心环节实现

4.1 最小可用 Agent 底座的搭建步骤

我以一个“能查文档、能执行代码、能记住会话”的最小 Agent 为例，走一遍搭建过程。

第一步，起基础设施。用 docker-compose 起 Postgres、Redis、一个向量库（pgvector 就够）、一个对象存储（MinIO）。这些用现成镜像，不要自己编译。

第二步，建数据表。核心表包括：会话表、消息表、任务表、工具调用表、文档表、文档片段表。文档片段表里存向量，用 pgvector 的 vector 类型。

第三步，写数据摄入管道。一个简单的 Python 脚本，读文档、切分、算向量、写库。切分按标题和段落，向量用开源 embedding 模型，本地跑，不依赖外部 API。

第四步，写编排逻辑。一个状态机，状态包括：理解问题、检索上下文、决定动作、执行动作、生成回答。每个状态是一个函数，输入输出都是明确定义的结构。

第五步，写工具。先写两个：文档检索工具和代码执行工具。代码执行工具调沙盒，沙盒用 Docker 起临时容器。

第六步，接模型。模型调用封装成一个客户端，支持重试和超时。提示词模板单独管理，不要硬编码在代码里。

第七步，加可观测性。每个步骤打点，trace id 贯穿全程。用一个简单的 dashboard 展示成功率和延迟。

这套东西跑起来大概两三天，能覆盖大部分 demo 需求。后面就是在这个骨架上加东西。

4.2 沙盒执行的参数计算与配置

沙盒的资源限制要算清楚，给多了浪费，给少了任务失败。

CPU 上，一个代码执行任务通常不需要多核，1 核够用。但如果 Agent 要跑测试或者编译，可能需要 2 到 4 核。我的做法是默认 1 核，允许任务声明更高需求。

内存上，Python 脚本一般 512MB 够，但如果要处理数据或者跑模型，可能要 2GB 以上。默认给 1GB，超了让任务失败并提示。

超时上，简单脚本 30 秒，复杂任务 5 分钟。超时后强制杀容器，不要留。

网络上，默认禁止外网访问，只允许访问内部服务。如果任务确实需要外网，走白名单代理，且记录所有请求。

磁盘上，给一个临时目录，任务结束就删。大小限制 1GB，防止写满。

# 沙盒容器配置示例 resources: cpu_limit: 1.0 memory_limit: 1g timeout_seconds: 300 disk_limit: 1g network: allow_internet: false allowed_hosts: - internal-api.local

4.3 检索效果的调优实录

检索效果不好，是 Agent 答非所问的头号原因。我调过很多次，总结下来几个有效手段。

第一，切分粒度要试。同样一批文档，按 256 字切和按 512 字切，召回效果可能差很多。我的经验是中文文档按 300 到 500 字切比较稳，英文按 500 到 800 词。

第二，加元数据过滤。文档往往有类型、时间、来源这些属性，检索的时候先按元数据过滤再算向量，能大幅提升准确率。比如用户问的是最新政策，就只检索最近一年的文档。

第三，混合检索。纯向量检索对精确匹配不敏感，比如产品型号这种词，向量可能召回一堆相似的但不对的。加上关键词检索做融合，能补上这个短板。

第四，重排。召回 20 条，重排取前 5 条，效果通常比直接取前 5 条好。重排模型可以用小的 cross-encoder，延迟增加可控。

第五，评估。建一个小的评估集，几十个问题加标准答案，每次调完跑一遍，看命中率变化。没有评估集的调优都是瞎调。

4.4 多 Agent 协作的编排模式

单 Agent 搞不定的任务，就要上多 Agent。常见的模式有三种。

第一种是流水线模式。Agent A 的输出是 Agent B 的输入，依次传递。适合步骤明确的流程，比如“提取需求 -> 生成代码 -> 测试代码”。

第二种是辩论模式。多个 Agent 对同一问题给出方案，然后互相评审，最后综合。适合需要多角度思考的任务，比如方案设计。缺点是 token 消耗大。

第三种是主管模式。一个主管 Agent 负责任务拆解和分配，多个执行 Agent 各干各的，主管汇总结果。适合可并行的任务，比如同时查多个数据源。

我实际用下来，主管模式最实用，但主管 Agent 的提示词要写好，否则它会把任务拆得乱七八糟。一个技巧是给主管 Agent 一个明确的拆解模板，让它按模板填，而不是自由发挥。

5. 常见问题与排查技巧实录

5.1 Agent 执行中断的排查路径

“agent execution terminated due to error”这个报错很常见，但信息量太少。我的排查路径是这样的。

先看 trace，找到最后一个成功的步骤和第一个失败的步骤。失败步骤的输入输出是关键。

如果失败在模型调用，看是不是超时、限流、或者上下文超长。上下文超长很隐蔽，因为不同模型的限制不一样，而且 token 计算和字符数不是线性关系。

如果失败在工具调用，看工具返回的错误码。超时看下游服务，参数错误看编排逻辑传参，权限错误看凭证配置。

如果失败在沙盒，看容器日志。常见的是依赖缺失、内存超限、超时被杀。

如果以上都正常，看是不是编排逻辑本身有 bug，比如状态机进入了死循环，或者某个分支没处理。

5.2 常见问题速查表

5.3 几个踩过的坑和对应的经验

第一个坑是过度依赖向量检索。我早期做一个代码问答 Agent，全用向量检索，结果用户问具体函数名的时候经常召回不相关的。后来加了关键词检索做融合，问题解决。教训是：向量检索擅长语义，不擅长精确匹配，两者要互补。

第二个坑是忽略工具调用的副作用。有个 Agent 会调“创建工单”的工具，结果因为超时重试，创建了两个工单。后来加了幂等键，服务端根据键去重。教训是：任何写操作都要假设会被重复调用。

第三个坑是日志记录不全。有一次线上问题，排查了半天，最后发现是某个中间步骤的输入没记录，只能靠猜。后来强制要求每个步骤的输入输出都记录，虽然日志量大，但排查效率高多了。

第四个坑是沙盒镜像没锁版本。有一次基础镜像更新，导致某个依赖不兼容，所有代码执行任务失败。后来把镜像 tag 固定，更新走审批流程。教训是：基础设施的依赖要锁版本，不要用 latest。

第五个坑是提示词硬编码。改一个提示词要重新部署，很麻烦。后来把提示词抽到配置中心，支持热更新，迭代速度快了很多。但要注意，提示词变更也要有版本管理和回滚能力。

5.4 性能与成本的平衡技巧

Agent 的成本主要在模型调用和沙盒资源上。几个降本手段。

模型调用上，分级使用。简单任务用小模型，复杂任务用大模型。判断任务复杂度可以用规则，也可以用一个小分类器。另外，缓存高频问题的答案，能省不少。

沙盒上，复用容器。如果任务之间隔离要求不高，可以用容器池，任务来了从池里取，用完还回去，省去启动开销。但要注意清理任务留下的文件和环境变更。

检索上，控制召回数量。召回 100 条和召回 20 条，后续处理的成本差很多。先用便宜的检索粗筛，再用贵的重排精筛。

提示：成本优化不要牺牲可观测性。省掉日志和 trace 省不了多少钱，但出问题的时候会让你付出更大代价。

6. 数据与智能的进化闭环怎么建

6.1 从执行日志到训练数据的转化

Agent 每次执行都会产生大量日志，这些日志是宝贵的进化素材。但原始日志不能直接用来训练，需要加工。

第一步是标注。哪些执行是成功的，哪些是失败的，失败的原因是什么。这个标注可以人工做，也可以用规则自动做，比如用户点了“不满意”就标为失败。

第二步是筛选。不是所有成功案例都值得学，太简单的没价值，太特殊的可能过拟合。筛选出中等难度、有代表性的案例。

第三步是构造。把执行过程构造成训练样本，输入是任务描述和上下文，输出是动作序列。这里要注意，动作序列的格式要和推理时一致，否则学了也用不上。

第四步是评估。新数据训练出来的模型，要在保留的评估集上测，确认真的有提升再上线。

6.2 反馈信号的采集与利用

反馈信号分显性和隐性。显性的是用户直接评价，比如点赞点踩。隐性的是用户行为，比如是否采纳了 Agent 的建议、是否重新提问、是否中途放弃。

显性反馈准确但稀疏，隐性反馈多但噪声大。我的做法是两者结合，显性反馈作为强信号，隐性反馈作为弱信号，加权使用。

反馈的利用有两个方向。短期是调整编排，比如某个工具经常失败，就换一个或者加保护。长期是调整模型，用反馈数据做微调或者强化学习。

这里有个节奏问题。编排调整可以快速迭代，一天改几次都行。模型调整要慢，因为训练和评估成本高，而且频繁换模型会让效果不稳定。我的建议是编排周级迭代，模型月级迭代。

6.3 持续评估体系的搭建

没有评估就没有进化。Agent 的评估比传统模型评估复杂，因为它是多轮的、有外部依赖的。

评估集要分层。基础层测单步能力，比如检索准不准、工具调用对不对。进阶层测多步任务，比如一个完整的客服流程能不能走通。应用层测端到端效果，比如用户满意度。

评估频率上，基础层每次改动都跑，进阶层每天跑，应用层每周跑。评估结果要可视化，趋势比单点值更重要。

评估的自动化程度要逐步提升。早期人工评估为主，积累足够数据后转向自动评估。自动评估可以用模型做裁判，但裁判模型本身也要评估，避免它和人类判断偏差太大。

7. 一些个人体会

这套东西我断断续续搞了一年多，最大的感受是：Agent 的瓶颈很少在模型，多在工程。模型能力每年都在涨，但数据管道、沙盒、状态管理这些工程问题，不会因为模型变强就自动消失。反而模型越强，能做的任务越复杂，对基础设施的要求越高。

另一个感受是，不要追求一步到位。我见过太多团队想一开始就把架构设计得很完美，结果几个月出不了东西。正确的做法是先跑通最小闭环，哪怕很粗糙，然后在真实使用中发现问题、迭代。基础设施是长出来的，不是设计出来的。

还有就是，可观测性怎么强调都不过分。Agent 的行为是不确定的，没有足够的日志和 trace，你根本不知道它为什么这么做。我现在的习惯是，每加一个新功能，先想好怎么观测它，再写实现。

最后说一个具体的技巧：把 Agent 的每次执行都当成一次实验，记录假设、变量、结果。时间长了，你会积累出一套自己的调优直觉，这比任何教程都有用。