publish-models

文档

• Cog 参考文档：https://cog.run/llms.txt
• cog push 参考文档：https://cog.run/cli#cog-push
• cog-safe-push：https://github.com/replicate/cog-safe-push
• 模型 CI 模板：https://github.com/replicate/model-ci-template
• 持续部署指南：https://replicate.com/docs/guides/continuous-model-deployment

何时使用此技能

• 你有一个可用的 Cog 项目（如果还没有，请参阅 build-models）。
• 你想在 Replicate 上发布私有或公开模型。
• 你要发布现有模型的新版本，并希望避免破坏性变更。
• 你正在为模型发布设置 CI/CD。

直接使用 cog push

最简单的方式。构建并上传新版本：

cog push r8.im/owner/my-model

或者在 cog.yaml 中设置 image: r8.im/owner/my-model，然后直接运行：

cog push

实用标志：

• --separate-weights — 将权重存储在单独的层中；对于权重超过 1GB 的模型，可加快冷启动和推送速度。
• --x-fast — 加快迭代期间的推送速度（跳过部分验证）。
• --secret id=hf,src=$HOME/.hf_token — 传递构建时使用的密钥，而不将其写入镜像历史记录。

cog-safe-push（推荐用于任何有用户的模型）

cog-safe-push 会先推送到私有的 -test 模型，检查与线上版本的架构兼容性，运行预测对比，并对输入进行模糊测试。在破坏性变更影响用户之前将其捕获。

安装：

pip install git+https://github.com/replicate/cog-safe-push.git

必需的环境变量：

• REPLICATE_API_TOKEN
• ANTHROPIC_API_KEY（Claude 会评估随机性模型的输出相似度）

基本用法：

cog-safe-push --test-hardware=gpu-l40s owner/my-model

此操作将：

1. 使用 ruff 检查 predict.py。
2. 如果私有测试模型 owner/my-model-test 不存在，则创建它。
3. 将本地 Cog 模型推送到测试模型。
4. 检查架构（描述、默认值等）。
5. 检查架构与线上 owner/my-model 版本的兼容性。
6. 对线上版本和测试版本运行预测对比。
7. 使用 AI 生成的输入对测试模型进行模糊测试。
8. 如果全部通过，则推送到 owner/my-model。

cog-safe-push.yaml 架构

在项目根目录中放置一个 cog-safe-push.yaml（多模型仓库则放在 cog-safe-push-configs/<variant>.yaml）。以下示例展示了全部五种测试用例检查器类型：

model: owner/my-model
test_model: owner/my-model-test
test_hardware: gpu-l40s

predict:
  compare_outputs: false              # set false for stochastic models
  predict_timeout: 600
  test_cases:
    - inputs:
        prompt: "a serene mountain landscape"
      match_prompt: "a landscape photo of mountains"   # AI-judged via Claude
    - inputs:
        prompt: "a cat"
      match_url: "https://example.com/reference-cat.png"   # binary/image match
    - inputs:
        prompt: ""
      error_contains: "prompt cannot be empty"           # negative test
    - inputs:
        mode: "json"
      jq_query: '.confidence > 0.8 and .status == "success"'   # JSON output
    - inputs:
        prompt: "echo this"
      exact_string: "echo this"                          # exact string match
  fuzz:
    fixed_inputs:
      seed: 42
    disabled_inputs:
      - debug
    iterations: 10
    prompt: "Generate creative and diverse prompts"

train:                                  # if your model has a trainer
  destination: owner/my-model-trained
  destination_hardware: gpu-l40s
  train_timeout: 1800
  test_cases:
    - inputs:
        input_images: "https://.../training.zip"
        steps: 10

deployment:                             # auto-create or update on push
  name: my-model
  owner: owner
  hardware: gpu-l40s

parallel: 4
fast_push: false
ignore_schema_compatibility: false
official_model: owner/my-model         # for proxy/wrapper models, see below

每个测试用例的检查器互斥：每个用例只能选择 match_prompt、match_url、error_contains、jq_query 或 exact_string 中的一种。对于任何随机性模型（扩散模型、LLM），请使用 compare_outputs: false；默认值 true 容易导致误判。

CI/CD：GitHub Actions

有两种方式，具体取决于你希望自行处理多少配置。

方式 A：自行配置

# .github/workflows/push.yaml
name: Push to Replicate
on:
  workflow_dispatch:
    inputs:
      no_push:
        type: boolean
        default: false

jobs:
  push:
    runs-on: ubuntu-latest-4-cores       # builds need disk + cores
    steps:
      - uses: actions/checkout@v4
      - uses: jlumbroso/[email protected]
        with:
          tool-cache: false
          docker-images: false
      - uses: replicate/setup-cog@v2
        with:
          token: ${{ secrets.REPLICATE_API_TOKEN }}
      - run: pip install git+https://github.com/replicate/cog-safe-push.git
      - env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          REPLICATE_API_TOKEN: ${{ secrets.REPLICATE_API_TOKEN }}
        run: |
          cog-safe-push -vv ${{ inputs.no_push && '--no-push' || '' }}

添加 concurrency: 块，让 PR 构建相互取消，同时让主分支推送排队：

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}

方式 B：使用 model-ci-template 中的可复用工作流

对于 Replicate 风格的多模型仓库，直接加入：

# .github/workflows/ci.yaml
name: CI
on:
  pull_request: { branches: [main] }
  push: { branches: [main] }
  workflow_dispatch:
    inputs:
      models: { type: string, default: "all" }
      ignore_schema_checks: { type: boolean, default: false }
      cog_version: { type: string, default: "latest" }
      test_only: { type: boolean, default: false }

jobs:
  ci:
    uses: replicate/model-ci-template/.github/workflows/template.yaml@main
    with:
      trigger_type: ${{ github.event_name }}
      models: ${{ inputs.models || 'all' }}
      ignore_schema_checks: ${{ inputs.ignore_schema_checks || false }}
      cog_version: ${{ inputs.cog_version || 'latest' }}
      test_only: ${{ inputs.test_only || false }}
    secrets: inherit

可复用工作流需要：

• cog-safe-push-configs/<model>.yaml — 每个模型变体各一个。
• script/select-model — 一个 bash 文件，包含列出有效模型名称的 if/elif [[ "$MODEL" == "..." ]] 块。
• 密钥：COG_TOKEN、REPLICATE_API_TOKEN、ANTHROPIC_API_KEY。

多模型矩阵推送

模式参考自 replicate/cog-flux：一个仓库，N 个变体，并行推送。

jobs:
  prepare:
    runs-on: ubuntu-latest
    outputs:
      matrix: ${{ steps.set.outputs.matrix }}
    steps:
      - id: set
        run: |
          if [ "${{ inputs.models }}" = "all" ]; then
            echo 'matrix={"model":["schnell","dev","krea-dev"]}' >> "$GITHUB_OUTPUT"
          else
            list=$(echo "${{ inputs.models }}" | jq -Rc 'split(",")')
            echo "matrix={\"model\":$list}" >> "$GITHUB_OUTPUT"
          fi

  push:
    needs: prepare
    runs-on: ubuntu-latest-4-cores
    strategy:
      fail-fast: false
      matrix: ${{ fromJson(needs.prepare.outputs.matrix) }}
    steps:
      - uses: actions/checkout@v4
      - run: ./script/select.sh ${{ matrix.model }}     # produces cog.yaml from a template
      - run: cog-safe-push --config cog-safe-push-configs/${{ matrix.model }}.yaml -vv

代理模型／官方模型的两阶段推送

维护封装第三方 API 的代理时，先推送到私有封装模型，再更新面向公众的官方模型卡片。模式参考自 replicate/cog-official-template：

./script/write-api-key                                              # bake API key into config
cog-safe-push --config cog-safe-push-configs/${MODEL}.yaml -vv

./script/delete-api-key                                             # strip the key
cog-safe-push --push-official-model --config cog-safe-push-configs/${MODEL}.yaml -vv

在配置中设置 official_model: owner/name，这样 --push-official-model 就知道要发布到哪里。

部署

将 deployment 块添加到 cog-safe-push.yaml，以便在每次推送时自动创建或更新 Replicate 部署：

deployment:
  name: my-model
  owner: owner
  hardware: gpu-l40s

默认扩缩容设置：CPU 部署扩缩至 1-20 个实例，GPU 部署扩缩至 0-2 个实例。需要时通过 API 或 Web UI 手动调整。

监控已发布的模型

每小时运行一次金丝雀测试，验证注册表链路。可参考 replicate/cog-pagerduty-check 的模式：

name: Hourly cog push check
on:
  schedule:
    - cron: "0 * * * *"
  workflow_dispatch:

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - run: |
          # generate a tiny model with a unique uuid, push it, run a prediction
          # by digest, fail loudly if anything breaks.
          ./script/canary.sh

对于任何生产关键型模型，都值得这样做；尤其是在收入依赖注册表正常运行时。

指南

• 除非有意为之，否则不要破坏架构兼容性。cog-safe-push 会捕获此类问题；--ignore-schema-compatibility 可用于选择忽略。
• 固定 test_hardware，以确保测试推送可复现。
• 在 PR CI 中试运行时使用 --no-push；合并到 main 或创建版本标签时进行完整推送。
• 有用户后，请从 CI 推送，而非从笔记本电脑推送。
• 对随机性模型使用 compare_outputs: false。对于图像/视频输出（VLM 判断），使用 match_prompt:；对于由你控制的二进制输出，使用 match_url:；对于 JSON，使用 jq_query:；对于负向测试，使用 error_contains:。
• 切勿提交 REPLICATE_API_TOKEN 或 ANTHROPIC_API_KEY。请使用仓库机密。
• 对于权重超过 1GB 的模型，使用 --separate-weights 推送。

生产环境参考

• https://github.com/replicate/cog-safe-push — 工具本身及其配置架构。
• https://github.com/replicate/model-ci-template — 可复用的 GitHub Actions 工作流。
• https://github.com/replicate/cog-official-template — 代理/官方模型模板。
• https://github.com/replicate/cog-flux/blob/main/.github/workflows/push.yaml — 跨 FLUX 变体的矩阵推送。
• https://github.com/replicate/cog-comfyui/blob/main/.github/workflows/ci.yaml — 带自定义节点安装步骤的 ComfyUI 模型 CI。
• https://github.com/replicate/cog-pagerduty-check — 每小时金丝雀测试模式。