Docker容器调用FastAPI的/sentiment端点时崩溃问题排查求助

问题详情 #

• 基于Huggingface Transformer模型搭建FastAPI REST API，模型可正常加载至服务器，但调用/sentiment预测端点时Docker容器直接停止，其他未使用模型的端点运行正常
• 已确认Docker桌面有8GB可用内存，模型本身仅占用0.5GB
• 使用技术栈：FastAPI、Huggingface Transformers、Docker、Poetry
• 构建及运行容器命令：

docker build --target production -t classifier .
docker build -t classifier .

• 服务器启动日志显示正常：

INFO:     Started server process [1]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:80 (Press CTRL+C to quit)

• 完整代码可查看指定仓库的docker-crashes分支

可能的问题原因及排查方向 #

• 容器内存配额限制：Docker桌面总内存充足，但单个容器可能被默认限制了内存使用上限。尝试手动指定容器内存配额，比如执行docker run -m 4g classifier，观察是否仍会崩溃。
• 推理阶段内存突发占用：模型本身占用0.5GB，但推理时的预处理、张量运算会产生临时内存开销，CPU推理时这种峰值可能超出容器配额。可以在容器内用top命令监控推理时的内存变化，或在代码中添加内存使用日志，确认峰值情况。
• 依赖版本不兼容：Poetry管理的依赖可能存在版本冲突，比如Transformers、Torch与FastAPI/Uvicorn的版本不匹配。检查pyproject.toml中的依赖版本，尝试锁定稳定兼容的版本组合（比如指定Transformers的具体稳定版本，确保Torch与容器架构适配）。
• Docker构建镜像问题：两次构建命令分别使用了production目标和默认目标，需确认生产镜像是否完整包含模型权重、依赖包，以及文件权限是否允许推理时读取模型文件。
• Uvicorn多进程内存叠加：默认Uvicorn可能启用多进程模式，每个进程都会加载一次模型，导致内存占用叠加。尝试设置Uvicorn使用单进程启动（比如uvicorn main:app --workers 1），避免重复加载模型。
• OOM Killer触发：容器崩溃可能是被系统OOM Killer终止，但未在日志中显示。用docker ps -a查看退出容器的状态码，若为137则说明是内存不足导致的崩溃。
• 推理代码逻辑问题：检查/sentiment端点的代码，是否存在未处理的异常、内存泄漏，或者每次请求时重复加载模型的情况，这些都会导致内存累积或直接崩溃。

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