{
  "id": "llm/llamaindex-embedding-model-mismatch-on-retrieval",
  "signature": "ValueError: Embedding dimension mismatch: query embedding dimension (384) does not match index embedding dimension (768)",
  "signature_zh": "ValueError: 嵌入维度不匹配：查询嵌入维度（384）与索引嵌入维度（768）不匹配",
  "regex": "ValueError: Embedding dimension mismatch: query embedding dimension \\(\\d+\\) does not match index embedding dimension \\(\\d+\\)",
  "domain": "llm",
  "category": "config_error",
  "subcategory": null,
  "root_cause": "LlamaIndex retrieves a query using an embedding model with a different output dimension than the model used to build the vector index, often due to changing the embed_model config after index construction.",
  "root_cause_type": "generic",
  "root_cause_zh": "LlamaIndex使用与构建向量索引时不同的输出维度的嵌入模型来检索查询，通常是由于在索引构建后更改了embed_model配置。",
  "versions": [
    {
      "version": "llama-index 0.10.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "llama-index 0.10.15",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "llama-index 0.10.30",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "sentence-transformers 2.2.2",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "sentence-transformers 3.0.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "",
      "why_fails": "Reshaping distorts the embedding space, producing semantically meaningless similarity scores and retrieval results.",
      "fail_rate": 0.8,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "The default embedding model may still have a different dimension than the one used during indexing, unless it's the exact same model.",
      "fail_rate": 0.5,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Rebuild the index with the same embedding model used for queries:\n\nfrom llama_index.core import VectorStoreIndex, Settings\nfrom llama_index.embeddings.huggingface import HuggingFaceEmbedding\n\nembed_model = HuggingFaceEmbedding(model_name='BAAI/bge-small-en-v1.5')\nSettings.embed_model = embed_model\nindex = VectorStoreIndex.from_documents(documents, embed_model=embed_model)",
      "success_rate": 0.95,
      "how": "Rebuild the index with the same embedding model used for queries:\n\nfrom llama_index.core import VectorStoreIndex, Settings\nfrom llama_index.embeddings.huggingface import HuggingFaceEmbedding\n\nembed_model = HuggingFaceEmbedding(model_name='BAAI/bge-small-en-v1.5')\nSettings.embed_model = embed_model\nindex = VectorStoreIndex.from_documents(documents, embed_model=embed_model)",
      "condition": "",
      "sources": []
    },
    {
      "action": "Persist the embedding model name in index metadata and validate on load:\n\nfrom llama_index.core import StorageContext, load_index_from_storage\n\nstorage_context = StorageContext.from_defaults(persist_dir='./index')\nindex = load_index_from_storage(storage_context)\nif index.embed_model != current_embed_model:\n    raise ValueError(f\"Embed model mismatch: index uses {index.embed_model}\")",
      "success_rate": 0.9,
      "how": "Persist the embedding model name in index metadata and validate on load:\n\nfrom llama_index.core import StorageContext, load_index_from_storage\n\nstorage_context = StorageContext.from_defaults(persist_dir='./index')\nindex = load_index_from_storage(storage_context)\nif index.embed_model != current_embed_model:\n    raise ValueError(f\"Embed model mismatch: index uses {index.embed_model}\")",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "使用与查询相同的嵌入模型重建索引：\n\nfrom llama_index.core import VectorStoreIndex, Settings\nfrom llama_index.embeddings.huggingface import HuggingFaceEmbedding\n\nembed_model = HuggingFaceEmbedding(model_name='BAAI/bge-small-en-v1.5')\nSettings.embed_model = embed_model\nindex = VectorStoreIndex.from_documents(documents, embed_model=embed_model)",
    "在索引元数据中持久化嵌入模型名称，并在加载时验证：\n\nfrom llama_index.core import StorageContext, load_index_from_storage\n\nstorage_context = StorageContext.from_defaults(persist_dir='./index')\nindex = load_index_from_storage(storage_context)\nif index.embed_model != current_embed_model:\n    raise ValueError(f\"嵌入模型不匹配：索引使用{index.embed_model}\")"
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://docs.llamaindex.ai/en/stable/module_guides/loading/embeddings/",
  "official_doc_section": null,
  "error_code": null,
  "verification_tier": "ai_generated",
  "confidence": 0.89,
  "fix_success_rate": 0.9,
  "resolvable": "true",
  "first_seen": "2024-04-12",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}