Cog CLI 完全指南：容器化机器学习模型的构建、运行与部署全生命周期
【免费下载链接】cogContainers for machine learning项目地址: https://gitcode.com/GitHub_Trending/co/cog
Cog CLI是一个用 Go 编写的命令行工具，专为容器化机器学习模型设计，一条命令链覆盖从项目初始化、本地调试、镜像构建到推送部署的完整生命周期。它最关键的设计原则只有一句话：模型代码永远在容器内运行，CLI 只做编排——你写的setup()、run()从不直接跑在宿主机上，而是先构建镜像、再启动容器、最后通过 HTTP 与容器内的运行时通信。这保证了本地跑通的环境与生产环境严格一致。
一张表看懂 Cog CLI：我想做什么，该用哪条命令
不用背参数，先建立"场景 → 命令"的直觉。所有命令都在根命令中统一注册（pkg/cli/root.go），下表覆盖日常全部场景：
| 我想做什么 | 用哪条命令 | 一句话说明 |
|---|---|---|
| 从零开始一个模型项目 | cog init | 在当前目录生成cog.yaml+ 骨架run.py |
| 在容器里跑一次预测 | cog run | 构建镜像、启动容器、发一次预测请求后退出 |
| 调试容器环境 / 跑一次性脚本 | cog exec | 例如cog exec bash直接进 shell |
| 启动本地 HTTP 服务供联调 | cog serve | 不解析任何预测输入，只构建并保持服务运行 |
| 只构建 Docker 镜像 | cog build | 产物可本地运行，也可推送给cog run复用 |
| 发布到 registry | cog push | 构建后推送到 Replicate 或任意 OCI 兼容 registry |
| 为推送做认证 | cog login | CI 场景支持--token-stdin从标准输入读 token |
| 项目"体检" | cog doctor | 检查废弃字段、废弃导入、配置问题并给修复建议 |
| 在浏览器里交互试模型 | cog serve --playground | 随 serve 一起启动可视化试玩页 |
两条最容易混淆的边界：
cog runvscog serve：前者是"一次性"的——发完一个预测请求就停掉容器；后者是"常驻"的——进程挂着等待任意多请求，供 curl、Postman 或其他服务调用。cog runvscog exec：前者走 Prediction API 执行模型预测；后者不碰预测，直接在容器里运行你指定的任意命令，适合验证依赖和 GPU 是否可用。
深度拆解cog run：从-i参数到容器输出的完整管线
cog run是整个 CLI 的心脏，值得完整跟一遍内部调用链（实现集中在 pkg/cli/predict.go 与 pkg/predict/）。
cog run -i prompt="a photo of a cat" -i steps=50这条命令在背后依次经历 6 个阶段：
- 解析配置与静态生成 schema。CLI 先用 tree-sitter 静态分析模型代码的类型注解，生成 OpenAPI 规范——注意这一步不需要运行你的代码（pkg/schema/ 负责）。
- 输入转换与校验。
-i name=value按 schema 做类型转换；值以@开头表示本地文件，CLI 读取后转成 base64 data URL 上传。字符串、数字、文件、URL 四种形态都支持。 - 构建镜像。这里有个省时间的细节：
run/serve/exec共享一条"排除源码"的构建路径，镜像里不做COPY . /src，改为运行时把项目目录卷挂载到/src——所以改run.py后再次运行通常只需秒级启动，不必重建镜像。 - 启动容器并等待就绪。容器内 HTTP 服务固定监听 5000 端口，CLI 随机映射宿主机端口后，每 100ms 轮询一次
/health-check，直到状态从STARTING变为READY；--setup-timeout默认 300 秒，超时即失败。 - 发送预测请求。
predictor.Predict向/predictions发一个固定信封结构的请求（详见 architecture/03-prediction-api.md），响应 422 时 CLI 会把每个输入字段的校验错误逐条列出并附修正示例。 - 按类型呈现输出。字符串原样打印；
Path类型写为文件，list[Path]按name.0.ext、name.1.ext依次命名；整数、浮点、布尔以原始值输出，列表与对象输出缩进 JSON。预测失败时进程以非零码退出。
上面两张图来自 examples/resnet/：一张输入图片进，一个分类结果出——这就是cog run的完整输入输出闭环。
直接对已有镜像预测：cog run r8.im/your-username/my-model -i prompt="hello"会跳过本地构建，改为拉取镜像，并优先用镜像 label 里固化的 schema 做预校验；label 缺失时，等容器启动后从/openapi.json运行时拉取 schema 再补做校验。
其余命令速览：init、serve、exec、build、push、login
cog init：模板通过 Go 的embed.FS内嵌在二进制里（pkg/cli/init-templates/），所以离线也能用；已存在的文件只提示Skipped existing而从不覆盖你的代码。cog build：cog build -t my-model:latest构建镜像。镜像名优先级为-t标签 >cog.yaml的image字段 >model字段 > 按目录生成的默认名。--no-cache禁用缓存，--separate-weights把权重分离到独立镜像层。cog serve：构建后启动python -m cog.server.http常驻服务，宿主机默认发布8393端口（容器内固定 5000），启动即打印Serving at http://localhost:8393。起服务后可以直接用curl http://localhost:8393/predictions -X POST -d '{"input":{"prompt":"a cat"}}'联调，/openapi.json看规范，/health-check查状态。cog exec：第一个参数之后的内容原样透传给容器内命令（cog exec python -c "import torch; print(torch.cuda.is_available())"）。-p发布端口（跑 Jupyter 常用），-e注入环境变量，工作目录天然就是项目目录。cog push：cog push r8.im/your-username/my-model构建并推送。值得注意它先解析目标引用再开始构建，配置冲突几秒内就能报错，而不是浪费几分钟构建后才告诉你推哪失败了；推送成功后会以树状结构打印 digest 固定的model/image/weight引用，直接可复制。cog login：对 Replicate 的r8.im走 token 认证；其他 registry 提示输入用户名密码，凭证交给 Docker 的 credential 系统保存。- 不常挂在嘴边的命令：
cog train向/trainings端点发训练请求（与run同构）；cog playground独立启动试玩页；隐藏的cog debug只生成 Dockerfile 不构建，排查构建问题很 handy。旧命令cog predict已弃用，调用时会提示改用cog run。
CLI 与容器运行时的协作机制：三个角色如何分工
一次cog run背后有三个角色协作，理解它们的关系，排障效率会高很多：
- 宿主机上的 CLI（Go）：负责配置解析、schema 生成、输入校验、构建编排、Docker 操作、HTTP 通信。它从不执行模型代码。
- 容器内的 Python SDK：你
import cog到的那套东西（BaseRunner、Input、Path等类型），随构建装进每个镜像。 - 容器内的 Rust 运行时（coglet）：Axum 写的 HTTP 服务器，负责
/health-check、/predictions、/openapi.json，并把你的setup()/run()放到隔离子进程中执行，崩溃不拖垮整个服务（源码在 crates/coglet/）。
上图来自 docs/wsl2/wsl2.md，展示 WSL2 环境下容器运行的资源开销——模型运行时占用多少内存、CPU，在宿主机层面是可见且可控的，这正是"容器内运行"原则的直接收益。
两个容易忽略的运行时细节：
- GPU 自动回退：
--gpus未显式指定而模型声明需要 GPU 时，CLI 以gpus=all启动；若检测到缺少设备驱动（docker.ErrMissingDeviceDriver），会自动去掉 GPU 参数重试，并打印Missing device driver, re-trying without GPU。serve、exec有同样的回退逻辑。 RUST_LOG透传：宿主机设置了RUST_LOG时会自动传入容器，方便调试容器内 Rust 运行时的日志，无需任何额外参数。
模块职责对照——代码读起来不迷路：
| 模块 | 职责 |
|---|---|
| pkg/cli/ | Cobra 命令定义层：参数解析 + 流程编排，不含业务逻辑 |
| pkg/config/ | cog.yaml解析与校验，CUDA / PyTorch 兼容矩阵 |
| pkg/schema/ | 基于 tree-sitter 从类型注解静态生成 OpenAPI 规范 |
| pkg/dockerfile/ | 生成 Dockerfile、选择基础镜像（CUDA / 纯 Python / Cog 预构建） |
| pkg/docker/ | Docker / BuildKit 客户端封装：构建、运行、端口、日志 |
| pkg/predict/ | 容器生命周期：启动、健康检查轮询、Predict/GetSchema |
| pkg/model/ | 构建 / 拉取 / 推送的 OCI 工件编排（resolver是枢纽） |
| pkg/provider/ | registry 行为抽象：Replicate 与通用 OCI 两套实现 |
| pkg/weights/ | 权重发现、weights.lock、只读挂载 |
| crates/coglet/ | 容器内 Rust 运行时：HTTP 服务 + worker 子进程隔离 |
新手容易踩的 6 个坑与排障线索
- 输入校验发生在构建之前。输入类型或名字错了，秒级报错，不会白等一次构建——所以看到校验错误时先改输入，别怀疑镜像。
-i必须写成name=value。漏掉=会直接报expected format is 'name=value'；把name=value整个当位置参数传，则会收到Did you forget -i?的友好提示。--json与-i不能混用。二选一，混用立即报错；--json @-可从 stdin 读 JSON，--json @inputs.json读文件。- 文件输入必须带
@前缀。-i image=@photo.jpg才会读文件内容并以 data URL 上传；写成-i image=photo.jpg，字符串会被当作 URL 处理。 cog serve默认只监听 127.0.0.1。局域网或远程机器访问不到时，加--host 0.0.0.0；端口冲突则换-p。另外注意默认访问地址是http://localhost:8393而非 5000——5000 是容器内部端口。- "能跑起来"不代表用对了 GPU。没有驱动的机器上模型会静默降级到 CPU（见上文的自动回退），日志里的
re-trying without GPU值得留意；在 WSL2 上用 GPU 则需先装 NVIDIA 驱动，参考 docs/wsl2/wsl2.md。
排障三板斧：
--debug（全局参数）打开调试日志，--profile做性能剖析；- 宿主机
export RUST_LOG=debug，运行时日志自动透传进容器； - 环境问题用
cog exec直接进容器验证，接口问题用curl http://localhost:8393/openapi.json核对 schema。
从零跑通 Cog CLI：5 步上手路径与验证方法
# 1. 克隆仓库（也可以直接对已有项目跑 cog init） git clone https://gitcode.com/GitHub_Trending/co/cog- 进入示例项目：
cd cog/examples/hello-world（或对自己项目cog init生成cog.yaml+run.py模板）。 - 跑一次预测：
cog run -i prompt="hello"。看到模型输出、终端打印Written output to: ...（文件型输出时），说明"构建 → 启动 → 通信 → 呈现"链路全通。 - 验证环境：
cog exec python -c "import torch; print(torch.cuda.is_available())"，确认依赖和 GPU 状态符合预期。 - 起服务自测：
cog serve，另开终端curl http://localhost:8393/health-check，返回READY即就绪；再向/predictions发一个 POST 验证完整 API。 - 构建与推送：
cog build -t my-model确认镜像可独立构建；推送前先cog login，再cog push r8.im/your-username/my-model，成功后检查终端打印的 digest 固定引用。
如何确认自己"用对了"？仓库的 integration-tests/tests/ 目录用 txtar 格式覆盖了上百个 CLI 场景——例如input_validation_before_build印证"校验先于构建"、union_input_cli印证输入解析行为、build_openapi_schema印证构建产物——对照这些用例阅读命令行为，是最快的验证方式。
收尾：一句话记住 Cog CLI
CLI 不执行任何模型代码，它只做编排：解析 → 构建 → 启动 → 通信 → 呈现，所有模型逻辑都发生在容器里的 Python SDK 与 Rust 运行时中——这正是本地实验与生产行为一致的原因。下一步可以深入 architecture/ 下的架构文档：模型源码规范（01）、Prediction API 信封格式（03）、容器运行时内部（04）与构建系统（05），把这条链路彻底看透。
【免费下载链接】cogContainers for machine learning项目地址: https://gitcode.com/GitHub_Trending/co/cog
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
