Recipe: refuse to query an index built with other settings
Store the settings when you build the index and run this check at startup and before every rebuild.
Recipes to copy into any project: a batching embed client with retry and a unit-length check, a cache keyed by model and content, and a guard that refuses to query an index with the wrong model settings. Plus the checklist for changing models.
Change the code and press Run (Ctrl+Enter). Predict what will happen first, then break it on purpose and read what changes. Your edits are saved and match the lesson page.
Ready for more? This phase has 5 hands-on exercises with automatic checks.
Practice questions
Write the code in the editor, run it, then open the model answer to compare.
Write with_retry(fn, attempts) that calls fn() and retries when it raises RuntimeError, up to attempts calls in total, and re-raises the last error. Test it with a function that fails twice and then returns "ok", and print the result and the number of calls.
Write check_settings(stored, live) that returns a list of the names of the keys whose values differ. Print the result for stored = {"model": "v1", "dims": 384} and live = {"model": "v2", "dims": 384}.
Explain it without notes
What does a production embedding client do that a ten-line script does not?
Why store the index's settings next to the vectors?
Walk through the safe steps of switching to a new embedding model.
Why is checking that vectors have length 1 worth its own recipe?
Expected output
same settings: ok, safe to query
new model, new size: BLOCKED (2)
- model changed (embed-v1 -> embed-v2): old and new vectors cannot be compared, re-embed everything
- dimensions changed (384 -> 768): the index cannot hold these vectors
prefixes added: BLOCKED (1)
- prefixes changed: queries and passages must be prepared the same way as when the index was built
vectors no longer normalised: BLOCKED (1)
- normalisation changed (yes -> no): scores would no longer be cosine