Cog CLI 保姆级上手：模型容器化完整路径

【免费下载链接】cogContainers for machine learning项目地址: https://gitcode.com/GitHub_Trending/co/cog

模型在你 Mac 上跑得欢，推到同事机器或云服务器就炸：Python 版本差小版本、CUDA 对不上、某个 C 库悄悄缺失。说白了，模型部署的麻烦全出在"环境"两个字上。Cog CLI 的思路很直接：把模型代码、依赖、权重一起打进一个镜像，运行环境跟着代码走——这就是模型容器化的核心。

一图看懂：从写代码到上线

整条主线只有四步：写代码、构建镜像、本地跑通推理、把镜像推上仓库。注意最后那条虚线——改代码之后你回到第一步，而不是把整条线重新走一遍，这一点下面会专门讲。

🐣 刚 clone 完仓库：30 秒生成项目骨架

仓库地址是 https://gitcode.com/GitHub_Trending/co/cog，clone 下来直接翻examples/blur，它是最小可读的完整示例：给一张图做高斯模糊。

如果从零开始，一条命令生成骨架：

cog init

它会落地三个文件：cog.yaml声明环境，run.py是模型入口，requirements.txt装依赖。cog.yaml你真正要填的核心就这几行：

build: gpu: false python_version: "3.12" python_requirements: requirements.txt run: "run.py:Runner"

run.py里你只需要关心两件事：setup()一次性加载模型，run()处理单次输入。输入参数用类型注解加Input(...)声明，Cog 会据此自动生成接口文档，不用你手写。

🔧 日常调试：改代码不用重新打包

第一次构建，以及第一次跑通推理

在示例目录里敲：

cog run -i image=@examples/kodim24.png -i blur=4

这条命令背后干了一串事：解析cog.yaml、静态生成 OpenAPI schema、校验-i传入的值、构建镜像、启动容器、轮询健康检查直到模型加载完、发送推理请求。全程你只按了一次回车。

输出图会直接落到当前目录，模糊前后对比如下：

顺手记下几个参数：-o out.png把输出写到指定路径；-i传本地文件必须带@前缀，否则会被当成普通字符串；--setup-timeout控制容器内模型加载的超时秒数，大权重模型记得调大。

进容器验证 GPU，而不是看日志猜

依赖有没有装全、CUDA 能不能用，与其翻构建日志，不如直接进去问：

cog exec python -c "import torch; print(torch.cuda.is_available())"

cog exec基于cog.yaml构建环境后跑你给的任意命令，第一个参数之后的内容会原样透传给容器，后面还能挂-e KEY=VALUE注入环境变量、-p 8888发布端口给宿主机（跑 Jupyter 很顺手）、--gpus指定 GPU。

你注意到没有：如果宿主机缺 GPU 驱动，CLI 会自动去掉 GPU 参数重试，并提示Missing device driver, re-trying without GPU——不会直接给你一坨报错。

起个本地 HTTP 服务，代码改动免重建

想联调接口，就起服务：

cog serve curl -X POST http://localhost:8393/predictions \ -H 'Content-Type: application/json' \ -d '{"input": {"prompt": "a cat"}}'

起服务后有三个端点可用：/predictions发推理请求、/openapi.json看接口规范、/health-check探活。-p改宿主机端口（默认 8393），--host 0.0.0.0允许局域网访问。

它省时间的地方在构建方式上：源码不是复制进镜像，而是以卷挂载进容器。换句话说，你改run.py不用重新构建镜像，重启容器即可；依赖层和cog build共享 Docker 缓存，只有cog.yaml环境变了才真正重建。

🚀 准备上线：把镜像送到任意 OCI 仓库

推之前先存凭证：

cog login

走 token 认证，凭证交给 Docker 的 credential 系统保管；CI 场景用--token-stdin从标准输入喂 token。

cog build -t my-model cog push r8.im/your-username/my-model --separate-weights

cog push接收任意 OCI 兼容的仓库地址，r8.im/owner/name走 Replicate，registry.example.com/...走你自己的仓库，目标由 provider 自动识别。-t指定镜像标签，优先级高于cog.yaml里的image字段；--no-cache强制全量重建；--secret id=foo,src=path在构建期注入密钥。--separate-weights会把权重拆成独立镜像层，后续只改代码时不用重传几十 GB 权重。推送成功会打印带 digest 的引用，复制下来就能在别处固定版本。

敲下回车后，背后只发生三件事

你敲下回车，Cog 先用 tree-sitter 静态解析run.py的类型注解生成 OpenAPI schema，输入错误在构建之前就能拦下；接着按 CUDA 兼容矩阵选基础镜像、生成 Dockerfile、交给 BuildKit 构建，schema 和配置以 label 写进镜像；最后容器内起一个 HTTP 服务，CLI 轮询/health-check到 READY 才发推理请求。整个过程模型代码从不接触宿主机，只在容器里跑。

容易踩的坑

• 服务起不来？先检查端口：容器内服务固定监听 5000，cog serve映射到宿主机默认 8393，访问地址是http://localhost:8393。
• GPU 项目在没有驱动的机器上启动失败属正常现象，CLI 会自动去 GPU 重试并打印提示，别被吓到。
• --use-cog-base-image、--use-cuda-base-image、--dockerfile三者互斥，同传会直接报错。
• -i image=photo.jpg少了@，文件路径会被当成字符串传进去，校验直接失败。
• cog predict已弃用，见警告就换成cog run；cog debug只生成 Dockerfile 不构建，适合排查构建问题；cog weights管权重镜像层，cog train调训练端点，这三个默认不出现在帮助里。

一句话：init 起步，run、serve 管开发，build 打包，push 上线。上手就敲这条：

cog run -i image=@examples/kodim24.png -i blur=4

延伸阅读：Schema 架构说明、预测 API 架构说明

【免费下载链接】cogContainers for machine learning项目地址: https://gitcode.com/GitHub_Trending/co/cog