Skip to main content
Version: Next

Configuration

Open System > Embedding Configuration in Pimcore Studio. The screen is admin-only. It has four tabs — General, Scope, Models and Usages — and a toolbar with Save, Save & Re-embed and Save & Full Re-embed.

Changes are stored in the settings store and take effect without a deployment. A few infrastructure settings have no editor and are configured in YAML, see Deploy-time YAML.

The editor opens read-only, with a warning and no Save button, whenever the configuration cannot be written: when the configuration comes from YAML outside debug mode — a hand-written pimcore_backend_power_tools.embeddings node is the usual case — or when the write target is disabled. See Where the configuration is stored.

General tab​

General tab of the embedding configurationGeneral tab of the embedding configurationGeneral tab of the embedding configuration

FieldDefaultDescription
EnabledoffMaster switch for all embedding behaviour: mapping, generation, indexing and kNN querying. Off by default, because embeddings add index fields and send content to an external service. Switch it on and configure at least one model and one usage.
Evaluation modeoffMaps, generates and stores every text representation per element so the Evaluation Tool can compare them. Off, only the primary representation is stored. Needs index recreation and a reindex.
Store embedded textoffDebug aid: also stores the composed element text, truncated to Max input characters exactly like the embedded input, in an emb_<model>_source sibling field, without the model's document prefix. Text inputs only; image inputs are never stored. Costs storage — keep it off in production.
Max input characters500000 (min 2000)Cost guard: composed text beyond this is truncated before chunking, which bounds how many embedding requests one element can cause. About 590 chunks at the default.
Cache eviction max age (days)90 (min 1)Under Advanced — embedding cache. Cache rows untouched for longer than this are pruned by bpt:embeddings:reindex --evict.
Cache eviction max rows1000000 (min 1)If the cache table is still over this row count after age-based pruning, the least recently used rows are removed down to the cap.

Max input characters changes cost, not quality: nested kNN ranks by the best-matching chunk, and a long document occupies one result slot however many chunks it has. Lower it on installations with many long documents; above the default, prefer splitting the source document. The hard ceilings are the search engine's — OpenSearch allows 10,000 nested objects per document, and one bulk request must stay under http.max_content_length.

Scope tab​

Which elements are embedded. Both sides deny by default: enabling embeddings alone embeds nothing, because sending a catalogue to an inference service should be a decision, not a side effect.

Scope tab of the embedding configurationScope tab of the embedding configurationScope tab of the embedding configuration

FieldDefaultDescription
Embed assets / Asset typesoffImages, Documents (PDF, Office) and Text files. Switching Embed assets off is the same as selecting no type. Documents and text files produce text vectors only.
Embed data objects / ClassesoffThe data object classes to embed. There is no wildcard: a class added later stays unembedded until it is named here.

Document and text assets are searchable once embedded, but they never enter duplicate detection — asset dedup requires Images.

Widening the scope needs the affected index's mapping updated before it can carry vectors. Save & Re-embed does this for you. Until the mapping exists, newly scoped elements index without their vector fields and are marked for backfill, so their vectors are filled in on that run — no manual reindex needed.

What is extracted from an asset​

Document and text assets are embedded from their identifying context (name, path, metadata) plus whatever text can be extracted. Max input characters governs how much: the extractors stop reading once they have delivered that many characters, because the chunker would discard anything beyond it.

SourceExtraction routeLimit
PDF, Word, PowerPoint and other office documentsPimcore core text extraction (pdftotext/Ghostscript for PDF, Gotenberg or LibreOffice for office formats); needs pimcore.assets.document.process_textcut at Max input characters
Spreadsheets and CSV (.xlsx, .xlsm, .ods, .xls, .csv)PhpSpreadsheet, data only, row by row with the header once per sheetrows are emitted until the text reaches the cap; a notice names the asset, sheet and row it stopped at. A workbook over 32 MB uncompressed is skipped; at most 256 columns per row and 200,000 cells per workbook are loaded
Plain text (.txt, .md, .json, .xml, …)file readthe first 4 bytes per character of the cap (2 MB at the default), cut at a UTF-8 character boundary
Scanned or image-only PDFsno OCR anywhere in the chainonly name, path and metadata are embedded

Extraction never fails to index: an unreadable or malformed file logs one warning, and the asset is embedded from its identifying context alone. The reasoning behind the fixed memory guards is in Defaults and Benchmarks.

Models tab​

One card per embedding model. Add creates a card, the bin icon deletes one, and Test probes the endpoint.

Models tab with three configured modelsModels tab with three configured modelsModels tab with three configured models

An expanded text model cardAn expanded text model cardAn expanded text model card

FieldDefaultDescription
Key(required)A free id you choose, referenced on the Usages tab. Dashes are folded to underscores internally: a model keyed nomic-text-v2 is addressed as nomic_text_v2 by CLI flags like --model=<id>.
ProviderdefaultWhich registered provider talks to the endpoint, see Custom Embedding Provider.
Modality(required)text or image.
Model(required)The model name the inference service should load. Not part of the identity key: swapping it under the same key does not invalidate stored vectors — bump Serving version alongside it.
Dimension(required)The vector dimension the model returns. It sizes the kNN field mapping, which is immutable once the index exists, and every provider response is validated against it, so a misconfigured endpoint is rejected instead of poisoning the index.
Max text length (characters)1500 (min 200)The longest text sent to the model as one input; longer text is split into chunks. See Sizing the character budgets. Text beyond the model's real window is truncated by the inference service without notice. Ignored for image models.
Chunk size (characters)1000 (min 100, ≤ max text length)Chunk length for longer text; the overlap is 15 % of it. Larger values cut the vector count of long documents roughly in proportion; smaller values match specific queries more sharply. Changing it changes the chunk texts, so that model's long texts re-embed.
Endpoint(required)Base URL of the HTTP inference service. Must be an absolute http:// or https:// URL.
Timeout (s)120Request timeout. Embedding batches on CPU-only services can be slow.
Auth tokenemptyOptional bearer token. Literal values only — an %env(...)% or %name% placeholder is always rejected. For an env-backed secret use a client profile.
OptionsemptyA JSON object of provider-specific settings, passed through untouched. The default provider reads params (extra request body params) and headers (custom HTTP headers).
Thumbnail(required for image models)The Pimcore image thumbnail used as the model input, see The image thumbnail.
Shared spaceemptyName of the latent space the model embeds into. Two models may only be combined in one search (a text query against an image field) when both declare the same space. Equal dimensions are not sufficient and would return confident nonsense.
Document prefix / Query prefixemptyInstruction prefixes some models expect, for example search_document: / search_query: for Nomic, passage: / query: for E5. The bundle prepends them, so the endpoint must not add its own. Only Document prefix is part of the identity key: editing it re-embeds that model's text vectors, while Query prefix only re-keys the query cache.
QuantizationBinary, disk-backedSee Quantization.
Serving versionemptyA version marker for the inference service's preprocessing, folded into the identity key. Bump it when serving-side preparation changes (a tokenizer fix, a normalization change, a new API-version header). Such changes are invisible to the text-based key, so stored vectors would otherwise stay silently stale.

Endpoint, Model, Provider, Dimension, Timeout, Options and the custom headers are transport or lookup details and are not part of the identity key. If one of them changes what the service actually computes, bump Serving version alongside it, see When vectors are regenerated.

Testing a model​

Test sends one probe request to the endpoint with a short, fixed 15-second timeout, using the values currently in the form — including unsaved ones. On success it reports the round-trip time and the dimension the endpoint actually returned; on failure it reports the error. Use it before saving a new model.

A successful model testA successful model testA successful model test

When the form's Auth token is left empty, the test falls back to the token already stored for that model's key, rather than testing with no auth at all.

Quantization​

The quantization presetsThe quantization presetsThe quantization presets

The select offers the three combinations measured against the quality bars in Defaults and Benchmarks:

PresetOpenSearch modeCompression
Binary, disk-backed (recommended)on_disk32x
Int8, in memoryin_memory4x
Full precision (float32)in_memory1x

A stored pair that matches none of the three — from YAML, or from an older configuration — is shown as a fourth, read-back Custom entry naming the actual mode and level.

Quantization is ignored on Elasticsearch. Changing it needs a reindex but no re-embed: the vectors carry over via index recreation.

Sizing the character budgets​

Both budgets are in characters, because the bundle has no tokenizer: provider, endpoint and model are all replaceable and none exposes one. Convert the model's token window yourself:

usable_tokens = window_tokens − tokens(document prefix) − 10 % of window_tokens
max_text_chars = usable_tokens × chars_per_token(language)
chunk_chars = 250 × chars_per_token(language) # ~250 tokens is the retrieval convention

window_tokens is on the model card (nomic-embed-text-v2-moe 512, nomic-embed-text-v1.5 8192, Qwen3-Embedding 32k). The 10 % margin covers the spread of real texts around the language average. For the default model and the Nomic prefix: 512 − 6 − 51 ≈ 455 usable tokens.

Content languageChars per token (approx.)Max text lengthChunk size
English418001000
German, French, Spanish, Italian3.51500875
Russian, Greek31350750
Arabic, Hebrew, Hindi2900500
Chinese, Japanese, Korean, Thai1450250

One model has one budget. For mixed-language content, size for the densest language you index; the other languages then produce more, smaller chunks, which costs vectors but loses no text. See Chunking.

The image thumbnail​

An image model embeds a Pimcore image thumbnail of the asset, never the original file. Define a thumbnail matching the dimensions your model expects:

pimcore:
assets:
image:
thumbnails:
definitions:
embeddings_siglip2:
name: embeddings_siglip2
description: 'Image input for embedding generation (SigLIP 2 base, 256x256)'
format: JPEG
quality: 90
items:
- method: cover
arguments:
width: 256
height: 256
  • Match the model's native input. siglip2-base-patch16-256 takes 256×256; feeding it 224 makes the service upscale and lose detail. A larger thumbnail is downscaled correctly, so err upward.
  • One per model. Two image models can use two definitions, for example 256 and 384.
  • Editing it re-embeds. The definition's pixel-affecting settings are part of the identity key, so a resize invalidates exactly that model's images.

Custom request headers​

Endpoints that do not authenticate with a bearer token, or need extra routing or tenant headers, are served through the Options field instead of a custom provider. Configured headers are added to every request and replace a same-named default, compared case-insensitively, so an Authorization entry wins over the Auth token bearer default:

{
"headers": {
"api-key": "temporary-value"
}
}

Like Auth token, header values are literal only: an %env(...)% or %name% placeholder is rejected. Never put a real secret here either — use a client profile. Headers are transport details and are not part of the identity key; if a header changes what the service computes, bump Serving version.

Filters tab​

Which fields of a data object class a particular model embeds. Without a filter a model embeds every field of every class in scope, which is what every configuration did before this tab existed.

A filter is one entry per (model, data object class) pair. The tab lists them in one grid — Model, Class, Mode, Fields — grouped by model, and the mode says what the listed fields mean:

ModeMeaning
Allow listOnly the listed field keys are embedded for that model and class.
Block listEvery field except the listed ones is embedded.

To add a filter, pick its model, class and mode above the grid, then choose its fields. Once a filter exists its model and class stay fixed. Its mode can be switched in its row, which keeps the listed fields but turns their meaning around; its fields change through the row's edit action.

A pair has one mode, never both — a configuration that names the same pair twice is rejected, at container build and on a Studio save, naming the pair, and the tab offers no class that already has a filter for the picked model. Stored, a filter carries its mode; the Studio API sends the two modes as allowListFilters and blockListFilters.

The Model picker offers only models bound as the embedding model (not the query model) of a usage that covers data objects — Semantic text search and Object deduplication. A cross-modal query model such as a text tower bound only as query_model of image search is never offered: it embeds queries, not object fields. Filters never affect assets; assets have no class fields.

Field keys​

Keys are the grid column keys of the class, the same ones the grid configuration uses:

Field kindKeyGranularity
Plain fieldnamethe field
Localized fieldnamethe field, in every language unless narrowed to one
Object brick attribute<field>.<brickType>.<attribute>, e.g. attributes.Engine.powerthat one attribute
Object brick, whole<field>, e.g. attributesevery attribute of every brick in it
Field collection<field>, e.g. featuresall or nothing
Classification store key<field>.<group>.<key>, e.g. technicalAttributes.Engine.powerthat one key
Classification store, whole<field>, e.g. technicalAttributesevery key of every group in it
Block<field>, e.g. notesall or nothing

Classification store keys are addressed by name, never by the numeric group and key ids the grid carries internally: ids are not portable between instances, so a filter written against them would silently mean something else on another system. The field picker offers a store's keys individually and the whole-store key only while it cannot read them; both forms stay valid in yaml and over the API.

Inside a field collection or block the filter is not evaluated against the inner field keys — those containers are all-or-nothing at their own key. A block list naming name therefore drops the top-level name field and leaves a block's inner name untouched.

Languages​

A key may be narrowed to one language, the way the grid models a localized column. In the Filters tab the field picker shows a language selector next to each selected key; left on all languages, the key keeps meaning what it always meant. In YAML and over the API the narrowed form is a {key, locale} map where a plain string would otherwise stand:

fields:
- name # every language
- { key: description, locale: de } # German only

A language may only be attached to a key that actually holds one: a localized field, a localized brick attribute or a classification store key. A language on a non-localized field, or one that is not a valid language of the system, is rejected on a Studio save with a 400 naming the model, the class and the key. A hand-written YAML filter is not checked this way — both lookups need the class definitions and the system languages, which a container build does not have — so there such an entry simply matches nothing.

Only what a save adds or changes is checked. A selector already stored is let through as it stands, so a filter written before its field was renamed away does not block saving the rest of the configuration. A classification store the class does not restrict to groups cannot have its keys listed from the class definition either, and a key written beneath such a store is taken at face value rather than rejected.

The narrowing applies per language as the text is composed, so a block entry on {key: description, locale: de} drops the German description and keeps every other language of it. Two entries may name the same key in two languages.

A classification store is read whole, with every language beside the others, so an entry on the store field itself — or on one of its keys — is applied per language inside it rather than against the language the object is being extracted in. Blocking a store in German keeps its English values, and allowing it only in German embeds those German values on an English-default system. A language may be written on the store field itself as well as on one of its keys, and on an object brick as well as on one of its localized attributes.

As soon as one entry names a language, the text is composed from every language rather than from the system's default alone: a field — a localized one, a brick attribute, a store key — is taken from whichever language the filter left it in. A filter that names no language changes nothing about which language a value is read in, so a configuration that does not use them embeds exactly what it always did.

Precedence​

  1. A password or encrypted field is never embedded, not even when an allow list names it. The field picker does not offer those two types at all.
  2. excluded_fields removes a key — also one the filter allow-lists. Naming a container there removes everything inside it, since extraction never descends into it.
  3. The pair's own entry applies, in its single mode.
  4. A field whose type carries no text of its own (images, geo fields, URL slugs, …) is skipped — unless an allow list names that exact key, which embeds it anyway. Naming an ancestor, e.g. a whole object brick, is not enough.
  5. No entry for the class means no filtering at all for that model.

Stale pairs​

A filter keeps its field keys exactly as stored, even after the class was changed under it. For indexing, a key the class no longer has simply matches nothing — and an allow entry left with no surviving key embeds nothing for that pair, which is logged once per extraction naming the model and the class. A renamed classification store key counts the same way. The same holds for a class taken out of the Scope tab, and for a model that stops being the embedding model of a usage covering data objects — for example after it is demoted to a usage's query_model.

A pair counts as inactive only when nothing survives in any language and no container above a named key is excluded: a block entry naming a single language leaves the other languages to embed, while an allow entry on an attribute of a brick named in excluded_fields embeds nothing at all.

The entry itself is never pruned, so taking the class back into scope or restoring the field brings the filter back. The Filters tab marks such a pair inactive while still showing its stored field keys, and the Studio API reports it as inactive on each entry.

caution

Changing a filter changes what is embedded, so the affected elements need a re-embed before search reflects it. Saving the configuration never queues one — use Save & Re-embed.

An element the filter leaves with nothing to embed has its stored vector and text siblings cleared by that re-embed, rather than keeping the last ones it had: a filter that empties an object would otherwise go on matching searches on text it was written to remove. An element that was never embedded is left untouched.

Usages tab​

What each search capability embeds with. The four registered usages are Semantic text search, Object deduplication, Image search and Image deduplication. To add one of your own, see Registering a Custom Embedding Usage.

Usages tab with a cross-modal image searchUsages tab with a cross-modal image searchUsages tab with a cross-modal image search

FieldDescription
ModelThe model that embeds the indexed content, and — for a text-to-text usage — the incoming query too.
Cross-modal querySwitch on when the query is embedded by a different model than the content, which is what image search needs: a vision model indexes the images, a text model embeds the typed query. Offered only on usages that take a cross-modal query — of the built-in ones, Image search — and on any usage that already has a query model, so it can be switched off.
Query modelOnly with Cross-modal query. Lists the text models declaring the same Shared space as Model, since the registry accepts no other; the tab shows which space is in effect.

Deploy-time YAML​

Three nodes live outside the editable configuration: they are infrastructure decisions, never persisted to the settings store and never editable through Studio.

Where the configuration is stored​

The embeddings configuration is a Pimcore location-aware configuration: the read source and the write target are chosen per installation.

pimcore_backend_power_tools:
config_location:
embeddings:
write_target:
type: settings-store # default; also: symfony-config, disabled
read_target:
type: ~ # default; also: settings-store, symfony-config
SetupBehaviour
Defaults, as shippedReads container config first, settings store as fallback. A hand-written pimcore_backend_power_tools.embeddings YAML node therefore takes over and the editor turns read-only. Saves go to the settings store.
write_target.type: symfony-configSaves write YAML files into var/config/backend_power_tools_embeddings/, which are loaded back into the container configuration — a version-controllable workflow. Writing is only permitted in debug mode, so production editors are read-only under this target.
write_target.type: disabledThe editor is read-only everywhere; the configuration is fully deploy-managed.

Under a YAML override every field above is available as a configuration key, including the field filters of the Filters tab, which are stored per model:

pimcore_backend_power_tools:
embeddings:
models:
text-a:
# …
field_filter:
Car:
mode: allow # allow | block, required, no default
fields: # at least one grid column key
- name
- attributes.Engine.power
- { key: description, locale: de } # one language of a localized field

Changing a filter needs a reindex.

caution

excluded_fields — field keys that are never embedded, at any nesting level, by both production indexing and the evaluation tool, for every model and class at once — is deprecated since 2026.4.0 in favour of models.<id>.field_filter and will be removed in 2027.1.0. Until then it keeps working unchanged, including its precedence: it still removes a key a field_filter allow-lists. It has no editor and is only reachable through YAML or the API:

pimcore_backend_power_tools:
embeddings:
excluded_fields:
- internalNotes

Changing it needs a reindex.

Credentials (embedding_client_profiles)​

Auth token and the headers in Options are runtime-editable by anyone who can reach the configuration screen, so stored values are literal-only: an %env(...)% placeholder or an unescaped %name% parameter reference in either is always rejected, by whichever of three checks sees it first:

  • a Studio save, by the config validator;
  • a hand-written config/packages/*.yaml value, by the same config-tree check (Pimcore loads it before that check runs);
  • a YAML file written into the embeddings write-target directory, by a dedicated build-time guard, since that directory is only read later, after the config-tree check has already run.
caution

%env(...)% or %name% in embeddings.models.*.auth_token or .options.headers is always rejected. This is a deliberate security control against env-var exfiltration through the editable configuration.

Env-backed secrets belong in embedding_client_profiles, a deploy-time-only node in config/packages/*.yaml. Each profile attaches its token and headers to a request only when the request URL matches its endpoint_pattern — an anchored regex, the same semantics as Symfony's ScopingHttpClient:

pimcore_backend_power_tools:
embedding_client_profiles:
my_inference_host:
endpoint_pattern: 'https://inference\.example\.com/.*' # anchored regex, escape literal dots
auth_token: '%env(MY_INFERENCE_TOKEN)%' # container-resolved — safe here
headers:
X-Tenant: 'catalog'

Rules, in order of precedence:

  • A stored literal token always wins. If the model's own Auth token is set, the matching profile's token is never used. Profiles are a fallback, not an override.
  • Profile headers only fill gaps. A profile header is added only when the model does not already define a header of the same name, compared case-insensitively.
  • No match, no credentials. If no endpoint_pattern matches the request URL, nothing is attached.
  • Non-absolute endpoints never receive profile credentials. Only a request to an absolute http:// or https:// URL can match a profile at all.
  • endpoint_pattern is anchored at the start only. It matches a prefix of the request URL, not the whole string — end the pattern with / to bind it to one host rather than any subpath of it.

Stored tokens are write-only through the API​

The editor's underlying API never returns a stored token. A GET exposes only hasAuthToken: boolean; a save distinguishes three cases for the authToken field:

Sent valueEffect
omitted / nullKeep the stored token for that model key unchanged.
""Clear the stored token.
any other valueOverwrite the stored token.

In the editor this is the Clear stored token checkbox next to a token field whose placeholder reports that one is stored. Renaming a model key does not inherit its old token: the keep-on-null behaviour is looked up by key, so a model saved under a new key starts with an empty token. Re-enter it after a rename.

Cache table (embedding_cache)​

Where the durable vector cache table lives and which engine it uses:

pimcore_backend_power_tools:
embedding_cache:
database: '' # optional schema for the cache table; empty = Pimcore's main schema
table_storage_engine: '' # explicit engine; empty = auto-detect at table creation
OptionDefaultDescription
database''Optional schema name on the same MySQL/MariaDB server. Empty keeps the table in Pimcore's main schema. Must match ^[A-Za-z0-9_]*$. Cross-schema DDL is not something the installer or a Doctrine migration on this connection can express, so both skip creating the table and print the manual CREATE TABLE statement instead, see Provisioning the table.
table_storage_engine''Storage engine for the cache table. Empty auto-detects one at table-creation time, see Storage engine. An explicit value is verified to exist on the server and bypasses auto-detection. Only takes effect at table-creation time; neither the installer nor the migrations ever ALTER an existing table onto a different engine.

Query-time settings of the Studio semantic search (grid filter, search modes and the global endpoint). Open System > Semantic Search Configuration in Pimcore Studio; the screen is admin-only. They are a separate configuration record, not part of the embeddings configuration: own root node pimcore_backend_power_tools.semantic_search, own settings-store scope backend_power_tools_semantic_search (record id default_semantic_search, seeded by the installer and migration Version20261008120000), own config_location entry and own Studio API, see Configuration API.

No mapping, vector or identity key depends on them: changing them needs neither a re-embed nor an index recreation. Like every Pimcore config save, saving the record restarts the messenger workers.

pimcore_backend_power_tools:
semantic_search: # yaml override: shadows the stored record, API turns read-only
candidate_cap: 10000 # 1..10000, listing searches
global_search_candidate_cap: 150 # 1..10000, global semantic search endpoint (per index)
targets:
text: { default_min_score: ~ } # percent 0..100, ~ = built-in default
image: { default_min_score: 12 }
config_location:
semantic_search:
write_target:
type: settings-store # default; also: symfony-config, disabled
read_target:
type: ~ # same semantics as the embeddings entry above
FieldOptionDefaultDescription
Listing candidate capcandidate_cap10000 (min 1, max 10000)Nearest-neighbour candidates per listing search (grid, search modal): OpenSearch k, Elasticsearch num_candidates (the knn query clause has no k; num_candidates is its per-shard match bound). Lower values are faster on large indexes but end the result set earlier; 10000 is the engine maximum.
Global search candidate capglobal_search_candidate_cap150 (min 1, max 10000)Nearest-neighbour candidates per index for the global endpoint. It runs without listing filters across every embedding-bearing index, so it keeps a small cap; the target's default minimum score applies to these candidates.
Text search → Default minimum scoretargets.text.default_min_scorenullDefault score threshold in percent (cosine similarity × 100) for the text target (semantic_text_search usage). null uses the built-in default (20).
Image search → Default minimum scoretargets.image.default_min_scorenullSame for the image target (image_search usage). null uses the built-in default (8).

Candidate cap. The cap bounds the candidate set every page, the total and the score threshold work on: the grid total never exceeds it, even when more documents would pass the threshold. Both engines apply it per shard (OpenSearch k, Elasticsearch num_candidates), so the cap is exact only for single-shard indexes. A lower cap trades completeness for latency; it does not change scores.

Default minimum score. Applied when a search request carries no minScore, see Threshold contract. Resolution order: request minScore, then targets.<target>.default_min_score, then the built-in default of the target's usage (semantic_text_search 20, image_search 8; calibrated on the demo label set, 2026-10-07). A configured 0 disables the default cut-off.

  • A partial Studio API update keeps the omitted members (candidateCap, globalSearchCandidateCap, a whole target); a target object that is sent must carry defaultMinScore and replaces its threshold, and an explicit null clears it to the built-in default (an empty or malformed target is rejected). NaN, infinite and out-of-range values are rejected in the YAML and on save; in a hand-edited row a threshold outside 0..100 is ignored and the caps are clamped to 1..10000.
  • Runtime reads (grid filter, score column, settings block, global search endpoint, and async workers such as export or batch edit) load the record once per request or worker message (kernel.reset); a save is picked up by the next request or message.
  • Score bands depend on the model pair: re-check the value after changing the model of the target's usage.
  • The percent/engine-score conversion follows the configured quantization profile. After changing a model's quantization, percentages and thresholds are only correct once the index was rebuilt. Vectors are assumed unit-normalised by the inference service; BPT does not normalise them.

Vector storage, reuse and index recreation​

Vectors live in the search index documents and in a durable MySQL/MariaDB cache table, and are reused via version-aware identity keys, so re-indexing unchanged content costs no inference calls. The cache table, the identity key and the ways to force a re-embed are covered in Caching.

How the defaults were chosen​

The measured reasoning behind the default model, text representation, chunking and compression choices is in Defaults and Benchmarks.