Changing models in Knowledge
Model settings belong to each knowledge base. Edit the selected YAML or JSON file and restart the process. An embedded application opens a new Knowledge handle and retires the old writer. Keep the same OKF root, database and encryption key for an in-place change. Use a separate database for a trial. Configuration reference
PostgreSQL rollout
A PostgreSQL index binds each bundle to a processing recipe. To change an encoder or another semantic processing setting, initialize a new bundle with the candidate configuration, reconcile the same authoritative OKF source, and let the workers build the new index. Configure the HNSW dimensions for the new encoder if using pgvector. Compare pinned baseline and candidate results, including citations and scoped graph context, before moving HTTP or MCP traffic. Keep the original bundle and serving configuration for rollback. Use a separate local service-state file for the candidate. A query-time HTTP reranker can change without a backfill. PostgreSQL operations
Which changes need indexing?
| Change | Effect after the next scan |
|---|---|
| Text embedding weights, HTTP encoder or revision, document prefix or query prefix | Reprocess affected sources in the new embedding space. For an ordinary text encoder swap, plan for a corpus backfill. Knowledge embeds queries with the encoder that matches the serving vectors. |
| Native multimodal projector or HTTP media encoder | Reprocess affected media and referenced-resource artifacts. A native projector is part of the inferred embedding-space identity, so a projector change can also trigger a text backfill. An incompatible joint encoder pair requires a new shared_space. |
| Vision or transcription model, including ASR language or revision | Regenerate affected captions, OCR or transcripts and embed the resulting text. Unchanged decoder samples and identical text embeddings can be reused. Beta.3 groups several model settings into the media recipe, so other media or URL-backed sources may also queue. |
| Answer generator | New answers use the selected generator after restart. With models.enrich: false, ordinary text enrichment is disabled. Media and URL-backed source recipes can still queue on a generator change. When enrichment is enabled, changed recipes can regenerate summaries, labels and extracted graph facts. |
| HTTP reranker | Takes effect at query time when retrieval.rerank: http is selected. No content backfill is required. |
| Consolidation analysis model | Model mode uses a new analysis recipe for subsequent runs. Existing proposals retain their recorded inputs and review state. A parent evidence version change can invalidate a promoted digest. Generate and review a replacement when needed. |
| Threads, GPU layers, or relocation of identical GGUF files | Execution settings and byte-identical file relocation preserve model identity when the revisions and other semantic settings stay the same. |
If you change several roles together, configure them before one scan. This avoids indexing a sequence of intermediate configurations. A queued source can reuse outputs from unaffected stages. Model contracts · Consolidation
Set the new model identity
- Put native weights at a new versioned path. Set the actual
sha256:<hex>revision for GGUF weights and, if present, the matching projector. Use the document and query prefixes required by the new encoder. Test representative long chunks and image/audio inputs against the new context limits and projector. - For HTTP, update the operation URL, protocol, model ID and
revisionas appropriate. Pin the real deployment behind those fields. A revision string changes Knowledge's recipe identity. The provider still has to serve the corresponding model. If the provider replaces weights under the same name and URL, bump the revision and keep a separately reachable old deployment for any retained vector queries. - Select either
models.embedding.gguformodels.embedding.httpfor text. When selecting an HTTP answer generator throughmodels.chat, removemodels.generationif the native generator currently takes precedence. Setmodels.enrichexplicitly when switching backends so the default enrichment behavior is intentional. - With
models.embedding.shared_space, Knowledge uses your explicit ID for compatibility and for replica vector reuse. Give an incompatible replacement a new versioned ID, even if the dimensions match. Whenmodels.media_embeddingis configured, verify the text and media encoders form one compatible space before using the new ID. A text-only configuration can let Knowledge derive the space from the encoder settings.
Reusing an explicit space ID for incompatible vectors can skip the necessary backfill and compare vectors from different encoders. If that already happened, assign a fresh identity, reindex and resync replica mounts. Native and HTTP configuration examples
Roll out and verify
- Capture a baseline. Save the current config and retain the old weights or endpoint revision. Record the active publication and representative lexical, vector and hybrid results. Budget disk space for old and new artifacts during staging. For a recovery snapshot, run
knowledge -c current.yml backup /private/before-model-change.sqlitewith a new destination. Preserve the matching SQLCipher key separately. A DB backup contains the source revisions observed by Knowledge. Back up any newer on-disk OKF edits separately. - Check the candidate. Run
knowledge -c next.yml --validate-configandknowledge -c next.yml models. These check configuration and show the selected roles. Useknowledge -c pilot.yml probe "calibration procedure"on a pilot config with its own database to run the actual embedding model. Index a small OKF sample to check document embeddings, media extraction, generation or reranking as applicable. Aprobeagainst the live database opens an engine and can set its target recipe, so keep candidate probes off the live database until rollout. - Switch and scan. Stop the old writer, then run
knowledge -c next.yml indexagainst the intended database or restartservewithserver.watch: true.indexscans and drains ready jobs.workdrains existing jobs. If indexing was paused or resource admission is blocking progress, checkknowledge -c next.yml indexing status. - Check the result. Use
knowledge -c next.yml statusto checkfiles,jobsanderrors. After an embedding-space change,files.stagedmeans work has been prepared and is awaiting publication. Useknowledge -c next.yml doctorand retrieval to verify that the expected publication is serving. Test the vector channel as well as lexical and hybrid search, inspect citations and replay the baseline queries. For changed ASR or vision roles, inspect the new text and the page or time locators. For a new answer model or reranker, compare supported answers or ranking on the same queries.
For a server or embedded client, test POST /v1/retrieve or Knowledge::retrieve with a payload like this and verify the returned publication_key and channels against the baseline.
{"query":"calibration procedure","mode":"vector","strict":true,"limit":5}
For a CLI smoke test after the backfill, run knowledge -c next.yml search "calibration procedure" --mode vector. The compatibility search CLI uses the encoder from its current config. The publication-aware API can use a retained recipe while the old space serves. Publication and retrieval behavior
During backfill and rollback
For a changed embedding space, local indexing stages target artifacts and publishes the complete new space together. A failed or deferred job can hold up this cutover. Publication-aware retrieval can keep using the prior view with its recorded encoder if the weights or service, credentials and current network policy still permit it. Keep old GGUF paths and pinned endpoints available for as long as you need vector queries against those retained publications. If an encoder is unavailable, hybrid retrieval can report a missing vector channel. Vector-only and strict retrieval fail in that case. Updates within the same space can publish source by source.
If jobs fail, inspect status.errors, fix the underlying model, policy or resource issue, then run knowledge -c next.yml retry followed by knowledge -c next.yml work or let the watcher drain the queue. If the fix changes the recipe, rescan with index or restart the watcher using the corrected config. rebuild restores index projections from saved artifacts and cannot generate vectors for a new model.
To roll back a model config, stop the new writer, restore the prior config and pinned model files or deployments, then run index or restart the watcher. Verify the resulting publication and query results. This processes the current OKF files with the old recipe and can reuse retained stage caches. To recover the pre-change database and observed sources, point a copy of the prior config at the backup database and use the matching key. Run knowledge -c backup.yml restore /private/recovered.sqlite /private/recovered-okf with a new database path and an existing empty destination root. Point the recovered instance at those two paths. Keep retained publications and the backup through the rollback window. Backup, restore and retention
Publisher, live mount and replica changes
- Publisher model change. Live mounts query the publisher's ranking and need no matching consumer encoder. During publisher backfill a Share can temporarily omit sources whose desired and active versions differ, even while the publisher's local retrieval serves the prior publication. This can affect replica membership too. For a Share that needs continuous coverage, validate a separate instance first and plan the switch with its consumers. If the publisher uses a new remote model origin, review the Share processing policy along with the instance's model network policy.
- Consumer model change. A live mount uses the publisher's embeddings. Local queries and replica mounts use the consumer's encoder. Restart with the new config and run
knowledge -c next.yml federation sync MOUNTfor a replica, or allow scheduled sync to run. With a new space ID, the replica can reuse authorized evidence bodies and build new local vectors even when the publisher's revision stays the same. Check the sync result forstate,embedding_spaceandvectors_enabled. Adeferredresult needs a later run. Verify a vector query with the mount required and check forreplica:vectorin the matches. - Replica transition. While old replica vectors do not match the consumer's config, compatible lexical results may still be available subject to the current lease. Vector-only or strict vector requests can fail until publication. The mount's query-egress setting and the Share's allowed model origins still govern remote encoder and reranker use. Restore the prior consumer config and sync again for a replica rollback.
Federation operations and leases · Indexing resource controls