LightRAG：香港大学开源的轻量RAG框架，低耗高效赋能多领域知识增强生成

原创 发布日期：
74

一、LightRAG是什么

LightRAG（Light Retrieval-Augmented Generation，轻量检索增强生成）是由香港大学数据科学实验室（HKUDS）主导开发的开源Python RAG框架，定位为Microsoft GraphRAG的轻量级替代方案，核心目标是在简化RAG系统搭建流程的同时，保持高性能的检索与生成能力。

传统的检索增强生成系统普遍存在两大短板：一是依赖扁平的数据表示形式，无法有效理解实体间的复杂关联；二是上下文感知能力不足，面对跨领域、多维度的查询时，容易输出碎片化、不完整的回答。比如当用户询问“电动汽车的普及如何影响城市空气质量与公共交通基建”时，传统RAG可能仅能分别检索到电动汽车、空气污染、公共交通的独立文档，却无法整合三者的关联逻辑。

LightRAG针对这些问题，创新性地将知识图谱的结构化关系表示与向量检索的高效相似度匹配相结合，通过图基索引与双层检索机制，既保留了数据间的上下文关联，又提升了检索效率与准确性。同时，该框架采用轻量设计，资源消耗低、部署门槛低，支持增量数据更新，不仅适用于学术研究，也能满足中小规模生产环境的实际需求，目前已达到生产级稳定状态。

二、功能特色

LightRAG的功能设计围绕“轻量、高效、灵活、易用”四大核心，相较于传统RAG系统与重量级GraphRAG，具备多方面的特色优势，具体可分为核心能力、兼容性与易用性两大维度：

（一）核心能力：解决传统RAG痛点，强化检索与生成效果

  1. 双层检索+知识图谱增强，提升回答完整性
    LightRAG采用“低层向量检索+高层图检索”的双层检索机制，先通过向量数据库快速召回与查询相关的文本块，再利用知识图谱遍历实体间的关联关系，补充上下文信息。同时，框架默认开启重排器（Reranker），对检索结果进行二次排序，进一步提升混合查询场景的检索精度，从根本上解决传统RAG回答碎片化的问题。例如在金融分析场景中，用户查询“某原材料短缺影响哪些企业”，框架不仅能检索到相关企业名单，还能通过知识图谱展示企业间的供应链关系，给出更全面的分析。

  2. 多存储后端适配，兼顾开发与生产需求
    框架提供了分层的存储解决方案，区分了开发测试用的轻量存储与生产级的高性能存储，同时支持“一体化存储”，即单个数据库可同时承载键值、向量、图三类数据，减少部署与维护成本。具体存储支持情况如下表所示：

存储类型 开发/轻量存储（默认） 生产级存储 核心用途
键值存储 JsonKVStorage PostgreSQL、MongoDB、Redis 存储文档状态、配置信息等简单键值对数据
向量存储 NanoVectorDBStorage PostgreSQL（pgvector）、Milvus、Qdrant、FAISS 存储文本与实体的嵌入向量，支持相似度检索
图存储 NetworkXStorage Neo4j、PostgreSQL 存储实体与关系，构建知识图谱
此外，框架还支持存储间的LLM缓存迁移，当更换存储后端时，可直接迁移已缓存的模型结果，避免重复计算，加速文件重新处理流程。

  1. 多模态处理，支持全格式文档解析
    集成RAG-Anything技术，实现对文本、图片、表格、公式、PDF、Office文档等多格式内容的解析与检索。例如在学术研究场景中，用户可直接上传PDF格式的论文，框架能自动提取论文中的文本、表格与公式，构建知识图谱并支持跨类型内容的联合检索。

  2. 工作空间隔离，支持多实例并行使用
    通过“工作空间（Workspace）”机制实现多实例的数据隔离，不同存储类型适配不同的隔离策略：文件存储通过独立目录隔离，MongoDB/PostgreSQL通过集合/表前缀隔离，Neo4j通过Label标签隔离。这一设计使得单个LightRAG部署可服务于多个业务场景，避免数据混淆。

  3. 完善的生态工具，降低使用与运维成本
    配套提供了一系列实用工具，包括：React 19 + TypeScript开发的WebUI可视化操作仪表板，支持文档索引、知识图谱探索与RAG查询；3D知识图谱查看器，直观展示实体间的关联关系；LLM缓存清理/迁移工具，方便运维管理；同时支持RAGAS评估（检索增强生成效果评估）、Langfuse追踪（模型调用与检索过程监控）与引用溯源功能，便于开发者调试与优化系统。

（二）兼容性与易用性：低门槛上手，高灵活性扩展

  1. 多模型兼容，支持本地与云端部署
    框架兼容多种大语言模型（LLM）与嵌入模型后端，既支持Ollama、Lollms等本地模型部署，也支持OpenAI、Azure OpenAI、AWS Bedrock、Gemini等云端闭源模型，还能对接Qwen3-30B-A3B等开源大模型。用户可根据自身资源情况与需求灵活选择，本地模型可降低API调用成本，云端模型则能获得更优的生成效果。

  2. 部署方式灵活，适配不同环境
    支持多种部署方式：本地直接运行、Docker容器化部署、K8s集群部署，同时提供离线部署依赖清单，可在无网络环境下完成部署。此外，框架提供Ollama兼容接口，可无缝对接Open WebUI等主流AI聊天工具，无需额外开发即可实现对话式查询。

  3. 多语言支持，降低国内用户使用门槛
    提供中英文双语官方文档，核心代码注释与自动生成的实体摘要也支持中文，解决了部分开源框架仅支持英文的痛点，方便国内开发者学习与使用。

  4. 模块化设计，易扩展与二次开发
    框架采用模块化的代码结构，将存储、LLM绑定、检索、生成等功能拆分为独立模块，开发者可根据需求自定义扩展，例如新增存储后端、替换重排器算法、修改文本分块策略等。

LightRAG：香港大学开源的轻量RAG框架，低耗高效赋能多领域知识增强生成

三、技术细节

LightRAG的技术架构围绕“数据处理-存储-检索-生成”四大核心环节展开，底层通过模块化的设计实现各功能的解耦，核心技术亮点体现在文本处理流程、双层检索机制、存储架构与参数配置四个方面：

（一）核心数据处理流程

LightRAG对输入文档的处理遵循“分块-实体提取-知识图谱构建-嵌入存储”的标准化流程，确保非结构化文档转化为可检索的结构化与向量数据，具体步骤如下：

  1. 文本分块：将长文档按照预设的token数分割为多个小文本块，默认每个块最大1200个token，相邻块之间保留100个token的重叠，既保证检索的精准性，又避免上下文断裂。分块所使用的分词模型默认为gpt-4o-mini，用户也可根据需求替换为其他模型。

  2. 实体与关系提取：调用LLM对每个文本块进行实体识别，提取人名、地名、日期、事件、概念等实体，并识别实体间的关联关系（如“某算法属于某研究领域”“某药物治疗某疾病”）。框架支持设置实体提取的最大尝试次数（默认1次）与实体摘要的最大token数（默认500个），平衡提取效果与效率。

  3. 知识图谱构建：将提取的实体与关系整合为知识图谱，自动去除重复节点与冗余关系，优化图谱结构。图谱的节点嵌入采用node2vec算法实现，默认向量维度为1536，通过随机游走、窗口大小等参数控制嵌入效果。

  4. 嵌入存储：将文本块的内容、实体的描述信息与图谱的节点嵌入转化为向量，存储到指定的向量数据库中；同时将文档状态、实体属性等信息存储到键值数据库，图谱结构存储到图数据库。

（二）双层检索与生成机制

当用户发起查询时，LightRAG通过“双层检索-结果融合-LLM生成”的流程生成回答，具体逻辑如下：

  1. 第一层：向量检索：将用户查询转化为嵌入向量，在向量数据库中进行相似度匹配，快速召回与查询相关的文本块与实体，这一步的核心是“快速定位”，保证检索的效率。

  2. 第二层：图检索：基于向量检索得到的实体，在知识图谱中进行多跳遍历，挖掘实体间的潜在关联，补充上下文信息，这一步的核心是“完善关联”，保证回答的完整性。

  3. 结果重排与融合：通过重排器对两层检索的结果进行综合排序，过滤掉无关信息，将筛选后的内容整合为统一的检索结果。

  4. LLM生成：将检索结果与用户查询一起作为输入，发送给绑定的LLM，由模型生成最终的自然语言回答，并支持引用溯源，标注回答的信息来源。

（三）核心存储架构

LightRAG采用“键值存储+向量存储+图存储”的三层存储架构，三类存储各司其职，又可通过“一体化存储”实现融合，具体设计如下：

  1. 键值存储：负责存储轻量级的配置信息、文档元数据（如文档名称、上传时间、分块数量）、LLM缓存结果等，默认使用JsonKVStorage，基于文件持久化实现，生产环境可替换为Redis、PostgreSQL等。

  2. 向量存储：负责存储文本与实体的嵌入向量，支持相似度检索，默认使用轻量级的NanoVectorDBStorage，生产环境可替换为支持向量检索的PostgreSQL（pgvector）、Milvus、Qdrant等。

  3. 图存储：负责存储知识图谱的节点（实体）与边（关系），支持图遍历与多跳查询，默认使用NetworkXStorage（基于Python的NetworkX库实现），生产环境可替换为Neo4j、PostgreSQL等。

  4. 一体化存储优化：支持PostgreSQL、MongoDB等数据库同时承载三类存储数据，例如PostgreSQL可通过普通表存储键值数据、pgvector扩展存储向量数据、递归表存储图数据，减少数据库部署的数量，降低运维成本。

（四）关键参数配置

LightRAG通过丰富的参数配置实现功能的灵活调优，核心参数主要分为文件与缓存管理、文本分块、实体提取、LLM配置四大类，部分关键参数及默认值如下（基于Python dataclasses定义）：

  1. 文件与缓存管理

    • working_dir：工作目录，默认值为./lightrag_cache_{当前时间戳}，用于存储缓存与临时文件，每次实例化自动生成新目录，避免数据冲突。

    • embedding_cache_config：嵌入缓存配置，默认{"enabled": False, "similarity_threshold": 0.95, "use_llm_check": False}，开启后可避免重复计算嵌入向量，相似度阈值0.95表示95%相似的内容可复用缓存。

  2. 文本分块

    • chunk_token_size：每个文本块的最大token数，默认1200。

    • chunk_overlap_token_size：相邻文本块的重叠token数，默认100。

    • tiktoken_model_name：分词模型名称，默认gpt-4o-mini，用于计算token数。

  3. 实体提取与节点嵌入

    • entity_extract_max_gleaning：实体提取的最大尝试次数，默认1。

    • entity_summary_to_max_tokens：实体摘要的最大token数，默认500。

    • node_embedding_algorithm：节点嵌入算法，默认node2vec。

  4. LLM配置

    • llm_model_name：默认使用的LLM模型，默认meta-llama/Llama-3.2-1B-Instruct。

    • llm_model_max_token_size：LLM回答的最大token限制，默认32768。

    • enable_llm_cache：是否缓存LLM回答，默认True，减少重复的模型调用成本。

四、应用场景

LightRAG的轻量设计、高效检索能力与灵活的部署方式，使其适用于多种需要外部知识增强LLM的场景，尤其在复杂关系挖掘、实时数据更新、低资源环境下表现突出，核心应用场景如下：

（一）法律与合规性分析

在法律领域，LightRAG可用于处理法律文档、合同、法规文件，构建包含法律条款、案例、法规的知识图谱。例如当用户询问“某合同条款是否符合最新的行业法规”时，框架可通过双层检索找到相关的条款文本与法规内容，再通过知识图谱展示条款与法规的关联关系，给出精准的合规性分析。相较于GraphRAG，LightRAG在法律数据集上的token消耗更低（少于100个，而GraphRAG需610,000个），且支持增量更新，能快速整合新出台的法规，适配动态的法律环境。

（二）学术研究与文献分析

针对学术研究场景，LightRAG可帮助研究者处理PDF格式的论文、期刊文献，提取论文的主题、研究方法、实验结果等实体，构建学术知识图谱。例如研究者查询“某机器学习算法的优缺点与应用场景”时，框架能检索到相关论文的具体内容，追溯到论文的具体页面或章节，并通过知识图谱展示该算法与其他算法的关联、在不同研究领域的应用情况。同时，框架支持元数据增强检索，可根据论文发表时间、作者、期刊等条件筛选结果，满足学术研究的精准检索需求。

（三）金融与市场分析

金融分析师可利用LightRAG分析市场报告、公司财报、行业新闻，构建包含公司、股东、供应链、市场指标的知识图谱。例如查询“原材料价格上涨将影响哪些上市公司”时，框架可通过图谱遍历供应链关系，找到上游原材料企业、中游加工企业与下游终端企业，结合市场报告数据，给出受影响的企业名单与具体的影响分析。框架的增量更新功能可快速整合最新的市场数据，确保分析结果的时效性，同时低token消耗与单次API调用的设计，降低了高频查询的成本。

（四）企业知识管理与客户支持

企业可基于LightRAG构建内部知识库与智能客服系统，整合产品文档、员工手册、客户反馈、常见问题等内容，构建知识图谱。例如客户咨询“某产品的常见故障与解决方法”时，智能客服可通过检索快速找到对应的故障解决方案，同时结合历史客户反馈，给出个性化的建议。对于企业内部员工，框架可支持员工查询内部制度、业务流程、技术文档等内容，提升工作效率。框架的多实例隔离功能，可让企业为不同部门（如技术部、客服部、销售部）搭建独立的知识空间，避免数据泄露与混淆。

（五）医疗与生物技术研究

在医疗领域，LightRAG可用于管理医疗知识库、分析医学文献、支持药物研发，构建包含疾病、药物、基因、临床症状的知识图谱。例如研究人员查询“某药物对某疾病的治疗效果与潜在副作用”时，框架能检索到相关的临床研究文献，展示药物的作用机制、临床试验结果，并通过知识图谱挖掘药物与其他疾病、基因的潜在关联。框架的高效图检索能力，适合处理生物医学领域复杂的实体关系，同时轻量设计可在医院的内部服务器上部署，保障医疗数据的安全性。

（六）教育与学习助手

教育机构可基于LightRAG开发交互式学习工具，整合课程资料、教材、练习题、知识点解析等内容，构建教育知识图谱。例如学生查询“神经网络与深度学习的关系及学习路径”时，框架能通过双层检索给出具体的知识点解析，展示神经网络在深度学习中的定位，并通过知识图谱推荐相关的学习资源（如课程视频、练习题、参考书籍）。框架的个性化检索能力，可根据学生的学习进度与知识掌握情况，调整检索结果，提供个性化的学习建议。

LightRAG：香港大学开源的轻量RAG框架，低耗高效赋能多领域知识增强生成

五、使用方法

LightRAG的使用流程主要分为“环境准备-安装部署-配置模型-启动服务-实际使用”五个步骤，支持通过PyPI安装与源码安装两种方式，同时提供WebUI与API两种使用接口，以下为详细的操作指南：

（一）环境准备

  1. 系统要求：支持Linux、macOS、Windows系统，推荐使用Linux系统进行生产部署；Python版本要求3.10及以上。

  2. 包管理工具：推荐使用uv进行包管理（比pip更快、更安全），也可使用pip，uv的安装命令如下：

    • Unix/macOS系统：curl -LsSf https://astral.sh/uv/install.sh | sh

    • Windows PowerShell系统：powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

（二）安装部署

LightRAG提供两种安装方式，分别适用于快速使用与二次开发场景：

方式一：通过PyPI快速安装（推荐普通用户）

  1. 基础安装（仅核心功能）：

  pip install lightrag-hku

  1. 完整安装（包含API、WebUI扩展）：

  # 使用uv（推荐）
  uv pip install "lightrag-hku[api]"
  # 使用pip
  pip install "lightrag-hku[api]"

  1. 离线存储安装（生产环境，支持PostgreSQL、Neo4j等）：

  pip install "lightrag-hku[offline-storage]"

方式二：从源码安装（适用于开发者）

  1. 克隆仓库：

  git clone https://github.com/HKUDS/LightRAG.git
  cd LightRAG

  1. 安装依赖：

  # 使用uv（推荐，自动创建虚拟环境）
  uv sync --extra api
  # 激活虚拟环境（Linux/macOS）
  source .venv/bin/activate
  # 激活虚拟环境（Windows）
  .venv\scripts\activate

  # 若使用pip，需先创建虚拟环境
  # python -m venv .venv
  # source .venv/bin/activate（Windows：.venv\scripts\activate）
  # pip install -e ".[api]"

  1. 构建前端WebUI：

  cd lightrag_webui
  bun install --frozen-lockfile
  bun run build
  cd ..

（三）模型配置

LightRAG需要绑定LLM与嵌入模型才能正常工作，推荐通过环境变量进行配置，具体步骤如下：

  1. 复制配置文件：仓库根目录下有env.example示例配置文件，将其复制到启动目录并改名为.env：

  cp env.example .env

  1. 修改配置参数：编辑.env文件，配置LLM与嵌入模型的相关参数，以下为常见的配置示例：

    • OpenAI LLM + Ollama嵌入模型：

    LLM_BINDING=openai
    LLM_MODEL=gpt-4o
    LLM_BINDING_HOST=https://api.openai.com/v1
    LLM_BINDING_API_KEY=你的OpenAI API密钥
    EMBEDDING_BINDING=ollama
    EMBEDDING_BINDING_HOST=http://localhost:11434
    EMBEDDING_MODEL=nomic-embed-text
- **Ollama本地模型**（无网络环境推荐）：
    LLM_BINDING=ollama
    LLM_BINDING_HOST=http://localhost:11434
    LLM_MODEL=llama3.2
    EMBEDDING_BINDING=ollama
    EMBEDDING_BINDING_HOST=http://localhost:11434
    EMBEDDING_MODEL=nomic-embed-text

  1. 注意事项：修改.env文件后，需重启终端或重新加载环境变量，确保配置生效；若使用VS Code的Python扩展，需打开新的终端会话。

（四）启动服务

  1. 启动API服务：

  # 本地启动（热重载，适合开发）
  uvicorn lightrag.api.lightrag_server:app --reload
  # 生产环境启动
  lightrag-server

  1. 访问WebUI：服务启动后，在浏览器中输入http://localhost:8000，即可进入LightRAG的WebUI界面，进行文档上传、知识图谱查看、查询等操作。

  2. 对接Ollama兼容工具：若需对接Open WebUI等工具，在工具中添加模型时，将地址配置为http://localhost:8000即可，框架会自动模拟Ollama聊天模型。

（五）实际使用

  1. WebUI使用：在WebUI中，可通过“文档上传”功能导入PDF、文本、Office等格式的文件，框架会自动完成分块、实体提取与图谱构建；通过“查询”输入框发起问题，即可获得带引用溯源的回答；通过“知识图谱”模块，可直观查看实体间的关联关系。

  2. API调用：框架提供RESTful API接口，可通过Python、Postman等工具调用，例如发起查询的API请求示例（Python）：

  import requests

  url = "http://localhost:8000/query"
  data = {
    "query": "电动汽车的普及如何影响城市空气质量？",
    "workspace": "default"
  }
  response = requests.post(url, json=data)
  print(response.json()["answer"])

LightRAG：香港大学开源的轻量RAG框架，低耗高效赋能多领域知识增强生成

六、常见问题解答

  1. Q：Docker容器无法访问本地的Ollama/OpenAI代理服务？
    A：在Docker容器中，localhost指向容器内部，需使用host.docker.internal替代localhost，例如将EMBEDDING_BINDING_HOST配置为http://host.docker.internal:11434。

  2. Q：API密钥认证失败，提示“Invalid API Key”？
    A：首先检查.env文件中的API密钥是否输入正确，无多余空格或符号；其次确认密钥的权限是否足够，例如OpenAI密钥是否开通了gpt-4o模型的使用权限；最后检查请求头是否包含正确的认证信息，若通过API调用，需在请求头中添加Authorization: Bearer 你的API密钥。

  3. Q：启动服务时提示“缺少依赖包”？
    A：若通过PyPI安装，尝试使用pip install --upgrade lightrag-hku[api,offline-storage]更新并安装完整依赖；若通过源码安装，重新执行uv sync --extra api或pip install -e ".[api]"，确保依赖安装完整；对于Linux系统，可能需要安装系统级依赖，如libpq-dev（PostgreSQL依赖）、python3-dev。

  4. Q：修改.env文件后，配置未生效？
    A：LightRAG启动时会优先加载系统环境变量，再加载.env文件；若使用VS Code的Python扩展，终端会自动加载.env文件，修改后需关闭终端并重新打开；也可通过export LLM_MODEL=gpt-4o命令手动设置系统环境变量，覆盖.env中的配置。

  5. Q：查询响应时间过长，超过10秒？
    A：首先检查LLM服务的状态，若使用本地Ollama模型，确认模型是否已成功加载（可通过ollama list查看）；其次优化并发配置，减少embedding_func_max_async与llm_model_max_async的数值（默认值可在源码中调整），降低系统资源占用；最后调整文本分块大小，适当减小chunk_token_size，减少检索的数据量。

  6. Q：服务运行一段时间后，内存占用过高，导致系统卡顿？
    A：开启嵌入缓存与LLM缓存，在.env中设置EMBEDDING_CACHE_ENABLED=True，减少重复的向量计算与模型调用；调整llm_model_max_token_size参数，减小LLM生成的最大token数，降低内存消耗；定期清理缓存，使用框架提供的缓存清理工具，删除过期的缓存数据。

  7. Q：知识图谱构建失败，提示“实体提取超时”？
    A：增加实体提取的超时时间，在源码中修改entity_extract_timeout参数；减少实体提取的最大尝试次数，将entity_extract_max_gleaning从1改为0，避免重复尝试；使用性能更强的LLM模型进行实体提取，例如将llm_model_name从Llama-3.2-1B改为Llama-3.2-7B，提升提取效率。

  8. Q：上传PDF文档后，无法提取文本或表格？
    A：确认PDF文档不是扫描件（扫描件为图片格式，无法直接提取文本），对于图片格式的PDF，需先进行OCR识别；检查是否安装了PDF处理依赖，通过pip install pypdf2 pdfplumber安装相关包；在WebUI中查看文档处理日志，根据日志提示排查问题，例如文档加密需先解密。

  9. Q：查询结果缺少引用溯源，无法看到信息来源？
    A：确认在配置中开启了引用溯源功能，部分LLM模型需要特定的提示词才能生成引用，可在.env中修改LLM_PROMPT_TEMPLATE参数，添加引用溯源的提示；检查文档的元数据是否完整，若文档缺少名称、页码等信息，引用溯源功能可能无法正常工作。

  10. Q：工作空间切换后，无法看到之前的文档与查询记录？
    A：LightRAG的工作空间采用数据隔离设计，不同工作空间的文档与数据相互独立；若需查看其他工作空间的内容，需在WebUI或API请求中指定正确的workspace参数；若误删除工作空间，可从working_dir对应的目录中恢复数据（默认缓存目录为./lightrag_cache_*）。

七、相关链接

  1. 项目仓库：https://github.com/HKUDS/LightRAG（核心代码、配置示例、开发文档）

  2. 学术论文：https://arxiv.org/abs/2410.05779（LightRAG的技术原理与实验验证）

八、总结

LightRAG是香港大学数据科学实验室开发的一款轻量级检索增强生成框架，以解决传统RAG系统数据表示扁平、回答碎片化、资源消耗高的痛点为核心目标，通过融合知识图谱与向量检索技术，实现了双层检索与上下文感知的检索效果，同时保持了轻量、快速、易扩展的特性。该框架支持多存储后端、多模态处理、工作空间数据隔离，兼容本地与云端大模型，提供WebUI可视化操作与Ollama兼容接口，部署方式灵活，可适配Linux、macOS、Windows等系统与Docker、K8s等部署环境。在应用层面，LightRAG可广泛服务于法律分析、学术研究、金融市场分析、企业知识管理、医疗研发、教育学习等多个领域，既满足了学术研究的灵活性需求，又能适配中小规模生产环境的性能与稳定性要求，是一款兼具实用性与易用性的开源RAG解决方案，为开发者快速构建高性能的检索增强生成系统提供了优质的技术支撑。

开源框架 知识图谱
打赏

版权及免责申明：本文由@AI铺子原创发布。该文章观点仅代表作者本人，不代表本站立场。本站不承担任何相关法律责任。

如若转载，请注明出处：https://www.aipuzi.cn/ai-news/lightrag.html

THE END
作者头像
AI铺子
关注ai行业发展，专注ai工具推荐