# 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](https://tsok.org/knowledge/docs/configuration/)

## 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](https://tsok.org/knowledge/docs/postgres-index/)

## 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](https://tsok.org/knowledge/docs/models/) · [Consolidation](https://tsok.org/knowledge/docs/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 `revision` as 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.gguf` or `models.embedding.http` for text. When selecting an HTTP answer generator through `models.chat`, remove `models.generation` if the native generator currently takes precedence. Set `models.enrich` explicitly 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. When `models.media_embedding` is 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](https://tsok.org/knowledge/docs/configuration/#models-by-role)

## Roll out and verify

1. **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.sqlite` with 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.
2. **Check the candidate.** Run `knowledge -c next.yml --validate-config` and `knowledge -c next.yml models`. These check configuration and show the selected roles. Use `knowledge -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. A `probe` against the live database opens an engine and can set its target recipe, so keep candidate probes off the live database until rollout.
3. **Switch and scan.** Stop the old writer, then run `knowledge -c next.yml index` against the intended database or restart `serve` with `server.watch: true`. `index` scans and drains ready jobs. `work` drains existing jobs. If indexing was paused or resource admission is blocking progress, check `knowledge -c next.yml indexing status`.
4. **Check the result.** Use `knowledge -c next.yml status` to check `files`, `jobs` and `errors`. After an embedding-space change, `files.staged` means work has been prepared and is awaiting publication. Use `knowledge -c next.yml doctor` and 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.

```json
{"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](https://tsok.org/knowledge/docs/retrieval/)

## 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](https://tsok.org/knowledge/docs/retrieval/#migration-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 MOUNT` for 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 for `state`, `embedding_space` and `vectors_enabled`. A `deferred` result needs a later run. Verify a vector query with the mount required and check for `replica:vector` in 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](https://tsok.org/knowledge/docs/federation/) · [Indexing resource controls](https://tsok.org/knowledge/docs/indexing-resources/)
