做AI全栈开发这两年我最大的感受是这个岗位的核心竞争力不是会调几个大模型接口而是能不能把模型能力当成一块普通的“基础设施”嵌进工程体系里。很多人上来就研究Prompt、微调、Agent框架结果项目卡在数据接不上、网关不稳定、线上没法观测这些土问题上。这篇内容不聊概念就聊我在真实项目里沉淀下来的一套可落地的AI全栈实践路径——从模型接入、RAG数据管线、Agent编排到前端交互、测试评估和部署迭代覆盖一个AI应用从零到上线再到持续演进的全过程。适合正在做AI应用开发的工程师也适合想从传统全栈转向AI方向的开发者做参考。1. 先把“全栈”的范围划清楚AI应用的五个层次“AI全栈”这个词太容易让人误解了。我见过不少人以为AI全栈就是会用LangChain写个Agent、能调OpenAI的API、再会点React就够了。真把一个AI产品丢到生产环境里你会发现它比传统Web全栈要宽得多。1.1 从传统Web全栈到AI全栈的变化传统Web全栈的典型链路是前端页面 → 后端接口 → 数据库 → 服务器部署。数据是结构化的逻辑是确定的你写个接口传入参数就能返回预期结果。AI应用多出来的东西是原来这套体系里完全没有的模型层LLM本身是你系统里的一个“不可控组件”有延迟、有随机性、有token成本还经常更新版本。向量数据层RAG需要一套独立于业务数据库之外的向量存储与检索链路。编排层Agent、多工具调用、记忆管理这层负责让模型“会用”你的系统和数据。评估层传统测试断言的是“返回是否等于预期”AI测试断言的是“返回是否合理、是否满足用户意图”。成本与观测层每一次对话都在烧钱每个慢请求都可能让用户流失你得对模型的每一次输出做到可追溯、可计量、可降级。1.2 AI全栈的五个核心层次我习惯把一个AI应用的工程结构拆成五层每一层都有清晰的边界和核心任务层次核心任务典型技术选型交互层流式输出、对话状态、前端降级React/Vue SSE/WebSocket应用编排层Agent逻辑、工具调用、业务流程调度LangChain、自研状态机、Spring AI数据接入层RAG索引、向量检索、业务数据接入PostgreSQL/pgvector、Milvus、Elasticsearch模型网关层多模型统一接入、路由、限流、成本控制LiteLLM Proxy、自研网关模型与推理层基座模型、微调、推理部署OpenAI API、开源模型本地部署、vLLM/SGLang这里每一层都不是孤立的。最典型的问题是很多团队在模型网关层省了事让前端直接调各家模型SDK前期跑Demo很爽一上线就出问题——某个模型供应商挂了整个系统不可用想换模型代码里散落着十几个调用点要改月底账单来了根本分不清钱花在哪个业务线上。1.3 团队能力模型与个人定位如果你是一个人在做AI全栈项目我建议按“一专多能”来布局深度掌握应用编排和数据接入这两层因为这是AI应用的核心业务价值所在模型网关和推理层知道怎么配、怎么选、怎么排查问题就行交互层至少要看得懂流式协议能做基本的联调。如果是团队协作这个分层天然就是分工边界前端工程师负责交互层后端/平台工程师负责网关和编排数据工程师负责RAG管线算法工程师负责模型选型与评估。各层之间以明确的API契约对接避免“AI应用没法分工”这种伪命题。2. 模型接入层统一网关的价值远不止“省事”我现在接手一个AI项目第一件事永远是看模型层是怎么接的。如果看到代码里到处是OpenAI、Claude、国产模型各自的原生SDK调用我就知道后续的开发体验会有多痛。2.1 为什么直接调用SDK不够用直接调用模型SDK在Demo阶段完全没问题代码还更短。但一旦进入生产你会面临一系列实际问题可用性单一模型供应商的API不稳定是常态你需要在多家之间做自动故障转移而不是人工改配置。成本治理不同模型价格差异很大业务场景需要按需分配。一个内部知识问答和一个小学生解题应用用同一个旗舰模型成本是灾难级的。版本管理同一家供应商的模型版本也会升级升级后行为可能变化。你需要有能力把某个业务锁定在特定版本上。可观测性线上出问题的时候你需要知道某个请求用了哪个模型、输入输出是什么、耗时多少、token消耗多少。原生SDK不会替你记这些东西。权限与安全内部系统不能让每个开发者都有模型API的秘钥需要统一入口做密钥管理和访问控制。2.2 LiteLLM Proxy的落地实践在这个环节我是LiteLLM Proxy的重度用户。它的核心能力是把OpenAI兼容的API格式作为统一标准后端对接几十家模型供应商和本地推理服务你只需要改一行配置就能切换模型。我在项目中通常这么配网关层model_list: - model_name: chat-primary litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY - model_name: chat-primary litellm_params: model: anthropic/claude-3-5-sonnet api_key: os.environ/ANTHROPIC_API_KEY - model_name: chat-cheap litellm_params: model: openai/gpt-4o-mini api_key: os.environ/OPENAI_API_KEY router_settings: routing_strategy: latency-based-routing fallbacks: [{chat-primary: [chat-primary-2]}]这里的关键设计是业务系统只认识chat-primary和chat-cheap这样的“逻辑模型名”不认识具体供应商和版本。配置中心一改业务零改动就能切换模型。出问题的时候网关自动走fallback到备用模型用户无感知。提示不要一上来就搞自研网关。LiteLLM Proxy这类项目已经解决了协议转换、重试、fallback、限流、预算告警等大量生产问题自研的成本远高于你的想象。等你真的遇到网关本身的性能瓶颈或特殊需求时再考虑二次开发也不迟。2.3 网关层的成本控制与可观测实践网关层还有一个容易忽略的价值它是全应用唯一的“模型流量关口”天然适合做成本计量。我的做法是在网关层做三件事按业务线和用户维度打标签每次请求带上metadata里面记录业务线、用户ID、功能模块。这样月底对账时能准确知道“A功能花了多少钱、B用户消耗了多少token”。配预算告警用LiteLLM Proxy内置的预算策略给每个业务线设月度token上限超过阈值自动限制或告警。请求日志落库把每条请求的输入输出、模型、耗时、token数、错误信息写入日志存储。这是后面做评测、排查问题、优化Prompt的数据基础。这套东西建好以后模型层对业务而言就成了一个稳定性、成本都可控的能力出口。你和算法团队、业务方沟通的时候拿出来的不再是“感觉”而是精确到每次请求的数据。3. RAG与数据管线让模型“看得见”业务数据的核心路径如果说网关是AI应用的血管那RAG数据管线就是AI应用的大脑供血系统。做过RAG的人都知道网上教程里的“三步走”看起来很简单——导入文档、切分、调API查询。但真实落地时问题一个接一个PDF排版乱、切分把语义切碎了、向量检索召回了不相干的内容、模型拿着错误资料一本正经地胡说八道。3.1 索引链路设计不是所有数据都适合先切再嵌RAG管线的基础是索引。传统做法是读文件 → 按固定大小切块 → 调Embedding接口 → 存入向量库。但根据我的经验不同来源的数据应该走不同的处理方式数据来源推荐处理方式原因PDF/Word/PPT中的正文先做版面解析提取标题层级再按章节切分保留文档结构信息检索时能按章节召回HTML/Web页面提取正文内容去掉导航、广告、版权信息避免噪声影响向量语义表格数据转成Markdown表格或键值对描述不要直接切块表格被切碎后上下文完全丢失数据库中的业务数据直接走结构化查询必要时转成自然语言描述再嵌入结构化数据用SQL更精准别硬套RAG在切分策略上我常用的是“层级切分”先按Markdown标题或文档结构切出大的章节块每块再按内容长度和语义边界切成适合Embedding的片段。每个切出来的块要保留两个关键元数据父块ID方便回溯上下文和来源信息引用溯源用。以常见的文档问答为例我的切分大致是这样的from markdown_splitter import MarkdownHeaderSplitter, RecursiveCharacterSplitter header_splitter MarkdownHeaderSplitter( headers_to_split_on[ (#, H1), (##, H2), (###, H3), ] ) chunks_with_meta header_splitter.split_text(markdown_doc) # 对每个H1/H2/H3下的内容再按1024字符窗口、128字符重叠做二次切分 final_chunks [] for section in chunks_with_meta: recursive_splitter RecursiveCharacterSplitter( chunk_size1024, chunk_overlap128 ) sub_chunks recursive_splitter.split_text(section.content) for i, sub in enumerate(sub_chunks): final_chunks.append({ content: sub, metadata: { **section.metadata, sub_chunk_index: i, } })这样做的好处是既能拿到语义聚焦的小块用于向量检索又能在命中后通过元数据回溯到大章节把完整的上下文交给大模型。3.2 召回策略向量检索不是万能的很多RAG项目召回质量差问题不在Embedding模型而在召回策略太单一——只有向量相似度没有词法匹配也没有结果重排。我的建议是采用“多路召回 重排”的策略向量召回用Embedding模型把查询转成向量在向量库里召回Top 50。这里要选择合适的Embedding模型我建议用专门做中文优化的模型效果比直接用英文模型好很多。关键词召回同时对查询做分词用BM25在全文索引中召回Top 20。这种算法的优势是精确匹配专有名词、型号、人名、编号这些往往是向量模型的弱项。融合与重排把两路结果合并去重用交叉编码器cross-encoder做精排取Top 5交给大模型生成回答。重排这一步效果提升非常明显优先保留段落级的内容而不要对长文本直接做向量召回。“混合检索”的典型实现在Elasticsearch里加一个向量字段用BM25和向量评分做倒数排序融合RRF代码量不大但对召回质量的提升是立竿见影的。3.3 上下文组装与引用溯源召回解决了“找什么”的问题接下来还要解决“怎么给”的问题。直接把Top 5的碎片拼起来塞给模型会出现几个问题召回结果之间互相矛盾每一块单独看有信息但合在一起语义不连贯模型回答后用户不知道信息来自哪里可信度低。我的上下文组装原则是给模型一个带有编号的引用清单每个引用带上来源标题、章节路径和原文关键句。同时要求模型在回答时用[1]、[2]这样的标记来标注信息来源。Prompt里的约束大致是这样你是一位基于资料回答问题的助手。 回答时只使用“参考资料”中提供的信息如果资料不足明确回答“资料中没有相关信息”。 参考资料 [1] 来源产品手册.pdf 3.2 安装步骤 原文摘要... [2] 来源常见问题.md Q15 设备无法启动 原文摘要... 请回答用户问题并在回答句末使用[1][2]标注引用来源。这样处理后用户可以对回答进行溯源验证模型的幻觉比例也会显著下降。这不仅是技术优化也是产品可信度的关键。4. Agent编排从“对话框”到“能干活的系统”工程跃迁AI Agent是近两年最热的方向也是最容易被高估的部分。我的看法是Agent不是比谁调用了更多工具而是比谁的编排逻辑更稳、更可控。真正能上生产的Agent应用靠的不只是模型的推理能力更是工程系统对不确定性的约束能力。4.1 工具调用的协议设计一个Agent要干活就必须调用外部工具查数据库、调API、发邮件、写工单。这里第一个工程决策就是工具调用协议怎么定。最成熟的方案是走Function Calling。OpenAI、Claude、国产模型都支持类似的JSON Schema声明方式。你需要做的是把“工具”抽象成统一的执行单元工具名search_business_orders 描述按用户ID或订单号查询业务订单详情 参数 user_id: string, 可选 order_id: string, 可选 date_range: object, 可选 返回订单列表JSON在代码层面我习惯给每个工具加一个统一的鉴权层和审计日志明确“谁能调用”“调用参数是什么”“返回了什么”“这步消耗了多少token”。AI Agent最容易出问题的不是“不会调”而是“乱调”——模型在没有足够依据时擅自执行了高权限操作。4.2 记忆、规划与多步执行让人工干预成为必要环节Agent的复杂之处在于它需要多步决策。一次任务可能涉及“查询需求 → 拆解子任务 → 调用多个工具 → 汇总结果”。这个过程中最大的坑是让模型自由发挥流程很容易失控。我的工程约束策略用有限状态机约束Agent流程设定明确状态比如waiting_for_user_input、collecting_data、waiting_for_approval、executing、completed。模型只能触发状态转移不能随意跳到未定义的操作。每步工具调用都要有“前置条件校验”如果Agent要查询某个用户的订单必须先确认用户身份已经鉴权否则调用被系统拒绝。关键操作设置人工审批环节涉及发送消息、删除数据、支付、对外承诺等场景Agent只生成操作草稿必须由人工确认后再执行。以“客户投诉自动处理”的Agent为例流程是这样的收到用户投诉 - Agent将投诉分类并抽取关键信息 - 查询订单历史与售后记录 - 生成处理建议 - 进入人工审批 - 审批通过后自动执行退款/补发/工单创建这个流程里模型负责“理解和建议”规则负责“约束和兜底”人负责“关键决策”。这是我认为目前最可靠的生产级Agent形态。4.3 Agent的失败恢复与日志Agent跑多步骤必然会有中间失败某个工具超时、某个数据格式不对、模型连续几次都给出无效的调用参数。不处理这些异常用户看到的就是“对话卡死了”。我在项目中建了一套Agent任务追踪数据结构{ task_id: agent_task_20250101_001, status: failed, current_step: tool_call, attempts: 3, error: tool_search_business_orders timeout after 5s, conversation_state: ... }每次工具调用都记录到任务日志里失败时支持三种恢复策略自动重试对幂等且安全的重试1-2次换个更简单的工具模型重跑当前步骤而不是整个任务重启无法自动恢复时把当前步骤和可选项打包给用户让用户选择下一步。提示Agent项目上线前一定要用历史对话数据做一次“旅程回放”。把过去一个月真实用户的提问喂给Agent看它能不能在每个任务里走到结束状态。别只在几个手工构造的例子上自嗨。5. AI原生前端与交互层流式、状态与降级方案很多AI应用的前端看起来很简单——一个聊天框一个流式输出区域。但真做起来交互层要处理的问题非常琐碎而且直接影响用户对系统“聪明不聪明”的感知。5.1 流式输出体验的核心AI对话应用最基础的交互就是流式输出。这里我强烈建议用SSE而不是WebSocket原因很简单SSE是单向Channel天然适配“服务端生成token推给客户端”的场景断线重连机制也更成熟。前端拿到流式数据的典型处理方式是把返回的增量内容持续追加到同一个消息块里const eventSource new EventSource(/api/chat/stream?conversation_id123); let currentMessage { role: assistant, content: }; eventSource.onmessage (event) { const data JSON.parse(event.data); if (data.type token) { currentMessage.content data.content; updateMessageDOM(currentMessage); } else if (data.type done) { eventSource.close(); setMessageStatus(completed); } };流式渲染时有一个容易被忽略的性能点不要每拿到一个token就做一次完整DOM更新。正确做法是维护一个缓冲用requestAnimationFrame节流刷屏否则高并发输出时页面会卡顿。长对话场景下超过一定长度还要做虚拟滚动或折叠老消息否则内存会撑不住。5.2 对话状态管理AI应用的状态管理比传统表单复杂得多。我总结出最少需要管理这些状态当前对话Id与历史消息数组每条消息的渲染状态pending等待响应、streaming流式输出中、completed、failed推荐问题和快捷操作按钮用于空状态引导引用资料的折叠面板状态。在多轮对话里前端还要维护“上下文窗口”的概念。用户可能会中途修改问题、切换话题你要决定哪些历史消息需要传给后端。这个决策建议放在后端做——前端只回传必要的消息ID由后端根据token预算和相关性动态选择上下文窗口。前端如果一股脑把全部历史都发过去Agent的上下文很容易被无关信息污染。5.3 交互降级与错误反馈模型接口不稳定是AI应用的家常便饭。前端必须有明确降级策略否则用户看到一个大红报错框体验直接归零。我在前端做的几层降级流式中断自动重拉一次如果仍然失败显示“当前服务繁忙”同时建议用户稍后再试。超时兜底如果请求超过设定阈值还没有返回先展示“内容生成中”并给用户一个“停掉生成”的按钮。无结果处理模型说“不知道”的时候不能只给一句话还要推荐相关功能入口或人工客服把对话引导到可解决的路径上。这些细节看起来不起眼但它们决定了用户对你的AI产品是“智能”还是“人工智障”的印象。6. 测试、评估与可观测性AI应用的质量“三件套”传统软件测试的核心是“确定性断言”AI应用没有这种确定性。同一个Prompt模型两次输出可能不同同一个问题换了模型版本结果天差地别。但这不代表AI应用没法做质量保障只是质量体系要换一套思路。6.1 回归测试先保住底线质量我做的第一层回归测试是“断言式”的针对的是那些边界清晰的场景输入为空、超长输入、非法参数系统必须给出正确异常响应而不是崩溃输出必须是合法格式如JSON不能截断、不能缺字段涉及敏感词和越权访问的请求必须被拦截工具调用的参数必须通过JSON Schema校验非法参数不允许执行。这些规则不依赖模型能力保证的是系统的“下限”。这部分测试用传统测试框架就能写跑在CI里自动化执行。第二层回归是“语义评估”。做法是准备一个覆盖核心场景的黄金测试集每个case包含用户输入、期望行为、检验标准。每次发版前让模型跑一遍测试集统计通过率。比如一个客服类Agent测试集里要有“查订单状态”“改地址”“退款政策咨询”“无理投诉”等典型场景。6.2 用LLM评估LLM引入裁判模型针对开放输出的质量评估现在比较成熟的方式是“LLM-as-a-Judge”。用一套评估Prompt让另一个模型通常是更强的主模型或独立的评估模型对回答从多个维度打分评估维度说明正确性回答与标准语料/事实是否一致完整性是否覆盖用户问题的所有关键点可读性表达是否清晰、有条理、不过度冗长引用准确性标注的引用是否真的支持对应的结论需要注意评估模型也会有偏好偏见。我建议每个维度出分数的时候同时要求它输出判断理由方便人工查看。关键场景的评测结果每周人工抽检一次确保自动评测和自己的判断方向是一致的。6.3 可观测性把每次模型交互变成可审计数据AI应用出问题最大的麻烦是“说不清哪里错了”。没有观测数据用户投诉一个回答不对你完全无法定位是Prompt的问题、召回的问题还是模型本身的问题。我的埋点数据模型长这样request_id, conversation_id, user_id model_name, model_version prompt_messages完整的实际发送内容 response_text tool_calls调用了哪些工具参数和返回 latency_ms, prompt_tokens, completion_tokens rag_sources命中了哪些引用 created_at这里关键是prompt_messages和rag_sources要完整记录。前者能让你复现“当时模型到底看到了什么”后者能让你判断“是不是召回的资料不对”。没有这两样你在线上排查AI问题就是盲人摸象。可观测数据量会很大建议按天分表长期数据冷存到对象存储。日志平台的选型上单机和中小规模用企业微信告警加Elasticsearch就够大规模再上专门的Trace系统。7. 部署与迭代从“能跑”到“能持续跑”的工程化差距AI应用的部署和传统后端不太一样除了业务代码你还得考虑模型推理资源、Embedding服务、向量库、以及模型版本的更新策略。这里最容易出问题的是“本地跑通了上生产就挂”。7.1 模型部署与推理优化选项如果业务用的是云端模型API部署相对简单主要做网关和配置管理。如果涉及私有化部署开源模型就要认真评估推理框架和硬件资源。开源模型推理这块我常用的方案是vLLM或SGLang利用PagedAttention和Continuous Batching提升并发吞吐。部署时关注几个关键配置# 示例用vLLM部署Qwen2.5-72B-Instruct python -m vllm.entrypoints.openai.api_server \ --model Qwen/Qwen2.5-72B-Instruct \ --served-model-name my-qwen-72b \ --tensor-parallel-size 4 \ --max-model-len 32768 \ --gpu-memory-utilization 0.9关键参数含义tensor-parallel-size多卡并行度需要根据GPU显存和模型大小计算。比如72B模型用BF16权重大约需要144G显存4张A100 80G或8张4090 24G都能跑但前者更稳。max-model-len最大序列长度。设得太短长对话直接被截断设得太长显存占用和显存碎片会激增。gpu-memory-utilization给KV Cache留多少显存。调得太满并发上来容易OOM一般0.85到0.9比较平衡。7.2 CI/CD与模型版本管理AI项目的CI/CD要比传统项目多考虑一个环节模型和Prompt的版本。代码回滚容易模型回滚就没那么快了。我在CI流水线里配置了这么几个阶段lint unit test代码静态检查和工具函数测试golden-set evaluation跑语义评估测试集对比基线模型分数低于阈值直接failbuild push构建镜像推送到仓库deploy to staging部署到预发环境用真实数据切片做冒烟测试deploy to prod金丝雀发布先切5%流量观察错误率和延迟稳定后全量。Prompt的改动不要直接改代码里的字符串。我习惯把Prompt也纳入配置中心管理每个Prompt有版本号和生效时间线上出问题可以秒级回滚到上一个Prompt版本不必重新发布服务。7.3 上线后的数据闭环AI应用上线不是终点而是数据积累的起点。用户真实的对话日志是你优化Prompt、召回质量、产品体验的最宝贵资产。我建议每两周做一次“bad case评审会”从线上日志里抽取出那些用户不满意的回答包括“用户点了不喜欢反馈”“用户重复问同一个问题”“Agent中途放弃”等信号。每一条bad case都要往下拆一层到底是知识库没有资料、检索没召回、还是模型指令遵循不强这个环节没法自动化完全替代但它恰恰是AI全栈工程师区别于“只会调API的开发者”的分水岭。你能从数据里定位问题、改对地方系统就会持续变好。8. 反模式清单我在项目中反复踩过的坑最后整理一份反模式清单都是我亲自踩过、也看到身边团队反复踩的教训。每一条都是一个“我当初要是早知道就好了”的坑。8.1 上来就微调模型而不是先做RAG很多团队业务知识问答效果不好第一反应是微调模型。这个方向大多数时候是错的。微调适合改变模型的行为风格和输出格式不适合灌输事实知识。事实类知识应该走RAG靠检索注入上下文。微调一个72B模型的一次实验成本足够你把RAG管线反复调优好几轮了。先上RAG再根据RAG覆盖不了的长尾问题考虑微调性价比完全不一样。8.2 忽视延迟控制导致产品体验崩塌大模型调用天然有延迟但很多开发者在设计流程时不加控制。一个用户问题走了“意图识别 → 数据查询 → 二次生成 → 摘要总结”四步模型调用单步2秒总耗时8秒用户早走了。延迟预算要拆解到每一步哪些步骤可以并行哪些步骤可以用小模型快速处理哪些步骤可以用缓存命中。现在的模型网关层都支持多模型路由快慢模型穿插使用是基本操作。8.3 对用户输入没有基本防护AI应用只要对外暴露就会遇到各种输入有些是恶意的、有些是无意识的破坏。不能因为“模型很聪明”就放松输入校验。防护至少要做到在网关和业务层做基于规则的输入长度、格式、敏感词过滤对工具调用的参数做严格JSON Schema校验Agent执行高权限操作前必须有独立的审批确认环节对外提供的接口要有独立于模型层的鉴权体系。8.4 日志里没有Prompt和召回快照这是排查效率的天花板。没有完整的Prompt记录和RAG引用快照线上问题基本没法定位。你只看得到一个“回答错误”不知道是哪个环节错了。这个前面已经强调过这里再放一次因为它的重要性怎么强调都不为过。结个尾分享一个我最近的体会这两年我越来越觉得AI全栈开发真正的难点不在AI算法本身而在“如何用工程手段把一个高不确定性系统管住”。模型能力会持续变强今天的最佳实践可能半年后就过时了但分层架构、统一网关、RAG管线、评估体系、可观测数据闭环这五根柱子是不会塌的。它保证的是不管底层换哪个模型、Agent框架怎么变你的系统都能快速适配、稳定运行。最后给一个可以立刻落地的小建议别急着现在就把系统做得多复杂。先用统一网关把你的模型调用收敛到一个入口再把请求日志和Prompt快照落库。这两步做完你后续做评估、做优化、做任何AI改造都会发现手上终于有了“数据”而不是“感觉”。项目一步步长起来这大概就是AI全栈开发最实在的乐趣所在。
