Add files using upload-large-folder tool

LightRAG/.dockerignore

@@ -0,0 +1,63 @@
+# Python-related files and directories
+__pycache__
+.cache
+
+# Virtual environment directories
+*.venv
+
+# Env
+env/
+*.env*
+.env_example
+
+# Distribution / build files
+site
+dist/
+build/
+.eggs/
+*.egg-info/
+*.tgz
+*.tar.gz
+
+# Exclude siles and folders
+*.yml
+.dockerignore
+Dockerfile
+Makefile
+
+# Exclude other projects
+/tests
+/scripts
+
+# Python version manager file
+.python-version
+
+# Reports
+*.coverage/
+*.log
+log/
+*.logfire
+
+# Cache
+.cache/
+.mypy_cache
+.pytest_cache
+.ruff_cache
+.gradio
+.logfire
+temp/
+
+# MacOS-related files
+.DS_Store
+
+# VS Code settings (local configuration files)
+.vscode
+
+# file
+TODO.md
+
+# Exclude Git-related files
+.git
+.github
+.gitignore
+.pre-commit-config.yaml

LightRAG/.gitattributes

@@ -0,0 +1,2 @@
+lightrag/api/webui/** binary
+lightrag/api/webui/** linguist-generated

LightRAG/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,61 @@
+name: Bug Report
+description: File a bug report
+title: "[Bug]:"
+labels: ["bug", "triage"]
+
+body:
+  - type: checkboxes
+    id: existingcheck
+    attributes:
+      label: Do you need to file an issue?
+      description: Please help us manage our time by avoiding duplicates and common bugs with the steps below.
+      options:
+        - label: I have searched the existing issues and this bug is not already filed.
+        - label: I believe this is a legitimate bug, not just a question or feature request.
+  - type: textarea
+    id: description
+    attributes:
+      label: Describe the bug
+      description: A clear and concise description of what the bug is.
+      placeholder: What went wrong?
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      description: Steps to reproduce the behavior.
+      placeholder: How can we replicate the issue?
+  - type: textarea
+    id: expected_behavior
+    attributes:
+      label: Expected Behavior
+      description: A clear and concise description of what you expected to happen.
+      placeholder: What should have happened?
+  - type: textarea
+    id: configused
+    attributes:
+      label: LightRAG Config Used
+      description: The LightRAG configuration used for the run.
+      placeholder: The settings content or LightRAG configuration
+      value: |
+        # Paste your config here
+  - type: textarea
+    id: screenshotslogs
+    attributes:
+      label: Logs and screenshots
+      description: If applicable, add screenshots and logs to help explain your problem.
+      placeholder: Add logs and screenshots here
+  - type: textarea
+    id: additional_information
+    attributes:
+      label: Additional Information
+      description: |
+        - LightRAG Version: e.g., v0.1.1
+        - Operating System: e.g., Windows 10, Ubuntu 20.04
+        - Python Version: e.g., 3.8
+        - Related Issues: e.g., #1
+        - Any other relevant information.
+      value: |
+        - LightRAG Version:
+        - Operating System:
+        - Python Version:
+        - Related Issues:

LightRAG/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

LightRAG/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,26 @@
+name: Feature Request
+description: File a feature request
+labels: ["enhancement"]
+title: "[Feature Request]:"
+
+body:
+  - type: checkboxes
+    id: existingcheck
+    attributes:
+      label: Do you need to file a feature request?
+      description: Please help us manage our time by avoiding duplicates and common feature request with the steps below.
+      options:
+        - label: I have searched the existing feature request and this feature request is not already filed.
+        - label: I believe this is a legitimate feature request, not just a question or bug.
+  - type: textarea
+    id: feature_request_description
+    attributes:
+      label: Feature Request Description
+      description: A clear and concise description of the feature request you would like.
+      placeholder: What this feature request add more or improve?
+  - type: textarea
+    id: additional_context
+    attributes:
+      label: Additional Context
+      description: Add any other context or screenshots about the feature request here.
+      placeholder: Any additional information

LightRAG/.github/ISSUE_TEMPLATE/question.yml

@@ -0,0 +1,26 @@
+name: Question
+description: Ask a general question
+labels: ["question"]
+title: "[Question]:"
+
+body:
+  - type: checkboxes
+    id: existingcheck
+    attributes:
+      label: Do you need to ask a question?
+      description: Please help us manage our time by avoiding duplicates and common questions with the steps below.
+      options:
+        - label: I have searched the existing question and discussions and this question is not already answered.
+        - label: I believe this is a legitimate question, not just a bug or feature request.
+  - type: textarea
+    id: question
+    attributes:
+      label: Your Question
+      description: A clear and concise description of your question.
+      placeholder: What is your question?
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional Context
+      description: Provide any additional context or details that might help us understand your question better.
+      placeholder: Add any relevant information here

LightRAG/.github/dependabot.yml

@@ -0,0 +1,11 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: "pip" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"

LightRAG/.github/pull_request_template.md

@@ -0,0 +1,32 @@
+<!--
+Thanks for contributing to LightRAG!
+
+Please ensure your pull request is ready for review before submitting.
+
+About this template
+
+This template helps contributors provide a clear and concise description of their changes. Feel free to adjust it as needed.
+-->
+
+## Description
+
+[Briefly describe the changes made in this pull request.]
+
+## Related Issues
+
+[Reference any related issues or tasks addressed by this pull request.]
+
+## Changes Made
+
+[List the specific changes made in this pull request.]
+
+## Checklist
+
+- [ ] Changes tested locally
+- [ ] Code reviewed
+- [ ] Documentation updated (if necessary)
+- [ ] Unit tests added (if applicable)
+
+## Additional Notes
+
+[Add any additional notes or context for the reviewer(s).]

LightRAG/.github/workflows/docker-build-manual.yml

@@ -0,0 +1,73 @@
+name: Build Test Docker Image manually
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Fetch all history for tags
+
+      - name: Get latest tag
+        id: get_tag
+        run: |
+          # Get the latest tag, fallback to commit SHA if no tags exist
+          LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
+          if [ -z "$LATEST_TAG" ]; then
+            LATEST_TAG="sha-$(git rev-parse --short HEAD)"
+            echo "No tags found, using commit SHA: $LATEST_TAG"
+          else
+            echo "Latest tag found: $LATEST_TAG"
+          fi
+          echo "tag=$LATEST_TAG" >> $GITHUB_OUTPUT
+          echo "image_tag=$LATEST_TAG" >> $GITHUB_OUTPUT
+
+      - name: Update version in __init__.py
+        run: |
+          sed -i "s/__version__ = \".*\"/__version__ = \"${{ steps.get_tag.outputs.tag }}\"/" lightrag/__init__.py
+          echo "Updated __init__.py with version ${{ steps.get_tag.outputs.tag }}"
+          cat lightrag/__init__.py | grep __version__
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata for Docker
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            type=raw,value=${{ steps.get_tag.outputs.tag }}
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: Output image details
+        run: |
+          echo "Docker image built and pushed successfully!"
+          echo "Image tags:"
+          echo "  - ghcr.io/${{ github.repository }}:${{ steps.get_tag.outputs.tag }}"
+          echo "Latest Git tag used: ${{ steps.get_tag.outputs.tag }}"

LightRAG/.github/workflows/docker-publish.yml

@@ -0,0 +1,62 @@
+name: Build Latest Docker Image on Release
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Fetch all history for tags
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Get latest tag
+        id: get_tag
+        run: |
+          TAG=$(git describe --tags --abbrev=0)
+          echo "Found tag: $TAG"
+          echo "tag=$TAG" >> $GITHUB_OUTPUT
+
+      - name: Update version in __init__.py
+        run: |
+          sed -i "s/__version__ = \".*\"/__version__ = \"${{ steps.get_tag.outputs.tag }}\"/" lightrag/__init__.py
+          echo "Updated __init__.py with version ${{ steps.get_tag.outputs.tag }}"
+          cat lightrag/__init__.py | grep __version__
+
+      - name: Extract metadata for Docker
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            type=raw,value=${{ steps.get_tag.outputs.tag }}
+            type=raw,value=latest
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

LightRAG/.github/workflows/linting.yaml

@@ -0,0 +1,30 @@
+name: Linting and Formatting
+
+on:
+    push:
+        branches:
+            - main
+    pull_request:
+        branches:
+            - main
+
+jobs:
+    lint-and-format:
+        runs-on: ubuntu-latest
+
+        steps:
+            - name: Checkout code
+              uses: actions/checkout@v2
+
+            - name: Set up Python
+              uses: actions/setup-python@v2
+              with:
+                python-version: '3.x'
+
+            - name: Install dependencies
+              run: |
+                python -m pip install --upgrade pip
+                pip install pre-commit
+
+            - name: Run pre-commit
+              run: pre-commit run --all-files --show-diff-on-failure

LightRAG/.github/workflows/pypi-publish.yml

@@ -0,0 +1,69 @@
+name: Upload LightRAG-hku Package
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  release-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Fetch all history for tags
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Get version from tag
+        id: get_version
+        run: |
+          TAG=$(git describe --tags --abbrev=0)
+          echo "Found tag: $TAG"
+          echo "Extracted version: $TAG"
+          echo "version=$TAG" >> $GITHUB_OUTPUT
+
+      - name: Update version in __init__.py
+        run: |
+          sed -i "s/__version__ = \".*\"/__version__ = \"${{ steps.get_version.outputs.version }}\"/" lightrag/__init__.py
+          echo "Updated __init__.py with version ${{ steps.get_version.outputs.version }}"
+          cat lightrag/__init__.py | grep __version__
+
+      - name: Build release distributions
+        run: |
+          python -m pip install build
+          python -m build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+    permissions:
+      id-token: write
+
+    environment:
+      name: pypi
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish release distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

LightRAG/.github/workflows/stale.yaml

@@ -0,0 +1,27 @@
+# .github/workflows/stale.yml
+name: Mark stale issues and pull requests
+
+on:
+  schedule:
+    - cron: '30 22 * * *' # run at 22:30+08 every day
+
+permissions:
+  issues: write
+  pull-requests: write
+
+jobs:
+  stale:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/stale@v9
+        with:
+          days-before-stale: 90 # 90 days
+          days-before-close: 7 # 7 days after marked as stale
+          stale-issue-message: 'This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.'
+          close-issue-message: 'This issue has been automatically closed because it has not had recent activity. Please open a new issue if you still have this problem.'
+          stale-pr-message: 'This pull request has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs.'
+          close-pr-message: 'This pull request has been automatically closed because it has not had recent activity.'
+          # If there are specific labels, exempt them from being marked as stale, for example:
+          exempt-issue-labels: 'enhancement,tracked'
+          # exempt-pr-labels: 'bug,enhancement,help wanted'
+          repo-token: ${{ secrets.GITHUB_TOKEN }} # token provided by GitHub

LightRAG/.gitignore

@@ -0,0 +1,75 @@
+# Python-related files
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+*.tgz
+*.tar.gz
+*.ini
+
+# Virtual Environment
+.venv/
+env/
+venv/
+*.env*
+.env_example
+
+# Build / Distribution
+dist/
+build/
+site/
+
+# Logs / Reports
+*.log
+*.log.*
+*.logfire
+*.coverage/
+log/
+
+# Caches
+.cache/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.gradio/
+.history/
+temp/
+
+# IDE / Editor Files
+.idea/
+.vscode/
+.vscode/settings.json
+
+# Framework-specific files
+local_neo4jWorkDir/
+neo4jWorkDir/
+
+# Data & Storage
+inputs/
+rag_storage/
+examples/input/
+examples/output/
+output*/
+data/
+
+# Miscellaneous
+.DS_Store
+TODO.md
+ignore_this.txt
+*.ignore.*
+
+# Project-specific files
+dickens*/
+book.txt
+LightRAG.pdf
+download_models_hf.py
+lightrag-dev/
+gui/
+
+# unit-test files
+test_*
+
+# Cline files
+memory-bank
+memory-bank/
+.clinerules

LightRAG/.pre-commit-config.yaml

@@ -0,0 +1,28 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+        exclude: ^lightrag/api/webui/
+      - id: end-of-file-fixer
+        exclude: ^lightrag/api/webui/
+      - id: requirements-txt-fixer
+        exclude: ^lightrag/api/webui/
+
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.4
+    hooks:
+      - id: ruff-format
+        exclude: ^lightrag/api/webui/
+      - id: ruff
+        args: [--fix, --ignore=E402]
+        exclude: ^lightrag/api/webui/
+
+
+  - repo: https://github.com/mgedmin/check-manifest
+    rev: "0.49"
+    hooks:
+      - id: check-manifest
+        stages: [manual]
+        exclude: ^lightrag/api/webui/

LightRAG/Dockerfile

@@ -0,0 +1,63 @@
+# Build stage
+FROM python:3.12-slim AS builder
+
+WORKDIR /app
+
+# Upgrade pip、setuptools and wheel to the latest version
+RUN pip install --upgrade pip setuptools wheel
+
+# Install Rust and required build dependencies
+RUN apt-get update && apt-get install -y \
+    curl \
+    build-essential \
+    pkg-config \
+    && rm -rf /var/lib/apt/lists/* \
+    && curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y \
+    && . $HOME/.cargo/env
+
+# Copy pyproject.toml and source code for dependency installation
+COPY pyproject.toml .
+COPY setup.py .
+COPY lightrag/ ./lightrag/
+
+# Install dependencies
+ENV PATH="/root/.cargo/bin:${PATH}"
+RUN pip install --user --no-cache-dir --use-pep517 .
+RUN pip install --user --no-cache-dir --use-pep517 .[api]
+
+# Install depndencies for default storage
+RUN pip install --user --no-cache-dir nano-vectordb networkx
+# Install depndencies for default LLM
+RUN pip install --user --no-cache-dir openai ollama tiktoken
+# Install depndencies for default document loader
+RUN pip install --user --no-cache-dir pypdf2 python-docx python-pptx openpyxl
+
+# Final stage
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# Upgrade pip and setuptools
+RUN pip install --upgrade pip setuptools wheel
+
+# Copy only necessary files from builder
+COPY --from=builder /root/.local /root/.local
+COPY ./lightrag ./lightrag
+COPY setup.py .
+
+RUN pip install --use-pep517 ".[api]"
+# Make sure scripts in .local are usable
+ENV PATH=/root/.local/bin:$PATH
+
+# Create necessary directories
+RUN mkdir -p /app/data/rag_storage /app/data/inputs
+
+# Docker data directories
+ENV WORKING_DIR=/app/data/rag_storage
+ENV INPUT_DIR=/app/data/inputs
+
+# Expose the default port
+EXPOSE 9621
+
+# Set entrypoint
+ENTRYPOINT ["python", "-m", "lightrag.api.lightrag_server"]

LightRAG/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 LightRAG Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

LightRAG/MANIFEST.in

@@ -0,0 +1,3 @@
+include requirements.txt
+include lightrag/api/requirements.txt
+recursive-include lightrag/api/webui *

LightRAG/README-zh.md

@@ -0,0 +1,1738 @@
+<div align="center">
+
+<div style="margin: 20px 0;">
+  <img src="./assets/logo.png" width="120" height="120" alt="LightRAG Logo" style="border-radius: 20px; box-shadow: 0 8px 32px rgba(0, 217, 255, 0.3);">
+</div>
+
+# 🚀 LightRAG: Simple and Fast Retrieval-Augmented Generation
+
+<div align="center">
+    <a href="https://trendshift.io/repositories/13043" target="_blank"><img src="https://trendshift.io/api/badge/repositories/13043" alt="HKUDS%2FLightRAG | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
+</div>
+
+<div align="center">
+  <div style="width: 100%; height: 2px; margin: 20px 0; background: linear-gradient(90deg, transparent, #00d9ff, transparent);"></div>
+</div>
+
+<div align="center">
+  <div style="background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); border-radius: 15px; padding: 25px; text-align: center;">
+    <p>
+      <a href='https://github.com/HKUDS/LightRAG'><img src='https://img.shields.io/badge/🔥项目-主页-00d9ff?style=for-the-badge&logo=github&logoColor=white&labelColor=1a1a2e'></a>
+      <a href='https://arxiv.org/abs/2410.05779'><img src='https://img.shields.io/badge/📄arXiv-2410.05779-ff6b6b?style=for-the-badge&logo=arxiv&logoColor=white&labelColor=1a1a2e'></a>
+      <a href="https://github.com/HKUDS/LightRAG/stargazers"><img src='https://img.shields.io/github/stars/HKUDS/LightRAG?color=00d9ff&style=for-the-badge&logo=star&logoColor=white&labelColor=1a1a2e' /></a>
+    </p>
+    <p>
+      <img src="https://img.shields.io/badge/🐍Python-3.10-4ecdc4?style=for-the-badge&logo=python&logoColor=white&labelColor=1a1a2e">
+      <a href="https://pypi.org/project/lightrag-hku/"><img src="https://img.shields.io/pypi/v/lightrag-hku.svg?style=for-the-badge&logo=pypi&logoColor=white&labelColor=1a1a2e&color=ff6b6b"></a>
+    </p>
+    <p>
+      <a href="https://discord.gg/yF2MmDJyGJ"><img src="https://img.shields.io/badge/💬Discord-社区-7289da?style=for-the-badge&logo=discord&logoColor=white&labelColor=1a1a2e"></a>
+      <a href="https://github.com/HKUDS/LightRAG/issues/285"><img src="https://img.shields.io/badge/💬微信群-交流-07c160?style=for-the-badge&logo=wechat&logoColor=white&labelColor=1a1a2e"></a>
+    </p>
+    <p>
+      <a href="README-zh.md"><img src="https://img.shields.io/badge/🇨🇳中文版-1a1a2e?style=for-the-badge"></a>
+      <a href="README.md"><img src="https://img.shields.io/badge/🇺🇸English-1a1a2e?style=for-the-badge"></a>
+    </p>
+    <p>
+      <a href="https://pepy.tech/projects/lightrag-hku"><img src="https://static.pepy.tech/personalized-badge/lightrag-hku?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads"></a>
+    </p>
+  </div>
+</div>
+
+</div>
+
+<div align="center" style="margin: 30px 0;">
+  <img src="https://user-images.githubusercontent.com/74038190/212284100-561aa473-3905-4a80-b561-0d28506553ee.gif" width="800">
+</div>
+
+<div align="center" style="margin: 30px 0;">
+    <img src="./README.assets/b2aaf634151b4706892693ffb43d9093.png" width="800" alt="LightRAG Diagram">
+</div>
+
+---
+
+## 🎉 新闻
+
+- [X] [2025.06.16]🎯📢我们的团队发布了[RAG-Anything](https://github.com/HKUDS/RAG-Anything)，一个用于无缝处理文本、图像、表格和方程式的全功能多模态 RAG 系统。
+- [X] [2025.06.05]🎯📢LightRAG现已集成[RAG-Anything](https://github.com/HKUDS/RAG-Anything)，支持全面的多模态文档解析与RAG能力（PDF、图片、Office文档、表格、公式等）。详见下方[多模态处理模块](https://github.com/HKUDS/LightRAG?tab=readme-ov-file#多模态文档处理rag-anything集成)。
+- [X] [2025.03.18]🎯📢LightRAG现已支持引文功能。
+- [X] [2025.02.05]🎯📢我们团队发布了[VideoRAG](https://github.com/HKUDS/VideoRAG)，用于理解超长上下文视频。
+- [X] [2025.01.13]🎯📢我们团队发布了[MiniRAG](https://github.com/HKUDS/MiniRAG)，使用小型模型简化RAG。
+- [X] [2025.01.06]🎯📢现在您可以[使用PostgreSQL进行存储](#using-postgresql-for-storage)。
+- [X] [2024.12.31]🎯📢LightRAG现在支持[通过文档ID删除](https://github.com/HKUDS/LightRAG?tab=readme-ov-file#delete)。
+- [X] [2024.11.25]🎯📢LightRAG现在支持无缝集成[自定义知识图谱](https://github.com/HKUDS/LightRAG?tab=readme-ov-file#insert-custom-kg)，使用户能够用自己的领域专业知识增强系统。
+- [X] [2024.11.19]🎯📢LightRAG的综合指南现已在[LearnOpenCV](https://learnopencv.com/lightrag)上发布。非常感谢博客作者。
+- [X] [2024.11.11]🎯📢LightRAG现在支持[通过实体名称删除实体](https://github.com/HKUDS/LightRAG?tab=readme-ov-file#delete)。
+- [X] [2024.11.09]🎯📢推出[LightRAG Gui](https://lightrag-gui.streamlit.app)，允许您插入、查询、可视化和下载LightRAG知识。
+- [X] [2024.11.04]🎯📢现在您可以[使用Neo4J进行存储](https://github.com/HKUDS/LightRAG?tab=readme-ov-file#using-neo4j-for-storage)。
+- [X] [2024.10.29]🎯📢LightRAG现在通过`textract`支持多种文件类型，包括PDF、DOC、PPT和CSV。
+- [X] [2024.10.20]🎯📢我们为LightRAG添加了一个新功能：图形可视化。
+- [X] [2024.10.18]🎯📢我们添加了[LightRAG介绍视频](https://youtu.be/oageL-1I0GE)的链接。感谢作者！
+- [X] [2024.10.17]🎯📢我们创建了一个[Discord频道](https://discord.gg/yF2MmDJyGJ)！欢迎加入分享和讨论！🎉🎉
+- [X] [2024.10.16]🎯📢LightRAG现在支持[Ollama模型](https://github.com/HKUDS/LightRAG?tab=readme-ov-file#quick-start)！
+- [X] [2024.10.15]🎯📢LightRAG现在支持[Hugging Face模型](https://github.com/HKUDS/LightRAG?tab=readme-ov-file#quick-start)！
+
+<details>
+  <summary style="font-size: 1.4em; font-weight: bold; cursor: pointer; display: list-item;">
+    算法流程图
+  </summary>
+
+![LightRAG索引流程图](https://learnopencv.com/wp-content/uploads/2024/11/LightRAG-VectorDB-Json-KV-Store-Indexing-Flowchart-scaled.jpg)
+*图1：LightRAG索引流程图 - 图片来源：[Source](https://learnopencv.com/lightrag/)*
+![LightRAG检索和查询流程图](https://learnopencv.com/wp-content/uploads/2024/11/LightRAG-Querying-Flowchart-Dual-Level-Retrieval-Generation-Knowledge-Graphs-scaled.jpg)
+*图2：LightRAG检索和查询流程图 - 图片来源：[Source](https://learnopencv.com/lightrag/)*
+
+</details>
+
+## 安装
+
+### 安装LightRAG服务器
+
+LightRAG服务器旨在提供Web UI和API支持。Web UI便于文档索引、知识图谱探索和简单的RAG查询界面。LightRAG服务器还提供兼容Ollama的接口，旨在将LightRAG模拟为Ollama聊天模型。这使得AI聊天机器人（如Open WebUI）可以轻松访问LightRAG。
+
+* 从PyPI安装
+
+```bash
+pip install "lightrag-hku[api]"
+cp env.example .env
+lightrag-server
+```
+
+* 从源代码安装
+
+```bash
+git clone https://github.com/HKUDS/LightRAG.git
+cd LightRAG
+# 如有必要，创建Python虚拟环境
+# 以可编辑模式安装并支持API
+pip install -e ".[api]"
+cp env.example .env
+lightrag-server
+```
+
+* 使用 Docker Compose 启动 LightRAG 服务器
+
+```
+git clone https://github.com/HKUDS/LightRAG.git
+cd LightRAG
+cp env.example .env
+# modify LLM and Embedding settings in .env
+docker compose up
+```
+
+> 在此获取LightRAG docker镜像历史版本: [LightRAG Docker Images]( https://github.com/HKUDS/LightRAG/pkgs/container/lightrag)
+
+### 安装LightRAG Core
+
+* 从源代码安装（推荐）
+
+```bash
+cd LightRAG
+pip install -e .
+```
+
+* 从PyPI安装
+
+```bash
+pip install lightrag-hku
+```
+
+## 快速开始
+
+### LightRAG的LLM及配套技术栈要求
+
+LightRAG对大型语言模型（LLM）的能力要求远高于传统RAG，因为它需要LLM执行文档中的实体关系抽取任务。配置合适的Embedding和Reranker模型对提高查询表现也至关重要。
+
+- **LLM选型**：
+  - 推荐选用参数量至少为32B的LLM。
+  - 上下文长度至少为32KB，推荐达到64KB。
+  - 在文档索引阶段不建议选择推理模型。
+  - 在查询阶段建议选择比索引阶段能力更强的模型，以达到更高的查询效果。
+- **Embedding模型**：
+  - 高性能的Embedding模型对RAG至关重要。
+  - 推荐使用主流的多语言Embedding模型，例如：BAAI/bge-m3 和 text-embedding-3-large。
+  - **重要提示**：在文档索引前必须确定使用的Embedding模型，且在文档查询阶段必须沿用与索引阶段相同的模型。有些存储（例如PostgreSQL）在首次建立数表的时候需要确定向量维度，因此更换Embedding模型后需要删除向量相关库表，以便让LightRAG重建新的库表。
+- **Reranker模型配置**：
+  - 配置Reranker模型能够显著提升LightRAG的检索效果。
+  - 启用Reranker模型后，推荐将“mix模式”设为默认查询模式。
+  - 推荐选用主流的Reranker模型，例如：BAAI/bge-reranker-v2-m3 或 Jina 等服务商提供的模型。
+
+### 使用LightRAG服务器
+
+**有关LightRAG服务器的更多信息，请参阅[LightRAG服务器](./lightrag/api/README.md)。**
+
+### 使用LightRAG Core
+
+LightRAG核心功能的示例代码请参见`examples`目录。您还可参照[视频](https://www.youtube.com/watch?v=g21royNJ4fw)视频完成环境配置。若已持有OpenAI API密钥，可以通过以下命令运行演示代码：
+
+```bash
+### you should run the demo code with project folder
+cd LightRAG
+### provide your API-KEY for OpenAI
+export OPENAI_API_KEY="sk-...your_opeai_key..."
+### download the demo document of "A Christmas Carol" by Charles Dickens
+curl https://raw.githubusercontent.com/gusye1234/nano-graphrag/main/tests/mock_data.txt > ./book.txt
+### run the demo code
+python examples/lightrag_openai_demo.py
+```
+
+如需流式响应示例的实现代码，请参阅 `examples/lightrag_openai_compatible_demo.py`。运行前，请确保根据需求修改示例代码中的LLM及嵌入模型配置。
+
+**注意1**：在运行demo程序的时候需要注意，不同的测试程序可能使用的是不同的embedding模型，更换不同的embeding模型的时候需要把清空数据目录（`./dickens`），否则层序执行会出错。如果你想保留LLM缓存，可以在清除数据目录时保留`kv_store_llm_response_cache.json`文件。
+
+**注意2**：官方支持的示例代码仅为 `lightrag_openai_demo.py` 和 `lightrag_openai_compatible_demo.py` 两个文件。其他示例文件均为社区贡献内容，尚未经过完整测试与优化。
+
+## 使用LightRAG Core进行编程
+
+> ⚠️ **如果您希望将LightRAG集成到您的项目中，建议您使用LightRAG Server提供的REST API**。LightRAG Core通常用于嵌入式应用，或供希望进行研究与评估的学者使用。
+
+### 一个简单程序
+
+以下Python代码片段演示了如何初始化LightRAG、插入文本并进行查询：
+
+```python
+import os
+import asyncio
+from lightrag import LightRAG, QueryParam
+from lightrag.llm.openai import gpt_4o_mini_complete, gpt_4o_complete, openai_embed
+from lightrag.kg.shared_storage import initialize_pipeline_status
+from lightrag.utils import setup_logger
+
+setup_logger("lightrag", level="INFO")
+
+WORKING_DIR = "./rag_storage"
+if not os.path.exists(WORKING_DIR):
+    os.mkdir(WORKING_DIR)
+
+async def initialize_rag():
+    rag = LightRAG(
+        working_dir=WORKING_DIR,
+        embedding_func=openai_embed,
+        llm_model_func=gpt_4o_mini_complete,
+    )
+    await rag.initialize_storages()
+    await initialize_pipeline_status()
+    return rag
+
+async def main():
+    try:
+        # 初始化RAG实例
+        rag = await initialize_rag()
+        # 插入文本
+        await rag.insert("Your text")
+
+        # 执行混合检索
+        mode = "hybrid"
+        print(
+            await rag.query(
+                "这个故事的主要主题是什么？",
+                param=QueryParam(mode=mode)
+            )
+        )
+
+    except Exception as e:
+        print(f"发生错误: {e}")
+    finally:
+        if rag:
+            await rag.finalize_storages()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+重要说明：
+- 运行脚本前请先导出你的OPENAI_API_KEY环境变量。
+- 该程序使用LightRAG的默认存储设置，所有数据将持久化在WORKING_DIR/rag_storage目录下。
+- 该示例仅展示了初始化LightRAG对象的最简单方式：注入embedding和LLM函数，并在创建LightRAG对象后初始化存储和管道状态。
+
+### LightRAG初始化参数
+
+以下是完整的LightRAG对象初始化参数清单：
+
+<details>
+<summary> 参数 </summary>
+
+| **参数** | **类型** | **说明** | **默认值** |
+|--------------|----------|-----------------|-------------|
+| **working_dir** | `str` | 存储缓存的目录 | `lightrag_cache+timestamp` |
+| **kv_storage** | `str` | Storage type for documents and text chunks. Supported types: `JsonKVStorage`,`PGKVStorage`,`RedisKVStorage`,`MongoKVStorage` | `JsonKVStorage` |
+| **vector_storage** | `str` | Storage type for embedding vectors. Supported types: `NanoVectorDBStorage`,`PGVectorStorage`,`MilvusVectorDBStorage`,`ChromaVectorDBStorage`,`FaissVectorDBStorage`,`MongoVectorDBStorage`,`QdrantVectorDBStorage` | `NanoVectorDBStorage` |
+| **graph_storage** | `str` | Storage type for graph edges and nodes. Supported types: `NetworkXStorage`,`Neo4JStorage`,`PGGraphStorage`,`AGEStorage` | `NetworkXStorage` |
+| **doc_status_storage** | `str` | Storage type for documents process status. Supported types: `JsonDocStatusStorage`,`PGDocStatusStorage`,`MongoDocStatusStorage` | `JsonDocStatusStorage` |
+| **chunk_token_size** | `int` | 拆分文档时每个块的最大令牌大小 | `1200` |
+| **chunk_overlap_token_size** | `int` | 拆分文档时两个块之间的重叠令牌大小 | `100` |
+| **tokenizer** | `Tokenizer` | 用于将文本转换为 tokens（数字）以及使用遵循 TokenizerInterface 协议的 .encode() 和 .decode() 函数将 tokens 转换回文本的函数。 如果您不指定，它将使用默认的 Tiktoken tokenizer。 | `TiktokenTokenizer` |
+| **tiktoken_model_name** | `str` | 如果您使用的是默认的 Tiktoken tokenizer，那么这是要使用的特定 Tiktoken 模型的名称。如果您提供自己的 tokenizer，则忽略此设置。 | `gpt-4o-mini` |
+| **entity_extract_max_gleaning** | `int` | 实体提取过程中的循环次数，附加历史消息 | `1` |
+| **node_embedding_algorithm** | `str` | 节点嵌入算法（当前未使用） | `node2vec` |
+| **node2vec_params** | `dict` | 节点嵌入的参数 | `{"dimensions": 1536,"num_walks": 10,"walk_length": 40,"window_size": 2,"iterations": 3,"random_seed": 3,}` |
+| **embedding_func** | `EmbeddingFunc` | 从文本生成嵌入向量的函数 | `openai_embed` |
+| **embedding_batch_num** | `int` | 嵌入过程的最大批量大小（每批发送多个文本） | `32` |
+| **embedding_func_max_async** | `int` | 最大并发异步嵌入进程数 | `16` |
+| **llm_model_func** | `callable` | LLM生成的函数 | `gpt_4o_mini_complete` |
+| **llm_model_name** | `str` | 用于生成的LLM模型名称 | `meta-llama/Llama-3.2-1B-Instruct` |
+| **summary_context_size** | `int` | 合并实体关系摘要时送给LLM的最大令牌数 | `10000`（由环境变量 SUMMARY_MAX_CONTEXT 设置） |
+| **summary_max_tokens** | `int` | 合并实体关系描述的最大令牌数长度 | `500`（由环境变量 SUMMARY_MAX_TOKENS 设置） |
+| **llm_model_max_async** | `int` | 最大并发异步LLM进程数 | `4`（默认值由环境变量MAX_ASYNC更改） |
+| **llm_model_kwargs** | `dict` | LLM生成的附加参数 | |
+| **vector_db_storage_cls_kwargs** | `dict` | 向量数据库的附加参数，如设置节点和关系检索的阈值 | cosine_better_than_threshold: 0.2（默认值由环境变量COSINE_THRESHOLD更改） |
+| **enable_llm_cache** | `bool` | 如果为`TRUE`，将LLM结果存储在缓存中；重复的提示返回缓存的响应 | `TRUE` |
+| **enable_llm_cache_for_entity_extract** | `bool` | 如果为`TRUE`，将实体提取的LLM结果存储在缓存中；适合初学者调试应用程序 | `TRUE` |
+| **addon_params** | `dict` | 附加参数，例如`{"language": "Simplified Chinese", "entity_types": ["organization", "person", "location", "event"]}`：设置示例限制、输出语言和文档处理的批量大小 | language: English` |
+| **embedding_cache_config** | `dict` | 问答缓存的配置。包含三个参数：`enabled`：布尔值，启用/禁用缓存查找功能。启用时，系统将在生成新答案之前检查缓存的响应。`similarity_threshold`：浮点值（0-1），相似度阈值。当新问题与缓存问题的相似度超过此阈值时，将直接返回缓存的答案而不调用LLM。`use_llm_check`：布尔值，启用/禁用LLM相似度验证。启用时，在返回缓存答案之前，将使用LLM作为二次检查来验证问题之间的相似度。 | 默认：`{"enabled": False, "similarity_threshold": 0.95, "use_llm_check": False}` |
+
+</details>
+
+### 查询参数
+
+使用QueryParam控制你的查询行为：
+
+```python
+class QueryParam:
+    """Configuration parameters for query execution in LightRAG."""
+
+    mode: Literal["local", "global", "hybrid", "naive", "mix", "bypass"] = "global"
+    """Specifies the retrieval mode:
+    - "local": Focuses on context-dependent information.
+    - "global": Utilizes global knowledge.
+    - "hybrid": Combines local and global retrieval methods.
+    - "naive": Performs a basic search without advanced techniques.
+    - "mix": Integrates knowledge graph and vector retrieval.
+    """
+
+    only_need_context: bool = False
+    """If True, only returns the retrieved context without generating a response."""
+
+    only_need_prompt: bool = False
+    """If True, only returns the generated prompt without producing a response."""
+
+    response_type: str = "Multiple Paragraphs"
+    """Defines the response format. Examples: 'Multiple Paragraphs', 'Single Paragraph', 'Bullet Points'."""
+
+    stream: bool = False
+    """If True, enables streaming output for real-time responses."""
+
+    top_k: int = int(os.getenv("TOP_K", "60"))
+    """Number of top items to retrieve. Represents entities in 'local' mode and relationships in 'global' mode."""
+
+    chunk_top_k: int = int(os.getenv("CHUNK_TOP_K", "20"))
+    """Number of text chunks to retrieve initially from vector search and keep after reranking.
+    If None, defaults to top_k value.
+    """
+
+    max_entity_tokens: int = int(os.getenv("MAX_ENTITY_TOKENS", "6000"))
+    """Maximum number of tokens allocated for entity context in unified token control system."""
+
+    max_relation_tokens: int = int(os.getenv("MAX_RELATION_TOKENS", "8000"))
+    """Maximum number of tokens allocated for relationship context in unified token control system."""
+
+    max_total_tokens: int = int(os.getenv("MAX_TOTAL_TOKENS", "30000"))
+    """Maximum total tokens budget for the entire query context (entities + relations + chunks + system prompt)."""
+
+    hl_keywords: list[str] = field(default_factory=list)
+    """List of high-level keywords to prioritize in retrieval."""
+
+    ll_keywords: list[str] = field(default_factory=list)
+    """List of low-level keywords to refine retrieval focus."""
+
+    conversation_history: list[dict[str, str]] = field(default_factory=list)
+    """Stores past conversation history to maintain context.
+    Format: [{"role": "user/assistant", "content": "message"}].
+    """
+
+    # Deprated: history message have negtive effect on query performance
+    history_turns: int = 0
+    """Number of complete conversation turns (user-assistant pairs) to consider in the response context."""
+
+    ids: list[str] | None = None
+    """List of ids to filter the results."""
+
+    model_func: Callable[..., object] | None = None
+    """Optional override for the LLM model function to use for this specific query.
+    If provided, this will be used instead of the global model function.
+    This allows using different models for different query modes.
+    """
+
+    user_prompt: str | None = None
+    """User-provided prompt for the query.
+    If proivded, this will be use instead of the default vaulue from prompt template.
+    """
+
+    enable_rerank: bool = True
+    """Enable reranking for retrieved text chunks. If True but no rerank model is configured, a warning will be issued.
+    Default is True to enable reranking when rerank model is available.
+    """
+```
+
+> top_k的默认值可以通过环境变量TOP_K更改。
+
+### LLM and Embedding注入
+
+LightRAG 需要利用LLM和Embeding模型来完成文档索引和知识库查询工作。在初始化LightRAG的时候需要把阶段，需要把LLM和Embedding的操作函数注入到对象中：
+
+<details>
+<summary> <b>使用类OpenAI的API</b> </summary>
+
+* LightRAG还支持类OpenAI的聊天/嵌入API：
+
+```python
+async def llm_model_func(
+    prompt, system_prompt=None, history_messages=[], keyword_extraction=False, **kwargs
+) -> str:
+    return await openai_complete_if_cache(
+        "solar-mini",
+        prompt,
+        system_prompt=system_prompt,
+        history_messages=history_messages,
+        api_key=os.getenv("UPSTAGE_API_KEY"),
+        base_url="https://api.upstage.ai/v1/solar",
+        **kwargs
+    )
+
+async def embedding_func(texts: list[str]) -> np.ndarray:
+    return await openai_embed(
+        texts,
+        model="solar-embedding-1-large-query",
+        api_key=os.getenv("UPSTAGE_API_KEY"),
+        base_url="https://api.upstage.ai/v1/solar"
+    )
+
+async def initialize_rag():
+    rag = LightRAG(
+        working_dir=WORKING_DIR,
+        llm_model_func=llm_model_func,
+        embedding_func=EmbeddingFunc(
+            embedding_dim=4096,
+            func=embedding_func
+        )
+    )
+
+    await rag.initialize_storages()
+    await initialize_pipeline_status()
+
+    return rag
+```
+
+</details>
+
+<details>
+<summary> <b>使用Hugging Face模型</b> </summary>
+
+* 如果您想使用Hugging Face模型，只需要按如下方式设置LightRAG：
+
+参见`lightrag_hf_demo.py`
+
+```python
+# 使用Hugging Face模型初始化LightRAG
+rag = LightRAG(
+    working_dir=WORKING_DIR,
+    llm_model_func=hf_model_complete,  # 使用Hugging Face模型进行文本生成
+    llm_model_name='meta-llama/Llama-3.1-8B-Instruct',  # Hugging Face的模型名称
+    # 使用Hugging Face嵌入函数
+    embedding_func=EmbeddingFunc(
+        embedding_dim=384,
+        func=lambda texts: hf_embed(
+            texts,
+            tokenizer=AutoTokenizer.from_pretrained("sentence-transformers/all-MiniLM-L6-v2"),
+            embed_model=AutoModel.from_pretrained("sentence-transformers/all-MiniLM-L6-v2")
+        )
+    ),
+)
+```
+
+</details>
+
+<details>
+<summary> <b>使用Ollama模型</b> </summary>
+如果您想使用Ollama模型，您需要拉取计划使用的模型和嵌入模型，例如`nomic-embed-text`。
+
+然后您只需要按如下方式设置LightRAG：
+
+```python
+# 使用Ollama模型初始化LightRAG
+rag = LightRAG(
+    working_dir=WORKING_DIR,
+    llm_model_func=ollama_model_complete,  # 使用Ollama模型进行文本生成
+    llm_model_name='your_model_name', # 您的模型名称
+    # 使用Ollama嵌入函数
+    embedding_func=EmbeddingFunc(
+        embedding_dim=768,
+        func=lambda texts: ollama_embed(
+            texts,
+            embed_model="nomic-embed-text"
+        )
+    ),
+)
+```
+
+* **增加上下文大小**
+
+为了使LightRAG正常工作，上下文应至少为32k令牌。默认情况下，Ollama模型的上下文大小为8k。您可以通过以下两种方式之一实现这一点：
+
+* **在Modelfile中增加`num_ctx`参数**
+
+1. 拉取模型：
+
+```bash
+ollama pull qwen2
+```
+
+2. 显示模型文件：
+
+```bash
+ollama show --modelfile qwen2 > Modelfile
+```
+
+3. 编辑Modelfile，添加以下行：
+
+```bash
+PARAMETER num_ctx 32768
+```
+
+4. 创建修改后的模型：
+
+```bash
+ollama create -f Modelfile qwen2m
+```
+
+* **通过Ollama API设置`num_ctx`**
+
+您可以使用`llm_model_kwargs`参数配置ollama：
+
+```python
+rag = LightRAG(
+    working_dir=WORKING_DIR,
+    llm_model_func=ollama_model_complete,  # 使用Ollama模型进行文本生成
+    llm_model_name='your_model_name', # 您的模型名称
+    llm_model_kwargs={"options": {"num_ctx": 32768}},
+    # 使用Ollama嵌入函数
+    embedding_func=EmbeddingFunc(
+        embedding_dim=768,
+        func=lambda texts: ollama_embed(
+            texts,
+            embed_model="nomic-embed-text"
+        )
+    ),
+)
+```
+
+* **低RAM GPU**
+
+为了在低RAM GPU上运行此实验，您应该选择小型模型并调整上下文窗口（增加上下文会增加内存消耗）。例如，在6Gb RAM的改装挖矿GPU上运行这个ollama示例需要将上下文大小设置为26k，同时使用`gemma2:2b`。它能够在`book.txt`中找到197个实体和19个关系。
+
+</details>
+<details>
+<summary> <b>LlamaIndex</b> </summary>
+
+LightRAG支持与LlamaIndex集成 (`llm/llama_index_impl.py`):
+
+- 通过LlamaIndex与OpenAI和其他提供商集成
+- 详细设置和示例请参见[LlamaIndex文档](lightrag/llm/Readme.md)
+
+**使用示例：**
+
+```python
+# 使用LlamaIndex直接访问OpenAI
+import asyncio
+from lightrag import LightRAG
+from lightrag.llm.llama_index_impl import llama_index_complete_if_cache, llama_index_embed
+from llama_index.embeddings.openai import OpenAIEmbedding
+from llama_index.llms.openai import OpenAI
+from lightrag.kg.shared_storage import initialize_pipeline_status
+from lightrag.utils import setup_logger
+
+# 为LightRAG设置日志处理程序
+setup_logger("lightrag", level="INFO")
+
+async def initialize_rag():
+    rag = LightRAG(
+        working_dir="your/path",
+        llm_model_func=llama_index_complete_if_cache,  # LlamaIndex兼容的完成函数
+        embedding_func=EmbeddingFunc(    # LlamaIndex兼容的嵌入函数
+            embedding_dim=1536,
+            func=lambda texts: llama_index_embed(texts, embed_model=embed_model)
+        ),
+    )
+
+    await rag.initialize_storages()
+    await initialize_pipeline_status()
+
+    return rag
+
+def main():
+    # 初始化RAG实例
+    rag = asyncio.run(initialize_rag())
+
+    with open("./book.txt", "r", encoding="utf-8") as f:
+        rag.insert(f.read())
+
+    # 执行朴素搜索
+    print(
+        rag.query("这个故事的主要主题是什么？", param=QueryParam(mode="naive"))
+    )
+
+    # 执行本地搜索
+    print(
+        rag.query("这个故事的主要主题是什么？", param=QueryParam(mode="local"))
+    )
+
+    # 执行全局搜索
+    print(
+        rag.query("这个故事的主要主题是什么？", param=QueryParam(mode="global"))
+    )
+
+    # 执行混合搜索
+    print(
+        rag.query("这个故事的主要主题是什么？", param=QueryParam(mode="hybrid"))
+    )
+
+if __name__ == "__main__":
+    main()
+```
+
+**详细文档和示例，请参见：**
+
+- [LlamaIndex文档](lightrag/llm/Readme.md)
+- [直接OpenAI示例](examples/lightrag_llamaindex_direct_demo.py)
+- [LiteLLM代理示例](examples/lightrag_llamaindex_litellm_demo.py)
+
+</details>
+
+### Rerank函数注入
+
+为了提高检索质量，可以根据更有效的相关性评分模型对文档进行重排序。`rerank.py`文件提供了三个Reranker提供商的驱动函数：
+
+* **Cohere / vLLM**: `cohere_rerank`
+* **Jina AI**: `jina_rerank`
+* **Aliyun阿里云**: `ali_rerank`
+
+您可以将这些函数之一注入到LightRAG对象的`rerank_model_func`属性中。这将使LightRAG的查询功能能够使用注入的函数对检索到的文本块进行重新排序。有关详细用法，请参阅`examples/rerank_example.py`文件。
+
+### 用户提示词 vs. 查询内容
+
+当使用LightRAG查询内容的时候，不要把内容查询和与查询结果无关的输出加工写在一起。因为把两者混在一起会严重影响查询的效果。Query Param中的`user_prompt`就是为解决这一问题而设计的。`user_prompt`中的内容不参与RAG中的查询过程，它仅会在获得查询结果之后，与查询结果一起送给LLM，指导LLM如何处理查询结果。以下是使用方法：
+
+```python
+# Create query parameters
+query_param = QueryParam(
+    mode = "hybrid",  # Other modes：local, global, hybrid, mix, naive
+    user_prompt = "如需画图使用mermaid格式，节点名称用英文或拼音，显示名称用中文",
+)
+
+# Query and process
+response_default = rag.query(
+    "请画出 Scrooge 的人物关系图谱",
+    param=query_param
+)
+print(response_default)
+```
+
+### 插入
+
+<details>
+  <summary> <b> 基本插入 </b></summary>
+
+```python
+# 基本插入
+rag.insert("文本")
+```
+
+</details>
+
+<details>
+  <summary> <b> 批量插入 </b></summary>
+
+```python
+# 基本批量插入：一次插入多个文本
+rag.insert(["文本1", "文本2",...])
+
+# 带有自定义批量大小配置的批量插入
+rag = LightRAG(
+    ...
+    working_dir=WORKING_DIR,
+    max_parallel_insert = 4
+)
+
+rag.insert(["文本1", "文本2", "文本3", ...])  # 文档将以4个为一批进行处理
+```
+
+参数 `max_parallel_insert` 用于控制文档索引流水线中并行处理的文档数量。若未指定，默认值为 **2**。建议将该参数设置为 **10 以下**，因为性能瓶颈通常出现在大语言模型（LLM）的处理环节。
+
+</details>
+
+<details>
+  <summary> <b> 带ID插入 </b></summary>
+
+如果您想为文档提供自己的ID，文档数量和ID数量必须相同。
+
+```python
+# 插入单个文本，并为其提供ID
+rag.insert("文本1", ids=["文本1的ID"])
+
+# 插入多个文本，并为它们提供ID
+rag.insert(["文本1", "文本2",...], ids=["文本1的ID", "文本2的ID"])
+```
+
+</details>
+
+<details>
+  <summary><b>使用流水线插入</b></summary>
+
+`apipeline_enqueue_documents`和`apipeline_process_enqueue_documents`函数允许您对文档进行增量插入到图中。
+
+这对于需要在后台处理文档的场景很有用，同时仍允许主线程继续执行。
+
+并使用例程处理新文档。
+
+```python
+rag = LightRAG(..)
+
+await rag.apipeline_enqueue_documents(input)
+# 您的循环例程
+await rag.apipeline_process_enqueue_documents(input)
+```
+
+</details>
+
+<details>
+  <summary><b>插入多文件类型支持</b></summary>
+
+`textract`支持读取TXT、DOCX、PPTX、CSV和PDF等文件类型。
+
+```python
+import textract
+
+file_path = 'TEXT.pdf'
+text_content = textract.process(file_path)
+
+rag.insert(text_content.decode('utf-8'))
+```
+
+</details>
+
+<details>
+  <summary><b>引文功能</b></summary>
+
+通过提供文件路径，系统确保可以将来源追溯到其原始文档。
+
+```python
+# 定义文档及其文件路径
+documents = ["文档内容1", "文档内容2"]
+file_paths = ["path/to/doc1.txt", "path/to/doc2.txt"]
+
+# 插入带有文件路径的文档
+rag.insert(documents, file_paths=file_paths)
+```
+
+</details>
+
+### 存储
+
+LightRAG 使用 4 种类型的存储用于不同目的：
+
+* KV_STORAGE：llm 响应缓存、文本块、文档信息
+* VECTOR_STORAGE：实体向量、关系向量、块向量
+* GRAPH_STORAGE：实体关系图
+* DOC_STATUS_STORAGE：文档索引状态
+
+每种存储类型都有几种实现：
+
+* KV_STORAGE 支持的实现名称
+
+```
+JsonKVStorage    JsonFile(默认)
+PGKVStorage      Postgres
+RedisKVStorage   Redis
+MongoKVStorage   MogonDB
+```
+
+* GRAPH_STORAGE 支持的实现名称
+
+```
+NetworkXStorage      NetworkX(默认)
+Neo4JStorage         Neo4J
+PGGraphStorage       PostgreSQL with AGE plugin
+```
+
+> 在测试中Neo4j图形数据库相比PostgreSQL AGE有更好的性能表现。
+
+* VECTOR_STORAGE 支持的实现名称
+
+```
+NanoVectorDBStorage         NanoVector(默认)
+PGVectorStorage             Postgres
+MilvusVectorDBStorge        Milvus
+FaissVectorDBStorage        Faiss
+QdrantVectorDBStorage       Qdrant
+MongoVectorDBStorage        MongoDB
+```
+
+* DOC_STATUS_STORAGE 支持的实现名称
+
+```
+JsonDocStatusStorage        JsonFile(默认)
+PGDocStatusStorage          Postgres
+MongoDocStatusStorage       MongoDB
+```
+
+每一种存储类型的链接配置范例可以在 `env.example` 文件中找到。链接字符串中的数据库实例是需要你预先在数据库服务器上创建好的，LightRAG 仅负责在数据库实例中创建数据表，不负责创建数据库实例。如果使用 Redis 作为存储，记得给 Redis 配置自动持久化数据规则，否则 Redis 服务重启后数据会丢失。如果使用PostgreSQL数据库，推荐使用16.6版本或以上。
+
+<details>
+<summary> <b>使用Neo4J存储</b> </summary>
+
+* 对于生产级场景，您很可能想要利用企业级解决方案
+* 进行KG存储。推荐在Docker中运行Neo4J以进行无缝本地测试。
+* 参见：https://hub.docker.com/_/neo4j
+
+```python
+export NEO4J_URI="neo4j://localhost:7687"
+export NEO4J_USERNAME="neo4j"
+export NEO4J_PASSWORD="password"
+
+# 为LightRAG设置日志记录器
+setup_logger("lightrag", level="INFO")
+
+# 当您启动项目时，请确保通过指定kg="Neo4JStorage"来覆盖默认的KG：NetworkX。
+
+# 注意：默认设置使用NetworkX
+# 使用Neo4J实现初始化LightRAG。
+async def initialize_rag():
+    rag = LightRAG(
+        working_dir=WORKING_DIR,
+        llm_model_func=gpt_4o_mini_complete,  # 使用gpt_4o_mini_complete LLM模型
+        graph_storage="Neo4JStorage", #<-----------覆盖KG默认值
+    )
+
+    # 初始化数据库连接
+    await rag.initialize_storages()
+    # 初始化文档处理的管道状态
+    await initialize_pipeline_status()
+
+    return rag
+```
+
+参见test_neo4j.py获取工作示例。
+
+</details>
+
+<details>
+<summary> <b>使用Faiss存储</b> </summary>
+在使用Faiss向量数据库之前必须手工安装`faiss-cpu`或`faiss-gpu`。
+
+- 安装所需依赖：
+
+```
+pip install faiss-cpu
+```
+
+如果您有GPU支持，也可以安装`faiss-gpu`。
+
+- 这里我们使用`sentence-transformers`，但您也可以使用维度为`3072`的`OpenAIEmbedding`模型。
+
+```python
+async def embedding_func(texts: list[str]) -> np.ndarray:
+    model = SentenceTransformer('all-MiniLM-L6-v2')
+    embeddings = model.encode(texts, convert_to_numpy=True)
+    return embeddings
+
+# 使用LLM模型函数和嵌入函数初始化LightRAG
+rag = LightRAG(
+    working_dir=WORKING_DIR,
+    llm_model_func=llm_model_func,
+    embedding_func=EmbeddingFunc(
+        embedding_dim=384,
+        func=embedding_func,
+    ),
+    vector_storage="FaissVectorDBStorage",
+    vector_db_storage_cls_kwargs={
+        "cosine_better_than_threshold": 0.3  # 您期望的阈值
+    }
+)
+```
+
+</details>
+
+<details>
+<summary> <b>使用PostgreSQL存储</b> </summary>
+
+对于生产级场景，您很可能想要利用企业级解决方案。PostgreSQL可以为您提供一站式储解解决方案，作为KV存储、向量数据库（pgvector）和图数据库（apache AGE）。支持 PostgreSQL 版本为16.6或以上。
+
+* 如果您是初学者并想避免麻烦，推荐使用docker，请从这个镜像开始（请务必阅读概述）：https://hub.docker.com/r/shangor/postgres-for-rag
+* Apache AGE的性能不如Neo4j。最求高性能的图数据库请使用Noe4j。
+
+</details>
+
+<details>
+<summary> <b>使用MogonDB存储</b> </summary>
+
+MongoDB为LightRAG提供了一站式的存储解决方案。MongoDB提供原生的KV存储和向量存储。LightRAG使用MogoDB的集合实现了一个简易的图存储。MongoDB 官方的向量检索功能（`$vectorSearch`）目前必须依赖其官方的云服务 MongoDB Atlas。无法在自托管的 MongoDB Community/Enterprise 版本上使用此功能。
+
+</details>
+
+<details>
+<summary> <b>使用Redis存储</b> </summary>
+
+LightRAG支持使用Reidis作为KV存储。使用Redis存储的时候需要注意进行持久化配置和内存使用量配置。以下是推荐的redis配置
+
+```
+save 900 1
+save 300 10
+save 60 1000
+stop-writes-on-bgsave-error yes
+maxmemory 4gb
+maxmemory-policy noeviction
+maxclients 500
+```
+
+</details>
+
+### LightRAG实例间的数据隔离
+
+通过 workspace 参数可以不同实现不同LightRAG实例之间的存储数据隔离。LightRAG在初始化后workspace就已经确定，之后修改workspace是无效的。下面是不同类型的存储实现工作空间的方式：
+
+- **对于本地基于文件的数据库，数据隔离通过工作空间子目录实现：** JsonKVStorage, JsonDocStatusStorage, NetworkXStorage, NanoVectorDBStorage, FaissVectorDBStorage。
+- **对于将数据存储在集合（collection）中的数据库，通过在集合名称前添加工作空间前缀来实现：** RedisKVStorage, RedisDocStatusStorage, MilvusVectorDBStorage, QdrantVectorDBStorage, MongoKVStorage, MongoDocStatusStorage, MongoVectorDBStorage, MongoGraphStorage, PGGraphStorage。
+- **对于关系型数据库，数据隔离通过向表中添加 `workspace` 字段进行数据的逻辑隔离：** PGKVStorage, PGVectorStorage, PGDocStatusStorage。
+
+* **对于Neo4j图数据库，通过label来实现数据的逻辑隔离**：Neo4JStorage
+
+为了保持对遗留数据的兼容，在未配置工作空间时PostgreSQL非图存储的工作空间为`default`，PostgreSQL AGE图存储的工作空间为空，Neo4j图存储的默认工作空间为`base`。对于所有的外部存储，系统都提供了专用的工作空间环境变量，用于覆盖公共的 `WORKSPACE`环境变量配置。这些适用于指定存储类型的工作空间环境变量为：`REDIS_WORKSPACE`, `MILVUS_WORKSPACE`, `QDRANT_WORKSPACE`, `MONGODB_WORKSPACE`, `POSTGRES_WORKSPACE`, `NEO4J_WORKSPACE`。
+
+## 编辑实体和关系
+
+LightRAG现在支持全面的知识图谱管理功能，允许您在知识图谱中创建、编辑和删除实体和关系。
+
+<details>
+<summary> <b>创建实体和关系</b> </summary>
+
+```python
+# 创建新实体
+entity = rag.create_entity("Google", {
+    "description": "Google是一家专注于互联网相关服务和产品的跨国科技公司。",
+    "entity_type": "company"
+})
+
+# 创建另一个实体
+product = rag.create_entity("Gmail", {
+    "description": "Gmail是由Google开发的电子邮件服务。",
+    "entity_type": "product"
+})
+
+# 创建实体之间的关系
+relation = rag.create_relation("Google", "Gmail", {
+    "description": "Google开发和运营Gmail。",
+    "keywords": "开发 运营 服务",
+    "weight": 2.0
+})
+```
+
+</details>
+
+<details>
+<summary> <b>编辑实体和关系</b> </summary>
+
+```python
+# 编辑现有实体
+updated_entity = rag.edit_entity("Google", {
+    "description": "Google是Alphabet Inc.的子公司，成立于1998年。",
+    "entity_type": "tech_company"
+})
+
+# 重命名实体（所有关系都会正确迁移）
+renamed_entity = rag.edit_entity("Gmail", {
+    "entity_name": "Google Mail",
+    "description": "Google Mail（前身为Gmail）是一项电子邮件服务。"
+})
+
+# 编辑实体之间的关系
+updated_relation = rag.edit_relation("Google", "Google Mail", {
+    "description": "Google创建并维护Google Mail服务。",
+    "keywords": "创建 维护 电子邮件服务",
+    "weight": 3.0
+})
+```
+
+所有操作都有同步和异步版本。异步版本带有前缀"a"（例如，`acreate_entity`，`aedit_relation`）。
+
+</details>
+
+<details>
+<summary> <b>插入自定义知识</b> </summary>
+
+```python
+custom_kg = {
+    "chunks": [
+        {
+            "content": "Alice和Bob正在合作进行量子计算研究。",
+            "source_id": "doc-1"
+        }
+    ],
+    "entities": [
+        {
+            "entity_name": "Alice",
+            "entity_type": "person",
+            "description": "Alice是一位专门研究量子物理的研究员。",
+            "source_id": "doc-1"
+        },
+        {
+            "entity_name": "Bob",
+            "entity_type": "person",
+            "description": "Bob是一位数学家。",
+            "source_id": "doc-1"
+        },
+        {
+            "entity_name": "量子计算",
+            "entity_type": "technology",
+            "description": "量子计算利用量子力学现象进行计算。",
+            "source_id": "doc-1"
+        }
+    ],
+    "relationships": [
+        {
+            "src_id": "Alice",
+            "tgt_id": "Bob",
+            "description": "Alice和Bob是研究伙伴。",
+            "keywords": "合作 研究",
+            "weight": 1.0,
+            "source_id": "doc-1"
+        },
+        {
+            "src_id": "Alice",
+            "tgt_id": "量子计算",
+            "description": "Alice进行量子计算研究。",
+            "keywords": "研究 专业",
+            "weight": 1.0,
+            "source_id": "doc-1"
+        },
+        {
+            "src_id": "Bob",
+            "tgt_id": "量子计算",
+            "description": "Bob研究量子计算。",
+            "keywords": "研究 应用",
+            "weight": 1.0,
+            "source_id": "doc-1"
+        }
+    ]
+}
+
+rag.insert_custom_kg(custom_kg)
+```
+
+</details>
+
+<details>
+<summary> <b>其它实体与关系操作</b> </summary>
+
+- **create_entity**：创建具有指定属性的新实体
+- **edit_entity**：更新现有实体的属性或重命名它
+
+- **create_relation**：在现有实体之间创建新关系
+- **edit_relation**：更新现有关系的属性
+
+这些操作在图数据库和向量数据库组件之间保持数据一致性，确保您的知识图谱保持连贯。
+
+</details>
+
+## 删除功能
+
+LightRAG提供了全面的删除功能，允许您删除文档、实体和关系。
+
+<details>
+<summary> <b>删除实体</b> </summary>
+
+您可以通过实体名称删除实体及其所有关联关系：
+
+```python
+# 删除实体及其所有关系（同步版本）
+rag.delete_by_entity("Google")
+
+# 异步版本
+await rag.adelete_by_entity("Google")
+```
+
+删除实体时会：
+- 从知识图谱中移除该实体节点
+- 删除该实体的所有关联关系
+- 从向量数据库中移除相关的嵌入向量
+- 保持知识图谱的完整性
+
+</details>
+
+<details>
+<summary> <b>删除关系</b> </summary>
+
+您可以删除两个特定实体之间的关系：
+
+```python
+# 删除两个实体之间的关系（同步版本）
+rag.delete_by_relation("Google", "Gmail")
+
+# 异步版本
+await rag.adelete_by_relation("Google", "Gmail")
+```
+
+删除关系时会：
+- 移除指定的关系边
+- 从向量数据库中删除关系的嵌入向量
+- 保留两个实体节点及其他关系
+
+</details>
+
+<details>
+<summary> <b>通过文档ID删除</b> </summary>
+
+您可以通过文档ID删除整个文档及其相关的所有知识：
+
+```python
+# 通过文档ID删除（异步版本）
+await rag.adelete_by_doc_id("doc-12345")
+```
+
+通过文档ID删除时的优化处理：
+- **智能清理**：自动识别并删除仅属于该文档的实体和关系
+- **保留共享知识**：如果实体或关系在其他文档中也存在，则会保留并重新构建描述
+- **缓存优化**：清理相关的LLM缓存以减少存储开销
+- **增量重建**：从剩余文档重新构建受影响的实体和关系描述
+
+删除过程包括：
+1. 删除文档相关的所有文本块
+2. 识别仅属于该文档的实体和关系并删除
+3. 重新构建在其他文档中仍存在的实体和关系
+4. 更新所有相关的向量索引
+5. 清理文档状态记录
+
+注意：通过文档ID删除是一个异步操作，因为它涉及复杂的知识图谱重构过程。
+
+</details>
+
+<details>
+<summary> <b>删除注意事项</b> </summary>
+
+**重要提醒：**
+
+1. **不可逆操作**：所有删除操作都是不可逆的，请谨慎使用
+2. **性能考虑**：删除大量数据时可能需要一些时间，特别是通过文档ID删除
+3. **数据一致性**：删除操作会自动维护知识图谱和向量数据库之间的一致性
+4. **备份建议**：在执行重要删除操作前建议备份数据
+
+**批量删除建议：**
+- 对于批量删除操作，建议使用异步方法以获得更好的性能
+- 大规模删除时，考虑分批进行以避免系统负载过高
+
+</details>
+
+## 实体合并
+
+<details>
+<summary> <b>合并实体及其关系</b> </summary>
+
+LightRAG现在支持将多个实体合并为单个实体，自动处理所有关系：
+
+```python
+# 基本实体合并
+rag.merge_entities(
+    source_entities=["人工智能", "AI", "机器智能"],
+    target_entity="AI技术"
+)
+```
+
+使用自定义合并策略：
+
+```python
+# 为不同字段定义自定义合并策略
+rag.merge_entities(
+    source_entities=["约翰·史密斯", "史密斯博士", "J·史密斯"],
+    target_entity="约翰·史密斯",
+    merge_strategy={
+        "description": "concatenate",  # 组合所有描述
+        "entity_type": "keep_first",   # 保留第一个实体的类型
+        "source_id": "join_unique"     # 组合所有唯一的源ID
+    }
+)
+```
+
+使用自定义目标实体数据：
+
+```python
+# 为合并后的实体指定确切值
+rag.merge_entities(
+    source_entities=["纽约", "NYC", "大苹果"],
+    target_entity="纽约市",
+    target_entity_data={
+        "entity_type": "LOCATION",
+        "description": "纽约市是美国人口最多的城市。",
+    }
+)
+```
+
+结合两种方法的高级用法：
+
+```python
+# 使用策略和自定义数据合并公司实体
+rag.merge_entities(
+    source_entities=["微软公司", "Microsoft Corporation", "MSFT"],
+    target_entity="微软",
+    merge_strategy={
+        "description": "concatenate",  # 组合所有描述
+        "source_id": "join_unique"     # 组合源ID
+    },
+    target_entity_data={
+        "entity_type": "ORGANIZATION",
+    }
+)
+```
+
+合并实体时：
+
+* 所有来自源实体的关系都会重定向到目标实体
+* 重复的关系会被智能合并
+* 防止自我关系（循环）
+* 合并后删除源实体
+* 保留关系权重和属性
+
+</details>
+
+## 多模态文档处理（RAG-Anything集成）
+
+LightRAG 现已与 [RAG-Anything](https://github.com/HKUDS/RAG-Anything) 实现无缝集成，这是一个专为 LightRAG 构建的**全能多模态文档处理RAG系统**。RAG-Anything 提供先进的解析和检索增强生成（RAG）能力，让您能够无缝处理多模态文档，并从各种文档格式中提取结构化内容——包括文本、图片、表格和公式——以集成到您的RAG流程中。
+
+**主要特性：**
+- **端到端多模态流程**：从文档摄取解析到智能多模态问答的完整工作流程
+- **通用文档支持**：无缝处理PDF、Office文档（DOC/DOCX/PPT/PPTX/XLS/XLSX）、图片和各种文件格式
+- **专业内容分析**：针对图片、表格、数学公式和异构内容类型的专用处理器
+- **多模态知识图谱**：自动实体提取和跨模态关系发现以增强理解
+- **混合智能检索**：覆盖文本和多模态内容的高级搜索能力，具备上下文理解
+
+**快速开始：**
+1. 安装RAG-Anything：
+   ```bash
+   pip install raganything
+   ```
+2. 处理多模态文档：
+    <details>
+    <summary> <b> RAGAnything 使用示例 </b></summary>
+
+    ```python
+        import asyncio
+        from raganything import RAGAnything
+        from lightrag import LightRAG
+        from lightrag.llm.openai import openai_complete_if_cache, openai_embed
+        from lightrag.utils import EmbeddingFunc
+        import os
+
+        async def load_existing_lightrag():
+            # 首先，创建或加载现有的 LightRAG 实例
+            lightrag_working_dir = "./existing_lightrag_storage"
+
+            # 检查是否存在之前的 LightRAG 实例
+            if os.path.exists(lightrag_working_dir) and os.listdir(lightrag_working_dir):
+                print("✅ Found existing LightRAG instance, loading...")
+            else:
+                print("❌ No existing LightRAG instance found, will create new one")
+
+            # 使用您的配置创建/加载 LightRAG 实例
+            lightrag_instance = LightRAG(
+                working_dir=lightrag_working_dir,
+                llm_model_func=lambda prompt, system_prompt=None, history_messages=[], **kwargs: openai_complete_if_cache(
+                    "gpt-4o-mini",
+                    prompt,
+                    system_prompt=system_prompt,
+                    history_messages=history_messages,
+                    api_key="your-api-key",
+                    **kwargs,
+                ),
+                embedding_func=EmbeddingFunc(
+                    embedding_dim=3072,
+                    func=lambda texts: openai_embed(
+                        texts,
+                        model="text-embedding-3-large",
+                        api_key=api_key,
+                        base_url=base_url,
+                    ),
+                )
+            )
+
+            # 初始化存储（如果有现有数据，这将加载现有数据）
+            await lightrag_instance.initialize_storages()
+
+            # 现在使用现有的 LightRAG 实例初始化 RAGAnything
+            rag = RAGAnything(
+                lightrag=lightrag_instance,  # 传递现有的 LightRAG 实例
+                # 仅需要视觉模型用于多模态处理
+                vision_model_func=lambda prompt, system_prompt=None, history_messages=[], image_data=None, **kwargs: openai_complete_if_cache(
+                    "gpt-4o",
+                    "",
+                    system_prompt=None,
+                    history_messages=[],
+                    messages=[
+                        {"role": "system", "content": system_prompt} if system_prompt else None,
+                        {"role": "user", "content": [
+                            {"type": "text", "text": prompt},
+                            {"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{image_data}"}}
+                        ]} if image_data else {"role": "user", "content": prompt}
+                    ],
+                    api_key="your-api-key",
+                    **kwargs,
+                ) if image_data else openai_complete_if_cache(
+                    "gpt-4o-mini",
+                    prompt,
+                    system_prompt=system_prompt,
+                    history_messages=history_messages,
+                    api_key="your-api-key",
+                    **kwargs,
+                )
+                # 注意：working_dir、llm_model_func��embedding_func 等都从 lightrag_instance 继承
+            )
+
+            # 查询现有的知识库
+            result = await rag.query_with_multimodal(
+                "What data has been processed in this LightRAG instance?",
+                mode="hybrid"
+            )
+            print("Query result:", result)
+
+            # 向现有的 LightRAG 实例添加新的多模态文档
+            await rag.process_document_complete(
+                file_path="path/to/new/multimodal_document.pdf",
+                output_dir="./output"
+            )
+
+        if __name__ == "__main__":
+            asyncio.run(load_existing_lightrag())
+    ```
+
+    </details>
+
+如需详细文档和高级用法，请参阅 [RAG-Anything 仓库](https://github.com/HKUDS/RAG-Anything)。
+
+## Token统计功能
+
+<details>
+<summary> <b>概述和使用</b> </summary>
+
+LightRAG提供了TokenTracker工具来跟踪和管理大模型的token消耗。这个功能对于控制API成本和优化性能特别有用。
+
+### 使用方法
+
+```python
+from lightrag.utils import TokenTracker
+
+# 创建TokenTracker实例
+token_tracker = TokenTracker()
+
+# 方法1：使用上下文管理器（推荐）
+# 适用于需要自动跟踪token使用的场景
+with token_tracker:
+    result1 = await llm_model_func("你的问题1")
+    result2 = await llm_model_func("你的问题2")
+
+# 方法2：手动添加token使用记录
+# 适用于需要更精细控制token统计的场景
+token_tracker.reset()
+
+rag.insert()
+
+rag.query("你的问题1", param=QueryParam(mode="naive"))
+rag.query("你的问题2", param=QueryParam(mode="mix"))
+
+# 显示总token使用量（包含插入和查询操作）
+print("Token usage:", token_tracker.get_usage())
+```
+
+### 使用建议
+- 在长会话或批量操作中使用上下文管理器，可以自动跟踪所有token消耗
+- 对于需要分段统计的场景，使用手动模式并适时调用reset()
+- 定期检查token使用情况，有助于及时发现异常消耗
+- 在开发测试阶段积极使用此功能，以便优化生产环境的成本
+
+### 实际应用示例
+您可以参考以下示例来实现token统计：
+- `examples/lightrag_gemini_track_token_demo.py`：使用Google Gemini模型的token统计示例
+- `examples/lightrag_siliconcloud_track_token_demo.py`：使用SiliconCloud模型的token统计示例
+
+这些示例展示了如何在不同模型和场景下有效地使用TokenTracker功能。
+
+</details>
+
+## 数据导出功能
+
+### 概述
+
+LightRAG允许您以各种格式导出知识图谱数据，用于分析、共享和备份目的。系统支持导出实体、关系和关系数据。
+
+### 导出功能
+
+#### 基本用法
+
+```python
+# 基本CSV导出（默认格式）
+rag.export_data("knowledge_graph.csv")
+
+# 指定任意格式
+rag.export_data("output.xlsx", file_format="excel")
+```
+
+#### 支持的不同文件格式
+
+```python
+# 以CSV格式导出数据
+rag.export_data("graph_data.csv", file_format="csv")
+
+# 导出数据到Excel表格
+rag.export_data("graph_data.xlsx", file_format="excel")
+
+# 以markdown格式导出数据
+rag.export_data("graph_data.md", file_format="md")
+
+# 导出数据为文本
+rag.export_data("graph_data.txt", file_format="txt")
+```
+
+#### 附加选项
+
+在导出中包含向量嵌入（可选）：
+
+```python
+rag.export_data("complete_data.csv", include_vector_data=True)
+```
+
+### 导出数据包括
+
+所有导出包括：
+
+* 实体信息（名称、ID、元数据）
+* 关系数据（实体之间的连接）
+* 来自向量数据库的关系信息
+
+## 缓存
+
+<details>
+  <summary> <b>清除缓存</b> </summary>
+
+您可以使用不同模式清除LLM响应缓存：
+
+```python
+# 清除所有缓存
+await rag.aclear_cache()
+
+# 清除本地模式缓存
+await rag.aclear_cache(modes=["local"])
+
+# 清除提取缓存
+await rag.aclear_cache(modes=["default"])
+
+# 清除多个模式
+await rag.aclear_cache(modes=["local", "global", "hybrid"])
+
+# 同步版本
+rag.clear_cache(modes=["local"])
+```
+
+有效的模式包括：
+
+- `"default"`：提取缓存
+- `"naive"`：朴素搜索缓存
+- `"local"`：本地搜索缓存
+- `"global"`：全局搜索缓存
+- `"hybrid"`：混合搜索缓存
+- `"mix"`：混合搜索缓存
+
+</details>
+
+## LightRAG API
+
+LightRAG服务器旨在提供Web UI和API支持。**有关LightRAG服务器的更多信息，请参阅[LightRAG服务器](./lightrag/api/README.md)。**
+
+## 知识图谱可视化
+
+LightRAG服务器提供全面的知识图谱可视化功能。它支持各种重力布局、节点查询、子图过滤等。**有关LightRAG服务器的更多信息，请参阅[LightRAG服务器](./lightrag/api/README.md)。**
+
+![iShot_2025-03-23_12.40.08](./README.assets/iShot_2025-03-23_12.40.08.png)
+
+## 评估
+
+### 数据集
+
+LightRAG使用的数据集可以从[TommyChien/UltraDomain](https://huggingface.co/datasets/TommyChien/UltraDomain)下载。
+
+### 生成查询
+
+LightRAG使用以下提示生成高级查询，相应的代码在`example/generate_query.py`中。
+
+<details>
+<summary> 提示 </summary>
+
+```python
+给定以下数据集描述：
+
+{description}
+
+请识别5个可能会使用此数据集的潜在用户。对于每个用户，列出他们会使用此数据集执行的5个任务。然后，对于每个（用户，任务）组合，生成5个需要对整个数据集有高级理解的问题。
+
+按以下结构输出结果：
+- 用户1：[用户描述]
+    - 任务1：[任务描述]
+        - 问题1：
+        - 问题2：
+        - 问题3：
+        - 问题4：
+        - 问题5：
+    - 任务2：[任务描述]
+        ...
+    - 任务5：[任务描述]
+- 用户2：[用户描述]
+    ...
+- 用户5：[用户描述]
+    ...
+```
+
+</details>
+
+### 批量评估
+
+为了评估两个RAG系统在高级查询上的性能，LightRAG使用以下提示，具体代码可在`example/batch_eval.py`中找到。
+
+<details>
+<summary> 提示 </summary>
+
+```python
+---角色---
+您是一位专家，负责根据三个标准评估同一问题的两个答案：**全面性**、**多样性**和**赋能性**。
+---目标---
+您将根据三个标准评估同一问题的两个答案：**全面性**、**多样性**和**赋能性**。
+
+- **全面性**：答案提供了多少细节来涵盖问题的所有方面和细节？
+- **多样性**：答案在提供关于问题的不同视角和见解方面有多丰富多样？
+- **赋能性**：答案在多大程度上帮助读者理解并对主题做出明智判断？
+
+对于每个标准，选择更好的答案（答案1或答案2）并解释原因。然后，根据这三个类别选择总体赢家。
+
+这是问题：
+{query}
+
+这是两个答案：
+
+**答案1：**
+{answer1}
+
+**答案2：**
+{answer2}
+
+使用上述三个标准评估两个答案，并为每个标准提供详细解释。
+
+以下列JSON格式输出您的评估：
+
+{{
+    "全面性": {{
+        "获胜者": "[答案1或答案2]",
+        "解释": "[在此提供解释]"
+    }},
+    "赋能性": {{
+        "获胜者": "[答案1或答案2]",
+        "解释": "[在此提供解释]"
+    }},
+    "总体获胜者": {{
+        "获胜者": "[答案1或答案2]",
+        "解释": "[根据三个标准总结为什么这个答案是总体获胜者]"
+    }}
+}}
+```
+
+</details>
+
+### 总体性能表
+
+|                      |**农业**|            |**计算机科学**|            |**法律**|            |**混合**|            |
+|----------------------|---------------|------------|------|------------|---------|------------|-------|------------|
+|                      |NaiveRAG|**LightRAG**|NaiveRAG|**LightRAG**|NaiveRAG|**LightRAG**|NaiveRAG|**LightRAG**|
+|**全面性**|32.4%|**67.6%**|38.4%|**61.6%**|16.4%|**83.6%**|38.8%|**61.2%**|
+|**多样性**|23.6%|**76.4%**|38.0%|**62.0%**|13.6%|**86.4%**|32.4%|**67.6%**|
+|**赋能性**|32.4%|**67.6%**|38.8%|**61.2%**|16.4%|**83.6%**|42.8%|**57.2%**|
+|**总体**|32.4%|**67.6%**|38.8%|**61.2%**|15.2%|**84.8%**|40.0%|**60.0%**|
+|                      |RQ-RAG|**LightRAG**|RQ-RAG|**LightRAG**|RQ-RAG|**LightRAG**|RQ-RAG|**LightRAG**|
+|**全面性**|31.6%|**68.4%**|38.8%|**61.2%**|15.2%|**84.8%**|39.2%|**60.8%**|
+|**多样性**|29.2%|**70.8%**|39.2%|**60.8%**|11.6%|**88.4%**|30.8%|**69.2%**|
+|**赋能性**|31.6%|**68.4%**|36.4%|**63.6%**|15.2%|**84.8%**|42.4%|**57.6%**|
+|**总体**|32.4%|**67.6%**|38.0%|**62.0%**|14.4%|**85.6%**|40.0%|**60.0%**|
+|                      |HyDE|**LightRAG**|HyDE|**LightRAG**|HyDE|**LightRAG**|HyDE|**LightRAG**|
+|**全面性**|26.0%|**74.0%**|41.6%|**58.4%**|26.8%|**73.2%**|40.4%|**59.6%**|
+|**多样性**|24.0%|**76.0%**|38.8%|**61.2%**|20.0%|**80.0%**|32.4%|**67.6%**|
+|**赋能性**|25.2%|**74.8%**|40.8%|**59.2%**|26.0%|**74.0%**|46.0%|**54.0%**|
+|**总体**|24.8%|**75.2%**|41.6%|**58.4%**|26.4%|**73.6%**|42.4%|**57.6%**|
+|                      |GraphRAG|**LightRAG**|GraphRAG|**LightRAG**|GraphRAG|**LightRAG**|GraphRAG|**LightRAG**|
+|**全面性**|45.6%|**54.4%**|48.4%|**51.6%**|48.4%|**51.6%**|**50.4%**|49.6%|
+|**多样性**|22.8%|**77.2%**|40.8%|**59.2%**|26.4%|**73.6%**|36.0%|**64.0%**|
+|**赋能性**|41.2%|**58.8%**|45.2%|**54.8%**|43.6%|**56.4%**|**50.8%**|49.2%|
+|**总体**|45.2%|**54.8%**|48.0%|**52.0%**|47.2%|**52.8%**|**50.4%**|49.6%|
+
+## 复现
+
+所有代码都可以在`./reproduce`目录中找到。
+
+### 步骤0 提取唯一上下文
+
+首先，我们需要提取数据集中的唯一上下文。
+
+<details>
+<summary> 代码 </summary>
+
+```python
+def extract_unique_contexts(input_directory, output_directory):
+
+    os.makedirs(output_directory, exist_ok=True)
+
+    jsonl_files = glob.glob(os.path.join(input_directory, '*.jsonl'))
+    print(f"找到{len(jsonl_files)}个JSONL文件。")
+
+    for file_path in jsonl_files:
+        filename = os.path.basename(file_path)
+        name, ext = os.path.splitext(filename)
+        output_filename = f"{name}_unique_contexts.json"
+        output_path = os.path.join(output_directory, output_filename)
+
+        unique_contexts_dict = {}
+
+        print(f"处理��件：{filename}")
+
+        try:
+            with open(file_path, 'r', encoding='utf-8') as infile:
+                for line_number, line in enumerate(infile, start=1):
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        json_obj = json.loads(line)
+                        context = json_obj.get('context')
+                        if context and context not in unique_contexts_dict:
+                            unique_contexts_dict[context] = None
+                    except json.JSONDecodeError as e:
+                        print(f"文件{filename}第{line_number}行JSON解码错误：{e}")
+        except FileNotFoundError:
+            print(f"未找到文件：{filename}")
+            continue
+        except Exception as e:
+            print(f"处理文件{filename}时发生错误：{e}")
+            continue
+
+        unique_contexts_list = list(unique_contexts_dict.keys())
+        print(f"文件{filename}中有{len(unique_contexts_list)}个唯一的`context`条目。")
+
+        try:
+            with open(output_path, 'w', encoding='utf-8') as outfile:
+                json.dump(unique_contexts_list, outfile, ensure_ascii=False, indent=4)
+            print(f"唯一的`context`条目已保存到：{output_filename}")
+        except Exception as e:
+            print(f"保存到文件{output_filename}时发生错误：{e}")
+
+    print("所有文件已处理完成。")
+
+```
+
+</details>
+
+### 步骤1 插入上下文
+
+对于提取的上下文，我们将它们插入到LightRAG系统中。
+
+<details>
+<summary> 代码 </summary>
+
+```python
+def insert_text(rag, file_path):
+    with open(file_path, mode='r') as f:
+        unique_contexts = json.load(f)
+
+    retries = 0
+    max_retries = 3
+    while retries < max_retries:
+        try:
+            rag.insert(unique_contexts)
+            break
+        except Exception as e:
+            retries += 1
+            print(f"插入失败，重试（{retries}/{max_retries}），错误：{e}")
+            time.sleep(10)
+    if retries == max_retries:
+        print("超过最大重试次数后插入失败")
+```
+
+</details>
+
+### 步骤2 生成查询
+
+我们从数据集中每个上下文的前半部分和后半部分提取令牌，然后将它们组合为数据集描述以生成查询。
+
+<details>
+<summary> 代码 </summary>
+
+```python
+tokenizer = GPT2Tokenizer.from_pretrained('gpt2')
+
+def get_summary(context, tot_tokens=2000):
+    tokens = tokenizer.tokenize(context)
+    half_tokens = tot_tokens // 2
+
+    start_tokens = tokens[1000:1000 + half_tokens]
+    end_tokens = tokens[-(1000 + half_tokens):1000]
+
+    summary_tokens = start_tokens + end_tokens
+    summary = tokenizer.convert_tokens_to_string(summary_tokens)
+
+    return summary
+```
+
+</details>
+
+### 步骤3 查询
+
+对于步骤2中生成的查询，我们将提取它们并查询LightRAG。
+
+<details>
+<summary> 代码 </summary>
+
+```python
+def extract_queries(file_path):
+    with open(file_path, 'r') as f:
+        data = f.read()
+
+    data = data.replace('**', '')
+
+    queries = re.findall(r'- Question \d+: (.+)', data)
+
+    return queries
+```
+
+</details>
+
+## Star历史
+
+<a href="https://star-history.com/#HKUDS/LightRAG&Date">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=HKUDS/LightRAG&type=Date&theme=dark" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=HKUDS/LightRAG&type=Date" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=HKUDS/LightRAG&type=Date" />
+ </picture>
+</a>
+
+## 贡献
+
+感谢所有贡献者！
+
+<a href="https://github.com/HKUDS/LightRAG/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=HKUDS/LightRAG" />
+</a>
+
+## 🌟引用
+
+```python
+@article{guo2024lightrag,
+title={LightRAG: Simple and Fast Retrieval-Augmented Generation},
+author={Zirui Guo and Lianghao Xia and Yanhua Yu and Tu Ao and Chao Huang},
+year={2024},
+eprint={2410.05779},
+archivePrefix={arXiv},
+primaryClass={cs.IR}
+}
+```
+
+**感谢您对我们工作的关注！**

LightRAG/README.md

@@ -0,0 +1,1889 @@
+<div align="center">
+
+<div style="margin: 20px 0;">
+  <img src="./assets/logo.png" width="120" height="120" alt="LightRAG Logo" style="border-radius: 20px; box-shadow: 0 8px 32px rgba(0, 217, 255, 0.3);">
+</div>
+
+# 🚀 LightRAG: Simple and Fast Retrieval-Augmented Generation
+
+<div align="center">
+    <a href="https://trendshift.io/repositories/13043" target="_blank"><img src="https://trendshift.io/api/badge/repositories/13043" alt="HKUDS%2FLightRAG | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
+</div>
+
+<div align="center">
+  <div style="width: 100%; height: 2px; margin: 20px 0; background: linear-gradient(90deg, transparent, #00d9ff, transparent);"></div>
+</div>
+
+<div align="center">
+  <div style="background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); border-radius: 15px; padding: 25px; text-align: center;">
+    <p>
+      <a href='https://github.com/HKUDS/LightRAG'><img src='https://img.shields.io/badge/🔥Project-Page-00d9ff?style=for-the-badge&logo=github&logoColor=white&labelColor=1a1a2e'></a>
+      <a href='https://arxiv.org/abs/2410.05779'><img src='https://img.shields.io/badge/📄arXiv-2410.05779-ff6b6b?style=for-the-badge&logo=arxiv&logoColor=white&labelColor=1a1a2e'></a>
+      <a href="https://github.com/HKUDS/LightRAG/stargazers"><img src='https://img.shields.io/github/stars/HKUDS/LightRAG?color=00d9ff&style=for-the-badge&logo=star&logoColor=white&labelColor=1a1a2e' /></a>
+    </p>
+    <p>
+      <img src="https://img.shields.io/badge/🐍Python-3.10-4ecdc4?style=for-the-badge&logo=python&logoColor=white&labelColor=1a1a2e">
+      <a href="https://pypi.org/project/lightrag-hku/"><img src="https://img.shields.io/pypi/v/lightrag-hku.svg?style=for-the-badge&logo=pypi&logoColor=white&labelColor=1a1a2e&color=ff6b6b"></a>
+    </p>
+    <p>
+      <a href="https://discord.gg/yF2MmDJyGJ"><img src="https://img.shields.io/badge/💬Discord-Community-7289da?style=for-the-badge&logo=discord&logoColor=white&labelColor=1a1a2e"></a>
+      <a href="https://github.com/HKUDS/LightRAG/issues/285"><img src="https://img.shields.io/badge/💬WeChat-Group-07c160?style=for-the-badge&logo=wechat&logoColor=white&labelColor=1a1a2e"></a>
+    </p>
+    <p>
+      <a href="README-zh.md"><img src="https://img.shields.io/badge/🇨🇳中文版-1a1a2e?style=for-the-badge"></a>
+      <a href="README.md"><img src="https://img.shields.io/badge/🇺🇸English-1a1a2e?style=for-the-badge"></a>
+    </p>
+    <p>
+      <a href="https://pepy.tech/projects/lightrag-hku"><img src="https://static.pepy.tech/personalized-badge/lightrag-hku?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads"></a>
+    </p>
+  </div>
+</div>
+
+</div>
+
+<div align="center" style="margin: 30px 0;">
+  <img src="https://user-images.githubusercontent.com/74038190/212284100-561aa473-3905-4a80-b561-0d28506553ee.gif" width="800">
+</div>
+
+<div align="center" style="margin: 30px 0;">
+    <img src="./README.assets/b2aaf634151b4706892693ffb43d9093.png" width="800" alt="LightRAG Diagram">
+</div>
+
+---
+## 🎉 News
+- [X] [2025.06.16]🎯📢Our team has released [RAG-Anything](https://github.com/HKUDS/RAG-Anything) an All-in-One Multimodal RAG System for seamless text, image, table, and equation processing.
+- [X] [2025.06.05]🎯📢LightRAG now supports comprehensive multimodal data handling through [RAG-Anything](https://github.com/HKUDS/RAG-Anything) integration, enabling seamless document parsing and RAG capabilities across diverse formats including PDFs, images, Office documents, tables, and formulas. Please refer to the new [multimodal section](https://github.com/HKUDS/LightRAG/?tab=readme-ov-file#multimodal-document-processing-rag-anything-integration) for details.
+- [X] [2025.03.18]🎯📢LightRAG now supports citation functionality, enabling proper source attribution.
+- [X] [2025.02.05]🎯📢Our team has released [VideoRAG](https://github.com/HKUDS/VideoRAG) understanding extremely long-context videos.
+- [X] [2025.01.13]🎯📢Our team has released [MiniRAG](https://github.com/HKUDS/MiniRAG) making RAG simpler with small models.
+- [X] [2025.01.06]🎯📢You can now [use PostgreSQL for Storage](#using-postgresql-for-storage).
+- [X] [2024.12.31]🎯📢LightRAG now supports [deletion by document ID](https://github.com/HKUDS/LightRAG?tab=readme-ov-file#delete).
+- [X] [2024.11.25]🎯📢LightRAG now supports seamless integration of [custom knowledge graphs](https://github.com/HKUDS/LightRAG?tab=readme-ov-file#insert-custom-kg), empowering users to enhance the system with their own domain expertise.
+- [X] [2024.11.19]🎯📢A comprehensive guide to LightRAG is now available on [LearnOpenCV](https://learnopencv.com/lightrag). Many thanks to the blog author.
+- [X] [2024.11.11]🎯📢LightRAG now supports [deleting entities by their names](https://github.com/HKUDS/LightRAG?tab=readme-ov-file#delete).
+- [X] [2024.11.09]🎯📢Introducing the [LightRAG Gui](https://lightrag-gui.streamlit.app), which allows you to insert, query, visualize, and download LightRAG knowledge.
+- [X] [2024.11.04]🎯📢You can now [use Neo4J for Storage](https://github.com/HKUDS/LightRAG?tab=readme-ov-file#using-neo4j-for-storage).
+- [X] [2024.10.29]🎯📢LightRAG now supports multiple file types, including PDF, DOC, PPT, and CSV via `textract`.
+- [X] [2024.10.20]🎯📢We've added a new feature to LightRAG: Graph Visualization.
+- [X] [2024.10.18]🎯📢We've added a link to a [LightRAG Introduction Video](https://youtu.be/oageL-1I0GE). Thanks to the author!
+- [X] [2024.10.17]🎯📢We have created a [Discord channel](https://discord.gg/yF2MmDJyGJ)! Welcome to join for sharing and discussions! 🎉🎉
+- [X] [2024.10.16]🎯📢LightRAG now supports [Ollama models](https://github.com/HKUDS/LightRAG?tab=readme-ov-file#quick-start)!
+- [X] [2024.10.15]🎯📢LightRAG now supports [Hugging Face models](https://github.com/HKUDS/LightRAG?tab=readme-ov-file#quick-start)!
+
+<details>
+  <summary style="font-size: 1.4em; font-weight: bold; cursor: pointer; display: list-item;">
+    Algorithm Flowchart
+  </summary>
+
+![LightRAG Indexing Flowchart](https://learnopencv.com/wp-content/uploads/2024/11/LightRAG-VectorDB-Json-KV-Store-Indexing-Flowchart-scaled.jpg)
+*Figure 1: LightRAG Indexing Flowchart - Img Caption : [Source](https://learnopencv.com/lightrag/)*
+![LightRAG Retrieval and Querying Flowchart](https://learnopencv.com/wp-content/uploads/2024/11/LightRAG-Querying-Flowchart-Dual-Level-Retrieval-Generation-Knowledge-Graphs-scaled.jpg)
+*Figure 2: LightRAG Retrieval and Querying Flowchart - Img Caption : [Source](https://learnopencv.com/lightrag/)*
+
+</details>
+
+## Installation
+
+### Install LightRAG Server
+
+The LightRAG Server is designed to provide Web UI and API support. The Web UI facilitates document indexing, knowledge graph exploration, and a simple RAG query interface. LightRAG Server also provide an Ollama compatible interfaces, aiming to emulate LightRAG as an Ollama chat model. This allows AI chat bot, such as Open WebUI, to access LightRAG easily.
+
+* Install from PyPI
+
+```bash
+pip install "lightrag-hku[api]"
+cp env.example .env
+lightrag-server
+```
+
+* Installation from Source
+
+```bash
+git clone https://github.com/HKUDS/LightRAG.git
+cd LightRAG
+# create a Python virtual enviroment if neccesary
+# Install in editable mode with API support
+pip install -e ".[api]"
+cp env.example .env
+lightrag-server
+```
+
+* Launching the LightRAG Server with Docker Compose
+
+```
+git clone https://github.com/HKUDS/LightRAG.git
+cd LightRAG
+cp env.example .env
+# modify LLM and Embedding settings in .env
+docker compose up
+```
+
+> Historical versions of LightRAG docker images can be found here: [LightRAG Docker Images]( https://github.com/HKUDS/LightRAG/pkgs/container/lightrag)
+
+### Install  LightRAG Core
+
+* Install from source (Recommend)
+
+```bash
+cd LightRAG
+pip install -e .
+```
+
+* Install from PyPI
+
+```bash
+pip install lightrag-hku
+```
+
+## Quick Start
+
+### LLM and Technology Stack Requirements for LightRAG
+
+LightRAG's demands on the capabilities of Large Language Models (LLMs) are significantly higher than those of traditional RAG, as it requires the LLM to perform entity-relationship extraction tasks from documents. Configuring appropriate Embedding and Reranker models is also crucial for improving query performance.
+
+- **LLM Selection**:
+  - It is recommended to use an LLM with at least 32 billion parameters.
+  - The context length should be at least 32KB, with 64KB being recommended.
+  - It is not recommended to choose reasoning models during the document indexing stage.
+  - During the query stage, it is recommended to choose models with stronger capabilities than those used in the indexing stage to achieve better query results.
+- **Embedding Model**:
+  - A high-performance Embedding model is essential for RAG.
+  - We recommend using mainstream multilingual Embedding models, such as: `BAAI/bge-m3` and `text-embedding-3-large`.
+  - **Important Note**: The Embedding model must be determined before document indexing, and the same model must be used during the document query phase. For certain storage solutions (e.g., PostgreSQL), the vector dimension must be defined upon initial table creation. Therefore, when changing embedding models, it is necessary to delete the existing vector-related tables and allow LightRAG to recreate them with the new dimensions.
+- **Reranker Model Configuration**:
+  - Configuring a Reranker model can significantly enhance LightRAG's retrieval performance.
+  - When a Reranker model is enabled, it is recommended to set the "mix mode" as the default query mode.
+  - We recommend using mainstream Reranker models, such as: `BAAI/bge-reranker-v2-m3` or models provided by services like Jina.
+
+### Quick Start for LightRAG Server
+
+* For more information about LightRAG Server, please refer to [LightRAG Server](./lightrag/api/README.md).
+
+### Quick Start for LightRAG core
+
+To get started with LightRAG core, refer to the sample codes available in the `examples` folder. Additionally, a [video demo](https://www.youtube.com/watch?v=g21royNJ4fw) demonstration is provided to guide you through the local setup process. If you already possess an OpenAI API key, you can run the demo right away:
+
+```bash
+### you should run the demo code with project folder
+cd LightRAG
+### provide your API-KEY for OpenAI
+export OPENAI_API_KEY="sk-...your_opeai_key..."
+### download the demo document of "A Christmas Carol" by Charles Dickens
+curl https://raw.githubusercontent.com/gusye1234/nano-graphrag/main/tests/mock_data.txt > ./book.txt
+### run the demo code
+python examples/lightrag_openai_demo.py
+```
+
+For a streaming response implementation example, please see `examples/lightrag_openai_compatible_demo.py`. Prior to execution, ensure you modify the sample code's LLM and embedding configurations accordingly.
+
+**Note 1**: When running the demo program, please be aware that different test scripts may use different embedding models. If you switch to a different embedding model, you must clear the data directory (`./dickens`); otherwise, the program may encounter errors. If you wish to retain the LLM cache, you can preserve the `kv_store_llm_response_cache.json` file while clearing the data directory.
+
+**Note 2**: Only `lightrag_openai_demo.py` and `lightrag_openai_compatible_demo.py` are officially supported sample codes. Other sample files are community contributions that haven't undergone full testing and optimization.
+
+## Programing with LightRAG Core
+
+> ⚠️ **If you would like to integrate LightRAG into your project, we recommend utilizing the REST API provided by the LightRAG Server**. LightRAG Core is typically intended for embedded applications or for researchers who wish to conduct studies and evaluations.
+
+### ⚠️ Important: Initialization Requirements
+
+**LightRAG requires explicit initialization before use.** You must call both `await rag.initialize_storages()` and `await initialize_pipeline_status()` after creating a LightRAG instance, otherwise you will encounter errors like:
+
+- `AttributeError: __aenter__` - if storages are not initialized
+- `KeyError: 'history_messages'` - if pipeline status is not initialized
+
+### A Simple Program
+
+Use the below Python snippet to initialize LightRAG, insert text to it, and perform queries:
+
+```python
+import os
+import asyncio
+from lightrag import LightRAG, QueryParam
+from lightrag.llm.openai import gpt_4o_mini_complete, gpt_4o_complete, openai_embed
+from lightrag.kg.shared_storage import initialize_pipeline_status
+from lightrag.utils import setup_logger
+
+setup_logger("lightrag", level="INFO")
+
+WORKING_DIR = "./rag_storage"
+if not os.path.exists(WORKING_DIR):
+    os.mkdir(WORKING_DIR)
+
+async def initialize_rag():
+    rag = LightRAG(
+        working_dir=WORKING_DIR,
+        embedding_func=openai_embed,
+        llm_model_func=gpt_4o_mini_complete,
+    )
+    # IMPORTANT: Both initialization calls are required!
+    await rag.initialize_storages()  # Initialize storage backends
+    await initialize_pipeline_status()  # Initialize processing pipeline
+    return rag
+
+async def main():
+    try:
+        # Initialize RAG instance
+        rag = await initialize_rag()
+        await rag.ainsert("Your text")
+
+        # Perform hybrid search
+        mode = "hybrid"
+        print(
+          await rag.aquery(
+              "What are the top themes in this story?",
+              param=QueryParam(mode=mode)
+          )
+        )
+
+    except Exception as e:
+        print(f"An error occurred: {e}")
+    finally:
+        if rag:
+            await rag.finalize_storages()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+Important notes for the above snippet:
+
+- Export your OPENAI_API_KEY environment variable before running the script.
+- This program uses the default storage settings for LightRAG, so all data will be persisted to WORKING_DIR/rag_storage.
+- This program demonstrates only the simplest way to initialize a LightRAG object: Injecting the embedding and LLM functions, and initializing storage and pipeline status after creating the LightRAG object.
+
+### LightRAG init parameters
+
+A full list of LightRAG init parameters:
+
+<details>
+<summary> Parameters </summary>
+
+| **Parameter** | **Type** | **Explanation** | **Default** |
+|--------------|----------|-----------------|-------------|
+| **working_dir** | `str` | Directory where the cache will be stored | `lightrag_cache+timestamp` |
+| **workspace** | str | Workspace name for data isolation between different LightRAG Instances |  |
+| **kv_storage** | `str` | Storage type for documents and text chunks. Supported types: `JsonKVStorage`,`PGKVStorage`,`RedisKVStorage`,`MongoKVStorage` | `JsonKVStorage` |
+| **vector_storage** | `str` | Storage type for embedding vectors. Supported types: `NanoVectorDBStorage`,`PGVectorStorage`,`MilvusVectorDBStorage`,`ChromaVectorDBStorage`,`FaissVectorDBStorage`,`MongoVectorDBStorage`,`QdrantVectorDBStorage` | `NanoVectorDBStorage` |
+| **graph_storage** | `str` | Storage type for graph edges and nodes. Supported types: `NetworkXStorage`,`Neo4JStorage`,`PGGraphStorage`,`AGEStorage` | `NetworkXStorage` |
+| **doc_status_storage** | `str` | Storage type for documents process status. Supported types: `JsonDocStatusStorage`,`PGDocStatusStorage`,`MongoDocStatusStorage` | `JsonDocStatusStorage` |
+| **chunk_token_size** | `int` | Maximum token size per chunk when splitting documents | `1200` |
+| **chunk_overlap_token_size** | `int` | Overlap token size between two chunks when splitting documents | `100` |
+| **tokenizer** | `Tokenizer` | The function used to convert text into tokens (numbers) and back using .encode() and .decode() functions following `TokenizerInterface` protocol. If you don't specify one, it will use the default Tiktoken tokenizer. | `TiktokenTokenizer` |
+| **tiktoken_model_name** | `str` | If you're using the default Tiktoken tokenizer, this is the name of the specific Tiktoken model to use. This setting is ignored if you provide your own tokenizer. | `gpt-4o-mini` |
+| **entity_extract_max_gleaning** | `int` | Number of loops in the entity extraction process, appending history messages | `1` |
+| **node_embedding_algorithm** | `str` | Algorithm for node embedding (currently not used) | `node2vec` |
+| **node2vec_params** | `dict` | Parameters for node embedding | `{"dimensions": 1536,"num_walks": 10,"walk_length": 40,"window_size": 2,"iterations": 3,"random_seed": 3,}` |
+| **embedding_func** | `EmbeddingFunc` | Function to generate embedding vectors from text | `openai_embed` |
+| **embedding_batch_num** | `int` | Maximum batch size for embedding processes (multiple texts sent per batch) | `32` |
+| **embedding_func_max_async** | `int` | Maximum number of concurrent asynchronous embedding processes | `16` |
+| **llm_model_func** | `callable` | Function for LLM generation | `gpt_4o_mini_complete` |
+| **llm_model_name** | `str` | LLM model name for generation | `meta-llama/Llama-3.2-1B-Instruct` |
+| **summary_context_size** | `int` | Maximum tokens send to LLM to generate summaries for entity relation merging | `10000`（configured by env var SUMMARY_CONTEXT_SIZE) |
+| **summary_max_tokens** | `int` | Maximum token size for entity/relation description | `500`（configured by env var SUMMARY_MAX_TOKENS) |
+| **llm_model_max_async** | `int` | Maximum number of concurrent asynchronous LLM processes | `4`（default value changed by env var MAX_ASYNC) |
+| **llm_model_kwargs** | `dict` | Additional parameters for LLM generation | |
+| **vector_db_storage_cls_kwargs** | `dict` | Additional parameters for vector database, like setting the threshold for nodes and relations retrieval | cosine_better_than_threshold: 0.2（default value changed by env var COSINE_THRESHOLD) |
+| **enable_llm_cache** | `bool` | If `TRUE`, stores LLM results in cache; repeated prompts return cached responses | `TRUE` |
+| **enable_llm_cache_for_entity_extract** | `bool` | If `TRUE`, stores LLM results in cache for entity extraction; Good for beginners to debug your application | `TRUE` |
+| **addon_params** | `dict` | Additional parameters, e.g., `{"language": "Simplified Chinese", "entity_types": ["organization", "person", "location", "event"]}`: sets example limit, entiy/relation extraction output language | language: English` |
+| **embedding_cache_config** | `dict` | Configuration for question-answer caching. Contains three parameters: `enabled`: Boolean value to enable/disable cache lookup functionality. When enabled, the system will check cached responses before generating new answers. `similarity_threshold`: Float value (0-1), similarity threshold. When a new question's similarity with a cached question exceeds this threshold, the cached answer will be returned directly without calling the LLM. `use_llm_check`: Boolean value to enable/disable LLM similarity verification. When enabled, LLM will be used as a secondary check to verify the similarity between questions before returning cached answers. | Default: `{"enabled": False, "similarity_threshold": 0.95, "use_llm_check": False}` |
+
+</details>
+
+### Query Param
+
+Use QueryParam to control the behavior your query:
+
+```python
+class QueryParam:
+    """Configuration parameters for query execution in LightRAG."""
+
+    mode: Literal["local", "global", "hybrid", "naive", "mix", "bypass"] = "global"
+    """Specifies the retrieval mode:
+    - "local": Focuses on context-dependent information.
+    - "global": Utilizes global knowledge.
+    - "hybrid": Combines local and global retrieval methods.
+    - "naive": Performs a basic search without advanced techniques.
+    - "mix": Integrates knowledge graph and vector retrieval.
+    """
+
+    only_need_context: bool = False
+    """If True, only returns the retrieved context without generating a response."""
+
+    only_need_prompt: bool = False
+    """If True, only returns the generated prompt without producing a response."""
+
+    response_type: str = "Multiple Paragraphs"
+    """Defines the response format. Examples: 'Multiple Paragraphs', 'Single Paragraph', 'Bullet Points'."""
+
+    stream: bool = False
+    """If True, enables streaming output for real-time responses."""
+
+    top_k: int = int(os.getenv("TOP_K", "60"))
+    """Number of top items to retrieve. Represents entities in 'local' mode and relationships in 'global' mode."""
+
+    chunk_top_k: int = int(os.getenv("CHUNK_TOP_K", "20"))
+    """Number of text chunks to retrieve initially from vector search and keep after reranking.
+    If None, defaults to top_k value.
+    """
+
+    max_entity_tokens: int = int(os.getenv("MAX_ENTITY_TOKENS", "6000"))
+    """Maximum number of tokens allocated for entity context in unified token control system."""
+
+    max_relation_tokens: int = int(os.getenv("MAX_RELATION_TOKENS", "8000"))
+    """Maximum number of tokens allocated for relationship context in unified token control system."""
+
+    max_total_tokens: int = int(os.getenv("MAX_TOTAL_TOKENS", "30000"))
+    """Maximum total tokens budget for the entire query context (entities + relations + chunks + system prompt)."""
+
+    conversation_history: list[dict[str, str]] = field(default_factory=list)
+    """Stores past conversation history to maintain context.
+    Format: [{"role": "user/assistant", "content": "message"}].
+    """
+
+    # Deprated: history message have negtive effect on query performance
+    history_turns: int = 0
+    """Number of complete conversation turns (user-assistant pairs) to consider in the response context."""
+
+    ids: list[str] | None = None
+    """List of ids to filter the results."""
+
+    model_func: Callable[..., object] | None = None
+    """Optional override for the LLM model function to use for this specific query.
+    If provided, this will be used instead of the global model function.
+    This allows using different models for different query modes.
+    """
+
+    user_prompt: str | None = None
+    """User-provided prompt for the query.
+    If proivded, this will be use instead of the default vaulue from prompt template.
+    """
+
+    enable_rerank: bool = True
+    """Enable reranking for retrieved text chunks. If True but no rerank model is configured, a warning will be issued.
+    Default is True to enable reranking when rerank model is available.
+    """
+```
+
+> default value of Top_k can be change by environment  variables  TOP_K.
+
+### LLM and Embedding Injection
+
+LightRAG requires the utilization of LLM and Embedding models to accomplish document indexing and querying tasks. During the initialization phase, it is necessary to inject the invocation methods of the relevant models into LightRAG：
+
+<details>
+<summary> <b>Using Open AI-like APIs</b> </summary>
+
+* LightRAG also supports Open AI-like chat/embeddings APIs:
+
+```python
+async def llm_model_func(
+    prompt, system_prompt=None, history_messages=[], keyword_extraction=False, **kwargs
+) -> str:
+    return await openai_complete_if_cache(
+        "solar-mini",
+        prompt,
+        system_prompt=system_prompt,
+        history_messages=history_messages,
+        api_key=os.getenv("UPSTAGE_API_KEY"),
+        base_url="https://api.upstage.ai/v1/solar",
+        **kwargs
+    )
+
+async def embedding_func(texts: list[str]) -> np.ndarray:
+    return await openai_embed(
+        texts,
+        model="solar-embedding-1-large-query",
+        api_key=os.getenv("UPSTAGE_API_KEY"),
+        base_url="https://api.upstage.ai/v1/solar"
+    )
+
+async def initialize_rag():
+    rag = LightRAG(
+        working_dir=WORKING_DIR,
+        llm_model_func=llm_model_func,
+        embedding_func=EmbeddingFunc(
+            embedding_dim=4096,
+            func=embedding_func
+        )
+    )
+
+    await rag.initialize_storages()
+    await initialize_pipeline_status()
+
+    return rag
+```
+
+</details>
+
+<details>
+<summary> <b>Using Hugging Face Models</b> </summary>
+
+* If you want to use Hugging Face models, you only need to set LightRAG as follows:
+
+See `lightrag_hf_demo.py`
+
+```python
+# Initialize LightRAG with Hugging Face model
+rag = LightRAG(
+    working_dir=WORKING_DIR,
+    llm_model_func=hf_model_complete,  # Use Hugging Face model for text generation
+    llm_model_name='meta-llama/Llama-3.1-8B-Instruct',  # Model name from Hugging Face
+    # Use Hugging Face embedding function
+    embedding_func=EmbeddingFunc(
+        embedding_dim=384,
+        func=lambda texts: hf_embed(
+            texts,
+            tokenizer=AutoTokenizer.from_pretrained("sentence-transformers/all-MiniLM-L6-v2"),
+            embed_model=AutoModel.from_pretrained("sentence-transformers/all-MiniLM-L6-v2")
+        )
+    ),
+)
+```
+
+</details>
+
+<details>
+<summary> <b>Using Ollama Models</b> </summary>
+**Overview**
+
+If you want to use Ollama models, you need to pull model you plan to use and embedding model, for example `nomic-embed-text`.
+
+Then you only need to set LightRAG as follows:
+
+```python
+# Initialize LightRAG with Ollama model
+rag = LightRAG(
+    working_dir=WORKING_DIR,
+    llm_model_func=ollama_model_complete,  # Use Ollama model for text generation
+    llm_model_name='your_model_name', # Your model name
+    # Use Ollama embedding function
+    embedding_func=EmbeddingFunc(
+        embedding_dim=768,
+        func=lambda texts: ollama_embed(
+            texts,
+            embed_model="nomic-embed-text"
+        )
+    ),
+)
+```
+
+* **Increasing context size**
+
+In order for LightRAG to work context should be at least 32k tokens. By default Ollama models have context size of 8k. You can achieve this using one of two ways:
+
+* **Increasing the `num_ctx` parameter in Modelfile**
+
+1. Pull the model:
+
+```bash
+ollama pull qwen2
+```
+
+2. Display the model file:
+
+```bash
+ollama show --modelfile qwen2 > Modelfile
+```
+
+3. Edit the Modelfile by adding the following line:
+
+```bash
+PARAMETER num_ctx 32768
+```
+
+4. Create the modified model:
+
+```bash
+ollama create -f Modelfile qwen2m
+```
+
+* **Setup `num_ctx` via Ollama API**
+
+Tiy can use `llm_model_kwargs` param to configure ollama:
+
+```python
+rag = LightRAG(
+    working_dir=WORKING_DIR,
+    llm_model_func=ollama_model_complete,  # Use Ollama model for text generation
+    llm_model_name='your_model_name', # Your model name
+    llm_model_kwargs={"options": {"num_ctx": 32768}},
+    # Use Ollama embedding function
+    embedding_func=EmbeddingFunc(
+        embedding_dim=768,
+        func=lambda texts: ollama_embed(
+            texts,
+            embed_model="nomic-embed-text"
+        )
+    ),
+)
+```
+
+* **Low RAM GPUs**
+
+In order to run this experiment on low RAM GPU you should select small model and tune context window (increasing context increase memory consumption). For example, running this ollama example on repurposed mining GPU with 6Gb of RAM required to set context size to 26k while using `gemma2:2b`. It was able to find 197 entities and 19 relations on `book.txt`.
+
+</details>
+<details>
+<summary> <b>LlamaIndex</b> </summary>
+
+LightRAG supports integration with LlamaIndex (`llm/llama_index_impl.py`):
+
+- Integrates with OpenAI and other providers through LlamaIndex
+- See [LlamaIndex Documentation](lightrag/llm/Readme.md) for detailed setup and examples
+
+**Example Usage**
+
+```python
+# Using LlamaIndex with direct OpenAI access
+import asyncio
+from lightrag import LightRAG
+from lightrag.llm.llama_index_impl import llama_index_complete_if_cache, llama_index_embed
+from llama_index.embeddings.openai import OpenAIEmbedding
+from llama_index.llms.openai import OpenAI
+from lightrag.kg.shared_storage import initialize_pipeline_status
+from lightrag.utils import setup_logger
+
+# Setup log handler for LightRAG
+setup_logger("lightrag", level="INFO")
+
+async def initialize_rag():
+    rag = LightRAG(
+        working_dir="your/path",
+        llm_model_func=llama_index_complete_if_cache,  # LlamaIndex-compatible completion function
+        embedding_func=EmbeddingFunc(    # LlamaIndex-compatible embedding function
+            embedding_dim=1536,
+            func=lambda texts: llama_index_embed(texts, embed_model=embed_model)
+        ),
+    )
+
+    await rag.initialize_storages()
+    await initialize_pipeline_status()
+
+    return rag
+
+def main():
+    # Initialize RAG instance
+    rag = asyncio.run(initialize_rag())
+
+    with open("./book.txt", "r", encoding="utf-8") as f:
+        rag.insert(f.read())
+
+    # Perform naive search
+    print(
+        rag.query("What are the top themes in this story?", param=QueryParam(mode="naive"))
+    )
+
+    # Perform local search
+    print(
+        rag.query("What are the top themes in this story?", param=QueryParam(mode="local"))
+    )
+
+    # Perform global search
+    print(
+        rag.query("What are the top themes in this story?", param=QueryParam(mode="global"))
+    )
+
+    # Perform hybrid search
+    print(
+        rag.query("What are the top themes in this story?", param=QueryParam(mode="hybrid"))
+    )
+
+if __name__ == "__main__":
+    main()
+```
+
+**For detailed documentation and examples, see:**
+
+- [LlamaIndex Documentation](lightrag/llm/Readme.md)
+- [Direct OpenAI Example](examples/lightrag_llamaindex_direct_demo.py)
+- [LiteLLM Proxy Example](examples/lightrag_llamaindex_litellm_demo.py)
+
+</details>
+
+### Rerank Function Injection
+
+To enhance retrieval quality, documents can be re-ranked based on a more effective relevance scoring model. The `rerank.py` file provides three Reranker provider driver functions:
+
+* **Cohere / vLLM**: `cohere_rerank`
+* **Jina AI**: `jina_rerank`
+* **Aliyun**: `ali_rerank`
+
+You can inject one of these functions into the `rerank_model_func` attribute of the LightRAG object. This will enable LightRAG's query function to re-order retrieved text blocks using the injected function. For detailed usage, please refer to the `examples/rerank_example.py` file.
+
+### User Prompt vs. Query
+
+When using LightRAG for content queries, avoid combining the search process with unrelated output processing, as this significantly impacts query effectiveness. The `user_prompt` parameter in Query Param is specifically designed to address this issue — it does not participate in the RAG retrieval phase, but rather guides the LLM on how to process the retrieved results after the query is completed. Here's how to use it:
+
+```python
+# Create query parameters
+query_param = QueryParam(
+    mode = "hybrid",  # Other modes：local, global, hybrid, mix, naive
+    user_prompt = "For diagrams, use mermaid format with English/Pinyin node names and Chinese display labels",
+)
+
+# Query and process
+response_default = rag.query(
+    "Please draw a character relationship diagram for Scrooge",
+    param=query_param
+)
+print(response_default)
+```
+
+### Insert
+
+<details>
+  <summary> <b> Basic Insert </b></summary>
+
+```python
+# Basic Insert
+rag.insert("Text")
+```
+
+</details>
+
+<details>
+  <summary> <b> Batch Insert </b></summary>
+
+```python
+# Basic Batch Insert: Insert multiple texts at once
+rag.insert(["TEXT1", "TEXT2",...])
+
+# Batch Insert with custom batch size configuration
+rag = LightRAG(
+    ...
+    working_dir=WORKING_DIR,
+    max_parallel_insert = 4
+)
+
+rag.insert(["TEXT1", "TEXT2", "TEXT3", ...])  # Documents will be processed in batches of 4
+```
+
+The `max_parallel_insert` parameter determines the number of documents processed concurrently in the document indexing pipeline. If unspecified, the default value is **2**. We recommend keeping this setting **below 10**, as the performance bottleneck typically lies with the LLM (Large Language Model) processing.The `max_parallel_insert` parameter determines the number of documents processed concurrently in the document indexing pipeline. If unspecified, the default value is **2**. We recommend keeping this setting **below 10**, as the performance bottleneck typically lies with the LLM (Large Language Model) processing.
+
+</details>
+
+<details>
+  <summary> <b> Insert with ID </b></summary>
+
+If you want to provide your own IDs for your documents, number of documents and number of IDs must be the same.
+
+```python
+# Insert single text, and provide ID for it
+rag.insert("TEXT1", ids=["ID_FOR_TEXT1"])
+
+# Insert multiple texts, and provide IDs for them
+rag.insert(["TEXT1", "TEXT2",...], ids=["ID_FOR_TEXT1", "ID_FOR_TEXT2"])
+```
+
+</details>
+
+<details>
+  <summary><b>Insert using Pipeline</b></summary>
+
+The `apipeline_enqueue_documents` and `apipeline_process_enqueue_documents` functions allow you to perform incremental insertion of documents into the graph.
+
+This is useful for scenarios where you want to process documents in the background while still allowing the main thread to continue executing.
+
+And using a routine to process new documents.
+
+```python
+rag = LightRAG(..)
+
+await rag.apipeline_enqueue_documents(input)
+# Your routine in loop
+await rag.apipeline_process_enqueue_documents(input)
+```
+
+</details>
+
+<details>
+  <summary><b>Insert Multi-file Type Support</b></summary>
+
+The `textract` supports reading file types such as TXT, DOCX, PPTX, CSV, and PDF.
+
+```python
+import textract
+
+file_path = 'TEXT.pdf'
+text_content = textract.process(file_path)
+
+rag.insert(text_content.decode('utf-8'))
+```
+
+</details>
+
+<details>
+  <summary><b>Citation Functionality</b></summary>
+
+By providing file paths, the system ensures that sources can be traced back to their original documents.
+
+```python
+# Define documents and their file paths
+documents = ["Document content 1", "Document content 2"]
+file_paths = ["path/to/doc1.txt", "path/to/doc2.txt"]
+
+# Insert documents with file paths
+rag.insert(documents, file_paths=file_paths)
+```
+
+</details>
+
+### Storage
+
+LightRAG uses 4 types of storage for different purposes:
+
+* KV_STORAGE: llm response cache, text chunks, document information
+* VECTOR_STORAGE: entities vectors, relation vectors, chunks vectors
+* GRAPH_STORAGE: entity relation graph
+* DOC_STATUS_STORAGE: document indexing status
+
+Each storage type has several implementations:
+
+* KV_STORAGE supported implementations:
+
+```
+JsonKVStorage    JsonFile (default)
+PGKVStorage      Postgres
+RedisKVStorage   Redis
+MongoKVStorage   MongoDB
+```
+
+* GRAPH_STORAGE supported implementations:
+
+```
+NetworkXStorage      NetworkX (default)
+Neo4JStorage         Neo4J
+PGGraphStorage       PostgreSQL with AGE plugin
+MemgraphStorage.     Memgraph
+```
+
+> Testing has shown that Neo4J delivers superior performance in production environments compared to PostgreSQL with AGE plugin.
+
+* VECTOR_STORAGE supported implementations:
+
+```
+NanoVectorDBStorage         NanoVector (default)
+PGVectorStorage             Postgres
+MilvusVectorDBStorage       Milvus
+FaissVectorDBStorage        Faiss
+QdrantVectorDBStorage       Qdrant
+MongoVectorDBStorage        MongoDB
+```
+
+* DOC_STATUS_STORAGE: supported implementations:
+
+```
+JsonDocStatusStorage        JsonFile (default)
+PGDocStatusStorage          Postgres
+MongoDocStatusStorage       MongoDB
+```
+
+Example connection configurations for each storage type can be found in the `env.example` file. The database instance in the connection string needs to be created by you on the database server beforehand. LightRAG is only responsible for creating tables within the database instance, not for creating the database instance itself. If using Redis as storage, remember to configure automatic data persistence rules for Redis, otherwise data will be lost after the Redis service restarts. If using PostgreSQL, it is recommended to use version 16.6 or above.
+
+<details>
+<summary> <b>Using Neo4J Storage</b> </summary>
+
+* For production level scenarios you will most likely want to leverage an enterprise solution
+* for KG storage. Running Neo4J in Docker is recommended for seamless local testing.
+* See: https://hub.docker.com/_/neo4j
+
+```python
+export NEO4J_URI="neo4j://localhost:7687"
+export NEO4J_USERNAME="neo4j"
+export NEO4J_PASSWORD="password"
+
+# Setup logger for LightRAG
+setup_logger("lightrag", level="INFO")
+
+# When you launch the project be sure to override the default KG: NetworkX
+# by specifying kg="Neo4JStorage".
+
+# Note: Default settings use NetworkX
+# Initialize LightRAG with Neo4J implementation.
+async def initialize_rag():
+    rag = LightRAG(
+        working_dir=WORKING_DIR,
+        llm_model_func=gpt_4o_mini_complete,  # Use gpt_4o_mini_complete LLM model
+        graph_storage="Neo4JStorage", #<-----------override KG default
+    )
+
+    # Initialize database connections
+    await rag.initialize_storages()
+    # Initialize pipeline status for document processing
+    await initialize_pipeline_status()
+
+    return rag
+```
+
+see test_neo4j.py for a working example.
+
+</details>
+
+<details>
+<summary> <b>Using PostgreSQL Storage</b> </summary>
+
+For production level scenarios you will most likely want to leverage an enterprise solution. PostgreSQL can provide a one-stop solution for you as KV store, VectorDB (pgvector) and GraphDB (apache AGE). PostgreSQL version 16.6 or higher is supported.
+
+* PostgreSQL is lightweight,the whole binary distribution including all necessary plugins can be zipped to 40MB: Ref to [Windows Release](https://github.com/ShanGor/apache-age-windows/releases/tag/PG17%2Fv1.5.0-rc0) as it is easy to install for Linux/Mac.
+* If you prefer docker, please start with this image if you are a beginner to avoid hiccups (DO read the overview): https://hub.docker.com/r/shangor/postgres-for-rag
+* How to start? Ref to: [examples/lightrag_zhipu_postgres_demo.py](https://github.com/HKUDS/LightRAG/blob/main/examples/lightrag_zhipu_postgres_demo.py)
+* For high-performance graph database requirements, Neo4j is recommended as Apache AGE's performance is not as competitive.
+
+</details>
+
+<details>
+<summary> <b>Using Faiss Storage</b> </summary>
+Before using Faiss vector database, you must manually install `faiss-cpu` or `faiss-gpu`.
+
+- Install the required dependencies:
+
+```
+pip install faiss-cpu
+```
+
+You can also install `faiss-gpu` if you have GPU support.
+
+- Here we are using `sentence-transformers` but you can also use `OpenAIEmbedding` model with `3072` dimensions.
+
+```python
+async def embedding_func(texts: list[str]) -> np.ndarray:
+    model = SentenceTransformer('all-MiniLM-L6-v2')
+    embeddings = model.encode(texts, convert_to_numpy=True)
+    return embeddings
+
+# Initialize LightRAG with the LLM model function and embedding function
+rag = LightRAG(
+    working_dir=WORKING_DIR,
+    llm_model_func=llm_model_func,
+    embedding_func=EmbeddingFunc(
+        embedding_dim=384,
+        func=embedding_func,
+    ),
+    vector_storage="FaissVectorDBStorage",
+    vector_db_storage_cls_kwargs={
+        "cosine_better_than_threshold": 0.3  # Your desired threshold
+    }
+)
+```
+
+</details>
+
+<details>
+<summary> <b>Using Memgraph for Storage</b> </summary>
+
+* Memgraph is a high-performance, in-memory graph database compatible with the Neo4j Bolt protocol.
+* You can run Memgraph locally using Docker for easy testing:
+* See: https://memgraph.com/download
+
+```python
+export MEMGRAPH_URI="bolt://localhost:7687"
+
+# Setup logger for LightRAG
+setup_logger("lightrag", level="INFO")
+
+# When you launch the project, override the default KG: NetworkX
+# by specifying kg="MemgraphStorage".
+
+# Note: Default settings use NetworkX
+# Initialize LightRAG with Memgraph implementation.
+async def initialize_rag():
+    rag = LightRAG(
+        working_dir=WORKING_DIR,
+        llm_model_func=gpt_4o_mini_complete,  # Use gpt_4o_mini_complete LLM model
+        graph_storage="MemgraphStorage", #<-----------override KG default
+    )
+
+    # Initialize database connections
+    await rag.initialize_storages()
+    # Initialize pipeline status for document processing
+    await initialize_pipeline_status()
+
+    return rag
+```
+
+</details>
+
+<details>
+<summary> <b>Using MongoDB Storage</b> </summary>
+
+MongoDB provides a one-stop storage solution for LightRAG. MongoDB offers native KV storage and vector storage. LightRAG uses MongoDB collections to implement a simple graph storage. MongoDB's official vector search functionality (`$vectorSearch`) currently requires their official cloud service MongoDB Atlas. This functionality cannot be used on self-hosted MongoDB Community/Enterprise versions.
+
+</details>
+
+<details>
+<summary> <b>Using Redis Storage</b> </summary>
+
+LightRAG supports using Redis as KV storage. When using Redis storage, attention should be paid to persistence configuration and memory usage configuration. The following is the recommended Redis configuration:
+
+```
+save 900 1
+save 300 10
+save 60 1000
+stop-writes-on-bgsave-error yes
+maxmemory 4gb
+maxmemory-policy noeviction
+maxclients 500
+```
+
+</details>
+
+### Data Isolation Between LightRAG Instances
+
+The `workspace` parameter ensures data isolation between different LightRAG instances. Once initialized, the `workspace` is immutable and cannot be changed.Here is how workspaces are implemented for different types of storage:
+
+- **For local file-based databases, data isolation is achieved through workspace subdirectories:** `JsonKVStorage`, `JsonDocStatusStorage`, `NetworkXStorage`, `NanoVectorDBStorage`, `FaissVectorDBStorage`.
+- **For databases that store data in collections, it's done by adding a workspace prefix to the collection name:** `RedisKVStorage`, `RedisDocStatusStorage`, `MilvusVectorDBStorage`, `QdrantVectorDBStorage`, `MongoKVStorage`, `MongoDocStatusStorage`, `MongoVectorDBStorage`, `MongoGraphStorage`, `PGGraphStorage`.
+- **For relational databases, data isolation is achieved by adding a `workspace` field to the tables for logical data separation:** `PGKVStorage`, `PGVectorStorage`, `PGDocStatusStorage`.
+- **For the Neo4j graph database, logical data isolation is achieved through labels:** `Neo4JStorage`
+
+To maintain compatibility with legacy data, the default workspace for PostgreSQL non-graph storage is `default` and, for PostgreSQL AGE graph storage is null, for Neo4j graph storage is `base` when no workspace is configured. For all external storages, the system provides dedicated workspace environment variables to override the common `WORKSPACE` environment variable configuration. These storage-specific workspace environment variables are: `REDIS_WORKSPACE`, `MILVUS_WORKSPACE`, `QDRANT_WORKSPACE`, `MONGODB_WORKSPACE`, `POSTGRES_WORKSPACE`, `NEO4J_WORKSPACE`.
+
+## Edit Entities and Relations
+
+LightRAG now supports comprehensive knowledge graph management capabilities, allowing you to create, edit, and delete entities and relationships within your knowledge graph.
+
+<details>
+  <summary> <b> Create Entities and Relations </b></summary>
+
+```python
+# Create new entity
+entity = rag.create_entity("Google", {
+    "description": "Google is a multinational technology company specializing in internet-related services and products.",
+    "entity_type": "company"
+})
+
+# Create another entity
+product = rag.create_entity("Gmail", {
+    "description": "Gmail is an email service developed by Google.",
+    "entity_type": "product"
+})
+
+# Create relation between entities
+relation = rag.create_relation("Google", "Gmail", {
+    "description": "Google develops and operates Gmail.",
+    "keywords": "develops operates service",
+    "weight": 2.0
+})
+```
+
+</details>
+
+<details>
+  <summary> <b> Edit Entities and Relations </b></summary>
+
+```python
+# Edit an existing entity
+updated_entity = rag.edit_entity("Google", {
+    "description": "Google is a subsidiary of Alphabet Inc., founded in 1998.",
+    "entity_type": "tech_company"
+})
+
+# Rename an entity (with all its relationships properly migrated)
+renamed_entity = rag.edit_entity("Gmail", {
+    "entity_name": "Google Mail",
+    "description": "Google Mail (formerly Gmail) is an email service."
+})
+
+# Edit a relation between entities
+updated_relation = rag.edit_relation("Google", "Google Mail", {
+    "description": "Google created and maintains Google Mail service.",
+    "keywords": "creates maintains email service",
+    "weight": 3.0
+})
+```
+
+All operations are available in both synchronous and asynchronous versions. The asynchronous versions have the prefix "a" (e.g., `acreate_entity`, `aedit_relation`).
+
+</details>
+
+<details>
+  <summary> <b> Insert Custom KG </b></summary>
+
+```python
+custom_kg = {
+        "chunks": [
+            {
+                "content": "Alice and Bob are collaborating on quantum computing research.",
+                "source_id": "doc-1",
+                "file_path": "test_file",
+            }
+        ],
+        "entities": [
+            {
+                "entity_name": "Alice",
+                "entity_type": "person",
+                "description": "Alice is a researcher specializing in quantum physics.",
+                "source_id": "doc-1",
+                "file_path": "test_file"
+            },
+            {
+                "entity_name": "Bob",
+                "entity_type": "person",
+                "description": "Bob is a mathematician.",
+                "source_id": "doc-1",
+                "file_path": "test_file"
+            },
+            {
+                "entity_name": "Quantum Computing",
+                "entity_type": "technology",
+                "description": "Quantum computing utilizes quantum mechanical phenomena for computation.",
+                "source_id": "doc-1",
+                "file_path": "test_file"
+            }
+        ],
+        "relationships": [
+            {
+                "src_id": "Alice",
+                "tgt_id": "Bob",
+                "description": "Alice and Bob are research partners.",
+                "keywords": "collaboration research",
+                "weight": 1.0,
+                "source_id": "doc-1",
+                "file_path": "test_file"
+            },
+            {
+                "src_id": "Alice",
+                "tgt_id": "Quantum Computing",
+                "description": "Alice conducts research on quantum computing.",
+                "keywords": "research expertise",
+                "weight": 1.0,
+                "source_id": "doc-1",
+                "file_path": "test_file"
+            },
+            {
+                "src_id": "Bob",
+                "tgt_id": "Quantum Computing",
+                "description": "Bob researches quantum computing.",
+                "keywords": "research application",
+                "weight": 1.0,
+                "source_id": "doc-1",
+                "file_path": "test_file"
+            }
+        ]
+    }
+
+rag.insert_custom_kg(custom_kg)
+```
+
+</details>
+
+<details>
+  <summary> <b>Other Entity and Relation Operations</b></summary>
+
+- **create_entity**: Creates a new entity with specified attributes
+- **edit_entity**: Updates an existing entity's attributes or renames it
+
+
+- **create_relation**: Creates a new relation between existing entities
+- **edit_relation**: Updates an existing relation's attributes
+
+These operations maintain data consistency across both the graph database and vector database components, ensuring your knowledge graph remains coherent.
+
+</details>
+
+## Delete Functions
+
+LightRAG provides comprehensive deletion capabilities, allowing you to delete documents, entities, and relationships.
+
+<details>
+<summary> <b>Delete Entities</b> </summary>
+
+You can delete entities by their name along with all associated relationships:
+
+```python
+# Delete entity and all its relationships (synchronous version)
+rag.delete_by_entity("Google")
+
+# Asynchronous version
+await rag.adelete_by_entity("Google")
+```
+
+When deleting an entity:
+- Removes the entity node from the knowledge graph
+- Deletes all associated relationships
+- Removes related embedding vectors from the vector database
+- Maintains knowledge graph integrity
+
+</details>
+
+<details>
+<summary> <b>Delete Relations</b> </summary>
+
+You can delete relationships between two specific entities:
+
+```python
+# Delete relationship between two entities (synchronous version)
+rag.delete_by_relation("Google", "Gmail")
+
+# Asynchronous version
+await rag.adelete_by_relation("Google", "Gmail")
+```
+
+When deleting a relationship:
+- Removes the specified relationship edge
+- Deletes the relationship's embedding vector from the vector database
+- Preserves both entity nodes and their other relationships
+
+</details>
+
+<details>
+<summary> <b>Delete by Document ID</b> </summary>
+
+You can delete an entire document and all its related knowledge through document ID:
+
+```python
+# Delete by document ID (asynchronous version)
+await rag.adelete_by_doc_id("doc-12345")
+```
+
+Optimized processing when deleting by document ID:
+- **Smart Cleanup**: Automatically identifies and removes entities and relationships that belong only to this document
+- **Preserve Shared Knowledge**: If entities or relationships exist in other documents, they are preserved and their descriptions are rebuilt
+- **Cache Optimization**: Clears related LLM cache to reduce storage overhead
+- **Incremental Rebuilding**: Reconstructs affected entity and relationship descriptions from remaining documents
+
+The deletion process includes:
+1. Delete all text chunks related to the document
+2. Identify and delete entities and relationships that belong only to this document
+3. Rebuild entities and relationships that still exist in other documents
+4. Update all related vector indexes
+5. Clean up document status records
+
+Note: Deletion by document ID is an asynchronous operation as it involves complex knowledge graph reconstruction processes.
+
+</details>
+
+**Important Reminders:**
+
+1. **Irreversible Operations**: All deletion operations are irreversible, please use with caution
+2. **Performance Considerations**: Deleting large amounts of data may take some time, especially deletion by document ID
+3. **Data Consistency**: Deletion operations automatically maintain consistency between the knowledge graph and vector database
+4. **Backup Recommendations**: Consider backing up data before performing important deletion operations
+
+**Batch Deletion Recommendations:**
+- For batch deletion operations, consider using asynchronous methods for better performance
+- For large-scale deletions, consider processing in batches to avoid excessive system load
+
+## Entity Merging
+
+<details>
+<summary> <b>Merge Entities and Their Relationships</b> </summary>
+
+LightRAG now supports merging multiple entities into a single entity, automatically handling all relationships:
+
+```python
+# Basic entity merging
+rag.merge_entities(
+    source_entities=["Artificial Intelligence", "AI", "Machine Intelligence"],
+    target_entity="AI Technology"
+)
+```
+
+With custom merge strategy:
+
+```python
+# Define custom merge strategy for different fields
+rag.merge_entities(
+    source_entities=["John Smith", "Dr. Smith", "J. Smith"],
+    target_entity="John Smith",
+    merge_strategy={
+        "description": "concatenate",  # Combine all descriptions
+        "entity_type": "keep_first",   # Keep the entity type from the first entity
+        "source_id": "join_unique"     # Combine all unique source IDs
+    }
+)
+```
+
+With custom target entity data:
+
+```python
+# Specify exact values for the merged entity
+rag.merge_entities(
+    source_entities=["New York", "NYC", "Big Apple"],
+    target_entity="New York City",
+    target_entity_data={
+        "entity_type": "LOCATION",
+        "description": "New York City is the most populous city in the United States.",
+    }
+)
+```
+
+Advanced usage combining both approaches:
+
+```python
+# Merge company entities with both strategy and custom data
+rag.merge_entities(
+    source_entities=["Microsoft Corp", "Microsoft Corporation", "MSFT"],
+    target_entity="Microsoft",
+    merge_strategy={
+        "description": "concatenate",  # Combine all descriptions
+        "source_id": "join_unique"     # Combine source IDs
+    },
+    target_entity_data={
+        "entity_type": "ORGANIZATION",
+    }
+)
+```
+
+When merging entities:
+
+* All relationships from source entities are redirected to the target entity
+* Duplicate relationships are intelligently merged
+* Self-relationships (loops) are prevented
+* Source entities are removed after merging
+* Relationship weights and attributes are preserved
+
+</details>
+
+## Multimodal Document Processing (RAG-Anything Integration)
+
+LightRAG now seamlessly integrates with [RAG-Anything](https://github.com/HKUDS/RAG-Anything), a comprehensive **All-in-One Multimodal Document Processing RAG system** built specifically for LightRAG. RAG-Anything enables advanced parsing and retrieval-augmented generation (RAG) capabilities, allowing you to handle multimodal documents seamlessly and extract structured content—including text, images, tables, and formulas—from various document formats for integration into your RAG pipeline.
+
+**Key Features:**
+- **End-to-End Multimodal Pipeline**: Complete workflow from document ingestion and parsing to intelligent multimodal query answering
+- **Universal Document Support**: Seamless processing of PDFs, Office documents (DOC/DOCX/PPT/PPTX/XLS/XLSX), images, and diverse file formats
+- **Specialized Content Analysis**: Dedicated processors for images, tables, mathematical equations, and heterogeneous content types
+- **Multimodal Knowledge Graph**: Automatic entity extraction and cross-modal relationship discovery for enhanced understanding
+- **Hybrid Intelligent Retrieval**: Advanced search capabilities spanning textual and multimodal content with contextual understanding
+
+**Quick Start:**
+1. Install RAG-Anything:
+   ```bash
+   pip install raganything
+   ```
+2. Process multimodal documents:
+    <details>
+    <summary> <b> RAGAnything Usage Example </b></summary>
+
+    ```python
+        import asyncio
+        from raganything import RAGAnything
+        from lightrag import LightRAG
+        from lightrag.llm.openai import openai_complete_if_cache, openai_embed
+        from lightrag.utils import EmbeddingFunc
+        import os
+
+        async def load_existing_lightrag():
+            # First, create or load an existing LightRAG instance
+            lightrag_working_dir = "./existing_lightrag_storage"
+
+            # Check if previous LightRAG instance exists
+            if os.path.exists(lightrag_working_dir) and os.listdir(lightrag_working_dir):
+                print("✅ Found existing LightRAG instance, loading...")
+            else:
+                print("❌ No existing LightRAG instance found, will create new one")
+
+            # Create/Load LightRAG instance with your configurations
+            lightrag_instance = LightRAG(
+                working_dir=lightrag_working_dir,
+                llm_model_func=lambda prompt, system_prompt=None, history_messages=[], **kwargs: openai_complete_if_cache(
+                    "gpt-4o-mini",
+                    prompt,
+                    system_prompt=system_prompt,
+                    history_messages=history_messages,
+                    api_key="your-api-key",
+                    **kwargs,
+                ),
+                embedding_func=EmbeddingFunc(
+                    embedding_dim=3072,
+                    func=lambda texts: openai_embed(
+                        texts,
+                        model="text-embedding-3-large",
+                        api_key=api_key,
+                        base_url=base_url,
+                    ),
+                )
+            )
+
+            # Initialize storage (this will load existing data if available)
+            await lightrag_instance.initialize_storages()
+
+            # Now initialize RAGAnything with the existing LightRAG instance
+            rag = RAGAnything(
+                lightrag=lightrag_instance,  # Pass the existing LightRAG instance
+                # Only need vision model for multimodal processing
+                vision_model_func=lambda prompt, system_prompt=None, history_messages=[], image_data=None, **kwargs: openai_complete_if_cache(
+                    "gpt-4o",
+                    "",
+                    system_prompt=None,
+                    history_messages=[],
+                    messages=[
+                        {"role": "system", "content": system_prompt} if system_prompt else None,
+                        {"role": "user", "content": [
+                            {"type": "text", "text": prompt},
+                            {"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{image_data}"}}
+                        ]} if image_data else {"role": "user", "content": prompt}
+                    ],
+                    api_key="your-api-key",
+                    **kwargs,
+                ) if image_data else openai_complete_if_cache(
+                    "gpt-4o-mini",
+                    prompt,
+                    system_prompt=system_prompt,
+                    history_messages=history_messages,
+                    api_key="your-api-key",
+                    **kwargs,
+                )
+                # Note: working_dir, llm_model_func, embedding_func, etc. are inherited from lightrag_instance
+            )
+
+            # Query the existing knowledge base
+            result = await rag.query_with_multimodal(
+                "What data has been processed in this LightRAG instance?",
+                mode="hybrid"
+            )
+            print("Query result:", result)
+
+            # Add new multimodal documents to the existing LightRAG instance
+            await rag.process_document_complete(
+                file_path="path/to/new/multimodal_document.pdf",
+                output_dir="./output"
+            )
+
+        if __name__ == "__main__":
+            asyncio.run(load_existing_lightrag())
+    ```
+    </details>
+
+For detailed documentation and advanced usage, please refer to the [RAG-Anything repository](https://github.com/HKUDS/RAG-Anything).
+
+## Token Usage Tracking
+
+<details>
+<summary> <b>Overview and Usage</b> </summary>
+
+LightRAG provides a TokenTracker tool to monitor and manage token consumption by large language models. This feature is particularly useful for controlling API costs and optimizing performance.
+
+### Usage
+
+```python
+from lightrag.utils import TokenTracker
+
+# Create TokenTracker instance
+token_tracker = TokenTracker()
+
+# Method 1: Using context manager (Recommended)
+# Suitable for scenarios requiring automatic token usage tracking
+with token_tracker:
+    result1 = await llm_model_func("your question 1")
+    result2 = await llm_model_func("your question 2")
+
+# Method 2: Manually adding token usage records
+# Suitable for scenarios requiring more granular control over token statistics
+token_tracker.reset()
+
+rag.insert()
+
+rag.query("your question 1", param=QueryParam(mode="naive"))
+rag.query("your question 2", param=QueryParam(mode="mix"))
+
+# Display total token usage (including insert and query operations)
+print("Token usage:", token_tracker.get_usage())
+```
+
+### Usage Tips
+- Use context managers for long sessions or batch operations to automatically track all token consumption
+- For scenarios requiring segmented statistics, use manual mode and call reset() when appropriate
+- Regular checking of token usage helps detect abnormal consumption early
+- Actively use this feature during development and testing to optimize production costs
+
+### Practical Examples
+You can refer to these examples for implementing token tracking:
+- `examples/lightrag_gemini_track_token_demo.py`: Token tracking example using Google Gemini model
+- `examples/lightrag_siliconcloud_track_token_demo.py`: Token tracking example using SiliconCloud model
+
+These examples demonstrate how to effectively use the TokenTracker feature with different models and scenarios.
+
+</details>
+
+## Data Export Functions
+
+### Overview
+
+LightRAG allows you to export your knowledge graph data in various formats for analysis, sharing, and backup purposes. The system supports exporting entities, relations, and relationship data.
+
+### Export Functions
+
+<details>
+  <summary> <b> Basic Usage </b></summary>
+
+```python
+# Basic CSV export (default format)
+rag.export_data("knowledge_graph.csv")
+
+# Specify any format
+rag.export_data("output.xlsx", file_format="excel")
+```
+
+</details>
+
+<details>
+  <summary> <b> Different File Formats supported </b></summary>
+
+```python
+#Export data in CSV format
+rag.export_data("graph_data.csv", file_format="csv")
+
+# Export data in Excel sheet
+rag.export_data("graph_data.xlsx", file_format="excel")
+
+# Export data in markdown format
+rag.export_data("graph_data.md", file_format="md")
+
+# Export data in Text
+rag.export_data("graph_data.txt", file_format="txt")
+```
+</details>
+
+<details>
+  <summary> <b> Additional Options </b></summary>
+
+Include vector embeddings in the export (optional):
+
+```python
+rag.export_data("complete_data.csv", include_vector_data=True)
+```
+</details>
+
+### Data Included in Export
+
+All exports include:
+
+* Entity information (names, IDs, metadata)
+* Relation data (connections between entities)
+* Relationship information from vector database
+
+## Cache
+
+<details>
+  <summary> <b>Clear Cache</b> </summary>
+
+You can clear the LLM response cache with different modes:
+
+```python
+# Clear all cache
+await rag.aclear_cache()
+
+# Clear local mode cache
+await rag.aclear_cache(modes=["local"])
+
+# Clear extraction cache
+await rag.aclear_cache(modes=["default"])
+
+# Clear multiple modes
+await rag.aclear_cache(modes=["local", "global", "hybrid"])
+
+# Synchronous version
+rag.clear_cache(modes=["local"])
+```
+
+Valid modes are:
+
+- `"default"`: Extraction cache
+- `"naive"`: Naive search cache
+- `"local"`: Local search cache
+- `"global"`: Global search cache
+- `"hybrid"`: Hybrid search cache
+- `"mix"`: Mix search cache
+
+</details>
+
+## Troubleshooting
+
+### Common Initialization Errors
+
+If you encounter these errors when using LightRAG:
+
+1. **`AttributeError: __aenter__`**
+   - **Cause**: Storage backends not initialized
+   - **Solution**: Call `await rag.initialize_storages()` after creating the LightRAG instance
+
+2. **`KeyError: 'history_messages'`**
+   - **Cause**: Pipeline status not initialized
+   - **Solution**: Call `await initialize_pipeline_status()` after initializing storages
+
+3. **Both errors in sequence**
+   - **Cause**: Neither initialization method was called
+   - **Solution**: Always follow this pattern:
+   ```python
+   rag = LightRAG(...)
+   await rag.initialize_storages()
+   await initialize_pipeline_status()
+   ```
+
+### Model Switching Issues
+
+When switching between different embedding models, you must clear the data directory to avoid errors. The only file you may want to preserve is `kv_store_llm_response_cache.json` if you wish to retain the LLM cache.
+
+## LightRAG API
+
+The LightRAG Server is designed to provide Web UI and API support.  **For more information about LightRAG Server, please refer to [LightRAG Server](./lightrag/api/README.md).**
+
+## Graph Visualization
+
+The LightRAG Server offers a comprehensive knowledge graph visualization feature. It supports various gravity layouts, node queries, subgraph filtering, and more. **For more information about LightRAG Server, please refer to [LightRAG Server](./lightrag/api/README.md).**
+
+![iShot_2025-03-23_12.40.08](./README.assets/iShot_2025-03-23_12.40.08.png)
+
+## Evaluation
+
+### Dataset
+
+The dataset used in LightRAG can be downloaded from [TommyChien/UltraDomain](https://huggingface.co/datasets/TommyChien/UltraDomain).
+
+### Generate Query
+
+LightRAG uses the following prompt to generate high-level queries, with the corresponding code in `example/generate_query.py`.
+
+<details>
+<summary> Prompt </summary>
+
+```python
+Given the following description of a dataset:
+
+{description}
+
+Please identify 5 potential users who would engage with this dataset. For each user, list 5 tasks they would perform with this dataset. Then, for each (user, task) combination, generate 5 questions that require a high-level understanding of the entire dataset.
+
+Output the results in the following structure:
+- User 1: [user description]
+    - Task 1: [task description]
+        - Question 1:
+        - Question 2:
+        - Question 3:
+        - Question 4:
+        - Question 5:
+    - Task 2: [task description]
+        ...
+    - Task 5: [task description]
+- User 2: [user description]
+    ...
+- User 5: [user description]
+    ...
+```
+
+</details>
+
+### Batch Eval
+
+To evaluate the performance of two RAG systems on high-level queries, LightRAG uses the following prompt, with the specific code available in `reproduce/batch_eval.py`.
+
+<details>
+<summary> Prompt </summary>
+
+```python
+---Role---
+You are an expert tasked with evaluating two answers to the same question based on three criteria: **Comprehensiveness**, **Diversity**, and **Empowerment**.
+---Goal---
+You will evaluate two answers to the same question based on three criteria: **Comprehensiveness**, **Diversity**, and **Empowerment**.
+
+- **Comprehensiveness**: How much detail does the answer provide to cover all aspects and details of the question?
+- **Diversity**: How varied and rich is the answer in providing different perspectives and insights on the question?
+- **Empowerment**: How well does the answer help the reader understand and make informed judgments about the topic?
+
+For each criterion, choose the better answer (either Answer 1 or Answer 2) and explain why. Then, select an overall winner based on these three categories.
+
+Here is the question:
+{query}
+
+Here are the two answers:
+
+**Answer 1:**
+{answer1}
+
+**Answer 2:**
+{answer2}
+
+Evaluate both answers using the three criteria listed above and provide detailed explanations for each criterion.
+
+Output your evaluation in the following JSON format:
+
+{{
+    "Comprehensiveness": {{
+        "Winner": "[Answer 1 or Answer 2]",
+        "Explanation": "[Provide explanation here]"
+    }},
+    "Empowerment": {{
+        "Winner": "[Answer 1 or Answer 2]",
+        "Explanation": "[Provide explanation here]"
+    }},
+    "Overall Winner": {{
+        "Winner": "[Answer 1 or Answer 2]",
+        "Explanation": "[Summarize why this answer is the overall winner based on the three criteria]"
+    }}
+}}
+```
+
+</details>
+
+### Overall Performance Table
+
+|                      |**Agriculture**|            |**CS**|            |**Legal**|            |**Mix**|            |
+|----------------------|---------------|------------|------|------------|---------|------------|-------|------------|
+|                      |NaiveRAG|**LightRAG**|NaiveRAG|**LightRAG**|NaiveRAG|**LightRAG**|NaiveRAG|**LightRAG**|
+|**Comprehensiveness**|32.4%|**67.6%**|38.4%|**61.6%**|16.4%|**83.6%**|38.8%|**61.2%**|
+|**Diversity**|23.6%|**76.4%**|38.0%|**62.0%**|13.6%|**86.4%**|32.4%|**67.6%**|
+|**Empowerment**|32.4%|**67.6%**|38.8%|**61.2%**|16.4%|**83.6%**|42.8%|**57.2%**|
+|**Overall**|32.4%|**67.6%**|38.8%|**61.2%**|15.2%|**84.8%**|40.0%|**60.0%**|
+|                      |RQ-RAG|**LightRAG**|RQ-RAG|**LightRAG**|RQ-RAG|**LightRAG**|RQ-RAG|**LightRAG**|
+|**Comprehensiveness**|31.6%|**68.4%**|38.8%|**61.2%**|15.2%|**84.8%**|39.2%|**60.8%**|
+|**Diversity**|29.2%|**70.8%**|39.2%|**60.8%**|11.6%|**88.4%**|30.8%|**69.2%**|
+|**Empowerment**|31.6%|**68.4%**|36.4%|**63.6%**|15.2%|**84.8%**|42.4%|**57.6%**|
+|**Overall**|32.4%|**67.6%**|38.0%|**62.0%**|14.4%|**85.6%**|40.0%|**60.0%**|
+|                      |HyDE|**LightRAG**|HyDE|**LightRAG**|HyDE|**LightRAG**|HyDE|**LightRAG**|
+|**Comprehensiveness**|26.0%|**74.0%**|41.6%|**58.4%**|26.8%|**73.2%**|40.4%|**59.6%**|
+|**Diversity**|24.0%|**76.0%**|38.8%|**61.2%**|20.0%|**80.0%**|32.4%|**67.6%**|
+|**Empowerment**|25.2%|**74.8%**|40.8%|**59.2%**|26.0%|**74.0%**|46.0%|**54.0%**|
+|**Overall**|24.8%|**75.2%**|41.6%|**58.4%**|26.4%|**73.6%**|42.4%|**57.6%**|
+|                      |GraphRAG|**LightRAG**|GraphRAG|**LightRAG**|GraphRAG|**LightRAG**|GraphRAG|**LightRAG**|
+|**Comprehensiveness**|45.6%|**54.4%**|48.4%|**51.6%**|48.4%|**51.6%**|**50.4%**|49.6%|
+|**Diversity**|22.8%|**77.2%**|40.8%|**59.2%**|26.4%|**73.6%**|36.0%|**64.0%**|
+|**Empowerment**|41.2%|**58.8%**|45.2%|**54.8%**|43.6%|**56.4%**|**50.8%**|49.2%|
+|**Overall**|45.2%|**54.8%**|48.0%|**52.0%**|47.2%|**52.8%**|**50.4%**|49.6%|
+
+## Reproduce
+
+All the code can be found in the `./reproduce` directory.
+
+### Step-0 Extract Unique Contexts
+
+First, we need to extract unique contexts in the datasets.
+
+<details>
+<summary> Code </summary>
+
+```python
+def extract_unique_contexts(input_directory, output_directory):
+
+    os.makedirs(output_directory, exist_ok=True)
+
+    jsonl_files = glob.glob(os.path.join(input_directory, '*.jsonl'))
+    print(f"Found {len(jsonl_files)} JSONL files.")
+
+    for file_path in jsonl_files:
+        filename = os.path.basename(file_path)
+        name, ext = os.path.splitext(filename)
+        output_filename = f"{name}_unique_contexts.json"
+        output_path = os.path.join(output_directory, output_filename)
+
+        unique_contexts_dict = {}
+
+        print(f"Processing file: {filename}")
+
+        try:
+            with open(file_path, 'r', encoding='utf-8') as infile:
+                for line_number, line in enumerate(infile, start=1):
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        json_obj = json.loads(line)
+                        context = json_obj.get('context')
+                        if context and context not in unique_contexts_dict:
+                            unique_contexts_dict[context] = None
+                    except json.JSONDecodeError as e:
+                        print(f"JSON decoding error in file {filename} at line {line_number}: {e}")
+        except FileNotFoundError:
+            print(f"File not found: {filename}")
+            continue
+        except Exception as e:
+            print(f"An error occurred while processing file {filename}: {e}")
+            continue
+
+        unique_contexts_list = list(unique_contexts_dict.keys())
+        print(f"There are {len(unique_contexts_list)} unique `context` entries in the file {filename}.")
+
+        try:
+            with open(output_path, 'w', encoding='utf-8') as outfile:
+                json.dump(unique_contexts_list, outfile, ensure_ascii=False, indent=4)
+            print(f"Unique `context` entries have been saved to: {output_filename}")
+        except Exception as e:
+            print(f"An error occurred while saving to the file {output_filename}: {e}")
+
+    print("All files have been processed.")
+
+```
+
+</details>
+
+### Step-1 Insert Contexts
+
+For the extracted contexts, we insert them into the LightRAG system.
+
+<details>
+<summary> Code </summary>
+
+```python
+def insert_text(rag, file_path):
+    with open(file_path, mode='r') as f:
+        unique_contexts = json.load(f)
+
+    retries = 0
+    max_retries = 3
+    while retries < max_retries:
+        try:
+            rag.insert(unique_contexts)
+            break
+        except Exception as e:
+            retries += 1
+            print(f"Insertion failed, retrying ({retries}/{max_retries}), error: {e}")
+            time.sleep(10)
+    if retries == max_retries:
+        print("Insertion failed after exceeding the maximum number of retries")
+```
+
+</details>
+
+### Step-2 Generate Queries
+
+We extract tokens from the first and the second half of each context in the dataset, then combine them as dataset descriptions to generate queries.
+
+<details>
+<summary> Code </summary>
+
+```python
+tokenizer = GPT2Tokenizer.from_pretrained('gpt2')
+
+def get_summary(context, tot_tokens=2000):
+    tokens = tokenizer.tokenize(context)
+    half_tokens = tot_tokens // 2
+
+    start_tokens = tokens[1000:1000 + half_tokens]
+    end_tokens = tokens[-(1000 + half_tokens):1000]
+
+    summary_tokens = start_tokens + end_tokens
+    summary = tokenizer.convert_tokens_to_string(summary_tokens)
+
+    return summary
+```
+
+</details>
+
+### Step-3 Query
+
+For the queries generated in Step-2, we will extract them and query LightRAG.
+
+<details>
+<summary> Code </summary>
+
+```python
+def extract_queries(file_path):
+    with open(file_path, 'r') as f:
+        data = f.read()
+
+    data = data.replace('**', '')
+
+    queries = re.findall(r'- Question \d+: (.+)', data)
+
+    return queries
+```
+
+</details>
+
+## 🔗 Related Projects
+
+*Ecosystem & Extensions*
+
+<div align="center">
+  <table>
+    <tr>
+      <td align="center">
+        <a href="https://github.com/HKUDS/RAG-Anything">
+          <div style="width: 100px; height: 100px; background: linear-gradient(135deg, rgba(0, 217, 255, 0.1) 0%, rgba(0, 217, 255, 0.05) 100%); border-radius: 15px; border: 1px solid rgba(0, 217, 255, 0.2); display: flex; align-items: center; justify-content: center; margin-bottom: 10px;">
+            <span style="font-size: 32px;">📸</span>
+          </div>
+          <b>RAG-Anything</b><br>
+          <sub>Multimodal RAG</sub>
+        </a>
+      </td>
+      <td align="center">
+        <a href="https://github.com/HKUDS/VideoRAG">
+          <div style="width: 100px; height: 100px; background: linear-gradient(135deg, rgba(0, 217, 255, 0.1) 0%, rgba(0, 217, 255, 0.05) 100%); border-radius: 15px; border: 1px solid rgba(0, 217, 255, 0.2); display: flex; align-items: center; justify-content: center; margin-bottom: 10px;">
+            <span style="font-size: 32px;">🎥</span>
+          </div>
+          <b>VideoRAG</b><br>
+          <sub>Extreme Long-Context Video RAG</sub>
+        </a>
+      </td>
+      <td align="center">
+        <a href="https://github.com/HKUDS/MiniRAG">
+          <div style="width: 100px; height: 100px; background: linear-gradient(135deg, rgba(0, 217, 255, 0.1) 0%, rgba(0, 217, 255, 0.05) 100%); border-radius: 15px; border: 1px solid rgba(0, 217, 255, 0.2); display: flex; align-items: center; justify-content: center; margin-bottom: 10px;">
+            <span style="font-size: 32px;">✨</span>
+          </div>
+          <b>MiniRAG</b><br>
+          <sub>Extremely Simple RAG</sub>
+        </a>
+      </td>
+    </tr>
+  </table>
+</div>
+
+---
+
+## ⭐ Star History
+
+<a href="https://star-history.com/#HKUDS/LightRAG&Date">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=HKUDS/LightRAG&type=Date&theme=dark" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=HKUDS/LightRAG&type=Date" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=HKUDS/LightRAG&type=Date" />
+ </picture>
+</a>
+
+## 🤝 Contribution
+
+<div align="center">
+  We thank all our contributors for their valuable contributions.
+</div>
+
+<div align="center">
+  <a href="https://github.com/HKUDS/LightRAG/graphs/contributors">
+    <img src="https://contrib.rocks/image?repo=HKUDS/LightRAG" style="border-radius: 15px; box-shadow: 0 0 20px rgba(0, 217, 255, 0.3);" />
+  </a>
+</div>
+
+---
+
+
+## 📖 Citation
+
+```python
+@article{guo2024lightrag,
+title={LightRAG: Simple and Fast Retrieval-Augmented Generation},
+author={Zirui Guo and Lianghao Xia and Yanhua Yu and Tu Ao and Chao Huang},
+year={2024},
+eprint={2410.05779},
+archivePrefix={arXiv},
+primaryClass={cs.IR}
+}
+```
+
+---
+
+<div align="center" style="background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); border-radius: 15px; padding: 30px; margin: 30px 0;">
+  <div>
+    <img src="https://user-images.githubusercontent.com/74038190/212284100-561aa473-3905-4a80-b561-0d28506553ee.gif" width="500">
+  </div>
+  <div style="margin-top: 20px;">
+    <a href="https://github.com/HKUDS/LightRAG" style="text-decoration: none;">
+      <img src="https://img.shields.io/badge/⭐%20Star%20us%20on%20GitHub-1a1a2e?style=for-the-badge&logo=github&logoColor=white">
+    </a>
+    <a href="https://github.com/HKUDS/LightRAG/issues" style="text-decoration: none;">
+      <img src="https://img.shields.io/badge/🐛%20Report%20Issues-ff6b6b?style=for-the-badge&logo=github&logoColor=white">
+    </a>
+    <a href="https://github.com/HKUDS/LightRAG/discussions" style="text-decoration: none;">
+      <img src="https://img.shields.io/badge/💬%20Discussions-4ecdc4?style=for-the-badge&logo=github&logoColor=white">
+    </a>
+  </div>
+</div>
+
+<div align="center">
+  <div style="width: 100%; max-width: 600px; margin: 20px auto; padding: 20px; background: linear-gradient(135deg, rgba(0, 217, 255, 0.1) 0%, rgba(0, 217, 255, 0.05) 100%); border-radius: 15px; border: 1px solid rgba(0, 217, 255, 0.2);">
+    <div style="display: flex; justify-content: center; align-items: center; gap: 15px;">
+      <span style="font-size: 24px;">⭐</span>
+      <span style="color: #00d9ff; font-size: 18px;">Thank you for visiting LightRAG!</span>
+      <span style="font-size: 24px;">⭐</span>
+    </div>
+  </div>
+</div>

LightRAG/SECURITY.md

@@ -0,0 +1,18 @@
+# Reporting Security Issues
+
+The LightRAG team and community take security bugs seriously. We appreciate your efforts to responsibly disclose your findings, and will make every effort to acknowledge your contributions.
+
+To report a security issue, please use the GitHub Security Advisory:  [Report a Vulnerability](https://github.com/HKUDS/LightRAG/security/advisories/new)
+
+The LightRAG team will send a response indicating the next steps in handling your report. After the initial reply to your report, the security team will keep you informed of the progress towards a fix and full announcement, and may ask for additional information or guidance.
+
+Report security bugs in third-party modules to the person or team maintaining the module.
+
+### Supported Versions
+
+The following versions currently being supported with security updates.
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 1.2.x   | :x:                |
+| 1.3.x   | :white_check_mark: |

LightRAG/config.ini.example

@@ -0,0 +1,37 @@
+[neo4j]
+uri = neo4j+s://xxxxxxxx.databases.neo4j.io
+username = neo4j
+password = your-password
+connection_pool_size = 100
+connection_timeout = 30.0
+connection_acquisition_timeout = 30.0
+max_transaction_retry_time = 30.0
+max_connection_lifetime = 300.0
+liveness_check_timeout = 30.0
+keep_alive = true
+
+[mongodb]
+uri = mongodb+srv://name:password@your-cluster-address
+database = lightrag
+
+[redis]
+uri=redis://localhost:6379/1
+
+[qdrant]
+uri = http://localhost:16333
+
+[postgres]
+host = localhost
+port = 5432
+user = your_username
+password = your_password
+database = your_database
+# workspace = default
+max_connections = 12
+vector_index_type = HNSW        # HNSW or IVFFLAT
+hnsw_m = 16
+hnsw_ef = 64
+ivfflat_lists = 100
+
+[memgraph]
+uri = bolt://localhost:7687

LightRAG/docker-compose.yml

@@ -0,0 +1,24 @@
+services:
+  lightrag:
+    container_name: lightrag
+    image: ghcr.io/hkuds/lightrag:latest
+    build:
+      context: .
+      dockerfile: Dockerfile
+      tags:
+        - ghcr.io/hkuds/lightrag:latest
+    ports:
+      - "${PORT:-9621}:9621"
+    volumes:
+      - ./data/rag_storage:/app/data/rag_storage
+      - ./data/inputs:/app/data/inputs
+      - ./data/tiktoken:/app/data/tiktoken
+      - ./config.ini:/app/config.ini
+      - ./.env:/app/.env
+    env_file:
+      - .env
+    environment:
+      - TIKTOKEN_CACHE_DIR=/app/data/tiktoken
+    restart: unless-stopped
+    extra_hosts:
+      - "host.docker.internal:host-gateway"

LightRAG/docs/Algorithm.md

@@ -0,0 +1,4 @@
+![LightRAG Indexing Flowchart](https://learnopencv.com/wp-content/uploads/2024/11/LightRAG-VectorDB-Json-KV-Store-Indexing-Flowchart-scaled.jpg)
+*Figure 1: LightRAG Indexing Flowchart - Img Caption : [Source](https://learnopencv.com/lightrag/)*
+![LightRAG Retrieval and Querying Flowchart](https://learnopencv.com/wp-content/uploads/2024/11/LightRAG-Querying-Flowchart-Dual-Level-Retrieval-Generation-Knowledge-Graphs-scaled.jpg)
+*Figure 2: LightRAG Retrieval and Querying Flowchart - Img Caption : [Source](https://learnopencv.com/lightrag/)*

LightRAG/docs/DockerDeployment.md

@@ -0,0 +1,175 @@
+# LightRAG
+
+A lightweight Knowledge Graph Retrieval-Augmented Generation system with multiple LLM backend support.
+
+## 🚀 Installation
+
+### Prerequisites
+- Python 3.10+
+- Git
+- Docker (optional for Docker deployment)
+
+### Native Installation
+
+1. Clone the repository:
+```bash
+# Linux/MacOS
+git clone https://github.com/HKUDS/LightRAG.git
+cd LightRAG
+```
+```powershell
+# Windows PowerShell
+git clone https://github.com/HKUDS/LightRAG.git
+cd LightRAG
+```
+
+2. Configure your environment:
+```bash
+# Linux/MacOS
+cp .env.example .env
+# Edit .env with your preferred configuration
+```
+```powershell
+# Windows PowerShell
+Copy-Item .env.example .env
+# Edit .env with your preferred configuration
+```
+
+3. Create and activate virtual environment:
+```bash
+# Linux/MacOS
+python -m venv venv
+source venv/bin/activate
+```
+```powershell
+# Windows PowerShell
+python -m venv venv
+.\venv\Scripts\Activate
+```
+
+4. Install dependencies:
+```bash
+# Both platforms
+pip install -r requirements.txt
+```
+
+## 🐳 Docker Deployment
+
+Docker instructions work the same on all platforms with Docker Desktop installed.
+
+1. Build and start the container:
+```bash
+docker-compose up -d
+```
+
+### Configuration Options
+
+LightRAG can be configured using environment variables in the `.env` file:
+
+#### Server Configuration
+- `HOST`: Server host (default: 0.0.0.0)
+- `PORT`: Server port (default: 9621)
+
+#### LLM Configuration
+- `LLM_BINDING`: LLM backend to use (lollms/ollama/openai)
+- `LLM_BINDING_HOST`: LLM server host URL
+- `LLM_MODEL`: Model name to use
+
+#### Embedding Configuration
+- `EMBEDDING_BINDING`: Embedding backend (lollms/ollama/openai)
+- `EMBEDDING_BINDING_HOST`: Embedding server host URL
+- `EMBEDDING_MODEL`: Embedding model name
+
+#### RAG Configuration
+- `MAX_ASYNC`: Maximum async operations
+- `MAX_TOKENS`: Maximum token size
+- `EMBEDDING_DIM`: Embedding dimensions
+
+#### Security
+- `LIGHTRAG_API_KEY`: API key for authentication
+
+### Data Storage Paths
+
+The system uses the following paths for data storage:
+```
+data/
+├── rag_storage/    # RAG data persistence
+└── inputs/         # Input documents
+```
+
+### Example Deployments
+
+1. Using with Ollama:
+```env
+LLM_BINDING=ollama
+LLM_BINDING_HOST=http://host.docker.internal:11434
+LLM_MODEL=mistral
+EMBEDDING_BINDING=ollama
+EMBEDDING_BINDING_HOST=http://host.docker.internal:11434
+EMBEDDING_MODEL=bge-m3
+```
+
+you can't just use localhost from docker, that's why you need to use host.docker.internal which is defined in the docker compose file and should allow you to access the localhost services.
+
+2. Using with OpenAI:
+```env
+LLM_BINDING=openai
+LLM_MODEL=gpt-3.5-turbo
+EMBEDDING_BINDING=openai
+EMBEDDING_MODEL=text-embedding-ada-002
+OPENAI_API_KEY=your-api-key
+```
+
+### API Usage
+
+Once deployed, you can interact with the API at `http://localhost:9621`
+
+Example query using PowerShell:
+```powershell
+$headers = @{
+    "X-API-Key" = "your-api-key"
+    "Content-Type" = "application/json"
+}
+$body = @{
+    query = "your question here"
+} | ConvertTo-Json
+
+Invoke-RestMethod -Uri "http://localhost:9621/query" -Method Post -Headers $headers -Body $body
+```
+
+Example query using curl:
+```bash
+curl -X POST "http://localhost:9621/query" \
+     -H "X-API-Key: your-api-key" \
+     -H "Content-Type: application/json" \
+     -d '{"query": "your question here"}'
+```
+
+## 🔒 Security
+
+Remember to:
+1. Set a strong API key in production
+2. Use SSL in production environments
+3. Configure proper network security
+
+## 📦 Updates
+
+To update the Docker container:
+```bash
+docker-compose pull
+docker-compose up -d --build
+```
+
+To update native installation:
+```bash
+# Linux/MacOS
+git pull
+source venv/bin/activate
+pip install -r requirements.txt
+```
+```powershell
+# Windows PowerShell
+git pull
+.\venv\Scripts\Activate
+pip install -r requirements.txt
+```

LightRAG/docs/LightRAG_concurrent_explain.md

@@ -0,0 +1,114 @@
+## LightRAG Multi-Document Processing: Concurrent Control Strategy
+
+LightRAG employs a multi-layered concurrent control strategy when processing multiple documents. This article provides an in-depth analysis of the concurrent control mechanisms at document level, chunk level, and LLM request level, helping you understand why specific concurrent behaviors occur.
+
+### 1. Document-Level Concurrent Control
+
+**Control Parameter**: `max_parallel_insert`
+
+This parameter controls the number of documents processed simultaneously. The purpose is to prevent excessive parallelism from overwhelming system resources, which could lead to extended processing times for individual files. Document-level concurrency is governed by the `max_parallel_insert` attribute within LightRAG, which defaults to 2 and is configurable via the `MAX_PARALLEL_INSERT` environment variable.  `max_parallel_insert` is recommended to be set between 2 and 10, typically `llm_model_max_async/3`. Setting this value too high can increase the likelihood of naming conflicts among entities and relationships across different documents during the merge phase, thereby reducing its overall efficiency.
+
+### 2. Chunk-Level Concurrent Control
+
+**Control Parameter**: `llm_model_max_async`
+
+This parameter controls the number of chunks processed simultaneously in the extraction stage within a document. The purpose is to prevent a high volume of concurrent requests from monopolizing LLM processing resources, which would impede the efficient parallel processing of multiple files. Chunk-Level Concurrent Control is governed by the `llm_model_max_async` attribute within LightRAG, which defaults to 4 and is configurable via the `MAX_ASYNC` environment variable. The purpose of this parameter is to fully leverage the LLM's concurrency capabilities when processing individual documents.
+
+In the `extract_entities` function, **each document independently creates** its own chunk semaphore. Since each document independently creates chunk semaphores, the theoretical chunk concurrency of the system is:
+$$
+ChunkConcurrency = Max Parallel Insert × LLM Model Max Async
+$$
+For example:
+- `max_parallel_insert = 2` (process 2 documents simultaneously)
+- `llm_model_max_async = 4` (maximum 4 chunk concurrency per document)
+- Theoretical chunk-level concurrent: 2 × 4 = 8
+
+### 3. Graph-Level Concurrent Control
+
+**Control Parameter**: `llm_model_max_async * 2`
+
+This parameter controls the number of entities and relations processed simultaneously in the merging stage within a document. The purpose is to prevent a high volume of concurrent requests from monopolizing LLM processing resources, which would impede the efficient parallel processing of multiple files. Graph-level concurrency is governed by the `llm_model_max_async` attribute within LightRAG, which defaults to 4 and is configurable via the `MAX_ASYNC` environment variable. Graph-level parallelism control parameters are equally applicable to managing parallelism during the entity relationship reconstruction phase after document deletion.
+
+Given that the entity relationship merging phase doesn't necessitate LLM interaction for every operation, its parallelism is set at double the LLM's parallelism. This optimizes machine utilization while concurrently preventing excessive queuing resource contention for the LLM.
+
+### 4. LLM-Level Concurrent Control
+
+**Control Parameter**: `llm_model_max_async`
+
+This parameter governs the **concurrent volume** of LLM requests dispatched by the entire LightRAG system, encompassing the document extraction stage, merging stage, and user query handling.
+
+LLM request prioritization is managed via a global priority queue, which **systematically prioritizes user queries** over merging-related requests, and merging-related requests over extraction-related requests. This strategic prioritization **minimizes user query latency**.
+
+LLM-level concurrency is governed by the `llm_model_max_async` attribute within LightRAG, which defaults to 4 and is configurable via the `MAX_ASYNC` environment variable.
+
+### 5. Complete Concurrent Hierarchy Diagram
+
+```mermaid
+graph TD
+classDef doc fill:#e6f3ff,stroke:#5b9bd5,stroke-width:2px;
+classDef chunk fill:#fbe5d6,stroke:#ed7d31,stroke-width:1px;
+classDef merge fill:#e2f0d9,stroke:#70ad47,stroke-width:2px;
+
+A["Multiple Documents<br>max_parallel_insert = 2"] --> A1
+A --> B1
+
+A1[DocA: split to n chunks] --> A_chunk;
+B1[DocB: split to m chunks] --> B_chunk;
+
+subgraph A_chunk[Extraction Stage]
+    A_chunk_title[Entity Relation Extraction<br>llm_model_max_async = 4];
+    A_chunk_title --> A_chunk1[Chunk A1]:::chunk;
+    A_chunk_title --> A_chunk2[Chunk A2]:::chunk;
+    A_chunk_title --> A_chunk3[Chunk A3]:::chunk;
+    A_chunk_title --> A_chunk4[Chunk A4]:::chunk;
+    A_chunk1 & A_chunk2 & A_chunk3 & A_chunk4  --> A_chunk_done([Extraction Complete]);
+end
+
+subgraph B_chunk[Extraction Stage]
+    B_chunk_title[Entity Relation Extraction<br>llm_model_max_async = 4];
+    B_chunk_title --> B_chunk1[Chunk B1]:::chunk;
+    B_chunk_title --> B_chunk2[Chunk B2]:::chunk;
+    B_chunk_title --> B_chunk3[Chunk B3]:::chunk;
+    B_chunk_title --> B_chunk4[Chunk B4]:::chunk;
+    B_chunk1 & B_chunk2 & B_chunk3 & B_chunk4  --> B_chunk_done([Extraction Complete]);
+end
+A_chunk -.->|LLM Request| LLM_Queue;
+
+A_chunk --> A_merge;
+B_chunk --> B_merge;
+
+subgraph A_merge[Merge Stage]
+    A_merge_title[Entity Relation Merging<br>llm_model_max_async * 2 = 8];
+    A_merge_title --> A1_entity[Ent a1]:::merge;
+    A_merge_title --> A2_entity[Ent a2]:::merge;
+    A_merge_title --> A3_entity[Rel a3]:::merge;
+    A_merge_title --> A4_entity[Rel a4]:::merge;
+    A1_entity & A2_entity & A3_entity & A4_entity --> A_done([Merge Complete])
+end
+
+subgraph B_merge[Merge Stage]
+    B_merge_title[Entity Relation Merging<br>llm_model_max_async * 2 = 8];
+    B_merge_title --> B1_entity[Ent b1]:::merge;
+    B_merge_title --> B2_entity[Ent b2]:::merge;
+    B_merge_title --> B3_entity[Rel b3]:::merge;
+    B_merge_title --> B4_entity[Rel b4]:::merge;
+    B1_entity & B2_entity & B3_entity & B4_entity --> B_done([Merge Complete])
+end
+
+A_merge -.->|LLM Request| LLM_Queue["LLM Request Prioritized Queue<br>llm_model_max_async = 4"];
+B_merge -.->|LLM Request| LLM_Queue;
+B_chunk -.->|LLM Request| LLM_Queue;
+
+```
+
+> The extraction and merge stages share a global prioritized LLM queue, regulated by `llm_model_max_async`. While numerous entity and relation extraction and merging operations may be "actively processing", **only a limited number will concurrently execute LLM requests** the remainder will be queued and awaiting their turn.
+
+### 6. Performance Optimization Recommendations
+
+* **Increase LLM Concurrent Setting based on the capabilities of your LLM server or API provider**
+
+During the file processing phase, the performance and concurrency capabilities of the LLM are critical bottlenecks. When deploying LLMs locally, the service's concurrency capacity must adequately account for the context length requirements of LightRAG. LightRAG recommends that LLMs support a minimum context length of 32KB; therefore, server concurrency should be calculated based on this benchmark. For API providers, LightRAG will retry requests up to three times if the client's request is rejected due to concurrent request limits. Backend logs can be used to determine if LLM retries are occurring, thereby indicating whether `MAX_ASYNC` has exceeded the API provider's limits.
+
+* **Align Parallel Document Insertion Settings with LLM Concurrency Configurations**
+
+The recommended number of parallel document processing tasks is 1/4 of the LLM's concurrency, with a minimum of 2 and a maximum of 10. Setting a higher number of parallel document processing tasks typically does not accelerate overall document processing speed, as even a small number of concurrently processed documents can fully utilize the LLM's parallel processing capabilities. Excessive parallel document processing can significantly increase the processing time for each individual document. Since LightRAG commits processing results on a file-by-file basis, a large number of concurrent files would necessitate caching a substantial amount of data. In the event of a system error, all documents in the middle stage would require reprocessing, thereby increasing error handling costs. For instance, setting `MAX_PARALLEL_INSERT` to 3 is appropriate when `MAX_ASYNC` is configured to 12.

LightRAG/env.example

@@ -0,0 +1,357 @@
+### This is sample file of .env
+
+###########################
+### Server Configuration
+###########################
+HOST=0.0.0.0
+PORT=9621
+WEBUI_TITLE='My Graph KB'
+WEBUI_DESCRIPTION="Simple and Fast Graph Based RAG System"
+# WORKERS=2
+### gunicorn worker timeout(as default LLM request timeout if LLM_TIMEOUT is not set)
+# TIMEOUT=150
+# CORS_ORIGINS=http://localhost:3000,http://localhost:8080
+
+### Optional SSL Configuration
+# SSL=true
+# SSL_CERTFILE=/path/to/cert.pem
+# SSL_KEYFILE=/path/to/key.pem
+
+### Directory Configuration (defaults to current working directory)
+### Default value is ./inputs and ./rag_storage
+# INPUT_DIR=<absolute_path_for_doc_input_dir>
+# WORKING_DIR=<absolute_path_for_working_dir>
+
+### Tiktoken cache directory (Store cached files in this folder for offline deployment)
+# TIKTOKEN_CACHE_DIR=./temp/tiktoken
+
+### Ollama Emulating Model and Tag
+# OLLAMA_EMULATING_MODEL_NAME=lightrag
+OLLAMA_EMULATING_MODEL_TAG=latest
+
+### Max nodes return from grap retrieval in webui
+# MAX_GRAPH_NODES=1000
+
+### Logging level
+# LOG_LEVEL=INFO
+# VERBOSE=False
+# LOG_MAX_BYTES=10485760
+# LOG_BACKUP_COUNT=5
+### Logfile location (defaults to current working directory)
+# LOG_DIR=/path/to/log/directory
+
+#####################################
+### Login and API-Key Configuration
+#####################################
+# AUTH_ACCOUNTS='admin:admin123,user1:pass456'
+# TOKEN_SECRET=Your-Key-For-LightRAG-API-Server
+# TOKEN_EXPIRE_HOURS=48
+# GUEST_TOKEN_EXPIRE_HOURS=24
+# JWT_ALGORITHM=HS256
+
+### API-Key to access LightRAG Server API
+# LIGHTRAG_API_KEY=your-secure-api-key-here
+# WHITELIST_PATHS=/health,/api/*
+
+######################################################################################
+### Query Configuration
+###
+### How to control the context lenght sent to LLM:
+###    MAX_ENTITY_TOKENS + MAX_RELATION_TOKENS < MAX_TOTAL_TOKENS
+###    Chunk_Tokens = MAX_TOTAL_TOKENS - Actual_Entity_Tokens - Actual_Reation_Tokens
+######################################################################################
+# LLM responde cache for query (Not valid for streaming response)
+ENABLE_LLM_CACHE=true
+# COSINE_THRESHOLD=0.2
+### Number of entities or relations retrieved from KG
+# TOP_K=40
+### Maxmium number or chunks for naive vector search
+# CHUNK_TOP_K=20
+### control the actual enties send to LLM
+# MAX_ENTITY_TOKENS=6000
+### control the actual relations send to LLM
+# MAX_RELATION_TOKENS=8000
+### control the maximum tokens send to LLM (include entities, raltions and chunks)
+# MAX_TOTAL_TOKENS=30000
+
+### maximum number of related chunks per source entity or relation
+###     The chunk picker uses this value to determine the total number of chunks selected from KG(knowledge graph)
+###     Higher values increase re-ranking time
+# RELATED_CHUNK_NUMBER=5
+
+### chunk selection strategies
+###     VECTOR: Pick KG chunks by vector similarity, delivered chunks to the LLM aligning more closely with naive retrieval
+###     WEIGHT: Pick KG chunks by entity and chunk weight, delivered more solely KG related chunks to the LLM
+###     If reranking is enabled, the impact of chunk selection strategies will be diminished.
+# KG_CHUNK_PICK_METHOD=VECTOR
+
+#########################################################
+### Reranking configuration
+### RERANK_BINDING type:  null, cohere, jina, aliyun
+### For rerank model deployed by vLLM use cohere binding
+#########################################################
+RERANK_BINDING=null
+### Enable rerank by default in query params when RERANK_BINDING is not null
+# RERANK_BY_DEFAULT=True
+### rerank score chunk filter(set to 0.0 to keep all chunks, 0.6 or above if LLM is not strong enought)
+# MIN_RERANK_SCORE=0.0
+
+### For local deployment with vLLM
+# RERANK_MODEL=BAAI/bge-reranker-v2-m3
+# RERANK_BINDING_HOST=http://localhost:8000/v1/rerank
+# RERANK_BINDING_API_KEY=your_rerank_api_key_here
+
+### Default value for Cohere AI
+# RERANK_MODEL=rerank-v3.5
+# RERANK_BINDING_HOST=https://api.cohere.com/v2/rerank
+# RERANK_BINDING_API_KEY=your_rerank_api_key_here
+
+### Default value for Jina AI
+# RERANK_MODEL=jina-reranker-v2-base-multilingual
+# RERANK_BINDING_HOST=https://api.jina.ai/v1/rerank
+# RERANK_BINDING_API_KEY=your_rerank_api_key_here
+
+### Default value for Aliyun
+# RERANK_MODEL=gte-rerank-v2
+# RERANK_BINDING_HOST=https://dashscope.aliyuncs.com/api/v1/services/rerank/text-rerank/text-rerank
+# RERANK_BINDING_API_KEY=your_rerank_api_key_here
+
+########################################
+### Document processing configuration
+########################################
+ENABLE_LLM_CACHE_FOR_EXTRACT=true
+
+### Document processing output language: English, Chinese, French, German ...
+SUMMARY_LANGUAGE=English
+
+### Entity types that the LLM will attempt to recognize
+# ENTITY_TYPES='["Person", "Organization", "Location", "Event", "Concept", "Method", "Content", "Data", "Artifact", "NaturalObject"]'
+
+### Chunk size for document splitting, 500~1500 is recommended
+# CHUNK_SIZE=1200
+# CHUNK_OVERLAP_SIZE=100
+
+### Number of summary semgments or tokens to trigger LLM summary on entity/relation merge (at least 3 is recommented)
+# FORCE_LLM_SUMMARY_ON_MERGE=8
+### Max description token size to trigger LLM summary
+# SUMMARY_MAX_TOKENS = 1200
+### Recommended LLM summary output length in tokens
+# SUMMARY_LENGTH_RECOMMENDED_=600
+### Maximum context size sent to LLM for description summary
+# SUMMARY_CONTEXT_SIZE=12000
+
+###############################
+### Concurrency Configuration
+###############################
+### Max concurrency requests of LLM (for both query and document processing)
+MAX_ASYNC=4
+### Number of parallel processing documents(between 2~10, MAX_ASYNC/3 is recommended)
+MAX_PARALLEL_INSERT=2
+### Max concurrency requests for Embedding
+# EMBEDDING_FUNC_MAX_ASYNC=8
+### Num of chunks send to Embedding in single request
+# EMBEDDING_BATCH_NUM=10
+
+###########################################################
+### LLM Configuration
+### LLM_BINDING type: openai, ollama, lollms, azure_openai, aws_bedrock
+###########################################################
+### LLM request timeout setting for all llm (0 means no timeout for Ollma)
+# LLM_TIMEOUT=180
+
+LLM_BINDING=openai
+LLM_MODEL=gpt-4o
+LLM_BINDING_HOST=https://api.openai.com/v1
+LLM_BINDING_API_KEY=your_api_key
+
+### Optional for Azure
+# AZURE_OPENAI_API_VERSION=2024-08-01-preview
+# AZURE_OPENAI_DEPLOYMENT=gpt-4o
+
+### Openrouter example
+# LLM_MODEL=google/gemini-2.5-flash
+# LLM_BINDING_HOST=https://openrouter.ai/api/v1
+# LLM_BINDING_API_KEY=your_api_key
+# LLM_BINDING=openai
+
+### OpenAI Compatible API Specific Parameters
+### Set the max_tokens to mitigate endless output of some LLM (less than LLM_TIMEOUT * llm_output_tokens/second, i.e. 9000 = 180s * 50 tokens/s)
+### Typically, max_tokens does not include prompt content, though some models, such as Gemini Models, are exceptions
+### For vLLM/SGLang doployed models, or most of OpenAI compatible API provider
+# OPENAI_LLM_MAX_TOKENS=9000
+### For OpenAI o1-mini or newer modles
+OPENAI_LLM_MAX_COMPLETION_TOKENS=9000
+
+#### OpenAI's new API utilizes max_completion_tokens instead of max_tokens
+# OPENAI_LLM_MAX_TOKENS=9000
+# OPENAI_LLM_MAX_COMPLETION_TOKENS=9000
+
+### OpenRouter Specific Parameters
+# OPENAI_LLM_EXTRA_BODY='{"reasoning": {"enabled": false}}'
+### Qwen3 Specific Parameters depoly by vLLM
+# OPENAI_LLM_EXTRA_BODY='{"chat_template_kwargs": {"enable_thinking": false}}'
+
+### use the following command to see all support options for OpenAI, azure_openai or OpenRouter
+### lightrag-server --llm-binding openai --help
+
+### Ollama Server Specific Parameters
+### OLLAMA_LLM_NUM_CTX must be provided, and should at least larger than MAX_TOTAL_TOKENS + 2000
+OLLAMA_LLM_NUM_CTX=32768
+### Set the max_output_tokens to mitigate endless output of some LLM (less than LLM_TIMEOUT * llm_output_tokens/second, i.e. 9000 = 180s * 50 tokens/s)
+# OLLAMA_LLM_NUM_PREDICT=9000
+### Stop sequences for Ollama LLM
+# OLLAMA_LLM_STOP='["</s>", "<|EOT|>"]'
+### use the following command to see all support options for Ollama LLM
+### lightrag-server --llm-binding ollama --help
+
+### Bedrock Specific Parameters
+# BEDROCK_LLM_TEMPERATURE=1.0
+
+####################################################################################
+### Embedding Configuration (Should not be changed after the first file processed)
+### EMBEDDING_BINDING: ollama, openai, azure_openai, jina, lollms, aws_bedrock
+####################################################################################
+# EMBEDDING_TIMEOUT=30
+EMBEDDING_BINDING=ollama
+EMBEDDING_MODEL=bge-m3:latest
+EMBEDDING_DIM=1024
+EMBEDDING_BINDING_API_KEY=your_api_key
+# If the embedding service is deployed within the same Docker stack, use host.docker.internal instead of localhost
+EMBEDDING_BINDING_HOST=http://localhost:11434
+
+### OpenAI compatible (VoyageAI embedding openai compatible)
+# EMBEDDING_BINDING=openai
+# EMBEDDING_MODEL=text-embedding-3-large
+# EMBEDDING_DIM=3072
+# EMBEDDING_BINDING_HOST=https://api.openai.com/v1
+# EMBEDDING_BINDING_API_KEY=your_api_key
+
+### Optional for Azure
+# AZURE_EMBEDDING_DEPLOYMENT=text-embedding-3-large
+# AZURE_EMBEDDING_API_VERSION=2023-05-15
+# AZURE_EMBEDDING_ENDPOINT=your_endpoint
+# AZURE_EMBEDDING_API_KEY=your_api_key
+
+### Jina AI Embedding
+# EMBEDDING_BINDING=jina
+# EMBEDDING_BINDING_HOST=https://api.jina.ai/v1/embeddings
+# EMBEDDING_MODEL=jina-embeddings-v4
+# EMBEDDING_DIM=2048
+# EMBEDDING_BINDING_API_KEY=your_api_key
+
+### Optional for Ollama embedding
+OLLAMA_EMBEDDING_NUM_CTX=8192
+### use the following command to see all support options for Ollama embedding
+### lightrag-server --embedding-binding ollama --help
+
+####################################################################
+### WORKSPACE setting workspace name for all storage types
+### in the purpose of isolating data from LightRAG instances.
+### Valid workspace name constraints: a-z, A-Z, 0-9, and _
+####################################################################
+# WORKSPACE=space1
+
+############################
+### Data storage selection
+############################
+### Default storage (Recommended for small scale deployment)
+# LIGHTRAG_KV_STORAGE=JsonKVStorage
+# LIGHTRAG_DOC_STATUS_STORAGE=JsonDocStatusStorage
+# LIGHTRAG_GRAPH_STORAGE=NetworkXStorage
+# LIGHTRAG_VECTOR_STORAGE=NanoVectorDBStorage
+
+### Redis Storage (Recommended for production deployment)
+# LIGHTRAG_KV_STORAGE=RedisKVStorage
+# LIGHTRAG_DOC_STATUS_STORAGE=RedisDocStatusStorage
+
+### Vector Storage (Recommended for production deployment)
+# LIGHTRAG_VECTOR_STORAGE=MilvusVectorDBStorage
+# LIGHTRAG_VECTOR_STORAGE=QdrantVectorDBStorage
+# LIGHTRAG_VECTOR_STORAGE=FaissVectorDBStorage
+
+### Graph Storage (Recommended for production deployment)
+# LIGHTRAG_GRAPH_STORAGE=Neo4JStorage
+# LIGHTRAG_GRAPH_STORAGE=MemgraphStorage
+
+### PostgreSQL
+# LIGHTRAG_KV_STORAGE=PGKVStorage
+# LIGHTRAG_DOC_STATUS_STORAGE=PGDocStatusStorage
+# LIGHTRAG_GRAPH_STORAGE=PGGraphStorage
+# LIGHTRAG_VECTOR_STORAGE=PGVectorStorage
+
+### MongoDB (Vector storage only available on Atlas Cloud)
+# LIGHTRAG_KV_STORAGE=MongoKVStorage
+# LIGHTRAG_DOC_STATUS_STORAGE=MongoDocStatusStorage
+# LIGHTRAG_GRAPH_STORAGE=MongoGraphStorage
+# LIGHTRAG_VECTOR_STORAGE=MongoVectorDBStorage
+
+### PostgreSQL Configuration
+POSTGRES_HOST=localhost
+POSTGRES_PORT=5432
+POSTGRES_USER=your_username
+POSTGRES_PASSWORD='your_password'
+POSTGRES_DATABASE=your_database
+POSTGRES_MAX_CONNECTIONS=12
+# POSTGRES_WORKSPACE=forced_workspace_name
+
+### PostgreSQL Vector Storage Configuration
+### Vector storage type: HNSW, IVFFlat
+POSTGRES_VECTOR_INDEX_TYPE=HNSW
+POSTGRES_HNSW_M=16
+POSTGRES_HNSW_EF=200
+POSTGRES_IVFFLAT_LISTS=100
+
+### PostgreSQL SSL Configuration (Optional)
+# POSTGRES_SSL_MODE=require
+# POSTGRES_SSL_CERT=/path/to/client-cert.pem
+# POSTGRES_SSL_KEY=/path/to/client-key.pem
+# POSTGRES_SSL_ROOT_CERT=/path/to/ca-cert.pem
+# POSTGRES_SSL_CRL=/path/to/crl.pem
+
+### Neo4j Configuration
+NEO4J_URI=neo4j+s://xxxxxxxx.databases.neo4j.io
+NEO4J_USERNAME=neo4j
+NEO4J_PASSWORD='your_password'
+NEO4J_DATABASE=noe4j
+NEO4J_MAX_CONNECTION_POOL_SIZE=100
+NEO4J_CONNECTION_TIMEOUT=30
+NEO4J_CONNECTION_ACQUISITION_TIMEOUT=30
+NEO4J_MAX_TRANSACTION_RETRY_TIME=30
+NEO4J_MAX_CONNECTION_LIFETIME=300
+NEO4J_LIVENESS_CHECK_TIMEOUT=30
+NEO4J_KEEP_ALIVE=true
+# NEO4J_WORKSPACE=forced_workspace_name
+
+### MongoDB Configuration
+MONGO_URI=mongodb://root:root@localhost:27017/
+#MONGO_URI=mongodb+srv://xxxx
+MONGO_DATABASE=LightRAG
+# MONGODB_WORKSPACE=forced_workspace_name
+
+### Milvus Configuration
+MILVUS_URI=http://localhost:19530
+MILVUS_DB_NAME=lightrag
+# MILVUS_USER=root
+# MILVUS_PASSWORD=your_password
+# MILVUS_TOKEN=your_token
+# MILVUS_WORKSPACE=forced_workspace_name
+
+### Qdrant
+QDRANT_URL=http://localhost:6333
+# QDRANT_API_KEY=your-api-key
+# QDRANT_WORKSPACE=forced_workspace_name
+
+### Redis
+REDIS_URI=redis://localhost:6379
+REDIS_SOCKET_TIMEOUT=30
+REDIS_CONNECT_TIMEOUT=10
+REDIS_MAX_CONNECTIONS=100
+REDIS_RETRY_ATTEMPTS=3
+# REDIS_WORKSPACE=forced_workspace_name
+
+### Memgraph Configuration
+MEMGRAPH_URI=bolt://localhost:7687
+MEMGRAPH_USERNAME=
+MEMGRAPH_PASSWORD=
+MEMGRAPH_DATABASE=memgraph
+# MEMGRAPH_WORKSPACE=forced_workspace_name

LightRAG/env.ollama-binding-options.example

@@ -0,0 +1,195 @@
+################################################################################
+# Autogenerated .env entries list for LightRAG binding options
+#
+# To generate run:
+# $ python -m lightrag.llm.binding_options
+################################################################################
+# ollama_embedding -- Context window size (number of tokens)
+# OLLAMA_EMBEDDING_NUM_CTX=4096
+
+# ollama_embedding -- Maximum number of tokens to predict
+# OLLAMA_EMBEDDING_NUM_PREDICT=128
+
+# ollama_embedding -- Number of tokens to keep from the initial prompt
+# OLLAMA_EMBEDDING_NUM_KEEP=0
+
+# ollama_embedding -- Random seed for generation (-1 for random)
+# OLLAMA_EMBEDDING_SEED=-1
+
+# ollama_embedding -- Controls randomness (0.0-2.0, higher = more creative)
+# OLLAMA_EMBEDDING_TEMPERATURE=0.8
+
+# ollama_embedding -- Top-k sampling parameter (0 = disabled)
+# OLLAMA_EMBEDDING_TOP_K=40
+
+# ollama_embedding -- Top-p (nucleus) sampling parameter (0.0-1.0)
+# OLLAMA_EMBEDDING_TOP_P=0.9
+
+# ollama_embedding -- Tail free sampling parameter (1.0 = disabled)
+# OLLAMA_EMBEDDING_TFS_Z=1.0
+
+# ollama_embedding -- Typical probability mass (1.0 = disabled)
+# OLLAMA_EMBEDDING_TYPICAL_P=1.0
+
+# ollama_embedding -- Minimum probability threshold (0.0 = disabled)
+# OLLAMA_EMBEDDING_MIN_P=0.0
+
+# ollama_embedding -- Number of tokens to consider for repetition penalty
+# OLLAMA_EMBEDDING_REPEAT_LAST_N=64
+
+# ollama_embedding -- Penalty for repetition (1.0 = no penalty)
+# OLLAMA_EMBEDDING_REPEAT_PENALTY=1.1
+
+# ollama_embedding -- Penalty for token presence (-2.0 to 2.0)
+# OLLAMA_EMBEDDING_PRESENCE_PENALTY=0.0
+
+# ollama_embedding -- Penalty for token frequency (-2.0 to 2.0)
+# OLLAMA_EMBEDDING_FREQUENCY_PENALTY=0.0
+
+# ollama_embedding -- Mirostat sampling algorithm (0=disabled, 1=Mirostat 1.0, 2=Mirostat 2.0)
+# OLLAMA_EMBEDDING_MIROSTAT=0
+
+# ollama_embedding -- Mirostat target entropy
+# OLLAMA_EMBEDDING_MIROSTAT_TAU=5.0
+
+# ollama_embedding -- Mirostat learning rate
+# OLLAMA_EMBEDDING_MIROSTAT_ETA=0.1
+
+# ollama_embedding -- Enable NUMA optimization
+# OLLAMA_EMBEDDING_NUMA=False
+
+# ollama_embedding -- Batch size for processing
+# OLLAMA_EMBEDDING_NUM_BATCH=512
+
+# ollama_embedding -- Number of GPUs to use (-1 for auto)
+# OLLAMA_EMBEDDING_NUM_GPU=-1
+
+# ollama_embedding -- Main GPU index
+# OLLAMA_EMBEDDING_MAIN_GPU=0
+
+# ollama_embedding -- Optimize for low VRAM
+# OLLAMA_EMBEDDING_LOW_VRAM=False
+
+# ollama_embedding -- Number of CPU threads (0 for auto)
+# OLLAMA_EMBEDDING_NUM_THREAD=0
+
+# ollama_embedding -- Use half-precision for key/value cache
+# OLLAMA_EMBEDDING_F16_KV=True
+
+# ollama_embedding -- Return logits for all tokens
+# OLLAMA_EMBEDDING_LOGITS_ALL=False
+
+# ollama_embedding -- Only load vocabulary
+# OLLAMA_EMBEDDING_VOCAB_ONLY=False
+
+# ollama_embedding -- Use memory mapping for model files
+# OLLAMA_EMBEDDING_USE_MMAP=True
+
+# ollama_embedding -- Lock model in memory
+# OLLAMA_EMBEDDING_USE_MLOCK=False
+
+# ollama_embedding -- Only use for embeddings
+# OLLAMA_EMBEDDING_EMBEDDING_ONLY=False
+
+# ollama_embedding -- Penalize newline tokens
+# OLLAMA_EMBEDDING_PENALIZE_NEWLINE=True
+
+# ollama_embedding -- Stop sequences (comma-separated string)
+# OLLAMA_EMBEDDING_STOP=
+
+# ollama_llm -- Context window size (number of tokens)
+# OLLAMA_LLM_NUM_CTX=4096
+
+# ollama_llm -- Maximum number of tokens to predict
+# OLLAMA_LLM_NUM_PREDICT=128
+
+# ollama_llm -- Number of tokens to keep from the initial prompt
+# OLLAMA_LLM_NUM_KEEP=0
+
+# ollama_llm -- Random seed for generation (-1 for random)
+# OLLAMA_LLM_SEED=-1
+
+# ollama_llm -- Controls randomness (0.0-2.0, higher = more creative)
+# OLLAMA_LLM_TEMPERATURE=0.8
+
+# ollama_llm -- Top-k sampling parameter (0 = disabled)
+# OLLAMA_LLM_TOP_K=40
+
+# ollama_llm -- Top-p (nucleus) sampling parameter (0.0-1.0)
+# OLLAMA_LLM_TOP_P=0.9
+
+# ollama_llm -- Tail free sampling parameter (1.0 = disabled)
+# OLLAMA_LLM_TFS_Z=1.0
+
+# ollama_llm -- Typical probability mass (1.0 = disabled)
+# OLLAMA_LLM_TYPICAL_P=1.0
+
+# ollama_llm -- Minimum probability threshold (0.0 = disabled)
+# OLLAMA_LLM_MIN_P=0.0
+
+# ollama_llm -- Number of tokens to consider for repetition penalty
+# OLLAMA_LLM_REPEAT_LAST_N=64
+
+# ollama_llm -- Penalty for repetition (1.0 = no penalty)
+# OLLAMA_LLM_REPEAT_PENALTY=1.1
+
+# ollama_llm -- Penalty for token presence (-2.0 to 2.0)
+# OLLAMA_LLM_PRESENCE_PENALTY=0.0
+
+# ollama_llm -- Penalty for token frequency (-2.0 to 2.0)
+# OLLAMA_LLM_FREQUENCY_PENALTY=0.0
+
+# ollama_llm -- Mirostat sampling algorithm (0=disabled, 1=Mirostat 1.0, 2=Mirostat 2.0)
+# OLLAMA_LLM_MIROSTAT=0
+
+# ollama_llm -- Mirostat target entropy
+# OLLAMA_LLM_MIROSTAT_TAU=5.0
+
+# ollama_llm -- Mirostat learning rate
+# OLLAMA_LLM_MIROSTAT_ETA=0.1
+
+# ollama_llm -- Enable NUMA optimization
+# OLLAMA_LLM_NUMA=False
+
+# ollama_llm -- Batch size for processing
+# OLLAMA_LLM_NUM_BATCH=512
+
+# ollama_llm -- Number of GPUs to use (-1 for auto)
+# OLLAMA_LLM_NUM_GPU=-1
+
+# ollama_llm -- Main GPU index
+# OLLAMA_LLM_MAIN_GPU=0
+
+# ollama_llm -- Optimize for low VRAM
+# OLLAMA_LLM_LOW_VRAM=False
+
+# ollama_llm -- Number of CPU threads (0 for auto)
+# OLLAMA_LLM_NUM_THREAD=0
+
+# ollama_llm -- Use half-precision for key/value cache
+# OLLAMA_LLM_F16_KV=True
+
+# ollama_llm -- Return logits for all tokens
+# OLLAMA_LLM_LOGITS_ALL=False
+
+# ollama_llm -- Only load vocabulary
+# OLLAMA_LLM_VOCAB_ONLY=False
+
+# ollama_llm -- Use memory mapping for model files
+# OLLAMA_LLM_USE_MMAP=True
+
+# ollama_llm -- Lock model in memory
+# OLLAMA_LLM_USE_MLOCK=False
+
+# ollama_llm -- Only use for embeddings
+# OLLAMA_LLM_EMBEDDING_ONLY=False
+
+# ollama_llm -- Penalize newline tokens
+# OLLAMA_LLM_PENALIZE_NEWLINE=True
+
+# ollama_llm -- Stop sequences (comma-separated string)
+# OLLAMA_LLM_STOP=
+
+#
+# End of .env entries for LightRAG binding options
+################################################################################

LightRAG/k8s-deploy/README-zh.md

@@ -0,0 +1,191 @@
+# LightRAG Helm Chart
+
+这是用于在Kubernetes集群上部署LightRAG服务的Helm chart。
+
+LightRAG有两种推荐的部署方法：
+1. **轻量级部署**：使用内置轻量级存储，适合测试和小规模使用
+2. **生产环境部署**：使用外部数据库（如PostgreSQL和Neo4J），适合生产环境和大规模使用
+
+> 如果您想要部署过程的视频演示，可以查看[bilibili](https://www.bilibili.com/video/BV1bUJazBEq2/)上的视频教程，对于喜欢视觉指导的用户可能会有所帮助。
+
+## 前提条件
+
+确保安装和配置了以下工具：
+
+* **Kubernetes集群**
+  * 需要一个运行中的Kubernetes集群。
+  * 对于本地开发或演示，可以使用[Minikube](https://minikube.sigs.k8s.io/docs/start/)（需要≥2个CPU，≥4GB内存，以及Docker/VM驱动支持）。
+  * 任何标准的云端或本地Kubernetes集群（EKS、GKE、AKS等）也可以使用。
+
+* **kubectl**
+  * Kubernetes命令行工具，用于管理集群。
+  * 按照官方指南安装：[安装和设置kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl)。
+
+* **Helm**（v3.x+）
+  * Kubernetes包管理器，用于安装LightRAG。
+  * 通过官方指南安装：[安装Helm](https://helm.sh/docs/intro/install/)。
+
+## 轻量级部署（无需外部数据库）
+
+这种部署选项使用内置的轻量级存储组件，非常适合测试、演示或小规模使用场景。无需外部数据库配置。
+
+您可以使用提供的便捷脚本或直接使用Helm命令部署LightRAG。两种方法都配置了`lightrag/values.yaml`文件中定义的相同环境变量。
+
+### 使用便捷脚本（推荐）：
+
+```bash
+export OPENAI_API_BASE=<您的OPENAI_API_BASE>
+export OPENAI_API_KEY=<您的OPENAI_API_KEY>
+bash ./install_lightrag_dev.sh
+```
+
+### 或直接使用Helm：
+
+```bash
+# 您可以覆盖任何想要的环境参数
+helm upgrade --install lightrag ./lightrag \
+  --namespace rag \
+  --set-string env.LIGHTRAG_KV_STORAGE=JsonKVStorage \
+  --set-string env.LIGHTRAG_VECTOR_STORAGE=NanoVectorDBStorage \
+  --set-string env.LIGHTRAG_GRAPH_STORAGE=NetworkXStorage \
+  --set-string env.LIGHTRAG_DOC_STATUS_STORAGE=JsonDocStatusStorage \
+  --set-string env.LLM_BINDING=openai \
+  --set-string env.LLM_MODEL=gpt-4o-mini \
+  --set-string env.LLM_BINDING_HOST=$OPENAI_API_BASE \
+  --set-string env.LLM_BINDING_API_KEY=$OPENAI_API_KEY \
+  --set-string env.EMBEDDING_BINDING=openai \
+  --set-string env.EMBEDDING_MODEL=text-embedding-ada-002 \
+  --set-string env.EMBEDDING_DIM=1536 \
+  --set-string env.EMBEDDING_BINDING_API_KEY=$OPENAI_API_KEY
+```
+
+### 访问应用程序：
+
+```bash
+# 1. 在终端中运行此端口转发命令：
+kubectl --namespace rag port-forward svc/lightrag-dev 9621:9621
+
+# 2. 当命令运行时，打开浏览器并导航到：
+# http://localhost:9621
+```
+
+## 生产环境部署（使用外部数据库）
+
+### 1. 安装数据库
+> 如果您已经准备好了数据库，可以跳过此步骤。详细信息可以在：[README.md](databases%2FREADME.md)中找到。
+
+我们推荐使用KubeBlocks进行数据库部署。KubeBlocks是一个云原生数据库操作符，可以轻松地在Kubernetes上以生产规模运行任何数据库。
+
+首先，安装KubeBlocks和KubeBlocks-Addons（如已安装可跳过）：
+```bash
+bash ./databases/01-prepare.sh
+```
+
+然后安装所需的数据库。默认情况下，这将安装PostgreSQL和Neo4J，但您可以修改[00-config.sh](databases%2F00-config.sh)以根据需要选择不同的数据库：
+```bash
+bash ./databases/02-install-database.sh
+```
+
+验证集群是否正在运行：
+```bash
+kubectl get clusters -n rag
+# 预期输出：
+# NAME            CLUSTER-DEFINITION   TERMINATION-POLICY   STATUS     AGE
+# neo4j-cluster                        Delete               Running    39s
+# pg-cluster      postgresql           Delete               Running    42s
+
+kubectl get po -n rag
+# 预期输出：
+# NAME                      READY   STATUS    RESTARTS   AGE
+# neo4j-cluster-neo4j-0     1/1     Running   0          58s
+# pg-cluster-postgresql-0   4/4     Running   0          59s
+# pg-cluster-postgresql-1   4/4     Running   0          59s
+```
+
+### 2. 安装LightRAG
+
+LightRAG及其数据库部署在同一Kubernetes集群中，使配置变得简单。
+安装脚本会自动从KubeBlocks获取所有数据库连接信息，无需手动设置数据库凭证：
+
+```bash
+export OPENAI_API_BASE=<您的OPENAI_API_BASE>
+export OPENAI_API_KEY=<您的OPENAI_API_KEY>
+bash ./install_lightrag.sh
+```
+
+### 访问应用程序：
+
+```bash
+# 1. 在终端中运行此端口转发命令：
+kubectl --namespace rag port-forward svc/lightrag 9621:9621
+
+# 2. 当命令运行时，打开浏览器并导航到：
+# http://localhost:9621
+```
+
+## 配置
+
+### 修改资源配置
+
+您可以通过修改`values.yaml`文件来配置LightRAG的资源使用：
+
+```yaml
+replicaCount: 1  # 副本数量，可根据需要增加
+
+resources:
+  limits:
+    cpu: 1000m    # CPU限制，可根据需要调整
+    memory: 2Gi   # 内存限制，可根据需要调整
+  requests:
+    cpu: 500m     # CPU请求，可根据需要调整
+    memory: 1Gi   # 内存请求，可根据需要调整
+```
+
+### 修改持久存储
+
+```yaml
+persistence:
+  enabled: true
+  ragStorage:
+    size: 10Gi    # RAG存储大小，可根据需要调整
+  inputs:
+    size: 5Gi     # 输入数据存储大小，可根据需要调整
+```
+
+### 配置环境变量
+
+`values.yaml`文件中的`env`部分包含LightRAG的所有环境配置，类似于`.env`文件。当使用helm upgrade或helm install命令时，可以使用--set标志覆盖这些变量。
+
+```yaml
+env:
+  HOST: 0.0.0.0
+  PORT: 9621
+  WEBUI_TITLE: Graph RAG Engine
+  WEBUI_DESCRIPTION: Simple and Fast Graph Based RAG System
+
+  # LLM配置
+  LLM_BINDING: openai            # LLM服务提供商
+  LLM_MODEL: gpt-4o-mini         # LLM模型
+  LLM_BINDING_HOST:              # API基础URL（可选）
+  LLM_BINDING_API_KEY:           # API密钥
+
+  # 嵌入配置
+  EMBEDDING_BINDING: openai                 # 嵌入服务提供商
+  EMBEDDING_MODEL: text-embedding-ada-002   # 嵌入模型
+  EMBEDDING_DIM: 1536                       # 嵌入维度
+  EMBEDDING_BINDING_API_KEY:                # API密钥
+
+  # 存储配置
+  LIGHTRAG_KV_STORAGE: PGKVStorage              # 键值存储类型
+  LIGHTRAG_VECTOR_STORAGE: PGVectorStorage      # 向量存储类型
+  LIGHTRAG_GRAPH_STORAGE: Neo4JStorage          # 图存储类型
+  LIGHTRAG_DOC_STATUS_STORAGE: PGDocStatusStorage  # 文档状态存储类型
+```
+
+## 注意事项
+
+- 在部署前确保设置了所有必要的环境变量（API密钥和数据库密码）
+- 出于安全原因，建议使用环境变量传递敏感信息，而不是直接写入脚本或values文件
+- 轻量级部署适合测试和小规模使用，但数据持久性和性能可能有限
+- 生产环境部署（PostgreSQL + Neo4J）推荐用于生产环境和大规模使用
+- 有关更多自定义配置，请参考LightRAG官方文档

LightRAG/k8s-deploy/README.md

@@ -0,0 +1,191 @@
+# LightRAG Helm Chart
+
+This is the Helm chart for LightRAG, used to deploy LightRAG services on a Kubernetes cluster.
+
+There are two recommended deployment methods for LightRAG:
+1. **Lightweight Deployment**: Using built-in lightweight storage, suitable for testing and small-scale usage
+2. **Production Deployment**: Using external databases (such as PostgreSQL and Neo4J), suitable for production environments and large-scale usage
+
+> If you'd like a video walkthrough of the deployment process, feel free to check out this optional [video tutorial](https://youtu.be/JW1z7fzeKTw?si=vPzukqqwmdzq9Q4q) on YouTube. It might help clarify some steps for those who prefer visual guidance.
+
+## Prerequisites
+
+Make sure the following tools are installed and configured:
+
+* **Kubernetes cluster**
+  * A running Kubernetes cluster is required.
+  * For local development or demos you can use [Minikube](https://minikube.sigs.k8s.io/docs/start/) (needs ≥ 2 CPUs, ≥ 4 GB RAM, and Docker/VM-driver support).
+  * Any standard cloud or on-premises Kubernetes cluster (EKS, GKE, AKS, etc.) also works.
+
+* **kubectl**
+  * The Kubernetes command-line tool for managing your cluster.
+  * Follow the official guide: [Install and Set Up kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl).
+
+* **Helm** (v3.x+)
+  * Kubernetes package manager used to install LightRAG.
+  * Install it via the official instructions: [Installing Helm](https://helm.sh/docs/intro/install/).
+
+## Lightweight Deployment (No External Databases Required)
+
+This deployment option uses built-in lightweight storage components that are perfect for testing, demos, or small-scale usage scenarios. No external database configuration is required.
+
+You can deploy LightRAG using either the provided convenience script or direct Helm commands. Both methods configure the same environment variables defined in the `lightrag/values.yaml` file.
+
+### Using the convenience script (recommended):
+
+```bash
+export OPENAI_API_BASE=<YOUR_OPENAI_API_BASE>
+export OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>
+bash ./install_lightrag_dev.sh
+```
+
+### Or using Helm directly:
+
+```bash
+# You can override any env param you want
+helm upgrade --install lightrag ./lightrag \
+  --namespace rag \
+  --set-string env.LIGHTRAG_KV_STORAGE=JsonKVStorage \
+  --set-string env.LIGHTRAG_VECTOR_STORAGE=NanoVectorDBStorage \
+  --set-string env.LIGHTRAG_GRAPH_STORAGE=NetworkXStorage \
+  --set-string env.LIGHTRAG_DOC_STATUS_STORAGE=JsonDocStatusStorage \
+  --set-string env.LLM_BINDING=openai \
+  --set-string env.LLM_MODEL=gpt-4o-mini \
+  --set-string env.LLM_BINDING_HOST=$OPENAI_API_BASE \
+  --set-string env.LLM_BINDING_API_KEY=$OPENAI_API_KEY \
+  --set-string env.EMBEDDING_BINDING=openai \
+  --set-string env.EMBEDDING_MODEL=text-embedding-ada-002 \
+  --set-string env.EMBEDDING_DIM=1536 \
+  --set-string env.EMBEDDING_BINDING_API_KEY=$OPENAI_API_KEY
+```
+
+### Accessing the application:
+
+```bash
+# 1. Run this port-forward command in your terminal:
+kubectl --namespace rag port-forward svc/lightrag-dev 9621:9621
+
+# 2. While the command is running, open your browser and navigate to:
+# http://localhost:9621
+```
+
+## Production Deployment (Using External Databases)
+
+### 1. Install Databases
+> You can skip this step if you've already prepared databases. Detailed information can be found in: [README.md](databases%2FREADME.md).
+
+We recommend KubeBlocks for database deployment. KubeBlocks is a cloud-native database operator that makes it easy to run any database on Kubernetes at production scale.
+
+First, install KubeBlocks and KubeBlocks-Addons (skip if already installed):
+```bash
+bash ./databases/01-prepare.sh
+```
+
+Then install the required databases. By default, this will install PostgreSQL and Neo4J, but you can modify [00-config.sh](databases%2F00-config.sh) to select different databases based on your needs:
+```bash
+bash ./databases/02-install-database.sh
+```
+
+Verify that the clusters are up and running:
+```bash
+kubectl get clusters -n rag
+# Expected output:
+# NAME            CLUSTER-DEFINITION   TERMINATION-POLICY   STATUS     AGE
+# neo4j-cluster                        Delete               Running    39s
+# pg-cluster      postgresql           Delete               Running    42s
+
+kubectl get po -n rag
+# Expected output:
+# NAME                      READY   STATUS    RESTARTS   AGE
+# neo4j-cluster-neo4j-0     1/1     Running   0          58s
+# pg-cluster-postgresql-0   4/4     Running   0          59s
+# pg-cluster-postgresql-1   4/4     Running   0          59s
+```
+
+### 2. Install LightRAG
+
+LightRAG and its databases are deployed within the same Kubernetes cluster, making configuration straightforward.
+The installation script automatically retrieves all database connection information from KubeBlocks, eliminating the need to manually set database credentials:
+
+```bash
+export OPENAI_API_BASE=<YOUR_OPENAI_API_BASE>
+export OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>
+bash ./install_lightrag.sh
+```
+
+### Accessing the application:
+
+```bash
+# 1. Run this port-forward command in your terminal:
+kubectl --namespace rag port-forward svc/lightrag 9621:9621
+
+# 2. While the command is running, open your browser and navigate to:
+# http://localhost:9621
+```
+
+## Configuration
+
+### Modifying Resource Configuration
+
+You can configure LightRAG's resource usage by modifying the `values.yaml` file:
+
+```yaml
+replicaCount: 1  # Number of replicas, can be increased as needed
+
+resources:
+  limits:
+    cpu: 1000m    # CPU limit, can be adjusted as needed
+    memory: 2Gi   # Memory limit, can be adjusted as needed
+  requests:
+    cpu: 500m     # CPU request, can be adjusted as needed
+    memory: 1Gi   # Memory request, can be adjusted as needed
+```
+
+### Modifying Persistent Storage
+
+```yaml
+persistence:
+  enabled: true
+  ragStorage:
+    size: 10Gi    # RAG storage size, can be adjusted as needed
+  inputs:
+    size: 5Gi     # Input data storage size, can be adjusted as needed
+```
+
+### Configuring Environment Variables
+
+The `env` section in the `values.yaml` file contains all environment configurations for LightRAG, similar to a `.env` file. When using helm upgrade or helm install commands, you can override these with the --set flag.
+
+```yaml
+env:
+  HOST: 0.0.0.0
+  PORT: 9621
+  WEBUI_TITLE: Graph RAG Engine
+  WEBUI_DESCRIPTION: Simple and Fast Graph Based RAG System
+
+  # LLM Configuration
+  LLM_BINDING: openai            # LLM service provider
+  LLM_MODEL: gpt-4o-mini         # LLM model
+  LLM_BINDING_HOST:              # API base URL (optional)
+  LLM_BINDING_API_KEY:           # API key
+
+  # Embedding Configuration
+  EMBEDDING_BINDING: openai                 # Embedding service provider
+  EMBEDDING_MODEL: text-embedding-ada-002   # Embedding model
+  EMBEDDING_DIM: 1536                       # Embedding dimension
+  EMBEDDING_BINDING_API_KEY:                # API key
+
+  # Storage Configuration
+  LIGHTRAG_KV_STORAGE: PGKVStorage              # Key-value storage type
+  LIGHTRAG_VECTOR_STORAGE: PGVectorStorage      # Vector storage type
+  LIGHTRAG_GRAPH_STORAGE: Neo4JStorage          # Graph storage type
+  LIGHTRAG_DOC_STATUS_STORAGE: PGDocStatusStorage  # Document status storage type
+```
+
+## Notes
+
+- Ensure all necessary environment variables (API keys and database passwords) are set before deployment
+- For security reasons, it's recommended to pass sensitive information using environment variables rather than writing them directly in scripts or values files
+- Lightweight deployment is suitable for testing and small-scale usage, but data persistence and performance may be limited
+- Production deployment (PostgreSQL + Neo4J) is recommended for production environments and large-scale usage
+- For more customized configurations, please refer to the official LightRAG documentation

LightRAG/k8s-deploy/databases/00-config.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+
+# Get the directory where this script is located
+DATABASE_SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
+source "$DATABASE_SCRIPT_DIR/scripts/common.sh"
+
+# Namespace configuration
+NAMESPACE="rag"
+# version
+KB_VERSION="1.0.0-beta.48"
+ADDON_CLUSTER_CHART_VERSION="1.0.0-alpha.0"
+# Helm repository
+HELM_REPO="https://apecloud.github.io/helm-charts"
+
+# Set to true to enable the database, false to disable
+ENABLE_POSTGRESQL=true
+ENABLE_REDIS=false
+ENABLE_QDRANT=false
+ENABLE_NEO4J=true
+ENABLE_ELASTICSEARCH=false
+ENABLE_MONGODB=false

LightRAG/k8s-deploy/databases/01-prepare.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+
+# Get the directory where this script is located
+DATABASE_SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
+# Load configuration file
+source "$DATABASE_SCRIPT_DIR/00-config.sh"
+
+check_dependencies
+
+# Check if KubeBlocks is already installed, install it if it is not.
+source "$DATABASE_SCRIPT_DIR/install-kubeblocks.sh"
+
+# Create namespaces
+print "Creating namespaces..."
+kubectl create namespace $NAMESPACE 2>/dev/null || true
+
+# Install database addons
+print "Installing KubeBlocks database addons..."
+
+# Add and update Helm repository
+print "Adding and updating KubeBlocks Helm repository..."
+helm repo add kubeblocks $HELM_REPO
+helm repo update
+# Install database addons based on configuration
+[ "$ENABLE_POSTGRESQL" = true ] && print "Installing PostgreSQL addon..." && helm upgrade --install kb-addon-postgresql kubeblocks/postgresql --namespace kb-system --version $ADDON_CLUSTER_CHART_VERSION
+[ "$ENABLE_REDIS" = true ] && print "Installing Redis addon..." && helm upgrade --install kb-addon-redis kubeblocks/redis --namespace kb-system --version $ADDON_CLUSTER_CHART_VERSION
+[ "$ENABLE_ELASTICSEARCH" = true ] && print "Installing Elasticsearch addon..." && helm upgrade --install kb-addon-elasticsearch kubeblocks/elasticsearch --namespace kb-system --version $ADDON_CLUSTER_CHART_VERSION
+[ "$ENABLE_QDRANT" = true ] && print "Installing Qdrant addon..." && helm upgrade --install kb-addon-qdrant kubeblocks/qdrant --namespace kb-system --version $ADDON_CLUSTER_CHART_VERSION
+[ "$ENABLE_MONGODB" = true ] && print "Installing MongoDB addon..." && helm upgrade --install kb-addon-mongodb kubeblocks/mongodb --namespace kb-system --version $ADDON_CLUSTER_CHART_VERSION
+[ "$ENABLE_NEO4J" = true ] && print "Installing Neo4j addon..." && helm upgrade --install kb-addon-neo4j kubeblocks/neo4j --namespace kb-system --version $ADDON_CLUSTER_CHART_VERSION
+
+print_success "KubeBlocks database addons installation completed!"
+print "Now you can run 02-install-database.sh to install database clusters"

LightRAG/k8s-deploy/databases/02-install-database.sh

@@ -0,0 +1,62 @@
+#!/bin/bash
+
+# Get the directory where this script is located
+DATABASE_SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
+
+# Load configuration file
+source "$DATABASE_SCRIPT_DIR/00-config.sh"
+
+print "Installing database clusters..."
+
+# Install database clusters based on configuration
+[ "$ENABLE_POSTGRESQL" = true ] && print "Installing PostgreSQL cluster..." && helm upgrade --install pg-cluster kubeblocks/postgresql-cluster -f "$DATABASE_SCRIPT_DIR/postgresql/values.yaml" --namespace $NAMESPACE --version $ADDON_CLUSTER_CHART_VERSION
+[ "$ENABLE_REDIS" = true ] && print "Installing Redis cluster..." && helm upgrade --install redis-cluster kubeblocks/redis-cluster -f "$DATABASE_SCRIPT_DIR/redis/values.yaml" --namespace $NAMESPACE --version $ADDON_CLUSTER_CHART_VERSION
+[ "$ENABLE_ELASTICSEARCH" = true ] && print "Installing Elasticsearch cluster..." && helm upgrade --install es-cluster kubeblocks/elasticsearch-cluster -f "$DATABASE_SCRIPT_DIR/elasticsearch/values.yaml" --namespace $NAMESPACE --version $ADDON_CLUSTER_CHART_VERSION
+[ "$ENABLE_QDRANT" = true ] && print "Installing Qdrant cluster..." && helm upgrade --install qdrant-cluster kubeblocks/qdrant-cluster -f "$DATABASE_SCRIPT_DIR/qdrant/values.yaml" --namespace $NAMESPACE --version $ADDON_CLUSTER_CHART_VERSION
+[ "$ENABLE_MONGODB" = true ] && print "Installing MongoDB cluster..." && helm upgrade --install mongodb-cluster kubeblocks/mongodb-cluster -f "$DATABASE_SCRIPT_DIR/mongodb/values.yaml" --namespace $NAMESPACE --version $ADDON_CLUSTER_CHART_VERSION
+[ "$ENABLE_NEO4J" = true ] && print "Installing Neo4j cluster..." && helm upgrade --install neo4j-cluster kubeblocks/neo4j-cluster -f "$DATABASE_SCRIPT_DIR/neo4j/values.yaml" --namespace $NAMESPACE --version $ADDON_CLUSTER_CHART_VERSION
+
+# Wait for databases to be ready
+print "Waiting for databases to be ready..."
+TIMEOUT=600  # Set timeout to 10 minutes
+START_TIME=$(date +%s)
+
+while true; do
+  CURRENT_TIME=$(date +%s)
+  ELAPSED=$((CURRENT_TIME - START_TIME))
+
+  if [ $ELAPSED -gt $TIMEOUT ]; then
+    print_error "Timeout waiting for databases to be ready. Please check database status manually and try again"
+    exit 1
+  fi
+
+  # Build wait conditions for enabled databases
+  WAIT_CONDITIONS=()
+  [ "$ENABLE_POSTGRESQL" = true ] && WAIT_CONDITIONS+=("kubectl wait --for=condition=ready pods -l app.kubernetes.io/instance=pg-cluster -n $NAMESPACE --timeout=10s")
+  [ "$ENABLE_REDIS" = true ] && WAIT_CONDITIONS+=("kubectl wait --for=condition=ready pods -l app.kubernetes.io/instance=redis-cluster -n $NAMESPACE --timeout=10s")
+  [ "$ENABLE_ELASTICSEARCH" = true ] && WAIT_CONDITIONS+=("kubectl wait --for=condition=ready pods -l app.kubernetes.io/instance=es-cluster -n $NAMESPACE --timeout=10s")
+  [ "$ENABLE_QDRANT" = true ] && WAIT_CONDITIONS+=("kubectl wait --for=condition=ready pods -l app.kubernetes.io/instance=qdrant-cluster -n $NAMESPACE --timeout=10s")
+  [ "$ENABLE_MONGODB" = true ] && WAIT_CONDITIONS+=("kubectl wait --for=condition=ready pods -l app.kubernetes.io/instance=mongodb-cluster -n $NAMESPACE --timeout=10s")
+  [ "$ENABLE_NEO4J" = true ] && WAIT_CONDITIONS+=("kubectl wait --for=condition=ready pods -l app.kubernetes.io/instance=neo4j-cluster -n $NAMESPACE --timeout=10s")
+
+  # Check if all enabled databases are ready
+  ALL_READY=true
+  for CONDITION in "${WAIT_CONDITIONS[@]}"; do
+    if ! eval "$CONDITION &> /dev/null"; then
+      ALL_READY=false
+      break
+    fi
+  done
+
+  if [ "$ALL_READY" = true ]; then
+    print "All database pods are ready, continuing with deployment..."
+    break
+  fi
+
+  print "Waiting for database pods to be ready (${ELAPSED}s elapsed)..."
+  sleep 10
+done
+
+print_success "Database clusters installation completed!"
+print "Use the following command to check the status of installed clusters:"
+print "kubectl get clusters -n $NAMESPACE"

LightRAG/k8s-deploy/databases/03-uninstall-database.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+
+# Get the directory where this script is located
+DATABASE_SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
+
+# Load configuration file
+source "$DATABASE_SCRIPT_DIR/00-config.sh"
+
+print "Uninstalling database clusters..."
+
+# Uninstall database clusters based on configuration
+[ "$ENABLE_POSTGRESQL" = true ] && print "Uninstalling PostgreSQL cluster..." && helm uninstall pg-cluster --namespace $NAMESPACE 2>/dev/null || true
+[ "$ENABLE_REDIS" = true ] && print "Uninstalling Redis cluster..." && helm uninstall redis-cluster --namespace $NAMESPACE 2>/dev/null || true
+[ "$ENABLE_ELASTICSEARCH" = true ] && print "Uninstalling Elasticsearch cluster..." && helm uninstall es-cluster --namespace $NAMESPACE 2>/dev/null || true
+[ "$ENABLE_QDRANT" = true ] && print "Uninstalling Qdrant cluster..." && helm uninstall qdrant-cluster --namespace $NAMESPACE 2>/dev/null || true
+[ "$ENABLE_MONGODB" = true ] && print "Uninstalling MongoDB cluster..." && helm uninstall mongodb-cluster --namespace $NAMESPACE 2>/dev/null || true
+[ "$ENABLE_NEO4J" = true ] && print "Uninstalling Neo4j cluster..." && helm uninstall neo4j-cluster --namespace $NAMESPACE 2>/dev/null || true
+
+print_success "Database clusters uninstalled"
+print "To uninstall database addons and KubeBlocks, run 04-cleanup.sh"

LightRAG/k8s-deploy/databases/04-cleanup.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+
+# Get the directory where this script is located
+DATABASE_SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
+
+# Load configuration file
+source "$DATABASE_SCRIPT_DIR/00-config.sh"
+
+print "Uninstalling KubeBlocks database addons..."
+
+# Uninstall database addons based on configuration
+[ "$ENABLE_POSTGRESQL" = true ] && print "Uninstalling PostgreSQL addon..." && helm uninstall kb-addon-postgresql --namespace kb-system 2>/dev/null || true
+[ "$ENABLE_REDIS" = true ] && print "Uninstalling Redis addon..." && helm uninstall kb-addon-redis --namespace kb-system 2>/dev/null || true
+[ "$ENABLE_ELASTICSEARCH" = true ] && print "Uninstalling Elasticsearch addon..." && helm uninstall kb-addon-elasticsearch --namespace kb-system 2>/dev/null || true
+[ "$ENABLE_QDRANT" = true ] && print "Uninstalling Qdrant addon..." && helm uninstall kb-addon-qdrant --namespace kb-system 2>/dev/null || true
+[ "$ENABLE_MONGODB" = true ] && print "Uninstalling MongoDB addon..." && helm uninstall kb-addon-mongodb --namespace kb-system 2>/dev/null || true
+[ "$ENABLE_NEO4J" = true ] && print "Uninstalling Neo4j addon..." && helm uninstall kb-addon-neo4j --namespace kb-system 2>/dev/null || true
+
+print_success "Database addons uninstallation completed!"
+
+source "$DATABASE_SCRIPT_DIR/uninstall-kubeblocks.sh"
+
+kubectl delete namespace $NAMESPACE
+kubectl delete namespace kb-system
+
+print_success "KubeBlocks uninstallation completed!"

LightRAG/k8s-deploy/databases/install-kubeblocks.sh

@@ -0,0 +1,52 @@
+#!/bin/bash
+
+# Get the directory where this script is located
+DATABASE_SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
+# Load configuration file
+source "$DATABASE_SCRIPT_DIR/00-config.sh"
+
+# Check dependencies
+check_dependencies
+
+# Function for installing KubeBlocks
+install_kubeblocks() {
+    print "Ready to install KubeBlocks."
+
+    # Install CSI Snapshotter CRDs
+    kubectl create -f https://raw.githubusercontent.com/kubernetes-csi/external-snapshotter/v8.2.0/client/config/crd/snapshot.storage.k8s.io_volumesnapshotclasses.yaml
+    kubectl create -f https://raw.githubusercontent.com/kubernetes-csi/external-snapshotter/v8.2.0/client/config/crd/snapshot.storage.k8s.io_volumesnapshots.yaml
+    kubectl create -f https://raw.githubusercontent.com/kubernetes-csi/external-snapshotter/v8.2.0/client/config/crd/snapshot.storage.k8s.io_volumesnapshotcontents.yaml
+
+    # Add and update Piraeus repository
+    helm repo add piraeus-charts https://piraeus.io/helm-charts/
+    helm repo update
+
+    # Install snapshot controller
+    helm install snapshot-controller piraeus-charts/snapshot-controller -n kb-system --create-namespace
+    kubectl wait --for=condition=ready pods -l app.kubernetes.io/name=snapshot-controller -n kb-system --timeout=60s
+    print_success "snapshot-controller installation complete!"
+
+    # Install KubeBlocks CRDs
+    kubectl create -f https://github.com/apecloud/kubeblocks/releases/download/v${KB_VERSION}/kubeblocks_crds.yaml
+
+    # Add and update KubeBlocks repository
+    helm repo add kubeblocks $HELM_REPO
+    helm repo update
+
+    # Install KubeBlocks
+    helm install kubeblocks kubeblocks/kubeblocks --namespace kb-system --create-namespace --version=${KB_VERSION}
+
+    # Verify installation
+    print "Waiting for KubeBlocks to be ready..."
+    kubectl wait --for=condition=ready pods -l app.kubernetes.io/instance=kubeblocks -n kb-system --timeout=120s
+    print_success "KubeBlocks installation complete!"
+}
+
+# Check if KubeBlocks is already installed
+print "Checking if KubeBlocks is already installed in kb-system namespace..."
+if kubectl get namespace kb-system &>/dev/null && kubectl get deployment kubeblocks -n kb-system &>/dev/null; then
+    print_success "KubeBlocks is already installed in kb-system namespace."
+else
+    # Call the function to install KubeBlocks
+    install_kubeblocks
+fi

LightRAG/k8s-deploy/databases/postgresql/values.yaml

@@ -0,0 +1,33 @@
+## description: service version.
+## default: 15.7.0
+version: 16.4.0
+
+## mode postgresql cluster topology mode replication
+mode: replication
+
+## description: The number of replicas, for standalone mode, the replicas is 1, for replication mode, the default replicas is 2.
+## default: 1
+## minimum: 1
+## maximum: 5
+replicas: 2
+
+## description: CPU cores.
+## default: 0.5
+## minimum: 0.5
+## maximum: 64
+cpu: 1
+
+## description: Memory, the unit is Gi.
+## default: 0.5
+## minimum: 0.5
+## maximum: 1000
+memory: 1
+
+## description: Storage size, the unit is Gi.
+## default: 20
+## minimum: 1
+## maximum: 10000
+storage: 5
+
+## terminationPolicy define Cluster termination policy. One of DoNotTerminate, Delete, WipeOut.
+terminationPolicy: Delete

LightRAG/k8s-deploy/install_lightrag.sh

@@ -0,0 +1,95 @@
+#!/bin/bash
+
+NAMESPACE=rag
+
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
+
+if [ -z "$OPENAI_API_KEY" ]; then
+  echo "OPENAI_API_KEY environment variable is not set"
+  read -s -p "Enter your OpenAI API key: " OPENAI_API_KEY
+  if [ -z "$OPENAI_API_KEY" ]; then
+    echo "Error: OPENAI_API_KEY must be provided"
+    exit 1
+  fi
+  export OPENAI_API_KEY=$OPENAI_API_KEY
+fi
+
+if [ -z "$OPENAI_API_BASE" ]; then
+  echo "OPENAI_API_BASE environment variable is not set, will use default value"
+  read -p "Enter OpenAI API base URL (press Enter to skip if not needed): " OPENAI_API_BASE
+  export OPENAI_API_BASE=$OPENAI_API_BASE
+fi
+
+# Install KubeBlocks (if not already installed)
+bash "$SCRIPT_DIR/databases/01-prepare.sh"
+
+# Install database clusters
+bash "$SCRIPT_DIR/databases/02-install-database.sh"
+
+# Create vector extension in PostgreSQL if enabled
+print "Waiting for PostgreSQL pods to be ready..."
+if kubectl wait --for=condition=ready pods -l kubeblocks.io/role=primary,app.kubernetes.io/instance=pg-cluster -n $NAMESPACE --timeout=300s; then
+    print "Creating vector extension in PostgreSQL..."
+    kubectl exec -it $(kubectl get pods -l kubeblocks.io/role=primary,app.kubernetes.io/instance=pg-cluster -n $NAMESPACE -o name) -n $NAMESPACE -- psql -c "CREATE EXTENSION vector;"
+    print_success "Vector extension created successfully."
+else
+    print "Warning: PostgreSQL pods not ready within timeout. Vector extension not created."
+fi
+
+# Get database passwords from Kubernetes secrets
+echo "Retrieving database credentials from Kubernetes secrets..."
+POSTGRES_PASSWORD=$(kubectl get secrets -n rag pg-cluster-postgresql-account-postgres -o jsonpath='{.data.password}' | base64 -d)
+if [ -z "$POSTGRES_PASSWORD" ]; then
+  echo "Error: Could not retrieve PostgreSQL password. Make sure PostgreSQL is deployed and the secret exists."
+  exit 1
+fi
+export POSTGRES_PASSWORD=$POSTGRES_PASSWORD
+
+NEO4J_PASSWORD=$(kubectl get secrets -n rag neo4j-cluster-neo4j-account-neo4j -o jsonpath='{.data.password}' | base64 -d)
+if [ -z "$NEO4J_PASSWORD" ]; then
+  echo "Error: Could not retrieve Neo4J password. Make sure Neo4J is deployed and the secret exists."
+  exit 1
+fi
+export NEO4J_PASSWORD=$NEO4J_PASSWORD
+
+#REDIS_PASSWORD=$(kubectl get secrets -n rag redis-cluster-redis-account-default -o jsonpath='{.data.password}' | base64 -d)
+#if [ -z "$REDIS_PASSWORD" ]; then
+#  echo "Error: Could not retrieve Redis password. Make sure Redis is deployed and the secret exists."
+#  exit 1
+#fi
+#export REDIS_PASSWORD=$REDIS_PASSWORD
+
+echo "Deploying production LightRAG (using external databases)..."
+
+if ! kubectl get namespace rag &> /dev/null; then
+  echo "creating namespace 'rag'..."
+  kubectl create namespace rag
+fi
+
+helm upgrade --install lightrag $SCRIPT_DIR/lightrag \
+  --namespace $NAMESPACE \
+  --set-string env.POSTGRES_PASSWORD=$POSTGRES_PASSWORD \
+  --set-string env.NEO4J_PASSWORD=$NEO4J_PASSWORD \
+  --set-string env.LLM_BINDING=openai \
+  --set-string env.LLM_MODEL=gpt-4o-mini \
+  --set-string env.LLM_BINDING_HOST=$OPENAI_API_BASE \
+  --set-string env.LLM_BINDING_API_KEY=$OPENAI_API_KEY \
+  --set-string env.EMBEDDING_BINDING=openai \
+  --set-string env.EMBEDDING_MODEL=text-embedding-ada-002 \
+  --set-string env.EMBEDDING_DIM=1536 \
+  --set-string env.EMBEDDING_BINDING_API_KEY=$OPENAI_API_KEY
+#  --set-string env.REDIS_URI="redis://default:${REDIS_PASSWORD}@redis-cluster-redis-redis:6379"
+
+# Wait for LightRAG pod to be ready
+echo ""
+echo "Waiting for lightrag pod to be ready..."
+kubectl wait --for=condition=ready pod -l app.kubernetes.io/instance=lightrag --timeout=300s -n rag
+echo "lightrag pod is ready"
+echo ""
+echo "Running Port-Forward:"
+echo "    kubectl --namespace rag port-forward svc/lightrag 9621:9621"
+echo "==========================================="
+echo ""
+echo "✅ You can visit LightRAG at: http://localhost:9621"
+echo ""
+kubectl --namespace rag port-forward svc/lightrag 9621:9621

LightRAG/k8s-deploy/install_lightrag_dev.sh

@@ -0,0 +1,81 @@
+#!/bin/bash
+
+NAMESPACE=rag
+
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
+
+check_dependencies(){
+  echo "Checking dependencies..."
+  command -v kubectl >/dev/null 2>&1 || { echo "Error: kubectl command not found"; exit 1; }
+  command -v helm >/dev/null 2>&1 || { echo "Error: helm command not found"; exit 1; }
+
+  # Check if Kubernetes is available
+  echo "Checking if Kubernetes is available..."
+  kubectl cluster-info &>/dev/null
+  if [ $? -ne 0 ]; then
+      echo "Error: Kubernetes cluster is not accessible. Please ensure you have proper access to a Kubernetes cluster."
+      exit 1
+  fi
+  echo "Kubernetes cluster is accessible."
+}
+
+check_dependencies
+
+if [ -z "$OPENAI_API_KEY" ]; then
+  echo "OPENAI_API_KEY environment variable is not set"
+  read -s -p "Enter your OpenAI API key: " OPENAI_API_KEY
+  if [ -z "$OPENAI_API_KEY" ]; then
+    echo "Error: OPENAI_API_KEY must be provided"
+    exit 1
+  fi
+  export OPENAI_API_KEY=$OPENAI_API_KEY
+fi
+
+if [ -z "$OPENAI_API_BASE" ]; then
+  echo "OPENAI_API_BASE environment variable is not set, will use default value"
+  read -p "Enter OpenAI API base URL (press Enter to skip if not needed): " OPENAI_API_BASE
+  export OPENAI_API_BASE=$OPENAI_API_BASE
+fi
+
+required_env_vars=("OPENAI_API_BASE" "OPENAI_API_KEY")
+
+for var in "${required_env_vars[@]}"; do
+  if [ -z "${!var}" ]; then
+    echo "Error: $var environment variable is not set"
+    exit 1
+  fi
+done
+
+if ! kubectl get namespace rag &> /dev/null; then
+  echo "creating namespace 'rag'..."
+  kubectl create namespace rag
+fi
+
+helm upgrade --install lightrag-dev $SCRIPT_DIR/lightrag \
+  --namespace rag \
+  --set-string env.LIGHTRAG_KV_STORAGE=JsonKVStorage \
+  --set-string env.LIGHTRAG_VECTOR_STORAGE=NanoVectorDBStorage \
+  --set-string env.LIGHTRAG_GRAPH_STORAGE=NetworkXStorage \
+  --set-string env.LIGHTRAG_DOC_STATUS_STORAGE=JsonDocStatusStorage \
+  --set-string env.LLM_BINDING=openai \
+  --set-string env.LLM_MODEL=gpt-4o-mini \
+  --set-string env.LLM_BINDING_HOST=$OPENAI_API_BASE \
+  --set-string env.LLM_BINDING_API_KEY=$OPENAI_API_KEY \
+  --set-string env.EMBEDDING_BINDING=openai \
+  --set-string env.EMBEDDING_MODEL=text-embedding-ada-002 \
+  --set-string env.EMBEDDING_DIM=1536 \
+  --set-string env.EMBEDDING_BINDING_API_KEY=$OPENAI_API_KEY
+
+# Wait for LightRAG pod to be ready
+echo ""
+echo "Waiting for lightrag-dev pod to be ready..."
+kubectl wait --for=condition=ready pod -l app.kubernetes.io/instance=lightrag-dev --timeout=300s -n rag
+echo "lightrag-dev pod is ready"
+echo ""
+echo "Running Port-Forward:"
+echo "    kubectl --namespace rag port-forward svc/lightrag-dev 9621:9621"
+echo "==========================================="
+echo ""
+echo "✅ You can visit LightRAG at: http://localhost:9621"
+echo ""
+kubectl --namespace rag port-forward svc/lightrag-dev 9621:9621

LightRAG/k8s-deploy/uninstall_lightrag.sh

@@ -0,0 +1,4 @@
+#!/bin/bash
+
+NAMESPACE=rag
+helm uninstall lightrag --namespace $NAMESPACE

LightRAG/k8s-deploy/uninstall_lightrag_dev.sh

@@ -0,0 +1,4 @@
+#!/bin/bash
+
+NAMESPACE=rag
+helm uninstall lightrag-dev --namespace $NAMESPACE

LightRAG/lightrag-api

@@ -0,0 +1,4 @@
+#!/bin/bash
+
+source /home/netman/lightrag-xyj/venv/bin/activate
+lightrag-server

LightRAG/lightrag.service.example

@@ -0,0 +1,17 @@
+[Unit]
+Description=LightRAG XYJ Ollama Service
+After=network.target
+
+[Service]
+Type=simple
+User=netman
+# Memory settings
+MemoryHigh=8G
+MemoryMax=12G
+WorkingDirectory=/home/netman/lightrag-xyj
+ExecStart=/home/netman/lightrag-xyj/lightrag-api
+Restart=always
+RestartSec=10
+
+[Install]
+WantedBy=multi-user.target

LightRAG/paging.md

@@ -0,0 +1,251 @@
+# 文档列表页面分页显示功能改造方案
+
+## 一、改造目标
+
+### 问题现状
+- 当前文档页面一次性加载所有文档，导致大量文档时界面加载慢
+- 前端内存占用过大，用户操作体验差
+- 状态过滤和排序都在前端进行，效率低下
+
+### 改造目标
+- 实现后端分页查询，减少单次数据传输量
+- 添加分页控制组件，支持翻页和跳转功能
+- 允许用户设置每页显示行数（10-200条）
+- 保持现有状态过滤和排序功能不变
+- 提升大数据量场景下的性能表现
+
+## 二、总体架构设计
+
+### 设计原则
+1. **统一分页接口**：后端提供统一的分页API，支持状态过滤和排序
+2. **智能刷新策略**：根据处理状态选择合适的刷新频率和范围
+3. **即时用户反馈**：状态切换、分页操作提供立即响应
+4. **向后兼容**：保持现有功能完整性，不影响现有操作流程
+5. **性能优化**：减少内存占用，优化网络请求
+
+### 技术方案
+- **后端**：在现有存储层基础上添加分页查询接口
+- **前端**：改造DocumentManager组件，添加分页控制
+- **数据流**：统一分页查询 + 独立状态计数查询
+
+## 三、后端改造步骤
+
+### 步骤1：存储层接口扩展
+
+**改动文件**：`lightrag/kg/base.py`
+
+**关键思路**：
+- 在BaseDocStatusStorage抽象类中添加分页查询方法
+- 设计统一的分页接口，支持状态过滤、排序、分页参数
+- 返回文档列表和总数量的元组
+
+**接口设计要点**：
+```
+get_docs_paginated(status_filter, page, page_size, sort_field, sort_direction) -> (documents, total_count)
+count_by_status(status) -> int
+get_all_status_counts() -> Dict[str, int]
+```
+
+### 步骤2：各存储后端实现
+
+**改动文件**：
+- `lightrag/kg/postgres_impl.py`
+- `lightrag/kg/mongo_impl.py`
+- `lightrag/kg/redis_impl.py`
+- `lightrag/kg/json_doc_status_impl.py`
+
+**PostgreSQL实现要点**：
+- 使用LIMIT和OFFSET实现分页
+- 构建动态WHERE条件支持状态过滤
+- 使用COUNT查询获取总数量
+- 添加合适的数据库索引优化查询性能
+
+**MongoDB实现要点**：
+- 使用skip()和limit()实现分页
+- 使用聚合管道进行状态统计
+- 优化查询条件和索引
+
+**Redis 与 Json实现要点：**
+
+* 考虑先用简单的方式实现，即把所有文件清单读到内存中后进行过滤和排序
+
+**关键考虑**：
+
+- 确保各存储后端的分页逻辑一致性
+- 处理边界情况（空结果、超出页码范围等）
+- 优化查询性能，避免全表扫描
+
+### 步骤3：API路由层改造
+
+**改动文件**：`lightrag/api/routers/document_routes.py`
+
+**新增接口**：
+1. `POST /documents/paginated` - 分页查询文档
+2. `GET /documents/status_counts` - 获取状态计数
+
+**数据模型设计**：
+- DocumentsRequest：分页请求参数
+- PaginatedDocsResponse：分页响应数据
+- PaginationInfo：分页元信息
+
+**关键逻辑**：
+- 参数验证（页码范围、页面大小限制）
+- 并行查询分页数据和状态计数
+- 错误处理和异常响应
+
+### 步骤4：数据库优化
+
+**索引策略**：
+- 为workspace + status + updated_at创建复合索引
+- 为workspace + status + created_at创建复合索引
+- 为workspace + updated_at创建索引
+- 为workspace + created_at创建索引
+
+**性能考虑**：
+- 避免深度分页的性能问题
+- 考虑添加缓存层优化状态计数查询
+- 监控查询性能，必要时调整索引策略
+
+## 四、前端改造步骤
+
+### 步骤1：API客户端扩展
+
+**改动文件**：`lightrag_webui/src/api/lightrag.ts`
+
+**新增函数**：
+- `getDocumentsPaginated()` - 分页查询文档
+- `getDocumentStatusCounts()` - 获取状态计数
+
+**类型定义**：
+- 定义分页请求和响应的TypeScript类型
+- 确保类型安全和代码提示
+
+### 步骤2：分页控制组件开发
+
+**新增文件**：`lightrag_webui/src/components/ui/PaginationControls.tsx`
+
+**组件功能**：
+- 支持紧凑模式和完整模式
+- 页码输入和跳转功能
+- 每页显示数量选择（10-200）
+- 总数信息显示
+- 禁用状态处理
+
+**设计要点**：
+- 响应式设计，适配不同屏幕尺寸
+- 防抖处理，避免频繁请求
+- 错误处理和状态回滚
+- 组件摆放位置：目前状态按钮上方，与scan按钮同一层，居中摆放
+
+### 步骤3：状态过滤按钮优化
+
+**改动文件**：现有状态过滤相关组件
+
+**优化要点**：
+
+- 添加加载状态指示
+- 数据不足时的智能提示
+- 定期刷新数据，状态切换时如果最先的状态数据距离上次刷新数据超过5秒应即时刷新数据
+- 防止重复点击和并发请求
+
+### 步骤4：主组件DocumentManager改造
+
+**改动文件**：`lightrag_webui/src/features/DocumentManager.tsx`
+
+**核心改动**：
+
+**状态管理重构**：
+- 将docs状态改为currentPageDocs（仅存储当前页数据）
+- 添加pagination状态管理分页信息
+- 添加statusCounts状态独立管理状态计数
+- 添加加载状态管理（isStatusChanging, isRefreshing）
+
+**数据获取策略**：
+- 实现智能刷新：活跃期完整刷新，稳定期轻量刷新
+- 状态切换时立即刷新数据
+- 分页操作时立即更新数据
+- 定期刷新与手动操作协调
+
+**布局调整**：
+- 将分页控制组件放置在顶部操作栏中间位置
+- 保持状态过滤按钮在表格上方
+- 确保响应式布局适配
+
+**事件处理优化**：
+- 状态切换时，如果当前页码数据不足，则重置到第一页
+- 页面大小变更时智能计算新页码
+- 错误时状态回滚机制
+
+## 五、用户体验优化
+
+### 即时反馈机制
+- 状态切换时显示加载动画
+- 分页操作时提供视觉反馈
+- 数据不足时智能提示用户
+
+### 错误处理策略
+- 网络错误时自动重试
+- 操作失败时状态回滚
+- 友好的错误提示信息
+
+### 性能优化措施
+- 防抖处理频繁操作
+- 智能刷新策略减少不必要请求
+- 组件卸载时清理定时器和请求
+
+## 六、兼容性保障
+
+### 向后兼容
+- 保留原有的/documents接口作为备用
+- 现有功能（排序、过滤、选择）保持不变
+- 渐进式升级，支持配置开关
+
+### 数据一致性
+- 确保分页数据与状态计数同步
+- 处理并发更新的数据一致性问题
+- 定期刷新保持数据最新
+
+## 七、测试策略
+
+### 功能测试
+- 各种分页场景测试
+- 状态过滤组合测试
+- 排序功能验证
+- 边界条件测试
+
+### 性能测试
+- 大数据量场景测试
+- 并发访问压力测试
+- 内存使用情况监控
+- 响应时间测试
+
+### 兼容性测试
+- 不同存储后端测试
+- 不同浏览器兼容性
+- 移动端响应式测试
+
+## 八、关键实现细节
+
+### 后端分页查询设计
+- **统一接口**：所有存储后端实现相同的分页接口签名
+- **参数验证**：严格验证页码、页面大小、排序参数的合法性
+- **性能优化**：使用数据库原生分页功能，避免应用层分页
+- **错误处理**：统一的错误响应格式和异常处理机制
+
+### 前端状态管理策略
+- **数据分离**：当前页数据与状态计数分别管理
+- **智能刷新**：根据文档处理状态选择刷新策略
+- **状态同步**：确保UI状态与后端数据保持一致
+- **错误恢复**：操作失败时自动回滚到之前状态
+
+### 分页控制组件设计
+- **紧凑布局**：适配顶部操作栏的空间限制
+- **响应式设计**：在不同屏幕尺寸下自适应布局
+- **交互优化**：防抖处理、加载状态、禁用状态管理
+- **可访问性**：支持键盘导航和屏幕阅读器
+
+### 数据库索引优化
+- **复合索引**：workspace + status + sort_field的组合索引
+- **覆盖索引**：尽可能使用覆盖索引减少回表查询
+- **索引监控**：定期监控索引使用情况和查询性能
+- **渐进优化**：根据实际使用情况调整索引策略

LightRAG/pyproject.toml

@@ -0,0 +1,105 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "lightrag-hku"
+dynamic = ["version"]
+authors = [
+    {name = "Zirui Guo"}
+]
+description = "LightRAG: Simple and Fast Retrieval-Augmented Generation"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "aiohttp",
+    "configparser",
+    "dotenv",
+    "future",
+    "json_repair",
+    "nano-vectordb",
+    "networkx",
+    "numpy",
+    "pandas>=2.0.0",
+    "pipmaster",
+    "pydantic",
+    "pypinyin",
+    "python-dotenv",
+    "setuptools",
+    "tenacity",
+    "tiktoken",
+    "xlsxwriter>=3.1.0",
+]
+
+[project.optional-dependencies]
+api = [
+    # Core dependencies
+    "aiohttp",
+    "configparser",
+    "dotenv",
+    "future",
+    "json_repair",
+    "nano-vectordb",
+    "networkx",
+    "numpy",
+    "openai",
+    "pandas>=2.0.0",
+    "pipmaster",
+    "pydantic",
+    "pypinyin",
+    "python-dotenv",
+    "setuptools",
+    "tenacity",
+    "tiktoken",
+    "xlsxwriter>=3.1.0",
+    # API-specific dependencies
+    "aiofiles",
+    "ascii_colors",
+    "asyncpg",
+    "distro",
+    "fastapi",
+    "httpcore",
+    "httpx",
+    "jiter",
+    "passlib[bcrypt]",
+    "psutil",
+    "PyJWT",
+    "python-jose[cryptography]",
+    "python-multipart",
+    "pytz",
+    "uvicorn",
+]
+
+[project.scripts]
+lightrag-server = "lightrag.api.lightrag_server:main"
+lightrag-gunicorn = "lightrag.api.run_with_gunicorn:main"
+
+[project.urls]
+Homepage = "https://github.com/HKUDS/LightRAG"
+Documentation = "https://github.com/HKUDS/LightRAG"
+Repository = "https://github.com/HKUDS/LightRAG"
+"Bug Tracker" = "https://github.com/HKUDS/LightRAG/issues"
+
+[tool.setuptools.packages.find]
+include = ["lightrag*"]
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.dynamic]
+version = {attr = "lightrag.__version__"}
+
+[tool.setuptools.package-data]
+lightrag = ["api/webui/**/*"]
+
+[tool.ruff]
+target-version = "py310"

LightRAG/setup.py

@@ -0,0 +1,6 @@
+# Minimal setup.py for backward compatibility
+# Primary configuration is now in pyproject.toml
+
+from setuptools import setup
+
+setup()

LightRAG/stgong.txt

@@ -0,0 +1,3 @@
+Hello!
+I am a 24-year-old boy.
+I am persuing my PHD in DLUT.