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

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

记忆管道与知识图谱构建 · 聚焦本章的模块关系、源码依据与实现要点。

项目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
模块标签
  • 存储与持久化
  • 检索、召回与索引
  • 接口与服务契约
  • 界面与交互
  • 配置治理

章节正文

向量数据库适配器

原始 DeepWiki 页面https://deepwiki.com/topoteretes/cognee/5.1-vector-database-adapters

向量数据库适配器

相关源文件

本章引用的主要源码文件：

  • 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，规定了集合管理、数据点操作、搜索和多租户支持的方法。

Cognee · VectorDBInterface 协议 · 图 1
Cognee · VectorDBInterface 协议 · 图 1

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

适配器实现

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

Cognee · 适配器实现 · 图 2
Cognee · 适配器实现 · 图 2
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 实例转换为嵌入向量，并将其与元数据一起存储。

Cognee · 数据点存储流程 · 图 3
Cognee · 数据点存储流程 · 图 3

存储流程通过 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

搜索操作

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

Cognee · 搜索操作 · 图 4
Cognee · 搜索操作 · 图 4
搜索过滤

适配器支持按 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