Pooling and templates
The three pooling modes, the query and passage templates each catalog model carries, instructions, normalization and Matryoshka truncation.
An encoder returns one hidden state per token; pooling turns them into the one vector a retrieval system stores, and a template is the prefix a model expects in front of a query or a passage. Both are descriptor data that ship with the model, because a wrong pooling mode or a missing prefix produces vectors that look healthy and rank worse.
Pooling
| Pooling | The vector is |
|---|---|
cls | the hidden state of the first token |
mean | the average over the real tokens, weighted by the attention mask |
last_token | the hidden state at index length - 1, the end-of-sequence token under right padding |
The catalog's Pooling column gives each model's mode.
Mean pooling divides the masked sum by the mask sum clamped at 1e-9, in the hidden states' dtype, and last-token pooling reads each row's length from the mask, not the final column. A repository with no registry entry and no descriptor takes its pooling from 1_Pooling/config.json: the CLS flag wins, then the last-token flag, then mean.
Templates
query_embed applies the query template, passage_embed the passage template and embed neither; {text} and {instruction} are the only placeholders.
| Models | Query template | Passage template |
|---|---|---|
| bge English (small, base, large), mxbai-embed-large-v1, Snowflake Arctic (xs, s, m, l, m-long) | Represent this sentence for searching relevant passages: {text} | none |
| BAAI/bge-small-zh-v1.5 | 为这个句子生成表示以用于检索相关文章：{text} | none |
| multilingual-e5 (small, base, large) | query: {text} | passage: {text} |
| nomic-ai/nomic-embed-text-v1, v1.5 | search_query: {text} | search_document: {text} |
| Qwen3-Embedding (0.6B, 4B, 8B) | Instruct: {instruction}\nQuery:{text} | none |
| google/embeddinggemma-300m | task: {instruction} | query: {text} | title: none | text: {text} |
| every other catalog model | none | none |
For a model with no templates, embed, query_embed and passage_embed return the same vectors.
Instructions
query_embed_with_instruction replaces the descriptor's default instruction for one call, filling {instruction} while {text} still takes the query. Qwen3-Embedding and EmbeddingGemma are the catalog's instruction models: Qwen3 takes a task sentence and EmbeddingGemma a task name such as clustering, and each family page lists the defaults. A model whose template has no {instruction} placeholder ignores the method.
Normalization
Every catalog entry returns unit-length vectors, as does a repository outside the registry, whatever its modules.json lists. Eight catalog repositories publish a modules.json of [Transformer, Pooling] with no Normalize module, so a bare SentenceTransformer.encode() of them returns longer vectors in the same direction, and every cosine agrees exactly:
Repositories without a Normalize module |
|---|
| mixedbread-ai/mxbai-embed-large-v1 |
| sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2, paraphrase-multilingual-mpnet-base-v2 |
| jinaai/jina-embeddings-v2-small-en, jina-embeddings-v2-base-code |
| nomic-ai/nomic-embed-text-v1.5 |
| Alibaba-NLP/gte-modernbert-base, gte-base-en-v1.5 |
The builder's normalize(false), or the CLI's --no-normalize, returns the raw vector for any model, as does a descriptor whose normalize is false.
Matryoshka
embed_dim, query_embed_dim and passage_embed_dim keep the first dim columns, after any Dense modules and the pipeline's LayerNorm and before L2 normalization, the order sentence-transformers uses.
| Model | Documented dimensions |
|---|---|
| Qwen3-Embedding (0.6B, 4B, 8B) | 32 up to the full size |
| google/embeddinggemma-300m | 768, 512, 256 and 128 |
| nomic-ai/nomic-embed-text-v1.5 | 768, 512, 256, 128 and 64 |
| Alibaba-NLP/gte-multilingual-base | 128 to 768, from its model card |
candding accepts any prefix length from 1 to the full size, so a dimension below the documented ones is the caller's choice.
| Error | When |
|---|---|
CanddingError::MrlUnsupported | a model whose descriptor does not declare Matryoshka support, before any tokenization |
CanddingError::InvalidDim | a dimension of zero, or one greater than the model's own |