Skip to content

fix(rag): batch LlamaIndex rebuild checkpoints - #2837

Open
Qiuner wants to merge 1 commit into
HKUDS:devfrom
Qiuner:codex/fix-2721-index-checkpoints
Open

Qiuner wants to merge 1 commit into
HKUDS:devfrom
Qiuner:codex/fix-2721-index-checkpoints

Conversation

@Qiuner

@Qiuner Qiuner commented Nov 21, 2026

Copy link
Copy Markdown

Description

LlamaIndex rebuilds currently write the full vector index and BM25 sidecar after every source document. Save a checkpoint after the first source, then after 16 more sources or once 30 seconds have elapsed, whichever comes first at a source boundary. Flush the remaining batch before publishing and mark its sources complete only after the checkpoint has been committed.

Related Issues

Related to #2721, specifically section E on full-index writes during large knowledge-base rebuilds.

Windows validation

Both runs used the same 96 source documents and produced 576 indexed nodes. The embedding provider was replaced with a deterministic local mock. Vector indexing, BM25 construction, snapshot writes, and the flush calls ran on Windows.

Measurement Before After
Full index snapshots 96 7
Cumulative snapshot file bytes 407,635,833 29,888,727
Time spent writing full snapshots 41.87 s 3.29 s
End-to-end rebuild time 47.25 s 9.44 s

The seven checkpoints covered 1, 17, 33, 49, 65, 81, and 96 completed sources.

I also forced the process to exit after it processed source 20, with 17 sources committed. A fresh process reused all 17 checkpointed sources and embedded the remaining 79, including the three that had been processed without a committed checkpoint. With a previously published index present, that index was still readable after the interruption. The resumed rebuild then published a new index containing all 96 sources and 576 nodes.

Modules affected

  • services
  • tests

Checklist

  • Targets dev.
  • Added regression coverage for source-count and elapsed-time checkpoints, final flush, and completion receipts.
  • 49 related tests passed on Windows. Targeted Ruff lint, formatting, and git diff --check passed.
  • pre-commit run --all-files was not run.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant