# ValueError: 嵌入维度不匹配：查询嵌入维度（384）与索引嵌入维度（768）不匹配

- **ID:** `llm/llamaindex-embedding-model-mismatch-on-retrieval`
- **领域:** llm
- **类别:** config_error
- **验证级别:** ai_generated
- **修复率:** 90%

## 根因

LlamaIndex使用与构建向量索引时不同的输出维度的嵌入模型来检索查询，通常是由于在索引构建后更改了embed_model配置。

## 版本兼容性

| 版本 | 状态 | 引入 | 弃用 |
|------|------|------|------|
| llama-index 0.10.0 | active | — | — |
| llama-index 0.10.15 | active | — | — |
| llama-index 0.10.30 | active | — | — |
| sentence-transformers 2.2.2 | active | — | — |
| sentence-transformers 3.0.0 | active | — | — |

## 解决方案

1. ```
   使用与查询相同的嵌入模型重建索引：

from llama_index.core import VectorStoreIndex, Settings
from llama_index.embeddings.huggingface import HuggingFaceEmbedding

embed_model = HuggingFaceEmbedding(model_name='BAAI/bge-small-en-v1.5')
Settings.embed_model = embed_model
index = VectorStoreIndex.from_documents(documents, embed_model=embed_model)
   ```
2. ```
   在索引元数据中持久化嵌入模型名称，并在加载时验证：

from llama_index.core import StorageContext, load_index_from_storage

storage_context = StorageContext.from_defaults(persist_dir='./index')
index = load_index_from_storage(storage_context)
if index.embed_model != current_embed_model:
    raise ValueError(f"嵌入模型不匹配：索引使用{index.embed_model}")
   ```

## 无效尝试

- **** — Reshaping distorts the embedding space, producing semantically meaningless similarity scores and retrieval results. (80% 失败率)
- **** — The default embedding model may still have a different dimension than the one used during indexing, unless it's the exact same model. (50% 失败率)