Introduction to LightRAG: A Lightweight, High-Performance Knowledge Graph-Augmented Retrieval Framework

在当今信息爆炸的时代，如何从海量非结构化文档中高效、准确地检索和生成信息，是人工智能领域面临的核心挑战之一。检索增强生成（RAG）技术通过将外部知识库与大型语言模型（LLM）相结合，显著提升了模型回答的准确性和事实性。然而，传统的基于向量相似度的RAG系统在处理复杂、多跳的推理问题时，往往显得力不从心。LightRAG 应运而生，它是一个创新的、轻量级的开源框架，通过巧妙地融合知识图谱（KG）的结构化语义与向量检索的强大能力，旨在为复杂查询提供更深入、更连贯的上下文理解。

In today's era of information explosion, efficiently and accurately retrieving and generating information from vast amounts of unstructured documents is a core challenge in the field of artificial intelligence. Retrieval-Augmented Generation (RAG) technology significantly improves the accuracy and factuality of model responses by combining external knowledge bases with Large Language Models (LLMs). However, traditional vector similarity-based RAG systems often struggle with complex, multi-hop reasoning problems. LightRAG emerges as an innovative, lightweight open-source framework designed to provide deeper, more coherent contextual understanding for complex queries by skillfully integrating the structured semantics of Knowledge Graphs (KG) with the powerful capabilities of vector retrieval.

核心概念与架构

Core Concepts and Architecture

LightRAG 的核心设计哲学是“双引擎驱动”。它不仅仅是一个向量数据库的封装，而是构建了一个动态的、可交互的知识图谱作为其“结构化大脑”，同时保留向量检索作为其“非结构化记忆”。这种混合架构允许系统执行两种关键的信息获取路径：

The core design philosophy of LightRAG is "dual-engine driven." It is not merely a wrapper for a vector database but constructs a dynamic, interactive knowledge graph as its "structured brain," while retaining vector retrieval as its "unstructured memory." This hybrid architecture enables the system to execute two key information retrieval paths:

1. 知识图谱路径：自动从文档中提取实体（如人物、地点、概念）和它们之间的关系，形成一个语义网络。查询时，系统可以在这个网络上进行“图遍历”，找到与问题相关的实体簇及其连接关系，从而理解概念的上下文和关联性。
2. 向量检索路径：与传统RAG相同，将文档块编码为向量，通过相似度搜索找到与查询语义最接近的文本片段。

1. Knowledge Graph Path: Automatically extracts entities (e.g., people, places, concepts) and their relationships from documents to form a semantic network. During querying, the system can perform "graph traversal" on this network to find clusters of entities related to the question and their connections, thereby understanding the context and associations of concepts.
2. Vector Retrieval Path: Similar to traditional RAG, it encodes document chunks into vectors and finds text fragments semantically closest to the query through similarity search.

LightRAG 的智能之处在于其 混合检索模式，它可以根据查询的复杂性，动态地结合或加权这两种路径的结果，为LLM提供最全面、最相关的上下文信息。

The intelligence of LightRAG lies in its Hybrid Retrieval Mode, which can dynamically combine or weight the results of these two paths based on the complexity of the query, providing the LLM with the most comprehensive and relevant contextual information.

快速入门与实践

Quick Start and Practice

安装与设置

Installation and Setup

LightRAG 的安装过程简洁明了，核心库可以通过PyPI直接获取。

The installation process for LightRAG is straightforward, and the core library can be obtained directly via PyPI.

安装 LightRAG Core

Install LightRAG Core

# 通过 PyPI 安装（推荐）
pip install lightrag-hku

# Install via PyPI (Recommended)
pip install lightrag-hku

安装 LightRAG ServerLightRAG 的服务器组件，提供 Web 界面用于文档索引、知识图谱探索和 RAG 查询，并暴露 API 接口。 (可选)

Install LightRAG ServerLightRAG 的服务器组件，提供 Web 界面用于文档索引、知识图谱探索和 RAG 查询，并暴露 API 接口。 (Optional)

对于需要Web界面或API服务的用户，可以安装带有服务器组件的版本。

For users requiring a web interface or API services, the version with server components can be installed.

# 安装包含API支持的版本
pip install "lightrag-hku[api]"

# Install the version with API support
pip install "lightrag-hku[api]"

第一个查询示例

First Query Example

以下是一个使用 OpenAI 模型进行初始化和查询的简化示例。

The following is a simplified example of initialization and querying using an OpenAI model.

import asyncio
import os
from lightrag import LightRAG, QueryParam
from lightrag.llm.openai import gpt_4o_mini_complete, openai_embed

# 设置您的 OpenAI API 密钥
os.environ["OPENAI_API_KEY"] = "your-api-key-here"

async def main():
    # 1. 初始化 LightRAG 实例
    rag = LightRAG(
        working_dir="./my_lightrag_data", # 指定工作目录用于存储缓存和索引
        embedding_func=openai_embed,      # 注入嵌入模型函数
        llm_model_func=gpt_4o_mini_complete # 注入LLM模型函数
    )
    await rag.initialize_storages() # 异步初始化存储后端

    # 2. 插入文档（例如，一段关于查尔斯·狄更斯的文本）
    sample_text = """
    Charles Dickens was a renowned English writer, famous for novels like
    'Oliver Twist', 'A Christmas Carol', and 'Great Expectations'.
    His works often critiqued social inequality in Victorian England.
    """
    rag.insert(sample_text)

    # 3. 执行查询 - 使用混合模式，结合知识图谱与向量检索
    response = rag.query(
        "What were the main themes in Charles Dickens' novels?",
        param=QueryParam(mode="mix") # 使用'mix'模式进行混合检索
    )
    print("Answer:", response)

if __name__ == "__main__":
    asyncio.run(main())

import asyncio
import os
from lightrag import LightRAG, QueryParam
from lightrag.llm.openai import gpt_4o_mini_complete, openai_embed

# Set your OpenAI API key
os.environ["OPENAI_API_KEY"] = "your-api-key-here"

async def main():
    # 1. Initialize LightRAG instance
    rag = LightRAG(
        working_dir="./my_lightrag_data", # Specify working directory for cache and indices
        embedding_func=openai_embed,      # Inject embedding model function
        llm_model_func=gpt_4o_mini_complete # Inject LLM model function
    )
    await rag.initialize_storages() # Asynchronously initialize storage backends

    # 2. Insert document (e.g., a text about Charles Dickens)
    sample_text = """
    Charles Dickens was a renowned English writer, famous for novels like
    'Oliver Twist', 'A Christmas Carol', and 'Great Expectations'.
    His works often critiqued social inequality in Victorian England.
    """
    rag.insert(sample_text)

    # 3. Execute query - Use hybrid mode, combining KG and vector retrieval
    response = rag.query(
        "What were the main themes in Charles Dickens' novels?",
        param=QueryParam(mode="mix") # Use 'mix' mode for hybrid retrieval
    )
    print("Answer:", response)

if __name__ == "__main__":
    asyncio.run(main())

核心功能深度解析

In-Depth Analysis of Core Features

灵活的检索模式

Flexible Retrieval Modes

LightRAG 的核心优势在于其多样化的检索策略，通过 QueryParam 中的 mode 参数控制。

The core strength of LightRAG lies in its diverse retrieval strategies, controlled by the mode parameter in QueryParam.

• naive: 基础向量检索模式，类似于传统RAG。
• local: 本地图检索。聚焦于查询直接提及的实体，检索其在知识图谱中的邻近节点（一度关系）及其描述，适合回答关于特定实体属性或直接关联的问题。
• global: 全局图检索。利用知识图谱的全局结构，寻找与查询主题在语义上高度相关的实体社区或子图，适合需要背景知识和概念关联的复杂、开放式问题。
• hybrid: 本地+全局混合。同时执行local和global图检索，并将结果合并，提供更广泛的上下文。
• mix (推荐): 图谱与向量混合。这是LightRAG的杀手锏。它并行执行知识图谱检索（获取结构化关系信息）和向量检索（获取相关文本片段），然后将两者融合成一个丰富的上下文提示，交给LLM生成答案。这种模式能同时捕捉到显性的语义相似度和隐性的逻辑关联。

• naive: Basic vector retrieval mode, similar to traditional RAG.
• local: Local Graph Retrieval. Focuses on entities directly mentioned in the query, retrieves their neighboring nodes (one-hop relationships) and descriptions in the knowledge graph. Suitable for answering questions about specific entity attributes or direct associations.
• global: Global Graph Retrieval. Leverages the global structure of the knowledge graph to find entity communities or subgraphs semantically highly relevant to the query topic. Suitable for complex, open-ended questions requiring background knowledge and conceptual associations.
• hybrid: Local + Global Hybrid. Simultaneously executes local and global graph retrieval and merges the results, providing broader context.
• mix (Recommended): Graph and Vector Hybrid. This is LightRAG's killer feature. It performs knowledge graph retrieval (to obtain structured relational information) and vector retrieval (to obtain relevant text fragments) in parallel, then fuses both into a rich contextual prompt for the LLM to generate an answer. This mode captures both explicit semantic similarity and implicit logical associations.

# 不同检索模式示例
param_local = QueryParam(mode="local", top_k=30) # 检索前30个相关实体
param_global = QueryParam(mode="global", top_k=50) # 检索前50个相关关系
param_mix = QueryParam(mode="mix", top_k=40) # 混合模式下控制检索深度

# Examples of Different Retrieval Modes
param_local = QueryParam(mode="local", top_k=30) # Retrieve top 30 related entities
param_global = QueryParam(mode="global", top_k=50) # Retrieve top 50 related relationships
param_mix = QueryParam(mode="mix", top_k=40) # Control retrieval depth in hybrid mode

多模型支持与注入

Multi-Model Support and Injection

LightRAG 采用灵活的模型注入机制，不与任何特定模型供应商绑定。

LightRAG employs a flexible model injection mechanism and is not bound to any specific model vendor.

1. 支持多种API后端：

1. Supports Multiple API Backends:

• OpenAI / 兼容API：如 Azure OpenAI, Groq, Together AI, 智谱AI, 月之暗面等。
• Ollama：完美支持本地运行的Ollama模型，方便私有化部署。
• Hugging Face Transformers：直接使用 transformers 库中的模型。
• LlamaIndex：复用现有的LlamaIndex模型配置和抽象。

• OpenAI / Compatible APIs: Such as Azure OpenAI, Groq, Together AI, Zhipu AI, Moonshot AI, etc.
• Ollama: Perfectly supports locally run Ollama models, facilitating private deployment.
• Hugging Face Transformers: Directly uses models from the transformers library.
• LlamaIndex: Reuses existing LlamaIndex model configurations and abstractions.

2. 模型注入示例 (Ollama):

2. Model Injection Example (Ollama):

from lightrag.llm.ollama import ollama_model_complete, ollama_embed
from lightrag import LightRAG, EmbeddingFunc

async def embedding_func(texts):
    return await ollama_embed(texts, embed_model="nomic-embed-text")

rag = LightRAG(
    working_dir="./ollama_rag",
    llm_model_func=ollama_model_complete,
    llm_model_name="qwen2.5:7b", # 指定Ollama中的模型名称
    embedding_func=EmbeddingFunc(
        embedding_dim=768,
        max_token_size=8192,
        func=embedding_func
    )
)

from lightrag.llm.ollama import ollama_model_complete, ollama_embed
from lightrag import LightRAG, EmbeddingFunc

async def embedding_func(texts):
    return await ollama_embed(texts, embed_model="nomic-embed-text")

rag = LightRAG(
    working_dir="./ollama_rag",
    llm_model_func=ollama_model_complete,
    llm_model_name="qwen2.5:7b", # Specify the model name in Ollama
    embedding_func=EmbeddingFunc(
        embedding_dim=768,
        max_token_size=8192,
        func=embedding_func
    )
)

可扩展的存储后端

Extensible Storage Backends

LightRAG 为向量、图谱和键值存储设计了可插拔的存储接口。

LightRAG features pluggable storage interfaces for vectors, graphs, and key-value stores.

• 向量存储：默认使用轻量级内存存储，可轻松切换至 FAISSFacebook AI Similarity Search, a library for efficient similarity search and clustering of dense vectors.（本地高性能）、PostgreSQL (pgvector)（生产级持久化）等。
• 图谱存储：默认使用内置的 NetworkXStorage（适用于中小规模、原型开发）。对于生产环境，强烈推荐：
  • Neo4j：成熟的图数据库，提供丰富的查询语言和可视化工具。
  • PostgreSQL + Apache AGE一个为 PostgreSQL 扩展的开源图数据库扩展，允许在 PostgreSQL 中存储和查询图数据。：将图数据库功能集成到熟悉的PostgreSQL中，实现“一库多用”，简化架构。

• Vector Storage: By default uses lightweight in-memory storage, can be easily switched to FAISSFacebook AI Similarity Search, a library for efficient similarity search and clustering of dense vectors. (local high-performance), PostgreSQL (pgvector) (production-grade persistence), etc.
• Graph Storage: By default uses the built-in NetworkXStorage (suitable for small to medium scale, prototyping). For production environments, it is highly recommended:
  • Neo4j: Mature graph database offering rich query languages and visualization tools.
  • PostgreSQL + Apache AGE一个为 PostgreSQL 扩展的开源图数据库扩展，允许在 PostgreSQL 中存储和查询图数据。: Integrates graph database functionality into the familiar PostgreSQL, achieving "multi-purpose with one database" and simplifying the architecture.

配置 Neo4j 示例：

Configuring Neo4j Example:

# 环境变量配置
export NEO4J_URI="bolt://localhost:7687"
export NEO4J_USERNAME="neo4j"
export NEO4J_PASSWORD="your_password"

# Environment Variable Configuration
export NEO4J_URI="bolt://localhost:7687"
export NEO4J_USERNAME="neo4j"
export NEO4J_PASSWORD="your_password"

# 代码中指定使用 Neo4j
rag = LightRAG(
    working_dir="./neo4j_rag",
    graph_storage="Neo4JStorage", # 关键参数：指定图存储后端
    llm_model_func=...,
    embedding_func=...
)

# Specify using Neo4j in code
rag = LightRAG(
    working_dir="./neo4j_rag",
    graph_storage="Neo4JStorage", # Key parameter: specify graph storage backend
    llm_model_func=...,
    embedding_func=...
)

知识图谱的交互与管理

Knowledge Graph Interaction and Management

LightRAG 不仅自动构建图谱，还提供了完整的CRUD API，允许用户动态地修正和增强知识库。

LightRAG not only automatically constructs the graph but also provides a complete CRUD API, allowing users to dynamically correct and enhance the knowledge base.

实体与关系编辑：

Entity and Relationship Editing:

# 创建实体
rag.create_entity(
    "量子计算",
    properties={"description": "利用量子力学原理进行计算的新范式", "category": "前沿科技"}
)

# 创建关系
rag.create_relation(
    "谷歌", "量子计算",
    properties={"relation_type": "投入研发", "strength": 0.9}
)

# 编辑实体（例如，修正描述或合并重复实体）
rag.edit_entity("AI", properties={"description": "人工智能的统称"})

# Create Entity
rag.create_entity(
    "Quantum Computing",
    properties={"description": "A new paradigm for computation using quantum mechanics principles", "category": "Cutting-edge Technology"}
)

# Create Relationship
rag.create_relation(
    "Google", "Quantum Computing",
    properties={"relation_type": "Invests in R&D", "strength": 0.9}
)

# Edit Entity (e.g., correct description or merge duplicate entities)
rag.edit_entity("AI", properties={"description": "Umbrella term for Artificial Intelligence"})

智能实体合并：

Intelligent Entity Merging:

此功能对于数据清洗至关重要，可以自动合并指代相同现实世界对象的不同实体表述。

This feature is crucial for data cleaning, automatically merging different entity expressions referring to the same real-world object.

# 将“机器学习”、“ML”、“Machine Learning”合并到“机器学习”下
rag.merge_entities(
    source_entities=["机器学习", "ML", "Machine Learning"],
    target_entity="机器学习",
    target_entity_data={"entity_type": "技术领域"}
)
# 合并后，所有与源实体相关的关系都会迁移到目标实体上。

常见问题（FAQ）

LightRAG和传统RAG框架有什么区别？

LightRAG创新地融合了知识图谱与向量检索，形成“双引擎驱动”架构。知识图谱作为结构化大脑处理复杂关联，向量检索作为非结构化记忆，通过混合检索模式动态结合两者优势，解决传统RAG在多跳推理上的不足。

如何快速开始使用LightRAG进行文档查询？

可通过PyPI安装核心库（pip install lightrag-hku），支持API的版本需安装lightrag-hku[api]。初始化后，配置LLM后端（如OpenAI）和嵌入模型，即可加载文档并执行混合检索查询，详见文中的第一个查询示例代码。

LightRAG支持哪些存储方案和LLM模型？

LightRAG支持可扩展的存储后端，并兼容多种LLM后端。框架设计灵活，允许注入不同模型，确保用户能根据需求选择适合的存储和生成模型，实现高效的文档分析与查询。