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
• Model 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 を使用します）。5 種類すべてのテストケースチェッカーを含む例：

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 のいずれか1つだけを選んでください。確率的モデル（拡散モデル、LLM など）では compare_outputs: false を使用します。デフォルトの true は壊れやすい設定です。

CI/CD：GitHub Actions

必要な連携の量に応じて、2つの方法があります。

方法 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' || '' }}

PR のビルドは相互にキャンセルし、main ブランチへのプッシュはキューに入るように、concurrency: ブロックを追加します。

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 — モデルのバリエーションごとに1つ。
• script/select-model — 有効なモデル名を列挙する if/elif [[ "$MODEL" == "..." ]] ブロックを含む bash ファイル。
• シークレット：COG_TOKEN、REPLICATE_API_TOKEN、ANTHROPIC_API_KEY。

マルチモデルのマトリックスプッシュ

replicate/cog-flux のパターンです。1つのリポジトリに 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

プロキシモデル／公式モデルへの2段階プッシュ

サードパーティ 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 の公開先が設定されます。

デプロイ

cog-safe-push.yaml に deployment ブロックを追加すると、プッシュごとに Replicate デプロイメントを自動的に作成または更新できます。

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

スケーリングのデフォルト設定：CPU デプロイメントではインスタンス数を 1～20、GPU デプロイメントでは 0～2 にスケーリングします。必要に応じて、API またはウェブ 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 へのマージ時またはバージョンタグの付与時に完全なプッシュを実行してください。
• ユーザーがいる場合は、ノート PC ではなく CI からプッシュしてください。
• 確率的なモデルには compare_outputs: false を使用してください。画像／動画出力には match_prompt:（VLM による判定）、管理下にあるバイナリ出力には 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 — 毎時カナリアを実行するパターン。