agentic_huge_data_base / wiki
页面 Cognee · 5.1 向量数据库 Adapters·DeepWiki 中文全文译文
DeepWiki 中文译文 / Cognee / 5.1

5.1 · 向量数据库 Adapters（Vector Database Adapters）

记忆管道与知识图谱构建 · 本章是 Cognee DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目Cognee 章节5.1 状态全文译文 模块存储与持久化、检索、召回与索引、接口与服务契约、界面与交互
项目要点页2.5 参考项目 项目章节目录Cognee DeepWiki 原始章节Vector Database Adapters 上一章5 下一章5.2
源码线索
  • cognee/base_config.py
  • cognee/context_global_variables.py
  • cognee/infrastructure/databases/graph/config.py
  • cognee/infrastructure/databases/graph/get_graph_engine.py
  • cognee/infrastructure/databases/graph/graph_db_interface.py
  • cognee/infrastructure/databases/graph/kuzu/adapter.py
  • cognee/infrastructure/databases/graph/neo4j_driver/adapter.py
  • cognee/infrastructure/databases/utils/get_or_create_dataset_database.py
  • cognee/infrastructure/databases/vector/chromadb/ChromaDBAdapter.py
  • cognee/infrastructure/databases/vector/config.py
模块标签
  • 存储与持久化
  • 检索、召回与索引
  • 接口与服务契约
  • 界面与交互
  • 配置治理

中文译文

向量数据库 Adapters（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/topoteretes/cognee/5.1-vector-database-adapters
翻译时间：2026-05-27T08:45:18.595Z
翻译模型：deepseek-chat
原文字符数：14227
项目：Cognee (cognee)

---

向量数据库适配器

相关源文件

以下文件用于生成此维基页面：

  • cognee/base_config.py
  • cognee/context_global_variables.py
  • cognee/infrastructure/databases/graph/config.py
  • cognee/infrastructure/databases/graph/get_graph_engine.py
  • cognee/infrastructure/databases/graph/graph_db_interface.py
  • cognee/infrastructure/databases/graph/kuzu/adapter.py
  • cognee/infrastructure/databases/graph/neo4j_driver/adapter.py
  • cognee/infrastructure/databases/utils/get_or_create_dataset_database.py
  • cognee/infrastructure/databases/vector/chromadb/ChromaDBAdapter.py
  • cognee/infrastructure/databases/vector/config.py
  • cognee/infrastructure/databases/vector/create_vector_engine.py
  • cognee/infrastructure/databases/vector/get_vector_engine.py
  • cognee/infrastructure/databases/vector/lancedb/LanceDBAdapter.py
  • cognee/infrastructure/databases/vector/pgvector/PGVectorAdapter.py
  • cognee/infrastructure/databases/vector/vector_db_interface.py
  • cognee/modules/users/models/DatasetDatabase.py
  • cognee/root_dir.py
  • cognee/shared/lru_cache.py

向量数据库适配器提供了一个统一接口，用于在多个向量数据库提供者之间存储和检索嵌入向量。这些适配器实现了语义搜索能力，通过余弦距离或其他向量相似度指标，支持基于相似性的数据点检索。

关于图数据库存储和关系，请参阅图数据库适配器。关于关系型元数据存储，请参阅关系型数据库适配器。关于配置要使用的向量数据库，请参阅数据库配置与选择。

VectorDBInterface 协议

VectorDBInterface 协议定义了所有向量数据库适配器必须实现的契约。该协议位于 cognee/infrastructure/databases/vector/vector_db_interface.py:17-265，规定了集合管理、数据点操作、搜索和多租户支持的方法。

graph TB
    VectorDBInterface["VectorDBInterface<br/>（协议）"]

    subgraph "核心方法"
        HasCollection["has_collection(collection_name)"]
        CreateCollection["create_collection(collection_name, payload_schema)"]
        CreateDataPoints["create_data_points(collection_name, data_points)"]
        Retrieve["retrieve(collection_name, data_point_ids)"]
        Search["search(collection_name, query_text/vector, limit)"]
        BatchSearch["batch_search(collection_name, query_texts, limit)"]
        DeleteDataPoints["delete_data_points(collection_name, data_point_ids)"]
        Prune["prune()"]
        EmbedData["embed_data(data)"]
    end

    subgraph "可选方法"
        GetConnection["get_connection()"]
        GetCollection["get_collection(collection_name)"]
        CreateVectorIndex["create_vector_index(index_name, index_property_name)"]
        IndexDataPoints["index_data_points(index_name, index_property_name, data_points)"]
        GetDataPointSchema["get_data_point_schema(model_type)"]
    end

    subgraph "多租户方法"
        CreateDataset["create_dataset(dataset_id, user)"]
        DeleteDataset["delete_dataset(dataset_id, user)"]
    end

    VectorDBInterface --> HasCollection
    VectorDBInterface --> CreateCollection
    VectorDBInterface --> CreateDataPoints
    VectorDBInterface --> Retrieve
    VectorDBInterface --> Search
    VectorDBInterface --> BatchSearch
    VectorDBInterface --> DeleteDataPoints
    VectorDBInterface --> Prune
    VectorDBInterface --> EmbedData
    VectorDBInterface -.可选.-> GetConnection
    VectorDBInterface -.可选.-> GetCollection
    VectorDBInterface -.可选.-> CreateVectorIndex
    VectorDBInterface -.可选.-> IndexDataPoints
    VectorDBInterface -.可选.-> GetDataPointSchema
    VectorDBInterface -.多租户.-> CreateDataset
    VectorDBInterface -.多租户.-> DeleteDataset

来源： cognee/infrastructure/databases/vector/vector_db_interface.py:17-265

适配器实现

Cognee 通过专用的适配器类支持多个向量数据库提供者。每个适配器都实现了 VectorDBInterface 协议，同时处理提供者特定的功能和优化。

graph LR
    VectorDBInterface["VectorDBInterface<br/>（协议）"]

    PGVectorAdapter["PGVectorAdapter"]
    LanceDBAdapter["LanceDBAdapter"]
    ChromaDBAdapter["ChromaDBAdapter"]
    OtherAdapters["QdrantAdapter<br/>WeaviateAdapter<br/>MilvusAdapter"]

    VectorDBInterface --> PGVectorAdapter
    VectorDBInterface --> LanceDBAdapter
    VectorDBInterface --> ChromaDBAdapter
    VectorDBInterface --> OtherAdapters

    EmbeddingEngine["EmbeddingEngine"]

    PGVectorAdapter --> EmbeddingEngine
    LanceDBAdapter --> EmbeddingEngine
    ChromaDBAdapter --> EmbeddingEngine

    SQLAlchemyAdapter["SQLAlchemyAdapter"]
    PGVectorAdapter --> SQLAlchemyAdapter

    PGVectorAdapter --> PostgreSQL["PostgreSQL<br/>带 pgvector"]
    LanceDBAdapter --> LanceDB["LanceDB"]
    ChromaDBAdapter --> ChromaDB["ChromaDB"]
PGVectorAdapter

PGVectorAdapter 提供对 PostgreSQL 与 pgvector 扩展的支持，将向量存储为 PostgreSQL 原生列。它同时继承自 SQLAlchemyAdapter 和 VectorDBInterface，复用了 SQLAlchemy 的异步会话管理 cognee/infrastructure/databases/vector/pgvector/PGVectorAdapter.py:51-52。

主要特性：

  • 通过 pgvector.sqlalchemy.Vector 使用 PostgreSQL 原生向量列类型 cognee/infrastructure/databases/vector/pgvector/PGVectorAdapter.py:96-98。
  • 在可能的情况下与关系型数据库复用引擎，并遵循 backend_access_control_enabled 设置 cognee/infrastructure/databases/vector/pgvector/PGVectorAdapter.py:69-92。
  • 针对死锁、唯一约束冲突和重复表错误的重试逻辑 cognee/infrastructure/databases/vector/pgvector/PGVectorAdapter.py:147-153。
  • 支持 JSON 载荷存储，实现灵活的模式 cognee/infrastructure/databases/vector/pgvector/PGVectorAdapter.py:170。
  • 使用 PostgreSQL 操作符按 belongs_to_set 进行过滤 cognee/infrastructure/databases/vector/pgvector/PGVectorAdapter.py:48。

来源： cognee/infrastructure/databases/vector/pgvector/PGVectorAdapter.py:51-175, cognee/context_global_variables.py:83-92

LanceDBAdapter

LanceDBAdapter 提供与 LanceDB 的集成，LanceDB 是一个针对 AI 应用优化的嵌入式向量数据库。它具备强大的子进程模式，用于处理并发环境中本地 LanceDB 文件常见的文件锁定问题 cognee/infrastructure/databases/vector/lancedb/LanceDBAdapter.py:108-133。

主要特性：

  • 子进程代理：支持 create_subprocess 模式，将 LanceDB 操作卸载到专用工作进程，防止数据库损坏和锁竞争 cognee/infrastructure/databases/vector/lancedb/LanceDBAdapter.py:108-133。
  • 内存管理：使用类级别的记忆化缓存（_payload_schema_cache、_lance_datapoint_class_cache），并配合有界 LRU（最近最少使用）策略，防止动态 Pydantic 类生成导致的内存泄漏 cognee/infrastructure/databases/vector/lancedb/LanceDBAdapter.py:101-105。
  • 类型化模式：使用 LanceModel 实现 LanceDataPoint 模式，并带有类型化的向量维度 cognee/infrastructure/databases/vector/lancedb/LanceDBAdapter.py:307-319。
  • OpenTelemetry：集成 new_span 用于追踪数据库操作，如搜索和集合创建 cognee/infrastructure/databases/vector/lancedb/LanceDBAdapter.py:28-33。

来源： cognee/infrastructure/databases/vector/lancedb/LanceDBAdapter.py:73-133, cognee/infrastructure/databases/vector/lancedb/LanceDBAdapter.py:101-105

ChromaDBAdapter

ChromaDBAdapter 提供与 ChromaDB 的集成，支持本地和远程部署，并支持令牌认证。

主要特性：

  • 序列化：处理复杂数据类型（UUID、字典、列表），通过添加类型后缀（例如 __dict、__list）将其转换为字符串，以满足 ChromaDB 扁平元数据的要求 cognee/infrastructure/databases/vector/chromadb/ChromaDBAdapter.py:56-90。
  • 反序列化：在检索时通过解析存储的类型后缀，自动恢复原始 Python 类型 cognee/infrastructure/databases/vector/chromadb/ChromaDBAdapter.py:93-146。
  • 异步 HTTP：使用 AsyncHttpClient 实现与远程 ChromaDB 实例的非阻塞通信 cognee/infrastructure/databases/vector/chromadb/ChromaDBAdapter.py:167-183。

来源： cognee/infrastructure/databases/vector/chromadb/ChromaDBAdapter.py:56-183

数据点存储流程

向量数据库适配器将 DataPoint 实例转换为嵌入向量，并将其与元数据一起存储。

sequenceDiagram
    participant Pipeline as "数据管线"
    participant Adapter as "VectorDBAdapter"
    participant EmbedEngine as "EmbeddingEngine"
    participant VectorDB as "向量数据库"

    Pipeline->>Adapter: create_data_points(collection_name, data_points)

    Adapter->>Adapter: 检查/创建集合

    Adapter->>EmbedEngine: embed_text(texts)
    EmbedEngine-->>Adapter: vectors (List[List[float]])

    Adapter->>Adapter: 序列化载荷（DataPoint -> Dict）

    Adapter->>VectorDB: 批量 Upsert（向量 + 元数据）
    VectorDB-->>Adapter: 成功

    Adapter-->>Pipeline: 返回 data_points

存储流程通过 create_vector_engine 进行编排，该引擎应用缓存和规范化，确保适配器实例的一致性 cognee/infrastructure/databases/vector/create_vector_engine.py:48-59。

来源： cognee/infrastructure/databases/vector/lancedb/LanceDBAdapter.py:177-196, cognee/infrastructure/databases/vector/create_vector_engine.py:48-109

搜索操作

向量适配器提供支持文本和向量查询的搜索方法，并支持按节点集进行高级过滤。

graph TB
    SearchCall["search(collection_name, query_text, limit, node_name)"]

    CheckParams{查询文本<br/>还是向量？}
    SearchCall --> CheckParams

    EmbedQuery["embed_text([query_text])"]
    CheckParams -->|仅文本| EmbedQuery
    CheckParams -->|提供向量| VectorSearch

    EmbedQuery --> VectorSearch["向量相似度搜索"]

    NodeFilter{提供了<br/>node_name？}
    VectorSearch --> NodeFilter

    FilteredSearch["使用<br/>belongs_to_set 过滤搜索"]
    UnfilteredSearch["搜索所有<br/>数据点"]

    NodeFilter -->|是| FilteredSearch
    NodeFilter -->|否| UnfilteredSearch

    FilteredSearch --> Results["原始结果<br/>带距离"]
    UnfilteredSearch --> Results
搜索过滤

适配器支持按 belongs_to_set 字段进行过滤。这允许将检索范围限定到特定的逻辑子图或文档集。

  • PGVector：对 belongs_to_set 列使用 PostgreSQL 数组包含操作 cognee/infrastructure/databases/vector/pgvector/PGVectorAdapter.py:48。
  • LanceDB：使用 LanceDB 的 SQL 风格过滤表达式实现过滤 cognee/infrastructure/databases/vector/lancedb/LanceDBAdapter.py:54-71。

来源： cognee/infrastructure/databases/vector/pgvector/PGVectorAdapter.py:36-49, cognee/infrastructure/databases/vector/lancedb/LanceDBAdapter.py:54-71

索引操作

系统使用专门的模式来标准化存储在向量索引中的数据。

IndexSchema

IndexSchema 类是一个专门的 DataPoint，用于标准化存储在向量索引中的数据 cognee/infrastructure/databases/vector/pgvector/PGVectorAdapter.py:36-49, cognee/infrastructure/databases/vector/lancedb/LanceDBAdapter.py:54-71。

字段类型描述
idstr索引片段的唯一标识符
textstr被嵌入的实际内容
metadatadict索引字段的配置（例如 {"index_fields": ["text"]}）
belongs_to_setList[str]用于限定检索范围的集合标识符列表

来源： cognee/infrastructure/databases/vector/pgvector/PGVectorAdapter.py:36-49, cognee/infrastructure/databases/vector/lancedb/LanceDBAdapter.py:54-71

多租户访问控制

当 ENABLE_BACKEND_ACCESS_CONTROL 为 true 时，Cognee 在数据库级别隔离向量数据 cognee/context_global_variables.py:83-92。

  1. 上下文管理：DatabaseContextManager 设置活动的数据集和用户上下文 cognee/context_global_variables.py:108-115。
  2. 数据库解析：get_or_create_dataset_database 检索或创建一个特定的 DatasetDatabase 记录，其中包含该用户/数据集对的提供者特定连接信息 cognee/infrastructure/databases/utils/get_or_create_dataset_database.py:64-82。
  3. 支持的提供者：目前已验证 lancedb、pgvector 和 falkor 支持多租户 cognee/context_global_variables.py:95。

来源： cognee/context_global_variables.py:83-150, cognee/infrastructure/databases/utils/get_or_create_dataset_database.py:64-110