LightRAG AI技能包

compatibility; set WHITELIST_PATHS=/health to require auth on them too.

lightrag-server

* Installation from Source

Installation

💡 Using uv for Package Management: This project uses uv for fast and reliable Python package management. Install uv first: curl -LsSf https://astral.sh/uv/install.sh | sh (Unix/macOS) or powershell -c "irm https://astral.sh/uv/install.ps1 | iex" (Windows)

Note: You can also use pip if you prefer, but uv is recommended for better performance and more reliable dependency management. 📦 Offline Deployment: For offline or air-gapped environments, see the Offline Deployment Guide for instructions on pre-installing all dependencies and cache files.

Install LightRAG Server

• Install from PyPI

```bash

Install LightRAG Server as tool using uv (recommended)

uv tool install "lightrag-hku[api]"

pip install "lightrag-hku[api]"

Build front-end artifacts

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

Setup env file

make dev installs the test toolchain plus the full offline stack

(API, storage backends, and provider integrations), then builds the frontend.

Or using pip with virtual environment

pip install -e ".[test,offline]"

Build front-end artifacts

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

setup env file

make env-base # Or: cp env.example .env and update it manually

Create .env File With Setup Tool

Instead of editing env.example by hand, use the interactive setup wizard to generate a configured .env and, when needed, docker-compose.final.yml:

make env-base           # Required first step: LLM, embedding, reranker
make env-storage        # Optional: storage backends and database services
make env-server         # Optional: server port, auth, and SSL
make env-base-rewrite   # Optional: force-regenerate wizard-managed compose services
make env-storage-rewrite # Optional: force-regenerate wizard-managed compose services
make env-security-check # Optional: audit the current .env for security risks

For full description of every target see docs/InteractiveSetup.md.

Install LightRAG SDK

• Install from source code

```bash cd LightRAG

或: pip install -e .

* Install from PyPI

或: pip install lightrag-hku

```

Obtain the env.example file by downloading it from the GitHub repository root

Run make env-base or copy env.example to .env before starting the server.

Key Configuration Guide

**Notes on SDK Usage**

For detailed instructions on using the SDK, please refer to docs/ProgramingWithCore.md. Some LightRAG features are not exposed via the REST API and are accessible only through the SDK. These features are typically experimental and may not be compatible with future versions.

you should run the demo code with project folder

cd LightRAG

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.

python -m venv .venv

source .venv/bin/activate # Windows: .venv\Scripts\activate

SECURITY: before exposing it on a network, configure authentication in .env

Bootstrap the development environment (recommended)

make dev source .venv/bin/activate # Activate the virtual environment (Linux/macOS)

Or on Windows: .venv\Scripts\activate

Note: uv sync automatically creates a virtual environment in .venv/

uv sync --extra test --extra offline source .venv/bin/activate # Activate the virtual environment (Linux/macOS)

Or on Windows: .venv\Scripts\activate

python -m venv .venv

source .venv/bin/activate # Windows: .venv\Scripts\activate

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) Official GHCR images published by GitHub Actions are signed with Sigstore Cosign using GitHub OIDC. See docs/DockerDeployment.md for verification commands.

Document Processing Pipeline Configuration

The default pipeline configuration in LightRAG does not allow the system to perform at its best. The quality of document parsing greatly impacts document indexing and querying. Therefore, we recommend configuring the pipeline to enable the MinerU parsing engine and activating the pipeline's image analysis features. Suggested configuration:

LIGHTRAG_PARSER=*:native-iteP,*:mineru-iteP,*:legacy-R

VLM_PROCESS_ENABLE=true
VLM_LLM_MODEL=<your_vlm_model_name>

Since the cloud-based MinerU service has limitations on usage, file size, and page count, it is recommended to use a locally deployed MinerU. For details on configuring the file processing pipeline, please refer to FileProcessingPipeline.md

Sample Configuration

MAX_ASYNC_LLM=8 MAX_PARALLEL_INSERT=3 EMBEDDING_FUNC_MAX_ASYNC=16 EMBEDDING_BATCH_NUM=32 ```

Other Important Configurations for Document Processing

During the document insertion stage, you may also want to adjust the following environment variables based on your needs:

• SUMMARY_LANGUAGE: Controls the language used by the LLM when outputting entity-relation names and summaries, e.g., Chinese, English.
• ENTITY_EXTRACTION_USE_JSON: Controls whether the LLM outputs entity-relation extractions in JSON format. Using JSON format typically yields more stable results, but it consumes more tokens and can be slightly slower.
• ENABLE_CONTENT_HEADINGS: Controls whether the section heading information of a text chunk is sent to the LLM during the query stage (enabled by default, providing more context for the LLM).
• FORCE_LLM_SUMMARY_ON_MERGE / MAX_SOURCE_IDS_PER_RELATION: Controls the maximum number of text chunks an entity/relation can be associated with.
• SOURCE_IDS_LIMIT_METHOD: Controls whether to keep updating the entity/relation description once an entity/relation exceeds its associated text chunk limit (by default it stops updating, because at that point the entity-relation description is already rich enough and further updates add little value; skipping updates can greatly speed up knowledge base construction).
• DEFAULT_MAX_FILE_PATHS: Controls the maximum number of source files an entity/relation can be associated with; once this limit is exceeded, new file names are no longer written to the vector storage.
• OPENAI_LLM_MAX_TOKENS / OPENAI_LLM_MAX_COMPLETION_TOKENS: Set a max output token limit to prevent endless output from certain LLMs, which may trigger timeout errors during entity and relation extraction. Different LLM providers require distinct parameter configurations, as detailed in the env.example.

Other Important Configurations for Document Querying

During the document query stage, you may also want to adjust the following environment variables based on your needs: - MAX_ENTITY_TOKENS / MAX_RELATION_TOKENS / MAX_TOTAL_TOKENS: Controls the token length of the retrieved content sent to the LLM context. The retrieved content consists of three parts: entities, relations, and text chunks. The lengths of entities and relations can be controlled independently, while the text chunk length is determined by subtracting the entity and relation lengths from the total length. - ENABLE_CONTENT_HEADINGS: Controls whether the section heading where a text chunk resides is sent to the LLM; enabled by default, providing richer context for the LLM and improving answer quality. - ENABLE_LLM_CACHE: Whether to cache query results. Enabled by default; identical query questions, query modes, and LLM model parameters will return the same result.

注意: uv sync 会自动在 .venv/ 目录创建虚拟环境

uv sync source .venv/bin/activate # 激活虚拟环境 (Linux/macOS)

Windows 系统: .venv\Scripts\activate

Launch the server. It binds to all interfaces (0.0.0.0) by default.

(LIGHTRAG_API_KEY, or AUTH_ACCOUNTS together with TOKEN_SECRET), or bind to

127.0.0.1 for local-only access; without auth every endpoint is public.

Note: the Ollama-compatible /api/* routes stay open by default for client

Launch API-WebUI server

lightrag-server

* Launching the LightRAG Server with Docker Compose

LightRAG API Server

The LightRAG server offers not only a web-based UI for exploring LightRAG functionalities but also a comprehensive REST API. For more information about the LightRAG server, please refer to LightRAG Server.

Using LightRAG As SDK

⚠️ For integration into your project, we strongly recommend using the REST API provided by the LightRAG Server. The LightRAG SDK is primarily intended for embedded applications or academic research and evaluation purposes.

LightRAG SDK Sample Code

To get started with LightRAG core, refer to the sample codes available in the examples folder. Additionally, a video demo 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

provide your API-KEY for OpenAI

export OPENAI_API_KEY="sk-...your_opeai_key..."