企业官网建设流程全解析

1. AI全栈的完整技术栈：你究竟需要掌握哪几层

这两年我在社区里看到太多人踩同一个坑：花两周学会了调大模型API，兴致勃勃做了个聊天Demo，然后被"全栈"两个字狠狠教育了一顿。前几天还有个朋友问我，说他能写Python、能写React，调通了大模型接口，怎么一接到稍微正式点的AI项目还是手足无措？我说你这不是全栈，你只是站在全栈门口往里看了一眼。

真正的AI全栈开发，核心不是"会调模型"这么简单。你至少得搞定四层东西：

• 模型接入层：选模型、管密钥、做流式、解析结果、处理各种异常
• 编排层：把一次性的模型调用，编排成多步骤的任务流程，也就是Agent该管的活
• 应用层：AI能力和现有业务系统结合，用户认证、权限、计费、数据落库一样都不能少
• 基础设施层：部署、日志、监控、评测、成本控制、灰度发布

很多人的误区是：把90%精力花在第一层，以为模型选得越强项目就越稳。实际上，线上跑挂了、用户被卡死、成本爆表、结果随机波动，问题几乎全出在后面三层。我做过的几个AI项目里，模型调用代码可能只占整个工程量的十分之一，剩下全是围绕它做的工程化打磨。

这篇文章不聊概念，就按照我从接小项目到做生产系统的经验，把每一层里真正决定成败的实践细节捋一遍。不管你是刚转过来的后端开发，还是准备用AI改造现有系统的架构师，都应该从中找到能直接拿去用的东西。

2. 模型接入的工程化：为什么我坚持要一个"统一网关"

2.1 别在业务代码里直接拼各家SDK

刚开始做AI项目的人，最常见的写法是：哪个模型好用，就在代码里直接装哪个的SDK，然后到处调用。今天用OpenAI的GPT，明天换Claude，后天客户要求接国内的DeepSeek、通义千问，代码里就出现了一堆if/else，每个分支的请求参数、返回结构、错误码都不一样。

这个问题在做AI全栈时会被放大，因为AI项目的模型选型迭代速度极快。今天我可能因为某个任务在Claude上表现更好就切换过去，下周可能为了降成本把简单任务路由到更便宜的小模型。如果这些逻辑散落在业务代码里，每次切换都是一次伤筋动骨的改动。

我的做法是：所有模型请求统一从一个内部网关走。这个网关可以自己写，也可以直接基于LiteLLM这类开源方案改。不要小看这一步，它解决的是后续所有工程问题的基础。

2.2 统一网关要做的四件事

一个合格的模型网关，不只是一个转发代理，至少得管好四件事：

第一，协议统一。不管上游是哪个厂商，网关对外只暴露一套接口，请求格式统一，返回格式统一。业务代码完全不知道背后是哪个模型。这样换模型就变成改配置，而不是改代码。

第二，自动降级与容灾。AI厂商的API稳定性说实话参差不齐，高峰期限流、区域网络抖动、间歇性5xx，都遇到过。网关层做多路容灾：主模型挂了，自动重试到备用模型；模型串行超时时切到下一个。实测下来，这个设计能把项目的可用性从"看厂商脸色"拉到99%以上。

第三，统一的限流和密钥管理。密钥不能散落在各个服务里，应该集中在网关中管理，配合按项目和按用户维度的限流。否则某个刷量的用户可能直接把你的月度Token预算打穿。

第四，全量日志和成本核算。每一次请求谁调的、用的哪个模型、多少输入Token、多少输出Token、花了多少钱、耗时多久，全在网关这一层沉淀下来。后面做成本优化的时候，这些数据就是决策依据。

2.3 流式输出与超时处理的两个细节

流式输出是AI应用里最影响体验的部分，也是最容易做砸的地方。很多人在网关层把流式响应缓冲成完整响应再转发，结果用户要等好几秒才能看到第一个字，体验直接崩掉。正确做法是网关对SSE流做透传，同时做心跳检测——如果超过一定时间没有数据输出，主动断开并触发重试。

超时设置也要分场景。对话类请求，用户能接受长一点的等待，可以设60秒；但如果是内部服务调用模型做数据抽取，等不起这么长时间，设15秒就够了。超时后是重试还是降级，要按业务场景提前想好，不能都用一个默认值糊弄过去。

3. Agent编排：把模型从"聊天对象"变成"能干活的员工"

3.1 工具调用是Agent能力的真正边界

很多做AI应用的人对Agent的理解还停留在"多轮对话"。但实际上，从全栈角度切入时，Agent真正厉害的地方在于：模型能调用你给它的工具去完成实际任务。

举一个我做过的例子：一个售后工单分类系统。如果只让模型读一遍工单内容然后输出分类，它的上限也就是个分类器。但当我给它挂了三个工具——"查用户历史订单"、"查常见售后政策"、"提交工单到处理队列"，模型就可以自己判断：这个工单要先查订单确认是否在保修期，再根据保修政策决定走维修还是换货流程，最后直接把工单提交到对应队列。这就是从"聊天"到"干活"的质变。

工具调用的工程潜规则是：工具的描述比工具本身的实现更影响效果。模型通过描述来决定什么时候调用、传什么参数。我见过很多团队在工具描述上偷懒，写一句"查询订单信息"，结果模型在不需要的时候也去调，或者参数传得乱七八糟。正确地写法是把触发条件、参数含义、返回结构都写清楚，你可以把工具描述理解为写给一个理解力一般的新人看的操作手册。

3.2 上下文管理的三个层级

做Agent编排绕不开上下文问题。多轮对话、多步操作，模型能记住的内容是有限的，工程上要把上下文分成三层管理：

短期会话窗口：最近的几轮对话，保留原始内容，这是模型当前推理的主要依据。我的习惯是给它设一个硬性上限，超过就截断。

中期摘要层：当会话超过窗口上限，把前面的对话做一次摘要，把摘要作为上下文的一部分继续对话。注意摘要本身也有信息损耗，要在"保留关键信息"和"避免超窗"之间找平衡。

长期检索层：涉及用户历史、知识库资料的，走RAG路径，把相关内容检索出来后动态注入。这里要强调：不要为了省事把所有资料全塞进上下文，检索的质量决定答案的质量。我踩过坑：知识库塞了一堆相似文档，模型被干扰，输出反而变差。

3.3 自主循环与受控流程：架构选择的权衡

Agent编排架构上，两个极端我都用过。一个是完全自主的ReAct循环——模型自己想下一步干什么，自己调用工具，自己判断是否完成；另一个是完全受控的流程——用状态机把任务拆成固定步骤，模型只负责在关键节点做决策。

我的建议很明确：生产环境优先选受控流程，只在局部放开自主性。原因很简单，完全自主的循环在真实业务里不可控：模型可能在一个错误上反复重试、可能调用工具的次数远超预期、可能在一通乱调用之后得出错误结论，而且这些问题还很难复现和排查。

我现在的标准做法是：先把业务流程画成状态图，找出其中"需要智能判断"的节点，只在这些节点上交给模型决策；其余步骤全部用代码控制。比如一个文档处理流水线，从上传、解析、到派发处理任务，这些是代码控制的；但"这份文档属于哪个类别、是否需要人工复核"这类判断，交给模型。这样既拿到了AI的灵活性，又保住了工程的确定性。

4. 与业务系统集成的数据流设计：AI接口不是普通API

4.1 同步还是异步：先想清楚调用场景

AI接口和普通接口最大的区别是：它慢、它不稳定、它可能失败，而且失败得毫无规律。所以接入业务系统前，第一步要想清楚调用场景应该走同步还是异步。

用户正在对话界面上等回复的场景，只能走同步，但要做好流式返回，让用户看到内容在陆续出来。而像批量文档审核、商品描述批量生成、定时任务里的数据补全，这些完全不需要用户在线等，就应该走异步任务队列。把模型调用放到异步队列里，失败重试、任务追踪、并行度控制都更好做。

我见过一个真实事故：某团队在同步接口里调用大模型做商品信息标准化，模型响应偶尔超过20秒，结果网关超时把请求熔断，用户端不断重试，流量放大了好几倍，直接把模型API的配额打爆。如果一开始就设计成异步任务，定期轮询结果，这个事故根本不会发生。

4.2 重试、幂等与超时：AI接口的容错三板斧

模型API的故障模式比普通数据库还复杂：限流返回429、服务器过载返回5xx、网络抖动直接断连、内容审核触发拒绝，甚至有时候返回200但内容是空字符串或者一堆非法JSON。针对这些情况，容错设计要分层次：

重试策略：429和5xx可以重试，但要带指数退避，第一次等1秒，第二次2秒，第三次4秒，最多重试3次。如果是内容审核被拒或者参数错误，重试一万次也没用，直接记为失败并走降级逻辑。

幂等设计：给每次请求生成一个request_id，网关和模型服务端都认这个ID。重试时带上同一个ID，避免因为重试导致业务数据重复处理。我建议从第一天就做这个设计，后面后悔的成本很高。

降级预案：每个调用模型的业务场景，都要想清楚"模型挂了怎么办"。有的场景可以降级到规则引擎，比如关键词分类；有的场景只能提示用户稍后再试；有的场景可以先返回缓存的历史结果。没有降级方案的AI功能，本质上就是定时炸弹。

4.3 结构化输出：让模型结果能被业务代码直接消费

模型输出的是自然语言，但业务系统需要的是结构化数据。这里最推荐的做法是使用Function Calling或者JSON Schema约束，让模型直接输出符合格式的结果。不过即便有约束，我仍然建议做一道输出校验：格式校验、字段完整性校验、枚举值校验、甚至简单的规则校验（比如数量不能为负数）。

校验不通过怎么处理？我的处理链路是：先解析失败就要求模型重新生成一次，给它的反馈里写清楚哪里不对；二次失败就标记该条数据进入人工复核队列。这个"解析→校验→修复→兜底"的链路，看着繁琐，但线上跑起来非常稳，能省掉大量的人工处理成本。

另外提醒一句：不要让业务代码直接消费模型的原始输出。中间加一个数据适配层，把模型输出转换成业务系统的内部结构。这样以后换模型、改Prompt，都不会影响到下游业务。

5. 上线后的工程闭环：评测、可观测性与成本控制

5.1 评测集：AI项目的"单元测试"

传统开发的单元测试思维，很多人没有迁移到AI项目里。结果是：改了一个Prompt，凭感觉觉得"好像变好了"，上线后才发现大量历史用例结果变差，用户投诉才反应过来。

我的做法是为每个AI功能维护一个回归评测集。这个评测集不需要很大，每个功能50到100条典型输入就够了，但必须覆盖：常见场景、边界场景、容易出错的场景、以及曾经线上出过问题的场景。每次修改Prompt、换模型、调参数，先用评测集跑一遍，看整体效果是变好还是变差。

评测方式根据任务类型来：分类任务就比准确率；抽取任务就比较字段级别的精确率和召回率；生成类任务，我推荐用"LLM-as-Judge"，也就是用一个更强的模型按你定义的评分标准来打分，同时配合人工抽检。注意评分标准要写得很具体，比如"回答是否完整覆盖用户问题中的三个要点"，而不是"回答质量如何"。模糊的标准会让评测结果失去意义。

5.2 全链路日志：没有日志就没有优化空间

AI项目的日志和普通项目不一样。普通项目记个错误信息就够了，AI项目你至少要记录：输入Prompt（处理过敏感信息后）、模型返回结果、Token用量、耗时、成本、经过的工具调用链、最终用户反馈。所有这些信息用一个trace_id串起来，出问题时才能一键还原整条链路。

日志存储要控制成本。全量原始日志很占空间，我的方案是：错误请求和低置信度请求存全量日志，正常请求只采样存10%到20%，另外把统计信息（耗时、Token、成本、状态码）单独聚合存储。这样既能定位问题，又不至于让日志成本比模型调用成本还高。

5.3 成本控制的几个实用手段

模型成本是AI全栈项目里最容易失控的环节。开源模型和各家API的计价差异很大，同一个功能，用不同模型成本能差出10倍。我的几个实战手段：

• 模型分层：简单任务（分类、抽取、改写）用小模型，复杂推理任务才用大模型。实测下来，80%的业务场景小模型完全够用，成本能降一半以上。
• Prompt压缩：上下文越长，成本越高。定期审查Prompt里塞进去的资料，删掉模型用不到的历史对话和冗余背景信息。
• 缓存：对于内容完全相同的请求，比如商品描述的固定模板，直接在网关层做结果缓存，能省掉相当比例的重复调用。
• 定期成本报表：让网关按天输出各业务线、各模型的Token消耗和费用，每周过一眼。成本失控从来不是瞬间发生的，都是积累了半个月才爆发的。

6. 部署与迭代：从Demo到生产环境的最后一公里

6.1 模型API调用还是私有化部署：算清楚再选

很多团队在"用云上API还是自己部署开源模型"之间纠结。我的判断标准很直接：算总账。

调用商业API的好处是省事、迭代快、效果稳定，缺点是单次调用成本随量上涨，且数据要出域。私有化部署开源模型（比如用vLLM跑推理服务）的好处是单次成本随规模递减、数据可控，代价是要养推理集群，还要自己处理推理稳定性问题。

一个比较稳妥的路线是：项目早期和中期无脑用API，业务量起来之后，把高频、高成本的场景迁移到自部署模型，商业API保留作为兜底和复杂任务专用。这样既控制了成本，又不牺牲体验。

6.2 Prompt和模型也要做版本管理

我在大部分项目里看到的现象是：代码有严格的版本管理，但Prompt散落在各个文件甚至生产环境的配置台里，改了什么、什么时候改的、为什么改，完全没有记录。这在AI项目里是很危险的事——Prompt很多时候就是"逻辑本身"，它的变更直接影响线上结果。

现在我把Prompt当作代码来管理，和业务代码一起提交、一起走Code Review、一起发布。模型版本同样固定住，每次发版记录当时的模型版本号，升模型也要走和改代码一样的流程。这样才能保证线上出问题时，你能知道当前跑的到底是哪套"Prompt+模型"组合，才能稳定回滚。

6.3 灰度发布与快速回滚

AI项目的变更风险比普通代码变更更难预估，因为模型和Prompt的效果受输入分布影响，而输入分布是动态的。所以发布策略一定要支持灰度：先放5%流量，观察评测指标和线上日志有没有异常，再逐步放大到全量。

灰度期间重点看三个指标：用户侧成功率、平均响应延迟、以及答非所问的比例（可以通过用户反馈按钮或对低评分样本的自动抽检来估算）。任何一个指标异常，立即切回上一个版本。

关于回滚，我特别想提醒一点：模型上下文相关的状态也要跟着回滚。如果新版本改了Prompt导致对话格式变化，那么缓存里的历史会话摘要可能是旧格式，回滚后要兼容处理，不然会出现"新对话正常、老会话全乱"的尴尬局面。

我在实际项目中还有一个心得：AI全栈的开发节奏，不应该追求一次性把功能做得又大又全。先把一条最简单的链路完整跑通——从一个模型调用，到业务数据落地，到评测日志齐全——然后在这个骨架上逐步叠加Agent能力、优化成本、丰富场景。每一次加功能，都顺手把评测集和观测指标一起补上。这个习惯坚持下来，你的AI项目会和大多数Demo级的作品拉开质的差距。