5.3 · 向量存储配置（Vector Store Configuration）

向量存储配置

向量存储配置

相关源文件

以下文件为本维基页面的生成提供了上下文：

• Makefile
• docs/components/vectordbs/config.mdx
• docs/components/vectordbs/dbs/chroma.mdx
• docs/components/vectordbs/dbs/qdrant.mdx
• docs/components/vectordbs/overview.mdx
• mem0-ts/src/oss/src/vector_stores/pgvector.ts
• mem0-ts/src/oss/src/vector_stores/qdrant.ts
• mem0-ts/src/oss/src/vector_stores/supabase.ts
• mem0-ts/src/oss/tests/pgvector.unit.test.ts
• mem0-ts/src/oss/tests/qdrant-url-port.test.ts
• mem0/configs/rerankers/llm.py
• mem0/reranker/llm_reranker.py
• mem0/utils/factory.py
• mem0/vector_stores/azure_mysql.py
• mem0/vector_stores/cassandra.py
• mem0/vector_stores/configs.py
• poetry.lock
• pyproject.toml
• tests/rerankers/conftest.py
• tests/rerankers/test_llm_reranker_config.py
• tests/rerankers/test_llm_reranker_nested_config.py
• tests/rerankers/test_llm_reranker_rerank.py

目的与范围

本文档详细介绍了 Mem0 中向量存储的配置系统，包括基于 Pydantic 的校验机制、特定于供应商的配置选项、连接管理策略以及索引配置。关于可用的向量存储供应商及其功能，请参阅向量存储供应商。关于向量存储操作（插入、搜索、更新、删除）的详细信息，请参阅向量存储概述。

配置系统概述

Mem0 使用两层配置系统来管理向量存储：

1. VectorStoreConfig：位于 mem0/vector_stores/configs.py:6-67 的顶层配置包装器，负责校验供应商名称并委托给特定于供应商的配置。
2. 特定于供应商的配置类：Pydantic BaseModel 子类（例如 QdrantConfig、ChromaDbConfig、MilvusDBConfig），用于强制实施特定于供应商的参数。

配置流程

使用 VectorStoreConfig 的配置流程

来源：mem0/vector_stores/configs.py:6-67、mem0/utils/factory.py:167-201

VectorStoreConfig 类

位于 mem0/vector_stores/configs.py:6-67 的 VectorStoreConfig 类是所有向量存储配置的入口点：

class VectorStoreConfig(BaseModel):
    provider: str = Field(
        description="向量存储的供应商（例如 'qdrant'、'chroma'、'upstash_vector'）",
        default="qdrant",
    )
    config: Optional[Dict] = Field(description="特定向量存储的配置", default=None)

它维护了所有 24 个以上受支持供应商到其配置类的映射：

位于 mem0/vector_stores/configs.py:40-67 的 validate_and_create_config 校验器会根据供应商名称动态导入并实例化相应的配置类。

来源：mem0/vector_stores/configs.py:6-67

VectorStoreFactory

位于 mem0/utils/factory.py:167-201 的 VectorStoreFactory 会根据校验后的配置实例化向量存储实现：

class VectorStoreFactory:
    provider_to_class = {
        "qdrant": "mem0.vector_stores.qdrant.Qdrant",
        "chroma": "mem0.vector_stores.chroma.ChromaDB",
        "milvus": "mem0.vector_stores.milvus.MilvusDB",
        # ... 另外 21 个供应商
    }

    @classmethod
    def create(cls, provider_name, config):
        class_type = cls.provider_to_class.get(provider_name)
        if class_type:
            vector_store_instance = load_class(class_type)
            return vector_store_instance(**config)
        else:
            raise ValueError(f"不支持的 VectorStore 供应商：{provider_name}")

来源：mem0/utils/factory.py:167-201

通用配置模式

必填字段校验

所有配置类都会强制要求必填字段，并拒绝多余字段，以防止配置错误。它们使用标准的校验器模式：

@model_validator(mode="before")
@classmethod
def validate_extra_fields(cls, values: Dict[str, Any]) -> Dict[str, Any]:
    allowed_fields = set(cls.model_fields.keys())
    input_fields = set(values.keys())
    extra_fields = input_fields - allowed_fields
    if extra_fields:
        raise ValueError(
            f"不允许有多余字段：{', '.join(extra_fields)}。请仅输入以下字段：{', '.join(allowed_fields)}"
        )
    return values

来源：mem0/configs/vector_stores/qdrant.py:35-46、mem0/configs/vector_stores/chroma.py:46-57

默认值

配置类为常用参数提供了合理的默认值：

来源：mem0/configs/vector_stores/qdrant.py:11-19、mem0/configs/vector_stores/chroma.py:13-20、mem0-ts/src/oss/src/vector_stores/pgvector.ts:31-40

特定于供应商的配置

Qdrant 配置

QdrantConfig 支持本地、远程服务器和云部署。在 TypeScript 实现中，QdrantConfig 还支持传入一个预配置的 QdrantClient 实例 mem0-ts/src/oss/src/vector_stores/qdrant.ts:6-31。

配置参数

位于 mem0/configs/vector_stores/qdrant.py:21-33 的校验器 check_host_port_or_path 会确保提供了 path、host+port 或 url+api_key 中的一组。

来源：mem0/configs/vector_stores/qdrant.py:6-48、mem0/vector_stores/qdrant.py:30-41、mem0-ts/src/oss/src/vector_stores/qdrant.ts:6-31

PGVector 配置（TypeScript）

TypeScript 实现的 PGVector 提供了详细的连接参数，并支持 diskann 和 hnsw 等高级索引 mem0-ts/src/oss/src/vector_stores/pgvector.ts:31-40。

来源：mem0-ts/src/oss/src/vector_stores/pgvector.ts:31-40

Supabase 配置（TypeScript）

TypeScript 中的 SupabaseDB 需要 supabaseUrl 和 supabaseKey，并允许自定义表和列的名称 mem0-ts/src/oss/src/vector_stores/supabase.ts:25-31。

来源：mem0-ts/src/oss/src/vector_stores/supabase.ts:25-31

混合搜索与模式迁移

Qdrant 混合搜索（v3）

在 Mem0 v3 中，Qdrant 实现会通过创建一个 bm25 稀疏向量槽位来自动尝试启用混合搜索（Dense + BM25），相关代码位于 mem0/vector_stores/qdrant.py:146-154。

迁移处理

对于 v3 之前创建的现有集合，系统会检查 bm25 槽位是否存在。如果缺失，系统会记录一条警告，并回退到仅使用语义搜索，以保持兼容性，无需手动迁移 mem0/vector_stores/qdrant.py:134-142。

Milvus 混合搜索（v3）

类似地，MilvusDB 会创建一个包含 text 字段和 sparse 向量字段的模式，该稀疏向量字段通过 BM25 Function 填充，相关代码位于 mem0/vector_stores/milvus.py:84-116。

迁移处理

如果现有集合缺少 text 或 sparse 字段，MilvusDB 会将 _has_bm25_schema 设置为 False，并针对该特定集合禁用混合评分 mem0/vector_stores/milvus.py:72-82。

来源：mem0/vector_stores/qdrant.py:120-157、mem0/vector_stores/milvus.py:58-116

连接管理

PGVector 初始化（TypeScript）

PGVector 实现采用两阶段连接策略：首先连接到默认的 postgres 数据库以检查或创建目标数据库，然后重新连接到目标数据库以初始化向量扩展和表 mem0-ts/src/oss/src/vector_stores/pgvector.ts:82-125。

PGVector 初始化流程（TypeScript）

来源：mem0-ts/src/oss/src/vector_stores/pgvector.ts:82-125

Qdrant 客户端初始化流程

Qdrant.__init__() 实现了一套灵活的优先级系统来设置客户端：

Qdrant 客户端初始化流程

来源：mem0/vector_stores/qdrant.py:57-76

校验与错误处理

默认路径分配

如果某个供应商需要 path 参数但用户未提供，VectorStoreConfig 会自动分配一个默认的临时路径（例如 /tmp/qdrant）mem0/vector_stores/configs.py:62-64。

自定义维度错误

一个常见的配置问题发生在使用维度不同于默认值（1536）的嵌入模型时。这会在搜索或插入过程中导致 ValueError：ValueError: shapes (0,1536) and (768,) not aligned。 解决方案：在向量存储配置中显式设置 embedding_model_dims（Python）或 embeddingModelDims（TypeScript）docs/components/vectordbs/overview.mdx:47-54。

来源：mem0/vector_stores/configs.py:62-67、docs/components/vectordbs/overview.mdx:47-54、mem0-ts/src/oss/src/vector_stores/pgvector.ts:31-40