LlamaIndex (RAG / Agent / Workflow)

WHENWhen porting code from a llama-index v0.9 era tutorial / blog / Stack Overflow answer that constructs a ServiceContext object

ACTIONDelete every ServiceContext.from_defaults / ServiceContext(...) / set_global_service_context(...) call. Replace with attribute assignments on the module-level Settings singleton (e.g. Settings.llm = OpenAI(...), Settings.embed_model = OpenAIEmbedding(...), Settings.node_parser = SentenceSplitter(chunk_overlap=20)) BEFORE any index/query construction. Do not pass a ServiceContext kwarg to BaseIndex.from_documents.

CONSEQUENCEundefined behavior

WHENWhen designing a workflow where the index is persisted to storage today and re-loaded later (possibly by a different process / different developer) for query

ACTIONDo not rely on storage_context to remember which embedder built the index. Treat the embed model identity as caller-managed state — always reconstruct the index with the same explicit embed_model that was used at index time, or fail loudly when re-loading. Read llamaindex-C-004 for the remedy.

CONSEQUENCEundefined behavior

WHENWhen persisting an index to disk / vector store today for later re-load and query

ACTIONAt index time: write a sidecar file (e.g. {storage_dir}/embed_model.json) with {'provider_class': type(embed_model).__module__ + '.' + type(embed_model).__name__, 'model_name': getattr(embed_model, 'model_name', None), 'embed_dim': getattr(embed_model, 'embed_dim', None) or len(embed_model.get_text_embedding('probe'))}. At re-load: read the sidecar, compare against Settings.embed_model or the embed_model passed to load_index_from_storage, raise EmbedModelMismatchError on any drift. Do not fall back to the new embedder.

CONSEQUENCEundefined behavior