5 个命令掌握 Cog CLI：把 Python 模型项目变成可部署的容器
【免费下载链接】cogContainers for machine learning项目地址: https://gitcode.com/GitHub_Trending/co/cog
想把 Python 模型变成稳定的 API 服务，你要对付三件事：环境、依赖、入口。Cog CLI 就是这套工作的编排入口：你只需写cog.yaml和run.py，构建、起容器、推 registry 剩下的事交给它。
先立原则：Cog 从不在宿主机跑模型代码
所有会执行模型代码的命令（cog run、cog serve、cog exec）都遵循同一个节奏：先构建镜像、再启动容器、最后通过 HTTP 向容器内的 Prediction API 发请求。setup()与run()只发生在与cog.yaml声明的依赖、CUDA 版本严格一致的容器化环境里，宿主机只是编排者。三层链路如下：
还有一点值得提前知道：输入输出 Schema 是从模型源码的类型注解静态生成的（见 architecture/02-schema.md），校验在建镜像之前就完成；镜像上会把这个 schema 写成 label，之后凭镜像做校验时无需启动容器。
🚀 起步：cog init 在当前目录生成什么
cog init它会落盘两个文件：cog.yaml（带默认值的环境配置：python 版本、gpu 开关、requirements 路径等）和run.py（Runner骨架类，setup()一次性加载模型，run()处理单次请求，输入可带Input(description=..., ge=0, le=10, default=1.5)这类约束）。
实现细节值得记住（见 pkg/cli/init.go）：
- 模板用 Go 的
//go:embed init-templates/**/*内嵌进二进制，离线也能用 - 已存在的文件一律跳过，打印
Skipped existing ...，绝不覆盖你写过的代码 AGENTS.md会优先在线拉取最新版，失败时回退到内嵌版本
🧪 本地验证：cog run、cog exec、cog serve 三件套
| 你想做什么 | 用哪条命令 |
|---|---|
| 跑一次预测拿结果 | cog run -i prompt="a photo of a cat" |
| 排查容器内依赖、CUDA 可用性 | cog exec python -c "import torch; print(torch.cuda.is_available())" |
| 起 HTTP 服务给前端或 curl 联调 | cog serve |
| 交互式进模型环境 | cog exec bash |
cog run 用法：四类输入怎么传，输出怎么读
cog run在 pkg/cli/run.go 里只是极薄封装，执行逻辑集中在 pkg/cli/predict.go 的cmdPredict。一次 run 的走法是：静态生成 Schema（或从已有镜像 label 读取）→ 解析并校验-i参数 → 构建镜像（仅本地源码路径）→ 启动容器 → 发预测请求并把输出流式写到终端。输入类型按 Schema 推断，共四种：
# 字符串 / 数字 cog run -i prompt="a cat" -i steps=50 # 文件：@ 前缀，CLI 读取本地文件转成 base64 data URL 上传 cog run -i image=@examples/hello-replicate/cat.png -o out.png # URL cog run -i image=https://example.com/photo.jpg输出按类型呈现：字符串原样打印；Path或list[Path]落盘（多条时按out.0.png、out.1.png命名）；整数、浮点、布尔给原始值；列表与对象输出缩进 JSON。-o指定写入路径；预测失败时进程以非零码退出。批量输入用--json @inputs.json（@-读 stdin），与-i互斥。--setup-timeout默认 300 秒，约束容器 setup 时长。
用 cog exec 排查容器依赖
cog exec基于cog.yaml构建镜像后在其中运行你的命令。第一个参数之后的内容全部原样传给容器内命令（flags.SetInterspersed(false)保证），复杂命令的引号问题由此消失。工作目录设为/src并挂载源码目录，所以cog exec python train.py能直接看到项目文件。常用参数：
-e HUGGING_FACE_HUB_TOKEN=abc123：注入环境变量--gpus：格式同docker run --gpus-p：发布端口，支持8888（跑 Jupyter）、0.0.0.0:8000、[::1]:8000三种写法
cog serve 本地调试：记住两个端口
cog serve构建镜像后启动一个兼容 Cog HTTP 协议的 REST 服务，暴露POST /predictions、/openapi.json、/health-check三个端点。
端口约定是最容易踩的坑：容器内服务固定监听5000（进程为python -m cog.server.http），宿主机默认发布8393。所以访问地址是http://localhost:8393，不是 5000：
cog serve curl http://localhost:8393/predictions -X POST \ -H 'Content-Type: application/json' -d '{"input": {"prompt": "a cat"}}'-p 9000：改宿主机端口--host 0.0.0.0：默认127.0.0.1仅本机可达，改后允许外部访问--upload-url：文件输出的上传地址，设置后自动附加host.docker.internal:host-gateway便于容器回连宿主机
另一个优点：源码走运行时卷挂载而非COPY . /src，改cog.yaml或模型代码不用重建镜像，其余各层与cog build共享缓存（见 pkg/cli/serve.go）。
🏭 镜像生产：cog build 的六步走
cog build -t my-model:latest一次 build 按六步执行：
- 解析
cog.yaml——pkg/config/ 负责，含 CUDA/cuDNN 与 PyTorch 兼容矩阵 - 依据 pkg/config/cuda_compatibility.json 解析 CUDA 版本
- 静态生成 OpenAPI Schema——pkg/schema/ 用 tree-sitter 解析 Python 类型注解
- 生成 Dockerfile——pkg/dockerfile/standard_generator.go 同时做基础镜像选择
- 经 Docker/BuildKit 构建镜像
- 向镜像写入 schema、config、pip freeze 等 label
场景 → 开关对照：
| 场景 | 开关 |
|---|---|
| 不用构建缓存 | --no-cache |
| 权重拆到独立层单独上传 | --separate-weights |
| 控制进度格式 | --progress auto/tty/plain/quiet（环境变量BUILDKIT_PROGRESS可覆盖默认值） |
| 构建期传密钥 | --secret id=foo,src=/path/to/file |
| 用文件指定 schema | --openapi-schema |
| 换纯 Python 基础镜像 | --use-cuda-base-image=false（镜像更小，非 torch 项目可能出问题） |
| 用预构建 Cog 基础镜像加快冷启动 | --use-cog-base-image（默认 true） |
| 自带 Dockerfile / 可复现构建 / 剥符号 / 预编译 | --dockerfile、--timestamp、--strip、--precompile（均为隐藏参数） |
两条硬规则：
--use-cog-base-image、--use-cuda-base-image、--dockerfile三者互斥，同时设两个直接报错（checkMutuallyExclusiveFlags校验）- 镜像命名优先级：
-t标签 >cog.yaml的image字段 >model字段 > 基于项目目录的默认名
cog run、cog serve、cog exec、cog push共用同一套构建开关，这里讲一次，后文直接引用。
📦 发布上线：cog login 与 cog push
cog login cog push r8.im/your-username/my-model --separate-weightscog login按 registry 主机挑选 provider（pkg/cli/login.go）：r8.im走 token 流程，CI 场景可用cog login --token-stdin < token.txt；其他 registry 提示输入用户名密码，凭证存入 Docker 的 credential 系统。主机可用全局--registry参数或COG_REGISTRY_HOST环境变量覆盖。
cog push（pkg/cli/push.go）分四步：
validatePushArgs先行校验——COG_MODEL/COG_MODEL_TAG与cog.yaml里model/image设置的冲突在耗时数分钟的构建前几秒内报出- 走与
cog build相同的构建路径 provider.DefaultRegistry().ForImage(target)选定 Replicate 或通用 OCI 实现（pkg/provider/）resolver.Push()推送镜像及分离的权重层；成功后 provider 负责错误格式化与模型 URL 输出，CLI 打印 digest 固定的引用树：model/image/weight各行，可直接复制
构建开关沿用 build 一节（--no-cache、--secret、--use-cuda-base-image等），不再重复。--separate-weights是 Replicate 专属能力：权重层独立推送，权重未变时无需重传整个镜像。
🛠️ 出问题时：隐藏命令与自愈机制
cog --help只展示了一部分命令，以下命令存在但隐藏：
cog debug——只生成并打印 Dockerfile 不实际构建（pkg/cli/debug.go），适合排查基础镜像与层的问题cog weights——实验性权重管理，含import/pull/status：把cog.yaml中的权重源打包为 OCI 层、更新weights.lock并推送 registry，之后cog run可直接挂载权重cog predict——旧预测命令，等价于cog run且支持直接指定已构建镜像，调用时打印"cog predict" is deprecated, use "cog run"cog train——向/trainings端点发训练请求
两个自愈机制值得记住：
- GPU 驱动回退：
--gpus未指定而模型需要 GPU 时，CLI 自动以gpus=all启动；若因缺设备驱动失败，打印Missing device driver, re-trying without GPU并去掉 GPU 参数重试。run、serve、exec 三处逻辑一致 - RUST_LOG 透传：宿主机设了
RUST_LOG会自动注入容器，方便调试容器内 Rust coglet 的日志
仓库 integration-tests/tests/ 用 txtar 格式覆盖了这些 CLI 行为。想核对上文流程可看：input_validation_before_build.txtar证明输入校验发生在构建之前，doctor_predict_to_run_migration.txtar覆盖旧 predict 向 run 的迁移，union_input_cli.txtar覆盖联合类型输入。
幕后机制：CLI 与容器如何协作
本地源码预测的完整时序：
容器内部的进程间通信细节见 architecture/04-container-runtime.md。入口 cmd/cog/cog.go 很薄：创建根命令后Execute()，错误统一交给console.Fatalf。根命令（pkg/cli/root.go）注册全部子命令，PersistentPreRun处理--debug日志级别、--no-color（同时写入NO_COLOR环境变量）与版本更新检查；cobra.EnableTraverseRunHooks保证根→子的钩子顺序执行。
源码地图按职责分三组：
- 核心：pkg/cli/（Cobra 命令定义）、pkg/config/（cog.yaml 解析与兼容矩阵）、pkg/image/（构建编排）、pkg/dockerfile/（Dockerfile 生成与基础镜像选择）、pkg/docker/（Docker 客户端）、pkg/predict/（预测执行与 input.go 输入转换）、pkg/schema/（静态 Schema）、pkg/wheels/（SDK 与 coglet wheel 解析）
- 基础设施：pkg/provider/（registry 行为抽象）、pkg/registry/（OCI registry 客户端）、pkg/model/（OCI 工件领域模型，含 resolver.go 的构建/拉取编排）、pkg/weights/（权重发现与 lockfile）、pkg/errors/（带错误码的 CodedError）
- 工具：pkg/dotcog/（
.cog/状态目录）、pkg/requirements/（requirements.txt 解析）、pkg/util/（控制台、MIME、版本）、pkg/update/（版本更新检查）、pkg/global/（进程级配置）
下一步验证
与其相信文章，不如亲手跑通：
- 空目录里执行
cog init，对照检查生成的cog.yaml与run.py - 在 examples/blur/ 下跑
cog run -i image=@examples/blur/examples/kodim24.png，或改用cog serve后curl http://localhost:8393/openapi.json - 浏览 integration-tests/ 的 txtar 用例与其
harness/目录，看集成测试如何驱动各命令 - 阅读源码调用链：入口 architecture/06-cli.md，再顺 architecture/03-prediction-api.md 与 architecture/04-container-runtime.md 深入
【免费下载链接】cogContainers for machine learning项目地址: https://gitcode.com/GitHub_Trending/co/cog
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
