Vertex AI自定义容器在线端点处理请求时收到SIGTERM问题排查

核心原因判断 #

你的容器在有未完成任务时收到SIGTERM关闭，大概率是自动扩缩容触发的缩容行为，而非Gunicorn超时直接导致，具体分析如下：

1. 扩缩容误判负载：你配置的扩缩容规则仅基于CPU使用率70%，但你的任务是通过后台线程执行，主线程快速返回空闲状态，会让实例的CPU使用率看起来远低于实际负载（后台线程的CPU占用可能未被扩缩容系统准确识别）。当CPU使用率降到阈值以下，或一段时间无新请求时，Vertex AI会启动缩容，关闭多余实例。
2. Gunicorn配置适配问题：你的--graceful-timeout=300设置为5分钟，和单任务耗时持平，但Gunicorn的优雅关闭逻辑只关注worker是否处理完当前请求（你的主线程已返回，worker认为请求完成），不会等待后台线程的任务。不过从日志看实例运行时长远超300秒，说明Gunicorn超时不是直接关闭原因，但shutdown handler和Gunicorn的退出逻辑可能存在冲突。

具体排查步骤 #

• 验证扩缩容触发条件
  • 查看Vertex AI端点监控：重点看实例关闭前的CPU使用率、请求QPS、待处理任务数（如果有自定义采集），确认缩容是否发生在CPU低于70%或请求量骤降时。
  • 检查扩缩容事件日志：在Vertex AI控制台的端点事件记录中，查看缩容操作的触发原因，确认是负载不足还是达到最小副本数限制。
• 测试Gunicorn与后台任务的兼容性
  • 手动发送SIGTERM信号到运行中的容器，观察shutdown handler是否能正确拦截并等待所有后台任务完成后再退出。如果容器直接关闭，说明shutdown handler逻辑存在漏洞，或Gunicorn未等待后台线程。
  • 检查Gunicorn worker的状态：查看日志中worker的启动、退出时间，确认是否有worker被意外杀死的情况。
• 排查任务队列与线程管理
  • 确认后台线程的状态跟踪是否准确：日志中显示的“pending requests”是否包含正在执行的任务，还是仅未开始的队列。如果正在执行的任务未被统计，shutdown handler可能无法正确等待。

优化解决方案 #

• 调整扩缩容策略
  • 替换或补充扩缩容指标：不要仅依赖CPU使用率，改用自定义指标（比如待处理任务数、队列长度）来触发扩缩容，让系统准确感知实例的实际负载。
  • 提高最小副本数：如果日常待处理请求量较大，将最小副本数从1调整为2或更高，避免缩容到单实例导致任务堆积和频繁重启。
• 优化Gunicorn与任务处理逻辑
  • 延长超时配置：将--timeout和--graceful-timeout设置为大于单任务最长耗时（比如600秒），给shutdown handler足够时间等待任务完成。
  • 重构任务处理方式：放弃后台线程模式，改用异步框架（如FastAPI）或独立任务队列（如Celery）将长任务从在线预测端点剥离，在线端点仅负责接收请求和返回任务状态，实际推理任务在独立的计算资源中执行，避免缩容影响任务进度。
• 完善shutdown handler
  • 在shutdown handler中添加线程等待逻辑：使用线程池的join()方法，或设置全局标志位，让所有后台线程完成当前任务后再退出，确保容器关闭前所有任务都处理完毕。

内容的提问来源于stack exchange，提问作者Techie5879