[[models]]

Each [[models]] entry picks an embedding model from the model registry and says what it embeds and where the vectors go. A spec needs at least one entry, and exactly one of them has text = "default".

[[models]]
preset = "potion"
text = "default"              # the file's main vectors (space 0)

[[models]]
preset = "wemm-2b"
text = "space"                # named space wemm-2b-text@256
image = "space"               # named space wemm-2b@256
dims = [256]
space_dtype = "int8"

[output]
allow_remote_code = ["wemm-2b"]

KeysCopy Anchor Link

The sentence-transformers presets are jina-v5-omni-nano, jina-v5-omni-small, wemm-2b, wemm-4b and wemm-9b. The open_clip presets are clip-vit-b32 and siglip2.

text_corpus_mode, text_query_mode, image_mode, image_prompt, normalize, preprocess_version, image_max_side, encode_kwargs, dtype and device enter the model's embedding recipe, which keys the embed cache: changing one computes that model's vectors again. dims, space_dtype and batch_size do not; a change to dims or space_dtype reuses the cached vectors and only changes what is stored.

RolesCopy Anchor Link

text and image decide what a model embeds and where the vectors land:

A model can hold text = "default" and image = "space" at once: its text vectors are space 0 and its image vectors are a named space.

image = "space" needs a source with images: kind = "image_dir", or a [source.image] path_template. What gets embedded (the source files or the decoded media) is set by [embedding.image_input].

DimensionsCopy Anchor Link

dims works only on presets trained for prefix truncation (Matryoshka). Each listed dimension must be on the preset's validated ladder; the vectors are cut to the first dim components and L2-normalized again.

dims shapes only named spaces. On a text = "default" model without image = "space" it produces nothing; to shorten space 0, use [build] mrl_dim (see [build]).

space_dtype = "int4" needs every listed dimension, or the preset's default dimension when dims is empty, to be a multiple of 64.

What a file containsCopy Anchor Link

For each output file:

• Space 0 holds the text = "default" model's text vectors over all rows, at the precision of the [build] preset. Its dimension is the model's native one, or [build] mrl_dim when set.
• Named spaces follow the order of [[models]] in the spec. Within one model, image spaces come first, then text spaces, one per entry in dims. Each is stored at the model's space_dtype and carries the preset's model_hash, which both towers of a model share.
• A spec can emit at most 15 named spaces. More fail validation with models: N named spaces > max 15.

With [output] mode = "per-model" or "both", each model also gets its own file with space 0 plus that model's named spaces (see [output]). The manifest lists every space with its name, preset, modality, dimension (null for native) and space_dtype. List a file's spaces with urna stats and query one with urna search-space.

Validation rulesCopy Anchor Link

Validation errors (exit 2 unless noted):

Invalid values of text, image and space_dtype also fail with a message naming the allowed values. The other keys are not checked: a bad dtype fails inside the model worker as a registry error (exit 4).

Where weights come fromCopy Anchor Link

The build never downloads a model. It resolves a model directory in this order: model_path, then URNA_MODEL_DIR_<NAME> (the preset name in upper case with - as _, for example URNA_MODEL_DIR_WEMM_2B), then the preset's built-in local directory if it exists, then, for sentence-transformers presets, the Hugging Face cache snapshot that refs/main points to. urna build --dry-run prints nothing about the directory; python python/tools/urna_forge.py --spec corpus.toml --dry-run --json shows it as model_dir.

A sentence-transformers preset with no directory on disk fails with a Python TypeError (exit 1). potion ships its weights in the repository.

Device and dtype for sentence-transformers presets: device in the spec, else URNA_ST_DEVICE, else cuda, mps, cpu in that order of availability. dtype in the spec, else URNA_ST_DTYPE, else bfloat16 on cuda, float16 on mps and float32 on cpu. The dtype enters the model_hash, so the same weights built on different devices get different hashes unless you pin dtype.

Querying what you builtCopy Anchor Link

The query side uses the preset's defaults. Spec overrides of text_query_mode, encode_kwargs, image_prompt, normalize, dtype and device are not carried to ask or retrieve. Because normalize and the resolved dtype enter the model_hash, a corpus built with a non-default dtype, or on a device whose default dtype differs from the query machine's, is refused by the model gate unless URNA_ST_DTYPE matches at query time. See the model gate.