AI Agent请求大模型的三种方式：SDK、HTTP裸调与框架封装选型指南

做AI Agent开发，绕不开的一个问题是：你写的智能体背后，到底用哪种方式把请求发给大模型。很多人一开始直接用官方SDK，后来自建系统改HTTP接口，再后来又套上了LangChain之类的框架。每个阶段的选择都有它的道理，但很少有人把“单次模型请求”这件事单独拎出来看清楚。这篇文章就基于我自己做Agent的实战经验，把三种主流方式一次讲透：官方SDK直调、HTTP/REST裸调、通过Agent框架封装调用。适合正在写Agent、接大模型API、或者想搞清楚框架底层在做什么的开发者参考。看完你就能明白，这三种方式各自解决什么问题、代价是什么、以及你自己的项目该选哪条路。

1. 先搞清楚“单次模型请求”到底指什么

1.1 Agent里最基础的原子操作

谈“三种方式”之前，必须先定义清楚“单次模型请求”。我见过不少朋友把Agent的整个运行流程和一次模型调用混为一谈，结果排查问题的时候思路全乱。

一个Agent从拿到用户输入到给出最终结果，中间通常会经历多轮“思考-调用-观察”的循环。每一轮循环里，Agent要把当前的历史消息、系统提示词、可能调用的工具描述、用户的原始问题一起打包，发给大模型，拿到一次补全结果。这个“发一次、收一次”的动作，就是单次模型请求。而Agent的整个决策链路，是由成百上千次这样的单次请求串联起来的。

为什么必须单独关注这一次请求？因为它决定了整个Agent的底层体验。一次请求的响应速度决定了Agent思考的快慢，一次请求的Token消耗直接关系到你的成本账单，一次请求里的参数配置——比如temperature、max_tokens、tools——决定了模型这轮的输出质量。可以说，就算你把Agent的编排逻辑写得再精巧，如果单次请求这一层不够稳，整个系统都立不住。

1.2 三种方式的共同前提

无论用哪种方式，你本质上都在做同一件事：把一段符合模型协议的消息结构发送到服务端，然后解析返回。这个“消息结构”在主流模型里长得很像——都有role和content，system/user/assistant三种角色，有的还支持functions或tools字段。

区别只在于你用什么姿势去完成这件事。官方SDK是把这套协议封装成你熟悉语言的函数调用；HTTP裸调是你亲手拼JSON、亲手发请求、亲手解析流式包；框架封装则是把这一整套动作藏进抽象层，让你面向业务写代码。

明白了这个共同前提，下面三种方式的对比才有着力点。它们解决的是同一件事，只是抽象层次不同、控制粒度不同、依赖多少不同。接下来我按“从最直接到最封装”的顺序，逐一拆开讲。

2. 方式一：官方SDK直调，开发体验最顺的路

2.1 SDK到底替你做了什么

凡是做大模型应用的人，第一个接触的几乎都是官方SDK。比如你在Python里用OpenAI SDK写一句client.chat.completions.create()，背后发生的事情其实相当多。

首先是协议封装。SDK帮你把Python对象序列化成服务端要求的具体JSON结构，把所有HTTP细节藏起来。其次是认证和连接管理，你只需要在初始化时传一次API Key，SDK会负责生成正确的header、管理连接池和SSL/TLS。再就是响应解析，SDK直接把服务端返回的JSON解析成带自动补全属性的对象，你可以用response.choices[0].message.content这种点号链直接取内容。

还有一个容易被忽略的点：SDK会跟随模型服务端的接口升级而更新。模型厂商加了新参数，SDK很快会跟进，你的代码只需要改一两个字段就能用上新能力。对绝大多数项目来说，这是开发效率最高的选择。

2.2 一个能跑的SDK调用样板

直接看代码。以下是我在项目里实际使用过的一段最简示例，用的是新版的OpenAI Python SDK（1.x版本，注意和0.x的调用风格完全不同）：

from openai import OpenAI client = OpenAI(api_key="your-api-key") response = client.chat.completions.create( model="gpt-4o-mini", messages=[ {"role": "system", "content": "你是一个擅长梳理技术方案的助手。"}, {"role": "user", "content": "帮我写一个获取天气信息的函数设计。"} ], temperature=0.7, max_tokens=1024 ) print(response.choices[0].message.content)

这里有几个细节值得说。第一，messages是整个单次请求的核心，system、user的顺序一般不能乱，如果做多轮对话还要按顺序把assistant的历史回复也加进来，否则模型会搞不清上下文。第二，temperature和max_tokens是影响单次请求最直观的两个参数，前者控制随机性，后者控制输出长度上限。第三，api_key直接写在代码里只适合本地测试，真正部署要放到环境变量或密钥管理服务里。

如果要做流式输出，把上面的代码改成stream=True，然后遍历响应对象，体验会明显不一样——首字延迟会大幅降低，用户在聊天界面里看到的就是逐字蹦出来的效果。

stream = client.chat.completions.create( model="gpt-4o-mini", messages=[...], stream=True ) for chunk in stream: delta = chunk.choices[0].delta.content if delta: print(delta, end="")

2.3 用SDK时最容易翻车的三个地方

SDK虽然省事，但我在实际项目中踩过不少坑，这里挑三个最常见的讲。

第一，版本差异。早期0.x版本的OpenAI SDK里，调用入口是openai.ChatCompletion.create()，到了1.x变成了client.chat.completions.create()。如果你拿着旧教程的代码配上新版SDK，一跑就会报错。我建议新项目直接锁最新版本，并且读官方迁移文档，别在网上随便复制代码。

第二，超时设置。SDK通常有默认超时，但那个默认值对复杂提示词来说经常不够用。模型推理本来就慢，长上下文或者开启了工具调用时，等几十秒都很正常。我一般会显式设置更长的超时：OpenAI(client = OpenAI(timeout=60.0))，避免请求被半路掐断。

第三，自动重试。SDK内置了对429和5xx错误的重试机制，这本来是好事，但在Agent场景里如果模型的单次请求本身已经消费了Token，重试会造成重复计费。更麻烦的是，如果你的编排逻辑不设防，重试可能雪崩式叠加。我的经验是：自行控制重试次数和退避策略，不要全交给SDK默认行为。

3. 方式二：HTTP/REST裸调，灵活和可控的代价

3.1 为什么框架都存在还要裸调接口

很多人会有疑问：官方SDK都那么完善了，为什么还要自己拼HTTP请求？

我自己的经历里，裸调的需求主要出现在这三种情况。一是跨语言场景，你的Agent服务如果是Go、Rust或其他语言写的，而模型官方没有维护对应语言的SDK，或者SDK不成熟，那直接调HTTP接口就是唯一选择。二是特殊功能需求，比如某些高级参数、自定义的调试开关，SDK还没有暴露，你只能通过原始请求去控制。三是对依赖极度敏感的场景，有些运行环境不能随便装第三方包，或者你希望整个模型调用层零依赖、完全自主可控。

用一句话概括：SDK省事但绑手绑脚，HTTP裸调是把协议握在自己手里。代价就是你得自己处理一切——请求构造、鉴权、流式解析、错误码映射、连接池管理。

3.2 用代码看懂HTTP裸调的真实流程

下面是我用Python的httpx库实现的一段原生HTTP调用，做完和上面SDK一样的事：

import httpx import json url = "https://api.openai.com/v1/chat/completions" headers = { "Content-Type": "application/json", "Authorization": "Bearer your-api-key" } payload = { "model": "gpt-4o-mini", "messages": [ {"role": "system", "content": "你是一个擅长梳理技术方案的助手。"}, {"role": "user", "content": "帮我写一个获取天气信息的函数设计。"} ], "temperature": 0.7, "max_tokens": 1024, "stream": True } with httpx.stream("POST", url, headers=headers, json=payload, timeout=60.0) as resp: if resp.status_code != 200: body = resp.read() print(f"HTTP {resp.status_code}: {body.decode()}") else: for line in resp.iter_lines(): if line.startswith("data:") and not line.endswith("[DONE]"): data = json.loads(line[6:]) delta = data["choices"][0]["delta"].get("content") if delta: print(delta, end="")

这段代码的关键点有三个。一是流式响应的解析，服务端返回的不是一个完整的JSON，而是按行推送以data:开头的SSE消息（Server-Sent Events），你拿到后要手动跳过事件前缀、手动JSON解析、还要识别[DONE]结束标记。二是错误处理，裸调时HTTP状态码就是你的第一道信号，其实响应的body里还有更详细的错误码和message，排查问题时要学会两个结合起来看。三是超时，http库默认也会等你，但我总是显式设置，否则Agent挂起的概率会很高。

非流式请求就更简单了，用httpx.post加json=payload，然后resp.json()里取choices[0].message.content就行。需要传图片等多模态数据时，还要在messages里构造带image_url的对象，请求体更复杂，但同样是裸JSON手动拼。

3.3 裸调时绕不开的四个细节

第一个是连接复用。每次调用都新建一个HTTP连接，性能会差很多，尤其当你的Agent在高并发下。我习惯用httpx.Client创建一个长连接客户端，在多个请求之间复用连接池。

第二个是请求体大小。日志、工具描述、历史消息全部塞进单次请求后，整个payload可能非常大。有的网关会对请求体大小有限制，有的模型上下文窗口吃不下那么多内容。裸调时你完全暴露在这些限制面前，得学会做消息压缩和摘要。

第三个是工具调用的差异。不同模型提供商的tools参数格式其实不完全一样——有的叫functions，有的叫tools，参数结构选型的说明也不同。裸调时你必须为每一种模型单独维护一套请求模板，这也是后期维护成本最高的地方。

第四个是高可用配置。裸调让你可以自定义多Provider的fallback，比如A厂商超时自动切到B厂商。这反而是裸调的一大优势。我见过有团队特意放弃SDK，就是为了把这种多模型路由逻辑做得足够精细。

4. 方式三：通过Agent框架封装，写业务不是写协议

4.1 框架层把单次请求藏在哪

LangChain、LlamaIndex这类Agent框架很流行，它们对单次模型请求的封装方式是：提供一个统一的模型抽象，让你用几乎一样的代码切换不同的模型厂商。

我以LangChain为例。在框架里，模型被抽象成BaseChatModel，典型用法是创建一个ChatOpenAI对象，调用invoke方法传入消息列表，即可拿到一个完整的响应对象。框架帮你做了模型API的适配，让你面向“模型能力”编程，而不是面向具体厂商的协议编程。

from langchain_openai import ChatOpenAI from langchain_core.messages import HumanMessage llm = ChatOpenAI(model="gpt-4o-mini", temperature=0.7) messages = [HumanMessage(content="帮我写一个获取天气信息的函数设计。")] response = llm.invoke(messages) print(response.content)

如果要做流式，把invoke换成stream，yield出来的就是一个个内容片段。如果在多轮对话里用，就要把消息列表维护好，每一次新调用都带着完整历史。

框架的价值在于：今天你写的业务逻辑用的是OpenAI模型，明天想换成其他模型，只需要改掉模型类和相关配置，上层业务代码几乎不用动。这种多模型可移植性，是裸调方案最难实现的。

4.2 框架里怎么带工具做单次调用

Agent和普通对话最大的区别就是工具调用。比如一个天气Agent，模型要能知道“当前有哪些函数可以调用、参数是什么、什么时候该调用”。

在LangChain里做带工具的调用，其实是把你定义好的函数传给模型，再由框架处理中间的流程：

from langchain_core.tools import tool from langchain_openai import ChatOpenAI @tool def get_weather(city: str) -> str: """查询指定城市当前天气""" return f"{city}：晴，25度。" llm = ChatOpenAI(model="gpt-4o-mini", temperature=0.7) llm_with_tools = llm.bind_tools([get_weather]) response = llm_with_tools.invoke( [HumanMessage(content="北京今天天气怎么样？")] ) print(response.tool_calls)

这个单次请求的返回里会包含模型计算的tool_calls，其中带有函数名和参数。你拿到这个结果后，还要自己执行真函数、把结果作为tool消息回传给模型，模型才能最终生成给用户的回答。注意，即使有框架，这个“工具执行后再回传”的循环依然需要你自己编排，框架只是帮你把“模型返回工具调用”这一步变得更友好。

4.3 框架封装的隐形成本

框架给你省了大量协议层面的工作，但隐形成本一定会还回来的。

第一是Debug难度上升。框架的调用链很深，一次简单的单次请求，内部可能经过了好几层抽象。一旦出问题，你很难一眼看出是参数没传对、协议不兼容、还是框架版本和SDK版本冲突。我实际排查过的不少故障，最后都定位到“LangChain版本太老，和最新SDK不兼容”这种问题上。

第二是性能损耗。框架会在请求前后做消息转换、回调通知、缓存判断等额外工作。相比HTTP裸调，一次调用多出几十毫秒开销并不罕见。对于极低延迟、高并发的场景，框架层反而可能成为瓶颈。

第三是黑盒带来的失控感。当你需要精确控制一次请求的原始报文时，框架抽象往往会阻碍你。有些框架提供自定义回调或请求钩子，但学习成本依然不低。

5. 三张表看清三种方式怎么选

5.1 核心维度对比

选项这种东西，摆在一起比才有意义。我把实践中的感受整理成了一张表：

可以看出，没有哪个维度是全面碾压的。SDK适合快速起步，HTTP适合深度控制，框架适合需要多模型支持的工程化项目。

5.2 按项目阶段选择

如果是自己写Demo、跑通概念验证，直接用官方SDK就够了。你不需要关心协议细节，只需要快速看到模型的输出，验证业务想法是否成立。这个阶段花时间去搞HTTP裸调纯属浪费。

如果是做正式产品，尤其是以Agent为核心、对成本和质量要求都比较高的产品，我会建议至少把模型调用层独立成模块。前期用SDK，但把调用点收敛在一个文件里。一旦发现SDK不够用，比如需要精细路由、需要自定义重试策略、需要处理多个Provider，再切换到HTTP裸调就很容易。

如果项目要接多家模型服务，且业务层不想关心模型差异，那框架是值得投入的。但团队里至少要留一个人懂框架的底层原理，否则每次遇到和模型协议相关的问题都会被卡住。

5.3 我的个人选择建议

我个人的习惯不是三选一，而是分场景混用。底层数据服务、批量任务、对可靠性要求最高的核心链路上，用HTTP裸调，因为我能完全掌握一次请求的每一毫秒。对快速迭代的普通对话场景，用SDK，开发效率更高。只有在需要快速适配多家模型做对比实验时，才会让框架介入。

这听起来可能不够“统一”，但实际工程里，混用往往比强求单一技术路线更舒服。关键在于你心里清楚每条链路的边界在哪里，出了问题知道去哪里看。

6. 我踩过的坑和排查速查表

6.1 超时与重试的教训

有一次，我的Agent在深夜突然大面积报错，排查后发现是某一次单次模型请求在等待响应时卡住了，所有并发都在空等，最后全部超时。根因有两个：一是当时代码里没有给请求设置合理的超时时间，二是下游模型服务当时响应确实变慢了。

那次之后我总结了一条硬规矩：所有单次模型请求必须显式设置超时和重试策略，超时阈值按场景区分。简单的问答请求，30秒就够；长文档总结和带工具链的复杂请求，要给到60到90秒。重试要加指数退避，比如首次失败后等1秒、第二次2秒、第三次4秒，最多重试3次，避免服务刚恢复瞬间被重试流量打爆。

6.2 流式解析的经典坑

流式响应的解析是裸调最常见的翻车点。我见过的最经典问题是：代码里直接用data["choices"][0]["delta"]["content"]，结果发现当delta里没有content字段直接是None时，一取就会报错。原因是流式过程中有些分片只有role变化或者工具调用参数，根本没有文本内容。

正确做法是先.get("content")再判断是否为空，就像我在前面示例里写的那样。另外要注意，部分服务在流式结束时可能不发送[DONE]标记，而是直接关闭连接，所以解析逻辑最好把“连接意外断开”也当作正常结束来处理。

6.3 Token与费用追踪

做过Agent的人都有这种体验：单次请求的Token消耗往往超预期。一个带全套工具描述、长历史消息的Agent请求，系统提示词加工具定义可能就占了几千Token，而用户的输入才几十个字。

我建议每一层请求都记录Model Usage信息。SDK里response.usage可以拿到prompt_tokens、completion_tokens、total_tokens；HTTP裸调时，响应体的usage字段同理。把这些数据统一打到日志里，按小时聚合统计，你才能真正掌握Agent的成本分布，发现“某内置工具的描述太长导致每次都浪费Token”这种隐蔽问题。

6.4 常见问题速查表

最后一张表，是我这段时间反复用到的排查清单，列在这里给你当备忘录。

这张表也是我排查问题时最快的入口。遇到模型请求异常，先冷静判断是前置参数问题、网络问题、还是模型服务端的问题，再决定动手方向。千万别一上来就怀疑模型本身——大多数故障都发生在自己的代码层。

这次就分享到这里。三种方式没有绝对的优劣，我的建议是：初学阶段别纠结，直接挑最顺手的官方SDK跑通流程；项目做大以后，再根据你对延迟、成本、可控性的真实需求，逐步向裸调或框架方案迁移。过程中多留日志、多做对比实验，你很快就能形成自己的判断标准。