用 Cog 将 Python 模型打包为容器

用 Cog 将 Python 模型打包为容器，核心是定义构建与运行配置，再由 cog build 生成 Docker 镜像；镜像启动后会在端口 5000 提供 HTTP 服务。Cog 的容器部署文档说明了构建、端口和运行方式；这条模型部署路径还要把入口、依赖、调用和 GPU 排查连起来。

模型部署前先准备运行环境

按 Cog 官方说明，Cog 生成的容器可供自有基础设施或 Replicate 使用，同时要求安装 Docker。若使用 Docker Engine 而非 Docker Desktop，还需要安装 Buildx。Cog 不原生支持 Windows，Windows 11 应通过 WSL 2 使用；macOS 可以执行：

brew install replicate/tap/cog

如果模型需要 GPU，按 Docker 的 GPU 访问说明，应先在宿主机安装 NVIDIA 驱动并重启，再安装 NVIDIA Container Toolkit。先完成这一层准备，再排查 Cog 构建或运行问题。

用 cog.yaml 定义构建和运行接口

进入 Python 项目目录后执行：

cog init

按 项目初始化文档，该命令会生成 cog.yaml 和 run.py。

当前 cog.yaml 配置参考定义的顶层键为 build、image 和 run。容器支持 Python 3.10、3.11、3.12 和 3.13；设置 build.gpu: true 后，Cog 会使用 nvidia-docker 基础镜像，并根据 Python、PyTorch 或 TensorFlow 版本选择 CUDA 和 cuDNN，确有需要时再用 build.cuda 覆盖自动选择。

Python 依赖应优先写入 build.python_requirements；旧的 build.python_packages 已弃用，而且两者不能同时设置。build.system_packages 用于 Ubuntu APT 软件包，build.run 用于准备命令，但执行这些命令时看不到源码，因此不要把必须读取项目源码的步骤放进去。

image 用于命名构建出的 Docker 镜像。新项目的入口应采用 run.py:Runner；虽然旧项目仍可使用 predict.py:Predictor，但 predict 已被标记为弃用别名：

run: "run.py:Runner"

编辑配置时，把依赖、系统准备命令和模型入口分开处理，后续构建失败也更容易定位到对应部分。

构建镜像并启动 HTTP 服务

按照 Cog 的容器部署说明，可以先用镜像名构建项目：

cog build -t my-model

GPU 镜像可使用文档中的生产启动示例：

docker run -d -p 5001:5000 --gpus all my-model

这里把宿主机端口 5001 接到容器端口 5000。容器内运行的是基于 Rust 的推理服务器 coglet，负责处理 HTTP 请求、管理工作进程并执行模型运行。该命令是 GPU 示例；不使用 GPU 的镜像不要机械照抄 --gpus all。

分两步确认容器能够工作

先用 cog run 检查本地调用链。按 Cog 的模型调用说明，输入通过 -i 传递，文件参数加 @ 前缀；支持的输入类型包括 str、int、float、bool 和 cog.Path：

cog run -i image=@image.jpg -i scale=2.0

这是官方示例，务必把 image 和 scale 换成你的模型真实字段。命令能够使用预期输入执行并返回模型结果，说明本地入口基本可用。

使用 GPU 时，还可以先按 Docker GPU 文档提供的命令单独检查 GPU 传递：

docker run -it --rm --gpus all ubuntu nvidia-smi

该步骤通过后，再启动模型容器，并通过宿主机端口 5001 按项目接口文档发送真实请求。Cog 的通用说明给出了容器端口和 coglet 的职责，但没有为所有模型规定统一的请求路径，因此不要自行假定根路径就是健康检查接口。

常见出错点

依赖键互相冲突

如果配置同时出现 python_packages 和 python_requirements，构建前应删除已经弃用的旧键，只保留 build.python_requirements。两者不能并存，否则你无法判断构建时究竟采用了哪套依赖入口。

新旧接口混用

Replicate 的推送指南仍展示 cog predict 和 predict.py:Predictor 工作流，而当前 Cog 配置已把 predict 标记为弃用。不要把两套入口拼在同一个新项目中：沿用旧项目时先核对 Cog 版本，新建项目则使用 run.py:Runner。

端口可连但请求仍失败

把排查分成三层：先确认容器能看到 GPU，再确认宿主机端口能连到容器端口，最后核对模型自己的请求路径和输入格式。前两层通过并不代表模型接口一定正确，通用端口正常后仍应检查项目接口文档。

这些步骤按正文链接的官方文档整理，未做运行或性能测量；使用前应结合当前版本复核。