publish-models

Docs

• Cog reference: https://cog.run/llms.txt
• Référence cog push: https://cog.run/cli#cog-push
• cog-safe-push: https://github.com/replicate/cog-safe-push
• Modèle de CI pour modèles: https://github.com/replicate/model-ci-template
• Guide de déploiement continu: https://replicate.com/docs/guides/continuous-model-deployment

Quand utiliser cette skill

• Vous avez un projet Cog fonctionnel (voir build-models si ce n'est pas le cas).
• Vous voulez publier un modèle privé ou public sur Replicate.
• Vous publiez une nouvelle version d'un modèle existant et voulez éviter les changements incompatibles.
• Vous mettez en place la CI/CD pour les versions de modèles.

Prérequis

• Cog installé et cog login authentifié contre r8.im (ou echo $TOKEN | cog login --token-stdin).
• Un modèle créé à replicate.com/{owner}/{name} via l'API, l'interface web, ou la CLI r8-model.
• REPLICATE_API_TOKEN défini dans votre environnement.

Simple cog push

Le chemin le plus simple. Construire et télécharger une nouvelle version:

cog push r8.im/owner/my-model

Ou définissez image: r8.im/owner/my-model dans cog.yaml et exécutez simplement:

cog push

Options utiles:

• --separate-weights — stocker les poids dans une couche séparée; démarrages à froid et poussées plus rapides pour les modèles avec > 1GB de poids.
• --x-fast — poussées plus rapides pendant le développement (ignore certaines validations).
• --secret id=hf,src=$HOME/.hf_token — passer des secrets de build sans les cuire dans l'historique de l'image.

cog-safe-push (recommandé pour tout modèle avec utilisateurs)

cog-safe-push pousse d'abord vers un modèle privé -test, vérifie la compatibilité du schéma avec la version en direct, exécute des comparaisons de prédictions, et teste les entrées. Détecte les changements incompatibles avant qu'ils ne parviennent aux utilisateurs.

Installation:

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

Variables d'environnement requises:

• REPLICATE_API_TOKEN
• ANTHROPIC_API_KEY (Claude juge la similarité des résultats pour les modèles stochastiques)

Utilisation basique:

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

Ceci:

1. Analyse predict.py avec ruff.
2. Crée un modèle de test privé owner/my-model-test s'il n'existe pas.
3. Pousse le modèle Cog local vers le modèle de test.
4. Analyse le schéma (descriptions, valeurs par défaut, etc.).
5. Vérifie la compatibilité du schéma avec la version en direct owner/my-model.
6. Exécute des comparaisons de prédictions entre les versions en direct et de test.
7. Teste le modèle de test avec des entrées générées par IA.
8. Si tout passe, pousse vers owner/my-model.

Schéma cog-safe-push.yaml

Déposez un cog-safe-push.yaml à la racine de votre projet (ou cog-safe-push-configs/<variant>.yaml pour les repos multi-modèles). Les cinq types de vérificateurs de cas de test dans un exemple:

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

predict:
  compare_outputs: false              # mettre false pour les modèles stochastiques
  predict_timeout: 600
  test_cases:
    - inputs:
        prompt: "a serene mountain landscape"
      match_prompt: "a landscape photo of mountains"   # jugé par IA via Claude
    - inputs:
        prompt: "a cat"
      match_url: "https://example.com/reference-cat.png"   # correspondance binaire/image
    - inputs:
        prompt: ""
      error_contains: "prompt cannot be empty"           # test négatif
    - inputs:
        mode: "json"
      jq_query: '.confidence > 0.8 and .status == "success"'   # résultat JSON
    - inputs:
        prompt: "echo this"
      exact_string: "echo this"                          # correspondance de chaîne exacte
  fuzz:
    fixed_inputs:
      seed: 42
    disabled_inputs:
      - debug
    iterations: 10
    prompt: "Generate creative and diverse prompts"

train:                                  # si votre modèle dispose d'un entraîneur
  destination: owner/my-model-trained
  destination_hardware: gpu-l40s
  train_timeout: 1800
  test_cases:
    - inputs:
        input_images: "https://.../training.zip"
        steps: 10

deployment:                             # créer ou mettre à jour automatiquement lors du push
  name: my-model
  owner: owner
  hardware: gpu-l40s

parallel: 4
fast_push: false
ignore_schema_compatibility: false
official_model: owner/my-model         # pour les modèles proxy/wrapper, voir ci-dessous

Les vérificateurs de cas de test s'excluent mutuellement: choisissez exactement un de match_prompt, match_url, error_contains, jq_query, ou exact_string par cas. Utilisez compare_outputs: false pour tout modèle stochastique (diffusion, LLMs); le défaut true est fragile.

CI/CD: GitHub Actions

Deux chemins, selon le niveau de personnalisation souhaité.

Chemin A: construire le vôtre

# .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       # les builds ont besoin d'espace disque et de cœurs
    steps:
      - uses: actions/checkout@v4
      - uses: jlumbroso/free-disk-space@v1.3.1
        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' || '' }}

Ajoutez un bloc concurrency: pour que les builds de PR s'annulent entre elles tandis que les pushes sur main se mettent en attente:

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

Chemin B: workflow réutilisable depuis model-ci-template

Pour les repos multi-modèles de style Replicate, insérez:

# .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

Le workflow réutilisable attend:

• cog-safe-push-configs/<model>.yaml — un par variante de modèle.
• script/select-model — fichier bash avec des blocs if/elif [[ "$MODEL" == "..." ]] listant les noms de modèles valides.
• Secrets: COG_TOKEN, REPLICATE_API_TOKEN, ANTHROPIC_API_KEY.

Pushes de matrice multi-modèles

Modèle de replicate/cog-flux: un repo, N variantes, les pousser en parallèle.

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 }}     # produit cog.yaml à partir d'un modèle
      - run: cog-safe-push --config cog-safe-push-configs/${{ matrix.model }}.yaml -vv

Push en deux passes pour modèles proxy / officiels

Quand vous maintenez un proxy qui enveloppe une API tierce, vous poussez d'abord vers un wrapper privé, puis mettez à jour la fiche de modèle publique. Modèle de replicate/cog-official-template:

./script/write-api-key                                              # cuire la clé API dans la config
cog-safe-push --config cog-safe-push-configs/${MODEL}.yaml -vv

./script/delete-api-key                                             # retirer la clé
cog-safe-push --push-official-model --config cog-safe-push-configs/${MODEL}.yaml -vv

Définissez official_model: owner/name dans la config pour que --push-official-model sache où publier.

Déploiements

Ajoutez un bloc deployment à cog-safe-push.yaml pour créer ou mettre à jour automatiquement un déploiement Replicate à chaque push:

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

Defaults de mise à l'échelle: les déploiements CPU se mettent à l'échelle 1-20 instances, les déploiements GPU se mettent à l'échelle 0-2. Ajustez manuellement via l'API ou l'interface web si nécessaire.

Monitoring des modèles publiés

Exécutez un canary horaire qui exerce le chemin du registre. Modèle de replicate/cog-pagerduty-check:

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

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - run: |
          # générer un petit modèle avec un uuid unique, le pousser, exécuter une prédiction
          # par digest, échouer bruyamment si quelque chose se casse.
          ./script/canary.sh

Cela vaut le coup pour tout modèle critique en production, surtout quand le revenu dépend de la disponibilité du registre.

Lignes directrices

• Ne cassez pas la compatibilité du schéma à moins que vous ne le vouliez vraiment. cog-safe-push le détecte; --ignore-schema-compatibility est la sortie.
• Fixez test_hardware pour que les pushes de test soient reproductibles.
• Utilisez --no-push pour les dry runs en CI/PR; push complet lors de la fusion vers main ou sur les tags de version.
• Poussez depuis la CI plutôt que depuis des ordinateurs portables une fois que vous avez des utilisateurs.
• Utilisez compare_outputs: false pour les modèles stochastiques. Utilisez match_prompt: pour les résultats image/vidéo (jugement VLM), match_url: pour les résultats binaires que vous contrôlez, jq_query: pour JSON, error_contains: pour les tests négatifs.
• Ne commitez jamais REPLICATE_API_TOKEN ou ANTHROPIC_API_KEY. Utilisez les secrets du repo.
• Pour les modèles avec des poids > 1GB, poussez avec --separate-weights.

Références de production

• https://github.com/replicate/cog-safe-push — l'outil lui-même, plus son schéma de config.
• https://github.com/replicate/model-ci-template — workflow GitHub Actions réutilisable.
• https://github.com/replicate/cog-official-template — modèle de proxy/modèle officiel.
• https://github.com/replicate/cog-flux/blob/main/.github/workflows/push.yaml — push de matrice à travers les variantes FLUX.
• https://github.com/replicate/cog-comfyui/blob/main/.github/workflows/ci.yaml — CI de modèle ComfyUI avec étape d'installation de custom-node.
• https://github.com/replicate/cog-pagerduty-check — modèle de canary horaire.