Cog CLI 完全指南容器化机器学习模型的构建、运行与部署全生命周期【免费下载链接】cogContainers for machine learning项目地址: https://gitcode.com/GitHub_Trending/co/cogCog 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复用发布到 registrycog push构建后推送到 Replicate 或任意 OCI 兼容 registry为推送做认证cog loginCI 场景支持--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 prompta photo of a cat -i steps50这条命令在背后依次经历 6 个阶段解析配置与静态生成 schema。CLI 先用 tree-sitter 静态分析模型代码的类型注解生成 OpenAPI 规范——注意这一步不需要运行你的代码pkg/schema/ 负责。输入转换与校验。-i namevalue按 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 prompthello会跳过本地构建改为拉取镜像并优先用镜像 label 里固化的 schema 做预校验label 缺失时等容器启动后从/openapi.json运行时拉取 schema 再补做校验。其余命令速览init、serve、exec、build、push、logincog init模板通过 Go 的embed.FS内嵌在二进制里pkg/cli/init-templates/所以离线也能用已存在的文件只提示Skipped existing而从不覆盖你的代码。cog buildcog 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 pushcog 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背后有三个角色协作理解它们的关系排障效率会高很多宿主机上的 CLIGo负责配置解析、schema 生成、输入校验、构建编排、Docker 操作、HTTP 通信。它从不执行模型代码。容器内的 Python SDK你import cog到的那套东西BaseRunner、Input、Path等类型随构建装进每个镜像。容器内的 Rust 运行时cogletAxum 写的 HTTP 服务器负责/health-check、/predictions、/openapi.json并把你的setup()/run()放到隔离子进程中执行崩溃不拖垮整个服务源码在 crates/coglet/。上图来自 docs/wsl2/wsl2.md展示 WSL2 环境下容器运行的资源开销——模型运行时占用多少内存、CPU在宿主机层面是可见且可控的这正是容器内运行原则的直接收益。两个容易忽略的运行时细节GPU 自动回退--gpus未显式指定而模型声明需要 GPU 时CLI 以gpusall启动若检测到缺少设备驱动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/GetSchemapkg/model/构建 / 拉取 / 推送的 OCI 工件编排resolver是枢纽pkg/provider/registry 行为抽象Replicate 与通用 OCI 两套实现pkg/weights/权重发现、weights.lock、只读挂载crates/coglet/容器内 Rust 运行时HTTP 服务 worker 子进程隔离新手容易踩的 6 个坑与排障线索输入校验发生在构建之前。输入类型或名字错了秒级报错不会白等一次构建——所以看到校验错误时先改输入别怀疑镜像。-i必须写成namevalue。漏掉会直接报expected format is namevalue把namevalue整个当位置参数传则会收到Did you forget -i?的友好提示。--json与-i不能混用。二选一混用立即报错--json -可从 stdin 读 JSON--json inputs.json读文件。文件输入必须带前缀。-i imagephoto.jpg才会读文件内容并以 data URL 上传写成-i imagephoto.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_LOGdebug运行时日志自动透传进容器环境问题用cog exec直接进容器验证接口问题用curl http://localhost:8393/openapi.json核对 schema。从零跑通 Cog CLI5 步上手路径与验证方法# 1. 克隆仓库也可以直接对已有项目跑 cog init git clone https://gitcode.com/GitHub_Trending/co/cog进入示例项目cd cog/examples/hello-world或对自己项目cog init生成cog.yamlrun.py模板。跑一次预测cog run -i prompthello。看到模型输出、终端打印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 CLICLI 不执行任何模型代码它只做编排解析 → 构建 → 启动 → 通信 → 呈现所有模型逻辑都发生在容器里的 Python SDK 与 Rust 运行时中——这正是本地实验与生产行为一致的原因。下一步可以深入 architecture/ 下的架构文档模型源码规范01、Prediction API 信封格式03、容器运行时内部04与构建系统05把这条链路彻底看透。【免费下载链接】cogContainers for machine learning项目地址: https://gitcode.com/GitHub_Trending/co/cog创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考