Create a Model Pack

~15 minIntermediateYou'll build: A .model.yaml + .pack.yaml bundle

In this tutorial you’ll create model manifests (.model.yaml) for individual models, then bundle them into a pack manifest (.pack.yaml) that users can install with one click.

Model packs let you ship a tested, compatible set of models — for example, an SDXL checkpoint + VAE + LoRA that are known to work well together.

Step 1: How Model Packs Work

The model system has two layers:

.model.yaml — describes a single model file (checkpoint, LoRA, VAE, etc.) with its download source, checksum, and hardware requirements
.pack.yaml — bundles multiple models into a compatible set with roles, presets, and platform-specific overrides

Apps reference packs via pack_refs in their .thumper.yaml. When a user installs an app, the referenced packs download automatically.

app.thumper.yaml → pack_refs: [sdxl-starter]

sdxl-starter.pack.yaml → models: [sdxl-base-1.0, sdxl-vae-fp16-fix]

sdxl-base-1.0.model.yaml → files, source, checksum

sdxl-vae-fp16-fix.model.yaml → files, source, checksum

Step 2: Write a Model Manifest

Start with the model you want to package. Here’s a complete example for an SDXL checkpoint:

sdxl-base-1.0.model.yaml

yaml

schema: thumper-model/v2
id: sdxl-base-1.0
name: Stable Diffusion XL Base 1.0
kind: checkpoint
format: safetensors
architecture: sdxl
function: text-to-image
version: "1.0"
precision: fp16
author: Stability AI
parameters: "3.5B"
output_resolution: "1024x1024"
compatible_apps: [comfyui, foocus, stable-diffusion-webui]
supported_platforms: [cuda, rocm, mps]
 
source:
  type: huggingface
  repo: stabilityai/stable-diffusion-xl-base-1.0
 
install_dir: models/checkpoints
 
files:
  - path: sd_xl_base_1.0.safetensors
    sha256: "31e35c80fc4829d14f90153f4c74cd59c90b779f6afe05a74cd6120b893f7e5b"
    size: "6.94 GB"
    size_bytes: 6938078334
 
vram_gb: 6.5
disk_gb: 6.94

Quick Check: .model.yaml

id—Unique identifier (e.g., sdxl-base-v1)required

name—Human-readable model namerequired

version—Semantic version (e.g., 1.0.0)required

kind—ModelKind enum value (e.g., diffusion_unet)required

format—File format (safetensors, gguf, onnx)required

files[]—At least one file with path and sizerequired

architecture—Model architecture (optional)optional

license—SPDX license identifier (optional)optional

description—Short description (optional)optional

hf_repo_id—HuggingFace repository ID (optional)optional

Required Fields

Field	Description
schema	Always "thumper-model/v2"
id	Unique model identifier
name	Display name
kind	Model type: checkpoint, lora, vae, controlnet, llm, tts, etc.
format	File format: safetensors, gguf, onnx, pytorch
source	Download source (HuggingFace, URL, CivitAI)
files	File list with paths and SHA-256 hashes

Model Kind Values

Common kinds for image generation:

checkpoint — main generation model
lora — fine-tuned adapter (small, stackable)
vae — variational autoencoder (image decoder)
controlnet — structural guidance (pose, depth, edges)
embedding — textual inversion
upscaler — super-resolution model

For LLMs:

llm — language model (GGUF, safetensors)
vlm — vision-language model
tts — text-to-speech
stt — speech-to-text

Source Types

yaml

# HuggingFace (most common)
source:
  type: huggingface
  repo: stabilityai/sdxl-base-1.0
  revision: main    # branch/tag (default: main)
 
# Direct URL
source:
  type: https
  url: "https://example.com/model.safetensors"
 
# CivitAI
source:
  type: civitai
  civitai_id: 12345
  civitai_version_id: 67890

Always include sha256 hashes for every file. Run: sha256sum model.safetensors

Step 3: Bundle into a Pack

Now bundle your models into a pack that users can install together:

sdxl-starter.pack.yaml

yaml

schema: thumper-pack/v2
id: sdxl-starter
name: SDXL Starter Pack
display_name: "SDXL Starter Pack"
version: "1.0"
description: "Complete SDXL setup with base, refiner, and FP16-safe VAE"
task_category: ImageGeneration
min_vram_mb: 6144
tags: [sdxl, starter, versatile]
compatible_apps: [comfyui, foocus, stable-diffusion-webui]
 
models:
  - ref: sdxl-base-1.0
    role: primary-checkpoint
    required: true
 
  - ref: sdxl-refiner-1.0
    role: auxiliary-checkpoint
    required: false
    rationale: "Improves fine details"
 
  - ref: sdxl-vae-fp16-fix
    role: vae
    required: false
    rationale: "Fixes NaN/black images with FP16"
 
hardware:
  minimum: { vram_gb: 6.5, ram_gb: 16, disk_gb: 14 }
  recommended: { vram_gb: 12, ram_gb: 32, disk_gb: 14 }
 
presets:
  - name: Fast Generation
    description: "Base model only"
    models_needed: [sdxl-base-1.0]
  - name: Full Quality
    description: "Base + Refiner + VAE fix"
    models_needed: [sdxl-base-1.0, sdxl-refiner-1.0, sdxl-vae-fp16-fix]

Quick Check: .pack.yaml

id—Unique pack identifierrequired

name—Human-readable pack namerequired

version—Semantic versionrequired

models[]—At least one model referencerequired

default_variant—Default variant for auto-selectionrequired

platform_overrides—GPU-specific configs (optional)optional

min_vram_gb—Minimum VRAM requirement (optional)optional

description—Short description (optional)optional

Model Roles

Role	Description
primary-checkpoint	Main generation model (required)
auxiliary-checkpoint	Secondary model (refiner, upscaler)
vae	Image encoder/decoder
lora	Style/subject adapter
controlnet	Structural guidance
text-encoder	CLIP or T5 text encoder

Task Categories

ImageGeneration, ImageEditing, ImageUpscaling
VideoGeneration, VideoEditing
AudioTts, AudioMusic, AudioVoiceCloning, AudioTranscription
LlmChat, LlmCode, LlmReasoning, LlmMultimodal
ThreeDGeneration, ThreeDEditing, FaceSwap, FaceEnhance

Step 4: Quantization Variants

For LLM models, offer multiple quantization levels so users can pick the best quality/speed tradeoff for their hardware:

yaml

# In your .model.yaml:
quantizations:
  - id: qwen3-8b-q4-k-m
    format: gguf
    precision: q4_k_m
    quality: good
    vram_gb: 5.0
    disk_gb: 4.9
    files:
      - path: qwen3-8b-q4_k_m.gguf
        sha256: "..."
        size_bytes: 5268045824
 
  - id: qwen3-8b-q8-0
    format: gguf
    precision: q8_0
    quality: excellent
    vram_gb: 9.5
    disk_gb: 8.5

Quantization Quality Guide

Format	Quality	Size vs FP16	Best For
q8_0	Excellent	~53%	Best quality, 12+ GB VRAM
q6_k	Very Good	~41%	Great balance, 8+ GB VRAM
q5_k_m	Good	~35%	Good balance, 6+ GB VRAM
q4_k_m	Good	~28%	Most popular, 4+ GB VRAM
q3_k_m	Acceptable	~22%	Low VRAM, some quality loss
q2_k	Degraded	~15%	Minimal VRAM, noticeable quality loss

For most users, q4_k_m offers the best balance of quality and speed. Always include it as the default quantization.

Step 5: Platform Overrides

Different GPU hardware may need different settings. Platform overrides let you customize behavior per-hardware:

yaml

platform_overrides:
  # AMD integrated GPU (APU) — limited VRAM, shared memory
  amd_apu:
    env:
      MIOPEN_FIND_MODE: "FAST"
      HSA_OVERRIDE_GFX_VERSION: "11.0.0"
    dtype_preference: bf16
    dtype_exclusions: [fp16]
    comfyui:
      text_encoder_device: cpu
      prefer_non_tiled_vae: true
      never_lowvram: true
    first_run_warmup_estimate_minutes: 5
    warning_text: "First run builds GPU kernel cache (~5 min)"

FP16 causes NaN outputs on AMD APUs because the model was trained in BF16 and FP16’s max value (~65504) overflows. Always exclude FP16 for AMD APU platform overrides.

Step 6: Performance Calibration

Help users estimate generation time on their hardware by providing a benchmark reference:

yaml

performance_calibration:
  metric_type: SecondsPerImage
  reference_value: 4.0
  reference_gpu: rtx_4090
  reference_bandwidth: 1008.0     # GB/s
  reference_tflops: 661.0
  model_weight_size_gb: 6.5
  peak_vram_mb: 8192

Metric Types

SecondsPerImage — image generation (SDXL, Flux)
SecondsPerClip — video/audio generation
TokensPerSecond — LLM inference
RealTimeFactor — TTS/audio (1.0 = real-time)

Thumper-Run uses the reference GPU’s bandwidth and TFLOPS to estimate performance on the user’s hardware.

Step 7: Test & Publish

Validate your manifests before submitting:

Checklist

Every file has a valid SHA-256 hash
All download URLs are accessible and return the correct file
vram_gb and disk_gb are accurate
compatible_apps lists the apps you’ve actually tested with
Quantization variants (if LLM) include at least q4_k_m and q8_0
Pack presets work end-to-end with the target app

Generate SHA-256 Hashes

bash

# Linux/macOS
sha256sum model.safetensors
 
# Or for multiple files
find . -name '*.safetensors' -exec sha256sum {} \;

Key Takeaways

Every model file needs a SHA-256 hash — run sha256sum on every file
Pack models by role: primary-checkpoint (required), vae/lora/upscaler (optional)
Include q4_k_m quantization for LLMs — it’s the best quality/speed balance for most users
AMD APU platform overrides: always exclude FP16, prefer BF16
performance_calibration helps users estimate generation time on their hardware

Next Steps

Full model manifest reference — Model Developer Guide
Create an app manifest — App Manifest Tutorial
Submit to the catalog — Publishing Guide

Learn More

App Manifest Tutorial

Write a .thumper.yaml manifest

Model Developer Guide

Full model manifest reference

Publishing Guide

Submit to the catalog

Troubleshooting

GPU benchmarks by hardware