Converted ONNX artifacts
Models with an upstream checkpoint can use this declaration:
conversion:
source:
uri: hf://models/owner/repository@0123456789012345678901234567890123456789/model.pt
sha256: <upstream checksum>
size_bytes: <upstream size>
compilation:
format: onnx
source: conversion
The checkpoint is a pinned Hugging Face file or a release file of a public GitHub repository. Pin every input lists the approved forms.
What convert.py exports
convert.py exports the official model as it is: its forward pass at the input shape
the package ships, from the model's input to the final outputs the package keeps. It may
simplify the ONNX with onnxsim.simplify, including constant folding, when that keeps
the same inputs, outputs, and computation.
Every other change made for the compiler belongs in surgery.py, even one that leaves
the results exactly the same. That includes a cut: an export that ends at an inner
tensor, such as the raw heads before the official decode step, or one that starts after
an official step. This split keeps the converted ONNX comparable with the official model.
What to keep in Git
Keep upstream pins and exporter dependencies in Git. Do not copy the output URL,
checksum, size, or run ID into model.yaml. The folder identifies the model and
the conversion produces model.onnx, unless conversion.outputs names other
files. Direct file and file-set sources continue to work.
Publish other files
To publish several ONNX models, or a PyTorch checkpoint, list the files under
conversion.outputs:
conversion:
source:
uri: hf://models/owner/repository@0123456789012345678901234567890123456789/model.pt
sha256: <upstream checksum>
size_bytes: <upstream size>
outputs: [vector_estimator.onnx, vocoder.onnx]
compilation:
format: onnx
source: conversion
components: [vector_estimator, vocoder]
Each name is a file name you choose, ending in .onnx, .pt or .pth, without
a folder. Order matters: compile.py receives the first file as --model, and
the others sit beside it. The default is [model.onnx], so a model with one ONNX
leaves the field out.
Scripts read the names from model.yaml and never hard-code them. Renaming a
file then takes one edit in model.yaml, followed by a new conversion:
from model_registry.conversion import conversion_outputs
# convert.py
estimator, vocoder = conversion_outputs(MODEL_DIR)
export_estimator(args.output_dir / estimator)
export_vocoder(args.output_dir / vocoder)
# compile.py
_, vocoder = conversion_outputs(MODEL_DIR)
vocoder_path = args.model.with_name(vocoder)
compile.py and surgery.py can also pick a file for each build profile by
branching on --build-profile.
For graph surgery in PyTorch, publish the checkpoint with outputs: [weights.pth].
compile.py receives weights.pth, and surgery.py edits the model and exports
the ONNX to compile, so compilation.format stays onnx.
Convert fails when a listed file is missing, and runs the ONNX checker on every
.onnx file. Nothing shared checks a .pt or .pth file, so the model's
conversion tests must do that. Their converted fixture is the first file, and
the others sit beside it.
Publish a conversion
No push runs a conversion. In Actions, run Vulcan Model Convert on the branch
that holds the model. Give it the model's ID and the registry environment, staging
or production.
The workflow installs the model's exporter requirements and runs convert.py and the
model's conversion tests. It then publishes the declared outputs, with any external
tensor files the ONNX files reference. A failed or skipped conversion test publishes
nothing.
A conversion belongs to the environment it ran in. To move a pinned model to
compilation.source: conversion, run Convert in each environment that builds the
model, then change the source.
CI resolves compilation.source: conversion to the latest published conversion that
matches the model's current conversion inputs. When none matches, CI stops with
<model-id>: no matching validated conversion; run Vulcan Model Convert first. The
compile fingerprint uses the content of the converted files, so a conversion that
publishes the same bytes again recompiles nothing.
When to run Convert again
Run Vulcan Model Convert again after changing anything that can change the converted files:
- the checkpoint pin under
conversion.source, orconversion.outputs scripts/convert.py, or a module beside it thatconvert.pyimports, directly or through another such module- any other file directly in
scripts/that is not a.pyfile, such asrequirements-convert.txtor an exporter patch - any file in a subfolder of
scripts/
Three files never count, wherever they sit: requirements-compile.txt,
requirements-accuracy.txt, and requirements-performance.txt.
Everything else leaves the conversion valid, including shared tooling, tests, compile and benchmark code, and the taxonomy. A changed conversion test runs the next time Convert runs.
Shared tooling is not on the list because the checkpoint is verified against its
pinned SHA-256: where it is hosted and how it is fetched cannot change the output.
When a shared change does alter converted output, such as a new Python version in
scripts/run_model_conversion.sh or a new bundle layout, raise
FINGERPRINT_VERSION in tools/model_registry/conversion.py in the same change.
Every conversion-backed model then needs Convert again.
Leave a successful conversion alone. A repeated Convert whose output bytes differ recompiles that model on every branch.
Import helpers with a plain import helper or from helper import name. The check
does not detect a module that convert.py loads dynamically or through a relative
import, so a change to it does not ask for a new conversion. Pin exporter
requirements too, because the check does not track packages they pull in indirectly.