Models
Compile a model
Turn open weights into an integer program with laplace model compile.
laplace model compile reads open float weights and writes a Laplace model: the four files The integer format describes, with the roots, step count and files hash that register_model takes. This page covers what the compiler accepts, the command, what it writes and prints, and how to check the result by running it.
What the compiler accepts
The compiler turns a BERT classifier into an integer program. It knows two shapes of it, selected by the slug given on the command line. Any other slug fails with The compiler knows judge and market; <slug> is neither.
| Slug | Shape | Files in the weights folder |
|---|---|---|
judge | A BERT sequence-pair classifier: 2 encoder layers, hidden size 256, 4 attention heads of 64, intermediate size 1,024, three output classes, 64 token positions. | model.safetensors and vocab.txt |
market | A MiniLM classifier in the BERT layout: 12 encoder layers, hidden size 384, 12 attention heads of 32, intermediate size 1,536, three output classes, 32 token positions. | model.safetensors and vocab.txt |
The BERT layout
model.safetensors is read by tensor name. Every tensor must be F32; any other type fails with <name>: only F32 tensors are read, and a tensor that is absent fails with missing tensor <name>. The names are the ones the transformers library writes for BertForSequenceClassification:
| Tensors | Used for |
|---|---|
bert.embeddings.word_embeddings.weight, position_embeddings.weight, token_type_embeddings.weight, LayerNorm.weight, LayerNorm.bias | The embeddings. Position and segment rows are summed into one table at compile time. |
bert.encoder.layer.<l>.attention.self.query, key, value (.weight, .bias) | Attention. |
bert.encoder.layer.<l>.attention.output.dense, attention.output.LayerNorm | The attention output and its norm. |
bert.encoder.layer.<l>.intermediate.dense, output.dense, output.LayerNorm | The feed-forward block with GELU, and its norm. |
bert.pooler.dense, classifier | The tanh pooler on the first token and the three-way classifier. |
The hidden and intermediate sizes are whole pages of 128 words, and the heads one page holds, times the positions, fit in one page of scores. A shape that breaks this stops the compiler with layout does not fit 128-word pages.
Every position runs through every layer, except in the last, where every position still gives its key and value but only the first, [CLS], goes on through attention and the feed-forward block: it is the one the pooler reads. The model answers one token, the index of the largest of the three logits.
| Slug | Input | Answer |
|---|---|---|
judge | [CLS] evidence [SEP] claim [SEP], at most 64 tokens | 0 yes, 1 unclear, 2 no |
market | [CLS] text [SEP], at most 32 tokens | 0 negative, 1 neutral, 2 positive |
What compiling does
| Source | Becomes |
|---|---|
| A matrix row | i8 weights with one i32 scale: the scale is the row's largest magnitude divided by 127, and each weight is rounded to the nearest step and clamped to -127 and 127. |
| A bias | An i32 in Q16: the value times 65,536, rounded. |
| Norm gains and biases | i16 values sharing one exponent per page, chosen so the largest magnitude fits in 32,767. |
| The forward pass | A fixed list of steps over a fixed set of pages, each step a slice of one operator sized to fit a transaction. |
Rounding happens here, once. From then on the model is the integers in its files, and every run of it is exact.
Compile
Get the weights
Put the two files in one folder. The source of each model on the network is on The models on the network.
Run the compiler
Shell laplace model compile market --weights ./market --out ./out/marketThe command needs no key and sends nothing. It runs the native
laplace-vmbinary, which it finds at the path inLAPLACE_VM_BIN, inbackend/chain/target/release/, in the CLI'sbin/folder, or onPATH, in that order: The native laplace-vm binary.Read what it printed
For the market weights it prints:
JSON { "program": "ca724dd25ca38a36a4384081330c85e89bc25458b9bd6ddbdccc955191270cd4", "weights": "8e8edab1ad8cb4ed145d292b40f25d5b20757c6fe02cb1bfe51447c1217ff276", "init": "8f8dfa519306420d8a7875a10c084e91542451632bcca01a38073f056914aa3e", "stepCount": 1318668, "statePages": 1063, "chunkCount": 133596, "filesHash": "57f80b9a78e3a7958fda43d0e3269b18801119557b438aee0e42f59e7c13137a" }Compiling the same weights again gives the same files and the same seven values.
Arguments
slugjudge | marketrequired- The shape to compile, and the slug written into the manifest.
--weightspathrequired- The folder holding
model.safetensorsandvocab.txt. --outpathrequired- The folder to write the model into. It is created when absent.
What it writes
File in --out | Content |
|---|---|
program.bin | The step list. |
weights.bin | The weight chunks. |
vocab.txt | The tokenizer, copied from the weights folder. |
manifest.json | The slug, name, task, summary, source and licence of the weights, the parameter count, the counts and limits, the labels, the three roots, and the SHA-256 and size of the other three files. |
What it prints
| Field | Meaning |
|---|---|
program | The program_root. |
weights | The weights_root. |
init | The init_root. |
stepCount, statePages, chunkCount | The counts register_model records. |
filesHash | The SHA-256 of manifest.json, which register_model records as files_hash. |
Check the result
A compiled model is checked by running it. The native binary takes the model folder and the input as token ids. The ids below are Nvidia beats revenue estimates and raises its outlook as the market model reads it.
Run it
laplace-vm run ./out/market --input 101,1050,17258,2401,10299,6599,10035,1998,13275,2049,17680,102 --seed 42{"output":[2],"traceRoot":"06a493141d3ad1be6922705a48d1e1c28c10fe0b050842e18be8fde99e96bc83","stepCount":1318668,"ms":1934}output is the answer as token ids, here 2, positive. traceRoot is what an operator would post with it, and ms is the time the run took. A second run prints the same output and traceRoot.
Prove sampled steps
check runs the model, builds the prove_step payload for a sample of steps, and executes each payload with the same verification the program runs, comparing the root it leads to with the run's own:
laplace-vm check ./out/market --input 101,1050,17258,2401,10299,6599,10035,1998,13275,2049,17680,102 --seed 42{"ok":true,"maxPayload":3479,"byOp":{"load":1099,"matvec":3479,"scores":3093,"softmax":2352,"weighted-sum":3061,"argmax":1616,"output":1579}}It samples 64 steps by default, plus the first step and the last two, and stops with an error at the first step whose payload does not verify. maxPayload and byOp are the largest payload seen, in bytes, overall and per operator.
Measure every step
max-payload builds the payload of every step of a run and prints the largest, the step it belongs to, and the largest per operator:
laplace-vm max-payload ./out/market --input 101,1050,17258,2401,10299,6599,10035,1998,13275,2049,17680,102 --seed 42{"maxPayload":3511,"atStep":1318372,"byOp":{"load":1099,"embed":2491,"add-row":2971,"matvec":3511,"norm-apply":3487,"norm-sum":2384,"activation":1579,"norm-stats":1579,"residual":2352,"scores":3125,"softmax":2384,"weighted-sum":3093,"argmax":1616,"output":1579}}The transaction around a payload adds 500 bytes, and a v1 transaction carries 4096, as One step on chain sets out.
The binary's commands
| Command | Prints |
|---|---|
laplace-vm compile <judge or market> <source dir> <out dir> | Writes program.bin and weights.bin and prints arch, stepCount, statePages, chunkCount, maxChunk (the largest chunk in bytes), inputMax, outputLen, the three roots and the two files' sizes. laplace model compile calls it. |
laplace-vm run <model dir> --input <ids> [--seed <n>] [--roots-out <file>] | The output, trace root, step count and time. --roots-out writes every root of the run to a file, 32 bytes each, from the init_root to the output leaf. |
laplace-vm prove <model dir> --input <ids> [--seed <n>] --step <k> | The prove_step payload for step k, as hex. |
laplace-vm check <model dir> --input <ids> [--seed <n>] [--samples <n>] | Whether sampled payloads verify, and their sizes. --samples defaults to 64. |
laplace-vm max-payload <model dir> --input <ids> [--seed <n>] | The largest payload over every step. |
--input is a comma-separated list of token ids. --seed defaults to 0. run and prove also take --fault <step>:<word>:<delta>, which adds delta to one word of the page that step writes and so produces a run that differs from that step on. With word at 128 or above it moves every word of the page, alternating in sign.
Run it in WASM
The SDK's WASM build loads the same two files and gives the same roots and the same run:
import { readFile } from 'node:fs/promises'
import { loadModel, toHex } from '@laplace/sdk/vm'
const model = await loadModel(await readFile('out/market/program.bin'), await readFile('out/market/weights.bin'))
console.log(toHex(model.programRoot), toHex(model.weightsRoot), toHex(model.initRoot), model.stepCount)
const input = [101, 1050, 17258, 2401, 10299, 6599, 10035, 1998, 13275, 2049, 17680, 102]
const run = await model.run(input, 42n)
console.log(run.output, toHex(run.traceRoot))The first line it prints holds the three roots and the step count from the manifest. The second holds the output and traceRoot the native run printed.
Next
Publish a model registers the compiled folder on chain and uploads its files.