{
  "id": "llm/embedding-dimension-mismatch-insert",
  "signature": "chromadb.errors.DimensionError: Inserted embedding dimension (512) does not match collection dimension (768)",
  "signature_zh": "chromadb.errors.DimensionError：插入的嵌入维度（512）与集合维度（768）不匹配",
  "regex": "chromadb\\.errors\\.DimensionError: Inserted embedding dimension \\(\\d+\\) does not match collection dimension \\(\\d+\\)",
  "domain": "llm",
  "category": "data_error",
  "subcategory": null,
  "root_cause": "The embedding model used for insertion produces vectors of a different dimensionality than the model used when creating the collection, often due to switching embedding models or using a model with a different output dimension.",
  "root_cause_type": "generic",
  "root_cause_zh": "用于插入的嵌入模型生成的向量维度与创建集合时使用的模型维度不同，通常是由于切换了嵌入模型或使用了不同输出维度的模型。",
  "versions": [
    {
      "version": "chromadb==0.4.22",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "chromadb==0.5.0",
      "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": "openai==1.12.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "",
      "why_fails": "Padding distorts the vector space and ruins retrieval accuracy; the collection's distance metrics expect all vectors to have the same semantic dimensionality.",
      "fail_rate": 0.95,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "ChromaDB infers dimension from the first inserted embedding; if the first insert uses the wrong model, the same mismatch occurs again.",
      "fail_rate": 0.8,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "Reshaping changes the data layout but not the semantic content; distance computations become meaningless and retrieval degrades to random.",
      "fail_rate": 0.9,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Delete the existing collection and recreate it using the same embedding model that you will use for all inserts. For example, in ChromaDB: `client.delete_collection(\"my_collection\"); collection = client.create_collection(name=\"my_collection\", embedding_function=current_embedding_function)`",
      "success_rate": 0.9,
      "how": "Delete the existing collection and recreate it using the same embedding model that you will use for all inserts. For example, in ChromaDB: `client.delete_collection(\"my_collection\"); collection = client.create_collection(name=\"my_collection\", embedding_function=current_embedding_function)`",
      "condition": "",
      "sources": []
    },
    {
      "action": "If you must keep the existing collection, re-embed all existing documents using the new model and re-insert them. Use a script to iterate over all documents, call `embedding_model.encode(doc)`, and upsert into the collection.",
      "success_rate": 0.85,
      "how": "If you must keep the existing collection, re-embed all existing documents using the new model and re-insert them. Use a script to iterate over all documents, call `embedding_model.encode(doc)`, and upsert into the collection.",
      "condition": "",
      "sources": []
    },
    {
      "action": "Explicitly set the embedding function dimension when creating the collection: `collection = client.create_collection(name=\"my_collection\", metadata={\"hnsw:space\": \"cosine\"}, embedding_function=current_embedding_function)` and verify `collection.metadata['dimension']` matches your model output.",
      "success_rate": 0.95,
      "how": "Explicitly set the embedding function dimension when creating the collection: `collection = client.create_collection(name=\"my_collection\", metadata={\"hnsw:space\": \"cosine\"}, embedding_function=current_embedding_function)` and verify `collection.metadata['dimension']` matches your model output.",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "删除现有集合并使用相同的嵌入模型重新创建，该模型将用于所有插入。例如，在 ChromaDB 中：`client.delete_collection(\"my_collection\"); collection = client.create_collection(name=\"my_collection\", embedding_function=current_embedding_function)`",
    "如果必须保留现有集合，请使用新模型重新嵌入所有现有文档并重新插入。使用脚本遍历所有文档，调用 `embedding_model.encode(doc)` 并更新到集合中。",
    "创建集合时显式设置嵌入函数维度：`collection = client.create_collection(name=\"my_collection\", metadata={\"hnsw:space\": \"cosine\"}, embedding_function=current_embedding_function)` 并验证 `collection.metadata['dimension']` 是否与您的模型输出匹配。"
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://docs.trychroma.com/usage-guide#creating-collections",
  "official_doc_section": null,
  "error_code": "DimensionError",
  "verification_tier": "ai_generated",
  "confidence": 0.88,
  "fix_success_rate": 0.85,
  "resolvable": "true",
  "first_seen": "2024-03-15",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}