企业官网建设流程全解析

调用大模型 API 这件事，很多人第一反应是装个官方 SDK，pip install一行命令，然后照着文档把 key 填进去就完事。我一开始也这么干，直到有段时间需要在几个不同的模型服务之间来回切换，才发现 SDK 这层封装有时候反而是负担：每个厂商一套接口、一套依赖、一套版本兼容问题，项目里光 SDK 就装了好几个，依赖冲突排查起来相当头疼。后来我干脆把 SDK 全卸了，统一用 Python 标准库之外的requests直接发 HTTP 请求，世界一下子清爽了。

这篇内容就是把我这段时间用requests裸调大模型 API 的完整经验整理出来，以百度 ernie-4.5-turbo 这类对话模型为例，把请求怎么拼、鉴权怎么做、流式响应怎么处理、错误怎么兜底这些事讲透。适合两类人看：一类是想搞明白 SDK 背后到底发生了什么、不想被封装黑盒困住的中级开发者；另一类是项目里依赖已经够乱、想用最轻量的方式接入模型能力的工程同学。哪怕你之前只用过 SDK、没手写过 HTTP 请求，跟着走一遍也能上手，因为我会把每一步的意图和坑都讲清楚。

1. 为什么我宁愿手写 HTTP 也不装 SDK

1.1 SDK 的便利与它悄悄带来的耦合

先说公道话，官方 SDK 不是没有价值。它帮你把鉴权、重试、参数序列化这些琐事包好了，文档里的示例复制粘贴就能跑，对刚接触模型 API 的人来说门槛确实低。但问题在于，SDK 本质上是一层厂商定制化的封装，它把某家服务的接口形态固化进了你的代码里。一旦你的项目需要接第二家、第三家模型服务，或者某天想从 A 模型换到 B 模型做效果对比，你就会发现业务代码里到处是 SDK 特有的对象和方法名，迁移成本比想象中高得多。

我踩过最典型的一个坑是依赖版本。某个 SDK 依赖了特定版本的 HTTP 客户端库，而我项目里另一个组件依赖了同库的另一个大版本，两者不兼容，pip装完直接报冲突。折腾半天最后发现，如果当初直接用requests发请求，根本不会有这层依赖传递的问题——requests本身足够稳定，接口十几年没大变过，几乎不会成为冲突源。

1.2 裸调 HTTP 到底换来了什么

用requests直接调 API，最直接的好处是透明。你发出的每一个字段、收到的每一段响应，都在你眼皮底下，没有中间层帮你"猜"。调试的时候这一点特别重要：SDK 报错往往只给你一句模糊的异常，而裸调 HTTP 你能直接看到状态码、响应头、原始 body，定位问题快得多。

第二个好处是可移植。HTTP 请求的形态是通用的，你把请求体里的模型名、endpoint 换一下，同一套代码逻辑就能对接不同厂商的对话接口——当然各家的字段命名和鉴权方式有差异，但骨架是通的。这意味着你可以在项目里抽象出一层薄薄的适配，而不是被某家 SDK 绑死。

第三个好处是可控的依赖面。整个方案只需要requests一个第三方库（标准库的urllib也能干，但写起来啰嗦），打包体积、安全审计、版本升级的负担都小。对于要交付到客户环境或者跑在受限容器里的项目，这点很实在。

提示：裸调不等于什么都自己造。重试、超时、连接池这些通用能力requests已经提供了，我们要做的是把"业务相关的部分"（请求体构造、响应解析）掌握在自己手里，而不是连 HTTP 客户端都自己写。

1.3 什么情况下还是建议用 SDK

也不是所有场景都适合裸调。如果你的项目只对接一家服务、团队里没人熟悉 HTTP 细节、又追求最快上线，那用官方 SDK 完全合理，别为了"纯粹"而增加无谓的工作量。另外有些厂商的高级功能（比如特定的文件上传协议、复杂的多模态封装）在 SDK 里做得比较完善，裸调要自己啃文档，性价比不一定高。我的判断标准很简单：当你开始频繁切换模型、或者被 SDK 的依赖/行为困扰时，就该考虑裸调了；否则按团队习惯来。

2. 动手前的准备：鉴权、endpoint 与请求骨架

2.1 拿到访问凭证并理解它的用法

调用任何大模型 API，第一步都是拿到访问凭证。以百度这类平台为例，通常是在控制台创建应用后获得一对API Key和Secret Key，然后需要先用它们换一个短期的access_token，再用这个 token 去调对话接口。这个"两级凭证"的设计和很多云服务一致：长期密钥不直接出现在每次业务请求里，降低泄露风险。

换取 token 的请求一般长这样（具体路径以官方文档为准，这里演示结构）：

import requests def fetch_access_token(api_key: str, secret_key: str) -> str: url = "https://aip.baidubce.com/oauth/2.0/token" params = { "grant_type": "client_credentials", "client_id": api_key, "client_secret": secret_key, } resp = requests.post(url, params=params, timeout=10) resp.raise_for_status() data = resp.json() return data["access_token"]

这里有几个细节值得说。grant_type=client_credentials是 OAuth 的标准模式，表示"用客户端凭证换令牌"，别写成别的值。timeout=10一定要加，网络请求没有超时等于给自己埋雷，后面会专门讲。raise_for_status()在状态码非 2xx 时抛异常，比手动判断status_code更省事。

拿到的access_token通常有有效期（比如 30 天），不要每次请求都去换，那样既慢又可能触发频率限制。正确做法是缓存起来，快过期时再刷新。我一般用一个简单的内存字典加时间戳来管，进程重启就重新换一次，够用了。

2.2 对话接口的请求体长什么样

拿到 token 后，对话请求一般是往一个带access_token查询参数的 URL POST 一个 JSON body。ernie 系列的对话接口请求体核心字段大致是这几块：

一个最小可用的请求构造如下：

def build_chat_payload(user_text: str) -> dict: return { "messages": [ {"role": "user", "content": user_text} ], "temperature": 0.7, "stream": False, }

messages是数组而不是单个字符串，这点和早期的一些补全接口不同，它天然支持多轮对话——你把历史消息按顺序塞进去，模型就能"记得"上下文。temperature我一般对话场景设 0.7，需要稳定输出（比如抽取结构化信息）时降到 0.1~0.3。

2.3 把请求发出去并解析响应

拼好 body 后，请求本身很直接：

def chat_once(token: str, payload: dict) -> str: url = "https://aip.baidubce.com/rpc/2.0/ai_custom/v1/wenxinworkshop/chat/ernie-4.5-turbo" resp = requests.post( url, params={"access_token": token}, json=payload, headers={"Content-Type": "application/json"}, timeout=60, ) resp.raise_for_status() data = resp.json() return data["result"]

注意json=payload这个参数，requests会自动帮你做 JSON 序列化并设置Content-Type，比手动data=json.dumps(...)更不容易出错。响应里对话结果通常在result字段（不同接口字段名可能不同，以文档为准），错误信息则在error_code/error_msg里。

注意：对话接口的timeout要给足。模型生成长文本时响应可能几十秒，设太短会频繁超时。我一般非流式设 60 秒，流式设更长或干脆不设总超时、只设连接超时。

3. 流式响应：让输出像打字一样出来

3.1 为什么对话场景几乎必须上流式

非流式请求要等模型把整段话生成完才一次性返回，用户盯着空白屏幕等十几秒，体验很差。流式（stream=true）则是模型每生成一小段就推给你一段，前端可以边收边显示，感知延迟大幅降低。这也是各家对话产品的标配做法。

流式的底层通常是Server-Sent Events（SSE），响应体是一行行以data:开头的文本，每行是一个 JSON 片段。requests处理它的关键是stream=True加上迭代iter_lines()：

def chat_stream(token: str, payload: dict): url = "https://aip.baidubce.com/rpc/2.0/ai_custom/v1/wenxinworkshop/chat/ernie-4.5-turbo" payload = {**payload, "stream": True} with requests.post( url, params={"access_token": token}, json=payload, headers={"Content-Type": "application/json"}, stream=True, timeout=(10, 120), ) as resp: resp.raise_for_status() for line in resp.iter_lines(decode_unicode=True): if not line or not line.startswith("data:"): continue chunk = line[len("data:"):].strip() if chunk == "[DONE]": break yield chunk

timeout=(10, 120)是元组形式，第一个是连接超时，第二个是读取超时——流式场景下这个区分很重要，连接要快，读取可以慢。iter_lines(decode_unicode=True)帮你按行切分并解码，省得自己处理字节流。

3.2 解析每个数据块并拼接

上面yield出来的是原始 JSON 字符串，实际使用时要解析出增量文本。不同接口的字段名不一样，ernie 系列流式块里通常是result字段携带增量内容：

import json def collect_stream(token: str, payload: dict) -> str: full = [] for raw in chat_stream(token, payload): try: obj = json.loads(raw) except json.JSONDecodeError: continue piece = obj.get("result", "") if piece: full.append(piece) return "".join(full)

这里有个容易忽略的点：流式块不保证每个都是合法 JSON，偶尔会有空行、心跳行或者被截断的片段，所以json.loads要包在 try 里，解析失败就跳过，别让一个坏块把整个流搞崩。

3.3 流式场景下的几个实战坑

第一个坑是代理和缓冲。如果你在请求链路上有反向代理，它可能默认缓冲响应，导致流式变成"假流式"——数据攒够了才一次性吐出来。排查方法是看首字节到达时间，如果和非流式差不多，基本就是被缓冲了，需要在代理层关掉缓冲。

第二个坑是连接中断的处理。流式连接时间长，中途网络抖动很常见。我的做法是在外层包一层重试，但只对"还没收到任何数据就断了"的情况重试，已经收到部分内容再重试会导致重复输出，得靠业务层去重或者干脆提示用户重试。

第三个坑是资源释放。用with语句包住响应对象很重要，否则连接可能不释放，跑久了连接池耗尽。我见过有人图省事不用with，结果批量跑几百次后卡死，排查半天才发现是连接泄漏。

4. 错误处理与稳定性：让调用不轻易翻车

4.1 先分清哪些错误值得重试

大模型 API 的错误大致分三类，处理策略完全不同：

把这三类混在一起无脑重试是新手常犯的错。401 你重试一百次还是 401，纯属浪费；而 429 不重试又会让请求直接失败。所以重试逻辑里要先判断状态码。

4.2 一个够用的退避重试封装

import time import random def request_with_retry(method, url, max_retries=3, **kwargs): for attempt in range(max_retries + 1): try: resp = requests.request(method, url, **kwargs) except requests.RequestException as e: if attempt == max_retries: raise time.sleep(2 ** attempt + random.random()) continue if resp.status_code in (429, 500, 502, 503, 504): if attempt == max_retries: resp.raise_for_status() time.sleep(2 ** attempt + random.random()) continue resp.raise_for_status() return resp

2 ** attempt是指数退避，加个random.random()是抖动，避免多个客户端同时重试造成"惊群"。这个封装不复杂，但覆盖了绝大多数临时故障场景。

4.3 token 失效的自动刷新

前面说 token 要缓存，但缓存有个绕不开的问题：它会在某个时刻失效。我的做法是把"换 token"和"发请求"解耦，请求遇到 401 时触发一次刷新再重试一次：

class TokenManager: def __init__(self, api_key, secret_key): self.api_key = api_key self.secret_key = secret_key self._token = None def get(self, force_refresh=False): if self._token is None or force_refresh: self._token = fetch_access_token(self.api_key, self.secret_key) return self._token

调用侧在收到 401 时调get(force_refresh=True)再试一次。这样既避免了每次请求都换 token 的开销，又能应对过期。注意刷新要加锁或者用单例，多线程环境下别让十个线程同时去换 token。

5. 从能跑到好用：参数调优与工程化细节

5.1 temperature 和输出长度怎么定

temperature是最常被滥调的参数。我的经验是：需要确定性输出就压低，需要创意就抬高。做信息抽取、分类、格式转换这类任务，0.1 甚至 0 都行；做文案、头脑风暴，0.7~0.9 更合适。别迷信某个"最佳值"，同一任务跑几组对比一下最靠谱。

max_output_tokens则直接关系到成本和延迟。设太大模型可能啰嗦，设太小又会截断。我的做法是先不设，观察正常输出的长度分布，然后取一个略高于 P95 的值作为上限，既防跑飞又不误伤。

5.2 多轮对话的上下文管理

messages数组会随着对话轮次增长，而模型的上下文窗口是有限的。无脑全量塞进去，迟早超限报错，而且 token 费用也水涨船高。常见策略有两种：一是滑动窗口，只保留最近 N 轮；二是摘要压缩，把早期对话用模型总结成一段再塞回去。前者简单粗暴够用，后者更省 token 但多一次调用开销。我一般先用滑动窗口，真遇到需要长记忆的场景再上摘要。

5.3 把调用封装成可复用的客户端

裸调不等于每次手写请求。把 token 管理、重试、流式解析这些收拢到一个类里，业务侧只调一个方法，代码会干净很多：

class ChatClient: def __init__(self, api_key, secret_key, model="ernie-4.5-turbo"): self.tokens = TokenManager(api_key, secret_key) self.model = model def chat(self, messages, stream=False, **params): payload = {"messages": messages, "stream": stream, **params} # 内部处理 token、重试、流式/非流式分支 ...

这样换模型时只改model参数或 endpoint，业务逻辑不动。这也是裸调相对 SDK 的一个隐性优势：适配层是你自己写的，长什么样你说了算。

提示：把 endpoint、模型名、超时这些做成配置项而不是硬编码，换环境、换模型时不用改代码。我吃过硬编码的亏，测试环境和生产环境 endpoint 不同，上线前忘了改，白排查半小时。

6. 我踩过的几个真实坑

第一个坑是请求体字段名记错。不同厂商对同一个概念叫法不同，有的叫messages，有的叫prompt，有的把系统提示单独放一个字段。我一开始照着 A 家的文档写，换到 B 家直接 400，还以为是 token 问题，查了半天才发现是字段名对不上。教训是：换服务时先把请求体字段表对一遍，别想当然。

第二个坑是中文编码。早期我用data=json.dumps(payload)手动序列化，忘了设ensure_ascii=False，结果中文全变成\uXXXX转义，虽然功能上没错，但日志里看着难受，排查时也不直观。用json=payload参数就没这个问题，requests处理得比较妥当。

第三个坑是并发下的连接池。默认requests用的是全局 session，连接池大小有限。我做过一个批量任务，几十个线程同时发请求，结果大量请求卡在等连接上。后来改成每个线程用自己的Session，或者调大连接池，问题才解决。这个坑不常见，但一旦碰上很隐蔽。

第四个坑是流式响应的编码。某些情况下iter_lines返回的字节流如果没正确解码，中文会乱码。decode_unicode=True大多数时候够用，但如果响应头没带正确的 charset，就得手动指定编码。我现在的习惯是拿到resp.encoding看一眼，不对就手动设成utf-8。

7. 这套方案适合延伸到哪

裸调 HTTP 这套骨架一旦跑通，延展性其实很好。比如你想做多模型路由，可以在客户端里维护一个模型到 endpoint 的映射，根据任务类型或成本预算选模型；想做结果缓存，在请求前加一层基于请求体哈希的缓存，相同问题直接命中；想做调用监控，在封装层埋点记录耗时、token 消耗、错误率，比在 SDK 外面套一层更自然。

我个人在实际操作中的体会是，裸调最大的价值不是省了那点依赖，而是让你对"一次模型调用到底发生了什么"有完整的掌控感。出问题时你知道该看哪一层，优化时你知道该动哪个参数，这种确定性在长期维护的项目里比一时的开发便利重要得多。如果你现在正被多个 SDK 的依赖和接口差异折腾，不妨挑一个接口用requests重写一遍试试，跑通之后大概率就不想回去了。