AI全栈开发实战：技术选型、RAG、Agent与生产化全攻略

早上十点，产品经理推开门，说我们要做一个智能助手。作为后端工程师，你可能觉得这事已经很平常：接大模型、做提示词、部署上线，所谓“AI全栈开发”嘛，不就是把这些串起来？但真把一个AI功能做到生产级，你遇到的第一件事往往是用户并发把账单打爆，第二件事是模型一本正经地给出一个完全错误的答案，第三件事是线上报错但你根本不知道模型当时说了什么。

这几年我带过好几个AI项目，从最初“一人一周搓出Demo”，到后面支撑日活几十万的活动页和客服系统，逐步沉淀出一套相对稳定的打法。这篇文章不聊空泛的概念，我把AI全栈开发的最佳实践拆成六个部分：技术选型、提示词与上下文管理、RAG链路、Agent编排、生产工程化，以及实际项目中踩过的坑。适合正在把大模型接入业务系统的后端/全栈工程师，也适合技术负责人拿去当团队内部评审时的参考框架。

1. AI全栈开发到底在开发什么：先把“三层版图”画清楚

1.1 三层架构：模型服务、业务编排、前端体验

很多团队做AI项目失败，不是模型不够强，而是压根没想清楚自己要开发什么。AI全栈应用至少包含三层，每一层的关注点完全不同。

第一层是模型服务层。这里的问题不是“调用OpenAI还是国产模型”，而是你有没有把模型当成一个可替换的组件。模型服务层要负责任何与模型相关的细节：API网关、超时重试、模型版本管理、密钥安全、流式转发、Token计量。如果你把这些逻辑散落在业务代码里，后面每次换模型或调参数都会是一场灾难。

第二层是业务编排层。这是AI全栈开发真正的主战场。用户问“我的订单什么时候到”，系统不是直接把这句话丢给大模型，而要先判断意图，再查询订单系统，把订单状态作为上下文交给模型，最后让模型组织语言回答。这个“判断-查询-组织答案”的过程，就是业务编排。它可能是一个简单的前置函数调用，也可能是一套带状态机的Agent流程。这层的工程质量，决定了AI能力是“玩具”还是“生产工具”。

第三层是前端体验层，常见误区是直接怼一个聊天框上去。聊天框只适合少数场景，更多的业务应该把AI能力嵌入到原有交互里：商品详情页的“参数解读”、工单页的“自动归类”、报表页的“问题归因”。前端的核心指标是用户能不能感知到AI的价值，而不是界面看起来多“科幻”。

把这层想清楚，你会发现AI全栈开发和传统业务后端开发没有本质区别，模型只是一个远程依赖。但恰恰因为它是远程依赖，且输出不稳定，才产生了一系列全新的工程课题。

1.2 技术选型的取舍：手写调用、LangChain还是Spring AI

技术选型是每个团队都会纠结的问题。我见过三种典型路线：直接用官方SDK或HTTP调用、引入LangChain这类通用编排框架、使用Spring AI这类和业务后端深度绑定的框架。它们没有绝对优劣，取决于你的团队和场景。

直接调用适合功能点少、业务简单的项目。比如只做一个“文章标题生成”的小工具，你的核心逻辑可能就是构造HTTP请求、解析响应。这时候引入框架反而多一层维护成本，每次框架升级都可能带来兼容性问题。

LangChain及其生态的优势在于工具链完整，文档、Agent、记忆、检索模块都现成的，适合快速验证复杂想法。但缺点也明显：抽象层级多，出了问题排查链路长，版本变化快，老项目升级经常“感动常在”。如果你的团队成员偏算法背景、实验性质强，选它没有问题。

Spring AI对于Java技术栈、尤其是后端体系已经比较重的团队，是更顺手的选择。它可以像写Spring MVC接口一样写大模型调用，和现有服务的配置体系、监控体系天然融合。今年Spring AI版本迭代明显提速，从早期只是封装ChatClient，到慢慢补齐了结构化输出、Tools、RAG、Advisors等模块，已经能支撑真实业务。它的社区和文档虽然远不如LangChain热闹，但只要沉下心看源码，反而更好掌控。

下表是三种方案的快速对比：

我做选型时有个原则：框架只解决“接入和编排”问题，不把业务的灵魂交给框架。无论选哪条路线，都要在业务层封装一层自己的AI服务接口，这样将来换框架、换模型，甚至从LangChain迁到Spring AI，代价都可控。

1.3 选模型不等于选服务：模型也要做“可用性清单”

模型选型不是挑“谁最聪明”，而是要建立一张可用性清单，包含至少这些维度：上下文长度、输出格式稳定性、响应延迟、并发上限、计费方式、数据合规要求、私有化部署可行性，以及它在特定领域（比如代码、法律、医疗）的实际表现。

我遇到过不止一次因为只关注“效果”而翻车的案例。某个团队选了一个效果很好的大模型，结果它的平均首字延迟就超过4秒，交互体验直接被用户吐槽。另一个案例是模型对JSON格式支持差，十次输出里三四次有残缺或多余标点，导致下游解析系统崩溃。这些都是离线评测时不会暴露、上线后立刻暴露的问题。

技术水平上，建议把模型能力分成三档：轻量模型处理分类、抽取、改写等简单任务；中等模型处理一般对话和工具调用；重量模型只处理复杂推理和长文本规划。不是所有请求都必须用最强模型，也不是所有请求都能用最小模型。后面成本治理的部分我会再展开。先把这层“能力地图”画好，你的AI全栈才算有了骨架。

2. 提示词与上下文管理：最容易被低估的两块硬骨头

2.1 提示词不是聊天框里的一段话，而是线上配置

很多团队把提示词直接写在代码里，或者由产品同学在调试面板里“调一调”。这种做法在早期没问题，一旦上线，你会发现提示词就是业务逻辑：改了提示词，回答口径就变了，用户看到的结果也变了。它理所应当像代码一样被管理。

我的习惯是把提示词抽象成“系统提示模板 + 业务变量 + 输出约束”三部分。系统提示模板是一段稳定的指令，包含角色、任务、原则、禁止事项；业务变量是动态拼入的数据，比如订单信息、商品参数、用户偏好；输出约束则明确指定格式和边界。整个模板放到独立的配置文件或模板目录里，和业务代码一同走版本管理，有变更必须走评审。

一个典型的模板结构是这样的：

你是{shop_name}的智能导购助手。 你的任务是基于以下商品信息回答用户问题。 商品信息： {product_info} 回答要求： 1. 只能使用上面提供的商品信息，不要编造参数。 2. 如果信息不足，请直接说“需要进一步确认”，不要猜测。 3. 结果的格式为JSON，包含字段：answer、need_more。

这样设计的好处是：提示词变更可以Review，模型行为可以追溯，同一套模板还能适配不同模型。如果你用Spring AI，可以把提示词模板写到resources目录下，运行时用PromptTemplate加载；如果你想做得更重一点，甚至可以做一个提示词管理后台，让运营同学在审批流内调整话术，本质上它的地位和运营规则配置是一样的。

2.2 上下文窗口的预算方案：滑动窗口加关键信息保留

上下文窗口是AI全栈开发绕不开的“预算问题”。很多大模型号称支持几十万Token，但你真的把用户历史全塞进去，结果往往是效果变差、成本暴涨、速度感人。不要因为是长窗口模型就挥霍上下文，人类开会不会把会议纪要全文念一遍，模型也一样。

我用的策略是给上下文做“分层预算”。固定层包括系统提示和用户本次输入，这一层不可压缩；参考层是从RAG或业务系统检索出来的信息，控制在一个上限之内；历史层是之前的对话内容，采用“最近N条 + 长期摘要”的组合。举个例子，假设我们把上下文预算切成100份，系统提示占20，本次输入占10，参考资料占40，历史对话占30，其中历史对话再细分：最近的6条完整保留占20，更早的对话压缩成摘要占10。

滑动窗口实现可以很简单：维护一个消息列表，超过阈值就把最早的消息取出，调用一次轻量模型生成摘要，然后把摘要塞回消息列表头部。每次对话结束再更新摘要。这样用户聊30轮和聊300轮，历史层占用的Token始终是恒定的。这是我从真实客服系统里验证过的方法，成本可控，体验也好。

上下文管理还有一个容易忽视的问题：消息乱序和字段冗余。你在调试时可能看到一条消息里同时存在tool_call、tool_result、assistant消息，代码里如果不严谨地过滤，模型会看到一堆内部噪音。最佳实践是把发送给模型的消息结构严格收敛成三种：System、User、Assistant，工具调用内容尽量压缩并标记为不可见或只保留结果摘要。

2.3 输出格式控制：让模型返回能被程序安全解析的内容

没有任何一件事比“解析模型输出失败”更让人暴躁的了。模型告诉你返回JSON，结果它从Markdown代码块开始了；模型说好的数组，结果多了一个逗号。指望模型永远规规矩矩输出，不如在工程上做四层防御。

第一层，使用模型自带的结构化输出功能。现在主流模型都支持JSON Schema约束或response_format参数，只要在请求时显式声明，输出格式的稳定性能大幅提升。如果你的框架不支持，至少要在系统提示里给出严格格式示例，并且注明“只输出JSON，不要解释”。

第二层，解析时使用容错逻辑。不要直接扔给JSON.parse，去掉首尾可能出现的json和标记，找到第一个{和最后一个}，再尝试解析。解析失败时，把原始输出记录到日志，并让用户侧得到一个可理解的“重新生成”操作，而不是报一个500错误。

第三层，设定“if parse fail then retry”机制。常见做法是让模型自己修复输出：把解析失败的片段和错误信息发给模型，让它重新生成一次。这在Agent链路里尤其有用，一次自动重试通常能挽回80%的失败。注意设置最大重试次数，别让系统陷入无限循环。

第四层，所有结构化输出必须有对应的数据校验。模型返回了JSON，不代表字段值一定合法。商品ID是否存在、日期格式对不对、分类是否在枚举范围内，这些校验必须在业务层做，而不是默认模型一定对。把模型当成一个不太靠谱的下游服务，你会舒服很多。

3. 打通内部知识：RAG链路的工程化做法

3.1 数据准备才是RAG效果的天花板

RAG（检索增强生成）是目前让模型“懂业务”最主流的方式。但团队最容易犯的错误，是花大量时间调向量检索参数，却不舍得在产品文档和知识整理上投入。事实上，RAG效果的上限由数据质量决定，检索只是把质量变现的渠道。

先做数据清洗。把原始文档里的页眉页脚、导航栏文字、图表乱码、重复段落全部清除。然后是结构解析，不要把PDF直接切成长度过大的块再丢给向量库。先用文档解析工具把标题层级、段落结构识别出来，如果内容本身有明确的条目、问题、答案，就按“一整个问答对”作为一个独立单元。表格数据建议转成Markdown或键值对描述，模型对纯表格的理解能力远不如自然语言。

分块策略上，我通常用“语义段落优先 + 字符数兜底”的方式：先按Markdown标题切出章节，章节内部再按段落切，每个块设一个目标长度范围，比如500到800字，块与块之间保留少量重叠，比如50字。这个重叠很关键，它在上下文边界处起到缓冲作用，能明显改善检索漏块问题。不要迷信“块越小相关性越高”，块太小会丢失上下文语义，模型拿到碎片根本无法组织完整答案。

3.2 向量检索加关键字检索的“混合召回”

向量检索解决的是语义相似问题，但它有天然弱点：对专有名词、SKU编号、缩写和精确短语不敏感。“iPhone 15 Pro Max 256G”这种商品名，向量化之后你很难保证它和“苹果手机”是对的咬合关系。所以实际项目里，单靠向量检索基本不够。

我推荐做混合检索：一路走向量检索，召回候选；另一路走倒排索引/关键词检索，召回精确匹配。两边各取TopN，再做合并去重。如果你团队里已经有Elasticsearch，直接在ES里同时配kNN查询和BM25查询，然后用RRF（Reciprocal Rank Fusion）融合排名。Redis、Milvus这类向量库也有自己的混合检索能力，如果从零选型，优先选择同时支持向量和标量过滤的存储。

标量过滤经常被忽略，但在真实业务里价值极高。比如电商场景按类目过滤、客服场景按知识库来源过滤、制造业场景按设备ID过滤。先通过标量过滤缩小候选集合，再做向量检索，速度和准确率都能提升。现在不少向量库把这种过滤放在索引层面，支持“先过滤后搜索”，查询性能直接翻倍。

3.3 检索之后：重排、引用和可信度校验

召回Top20，不代表Top1就一定是答案。我把RAG链路设计成“召回-重排-生成”三段式。召回阶段用简单但速度快的算法多取一些候选，重排阶段用更重的模型（比如bge-reranker）对候选逐条打分，最后把Top3到Top5的结果喂给生成模型。

重排模型的价值不可小觑。它通常是一个交叉编码器，能同时看到问题和文档，比向量检索“先各自编码再算相似度”的双塔方式更准。实测下来，好的重排模型能把准确率提升5到15个百分点，而且它对长文档和短问题的匹配效果，明显优于单纯向量距离排序。

生成阶段也要做约束：要求模型必须引用来源编号，比如“根据资料[1]”，严禁输出没有依据的内容。然后在返回前端前，程序里校验答案涉及的引用编号是否都在检索结果范围内，发现凭空引用就把对应句段拦截或降级。如果你的知识库强于合规性要求，甚至可以做“无检索引不回答”的模式，宁可让用户觉得笨，也不能让模型胡说八道。

最后，RAG链路需要有评测集。我会为每个业务场景准备至少100到200个“问题-期望答案来源段-是否应拒答”的三元组，每次改数据、改分块、换模型，都跑一遍召回率指标。不要凭感觉说“好像变好了”，要用数据说话。

4. 从问答到干活：Agent与Function Calling的落地姿势

4.1 定义工具：给模型一份“能力说明书”

Agent和普通问答最大的区别，是模型可以调用工具去完成真实任务。但这个能力是一把双刃剑，模型对工具的“理解能力”完全取决于你给它的说明书。

每定义一个工具，必须说清楚四件事：工具名称、功能描述、入参格式、调用限制。名称要用动词短语，比如query_order_by_id，不要叫getData1这种没头没尾的；功能描述要写“这个工具根据订单ID查询订单当前状态、物流信息、支付信息”，不要只写“查询订单”；入参要给出JSON Schema，注明必填字段和类型；调用限制要写明“只有当前登录用户是订单所属人时才能调用”。模型并不天然理解业务权限，它需要一份极其清晰的说明书。

实际编码时，多数框架把工具定义成注解方法或函数，框架会自动生成描述元数据。但框架只会序列化方法签名，不会替你补全业务语义。我建议在方法注释里写得非常详细，甚至可以自定义工具描述，把正常人类工程师交接工作时需要的业务背景都写进去。工具描述越清晰，Agent误调用、乱传参的概率越低。

4.2 让Agent按流程办事：工作流约束与状态管理

很多人对Agent最大的误解，是以为“让模型自由发挥”才算Agent。真实生产环境正好反着：越自由，越容易出事。我见过Agent自说自话把两件不相干的事串在一起执行，也见过它在工具调用循环里反复尝试一个根本不存在的参数。

我的建议是采用“有限步骤Agent”模式，也叫工作流加局部Agent。把业务流程拆成节点：意图识别、参数抽取、执行查询、结果分析、答案生成。流程本身用代码控制，模型只在每个节点内部做决策。比如先让模型把用户输入做意图分类，如果意图是“查物流”，就走查物流的节点，节点内部再让模型从上下文中抽取订单号，代码校验订单号后调用查询接口，再把结果交给模型生成回答。

这样做的好处是每一步都可控、可观测、可回滚。模型错了只错在某一个节点，而不是把整条链路带跑偏。如果你一定要做开放式Agent，也要给它套上三根缰绳：最大迭代次数（比如10次）、单次工具调用的超时时间、每轮结束后的“目标达成判断”。一旦超限就中止，并输出“暂时无法完成”的兜底文案，绝不能让它空转。

状态管理方面，每个会话要有独立的状态快照，至少要保存用户身份、会话上下文、以及已执行工具的调用链。Model本身是无状态的，状态必须放在你的应用内存或Redis里。分布式部署时尤其要注意，同一个会话的连续请求尽量路由到同一个服务实例，否则状态同步又是一堆破事。

4.3 处理调用失败、幻觉与安全边界

工具调用失败是常态，不是异常。我在代码里专门定义一个AgentToolException，任何工具执行失败都会包装成这个异常，并把错误信息返回给模型，让它调整参数后重试或改走别的工具。这么做比直接中断对话体验好太多，很多时候模型会自动意识到“参数不对，换一种提取方式”。

模型幻觉在Agent场景会被放大，因为它会为了完成任务“脑补”数据。防幻觉要靠两层约束：第一层，工具返回的结果必须标记为“唯一事实来源”，提示词里反复强调“只能使用工具返回的数据，禁止从未知来源补充细节”；第二层，生成回答前做一个字段校验，凡是涉及金额、日期、单号的数据格式必须合法，格式不对就判定为错误输出。

安全问题更要提前设防。模型可调用的工具等同于开放出来的API能力，权限控制必须在工具执行层校验，不能指望模型自己判断。每一个工具入口都要做身份验证、数据权限验证、操作审计日志。你可以在Agent里配置工具白名单，不同角色对应不同工具集：普通用户能查自己的订单，客服能查范围内的订单，管理员才能改数据。模型只是触发工具的一个“智能入口”，绝不能让模型成为绕过权限后门的路径。

5. 生产环境四件套：流式响应、可观测、评测、限流降本

5.1 流式传输的落地细节：SSE连接管理与超时

用户不喜欢面对一个转圈很久的界面。大模型生成完整响应可能要十几秒，但首字返回往往在1秒内，所以生产级AI应用几乎必然要上流式输出。SSE（Server-Sent Events）是后端推送流式文本的主流方式，因为它基于普通HTTP，穿透性好，实现简单。别上来就用WebSocket，除非你需要双向实时通信，否则SSE足够。

用Spring AI做流式功能时，接口可以返回Flux或者SseEmitter。我习惯选择SseEmitter，因为更容易控制超时和连接生命周期。注意几个关键参数：连接超时时间要设置比模型最长生成时间更长，一般给到120秒；每次写入前要检查客户端连接是否关闭，避免对断开的连接填充数据；整个流结束时必须显式调用complete()，否则前端的EventSource会一直等待。

大模型自身也可能中途断开，这在长文本生成时经常发生。前端要做好“部分内容也能展示”的容错，后端要做好“断流后清理上下文状态”的兜底。流式传输下Token统计常常被忽略，你要在响应结束事件里携带本轮的Token消耗，让前端埋点上报，否则成本报表就是一笔糊涂账。

5.2 可观测性：不记录这些数据，出了问题等于抓瞎

传统后端出问题，看日志、看错误栈、看慢查询就能定位。AI应用多了两个不确定性：模型返回内容不可预测，且原因不在自己代码里。这时可观测性设计就变得极其重要。

第一层是链路追踪。每次请求生成一个traceId，贯穿用户请求、业务编排、检索调用、模型调用。日志里必须记录：模型名称、模型版本、提示词是否命中缓存、检索命中了哪些文档、工具调用了哪些函数、各阶段耗时、Token消耗、以及完整输入与输出。这些数据在你调优和排查问题时会像“黑匣子”一样有说服力。

第二层是业务效果监控。模型返回之后，用户点了“有用”还是“无用”，有没有复制答案，有没有二次追问，这些反馈信号要采集下来。没有效果反馈的AI系统，就像没有质检的生产线，你不知道自己每天到底在交付什么质量。

第三层是成本监控。按用户、按场景、按模型三张表统计Token费用，设置日预算告警。很多团队上AI应用后发现成本失控，就是因为只有总账单，没有分账能力。成本数据的滞后性太致命，必须要准实时甚至实时汇总。

5.3 持续评测机制：给AI做“自动化测试”

传统代码有CI/CD，AI应用也要有“模型测试”。但模型输出是概率性的，不能只断言一个精确值。我对AI评测的理解是三层：离线评测、线上灰度、用户反馈闭环。

离线评测集必须和业务强相关，不要拿公开的通用Benchmark直接充当生产验收。比如你做客服助手，评测集就应该是“用户咨询-期望工具调用-期望回答要点”这样的真实际对话。每次改动提示词、检索策略、模型版本之前，都跑一遍离线评测，观察通过率有没有下降。我团队里现在把这步做成了CI任务，发布前自动触发。

线上灰度是最可靠的验证。新模型版本、新提示词策略不要全量切换，先放10%流量，对比回答采纳率、无意义回答率、用户投诉率等指标。AI项目的灰度窗口要比普通功能长一些，因为很多问题需要多轮对话才能暴露。

用户反馈闭环不是简单放一个点赞点踩按钮，要把反馈和具体回答绑定入库。每周Review哪些回答被打差评，分类汇总，找到高频问题驱动提示词或数据优化。这套循环转起来，你的AI能力才会一周比一周强。

5.4 成本控制与限流降级

账单爆炸是AI应用上线后最现实的管理危机。大模型按Token计费，无节制地堆长上下文、频繁重试、让Agent空转，都会快速烧钱。成本控制必须前置到架构设计，不能等账单出来再喊疼。

我的成本策略是三级模型路由。简单抽取和分类用轻量模型，常规对话用通用模型，复杂推理和长文本生成才动重量模型。每个接口在业务层就定义好model的级别和上限，不允许业务方绕过这层随意指定模型。然后再加一层语义缓存，用户的重复或不完全重复问题直接命中缓存，不再调用大模型。比如商品详情页的“帮我总结卖点”，短时间内一千个用户问同样的问题，缓存把成本直接打到接近零。

限流和多级降级用于保护预算和体验。按用户、按接口分别设置速率限制，超过配额就提示“服务繁忙”。降级意味着大模型不可用时，自动切换到兜底逻辑：比如退回检索摘要、返回预置话术、或者提示稍后再试。降级预案要在上线前就演练一遍，别等到线上故障了才临场写代码。

6. 复盘与速查：AI全栈开发中的经典故障

6.1 四个真实翻车现场与排查思路

场景一：模型返回的JSON解析失败。当时系统频繁报错，用户侧看到“服务错误”。排查时发现模型输出偶尔会带着Markdown标记，或者JSON里混进了多余的逗号。后来加上两层容错：先清理首尾标记再解析，解析失败自动重试一次，同时开启模型的结构化输出参数。报错率从5%降到0.1%以下。

场景二：Agent陷入死循环。某个测试用户不按常理出牌，连续追问模糊不清的问题，Agent在“参数抽取-调用工具-失败-再抽取”的循环里空转了十几分钟，Token费用一路飙升。后来代码里强加了最大迭代次数和单步超时，同时增加了“参数确定性不够时直接反问用户”的节点，不再让模型反复猜。

场景三：上下文爆炸导致回答质量劣化。用户连续聊了几十轮后，模型开始答非所问。原因是历史消息全部塞进了上下文，早先的业务信息被后续对话稀释。后来改成“窗口截断加摘要压缩”，并把关键用户信息（姓名、订单号、问题类型）单独提取为会话级变量，每次请求都固定注入，基本解决了长会话劣化问题。

场景四：线上用户被幻觉答案误导。客服助手回答某个退款问题时，编造了一个不存在的退款政策。原因是提示词里没有强约束“只能依据资料”，且知识库没有返回相关政策文档。后来改成“无检索引不回答”，生成答案必须带引用编号，并在前端展示来源，用户侧误导投诉明显下降。

6.2 高频问题速查表

这套速查表我一直贴在项目文档里，每次有新同事加入先读一遍，能少踩不少坑。AI全栈开发看起来全是新东西，本质上还是工程问题：可控、可观测、可回滚才是王道。我个人这几年最大的体会是，别被模型能力牵着走，也别被框架生态带着跑，业务场景需要什么，就老老实实把那一环做到极致，这比追任何热点都管用。