企业官网建设流程全解析

Cog：从 Python 模型代码到生产推理容器的 5 条命令链路

【免费下载链接】cogContainers for machine learning项目地址: https://gitcode.com/GitHub_Trending/co/cog

Cog 把几十行 Python 模型代码和一份cog.yaml，变成可以直接部署、可对外提供推理服务的容器镜像，它的 Go CLI（cog命令）就是本地跑模型、暴露服务、交付 registry 的主力工具。理解它之前先记住一个关键设计：模型代码永远不在宿主机上执行。所有会跑模型的命令都走同一条路径——先构建镜像、再启动容器、最后通过 HTTP 与容器内的运行时交互。CLI 是指挥家，容器才是演员。

用一条 cog init 引导出模型项目

cog init在当前目录生成一份开箱即用的项目骨架：声明运行环境的cog.yaml（Python 版本、GPU、依赖）、带Runner类的run.py，以及requirements.txt。模板通过 Go 的embed.FS内嵌在二进制里（pkg/cli/init.go 中的//go:embed init-templates/**/*），离线也能工作；对已存在的文件只提示Skipped existing ...而不覆盖，所以可以安全地在任何项目目录里重跑。这条命令的真正价值是定义了"模型项目"的形态：cog.yaml声明环境，run()方法签名上的类型注解定义模型的输入输出契约，setup()在容器启动时调用一次用于加载权重，run()则处理每个请求。构建时pkg/schema/模块用 tree-sitter 从这些注解静态生成 OpenAPI 规范，这份 schema 是后续所有输入校验、接口调试的地基。把模型逻辑写进骨架类之后，项目就齐了。

用 cog run 在本地跑一次推理

cog run是日常开发中最高频的命令，它的流程比看起来要长。实现在 pkg/cli/predict.go：先从本地源码静态生成 schema，再基于它做-i输入的类型转换与校验（pkg/predict/负责这一步）——steps给错类型会在镜像构建之前就被拦下；校验通过才调用resolver.Build()构建镜像，启动容器并轮询/health-check直到 READY，最后向/predictions发送预测请求并流式读回结果。

cog run -i prompt="a photo of a cat" -i steps=50 cog run -i image=@photo.jpg -o out.png

输入语法由 schema 决定：字符串、数字直接写；本地文件加@前缀，CLI 会把文件读出来转成 base64 data URL 传给容器；URL 原样透传。输出按类型呈现：字符串直接打印，Path结果落盘成文件，其余结构化结果以缩进 JSON 输出；预测失败时进程以非零码退出。一个值得知道的行为是 GPU 回退：未指定--gpus而模型声明了 GPU 时，CLI 自动以gpus=all启动，若因缺少设备驱动失败，会去掉 GPU 参数重试一次并提示Missing device driver, re-trying without GPU。旧的cog predict命令与此共享同一套实现，调用时会打印弃用警告。

单次推理能复现之后，下一个问题往往是环境本身：容器跑起来了，但里面的依赖和 CUDA 是不是你以为的那套？

用 cog exec 调试容器环境

cog exec就是为这个问题准备的：基于cog.yaml构建临时镜像，在容器里执行你指定的任意命令。实现在 pkg/cli/exec.go，关键手法是flags.SetInterspersed(false)——第一个参数之后的内容全部原样传给容器命令，cog侧不会截走你的-c、-m。项目目录以卷挂载到/src并设为工作目录，构建复用ExcludeSource逻辑（源码不进镜像层），因此与cog build共享 Docker 层缓存，首次运行不会太慢。

cog exec python -c "import torch; print(torch.cuda.is_available())" cog exec -e HUGGING_FACE_HUB_TOKEN=abc123 python download.py cog exec -p 8888 jupyter notebook

典型用途：验证依赖是否装齐、CUDA 是否真的可用、跑一次性脚本，或cog exec bash打开交互式 shell。-p支持8000、0.0.0.0:8000、[::1]:8000三种形式，方便跑 Jupyter 这类需要端口的服务。环境验证通过、单次推理跑通，下一步就是把模型交给前端或其他服务调用。

用 cog serve 启动本地 HTTP 服务

cog serve构建镜像、启动容器运行时并保持运行，它不解析任何预测输入。端口约定需要先澄清：容器内的 HTTP 服务固定监听 5000 端口（以python -m cog.server.http启动），宿主机默认发布到8393，所以访问地址是http://localhost:8393而不是 5000；默认绑定127.0.0.1仅本机可达，--host 0.0.0.0放开外部访问，-p改端口。

curl http://localhost:8393/predictions \ -X POST -H 'Content-Type: application/json' \ -d '{"input": {"prompt": "a cat"}}'

服务兼容 Cog HTTP 协议：POST /predictions发预测、/openapi.json看规范、/health-check查健康。cog serve还有一个实用细节：构建路径跳过COPY . /src、改为运行时卷挂载源码，改完cog.yaml或模型代码后不用重新构建镜像，重启即可。想有浏览器界面，启动时加--playground，或单独跑cog playground --target http://localhost:8393打开一个能直接调用模型 API 的 UI。另外 CLI 会自动把宿主机的RUST_LOG透传进容器，方便调容器内 Rust 运行时（coglet）的日志。

用 cog build 构建可复现镜像

cog build是唯一产出"交付物"的命令，流程六步：解析cog.yaml（pkg/config/负责解析与校验，含 CUDA/PyTorch 兼容矩阵）→ 解析 CUDA 版本 → 静态生成 schema → 生成 Dockerfile（pkg/dockerfile/）→ BuildKit 构建（pkg/docker/）→ 写入 schema、config、pip freeze 等 label。最常用的开关是-t（标签）、--no-cache（禁用缓存）、--separate-weights（权重拆到独立层，便于单独传输）；--use-cuda-base-image控制基础镜像，false用纯 Python 镜像，体积更小但非 torch 项目可能出问题。checkMutuallyExclusiveFlags会强制--use-cog-base-image、--use-cuda-base-image、--dockerfile三者互斥，同时设置多个直接报错。

cog build -t my-model:latest

镜像命名优先级：-t标签 >cog.yaml的image字段 >model字段 > 按项目目录生成的默认名。几个进阶选项一句话带过：隐藏的--dockerfile（用现成 Dockerfile 替代生成）、--timestamp（重写层时间戳做可复现构建）、--strip（剥离符号）、--precompile（预编译 Python 文件）都存在；构建失败时，隐藏命令cog debug只生成 Dockerfile 而不构建，是排查构建问题的最快入口。schema label 写进镜像后，之后针对该镜像的预测可以直接用 label 做输入预校验，不用再等容器启动。

用 cog push 与 cog login 部署到 registry

部署就是把镜像推到 registry，cog push负责全链路。实现在 pkg/cli/push.go，有一个值得强调的细节：validatePushArgs先解析目标引用，把COG_MODEL/COG_MODEL_TAG与cog.yaml中model/image配置之间的冲突当场报出——参数错误几秒内失败，而不是浪费几分钟的构建。构建之后由pkg/provider/按目标地址选择 provider：Replicate 的r8.im走 token 认证，任意 OCI 兼容 registry 走通用路径，最后resolver.Push()推送镜像及分离的权重层。推送成功会打印一棵 digest 固定的引用树（model/image/weight各行），可直接复制使用。

cog login cog push r8.im/your-username/my-model

登录目标由全局--registry参数或COG_REGISTRY_HOST环境变量控制：cog login对r8.im走 token 流程，对其他 registry 提示输入用户名/密码并写入 Docker 凭证系统；CI 场景用cog login --token-stdin < token.txt从标准输入传 token。Replicate 专属的--separate-weights推送在此生效，权重层与代码层解耦，后续更新代码不必重传权重。

CLI 是指挥家，容器是演员：一份配置、一条命令链，从代码走到生产。

【免费下载链接】cogContainers for machine learning项目地址: https://gitcode.com/GitHub_Trending/co/cog