1. 从一张架构图说起AI应用到底该怎么搭这两年我参与过不少AI应用项目的评审和落地发现一个特别普遍的现象很多人一上来就急着写Prompt、调API、接模型结果做到一半发现整个系统像一团乱麻——模型换了要改几十处代码加个新工具要动核心逻辑想做个多轮对话状态管理得从头造轮子。说到底问题出在动手之前没有把架构想清楚。“图解AI应用架构设计”这个主题核心就是解决一件事用可视化的方式把AI应用从底层模型到上层交互的完整链路拆解清楚让开发者知道每一层该放什么、层与层之间怎么通信、哪些东西该抽象、哪些东西该固化。它适合正在做AI应用开发的工程师、正在设计Agent系统的架构师也适合刚入门想搞清楚“一个AI应用到底由哪些部分组成”的学习者。我个人的判断是2024年之后AI应用开发已经从“能不能跑通”进入“能不能扛住”的阶段。早期大家写个脚本调一下LLM接口就算AI应用了现在要考虑多模型切换、工具调用编排、上下文管理、并发控制、安全防护、可观测性等等。这些需求叠加在一起如果没有一个清晰的架构设计代码会迅速腐化。所以这篇文章我会从架构分层、核心组件、实操搭建、问题排查几个维度把AI应用架构设计这件事讲透尽量做到你看完能直接对照着画自己的架构图。2. AI应用架构的整体分层与设计思路2.1 为什么不能把AI应用写成一个“大函数”我见过最简陋的AI应用是这样的一个Python文件里面一个函数接收用户输入拼接Prompt调用OpenAI接口返回结果。这种写法在Demo阶段没问题但一旦要加功能——比如支持多轮对话、支持工具调用、支持切换模型——这个函数会迅速膨胀到几百行改一处崩三处。架构设计的本质是分离关注点。AI应用和传统Web应用最大的区别在于传统应用的核心逻辑是确定的if-else、循环、数据库查询而AI应用的核心逻辑包含了一个不确定的组件——LLM。LLM的输出不可预测、有延迟、有成本、可能失败。所以架构设计的第一原则就是把LLM当作一个不可靠的外部依赖来对待围绕它做隔离、降级、重试和监控。基于这个原则我把AI应用的架构分为五层从下往上依次是模型层LLM、Embedding模型、Rerank模型等负责推理和生成能力层Prompt管理、上下文管理、工具/函数注册、记忆系统编排层Agent逻辑、工作流引擎、任务规划、多步推理控制接口层API网关、鉴权、限流、请求路由应用层对话界面、业务逻辑、数据持久化、监控告警每一层只和相邻层通信层内可以替换实现而不影响其他层。比如你把GPT-4换成Claude只需要改模型层的适配器编排层和接口层完全不用动。这就是分层架构的价值。2.2 模型层别把鸡蛋放在一个篮子里模型层看起来简单——不就是调API吗但实际项目中模型层要处理的问题非常多。首先是多模型适配。不同厂商的API格式不一样参数命名不一样返回结构不一样。如果你在业务代码里直接写openai.ChatCompletion.create(...)那换模型的时候就得全局搜索替换。正确的做法是定义一个统一的模型接口抽象比如class BaseLLM: def chat(self, messages: list, tools: list None, **kwargs) - LLMResponse: raise NotImplementedError class OpenAILLM(BaseLLM): def chat(self, messages, toolsNone, **kwargs): # 适配OpenAI格式 ... class ClaudeLLM(BaseLLM): def chat(self, messages, toolsNone, **kwargs): # 适配Claude格式 ...这样上层只需要依赖BaseLLM具体用哪个模型通过配置决定。我实测下来这个抽象层大概多写200行代码但后续换模型、加模型、做A/B测试的时候能省掉大量重构时间。其次是模型路由。不同任务对模型的要求不一样。简单的意图分类用便宜的小模型就够了复杂的推理任务才需要上大模型。你可以在模型层做一个路由策略根据任务类型、输入长度、历史成功率动态选择模型。这不只是为了省钱也是为了控制延迟——小模型的响应速度通常快很多。注意模型路由策略一定要有fallback。我踩过的坑是某次主力模型服务抖动因为没有配置备用模型整个应用直接不可用。后来加了自动降级逻辑主模型连续失败3次就切到备用模型同时发告警。2.3 能力层Prompt、上下文和工具注册能力层是AI应用架构中最“AI”的部分也是最容易写乱的部分。Prompt管理不是简单地把字符串存在代码里。一个成熟的Prompt管理系统应该支持模板变量替换、多版本管理、A/B测试、按场景切换。我通常会把Prompt存在数据库或配置文件中每个Prompt有唯一ID和版本号代码里通过ID引用。这样产品经理改Prompt不需要发版运营可以做实验对比不同Prompt的效果。上下文管理是另一个重灾区。LLM有上下文窗口限制对话轮次多了之后必须做截断或摘要。常见的策略有几种滑动窗口保留最近N轮、摘要压缩把早期对话用LLM总结成一段话、关键信息提取只保留实体和意图。我一般会组合使用——最近5轮保留原文更早的做摘要系统指令永远保留。工具注册是Agent能力的基础。每个工具需要定义名称、描述、参数Schema、执行函数。描述非常重要LLM就是靠描述来判断什么时候该调用哪个工具。我见过很多工具调用失败的情况排查下来都是描述写得太模糊LLM根本分不清什么时候该用。tools [ { name: search_knowledge_base, description: 在内部知识库中搜索相关文档。当用户询问产品功能、操作步骤、常见问题时使用此工具。, parameters: { type: object, properties: { query: {type: string, description: 搜索关键词} }, required: [query] } } ]2.4 编排层Agent的大脑编排层决定了AI应用是“单轮问答”还是“能自主完成复杂任务”。简单场景下编排层就是一个线性流程接收输入→组装Prompt→调用LLM→解析输出→返回结果。但Agent场景下编排层要复杂得多。一个典型的Agent循环是这样的LLM思考当前状态→决定下一步行动调用工具/直接回答→执行行动→把结果喂回LLM→继续思考。这个循环可能跑几轮甚至几十轮直到任务完成或达到最大轮次限制。编排层需要处理的核心问题包括任务规划把复杂任务拆成子任务、工具选择从注册的工具中选合适的、结果解析从LLM输出中提取结构化信息、错误恢复工具调用失败后怎么办、轮次控制防止无限循环。我个人的经验是编排层不要写得太“聪明”。很多开发者想让Agent完全自主决策结果行为不可预测调试极其困难。更稳妥的做法是混合编排——关键路径用确定性代码控制只在需要灵活性的环节交给LLM决策。比如“先查知识库查不到再调搜索引擎”这种逻辑用代码写死而“根据用户问题判断该查哪个知识库”交给LLM。2.5 接口层与应用层别忘了这是给用户用的接口层负责对外暴露服务核心要考虑的是鉴权、限流、请求校验、流式输出。流式输出特别重要——LLM生成完整回复可能要好几秒如果等全部生成完再返回用户体验很差。用SSE或WebSocket做流式推送用户能看到文字逐字出现感知延迟大幅降低。应用层则是业务逻辑的归宿。用户会话管理、历史记录存储、计费统计、内容审核、监控告警都在这一层。我特别想强调的是可观测性——AI应用比传统应用更需要日志和追踪。每次LLM调用的输入输出、耗时、Token消耗、工具调用链路都要记录下来否则出了问题根本没法排查。3. 核心组件深度拆解与实操要点3.1 Agent架构ReAct还是Plan-ExecuteAgent架构目前主流的有两种模式。ReAct模式是“思考-行动-观察”循环每一步都让LLM决定下一步做什么。优点是灵活能应对不确定的环境缺点是LLM调用次数多延迟高而且容易陷入循环。Plan-Execute模式是先让LLM制定完整计划然后按计划逐步执行。优点是效率高、可控性强缺点是计划可能不准确执行过程中遇到意外不好调整。我的建议是任务步骤少于5步、环境确定性高的场景用Plan-Execute任务复杂、需要根据中间结果动态调整的场景用ReAct。实际项目中也可以混合——先用Plan-Execute生成大致计划每个步骤内部用ReAct处理细节。Agent的并发问题也值得单独说。当多个用户同时请求Agent服务时每个Agent实例都有自己的状态对话历史、中间结果必须做好隔离。我通常用会话ID作为key每个会话维护独立的状态对象存在Redis或内存缓存中。要注意设置合理的过期时间否则内存会爆。3.2 MCP协议工具调用的标准化尝试MCPModel Context Protocol是最近很热的一个话题它试图解决的是工具调用的标准化问题。在没有MCP之前每个AI应用接入工具的方式都不一样——有的用OpenAI的Function Calling格式有的自己定义JSON Schema有的直接拼字符串。MCP定义了一套标准协议让工具提供方和使用方解耦。MCP的核心概念是Server工具提供方暴露资源Resource和工具ToolClientAI应用通过标准协议发现和调用这些工具。这样你写一个MCP Server所有支持MCP的AI应用都能直接用不需要为每个应用单独适配。实际使用中MCP的配置通常长这样{ mcpServers: { knowledge-base: { command: python, args: [mcp_server_kb.py], env: { KB_API_KEY: your-key } } } }提示MCP目前还在快速演进中不同实现的兼容性参差不齐。生产环境使用前一定要做充分的兼容性测试特别是流式输出和错误处理部分。3.3 上下文窗口管理Token就是钱LLM的上下文窗口是有限资源而且直接关系到成本。GPT-4的128K上下文听起来很大但如果每轮对话都塞满成本会高得离谱。上下文管理的目标是在保留关键信息和控制Token消耗之间找平衡。我的实操策略是这样的系统Prompt控制在500 Token以内只放最核心的角色定义和输出格式要求最近3-5轮对话保留原文更早的对话用LLM做摘要摘要控制在200 Token以内工具调用结果只保留关键字段不要把整个API返回的JSON都塞进去。还有一个技巧是动态上下文。根据当前用户问题从历史对话中检索最相关的几轮而不是简单按时间截取。这需要用到Embedding和向量检索但效果比固定窗口好很多。3.4 安全防护Agent也会被“投毒”Agent安全是一个容易被忽视但非常重要的领域。所谓Agent投毒AgentPoison指的是攻击者通过污染Agent的记忆或知识库让Agent在后续对话中产生恶意行为。比如攻击者在用户输入中植入一段看似正常但实际包含指令的文本Agent把它存到记忆里下次检索出来执行。防护措施包括输入过滤检测并剥离可疑的指令注入、记忆隔离不同用户的记忆严格隔离、工具权限控制敏感工具需要额外鉴权、输出审核对Agent的输出做安全检查。这些措施会增加一些延迟但安全底线不能破。4. 从零搭建一个AI应用的完整实操4.1 环境准备与技术选型假设我们要搭建一个企业知识库问答Agent支持多轮对话、工具调用和流式输出。技术选型如下组件选型理由开发语言Python 3.11AI生态最完善库最多Web框架FastAPI异步支持好自带OpenAPI文档LLMGPT-4o / Claude 3.5综合能力强工具调用稳定向量库Qdrant轻量部署简单性能好缓存Redis会话状态和限流前端React SSE流式渲染体验好安装核心依赖pip install fastapi uvicorn openai anthropic qdrant-client redis sse-starlette4.2 模型适配层实现先定义统一的模型接口然后实现OpenAI和Claude两个适配器。关键点是统一消息格式和统一工具调用格式。OpenAI的tool_calls和Claude的tool_use结构不同需要在适配器里做转换。from abc import ABC, abstractmethod from dataclasses import dataclass dataclass class LLMResponse: content: str tool_calls: list usage: dict class BaseLLM(ABC): abstractmethod async def chat(self, messages, toolsNone, streamFalse): pass class OpenAIAdapter(BaseLLM): def __init__(self, api_key, modelgpt-4o): self.client AsyncOpenAI(api_keyapi_key) self.model model async def chat(self, messages, toolsNone, streamFalse): resp await self.client.chat.completions.create( modelself.model, messagesmessages, toolstools, streamstream ) return self._parse(resp)这个适配层的价值在于上层编排逻辑完全不关心底层用的是哪个模型换模型只需要改配置。4.3 工具注册与调用链路工具注册我用装饰器模式写起来简洁读起来也清楚TOOL_REGISTRY {} def register_tool(name, description, parameters): def decorator(func): TOOL_REGISTRY[name] { function: func, schema: { type: function, function: { name: name, description: description, parameters: parameters } } } return func return decorator register_tool( namesearch_kb, description搜索企业知识库适用于产品功能、操作流程类问题, parameters{ type: object, properties: { query: {type: string, description: 搜索关键词} }, required: [query] } ) async def search_kb(query: str): # 向量检索逻辑 results await vector_store.search(query, top_k3) return \n.join([r.text for r in results])工具调用的完整链路是LLM返回tool_calls→编排层解析出工具名和参数→从注册表找到对应函数→执行→把结果作为tool消息追加到对话→再次调用LLM。这个循环要设置最大轮次我一般设5轮防止无限调用。4.4 流式输出与会话管理流式输出用SSE实现FastAPI这边用StreamingResponse。关键是要把LLM的流式响应和工具调用的中间状态都推给前端让用户知道Agent在干什么。from sse_starlette.sse import EventSourceResponse app.post(/chat) async def chat(request: ChatRequest): async def event_generator(): async for event in agent.run(request.session_id, request.message): yield {event: event.type, data: json.dumps(event.data)} return EventSourceResponse(event_generator())会话管理用Redis存对话历史key是session:{session_id}value是消息列表的JSON。设置30分钟过期每次访问刷新过期时间。要注意消息列表不能无限增长超过20条就触发摘要压缩。4.5 部署与监控部署我推荐用Docker Compose起步服务不多的时候够用。核心服务包括API服务、Redis、Qdrant、监控Prometheus Grafana。API服务至少起2个实例做负载均衡避免单点故障。监控指标重点关注LLM调用延迟P95、Token消耗速率、工具调用成功率、Agent平均轮次、错误率。这些指标能帮你快速定位问题——比如工具调用成功率突然下降可能是某个外部API挂了Agent平均轮次飙升可能是Prompt出了问题导致LLM反复调用工具。5. 常见问题与排查技巧实录5.1 LLM返回格式不符合预期怎么办这是最常见的问题。你要求LLM返回JSON它偏偏给你加一段“好的以下是JSON”的前缀。解决办法有几个层次第一层是Prompt层面在系统指令里明确要求“只输出JSON不要任何其他文字”并给出示例。第二层是解析层面用正则提取JSON部分容忍一定程度的格式偏差。第三层是重试层面解析失败时把错误信息喂回LLM让它重新生成。第四层是约束解码如果用的模型支持JSON Mode或Structured Output直接开启。我一般四层都上实测下来格式错误率能从15%降到1%以下。5.2 Agent陷入循环调用怎么破Agent反复调用同一个工具、或者在两个工具之间来回跳这是ReAct模式的经典问题。排查思路先看LLM的思考过程如果记录了的话判断是工具描述有歧义还是任务本身无法完成。如果是描述问题优化工具描述如果是任务问题设置最大轮次强制退出并返回一个兜底回复。还有一个技巧是在Prompt里加入“如果你已经调用过某个工具且结果不理想不要重复调用尝试其他方法或直接告知用户”。这句话能显著减少无效循环。5.3 并发上来之后响应变慢LLM API本身有速率限制并发高了之后请求会排队。解决办法请求队列优先级。用Redis做队列重要请求优先处理批量合并短时间内相同或相似的请求合并成一次LLM调用缓存对常见问题缓存LLM回复命中缓存直接返回。缓存要注意设置合理的TTL和失效策略。知识库更新后相关缓存要主动清除否则用户会拿到过时的答案。5.4 常见问题速查表问题现象可能原因排查方向解决方案LLM调用超时网络问题/模型服务抖动检查网络和模型服务状态增加超时重试配置备用模型工具调用参数错误工具描述不清/参数Schema有误检查工具定义和LLM输出优化描述增加参数示例上下文超限对话轮次过多/工具结果太大统计Token消耗摘要压缩截断工具结果回复内容不安全输入注入/模型幻觉检查输入和输出加输入过滤和输出审核流式输出中断网络不稳定/服务重启检查SSE连接状态前端加重连后端加心跳5.5 几个我踩过的坑第一个坑是过度依赖LLM做决策。早期我让LLM自己决定要不要调用工具、调用哪个工具结果行为很不稳定。后来改成混合模式——简单规则用代码判断复杂情况才交给LLM稳定性大幅提升。第二个坑是忽略Token成本。上线第一个月账单出来吓了一跳排查发现是工具返回结果太长每次都把整个JSON塞进上下文。后来改成只提取关键字段成本降了60%。第三个坑是没有做会话隔离。测试阶段两个用户同时对话发现A用户能看到B用户的历史记录。原因是会话状态存在了全局变量里。改成Redis按session_id隔离后解决。这个坑很危险涉及数据安全一定要在架构设计阶段就考虑清楚。第四个坑是Prompt硬编码。一开始Prompt写在代码里每次调整都要重新部署。后来迁移到配置中心产品经理自己就能改迭代速度快了很多。6. 架构演进从单体到分布式的思考6.1 什么时候该拆服务一开始不要拆。单体应用开发快、部署简单、调试方便。当出现以下信号时再考虑拆分不同模块的伸缩需求差异大比如模型调用需要GPU而业务逻辑不需要、团队规模变大需要独立发布、某个模块成为性能瓶颈。拆分的第一刀通常切在模型服务上。把LLM调用独立成一个服务统一管理API Key、限流、缓存、监控。这样多个AI应用可以共享模型服务也方便做统一的成本核算。6.2 多Agent协作的架构模式当单个Agent搞不定复杂任务时就需要多Agent协作。常见的模式有主管模式一个Orchestrator Agent分配任务给Worker Agent、流水线模式Agent按顺序处理前一个的输出是后一个的输入、辩论模式多个Agent给出方案互相评审后选最优。多Agent架构的复杂度比单Agent高一个数量级通信协议、状态同步、错误传播都是难点。我的建议是除非单Agent确实无法完成否则不要上多Agent。很多场景下把单Agent的Prompt和工具优化好效果比多Agent更好。6.3 架构设计的取舍原则最后分享几条我在架构设计中的取舍原则。简单优于灵活——能用一个Agent解决的不要用两个能用代码写死的不要交给LLM决策。可观测优于性能——宁可多花一点性能在日志和追踪上也不要出了问题两眼一抹黑。隔离优于复用——不同用户的会话、不同任务的上下文严格隔离不要为了省内存而共享状态。渐进优于一步到位——先跑通最小闭环再逐步加功能不要一开始就设计一个“完美”的架构。这些原则听起来简单但在实际项目中坚持下来不容易。我见过太多项目因为一开始追求“大而全”的架构结果三个月都没上线。反而是那些从简单开始、快速迭代的项目最终跑得更远。架构设计这件事纸上谈兵容易落地踩坑才是常态。我自己的体会是每次做完一个AI应用回头看架构图都会发现可以优化的地方。这不是坏事说明你在进步。重要的是保持架构的可演进性——今天的设计不一定要完美但一定要让明天的修改成本足够低。 
长河君 · 2026/10/6 21:48:42 · 阅读 1.2k 图解AI应用架构设计：从模型层到应用层的五层架构与Agent实操
1. 从一张架构图说起AI应用到底该怎么搭这两年我参与过不少AI应用项目的评审和落地发现一个特别普遍的现象很多人一上来就急着写Prompt、调API、接模型结果做到一半发现整个系统像一团乱麻——模型换了要改几十处代码加个新工具要动核心逻辑想做个多轮对话状态管理得从头造轮子。说到底问题出在动手之前没有把架构想清楚。“图解AI应用架构设计”这个主题核心就是解决一件事用可视化的方式把AI应用从底层模型到上层交互的完整链路拆解清楚让开发者知道每一层该放什么、层与层之间怎么通信、哪些东西该抽象、哪些东西该固化。它适合正在做AI应用开发的工程师、正在设计Agent系统的架构师也适合刚入门想搞清楚“一个AI应用到底由哪些部分组成”的学习者。我个人的判断是2024年之后AI应用开发已经从“能不能跑通”进入“能不能扛住”的阶段。早期大家写个脚本调一下LLM接口就算AI应用了现在要考虑多模型切换、工具调用编排、上下文管理、并发控制、安全防护、可观测性等等。这些需求叠加在一起如果没有一个清晰的架构设计代码会迅速腐化。所以这篇文章我会从架构分层、核心组件、实操搭建、问题排查几个维度把AI应用架构设计这件事讲透尽量做到你看完能直接对照着画自己的架构图。2. AI应用架构的整体分层与设计思路2.1 为什么不能把AI应用写成一个“大函数”我见过最简陋的AI应用是这样的一个Python文件里面一个函数接收用户输入拼接Prompt调用OpenAI接口返回结果。这种写法在Demo阶段没问题但一旦要加功能——比如支持多轮对话、支持工具调用、支持切换模型——这个函数会迅速膨胀到几百行改一处崩三处。架构设计的本质是分离关注点。AI应用和传统Web应用最大的区别在于传统应用的核心逻辑是确定的if-else、循环、数据库查询而AI应用的核心逻辑包含了一个不确定的组件——LLM。LLM的输出不可预测、有延迟、有成本、可能失败。所以架构设计的第一原则就是把LLM当作一个不可靠的外部依赖来对待围绕它做隔离、降级、重试和监控。基于这个原则我把AI应用的架构分为五层从下往上依次是模型层LLM、Embedding模型、Rerank模型等负责推理和生成能力层Prompt管理、上下文管理、工具/函数注册、记忆系统编排层Agent逻辑、工作流引擎、任务规划、多步推理控制接口层API网关、鉴权、限流、请求路由应用层对话界面、业务逻辑、数据持久化、监控告警每一层只和相邻层通信层内可以替换实现而不影响其他层。比如你把GPT-4换成Claude只需要改模型层的适配器编排层和接口层完全不用动。这就是分层架构的价值。2.2 模型层别把鸡蛋放在一个篮子里模型层看起来简单——不就是调API吗但实际项目中模型层要处理的问题非常多。首先是多模型适配。不同厂商的API格式不一样参数命名不一样返回结构不一样。如果你在业务代码里直接写openai.ChatCompletion.create(...)那换模型的时候就得全局搜索替换。正确的做法是定义一个统一的模型接口抽象比如class BaseLLM: def chat(self, messages: list, tools: list None, **kwargs) - LLMResponse: raise NotImplementedError class OpenAILLM(BaseLLM): def chat(self, messages, toolsNone, **kwargs): # 适配OpenAI格式 ... class ClaudeLLM(BaseLLM): def chat(self, messages, toolsNone, **kwargs): # 适配Claude格式 ...这样上层只需要依赖BaseLLM具体用哪个模型通过配置决定。我实测下来这个抽象层大概多写200行代码但后续换模型、加模型、做A/B测试的时候能省掉大量重构时间。其次是模型路由。不同任务对模型的要求不一样。简单的意图分类用便宜的小模型就够了复杂的推理任务才需要上大模型。你可以在模型层做一个路由策略根据任务类型、输入长度、历史成功率动态选择模型。这不只是为了省钱也是为了控制延迟——小模型的响应速度通常快很多。注意模型路由策略一定要有fallback。我踩过的坑是某次主力模型服务抖动因为没有配置备用模型整个应用直接不可用。后来加了自动降级逻辑主模型连续失败3次就切到备用模型同时发告警。2.3 能力层Prompt、上下文和工具注册能力层是AI应用架构中最“AI”的部分也是最容易写乱的部分。Prompt管理不是简单地把字符串存在代码里。一个成熟的Prompt管理系统应该支持模板变量替换、多版本管理、A/B测试、按场景切换。我通常会把Prompt存在数据库或配置文件中每个Prompt有唯一ID和版本号代码里通过ID引用。这样产品经理改Prompt不需要发版运营可以做实验对比不同Prompt的效果。上下文管理是另一个重灾区。LLM有上下文窗口限制对话轮次多了之后必须做截断或摘要。常见的策略有几种滑动窗口保留最近N轮、摘要压缩把早期对话用LLM总结成一段话、关键信息提取只保留实体和意图。我一般会组合使用——最近5轮保留原文更早的做摘要系统指令永远保留。工具注册是Agent能力的基础。每个工具需要定义名称、描述、参数Schema、执行函数。描述非常重要LLM就是靠描述来判断什么时候该调用哪个工具。我见过很多工具调用失败的情况排查下来都是描述写得太模糊LLM根本分不清什么时候该用。tools [ { name: search_knowledge_base, description: 在内部知识库中搜索相关文档。当用户询问产品功能、操作步骤、常见问题时使用此工具。, parameters: { type: object, properties: { query: {type: string, description: 搜索关键词} }, required: [query] } } ]2.4 编排层Agent的大脑编排层决定了AI应用是“单轮问答”还是“能自主完成复杂任务”。简单场景下编排层就是一个线性流程接收输入→组装Prompt→调用LLM→解析输出→返回结果。但Agent场景下编排层要复杂得多。一个典型的Agent循环是这样的LLM思考当前状态→决定下一步行动调用工具/直接回答→执行行动→把结果喂回LLM→继续思考。这个循环可能跑几轮甚至几十轮直到任务完成或达到最大轮次限制。编排层需要处理的核心问题包括任务规划把复杂任务拆成子任务、工具选择从注册的工具中选合适的、结果解析从LLM输出中提取结构化信息、错误恢复工具调用失败后怎么办、轮次控制防止无限循环。我个人的经验是编排层不要写得太“聪明”。很多开发者想让Agent完全自主决策结果行为不可预测调试极其困难。更稳妥的做法是混合编排——关键路径用确定性代码控制只在需要灵活性的环节交给LLM决策。比如“先查知识库查不到再调搜索引擎”这种逻辑用代码写死而“根据用户问题判断该查哪个知识库”交给LLM。2.5 接口层与应用层别忘了这是给用户用的接口层负责对外暴露服务核心要考虑的是鉴权、限流、请求校验、流式输出。流式输出特别重要——LLM生成完整回复可能要好几秒如果等全部生成完再返回用户体验很差。用SSE或WebSocket做流式推送用户能看到文字逐字出现感知延迟大幅降低。应用层则是业务逻辑的归宿。用户会话管理、历史记录存储、计费统计、内容审核、监控告警都在这一层。我特别想强调的是可观测性——AI应用比传统应用更需要日志和追踪。每次LLM调用的输入输出、耗时、Token消耗、工具调用链路都要记录下来否则出了问题根本没法排查。3. 核心组件深度拆解与实操要点3.1 Agent架构ReAct还是Plan-ExecuteAgent架构目前主流的有两种模式。ReAct模式是“思考-行动-观察”循环每一步都让LLM决定下一步做什么。优点是灵活能应对不确定的环境缺点是LLM调用次数多延迟高而且容易陷入循环。Plan-Execute模式是先让LLM制定完整计划然后按计划逐步执行。优点是效率高、可控性强缺点是计划可能不准确执行过程中遇到意外不好调整。我的建议是任务步骤少于5步、环境确定性高的场景用Plan-Execute任务复杂、需要根据中间结果动态调整的场景用ReAct。实际项目中也可以混合——先用Plan-Execute生成大致计划每个步骤内部用ReAct处理细节。Agent的并发问题也值得单独说。当多个用户同时请求Agent服务时每个Agent实例都有自己的状态对话历史、中间结果必须做好隔离。我通常用会话ID作为key每个会话维护独立的状态对象存在Redis或内存缓存中。要注意设置合理的过期时间否则内存会爆。3.2 MCP协议工具调用的标准化尝试MCPModel Context Protocol是最近很热的一个话题它试图解决的是工具调用的标准化问题。在没有MCP之前每个AI应用接入工具的方式都不一样——有的用OpenAI的Function Calling格式有的自己定义JSON Schema有的直接拼字符串。MCP定义了一套标准协议让工具提供方和使用方解耦。MCP的核心概念是Server工具提供方暴露资源Resource和工具ToolClientAI应用通过标准协议发现和调用这些工具。这样你写一个MCP Server所有支持MCP的AI应用都能直接用不需要为每个应用单独适配。实际使用中MCP的配置通常长这样{ mcpServers: { knowledge-base: { command: python, args: [mcp_server_kb.py], env: { KB_API_KEY: your-key } } } }提示MCP目前还在快速演进中不同实现的兼容性参差不齐。生产环境使用前一定要做充分的兼容性测试特别是流式输出和错误处理部分。3.3 上下文窗口管理Token就是钱LLM的上下文窗口是有限资源而且直接关系到成本。GPT-4的128K上下文听起来很大但如果每轮对话都塞满成本会高得离谱。上下文管理的目标是在保留关键信息和控制Token消耗之间找平衡。我的实操策略是这样的系统Prompt控制在500 Token以内只放最核心的角色定义和输出格式要求最近3-5轮对话保留原文更早的对话用LLM做摘要摘要控制在200 Token以内工具调用结果只保留关键字段不要把整个API返回的JSON都塞进去。还有一个技巧是动态上下文。根据当前用户问题从历史对话中检索最相关的几轮而不是简单按时间截取。这需要用到Embedding和向量检索但效果比固定窗口好很多。3.4 安全防护Agent也会被“投毒”Agent安全是一个容易被忽视但非常重要的领域。所谓Agent投毒AgentPoison指的是攻击者通过污染Agent的记忆或知识库让Agent在后续对话中产生恶意行为。比如攻击者在用户输入中植入一段看似正常但实际包含指令的文本Agent把它存到记忆里下次检索出来执行。防护措施包括输入过滤检测并剥离可疑的指令注入、记忆隔离不同用户的记忆严格隔离、工具权限控制敏感工具需要额外鉴权、输出审核对Agent的输出做安全检查。这些措施会增加一些延迟但安全底线不能破。4. 从零搭建一个AI应用的完整实操4.1 环境准备与技术选型假设我们要搭建一个企业知识库问答Agent支持多轮对话、工具调用和流式输出。技术选型如下组件选型理由开发语言Python 3.11AI生态最完善库最多Web框架FastAPI异步支持好自带OpenAPI文档LLMGPT-4o / Claude 3.5综合能力强工具调用稳定向量库Qdrant轻量部署简单性能好缓存Redis会话状态和限流前端React SSE流式渲染体验好安装核心依赖pip install fastapi uvicorn openai anthropic qdrant-client redis sse-starlette4.2 模型适配层实现先定义统一的模型接口然后实现OpenAI和Claude两个适配器。关键点是统一消息格式和统一工具调用格式。OpenAI的tool_calls和Claude的tool_use结构不同需要在适配器里做转换。from abc import ABC, abstractmethod from dataclasses import dataclass dataclass class LLMResponse: content: str tool_calls: list usage: dict class BaseLLM(ABC): abstractmethod async def chat(self, messages, toolsNone, streamFalse): pass class OpenAIAdapter(BaseLLM): def __init__(self, api_key, modelgpt-4o): self.client AsyncOpenAI(api_keyapi_key) self.model model async def chat(self, messages, toolsNone, streamFalse): resp await self.client.chat.completions.create( modelself.model, messagesmessages, toolstools, streamstream ) return self._parse(resp)这个适配层的价值在于上层编排逻辑完全不关心底层用的是哪个模型换模型只需要改配置。4.3 工具注册与调用链路工具注册我用装饰器模式写起来简洁读起来也清楚TOOL_REGISTRY {} def register_tool(name, description, parameters): def decorator(func): TOOL_REGISTRY[name] { function: func, schema: { type: function, function: { name: name, description: description, parameters: parameters } } } return func return decorator register_tool( namesearch_kb, description搜索企业知识库适用于产品功能、操作流程类问题, parameters{ type: object, properties: { query: {type: string, description: 搜索关键词} }, required: [query] } ) async def search_kb(query: str): # 向量检索逻辑 results await vector_store.search(query, top_k3) return \n.join([r.text for r in results])工具调用的完整链路是LLM返回tool_calls→编排层解析出工具名和参数→从注册表找到对应函数→执行→把结果作为tool消息追加到对话→再次调用LLM。这个循环要设置最大轮次我一般设5轮防止无限调用。4.4 流式输出与会话管理流式输出用SSE实现FastAPI这边用StreamingResponse。关键是要把LLM的流式响应和工具调用的中间状态都推给前端让用户知道Agent在干什么。from sse_starlette.sse import EventSourceResponse app.post(/chat) async def chat(request: ChatRequest): async def event_generator(): async for event in agent.run(request.session_id, request.message): yield {event: event.type, data: json.dumps(event.data)} return EventSourceResponse(event_generator())会话管理用Redis存对话历史key是session:{session_id}value是消息列表的JSON。设置30分钟过期每次访问刷新过期时间。要注意消息列表不能无限增长超过20条就触发摘要压缩。4.5 部署与监控部署我推荐用Docker Compose起步服务不多的时候够用。核心服务包括API服务、Redis、Qdrant、监控Prometheus Grafana。API服务至少起2个实例做负载均衡避免单点故障。监控指标重点关注LLM调用延迟P95、Token消耗速率、工具调用成功率、Agent平均轮次、错误率。这些指标能帮你快速定位问题——比如工具调用成功率突然下降可能是某个外部API挂了Agent平均轮次飙升可能是Prompt出了问题导致LLM反复调用工具。5. 常见问题与排查技巧实录5.1 LLM返回格式不符合预期怎么办这是最常见的问题。你要求LLM返回JSON它偏偏给你加一段“好的以下是JSON”的前缀。解决办法有几个层次第一层是Prompt层面在系统指令里明确要求“只输出JSON不要任何其他文字”并给出示例。第二层是解析层面用正则提取JSON部分容忍一定程度的格式偏差。第三层是重试层面解析失败时把错误信息喂回LLM让它重新生成。第四层是约束解码如果用的模型支持JSON Mode或Structured Output直接开启。我一般四层都上实测下来格式错误率能从15%降到1%以下。5.2 Agent陷入循环调用怎么破Agent反复调用同一个工具、或者在两个工具之间来回跳这是ReAct模式的经典问题。排查思路先看LLM的思考过程如果记录了的话判断是工具描述有歧义还是任务本身无法完成。如果是描述问题优化工具描述如果是任务问题设置最大轮次强制退出并返回一个兜底回复。还有一个技巧是在Prompt里加入“如果你已经调用过某个工具且结果不理想不要重复调用尝试其他方法或直接告知用户”。这句话能显著减少无效循环。5.3 并发上来之后响应变慢LLM API本身有速率限制并发高了之后请求会排队。解决办法请求队列优先级。用Redis做队列重要请求优先处理批量合并短时间内相同或相似的请求合并成一次LLM调用缓存对常见问题缓存LLM回复命中缓存直接返回。缓存要注意设置合理的TTL和失效策略。知识库更新后相关缓存要主动清除否则用户会拿到过时的答案。5.4 常见问题速查表问题现象可能原因排查方向解决方案LLM调用超时网络问题/模型服务抖动检查网络和模型服务状态增加超时重试配置备用模型工具调用参数错误工具描述不清/参数Schema有误检查工具定义和LLM输出优化描述增加参数示例上下文超限对话轮次过多/工具结果太大统计Token消耗摘要压缩截断工具结果回复内容不安全输入注入/模型幻觉检查输入和输出加输入过滤和输出审核流式输出中断网络不稳定/服务重启检查SSE连接状态前端加重连后端加心跳5.5 几个我踩过的坑第一个坑是过度依赖LLM做决策。早期我让LLM自己决定要不要调用工具、调用哪个工具结果行为很不稳定。后来改成混合模式——简单规则用代码判断复杂情况才交给LLM稳定性大幅提升。第二个坑是忽略Token成本。上线第一个月账单出来吓了一跳排查发现是工具返回结果太长每次都把整个JSON塞进上下文。后来改成只提取关键字段成本降了60%。第三个坑是没有做会话隔离。测试阶段两个用户同时对话发现A用户能看到B用户的历史记录。原因是会话状态存在了全局变量里。改成Redis按session_id隔离后解决。这个坑很危险涉及数据安全一定要在架构设计阶段就考虑清楚。第四个坑是Prompt硬编码。一开始Prompt写在代码里每次调整都要重新部署。后来迁移到配置中心产品经理自己就能改迭代速度快了很多。6. 架构演进从单体到分布式的思考6.1 什么时候该拆服务一开始不要拆。单体应用开发快、部署简单、调试方便。当出现以下信号时再考虑拆分不同模块的伸缩需求差异大比如模型调用需要GPU而业务逻辑不需要、团队规模变大需要独立发布、某个模块成为性能瓶颈。拆分的第一刀通常切在模型服务上。把LLM调用独立成一个服务统一管理API Key、限流、缓存、监控。这样多个AI应用可以共享模型服务也方便做统一的成本核算。6.2 多Agent协作的架构模式当单个Agent搞不定复杂任务时就需要多Agent协作。常见的模式有主管模式一个Orchestrator Agent分配任务给Worker Agent、流水线模式Agent按顺序处理前一个的输出是后一个的输入、辩论模式多个Agent给出方案互相评审后选最优。多Agent架构的复杂度比单Agent高一个数量级通信协议、状态同步、错误传播都是难点。我的建议是除非单Agent确实无法完成否则不要上多Agent。很多场景下把单Agent的Prompt和工具优化好效果比多Agent更好。6.3 架构设计的取舍原则最后分享几条我在架构设计中的取舍原则。简单优于灵活——能用一个Agent解决的不要用两个能用代码写死的不要交给LLM决策。可观测优于性能——宁可多花一点性能在日志和追踪上也不要出了问题两眼一抹黑。隔离优于复用——不同用户的会话、不同任务的上下文严格隔离不要为了省内存而共享状态。渐进优于一步到位——先跑通最小闭环再逐步加功能不要一开始就设计一个“完美”的架构。这些原则听起来简单但在实际项目中坚持下来不容易。我见过太多项目因为一开始追求“大而全”的架构结果三个月都没上线。反而是那些从简单开始、快速迭代的项目最终跑得更远。架构设计这件事纸上谈兵容易落地踩坑才是常态。我自己的体会是每次做完一个AI应用回头看架构图都会发现可以优化的地方。这不是坏事说明你在进步。重要的是保持架构的可演进性——今天的设计不一定要完美但一定要让明天的修改成本足够低。