LlamaIndex 索引存了加载报错，版本要对齐

这类问题我又碰上了一次。把建好的索引持久化到磁盘，服务重启加载时报字段缺失或类型不匹配，只能重建。

第一反应是「存储上下文没有指向同一目录」，验证下来不成立。

这类报错背后常见的原因有几处，逐个排除就行。保存与加载的库版本不一致；嵌入模型换了，向量维度或语义空间变了；文档节点结构变化，旧索引缺字段。

动手时先确认保存与加载的版本一致

python -c "import llama_index.core as c;print(c.__version__)"

接着用同一存储上下文加载

storage = StorageContext.from_defaults(persist_dir='./storage'); idx = load_index_from_storage(storage)

再往下换过嵌入模型就重建索引

python rebuild.py --model bge-m3 --out ./storage

末了加载后做一次检索验证

python -c "print(idx.as_retriever().retrieve('测试')[:1])"

怎么算真的好了，看的是同一批现象。索引加载成功，检索结果与保存前一致，服务启动时间从几分钟降到几秒。

提醒一点。持久化只保存向量和节点，不保存嵌入模型本身，换模型后加载能成功但结果全错，这类问题最难排查。改动前把原配置备份一份，出问题能马上回滚，这比任何技巧都实用。