如何使用 python 调用 api

你在本地跑通了第一段 Python 请求，但一放进项目就出问题：偶尔卡住不返回、批量跑一半被限流、报错信息看不出哪一步挂了、换个模型整个脚本要重写。这篇不讲协议原理，只讲把请求包成能上线的函数该怎么做——参数怎么设、异常怎么兜、并发怎么控、日志记什么、上线前拿什么自测。

你在本地跑通了第一段 Python 请求，但一放进项目就出问题：偶尔卡住不返回、批量跑一半被限流、报错信息看不出哪一步挂了、换个模型整个脚本要重写。这篇不讲协议原理，只讲把请求包成能上线的函数该怎么做——参数怎么设、异常怎么兜、并发怎么控、日志记什么、上线前拿什么自测。

先把心态摆正：一次请求成功，只能说明这一次没踩到边界，不代表你的函数是稳定的。下面每一节都按「先写什么、怎么验证、什么情况下不适用」来讲，你照着做能少走很多弯路。

先写一个能跑的请求函数，再往上加东西

不管是 requests 还是官方 SDK，第一步都是把一次同步请求封成函数。关键是把四个变量单独拎出来做成配置：接口地址、鉴权头、模型名、消息体。不要把它们散落在业务代码里，否则换一次源你要翻遍全项目。字段含义可以到 基础字段词典（/ai-dict/category/basics） 先混个脸熟，字段名拼错是最常见的低级报错。

• 先跑通非流式，确认能拿到完整返回，再改流式；流式挂掉时先退回非流式，判断是网络问题还是解析问题
• 请求函数只做两件事：发请求、返回结构化结果或抛明确异常，不要在函数里顺手写业务逻辑
• 把「能跑」和「稳定跑」分开看：一次成功只能说明这次没触发边界，不能当成参数设对了
• 函数签名里把超时、重试次数留成可选参数，后面几节才有地方加东西

超时、重试和退避：三个必须写死的值

新手最容易犯的错是全套默认值：连接超时和读取超时分开设，读取超时按你最慢那档模型的响应时间留余量，别用一个默认值走天下。具体怎么分档，可以对照 超时调优（/api-timeout-tuning） 里的思路，按你的实际请求形态取值，不要照抄别人的数字。

重试只对可恢复的错误做：连接失败、网关错误、限流。参数错误、鉴权失败重试多少次都一样，纯属浪费额度。退避要带随机抖动，固定间隔在批量场景下反而更容易撞上限流。

1. 设两个超时连接超时和读取超时分开放，读取超时先按你观察到的慢请求上限乘一个安全系数
2. 区分可重试错误把异常按网络层、鉴权层、参数层、限流层分类，只对前两者里的网络类和限流类重试
3. 加退避和抖动每次重试等待时间递增，并对等待时间加随机扰动，避免多任务同时重试
4. 设总预算算出最坏情况总耗时，超过预算就放弃并记录，不要无限重试

并发别凭感觉调，先量再压

很多人一上来就把并发调到很高，结果失败率飙升还以为是接口问题。正确顺序是先单线程跑一批，看单次耗时和失败率，这就是你的基线。基线都不稳就别急着加并发。限流的具体机制和恢复方式可以对照 限流恢复（/api-rate-limit-recovery），照着排查比你瞎猜快。

• 并发数从低往高试，盯失败率和延迟，出现明显拐点就回退一档
• 队列要有背压：积压超过阈值就暂停投递，而不是无限堆内存
• 批量任务记录每条的成功、失败、重试次数，失败后只重投失败项，不要整批重跑
• 给每个任务打上来源标签，方便区分是接口慢还是你自己的代码慢

# 思路示意，不是完整代码
results = []
for item in batch:
    try:
        r = call_api(item, timeout=(3, 30))
        results.append((item, 'ok', r))
    except RetryableError as e:
        results.append((item, 'retry', str(e)))
    except FatalError as e:
        results.append((item, 'fail', str(e)))
# 失败项单独收集，下一轮只跑 fail/retry 的

降级方案要在写代码时就留好口子

降级不是出事了才想，而是写代码时就留好口子。模型名、超时、并发数全部走配置，不要硬编码在业务逻辑里，换源时才不用改代码。准备「换模型」和「降级到非流式或更短输出」两条退路，触发条件写成明确规则：连续失败几次、延迟超过多少。不要写成「感觉不行就换」。

换模型退路

同一任务准备一个能力相近的备选源，触发条件写成连续失败次数或延迟阈值

降级输出

流式失败退回非流式，或缩短最大输出长度，保证任务能出结果

格式容忍

多源切换时字段可能缺失，解析层用默认值兜底，别假设两家格式完全一致

降级日志

降级发生时至少打一条日志，否则你会在几天后才发现一直在用备用方案

需要注意，降级本身会带来体验差异，如果你的业务对输出质量敏感，降级后要么提示用户，要么走异步补偿，不要静默换掉还在用结果的下游。这条在什么情况下不适用？如果任务本身可重试且不面向用户，静默降级问题不大。

日志记什么、上线前自测什么

日志不是越多越好，而是要能在事后复盘一次慢请求和一次贵请求。每次请求至少记：时间、模型、耗时、是否流式、输入输出量、状态码、错误类型。字段清单和回放思路可以参考 日志字段与回放（/api-log-fields-replay），照着对齐一遍能发现你缺了哪些关键字段。

对成本敏感的场景，先用 成本估算工具（/tools/model-cost-calculator） 按你的请求形态估一遍，再决定并发上限和重试策略。具体单价和分档数字不要凭记忆，去 价格追踪（/price-watch） 核对当时的数字，因为不同时间、不同源都可能变。