如果你已经能跑通基础调用下一步最值得做的就是把请求封装得更稳。这篇文章适合个人开发者、AI 工具作者、自动化脚本玩家直接参考。为什么基础调用不够很多人第一次接 API 的时候代码是这样的fromopenaiimportOpenAI clientOpenAI(api_keysk-xxxxxx,base_urlhttps://your-api-domain.com/v1)responseclient.chat.completions.create(modelyour-model-name,messages[{role:user,content:你好}])print(response.choices[0].message.content)这段代码能跑但如果你真把它放进项目里后面很容易遇到这些问题网络偶尔失败请求超时接口返回错误模型临时不可用并发一高就容易出问题所以真正适合项目的写法不是“能跑就行”而是要把重试超时异常处理日志输出一起加进去。一、为什么要给 API 调用加重试网络请求不是每次都稳定成功尤其是你在做AI 工具站自动化脚本Agent 工作流批量请求的时候偶发失败很正常。如果没有重试用户看到的就是“失败”如果加了重试很多临时问题可以自动恢复。适合重试的情况网络闪断短暂超时目标服务临时抖动连接不稳定不适合无限重试的情况参数写错Key 无效model 名字错误请求格式不对所以重试要有边界不能无脑死循环。二、先给你一个最实用的封装版本下面这个版本适合个人项目直接用。示例代码importtimefromopenaiimportOpenAIfromopenaiimportAPIError,APIConnectionError,APITimeoutError,RateLimitError clientOpenAI(api_keysk-xxxxxx,base_urlhttps://your-api-domain.com/v1,timeout20.0)defask_llm(prompt:str,model:stryour-model-name,max_retries:int3)-str:last_errorNoneforattemptinrange(1,max_retries1):try:responseclient.chat.completions.create(modelmodel,messages[{role:system,content:你是一个专业的技术助手。},{role:user,content:prompt}])returnresponse.choices[0].message.contentexcept(APIConnectionError,APITimeoutError,RateLimitError,APIError)ase:last_erroreifattemptmax_retries:wait2*attemptprint(f第{attempt}次失败{wait}秒后重试{e})time.sleep(wait)else:print(f重试结束最终失败{e})exceptExceptionase:# 非预期错误直接抛出方便排查raiseRuntimeError(f调用失败{e})fromeraiseRuntimeError(f请求失败已重试{max_retries}次{last_error})三、这段代码是怎么工作的1.timeout20.0给请求加超时避免一直卡住。2.max_retries3最多重试 3 次避免无限循环。3. 只对“适合重试”的错误做重试比如连接错误超时限流API 临时问题4. 不可恢复错误直接报出来比如代码写错参数非法模型名不对这种问题重试没意义必须直接修。四、为什么要把错误类型分开处理因为不是所有错误都一样。1.APIConnectionError网络连接问题比如域名、代理、线路问题。2.APITimeoutError接口太慢超时了。3.RateLimitError请求太频繁或者额度有限。4.APIError接口返回了服务端错误。如果你把所有错误都混在一起处理后面排障会很难。五、推荐的生产级写法如果你是做项目我建议你再加两样东西1. 日志至少把失败原因记下来。print(f[API ERROR] attempt{attempt}, error{e})2. 统一封装不要每个文件都单独写一份请求代码。建议封装成一个llm_client.py后面统一调用。六、一个更完整的项目结构你可以这样组织project/ ├── llm_client.py ├── main.py ├── config.py ├── logs/ └── requirements.txtllm_client.py负责 API 调用封装。config.py负责读取base_url、api_key、model。main.py负责业务逻辑。这样后面维护会轻松很多。七、哪些场景特别需要这套封装这套写法特别适合AI 工具站批量问答脚本Agent 工作流文本生成任务自动化调用个人效率工具如果你要的是稳定运行而不是“跑通一次就算”那这套封装很值得做。八、几个很实用的建议建议 1超时别设太长太长会让用户感觉系统卡死。建议 2重试别太多重试 2~3 次通常就够了。建议 3错误日志要清楚至少要知道是网络问题、限流还是参数错了。建议 4先本地调通再上线不要直接把未验证的调用逻辑放进正式功能。九、结语对于个人开发者来说接 API 不只是“能调用”而是要“稳定、可维护、可扩展”。所以在你跑通最小示例之后下一步最值得做的就是加重试加超时加错误处理统一封装这样你的项目后面才不会越写越乱。如果你也在做 AI 工具、脚本自动化或者个人项目可以直接留言或私信我可以把我整理好的接入经验发给你。免责声明本文内容仅用于技术交流与经验分享不构成任何商业承诺。具体使用效果请以实际测试为准。