尧图网站建设 
使用 Cog 打包 Z-Image-Turbo生成式图像模型的端到端部署实践【免费下载链接】cogContainers for machine learning项目地址: https://gitcode.com/GitHub_Trending/co/cogZ-Image-Turbo 是通义实验室Tongyi-MAI发布的快速文本生成图像text-to-image模型本仓库的examples/z-image-turbo示例展示了如何用 Cog 将这类生成式模型完整封装为可复现、可移植的容器化服务。本文以该示例的 README.md 为骨架逐一拆解其配置文件、依赖清单与 Runner 实现并结合本仓库的 Cog 源码python/cog/predictor.py、pkg/cli/predict.go等说明底层机制帮助你掌握用 Cog 打包任意生成式模型的通用套路写完这份示例你就能从零开始把任意 Diffusers 图像模型跑成一条cog predict/cog run命令或一个 HTTP 服务。示例概览一个最小可运行的生成式图像模型examples/z-image-turbo是整个仓库 examples 目录 中面向生成式模型generative models的示范项目。与resnet图像分类等判别式示例不同它演示的是 Cog 对输入一句 prompt、输出一张图片这类生成式工作负载的支持方式。整个示例只包含三个文件examples/z-image-turbo/ ├── README.md # 一句话说明 运行命令 ├── cog.yaml # 容器构建与运行配置 ├── requirements.txt # Python 依赖 └── run.py # Runner 实现模型加载与推理原文档给出的核心使用方式只有一行命令$ cog predict -i prompta cat with a hat运行后 Cog 会自动完成构建镜像 → 启动容器 → 执行setup()加载模型 → 执行run()生成图像 → 返回 PNG 文件的完整流程。接下来我们逐层剖析这背后每个文件的职责。cog.yamlGPU 构建与运行入口配置cog.yaml 是整个项目的构建契约全文如下build: gpu: true python_version: 3.13 python_requirements: requirements.txt run: run.py:Runner对照仓库中的 cog.yaml 参考文档可以逐字段理解它的含义build.gpu: true声明该模型需要 GPU。启用后 Cog 会使用 nvidia-docker 基础镜像并根据 Python / PyTorch / TensorFlow 版本自动匹配 CUDA 与 cuDNN 版本。在使用cog exec或cog run时Cog 会自动向 Docker 传递--gpusall参数这一逻辑在 pkg/cli/predict.go 中有体现当gpus为空且模型声明HasGPU()时自动置为all。build.python_version: 3.13指定容器内使用的 Python 主版本。Cog 支持 Python 3.103.13未指定时会自动选用与 PyTorch/TensorFlow 兼容的版本。build.python_requirements: requirements.txt声明 pip 依赖清单。python_requirements与已废弃的python_packages二选一需要配置--extra-index-url、--trusted-host等选项时优先使用前者。run: run.py:Runner运行入口指向run.py中的Runner类。这是新版 Cog 的推荐写法旧字段predict:仍兼容但已废弃对应 SDK 中的BaseRunner契约详见下文。如果你希望自定义镜像名例如推送到自有 registry可以在cog.yaml中追加image:字段例如image: registry.example.com/your-name/z-image-turbo不设置时 Cog 会用目录名自动生成镜像名。requirements.txt固定图像生成依赖栈requirements.txt 内容如下diffusers0.38.0 transformers5.5.0 torch2.13.0三个依赖共同构成了图像生成的最小技术栈diffusersHugging Face 的扩散模型库提供ZImagePipeline管线run.py中直接使用。transformers为文本编码器text encoder提供模型与分词支持。torch深度学习后端示例中模型以torch.bfloat16精度加载并迁移到 CUDA。使用精确版本号锁定是本示例刻意为之的做法这保证了在任何机器、任何时间构建得到的镜像内容一致这正是 Cog 强调的可复现性reproducibility的核心。生产实践中还可以在该文件中追加本地 wheel 或 git 引用依赖详见 docs/yaml.md 的 python_requirements 小节。run.py基于 BaseRunner 实现图像生成run.py 是模型逻辑的核心完整代码如下import os os.environ[HF_HUB_CACHE] ./.cache os.environ[HF_XET_HIGH_PERFORMANCE] 1 import tempfile import torch from diffusers import ZImagePipeline from cog import BaseRunner, Path class Runner(BaseRunner): def setup(self) - None: self.model ZImagePipeline.from_pretrained( Tongyi-MAI/Z-Image-Turbo, torch_dtypetorch.bfloat16, low_cpu_mem_usageFalse, ) self.model.to(cuda) def run(self, prompt: str) - Path: image self.model( promptprompt, height1024, width1024, num_inference_steps9, # This actually results in 8 DiT forwards guidance_scale0.0, # Guidance should be 0 for the Turbo models generatortorch.Generator(cuda).manual_seed(42), ).images[0] with tempfile.NamedTemporaryFile(suffix.png, deleteFalse) as f: output_path Path(f.name) image.save(output_path) return output_pathsetup()一次性加载模型setup()在容器启动时被调用一次用于完成耗时的模型加载通过HF_HUB_CACHE将 Hugging Face Hub 的模型缓存指向容器内./.cache目录方便后续复用与镜像分层缓存开启HF_XET_HIGH_PERFORMANCE以使用 Hugging Face 的 xet 高带宽下载用ZImagePipeline.from_pretrained(Tongyi-MAI/Z-Image-Turbo, torch_dtypetorch.bfloat16, ...)加载管线再.to(cuda)迁移到 GPU。从 SDK 源码看BaseRunner.setup()的默认实现为空但签名已预留weights参数参见 python/cog/predictor.py用于支持托管权重managed weights场景——即模型权重由平台管理、运行时注入而非打进镜像。本示例直接使用 Hugging Face 仓库名属于权重内嵌镜像的简单路线。run()单次推理并返回文件run()在每次预测请求时执行输入输出完全由方法签名决定输入prompt: str输出Path。几个关键推理参数值得注意num_inference_steps9Z-Image-Turbo 是蒸馏distilled加速模型注释明确指出 9 步实际只对应 8 次 DiTDiffusion Transformer前向传播采样速度远快于常规扩散模型。guidance_scale0.0Turbo 系列模型在训练时已内置引导guidance推理时必须置 0否则会破坏生成质量。这是移植 Turbo 系模型时最常见的踩坑点。generatortorch.Generator(cuda).manual_seed(42)固定随机种子保证同一 prompt 可复现同一张图便于调试与对比。输出尺寸固定为1024×1024这是模型的推荐分辨率。输出用 cog.Path 表示文件run()的返回类型标注为cog.Path。这是 Cog SDK 提供的文件类型定义在 python/cog/types.py它不仅兼容pathlib.Path的全部语义还能自动处理 URL/data URI 输入并且是 Cog 识别文件输出的信号——CLI 与 HTTP 层会据此把文件转换为可下载的 URI 而非原始字节。实现上示例先将PIL.Image保存到临时 PNG 文件再以Path(f.name)包装返回Cog 运行时会负责把容器内的文件拷贝/传输回宿主机。BaseRunner 与 predict() 的演进关系本示例使用BaseRunnerrun()的新式接口。仓库源码 python/cog/predictor.py 显示BasePredictor目前仅是BaseRunner的兼容别名且predict()已被标记为废弃DeprecationWarning。Cog 会在类校验阶段检查run()与predict()不能同时定义二者至少定义一个。因此新项目应统一使用Runnerrun()写法与cog.yaml中的run:字段保持一致。本地运行与结果输出直接使用原文档命令进入示例目录后原文档给出的命令即可运行$ cog predict -i prompta cat with a hatCog 会依次完成根据cog.yaml构建 Docker 镜像安装 Python 3.13、pip 依赖、打包run.py→ 启动容器并执行setup()加载约数 GB 的模型权重 → 调用run()生成图片 → 将输出文件写入当前目录。推荐命令cog run从源码 pkg/cli/predict.go 可以看到cog predict已被官方标记为废弃cog predict is deprecated, use cog run两者共享同一套实现newPredictionCommand。新代码建议使用cog run功能完全一致# 基础用法等价于原文档命令 $ cog run -i prompta cat with a hat # 显式指定输出文件路径 $ cog run -i prompta cat with a hat -o output.png # 多输入本示例 run() 仅有一个 prompt 参数 $ cog run -i prompta rocket ship -o rocket.png # 以 JSON 传入输入 $ echo {prompt: a cat with a hat} | cog run --json --o output.png会将生成的 PNG 直接写到指定路径CLI 依据 OpenAPI schema 识别到输出类型为文件URI后自动落盘对应 pkg/cli/predict.go 中的processFileOutputs逻辑。若输出类型是字符串或 JSON则直接打印到 stdout。指定 GPUcog.yaml声明了gpu: true因此cog run/cog predict会自动传递--gpusall。如需精确控制可手动追加$ cog run --gpus 0 -i prompta cat with a hat从单次预测到 HTTP 服务如果想让 Z-Image-Turbo 提供 API 服务cog serve会在不修改任何代码的情况下根据run()签名自动生成 OpenAPI schema 并启动兼容 Cog HTTP 协议的服务详见 docs/cli.md 的 serve 小节$ cog serve默认监听127.0.0.1:8393可用 curl 直接调用$ curl http://localhost:8393/predictions \ -X POST \ -H Content-Type: application/json \ -d {input: {prompt: a cat with a hat}}响应中的output字段会给出生成图片的可访问 URL文件输出自动经上传/传输通道对外暴露。这意味着从一条 CLI 命令到一个图像生成 API之间只需要切换子命令模型代码零改动。小结从示例到你自己的生成式模型examples/z-image-turbo虽然只有几十行代码却完整覆盖了 Cog 打包生成式模型的全部关键环节可抽象为通用四步法cog.yaml声明gpu: true、锁定 Python 版本与依赖文件、指定run: xxx.py:Runnerrequirements.txt用精确锁定 diffusers / transformers / torch 等依赖Runner类setup()中一次性加载管线注意 Turbo 系模型guidance_scale0等推理细节run()中接收类型化输入、返回cog.Path文件运行本地用cog run -i ...调试上线用cog serve或cog push部署。把ZImagePipeline换成 Stable Diffusion、Flux 或任何 Diffusers 管线参数稍作调整即可快速复用到其他生成式模型项目上。更多示例流式文本、训练接口、托管权重等见 examples 总览配置字段的完整说明见 cog.yaml 参考CLI 全量命令见 CLI 参考Python SDK 用法见 Python API 文档。【免费下载链接】cogContainers for machine learning项目地址: https://gitcode.com/GitHub_Trending/co/cog创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 使用 Cog 打包 Z-Image-Turbo：生成式图像模型的端到端部署实践
使用 Cog 打包 Z-Image-Turbo生成式图像模型的端到端部署实践【免费下载链接】cogContainers for machine learning项目地址: https://gitcode.com/GitHub_Trending/co/cogZ-Image-Turbo 是通义实验室Tongyi-MAI发布的快速文本生成图像text-to-image模型本仓库的examples/z-image-turbo示例展示了如何用 Cog 将这类生成式模型完整封装为可复现、可移植的容器化服务。本文以该示例的 README.md 为骨架逐一拆解其配置文件、依赖清单与 Runner 实现并结合本仓库的 Cog 源码python/cog/predictor.py、pkg/cli/predict.go等说明底层机制帮助你掌握用 Cog 打包任意生成式模型的通用套路写完这份示例你就能从零开始把任意 Diffusers 图像模型跑成一条cog predict/cog run命令或一个 HTTP 服务。示例概览一个最小可运行的生成式图像模型examples/z-image-turbo是整个仓库 examples 目录 中面向生成式模型generative models的示范项目。与resnet图像分类等判别式示例不同它演示的是 Cog 对输入一句 prompt、输出一张图片这类生成式工作负载的支持方式。整个示例只包含三个文件examples/z-image-turbo/ ├── README.md # 一句话说明 运行命令 ├── cog.yaml # 容器构建与运行配置 ├── requirements.txt # Python 依赖 └── run.py # Runner 实现模型加载与推理原文档给出的核心使用方式只有一行命令$ cog predict -i prompta cat with a hat运行后 Cog 会自动完成构建镜像 → 启动容器 → 执行setup()加载模型 → 执行run()生成图像 → 返回 PNG 文件的完整流程。接下来我们逐层剖析这背后每个文件的职责。cog.yamlGPU 构建与运行入口配置cog.yaml 是整个项目的构建契约全文如下build: gpu: true python_version: 3.13 python_requirements: requirements.txt run: run.py:Runner对照仓库中的 cog.yaml 参考文档可以逐字段理解它的含义build.gpu: true声明该模型需要 GPU。启用后 Cog 会使用 nvidia-docker 基础镜像并根据 Python / PyTorch / TensorFlow 版本自动匹配 CUDA 与 cuDNN 版本。在使用cog exec或cog run时Cog 会自动向 Docker 传递--gpusall参数这一逻辑在 pkg/cli/predict.go 中有体现当gpus为空且模型声明HasGPU()时自动置为all。build.python_version: 3.13指定容器内使用的 Python 主版本。Cog 支持 Python 3.103.13未指定时会自动选用与 PyTorch/TensorFlow 兼容的版本。build.python_requirements: requirements.txt声明 pip 依赖清单。python_requirements与已废弃的python_packages二选一需要配置--extra-index-url、--trusted-host等选项时优先使用前者。run: run.py:Runner运行入口指向run.py中的Runner类。这是新版 Cog 的推荐写法旧字段predict:仍兼容但已废弃对应 SDK 中的BaseRunner契约详见下文。如果你希望自定义镜像名例如推送到自有 registry可以在cog.yaml中追加image:字段例如image: registry.example.com/your-name/z-image-turbo不设置时 Cog 会用目录名自动生成镜像名。requirements.txt固定图像生成依赖栈requirements.txt 内容如下diffusers0.38.0 transformers5.5.0 torch2.13.0三个依赖共同构成了图像生成的最小技术栈diffusersHugging Face 的扩散模型库提供ZImagePipeline管线run.py中直接使用。transformers为文本编码器text encoder提供模型与分词支持。torch深度学习后端示例中模型以torch.bfloat16精度加载并迁移到 CUDA。使用精确版本号锁定是本示例刻意为之的做法这保证了在任何机器、任何时间构建得到的镜像内容一致这正是 Cog 强调的可复现性reproducibility的核心。生产实践中还可以在该文件中追加本地 wheel 或 git 引用依赖详见 docs/yaml.md 的 python_requirements 小节。run.py基于 BaseRunner 实现图像生成run.py 是模型逻辑的核心完整代码如下import os os.environ[HF_HUB_CACHE] ./.cache os.environ[HF_XET_HIGH_PERFORMANCE] 1 import tempfile import torch from diffusers import ZImagePipeline from cog import BaseRunner, Path class Runner(BaseRunner): def setup(self) - None: self.model ZImagePipeline.from_pretrained( Tongyi-MAI/Z-Image-Turbo, torch_dtypetorch.bfloat16, low_cpu_mem_usageFalse, ) self.model.to(cuda) def run(self, prompt: str) - Path: image self.model( promptprompt, height1024, width1024, num_inference_steps9, # This actually results in 8 DiT forwards guidance_scale0.0, # Guidance should be 0 for the Turbo models generatortorch.Generator(cuda).manual_seed(42), ).images[0] with tempfile.NamedTemporaryFile(suffix.png, deleteFalse) as f: output_path Path(f.name) image.save(output_path) return output_pathsetup()一次性加载模型setup()在容器启动时被调用一次用于完成耗时的模型加载通过HF_HUB_CACHE将 Hugging Face Hub 的模型缓存指向容器内./.cache目录方便后续复用与镜像分层缓存开启HF_XET_HIGH_PERFORMANCE以使用 Hugging Face 的 xet 高带宽下载用ZImagePipeline.from_pretrained(Tongyi-MAI/Z-Image-Turbo, torch_dtypetorch.bfloat16, ...)加载管线再.to(cuda)迁移到 GPU。从 SDK 源码看BaseRunner.setup()的默认实现为空但签名已预留weights参数参见 python/cog/predictor.py用于支持托管权重managed weights场景——即模型权重由平台管理、运行时注入而非打进镜像。本示例直接使用 Hugging Face 仓库名属于权重内嵌镜像的简单路线。run()单次推理并返回文件run()在每次预测请求时执行输入输出完全由方法签名决定输入prompt: str输出Path。几个关键推理参数值得注意num_inference_steps9Z-Image-Turbo 是蒸馏distilled加速模型注释明确指出 9 步实际只对应 8 次 DiTDiffusion Transformer前向传播采样速度远快于常规扩散模型。guidance_scale0.0Turbo 系列模型在训练时已内置引导guidance推理时必须置 0否则会破坏生成质量。这是移植 Turbo 系模型时最常见的踩坑点。generatortorch.Generator(cuda).manual_seed(42)固定随机种子保证同一 prompt 可复现同一张图便于调试与对比。输出尺寸固定为1024×1024这是模型的推荐分辨率。输出用 cog.Path 表示文件run()的返回类型标注为cog.Path。这是 Cog SDK 提供的文件类型定义在 python/cog/types.py它不仅兼容pathlib.Path的全部语义还能自动处理 URL/data URI 输入并且是 Cog 识别文件输出的信号——CLI 与 HTTP 层会据此把文件转换为可下载的 URI 而非原始字节。实现上示例先将PIL.Image保存到临时 PNG 文件再以Path(f.name)包装返回Cog 运行时会负责把容器内的文件拷贝/传输回宿主机。BaseRunner 与 predict() 的演进关系本示例使用BaseRunnerrun()的新式接口。仓库源码 python/cog/predictor.py 显示BasePredictor目前仅是BaseRunner的兼容别名且predict()已被标记为废弃DeprecationWarning。Cog 会在类校验阶段检查run()与predict()不能同时定义二者至少定义一个。因此新项目应统一使用Runnerrun()写法与cog.yaml中的run:字段保持一致。本地运行与结果输出直接使用原文档命令进入示例目录后原文档给出的命令即可运行$ cog predict -i prompta cat with a hatCog 会依次完成根据cog.yaml构建 Docker 镜像安装 Python 3.13、pip 依赖、打包run.py→ 启动容器并执行setup()加载约数 GB 的模型权重 → 调用run()生成图片 → 将输出文件写入当前目录。推荐命令cog run从源码 pkg/cli/predict.go 可以看到cog predict已被官方标记为废弃cog predict is deprecated, use cog run两者共享同一套实现newPredictionCommand。新代码建议使用cog run功能完全一致# 基础用法等价于原文档命令 $ cog run -i prompta cat with a hat # 显式指定输出文件路径 $ cog run -i prompta cat with a hat -o output.png # 多输入本示例 run() 仅有一个 prompt 参数 $ cog run -i prompta rocket ship -o rocket.png # 以 JSON 传入输入 $ echo {prompt: a cat with a hat} | cog run --json --o output.png会将生成的 PNG 直接写到指定路径CLI 依据 OpenAPI schema 识别到输出类型为文件URI后自动落盘对应 pkg/cli/predict.go 中的processFileOutputs逻辑。若输出类型是字符串或 JSON则直接打印到 stdout。指定 GPUcog.yaml声明了gpu: true因此cog run/cog predict会自动传递--gpusall。如需精确控制可手动追加$ cog run --gpus 0 -i prompta cat with a hat从单次预测到 HTTP 服务如果想让 Z-Image-Turbo 提供 API 服务cog serve会在不修改任何代码的情况下根据run()签名自动生成 OpenAPI schema 并启动兼容 Cog HTTP 协议的服务详见 docs/cli.md 的 serve 小节$ cog serve默认监听127.0.0.1:8393可用 curl 直接调用$ curl http://localhost:8393/predictions \ -X POST \ -H Content-Type: application/json \ -d {input: {prompt: a cat with a hat}}响应中的output字段会给出生成图片的可访问 URL文件输出自动经上传/传输通道对外暴露。这意味着从一条 CLI 命令到一个图像生成 API之间只需要切换子命令模型代码零改动。小结从示例到你自己的生成式模型examples/z-image-turbo虽然只有几十行代码却完整覆盖了 Cog 打包生成式模型的全部关键环节可抽象为通用四步法cog.yaml声明gpu: true、锁定 Python 版本与依赖文件、指定run: xxx.py:Runnerrequirements.txt用精确锁定 diffusers / transformers / torch 等依赖Runner类setup()中一次性加载管线注意 Turbo 系模型guidance_scale0等推理细节run()中接收类型化输入、返回cog.Path文件运行本地用cog run -i ...调试上线用cog serve或cog push部署。把ZImagePipeline换成 Stable Diffusion、Flux 或任何 Diffusers 管线参数稍作调整即可快速复用到其他生成式模型项目上。更多示例流式文本、训练接口、托管权重等见 examples 总览配置字段的完整说明见 cog.yaml 参考CLI 全量命令见 CLI 参考Python SDK 用法见 Python API 文档。【免费下载链接】cogContainers for machine learning项目地址: https://gitcode.com/GitHub_Trending/co/cog创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考