agentic_huge_data_base / wiki
页面 LightRAG · 3.4 向量数据库实现·DeepWiki 中文全文译文
DeepWiki 中文译文 / LightRAG / 3.4

3.4 · 向量数据库实现（Vector Database Implementations）

轻量图谱增强检索 · 聚焦本章的模块关系、源码依据与实现要点。

项目LightRAG 章节3.4 状态全文译文 模块存储与持久化、检索、召回与索引、界面与交互、记忆与上下文
项目要点页2.5 参考项目 项目章节目录LightRAG DeepWiki 原始章节Vector Database Implementations 上一章3.3 下一章3.5
源码线索
  • docs/MilvusConfigurationGuide.md
  • examples/milvus_kwargs_configuration_demo.py
  • lightrag/kg/deprecated/chroma_impl.py
  • lightrag/kg/faiss_impl.py
  • lightrag/kg/milvus_impl.py
  • lightrag/kg/nano_vector_db_impl.py
  • lightrag/kg/networkx_impl.py
  • lightrag/kg/qdrant_impl.py
  • tests/test_milvus_index_config.py
  • tests/test_milvus_index_creation.py
模块标签
  • 存储与持久化
  • 检索、召回与索引
  • 界面与交互
  • 记忆与上下文
  • 配置治理

章节正文

向量数据库实现

原始 DeepWiki 页面https://deepwiki.com/HKUDS/LightRAG/3.4-vector-database-implementations
此页面内容来自 DeepWiki 重组后的对应页面（来源：4-2.zh.md）

向量存储后端

相关源文件

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

  • docs/MilvusConfigurationGuide.md
  • examples/graph_visual_with_opensearch.py
  • examples/lightrag_openai_opensearch_graph_demo.py
  • examples/milvus_kwargs_configuration_demo.py
  • examples/opensearch_storage_demo.py
  • lightrag/kg/faiss_impl.py
  • lightrag/kg/json_doc_status_impl.py
  • lightrag/kg/json_kv_impl.py
  • lightrag/kg/milvus_impl.py
  • lightrag/kg/mongo_impl.py
  • lightrag/kg/nano_vector_db_impl.py
  • lightrag/kg/neo4j_impl.py
  • lightrag/kg/networkx_impl.py
  • lightrag/kg/opensearch_impl.py
  • lightrag/kg/postgres_impl.py
  • lightrag/kg/qdrant_impl.py
  • lightrag/kg/redis_impl.py
  • tests/test_dimension_mismatch.py
  • tests/test_llm_cache_tools_opensearch.py
  • tests/test_milvus_index_config.py
  • tests/test_milvus_index_creation.py
  • tests/test_milvus_kwargs_bridge.py
  • tests/test_mongo_storage.py
  • tests/test_no_model_suffix_safety.py
  • tests/test_opensearch_storage.py
  • tests/test_postgres_migration.py
  • tests/test_qdrant_migration.py
  • tests/test_unified_lock_safety.py
  • tests/test_workspace_migration_isolation.py

LightRAG 采用可插拔的向量存储架构，将检索增强生成（RAG）引擎与具体数据库实现解耦。这使得用户可以在轻量级本地文件存储和企业级分布式向量数据库之间进行选择。所有后端都实现了 BaseVectorStorage 接口，为向量插入、相似性搜索和删除提供了统一的契约。

架构总览

LightRAG 中的向量存储主要用于三个命名空间：chunks（文本片段）、entities（知识图谱节点）和 relationships（知识图谱边）。每个后端通过工作空间前缀或集合后缀管理数据隔离，确保多个 LightRAG 实例可以共享同一个数据库集群而不会发生冲突。

向量存储接口

所有后端都必须实现 BaseVectorStorage 中定义的以下核心方法：

  • upsert(data: dict[str, dict[str, Any]])：嵌入文本内容并随元数据一起存储。
  • query(query: str, top_k: int, query_embedding: list[float])：执行相似性搜索。
  • delete(ids: list[str])：通过唯一标识符删除向量。
数据流图

下图展示了从自然语言输入到不同后端实现中向量嵌入存储的流程。

向量入库与检索流程

LightRAG · 数据流图 · 图 1
LightRAG · 数据流图 · 图 1

来源：lightrag/base.py:32-32, lightrag/kg/nano_vector_db_impl.py:26-26, lightrag/kg/milvus_impl.py:220-220, lightrag/kg/qdrant_impl.py:119-119, lightrag/kg/postgres_impl.py:143-143

支持的后端

1. NanoVectorDB（默认）

NanoVectorDBStorage 是默认的基于文件的后端，专为本地开发和中小型数据集设计。它在内部使用 nano-vectordb。

  • 存储格式：数据以 JSON 文件形式持久化（例如 vdb_chunks.json），存储在 working_dir 中。lightrag/kg/nano_vector_db_impl.py:55-57
  • 优化：在将向量编码为 Base64 进行存储之前，会使用 zlib 压缩和 Float16 量化。lightrag/kg/nano_vector_db_impl.py:131-135
  • 并发：通过共享内存实现 _storage_lock 和 storage_updated 标志，以处理跨进程更新。lightrag/kg/nano_vector_db_impl.py:68-75
2. Milvus

Milvus 后端提供高性能、可扩展的向量搜索，并具有广泛的索引配置选项。

  • 索引配置：支持 AUTOINDEX、HNSW、IVF_FLAT、DISKANN 和 SCANN。lightrag/kg/milvus_impl.py:24-35
  • 量化：支持 HNSW_SQ，量化类型包括 SQ8、BF16 和 FP16（需要 Milvus 2.6.8+）。lightrag/kg/milvus_impl.py:41-48
  • 集合后缀：自动在集合名称后附加模型特定后缀（例如 _d768），以防止切换嵌入模型时出现维度不匹配。lightrag/kg/milvus_impl.py:270-275
3. Qdrant

Qdrant 实现专注于稳健的数据迁移和工作空间隔离。

  • 工作空间隔离：使用 workspace_id 载荷字段和 models.KeywordIndexParams(is_tenant=True)，确保在单个集合内实现高性能过滤。lightrag/kg/qdrant_impl.py:175-183
  • 旧版迁移：具有复杂的 setup_collection 方法，可以检测旧版 LightRAG 集合并自动将数据迁移到新模式。lightrag/kg/qdrant_impl.py:133-160
4. PostgreSQL（pgvector）

使用 pgvector 扩展在关系数据库中存储向量。

  • 索引类型：支持 HNSW 和 IVFFlat。特别支持 HNSW_HALFVEC 以减少存储占用。lightrag/kg/postgres_impl.py:65-71
  • 标识符安全性：包含 _safe_index_name 工具函数，通过哈希长表名/索引名来处理 PostgreSQL 的 63 字节标识符限制。lightrag/kg/postgres_impl.py:74-104
5. OpenSearch

专为 OpenSearch 3.x+ 设计，使用 k-NN 插件。

  • 分页：针对 3.3.0 及以上版本的集群，使用 _shard_doc 实现高效的 PIT（时间点）分页。lightrag/kg/opensearch_impl.py:72-84
  • 分片：可通过 OPENSEARCH_NUMBER_OF_SHARDS 和 OPENSEARCH_NUMBER_OF_REPLICAS 进行配置。lightrag/kg/opensearch_impl.py:52-57

实现细节

向量插入逻辑

upsert 接口负责批处理文本内容，调用嵌入函数，然后将存储委托给特定后端。

upsert 的内部逻辑（以 NanoVectorDB 为例）：

  1. 元数据准备：过滤输入数据，仅包含允许的 meta_fields。lightrag/kg/nano_vector_db_impl.py:108-115
  2. 批量嵌入：将内容拆分为由 embedding_batch_num 定义的批次。lightrag/kg/nano_vector_db_impl.py:117-126
  3. 向量压缩：（后端特定）对生成的 numpy 数组进行量化和压缩。lightrag/kg/nano_vector_db_impl.py:131-136
  4. 持久化：更新内部客户端，并将存储标记为已更新，以供其他进程使用。lightrag/kg/nano_vector_db_impl.py:137-139
集合后缀生成

为防止在更改嵌入模型（通常会改变向量维度）时出错，Milvus 和 Qdrant 等企业级后端会生成动态集合名称。

后端逻辑示例
Milvus{workspace}_{namespace}_{model_suffix}base_chunks_d1536
PostgreSQL{namespace}_{model_suffix}（表名）chunks_d768

来源：lightrag/kg/milvus_impl.py:272-276, lightrag/kg/postgres_impl.py:260-265

存储生命周期与并发

LightRAG 使用协作锁定机制来管理跨多个进程的向量存储。

进程同步图

LightRAG · 存储生命周期与并发 · 图 2
LightRAG · 存储生命周期与并发 · 图 2

来源：lightrag/kg/shared_storage.py:11-14, lightrag/kg/nano_vector_db_impl.py:77-94, lightrag/kg/faiss_impl.py:83-97

关键函数与类
实体文件路径描述
BaseVectorStoragelightrag/base.py所有向量后端的抽象基类。
MilvusIndexConfiglightrag/kg/milvus_impl.pyHNSW/IVF 索引参数的数据类。
_safe_index_namelightrag/kg/postgres_impl.py确保 PostgreSQL 标识符保持在 63 字节以内。
ClientManagerlightrag/kg/mongo_impl.py用于管理异步数据库客户端的单例。
get_data_init_locklightrag/kg/shared_storage.py全局锁，防止数据库初始化期间的竞态条件。

来源：lightrag/base.py:32, lightrag/kg/milvus_impl.py:75, lightrag/kg/postgres_impl.py:74, lightrag/kg/mongo_impl.py:44, lightrag/kg/shared_storage.py:40