用途:Cog 用于把机器学习模型打包成生产可用的容器。本技能适用于涉及跨语言边界或触及核心架构的变更评审,梳理组件、设计模式与需重点关注的横切问题。
组件概览:CLI(Go)位于 cmd/cog/ 与 pkg/,负责构建、运行和部署模型;Python SDK 位于 python/cog/,提供 predictor 接口、类型与 HTTP/队列服务;Coglet(Rust)位于 crates/,是容器内的预测服务器,处理 HTTP、worker 管理与 IPC。
关键设计模式:wheel 解析方面,CLI 在 Docker 构建时从 dist/ 发现 SDK 与 coglet 的 wheel,wheel 不嵌入二进制,改动构建产物需考虑到这一点。Dockerfile 生成由 pkg/dockerfile/ 依据 cog.yaml 完成,需注意模板注入与转义。配置解析由 pkg/config/config.go 处理 cog.yaml,schema 位于 pkg/config/data/config_schema_v1.0.json,改动须保持 schema 与 Go 代码同步。coglet 为双进程结构:父进程(HTTP 服务器加编排器)与子 worker 进程(执行 Python predictor)通过 IPC 通信,改动 IPC 协议会同时影响 Rust 与 Python 代码。兼容矩阵由 tools/compatgen/ 管理 CUDA/PyTorch/TensorFlow 兼容性,框架版本变更影响面较大。
横切关注点:VERSION.txt 是版本唯一来源,Cargo.toml 必须与之匹配;改动 python/cog/base_predictor.py 会影响所有下游模型作者;改动 docs/ 需运行 mise run docs:llm 重新生成 docs/llms.txt;CLI 参考文档为自动生成,改动 cmd/ 或 pkg/cli/ 需运行 mise run docs:cli;integration-tests/ 中的集成测试使用 Go 的 testscript,且需要已构建的 cog 二进制。
需警惕:predictor 接口或 cog.yaml schema 的破坏性变更;影响层缓存或构建时间的 Docker 构建改动;只更新 Rust 或 Python 一侧的 IPC 协议改动;遗漏 VERSION.txt 需同步位置之一的版本号提升;未做兼容性测试就引入新的 ML 框架版本。