5 个命令掌握 Cog CLI：把 Python 模型项目变成可部署的容器

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.pyRunner骨架类setup()一次性加载模型run()处理单次请求输入可带Input(description..., ge0, le10, default1.5)这类约束。实现细节值得记住见 pkg/cli/init.go模板用 Go 的//go:embed init-templates/**/*内嵌进二进制离线也能用已存在的文件一律跳过打印Skipped existing ...绝不覆盖你写过的代码AGENTS.md会优先在线拉取最新版失败时回退到内嵌版本 本地验证cog run、cog exec、cog serve 三件套你想做什么用哪条命令跑一次预测拿结果cog run -i prompta photo of a cat排查容器内依赖、CUDA 可用性cog exec python -c import torch; print(torch.cuda.is_available())起 HTTP 服务给前端或 curl 联调cog serve交互式进模型环境cog exec bashcog run 用法四类输入怎么传输出怎么读cog run在 pkg/cli/run.go 里只是极薄封装执行逻辑集中在 pkg/cli/predict.go 的cmdPredict。一次 run 的走法是静态生成 Schema或从已有镜像 label 读取→ 解析并校验-i参数 → 构建镜像仅本地源码路径→ 启动容器 → 发预测请求并把输出流式写到终端。输入类型按 Schema 推断共四种# 字符串 / 数字 cog run -i prompta cat -i steps50 # 文件 前缀CLI 读取本地文件转成 base64 data URL 上传 cog run -i imageexamples/hello-replicate/cat.png -o out.png # URL cog run -i imagehttps://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_TOKENabc123注入环境变量--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不是 5000cog 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 idfoo,src/path/to/file用文件指定 schema--openapi-schema换纯 Python 基础镜像--use-cuda-base-imagefalse镜像更小非 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 pushcog login cog push r8.im/your-username/my-model --separate-weightscog login按 registry 主机挑选 providerpkg/cli/login.gor8.im走 token 流程CI 场景可用cog login --token-stdin token.txt其他 registry 提示输入用户名密码凭证存入 Docker 的 credential 系统。主机可用全局--registry参数或COG_REGISTRY_HOST环境变量覆盖。cog pushpkg/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 runcog train——向/trainings端点发训练请求两个自愈机制值得记住GPU 驱动回退--gpus未指定而模型需要 GPU 时CLI 自动以gpusall启动若因缺设备驱动失败打印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 imageexamples/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），仅供参考