Cog CLI 深度实战：6 条命令把 Python 模型变成生产级推理容器

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

Cog 是面向机器学习模型容器化的开源工具：Python 写模型，一份 cog.yaml 声明环境，即可打包成带标准 HTTP 接口的 Docker 镜像。本文按项目初始化、本地推理、服务启动、推送 registry 的完整流程，串讲 Cog CLI 各命令的参数、内部调用链与隐藏能力，给你一份可直接上手的实操参考。

从一个真实场景开始：本地跑一次模糊

假设你只有一个用 PIL 模糊照片的小脚本，想直接在模型最终的运行环境里验证它，但不想碰手写 Dockerfile、CUDA 版本对齐、包 HTTP 接口这些杂事。仓库里的 examples/blur/ 就是这样个项目：cog.yaml 只声明 Python 版本和依赖，run.py 里的Runner.run()接收一张图和一个模糊半径，返回输出图路径。

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

这条命令背后发生的事：构建镜像 → 启动容器 → 容器内执行setup()→ 向/predictions发请求 → 把返回的图片写回本地文件。处理完的输出就是这张带方框模糊的照片：

注意-i image=@examples/kodim24.png里的@前缀：本地文件由 CLI 读取后以 base64 data URL 形式上传进容器，这段逻辑在 pkg/cli/predict.go 的transformPathsToBase64URLs里，MIME 类型按扩展名推断。

一次完整旅程：从空目录到线上服务

一条模型从 0 到生产的最短路径，每一步都是一条命令：

# 1. 生成项目骨架 cog init # 2. 构建镜像 cog build -t my-model:latest # 3. 本地跑一次预测 cog run -i image=@photo.jpg # 4. 启动 HTTP 服务做联调 cog serve -p 8393 # 5. 登录并推送 cog login cog push r8.im/your-username/my-model

• cog init从内嵌模板写出 cog.yaml、run.py、requirements.txt，模板通过 Go 的 embed 直接编进二进制。
• cog build依次完成解析配置、静态生成 OpenAPI schema、生成 Dockerfile、构建镜像、写入 label，入口在 pkg/cli/build.go，Dockerfile 生成在 pkg/dockerfile/。
• cog run构建后启动容器，经 HTTP 与容器内运行时交互，执行核心在 pkg/predict/predictor.go。
• cog serve启动同一个运行时但不发预测请求，常驻等待调用。
• cog push复用 build 的构建路径，推送与目标 registry 的后处理由 pkg/provider/ 按目标地址分派。

核心命令逐个讲

cog init：一步生成项目骨架

在当前目录生成开箱即用的配置文件。它没有专属参数，唯一的行为差异是：已存在的文件会提示Skipped existing ...并跳过，绝不覆盖你的代码。AGENTS.md 会优先尝试下载最新版，失败时回退到内嵌模板（见 pkg/cli/init.go）。生成的 run.py 是继承BaseRunner的骨架类：

from cog import BaseRunner, Input, Path class Runner(BaseRunner): def setup(self) -> None: """Load the model into memory to make running multiple requests efficient""" def run(self, image: Path = Input(description="Grayscale input image"), scale: float = Input(description="Factor to scale image by", ge=0, le=10, default=1.5), ) -> Path: """Run the model on a single input"""

Input(ge=0, le=10, default=1.5)这类约束注解会被 Cog 静态解析进 OpenAPI schema，后续的输入校验就靠它。

cog build：构建镜像

cog build -t my-model:latest cog build --no-cache --separate-weights

常用参数：

易错点：--use-cog-base-image、--use-cuda-base-image、隐藏的--dockerfile三者互斥，同时设置会被checkMutuallyExclusiveFlags直接拦下。镜像命名优先级：-t> cog.yaml 的image>model> 按项目目录生成的默认名。

cog run：本地跑一次推理

cog run -i prompt="a cat" -i steps=50 cog run -i image=@photo.jpg -o out.jpg echo '{"prompt": "a cat"}' | cog run --json @-

常用参数：

进阶技巧：把已构建镜像名作为位置参数传入就切换到"基于镜像"路径——拉取镜像、优先用镜像 schema label 预校验输入，label 不可用时在容器启动后再取运行时 schema：

cog run r8.im/your-username/my-model -i prompt="hello"

旧命令cog predict仍可执行但会打印弃用警告，二者共享同一实现（newPredictionCommand）。

cog serve：起一个 HTTP 服务

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

易错点：访问端口不是 5000——5000 是容器内绑定端口，宿主机默认是 8393。另外 serve 构建时跳过COPY . /src，源码以卷挂载到/src（serveBuildOptions中ExcludeSource: true），改代码不用重建镜像（见 pkg/cli/serve.go）。

cog exec：容器里执行任意命令

cog exec python -c "import torch; print(torch.cuda.is_available())" cog exec -p 8888 jupyter notebook --ip=0.0.0.0 cog exec -e HUGGING_FACE_HUB_TOKEN=xxx python download.py

实现细节：exec 用SetInterspersed(false)关闭参数交错解析，第一个位置参数之后的所有内容（包括--ip这种长得像 flag 的东西）都会原样传给容器内命令，不会被 CLI 吃掉。

cog push 与 cog login：部署与认证

cog login # r8.im 走 token 流程；其他 registry 提示输入用户名/密码 cog login --token-stdin < token.txt # CI 非交互场景 cog push r8.im/your-username/my-model cog push registry.example.com/you/model # 任意 OCI registry

cog push 与 build 共享大部分参数（--no-cache、--secret、--separate-weights等），目标是完整镜像引用；cog.yaml 的model字段已配置时可省略，用COG_MODEL/COG_MODEL_TAG环境变量可分别覆盖完整引用或仅 tag。

两个值得注意的细节：validatePushArgs（见 pkg/cli/push.go）在数分钟的构建开始前就先解析目标引用，配置冲突当场报出；推送成功后打印 digest 固定的引用树（model / image / weight 三行），可以直接复制。registry 行为由 pkg/provider/ 抽象，Replicate 与通用 OCI 各有一个 provider。

🔧 内部机制走读：一次 cog run 背后发生了什么

本地源码预测时，CLI 与容器之间是严格的时序（调用链见 pkg/cli/predict.go 的cmdPredict）：

三个值得记住的实现细节：

1. 校验先于构建。schema 生成与输入校验在调用resolver.Build()之前完成，输错一个参数名不会触发分钟级构建。
2. GPU 回退。未显式传--gpus且模型声明需要 GPU 时，CLI 自动以gpus=all启动；若 Docker 报缺设备驱动（ErrMissingDeviceDriver），则去掉 GPU 参数重试并提示Missing device driver, re-trying without GPU。run、serve、exec 三处都有这段逻辑。
3. RUST_LOG 透传。宿主机设置了RUST_LOG时自动传入容器，方便调试容器内 Rust 运行时（coglet）的日志；serve/exec 还会注入LOG_FORMAT=console得到人读日志。

参数与配置速查

全局参数（定义在 pkg/cli/root.go，所有子命令生效）：

环境变量：

cog.yaml 常用字段（完整模板见 pkg/cli/init-templates/base/cog.yaml）：

隐藏能力与进阶

• cog debug（隐藏）：只生成 Dockerfile 不构建，排查构建问题利器；加--separate-weights会分别打印权重与 runner 两份 Dockerfile 及排除规则。
• cog weights（隐藏，实验性）：import/pull/status三个子命令，把 cog.yaml 声明的权重源打包成 OCI 层、更新 weights.lock 并推送；import 会预热本地内容寻址存储，之后cog run可直接挂载权重而无需单独 pull。
• cog doctor（实验性）：诊断配置弃用字段、predict→run 迁移、Pydantic 版本等；默认只报告，--fix自动应用安全修复；存在未修复错误时返回非零退出码，方便进 CI。
• cog train（隐藏且已标记弃用）：向/trainings端点发请求，与 run 共享执行路径，-o默认输出到weights目录。
• cog playground：为运行中的 Cog HTTP API 提供浏览器原生界面，请求经本地代理转发到目标 API，也可用cog serve --playground同时拉起。
• 此外还有一个独立的base-image二进制用于维护 Cog 基础镜像，不是 cog 的子命令，见 architecture/06-cli.md。

如何自行验证上述行为

仓库的集成测试是 integration-tests/tests/ 下的 txtar 文件，文件名与本文描述的行为一一对应：

• 输入校验：input_validation_before_build.txtar、invalid_int_validation.txtar、union_input_cli.txtar
• 预测与输出：predict_json_input.txtar、predict_output_file.txtar、cancel_async_prediction.txtar
• 容器交互：exec_basic.txtar、pty_interactive.txtar、healthcheck_during_prediction.txtar
• 构建：build_openapi_schema.txtar、build_pip_freeze.txtar、torch_baseimage_fallback.txtar
• 诊断与迁移：doctor_clean_project.txtar、doctor_predict_to_run_migration.txtar

想跑真实用例，克隆源码后挑 examples/ 里任意项目（blur、resnet 等）执行cog run即可对照：

git clone https://gitcode.com/GitHub_Trending/co/cog

行为层面的说明可对照 architecture/06-cli.md，HTTP 协议见 docs/http.md。

小结

Cog CLI 把"写镜像、配环境、包接口"的琐碎收敛成几条命令，模型作者只需要写setup()和run()。想继续深入，建议从 architecture/02-schema.md 的 schema 生成与 docs/python.md 的 Runner 接口参考两条线入手。

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