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

Cog CLI 深度实战6 条命令把 Python 模型变成生产级推理容器【免费下载链接】cogContainers for machine learning项目地址: https://gitcode.com/GitHub_Trending/co/cogCog 是面向机器学习模型容器化的开源工具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 imageexamples/kodim24.png -i blur4这条命令背后发生的事构建镜像 → 启动容器 → 容器内执行setup()→ 向/predictions发请求 → 把返回的图片写回本地文件。处理完的输出就是这张带方框模糊的照片注意-i imageexamples/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 imagephoto.jpg # 4. 启动 HTTP 服务做联调 cog serve -p 8393 # 5. 登录并推送 cog login cog push r8.im/your-username/my-modelcog init从内嵌模板写出 cog.yaml、run.py、requirements.txt模板通过 Go 的 embed 直接编进二进制。cog build依次完成解析配置、静态生成 OpenAPI schema、生成 Dockerfile、构建镜像、写入 label入口在 pkg/cli/build.goDockerfile 生成在 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(descriptionGrayscale input image), scale: float Input(descriptionFactor to scale image by, ge0, le10, default1.5), ) - Path: Run the model on a single inputInput(ge0, le10, default1.5)这类约束注解会被 Cog 静态解析进 OpenAPI schema后续的输入校验就靠它。cog build构建镜像cog build -t my-model:latest cog build --no-cache --separate-weights常用参数参数默认值说明-t, --tag—镜像标签优先于 cog.yaml 的 image/model--no-cachefalse禁用 Docker 构建缓存--separate-weightsfalse权重拆到独立层便于单独上传--progressauto进度格式 auto/tty/plain/quiet--secret—构建期密钥idfoo,src/path/to/file--openapi-schema—从文件加载 schema替代静态生成--use-cuda-base-imageautoauto/trueNVIDIA CUDA/false纯 Python镜像更小--use-cog-base-imagetrue用预构建 Cog 基础镜像加快冷启动-f, --filecog.yaml配置文件路径易错点--use-cog-base-image、--use-cuda-base-image、隐藏的--dockerfile三者互斥同时设置会被checkMutuallyExclusiveFlags直接拦下。镜像命名优先级-t cog.yaml 的imagemodel 按项目目录生成的默认名。cog run本地跑一次推理cog run -i prompta cat -i steps50 cog run -i imagephoto.jpg -o out.jpg echo {prompt: a cat} | cog run --json -常用参数参数说明-i, --input namevalue可重复前缀表示本地文件-o, --output输出落盘路径多个 Path 输出依次命名name.0.ext、name.1.ext-e, --env注入容器的环境变量--json以 JSON 对象传输入支持file与 stdin 的-与-i互斥--use-replicate-token把宿主机REPLICATE_API_TOKEN传入模型上下文--setup-timeout容器 setup 超时秒数默认 300--gpus同docker run --gpus格式进阶技巧把已构建镜像名作为位置参数传入就切换到基于镜像路径——拉取镜像、优先用镜像 schema label 预校验输入label 不可用时在容器启动后再取运行时 schemacog run r8.im/your-username/my-model -i prompthello旧命令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}}参数默认值说明-p, --port8393宿主机发布端口容器内固定监听 5000--host127.0.0.1端口映射绑定地址0.0.0.0 允许外部访问--upload-url—文件输出的上传地址自动附加host.docker.internal:host-gateway--playground/--playground-port关 / 9000同时起浏览器调试界面--gpusauto同 cog run易错点访问端口不是 5000——5000 是容器内绑定端口宿主机默认是 8393。另外 serve 构建时跳过COPY . /src源码以卷挂载到/srcserveBuildOptions中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 --ip0.0.0.0 cog exec -e HUGGING_FACE_HUB_TOKENxxx python download.py参数说明-p, --publish端口发布支持8000、0.0.0.0:8000、[::1]:8000三种形式-e, --env环境变量namevalue--gpus同docker run --gpus实现细节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 registrycog 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三个值得记住的实现细节校验先于构建。schema 生成与输入校验在调用resolver.Build()之前完成输错一个参数名不会触发分钟级构建。GPU 回退。未显式传--gpus且模型声明需要 GPU 时CLI 自动以gpusall启动若 Docker 报缺设备驱动ErrMissingDeviceDriver则去掉 GPU 参数重试并提示Missing device driver, re-trying without GPU。run、serve、exec 三处都有这段逻辑。RUST_LOG 透传。宿主机设置了RUST_LOG时自动传入容器方便调试容器内 Rust 运行时coglet的日志serve/exec 还会注入LOG_FORMATconsole得到人读日志。参数与配置速查全局参数定义在 pkg/cli/root.go所有子命令生效参数说明--debug打开调试输出--no-color禁用彩色并写入NO_COLOR1--version显示版本与构建时间--profile/--registry隐藏参数性能剖析 / 覆盖 registry 主机环境变量变量作用BUILDKIT_PROGRESS覆盖--progress默认值RUST_LOG透传进容器调试 Rust 运行时REPLICATE_API_TOKEN配合--use-replicate-token传入模型上下文COG_REGISTRY_HOST覆盖 registry 主机等价于--registryTERMdumb构建进度默认退化为 plain 文本cog.yaml 常用字段完整模板见 pkg/cli/init-templates/base/cog.yaml字段说明build.gpu是否需要 GPU决定默认gpusallbuild.python_version/python_requirementsPython 版本与依赖文件build.system_packages要安装的 apt 包build.run环境就绪后执行的命令run入口形如run.py:Runnerimage/model推送目标引用push 时解析优先级 image model隐藏能力与进阶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.mdHTTP 协议见 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考