当前位置：首页 > news >正文

Python 如何给 AI API 做健康检查：快速判断接口是否可用

news 2026/8/4 5:26:41

在 AI 工具、自动化脚本或后端服务中，接口偶尔超时并不罕见。增加健康检查，可以在真正处理用户请求前，先判断接口、模型和网络是否正常。

为什么需要健康检查？

如果程序只有在用户请求时才发现接口异常，通常会带来几个问题：

用户直接看到错误
故障发现不及时
很难判断是网络还是接口问题
备用方案无法及时切换
排查时缺少基础数据

健康检查的目标不是验证所有功能，而是用一个轻量请求快速回答：

当前 API 地址能访问吗？ 鉴权信息有效吗？ 指定模型能响应吗？

一、健康检查应该检查哪些内容？

建议拆成三层：

1. 网络层

确认域名、端口和 HTTPS 连接是否正常。

2. 鉴权层

确认 API Key 是否可用，但不要在日志中打印完整 Key。

3. 模型层

发送一个最小请求，确认指定模型可以返回结果。

分层检查比只访问首页更有意义，因为网页能打开不代表 API 调用一定正常。

二、用 requests 做最小健康检查

importosimporttimeimportrequestsfromdotenvimportload_dotenv load_dotenv()BASE_URL=os.getenv("BASE_URL","").rstrip("/")API_KEY=os.getenv("API_KEY","")MODEL=os.getenv("MODEL","your-model-name")defcheck_api(timeout:int=10)->dict:url=f"{BASE_URL}/chat/completions"headers={"Authorization":f"Bearer{API_KEY}","Content-Type":"application/json",}payload={"model":MODEL,"messages":[{"role":"user","content":"请只回复：ok"}],"max_tokens":8,}started=time.perf_counter()try:response=requests.post(url,headers=headers,json=payload,timeout=timeout,)elapsed=time.perf_counter()-startedreturn{"ok":response.ok,"status_code":response.status_code,"latency_ms":round(elapsed*1000,2),}exceptrequests.RequestExceptionasexc:elapsed=time.perf_counter()-startedreturn{"ok":False,"status_code":None,"latency_ms":round(elapsed*1000,2),"error":str(exc),}

这里使用了一个很短的提示词和较小的输出限制，目的是降低健康检查本身的请求开销。

三、不要把敏感信息写进检查结果

健康检查的结果可能会进入日志、监控面板或通知消息，因此不要返回：

完整 API Key
Authorization 请求头
用户原始提示词
模型生成的完整内容

建议只保留这些字段：

{"ok":True,"status_code":200,"latency_ms":532.4}

如果需要区分不同环境，可以额外记录环境名称，但不要记录密钥本身。

四、根据状态码判断问题类型

可以先做一个简单分类：

defclassify_status(status_code):ifstatus_codeisNone:return"network_error"ifstatus_code==401:return"authentication_error"ifstatus_code==429:return"rate_limit"if500<=status_code<600:return"upstream_error"if200<=status_code<300:return"healthy"return"request_error"

分类之后，通知内容会比简单显示“失败”更有帮助。

五、健康检查不应该太频繁

健康检查也会占用请求额度，因此不要设置过短间隔。

可以根据用途选择：

本地开发：手动执行
测试环境：每 1 到 5 分钟一次
正式服务：结合流量和故障等级调整

如果接口本身有严格的频率限制，应该优先查看服务说明，再设计检查周期。

六、把健康检查接到启动流程

在程序启动时执行一次，可以提前发现配置问题：

if__name__=="__main__":result=check_api()ifresult["ok"]:print(f"API healthy:{result['latency_ms']}ms")else:print(f"API unavailable:{result}")raiseSystemExit(1)