Skip to main content
A new embedding model enters as an evaluation space of your ingestion plugin. Articles ingested from then on get vectors in it, but the ones you already have do not. A backfill fills that space for a Corpus’s past articles, at low priority, and a promotion then makes search use it.

​
Prerequisites

  • A version of your ingestion plugin whose manifest declares the new space, activated with it as evaluation and the current one as served (see Switch plugins without restarting). It must cut articles into the same segments as the version that ingested them.
  • A key of the Organization that owns the Corpus with the actions plugins:admin, operations:read (to follow the backfill) and operations:write (to pause, resume or cancel it), in QUIVR_OPERATOR_KEY, and the Corpus id in CORPUS_ID.
  • Optional: an input_price on the new space in the manifest (usd_per_million_tokens), so the estimate shows a cost. Without it the cost is unknown.

​
Steps

1

Estimate it

A dry run is required. It counts the articles to fill and estimates how long it takes and what it costs:
spaces defaults to the evaluation spaces of the active ingestion plugin; name them in spaces to choose. To fill only part of the Corpus, add accepted_after or accepted_before: the time Quivr accepted each article. estimated_seconds uses the deployment’s backfill.rate, or the recent throughput when it is slower (duration_basis).
2

Start it

Send the same body with dry_run set to false. When confirmation_required is true, because the cost exceeds backfill.max_cost_without_confirmation, add "confirm_cost": true:
The answer is an Operation, Quivr’s record of a long-running administrative task. The same key and body return the same Operation. Keep its id:
3

Follow it

counters shows versions_in_scope, versions_done, versions_skipped and segments. One backfill of a Corpus runs at a time: another one is refused with 409 backfill_in_progress until it ends. Pause, resume or cancel it with POST /v0/operations/{id}/pause, /resume or /cancel, each with an idempotency_key body. A paused or restarted backfill continues after its checkpoint and never fills an article twice.
4

Promote the space

When the Operation is succeeded, make search use the new space:
A promotion applies to the whole deployment. It is refused with 409 coverage_incomplete while some Corpus has current articles without a vector in the space: backfill those Corpora first. {"force": true} promotes anyway, and the articles without a vector drop out of semantic results until a backfill fills them.

​
Check it worked

The new space is served and covers every segment. Semantic hits name it in vector_space_id.

​
Go back to the previous model

Promote the former space the same way. It stayed an evaluation space and kept its vectors, so search uses it again at once. A promotion survives restarts, activations and rollbacks while the ingestion plugin enables both spaces. Once a plugin version stops declaring one of them, its own spaces settings decide again.

​
How a backfill runs

  • It runs on its own worker queue, one article at a time, at most backfill.rate articles per second (see Configuration), so live ingestion keeps its capacity.
  • It is pinned to the Pipeline Plan active when it started, like other work, and fails with pinned_plugin_unavailable or pinned_plan_stopped rather than moving to another plugin version.
  • On its first step, the Corpus’s search index starts carrying the new space, so articles ingested from then on get their vectors from live ingestion. The backfill fills only the articles that already had theirs.
  • It creates no new Version and no content event in the change feed. Articles outside its window are not touched.
  • An article the plugin now cuts into other segments is skipped and counted as skipped_segmentation_differs: rebuild the Corpus to re-cut it (see Write an ingestion plugin). A refusal by the plugin is counted as skipped_ingestion_refused, and an article the plugin cannot embed within its deadline as skipped_plugin_deadline. Rerun the backfill to try skipped articles again.

​
Troubleshooting