publish-models

Files (1)

• SKILL.md

SKILL.md (first lines)

## Docs

- Cog reference: <https://cog.run/llms.txt>
- `cog push` reference: <https://cog.run/cli#cog-push>
- cog-safe-push: <https://github.com/replicate/cog-safe-push>
- Model CI template: <https://github.com/replicate/model-ci-template>
- Continuous deployment guide: <https://replicate.com/docs/guides/continuous-model-deployment>

## When to use this skill

- You have a working Cog project (see `build-models` if you don't yet).
- You want to publish a private or public model on Replicate.
- You're releasing a new version of an existing model and want to avoid breaking changes.
- You're setting up CI/CD for model releases.

## Prerequisites

- Cog installed and `cog login` against `r8.im` (or `echo $TOKEN | cog login --token-stdin`).
- A model created at `replicate.com/{owner}/{name}` via the API, web UI, or `r8-model` CLI.
- `REPLICATE_API_TOKEN` set in your environment.

## Plain `cog push`

The simplest path. Build and upload a new version:

```
cog push r8.im/owner/my-model
```

Or set `image: r8.im/owner/my-model` in `cog.yaml` and run a bare:

```
cog push
```

Useful flags:

- `--separate-weights` — store weights in a separate layer; faster cold boots and pushes for models with > 1GB of weights.
- `--x-fast` — faster pushes during iteration (skips some validation).
- `--secret id=hf,src=$HOME/.hf_token` — pass build-time secrets without baking them into image history.

## cog-safe-push (recommended for any model with users)

`cog-safe-push` pushes to a private `-test` model first, checks schema compatibility against the live version, runs prediction comparisons, and fuzzes inputs. Catches breaking changes before they reach users.

Install:

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

Required env vars:

- `REPLICATE_API_TOKEN`
- `ANTHROPIC_API_KEY` (Claude judges output similarity for stochastic models)

Basic usage:

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

This will:

1. Lint `predict.py` with ruff.
2. Create a private test model `owner/my-model-test` if missing.
3. Push the local Cog model to the test model.
4. Lint the schema (descriptions, defaults, etc.).
5. Check schema compatibility against the live `owner/my-model` version.
6. Run prediction comparisons between live and test versions.
7. Fuzz the test model with AI-generated inputs.
8. If everything passes, push to `owner/my-model`.

## cog-safe-push.yaml schema

Drop a `cog-safe-push.yaml` in your project root (or `cog-safe-push-configs/<variant>.yaml` for multi-model repos). All five test-case checker types in one example:

```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

From replicate/skills, Apache-2.0.

More from replicate/skills