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.

SlugShapeFiles in the weights folder
judgeA 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
marketA 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:

TensorsUsed for
bert.embeddings.word_embeddings.weight, position_embeddings.weight, token_type_embeddings.weight, LayerNorm.weight, LayerNorm.biasThe 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.LayerNormThe attention output and its norm.
bert.encoder.layer.<l>.intermediate.dense, output.dense, output.LayerNormThe feed-forward block with GELU, and its norm.
bert.pooler.dense, classifierThe 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.

SlugInputAnswer
judge[CLS] evidence [SEP] claim [SEP], at most 64 tokens0 yes, 1 unclear, 2 no
market[CLS] text [SEP], at most 32 tokens0 negative, 1 neutral, 2 positive

What compiling does

SourceBecomes
A matrix rowi8 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 biasAn i32 in Q16: the value times 65,536, rounded.
Norm gains and biasesi16 values sharing one exponent per page, chosen so the largest magnitude fits in 32,767.
The forward passA 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

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

  2. Run the compiler

    Shell
    laplace model compile market --weights ./market --out ./out/market

    The command needs no key and sends nothing. It runs the native laplace-vm binary, which it finds at the path in LAPLACE_VM_BIN, in backend/chain/target/release/, in the CLI's bin/ folder, or on PATH, in that order: The native laplace-vm binary.

  3. 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.safetensors and vocab.txt.
--outpathrequired
The folder to write the model into. It is created when absent.

What it writes

File in --outContent
program.binThe step list.
weights.binThe weight chunks.
vocab.txtThe tokenizer, copied from the weights folder.
manifest.jsonThe 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

FieldMeaning
programThe program_root.
weightsThe weights_root.
initThe init_root.
stepCount, statePages, chunkCountThe counts register_model records.
filesHashThe 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

Shell
laplace-vm run ./out/market --input 101,1050,17258,2401,10299,6599,10035,1998,13275,2049,17680,102 --seed 42
JSON
{"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:

Shell
laplace-vm check ./out/market --input 101,1050,17258,2401,10299,6599,10035,1998,13275,2049,17680,102 --seed 42
JSON
{"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:

Shell
laplace-vm max-payload ./out/market --input 101,1050,17258,2401,10299,6599,10035,1998,13275,2049,17680,102 --seed 42
JSON
{"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

CommandPrints
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:

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