不管是做 AI 客服、知识库问答还是带工具调用的复杂 Agent我们几乎默认遵循一条逻辑模型选得好Agent 效果就好模型换成参数更大的新版本智能体就一定更聪明。但从我实际做过的几个项目来看情况通常没那么简单——换了更强的大模型之后智能体助手并没有变“聪明”甚至在一些场景下变得更不稳定。真正改变智能体行为的往往是那套很少被写进对比评测文章里的部署框架。本文会围绕“为什么智能体行为更多由部署框架而非模型决定”这一主题做一个系统拆解。先搞清楚模型、智能体、部署框架各自的职责边界再从推理参数、上下文管理、工具调用、资源部署四个方面分析行为差异的来源然后给出一套完整的自建智能体部署实验代码覆盖可复制的 Python 实现、部署配置和结果验证最后补充常见报错排查和工程化建议。无论你是在做 Dify 平台上的 RAG 助手还是基于 vllm 自建推理服务这篇文章都能帮你少踩一半的坑。1. 背景与核心概念1.1 为什么会出现“框架比模型更重要”的现象在智能体项目中我们通常把效果稳定或变差的缘由归结为模型。比如“GPT-4 生成的回答比 Qwen 好”“换成了更长的上下文窗口记忆能力更强了”。但把项目投入生产环境后会逐渐发现另一个隐藏变量部署框架。所谓部署框架不只是“把模型跑起来”的 vllm、TGI还包括承载智能体逻辑的应用层框架比如 Dify、LangChain 的自建版本甚至是你自己写的 FastAPI 服务。它决定了模型以什么格式接收提示词、拿到哪些工具函数、上下文被截断到多长、在超时或并发时怎么降级。这些细节堆叠在一起直接影响最终输出。一个很常见的现象是底层模型没变只修改了部署参数里的temperature或者调整了工具函数的返回阈值智能体行为就能完全变形。反过来说即使把模型换成更强的版本只要部署框架里的提示词模板、工具注册表、知识库召回策略没有同步升级输出质量可能不升反降。这也就是“行为更多由部署框架而非模型决定”这句话成立的根本原因。1.2 模型、智能体、部署框架的职责边界为了不让概念混淆先把三个层级区分清楚。模型层包含模型权重、预训练知识、基础对话能力。它决定“这个模型有多聪明”但模型本身并不知道自己要被用来做什么。智能体层包含系统提示词、任务规划逻辑、工具调用协议、上下文记忆策略。它决定“智能体为什么要这么做”。部署框架层包含推理服务、向量检索服务、Web 服务、消息路由、限流与超时策略。它决定“系统在真实环境中能否稳定复现这个行为”。从技术分工来看模型只负责给定输入后的概率分布输出真正限制和格式化输入、决定调用哪些工具、以什么顺序返回结果的是框架和智能体逻辑。因此在评估智能体项目时不能只做模型对比也要做框架对比。1.3 本文的核心观点本文不是宣称模型不重要而是想说明一个工程观察当框架没有匹配到位时模型的能力优势会被抵消而框架做得好时即使模型规级低一档智能体在具体业务上也能表现得稳定可用。下面我从 4 个影响路径入手把“框架决定行为”这件事讲透。2. 部署框架影响智能体行为的 4 个路径2.1 推理参数决定输出的稳定性和风格先看一个最常见的例子模型没变但在部署推理服务时有人在启动参数里加了temperature0.7有人用默认的0.1。两个用户问同一个问题得到的回答可能截然不同。推理服务在部署层面的几个参数会直接影响智能体的行为特征推理参数影响行为temperature决定回答的随机性值越高越发散值越低越稳定top_p配合 temperature 使用控制候选词采样范围max_tokens限制输出长度设置过小会导致回答被截断看起来像“模型不会了”repetition_penalty影响是否出现重复表达上下文长度影响模型能看到的窗口范围过长会降低响应速度过短会丢失记忆很多智能体项目在上线后出现“一阵好一阵坏”的现象并不是模型能力波动而是部署侧没有固化推理参数。部署框架中这些参数被不同请求动态覆盖时行为就会变得不可控。2.2 上下文管理与知识召回机制第二个路径是上下文。模型只负责“看当前给它的内容”但“当前给什么”由部署框架决定。以知识库问答为例如果部署框架中的向量检索模块只召回 Top-3 片段那么即使底层模型是无敌的它也只能基于这 3 段内容作答。反过来说如果召回模块能把用户原问题改写、重排后召回更准确的片段即便模型本领一般回答质量也能明显提升。在 RAG 智能体里部署框架通常承担这些工作用户文档的上传与解析文本分块chunk策略embedding 向量化向量库检索reranker 重排序检索结果拼入提示词模板。以上任何一环配置不一致都会改变模型看到的信息从而改变输出。框架在这里发挥了“信息守门员”的作用。注意 embedding 模型和 reranker 模型通常不能直接用 vllm 这种面向生成模型优化的推理服务启动尤其在昇腾 910B-A2 这类 NPU 服务器上强行用 vllm 启动 embedding 模型会报错正确的做法是单独封装为向量检索服务。2.3 工具调用机制决定智能体的行为边界智能体区别于普通聊天机器人的关键在于工具调用。模型本身往往不知道“当前环境有哪些工具”是部署框架在系统提示词和工具列表中告诉它的。部署框架中的工具注册表决定了智能体“能做”什么框架注册了联网搜索工具智能体才会在信息不足时调用搜索框架入库了订单查询接口智能体才能回答订单状态框架没注册文件读取工具智能体即使猜到了文件路径也无法读取内容。而在更细的层面工具函数返回的数据结构、错误提示语、超时时长也会改变智能体的下一步规划。例如工具返回“查询超时”有的框架会把错误原文带给模型导致模型误以为数据库中无数据有的框架会把错误翻译成“系统暂时不可用”模型就会给出更稳妥的回答。这些差异本质上是部署框架决定的。2.4 服务架构与并发模型影响用户体验第三个容易被忽略的路径是服务架构。同一个智能体项目如果用while True串行处理请求再强的模型也会因为排队时间过长而被用户判定为“不聪明”如果采用异步任务队列响应速度和并发能力提升后用户感知的智能感也会明显增强。在多卡或多机部署大模型时推理框架里的并行参数配置会让模型行为产生两个层面的差异吞吐量差异并行度越高单位时间处理的请求越多批次效应差异动态批处理时不同请求被合并到同一个 batchGPU 计算过程中的数值波动会使输出产生细微变化。在对外提供服务时需要把推理参数、上下文构建、工具协议全部固化进框架配置不能交给每个调用方随意指定。3. 自建智能体部署实验同一个模型两套框架两种行为为了把“部署框架影响行为”从概念变成可验证的结果下面我做了一个最小化实验。核心思路是保持模型不变分别用两套不同的提示词模板和工具结果拼装逻辑去调用同一个模型接口观察智能体行为差异。3.1 实验架构实验采用本地自建方式大模型推理服务远程推理服务兼容 OpenAI 协议应用框架Python FastAPI智能体核心手工实现一个AgentRunner负责规划、调用工具、拼接上下文两套框架模板一套把工具结果简单拼接在末尾另一套在拼接前做了结构化重排。架构示意如下用户请求 - FastAPI Web 服务 - AgentRunner |- 调用远程大模型推理服务 |- 调用工具函数模拟查库 |- 重新拼接上下文 - 再次调用模型 消费者拿到最终回答3.2 项目结构实验代码目录如下agent-framework-demo/ ├── app.py # FastAPI 入口 ├── agent_runner.py # 智能体核心流程 ├── tools.py # 工具函数定义 ├── prompt_builder.py # 两套提示词模板 ├── config.py # 推理参数配置 └── requirements.txt # 依赖3.3 环境准备在本地运行前需要准备Python 3.10 或更高版本一个可用的推理服务地址支持 OpenAI Chat Completions 格式安装依赖fastapi、uvicorn、openai、pydantic。版本方面需要根据你的项目实际情况调整上面的示例重点演示框架对行为的影响不一定要求最新版本。requirements.txt示例fastapi0.110.0 uvicorn0.29.0 openai1.30.0 pydantic2.6.03.4 核心代码一配置管理先把推理参数统一放到配置里避免埋没在代码各处。# config.py class LLMConfig: API_BASE http://your-inference-service/v1 API_KEY your-key MODEL_NAME qwen-72b TEMPERATURE 0.1 TOP_P 0.9 MAX_TOKENS 2048 REQUEST_TIMEOUT 30这里把 temperature 固定为 0.1是为了让模型尽量稳定输出排除随机性造成的噪声干扰。实际项目中可以把参数放到环境变量配置中心方便运行时调整。3.5 核心代码二工具函数tools.py中实现一个模拟订单查询工具。工具返回值结构是固定字典但不同框架在拼接时对返回内容的处理方式不同。# tools.py def query_order_status(order_id: str) - dict: # 模拟真实查询逻辑实际项目里可替换为 HTTP 请求或数据库查询 if order_id A1001: return { code: 200, order_id: order_id, status: 已发货, tracking_number: SF1234567890, remark: 预计今天下午送达 } return { code: 200, order_id: order_id, status: 未知, tracking_number: , remark: 该订单不存在或已被删除 }注意这里的返回值结构对最终模型输出很重要。如果框架在拼入上下文时只保留了status模型就看不到备注信息如果把整个字典原样传给模型模型会读到更多细节。这属于部署框架层对工具结果处理策略的差异。3.6 核心代码三两套提示词模板下面定义两套提示词模板。为便于对比其他条件完全一致只有工具结果的呈现方式不同。# prompt_builder.py BASE_SYSTEM_PROMPT 你是一名订单客服助手请根据用户问题给出回答。 def build_agent_input_v1(user_query: str, tool_result: dict) - list[dict]: 模板一把工具结果简单拼接在末尾。 这种写法在早期 Agent 项目里很常见模型很容易遗漏细节。 return [ {role: system, content: BASE_SYSTEM_PROMPT}, {role: user, content: user_query}, {role: assistant, content: 我需要调用工具查询订单状态。}, {role: tool, content: str(tool_result)} ] def build_agent_input_v2(user_query: str, tool_result: dict) - list[dict]: 模板二将工具结果结构化为清晰字段并重新组织上下文。 这是更接近生产可用的框架层设计。 content ( f订单查询结果如下\n f订单号{tool_result[order_id]}\n f订单状态{tool_result[status]}\n f物流单号{tool_result[tracking_number]}\n f备注{tool_result[remark]}\n 请基于以上结果回答不要编造不存在的信息。 ) return [ {role: system, content: BASE_SYSTEM_PROMPT}, {role: user, content: user_query}, {role: assistant, content: 我先查询订单状态再回答。}, {role: tool, content: content} ]模板一和模板二在同一个模型下运行观感上的表现差异非常明显。模板一中模型经常忽略remark字段甚至把tracking_number读成订单号模板二中因为字段被明确标注模型几乎不会读错。这正是“部署框架而非模型”的一个具象表现——模型的对话能力没有变但框架对工具结果的解析方式变了模型的可用性就被放大了。3.7 核心代码四AgentRunneragent_runner.py负责把用户问题、工具函数、提示词模板、模型调用串起来。# agent_runner.py from openai import OpenAI from config import LLMConfig from tools import query_order_status from prompt_builder import build_agent_input_v1, build_agent_input_v2 class AgentRunner: def __init__(self, version: str v1): self.client OpenAI(base_urlLLMConfig.API_BASE, api_keyLLMConfig.API_KEY) self.version version def run(self, user_query: str, order_id: str) - str: # 1. 调用工具 tool_result query_order_status(order_id) # 2. 根据框架版本选择不同的上下文拼装策略 if self.version v1: messages build_agent_input_v1(user_query, tool_result) else: messages build_agent_input_v2(user_query, tool_result) # 3. 调用模型 response self.client.chat.completions.create( modelLLMConfig.MODEL_NAME, messagesmessages, temperatureLLMConfig.TEMPERATURE, top_pLLMConfig.TOP_P, max_tokensLLMConfig.MAX_TOKENS, timeoutLLMConfig.REQUEST_TIMEOUT ) return response.choices[0].message.content这里的version参数就是“框架差异”的简化版。实际项目里两套框架往往不是选一个字符串而是不同的模块实现、不同的工具调用协议和不同的上下文持久化方式。3.8 核心代码五FastAPI 入口app.py中暴露一个 HTTP 接口用于测试两套框架的行为差异。# app.py from fastapi import FastAPI, Query from agent_runner import AgentRunner app FastAPI() runner_v1 AgentRunner(versionv1) runner_v2 AgentRunner(versionv2) app.get(/agent) def agent_endpoint(query: str Query(..., description用户问题), order_id: str Query(A1001, description订单号), version: str Query(v1, description框架版本号)) - dict: if version v2: reply runner_v2.run(query, order_id) else: reply runner_v1.run(query, order_id) return {version: version, reply: reply}3.9 运行与验证启动服务uvicorn app:app --host 0.0.0.0 --port 8000访问地址# 使用框架 v1 curl http://localhost:8000/agent?query我的订单到哪了order_idA1001versionv1 # 使用框架 v2 curl http://localhost:8000/agent?query我的订单到哪了order_idA1001versionv2预期现象v1 模板拿到的是str(tool_result)的原始字典字符串模型可能提取出正确状态但回答比较死板偶尔会出现字段名暴露的情况v2 模板拿到的是结构化文本模型基本能流畅地给出“已发货快递单号为 SF1234567890预计今天下午送达”的回答。在同一个模型下v2 的表现明显更接近生产可用的智能体v1 则像是一个没有做完的 Demo。二者差距完全来自部署框架而不是模型。4. 借力 Dify 等平台框架一个文件上传问答实例除了自建框架很多项目也会选择 Dify 这类开源智能体平台。平台本身同样是“部署框架”的一部分它决定了用户与模型之间的交互方式。下面以“识别上传文件内容并回答”为例说明平台框架如何改变智能体行为。4.1 平台框架的核心链路在 Dify 中是通作业流完成的完整链路如下用户上传文件 - 文档解析 - 文本分块 - 向量化(embedding) - 向量检索引擎匹配 - 将检索结果拼入上下文 - 调用大模型生成 - 返回用户回答如果只是调用模型本身Dify 里的知识库问答和普通聊天没有区别。但部署平台为我们提供了知识库阶段智能体回答就有了“依据来源”。这是模型单靠自己做不到的因为模型并不认识用户上传的新文档。4.2 平台框架里最容易影响行为的三处配置第一处是分块大小。分块太小模型可能看不到完整业务逻辑分块太大向量检索精度下降。需要根据文档类型做实验。第二处是 embedding 和 reranker 模型部署。embedding 模型负责把文本转成向量reranker 负责精排。这两类模型在昇腾 910B-A2 等 NPU 环境下不一定能通过 vllm 启动因为 vllm 主要面向生成类模型做推理优化。建议单独封装向量服务并在平台框架里配置独立的服务地址。第三处是检索 TopK 与相似度阈值。TopK 太大无关上下文进入提示词模型容易被干扰TopK 太小关键信息可能被漏掉。4.3 平台框架的自测建议在改动平台配置后应该保留一组回放样本比如 50 个真实用户问题。每次改动部署框架都跑一遍回放集对比回答是否变好。这是防止“框架升级引发退化”最有效的办法。5. 部署框架选型对照表下面的表格基于常见项目经验整理可以帮助你在实际选型时做一个横向判断。场景常用框架影响行为的关键点注意事项大模型推理服务vllm、TGI、SGLang采样参数、上下文长度、并行度面向生成类模型优化embedding/reranker 不一定支持向量检索独立向量服务 FAISS/Milvus召回数量、相似度阈值、重排序单独部署 embedding 和 reranker 服务智能体编排Dify、自研 FastAPI工具注册、提示词模板、上下文组织把提示词和工具结果处理收敛到框架中统一管理前端交互Nginx Vue/React路由刷新、登录会话部署到 Nginx 后如刷新 404需要在 Nginx 配置 history 路由 fallback网关层Nginx/Gateway超时、限流、链路追踪推理服务响应慢时网关超时设置影响整体稳定性不管选哪套都需要把这几个问题想清楚模型输出是否会被框架截断工具调用失败时模型看到什么错误信息上下文超过窗口长度时是截断还是向量压缩多用户并发时框架是否有排队策略这些问题的答案才是智能体真正表现出来的行为。6. 常见问题与排查思路6.1 常见问题速查表问题现象常见原因解决思路回答不稳定同一问题结果反复变推理参数未固定或模型被动态传入 temperature在部署框架中固定 temperature/top_p禁止调用方覆盖回答明显截断像“没说完”max_tokens 设置过小或被上下文长度压缩检查 max_tokens、上下文窗口长度和输出限制知识库回答与文档内容不符分块过大/过小召回 TopK 不合理调整分块策略验证 embedding 和 reranker 效果智能体应该调用工具却直接硬答工具注册表未配置完整或工具描述太模糊在框架中注册工具并写好工具描述vllm 启动 embedding/reranker 报错vllm 对生成模型优化不适用于向量模型单独部署 embedding 服务并在框架中替换地址前端刷新页面 404Nginx 未配置 history 路由 fallback在 Nginx 配置中增加 try_files 到 index.html模型回答总是编造工具结果工具返回结果原样拼入上下文模型被误导将工具结果结构化处理并标注“该结果来自查询接口”多 GPU 服务下行为不一致并行参数配置不当动态批处理导致一致性差异固化批处理策略使用相同采样参数必要时调整并行参数6.2 详细排查vllm 无法启动 embedding / reranker在部分 NPU 设备或旧版 vllm 环境中用户会遇到“通过 vllm 启动 embedding 模型和 reranker 模型失败”的问题。排查步骤建议按顺序进行确认建模类型。vllm 优先支持 decode 类生成模型embedding 和 reranker 的模型结构与生成模型不同。查看日志报错。如果报错中明确提到模型类型不受支持则不能再继续用 vllm。换用向量检索服务。可以封装一个独立的 FastAPI 服务来加载 embedding 模型和 reranker 模型。在智能体框架中配置两个地址一个负责生成对话一个负责向量化与重排。这种拆分不仅解决兼容性问题还能让向量服务的并发和精度独立优化。7. 最佳实践与工程建议7.1 保持模型与框架解耦在智能体工程化时最忌讳把模型 API 直接写死在业务代码中。推荐在中间层加一个“模型网关”让上层 Agent 只能通过标准 OpenAI 兼容协议调用模型。这样后续换框架、换模型都不需要改 Agent 逻辑。7.2 固化所有行为敏感参数不仅要固定 temperature 和 top_p还要固定工具返回结构、提示词模板版本、知识库分块策略、召回数量。建议在框架配置文件中集中管理并对外暴露版本号。每次上线前先跑回放测试集对比行为变化。7.3 建立完整的观测链路框架里必须有日志系统记录以下内容用户原始输入系统提示词最终版本工具函数入参与返回最终发给模型的 messages 完整内容模型输出、耗时、Token 消耗。没有这些日志遇到“智能体突然变笨”的问题时完全无法定位是模型问题还是框架问题。7.4 工具呼叫的安全边界部署框架对工具的暴露范围要做最小权限控制。不要在工具列表里暴露可执行任意命令、读取任意文件、修改生产数据的能力。工具函数的入参校验、超时控制、返回结果大小限制都应该在框架层完成。涉及生产数据库或支付等敏感操作时必须增加二次确认机制并在测试环境充分验证。7.5 部署层面的灰度与回滚框架配置改动引发的智能体行为变化往往是隐性的。建议在网关层支持按用户维度灰度。比如只有 10% 流量进入新框架版本观察错误率和用户反馈后再逐步放量。一旦出现明显劣化立刻回滚框架配置而不是回滚模型。7.6 参数调优优先从框架侧入手当智能体效果不满足预期时不要一上来就换模型可以先做以下排查检查提示词模板是否与业务场景匹配检查工具返回结构化程度是否足够检查知识库召回结果是否准确检查模型是否能看到完整且必要的上下文检查推理参数是否被其他模块覆盖。很多“模型不行”的结论最终都是框架层的问题。如果框架已经调到合理水平再换模型才有对比意义。8. 总结模型决定智能体的能力下限部署框架决定模型能力能发挥出几成也决定智能体在真实业务中呈现出的稳定行为。同为一个大模型在一个框架下可能表现得像个半成品在另一个框架下就能稳定完成多轮工具调用。本文从推理参数、上下文管理、工具调用和服务架构四个角度拆解了框架对行为的影响并给出了一个完整的最小实验代码。你可以把它当成一个基线工程后续继续在这个基础上扩展工具调用、知识库检索、Dify 平台接入等能力。实际落地时建议把框架配置和模型选型放在同一优先级对待。真正需要长期投入的不是“换一个更强模型”的冲动而是把那套部署框架打磨好。只有行为链路里的每一步都可控、可观测、可回滚智能体才能从实验室 Demo 走向稳定可用的生产系统。
不管是做 AI 客服、知识库问答还是带工具调用的复杂 Agent我们几乎默认遵循一条逻辑模型选得好Agent 效果就好模型换成参数更大的新版本智能体就一定更聪明。但从我实际做过的几个项目来看情况通常没那么简单——换了更强的大模型之后智能体助手并没有变“聪明”甚至在一些场景下变得更不稳定。真正改变智能体行为的往往是那套很少被写进对比评测文章里的部署框架。本文会围绕“为什么智能体行为更多由部署框架而非模型决定”这一主题做一个系统拆解。先搞清楚模型、智能体、部署框架各自的职责边界再从推理参数、上下文管理、工具调用、资源部署四个方面分析行为差异的来源然后给出一套完整的自建智能体部署实验代码覆盖可复制的 Python 实现、部署配置和结果验证最后补充常见报错排查和工程化建议。无论你是在做 Dify 平台上的 RAG 助手还是基于 vllm 自建推理服务这篇文章都能帮你少踩一半的坑。1. 背景与核心概念1.1 为什么会出现“框架比模型更重要”的现象在智能体项目中我们通常把效果稳定或变差的缘由归结为模型。比如“GPT-4 生成的回答比 Qwen 好”“换成了更长的上下文窗口记忆能力更强了”。但把项目投入生产环境后会逐渐发现另一个隐藏变量部署框架。所谓部署框架不只是“把模型跑起来”的 vllm、TGI还包括承载智能体逻辑的应用层框架比如 Dify、LangChain 的自建版本甚至是你自己写的 FastAPI 服务。它决定了模型以什么格式接收提示词、拿到哪些工具函数、上下文被截断到多长、在超时或并发时怎么降级。这些细节堆叠在一起直接影响最终输出。一个很常见的现象是底层模型没变只修改了部署参数里的temperature或者调整了工具函数的返回阈值智能体行为就能完全变形。反过来说即使把模型换成更强的版本只要部署框架里的提示词模板、工具注册表、知识库召回策略没有同步升级输出质量可能不升反降。这也就是“行为更多由部署框架而非模型决定”这句话成立的根本原因。1.2 模型、智能体、部署框架的职责边界为了不让概念混淆先把三个层级区分清楚。模型层包含模型权重、预训练知识、基础对话能力。它决定“这个模型有多聪明”但模型本身并不知道自己要被用来做什么。智能体层包含系统提示词、任务规划逻辑、工具调用协议、上下文记忆策略。它决定“智能体为什么要这么做”。部署框架层包含推理服务、向量检索服务、Web 服务、消息路由、限流与超时策略。它决定“系统在真实环境中能否稳定复现这个行为”。从技术分工来看模型只负责给定输入后的概率分布输出真正限制和格式化输入、决定调用哪些工具、以什么顺序返回结果的是框架和智能体逻辑。因此在评估智能体项目时不能只做模型对比也要做框架对比。1.3 本文的核心观点本文不是宣称模型不重要而是想说明一个工程观察当框架没有匹配到位时模型的能力优势会被抵消而框架做得好时即使模型规级低一档智能体在具体业务上也能表现得稳定可用。下面我从 4 个影响路径入手把“框架决定行为”这件事讲透。2. 部署框架影响智能体行为的 4 个路径2.1 推理参数决定输出的稳定性和风格先看一个最常见的例子模型没变但在部署推理服务时有人在启动参数里加了temperature0.7有人用默认的0.1。两个用户问同一个问题得到的回答可能截然不同。推理服务在部署层面的几个参数会直接影响智能体的行为特征推理参数影响行为temperature决定回答的随机性值越高越发散值越低越稳定top_p配合 temperature 使用控制候选词采样范围max_tokens限制输出长度设置过小会导致回答被截断看起来像“模型不会了”repetition_penalty影响是否出现重复表达上下文长度影响模型能看到的窗口范围过长会降低响应速度过短会丢失记忆很多智能体项目在上线后出现“一阵好一阵坏”的现象并不是模型能力波动而是部署侧没有固化推理参数。部署框架中这些参数被不同请求动态覆盖时行为就会变得不可控。2.2 上下文管理与知识召回机制第二个路径是上下文。模型只负责“看当前给它的内容”但“当前给什么”由部署框架决定。以知识库问答为例如果部署框架中的向量检索模块只召回 Top-3 片段那么即使底层模型是无敌的它也只能基于这 3 段内容作答。反过来说如果召回模块能把用户原问题改写、重排后召回更准确的片段即便模型本领一般回答质量也能明显提升。在 RAG 智能体里部署框架通常承担这些工作用户文档的上传与解析文本分块chunk策略embedding 向量化向量库检索reranker 重排序检索结果拼入提示词模板。以上任何一环配置不一致都会改变模型看到的信息从而改变输出。框架在这里发挥了“信息守门员”的作用。注意 embedding 模型和 reranker 模型通常不能直接用 vllm 这种面向生成模型优化的推理服务启动尤其在昇腾 910B-A2 这类 NPU 服务器上强行用 vllm 启动 embedding 模型会报错正确的做法是单独封装为向量检索服务。2.3 工具调用机制决定智能体的行为边界智能体区别于普通聊天机器人的关键在于工具调用。模型本身往往不知道“当前环境有哪些工具”是部署框架在系统提示词和工具列表中告诉它的。部署框架中的工具注册表决定了智能体“能做”什么框架注册了联网搜索工具智能体才会在信息不足时调用搜索框架入库了订单查询接口智能体才能回答订单状态框架没注册文件读取工具智能体即使猜到了文件路径也无法读取内容。而在更细的层面工具函数返回的数据结构、错误提示语、超时时长也会改变智能体的下一步规划。例如工具返回“查询超时”有的框架会把错误原文带给模型导致模型误以为数据库中无数据有的框架会把错误翻译成“系统暂时不可用”模型就会给出更稳妥的回答。这些差异本质上是部署框架决定的。2.4 服务架构与并发模型影响用户体验第三个容易被忽略的路径是服务架构。同一个智能体项目如果用while True串行处理请求再强的模型也会因为排队时间过长而被用户判定为“不聪明”如果采用异步任务队列响应速度和并发能力提升后用户感知的智能感也会明显增强。在多卡或多机部署大模型时推理框架里的并行参数配置会让模型行为产生两个层面的差异吞吐量差异并行度越高单位时间处理的请求越多批次效应差异动态批处理时不同请求被合并到同一个 batchGPU 计算过程中的数值波动会使输出产生细微变化。在对外提供服务时需要把推理参数、上下文构建、工具协议全部固化进框架配置不能交给每个调用方随意指定。3. 自建智能体部署实验同一个模型两套框架两种行为为了把“部署框架影响行为”从概念变成可验证的结果下面我做了一个最小化实验。核心思路是保持模型不变分别用两套不同的提示词模板和工具结果拼装逻辑去调用同一个模型接口观察智能体行为差异。3.1 实验架构实验采用本地自建方式大模型推理服务远程推理服务兼容 OpenAI 协议应用框架Python FastAPI智能体核心手工实现一个AgentRunner负责规划、调用工具、拼接上下文两套框架模板一套把工具结果简单拼接在末尾另一套在拼接前做了结构化重排。架构示意如下用户请求 - FastAPI Web 服务 - AgentRunner |- 调用远程大模型推理服务 |- 调用工具函数模拟查库 |- 重新拼接上下文 - 再次调用模型 消费者拿到最终回答3.2 项目结构实验代码目录如下agent-framework-demo/ ├── app.py # FastAPI 入口 ├── agent_runner.py # 智能体核心流程 ├── tools.py # 工具函数定义 ├── prompt_builder.py # 两套提示词模板 ├── config.py # 推理参数配置 └── requirements.txt # 依赖3.3 环境准备在本地运行前需要准备Python 3.10 或更高版本一个可用的推理服务地址支持 OpenAI Chat Completions 格式安装依赖fastapi、uvicorn、openai、pydantic。版本方面需要根据你的项目实际情况调整上面的示例重点演示框架对行为的影响不一定要求最新版本。requirements.txt示例fastapi0.110.0 uvicorn0.29.0 openai1.30.0 pydantic2.6.03.4 核心代码一配置管理先把推理参数统一放到配置里避免埋没在代码各处。# config.py class LLMConfig: API_BASE http://your-inference-service/v1 API_KEY your-key MODEL_NAME qwen-72b TEMPERATURE 0.1 TOP_P 0.9 MAX_TOKENS 2048 REQUEST_TIMEOUT 30这里把 temperature 固定为 0.1是为了让模型尽量稳定输出排除随机性造成的噪声干扰。实际项目中可以把参数放到环境变量配置中心方便运行时调整。3.5 核心代码二工具函数tools.py中实现一个模拟订单查询工具。工具返回值结构是固定字典但不同框架在拼接时对返回内容的处理方式不同。# tools.py def query_order_status(order_id: str) - dict: # 模拟真实查询逻辑实际项目里可替换为 HTTP 请求或数据库查询 if order_id A1001: return { code: 200, order_id: order_id, status: 已发货, tracking_number: SF1234567890, remark: 预计今天下午送达 } return { code: 200, order_id: order_id, status: 未知, tracking_number: , remark: 该订单不存在或已被删除 }注意这里的返回值结构对最终模型输出很重要。如果框架在拼入上下文时只保留了status模型就看不到备注信息如果把整个字典原样传给模型模型会读到更多细节。这属于部署框架层对工具结果处理策略的差异。3.6 核心代码三两套提示词模板下面定义两套提示词模板。为便于对比其他条件完全一致只有工具结果的呈现方式不同。# prompt_builder.py BASE_SYSTEM_PROMPT 你是一名订单客服助手请根据用户问题给出回答。 def build_agent_input_v1(user_query: str, tool_result: dict) - list[dict]: 模板一把工具结果简单拼接在末尾。 这种写法在早期 Agent 项目里很常见模型很容易遗漏细节。 return [ {role: system, content: BASE_SYSTEM_PROMPT}, {role: user, content: user_query}, {role: assistant, content: 我需要调用工具查询订单状态。}, {role: tool, content: str(tool_result)} ] def build_agent_input_v2(user_query: str, tool_result: dict) - list[dict]: 模板二将工具结果结构化为清晰字段并重新组织上下文。 这是更接近生产可用的框架层设计。 content ( f订单查询结果如下\n f订单号{tool_result[order_id]}\n f订单状态{tool_result[status]}\n f物流单号{tool_result[tracking_number]}\n f备注{tool_result[remark]}\n 请基于以上结果回答不要编造不存在的信息。 ) return [ {role: system, content: BASE_SYSTEM_PROMPT}, {role: user, content: user_query}, {role: assistant, content: 我先查询订单状态再回答。}, {role: tool, content: content} ]模板一和模板二在同一个模型下运行观感上的表现差异非常明显。模板一中模型经常忽略remark字段甚至把tracking_number读成订单号模板二中因为字段被明确标注模型几乎不会读错。这正是“部署框架而非模型”的一个具象表现——模型的对话能力没有变但框架对工具结果的解析方式变了模型的可用性就被放大了。3.7 核心代码四AgentRunneragent_runner.py负责把用户问题、工具函数、提示词模板、模型调用串起来。# agent_runner.py from openai import OpenAI from config import LLMConfig from tools import query_order_status from prompt_builder import build_agent_input_v1, build_agent_input_v2 class AgentRunner: def __init__(self, version: str v1): self.client OpenAI(base_urlLLMConfig.API_BASE, api_keyLLMConfig.API_KEY) self.version version def run(self, user_query: str, order_id: str) - str: # 1. 调用工具 tool_result query_order_status(order_id) # 2. 根据框架版本选择不同的上下文拼装策略 if self.version v1: messages build_agent_input_v1(user_query, tool_result) else: messages build_agent_input_v2(user_query, tool_result) # 3. 调用模型 response self.client.chat.completions.create( modelLLMConfig.MODEL_NAME, messagesmessages, temperatureLLMConfig.TEMPERATURE, top_pLLMConfig.TOP_P, max_tokensLLMConfig.MAX_TOKENS, timeoutLLMConfig.REQUEST_TIMEOUT ) return response.choices[0].message.content这里的version参数就是“框架差异”的简化版。实际项目里两套框架往往不是选一个字符串而是不同的模块实现、不同的工具调用协议和不同的上下文持久化方式。3.8 核心代码五FastAPI 入口app.py中暴露一个 HTTP 接口用于测试两套框架的行为差异。# app.py from fastapi import FastAPI, Query from agent_runner import AgentRunner app FastAPI() runner_v1 AgentRunner(versionv1) runner_v2 AgentRunner(versionv2) app.get(/agent) def agent_endpoint(query: str Query(..., description用户问题), order_id: str Query(A1001, description订单号), version: str Query(v1, description框架版本号)) - dict: if version v2: reply runner_v2.run(query, order_id) else: reply runner_v1.run(query, order_id) return {version: version, reply: reply}3.9 运行与验证启动服务uvicorn app:app --host 0.0.0.0 --port 8000访问地址# 使用框架 v1 curl http://localhost:8000/agent?query我的订单到哪了order_idA1001versionv1 # 使用框架 v2 curl http://localhost:8000/agent?query我的订单到哪了order_idA1001versionv2预期现象v1 模板拿到的是str(tool_result)的原始字典字符串模型可能提取出正确状态但回答比较死板偶尔会出现字段名暴露的情况v2 模板拿到的是结构化文本模型基本能流畅地给出“已发货快递单号为 SF1234567890预计今天下午送达”的回答。在同一个模型下v2 的表现明显更接近生产可用的智能体v1 则像是一个没有做完的 Demo。二者差距完全来自部署框架而不是模型。4. 借力 Dify 等平台框架一个文件上传问答实例除了自建框架很多项目也会选择 Dify 这类开源智能体平台。平台本身同样是“部署框架”的一部分它决定了用户与模型之间的交互方式。下面以“识别上传文件内容并回答”为例说明平台框架如何改变智能体行为。4.1 平台框架的核心链路在 Dify 中是通作业流完成的完整链路如下用户上传文件 - 文档解析 - 文本分块 - 向量化(embedding) - 向量检索引擎匹配 - 将检索结果拼入上下文 - 调用大模型生成 - 返回用户回答如果只是调用模型本身Dify 里的知识库问答和普通聊天没有区别。但部署平台为我们提供了知识库阶段智能体回答就有了“依据来源”。这是模型单靠自己做不到的因为模型并不认识用户上传的新文档。4.2 平台框架里最容易影响行为的三处配置第一处是分块大小。分块太小模型可能看不到完整业务逻辑分块太大向量检索精度下降。需要根据文档类型做实验。第二处是 embedding 和 reranker 模型部署。embedding 模型负责把文本转成向量reranker 负责精排。这两类模型在昇腾 910B-A2 等 NPU 环境下不一定能通过 vllm 启动因为 vllm 主要面向生成类模型做推理优化。建议单独封装向量服务并在平台框架里配置独立的服务地址。第三处是检索 TopK 与相似度阈值。TopK 太大无关上下文进入提示词模型容易被干扰TopK 太小关键信息可能被漏掉。4.3 平台框架的自测建议在改动平台配置后应该保留一组回放样本比如 50 个真实用户问题。每次改动部署框架都跑一遍回放集对比回答是否变好。这是防止“框架升级引发退化”最有效的办法。5. 部署框架选型对照表下面的表格基于常见项目经验整理可以帮助你在实际选型时做一个横向判断。场景常用框架影响行为的关键点注意事项大模型推理服务vllm、TGI、SGLang采样参数、上下文长度、并行度面向生成类模型优化embedding/reranker 不一定支持向量检索独立向量服务 FAISS/Milvus召回数量、相似度阈值、重排序单独部署 embedding 和 reranker 服务智能体编排Dify、自研 FastAPI工具注册、提示词模板、上下文组织把提示词和工具结果处理收敛到框架中统一管理前端交互Nginx Vue/React路由刷新、登录会话部署到 Nginx 后如刷新 404需要在 Nginx 配置 history 路由 fallback网关层Nginx/Gateway超时、限流、链路追踪推理服务响应慢时网关超时设置影响整体稳定性不管选哪套都需要把这几个问题想清楚模型输出是否会被框架截断工具调用失败时模型看到什么错误信息上下文超过窗口长度时是截断还是向量压缩多用户并发时框架是否有排队策略这些问题的答案才是智能体真正表现出来的行为。6. 常见问题与排查思路6.1 常见问题速查表问题现象常见原因解决思路回答不稳定同一问题结果反复变推理参数未固定或模型被动态传入 temperature在部署框架中固定 temperature/top_p禁止调用方覆盖回答明显截断像“没说完”max_tokens 设置过小或被上下文长度压缩检查 max_tokens、上下文窗口长度和输出限制知识库回答与文档内容不符分块过大/过小召回 TopK 不合理调整分块策略验证 embedding 和 reranker 效果智能体应该调用工具却直接硬答工具注册表未配置完整或工具描述太模糊在框架中注册工具并写好工具描述vllm 启动 embedding/reranker 报错vllm 对生成模型优化不适用于向量模型单独部署 embedding 服务并在框架中替换地址前端刷新页面 404Nginx 未配置 history 路由 fallback在 Nginx 配置中增加 try_files 到 index.html模型回答总是编造工具结果工具返回结果原样拼入上下文模型被误导将工具结果结构化处理并标注“该结果来自查询接口”多 GPU 服务下行为不一致并行参数配置不当动态批处理导致一致性差异固化批处理策略使用相同采样参数必要时调整并行参数6.2 详细排查vllm 无法启动 embedding / reranker在部分 NPU 设备或旧版 vllm 环境中用户会遇到“通过 vllm 启动 embedding 模型和 reranker 模型失败”的问题。排查步骤建议按顺序进行确认建模类型。vllm 优先支持 decode 类生成模型embedding 和 reranker 的模型结构与生成模型不同。查看日志报错。如果报错中明确提到模型类型不受支持则不能再继续用 vllm。换用向量检索服务。可以封装一个独立的 FastAPI 服务来加载 embedding 模型和 reranker 模型。在智能体框架中配置两个地址一个负责生成对话一个负责向量化与重排。这种拆分不仅解决兼容性问题还能让向量服务的并发和精度独立优化。7. 最佳实践与工程建议7.1 保持模型与框架解耦在智能体工程化时最忌讳把模型 API 直接写死在业务代码中。推荐在中间层加一个“模型网关”让上层 Agent 只能通过标准 OpenAI 兼容协议调用模型。这样后续换框架、换模型都不需要改 Agent 逻辑。7.2 固化所有行为敏感参数不仅要固定 temperature 和 top_p还要固定工具返回结构、提示词模板版本、知识库分块策略、召回数量。建议在框架配置文件中集中管理并对外暴露版本号。每次上线前先跑回放测试集对比行为变化。7.3 建立完整的观测链路框架里必须有日志系统记录以下内容用户原始输入系统提示词最终版本工具函数入参与返回最终发给模型的 messages 完整内容模型输出、耗时、Token 消耗。没有这些日志遇到“智能体突然变笨”的问题时完全无法定位是模型问题还是框架问题。7.4 工具呼叫的安全边界部署框架对工具的暴露范围要做最小权限控制。不要在工具列表里暴露可执行任意命令、读取任意文件、修改生产数据的能力。工具函数的入参校验、超时控制、返回结果大小限制都应该在框架层完成。涉及生产数据库或支付等敏感操作时必须增加二次确认机制并在测试环境充分验证。7.5 部署层面的灰度与回滚框架配置改动引发的智能体行为变化往往是隐性的。建议在网关层支持按用户维度灰度。比如只有 10% 流量进入新框架版本观察错误率和用户反馈后再逐步放量。一旦出现明显劣化立刻回滚框架配置而不是回滚模型。7.6 参数调优优先从框架侧入手当智能体效果不满足预期时不要一上来就换模型可以先做以下排查检查提示词模板是否与业务场景匹配检查工具返回结构化程度是否足够检查知识库召回结果是否准确检查模型是否能看到完整且必要的上下文检查推理参数是否被其他模块覆盖。很多“模型不行”的结论最终都是框架层的问题。如果框架已经调到合理水平再换模型才有对比意义。8. 总结模型决定智能体的能力下限部署框架决定模型能力能发挥出几成也决定智能体在真实业务中呈现出的稳定行为。同为一个大模型在一个框架下可能表现得像个半成品在另一个框架下就能稳定完成多轮工具调用。本文从推理参数、上下文管理、工具调用和服务架构四个角度拆解了框架对行为的影响并给出了一个完整的最小实验代码。你可以把它当成一个基线工程后续继续在这个基础上扩展工具调用、知识库检索、Dify 平台接入等能力。实际落地时建议把框架配置和模型选型放在同一优先级对待。真正需要长期投入的不是“换一个更强模型”的冲动而是把那套部署框架打磨好。只有行为链路里的每一步都可控、可观测、可回滚智能体才能从实验室 Demo 走向稳定可用的生产系统。
