在 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)

这样可以避免服务已经启动，但实际无法调用模型的情况。

七、健康检查和业务请求要分开

健康检查只需要验证最小链路，不应该复用复杂业务提示词。

建议：

• 使用固定、简短的测试内容
• 使用低输出限制
• 不读取真实用户数据
• 不把检查结果当作业务结果
• 给健康检查设置单独的超时时间

这样既容易分析，也不会影响正常业务。

八、哪些场景适合增加健康检查？

• AI 工具后端
• 定时自动化任务
• 多模型调用服务
• 个人开发环境
• 测试部署流程
• 需要备用接口的项目

当项目开始依赖外部 API 时，健康检查就是一个很实用的基础能力。

九、结语

一个好用的健康检查不需要很复杂，关键是做到：

1. 检查真实 API 调用链路
2. 记录状态码和响应时间
3. 不泄露密钥和用户内容
4. 区分网络、鉴权、限流和服务错误
5. 按合理频率执行

对于 Python AI 项目，可以先从一个最小check_api()函数开始，再逐步接入日志、告警和备用模型策略。

免责声明

本文内容仅用于技术交流与经验分享，具体实现请结合项目实际情况调整。