[2024.11.25]🎯📢LightRAG now supports seamless integration of custom knowledge graphs, empowering users to enhance the system with their own domain expertise.
[2024.11.19]🎯📢A comprehensive guide to LightRAG is now available on LearnOpenCV. Many thanks to the blog author.
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
pip install "lightrag-hku[api]"
Installation from Source
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]"
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
For more information about LightRAG Server, please refer to LightRAG Server.
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 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:
### 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.
A Simple Program
Use the below Python snippet to initialize LightRAG, insert text to it, and perform queries:
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:
# Initialize RAG instance
rag = await initialize_rag()
rag.insert("Your text")
# Perform hybrid search
mode="hybrid"
print(
await rag.query(
"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:
Parameters
Parameter
Type
Explanation
Default
working_dir
str
Directory where the cache will be stored
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
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
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
llm_model_max_token_size
int
Maximum token size for LLM generation (affects entity relation summaries)
32768(default value changed by env var 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., {"example_number": 1, "language": "Simplified Chinese", "entity_types": ["organization", "person", "geo", "event"]}: sets example limit, entiy/relation extraction output language
example_number: all examples, language: English
convert_response_to_json_func
callable
Not used
convert_response_to_json
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.
Use QueryParam to control the behavior your query:
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."""
max_token_for_text_unit: int = int(os.getenv("MAX_TOKEN_TEXT_CHUNK", "4000"))
"""Maximum number of tokens allowed for each retrieved text chunk."""
max_token_for_global_context: int = int(
os.getenv("MAX_TOKEN_RELATION_DESC", "4000")
)
"""Maximum number of tokens allocated for relationship descriptions in global retrieval."""
max_token_for_local_context: int = int(os.getenv("MAX_TOKEN_ENTITY_DESC", "4000"))
"""Maximum number of tokens allocated for entity descriptions in local retrieval."""
conversation_history: list[dict[str, str]] = field(default_factory=list)
"""Stores past conversation history to maintain context.
Format: [{"role": "user/assistant", "content": "message"}].
"""
history_turns: int = 3
"""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.
"""
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:
Using Open AI-like APIs
LightRAG also supports Open AI-like chat/embeddings APIs:
If you want to use Hugging Face models, you only need to set LightRAG as follows:
See lightrag_hf_demo.py
# 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,
max_token_size=5000,
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")
)
),
)
Using Ollama Models
**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:
# 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,
max_token_size=8192,
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
Pull the model:
ollama pull qwen2
Display the model file:
ollama show --modelfile qwen2 > Modelfile
Edit the Modelfile by adding the following line:
PARAMETER num_ctx 32768
Create the modified model:
ollama create -f Modelfile qwen2m
Setup num_ctx via Ollama API
Tiy can use llm_model_kwargs param to configure ollama:
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,
max_token_size=8192,
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.
LlamaIndex
LightRAG supports integration with LlamaIndex (llm/llama_index_impl.py):
Integrates with OpenAI and other providers through LlamaIndex
# 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,
max_token_size=8192,
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()
LightRAG now supports multi-turn dialogue through the conversation history feature. Here’s how to use it:
Usage Example
# Create conversation history
conversation_history = [
{"role": "user", "content": "What is the main character's attitude towards Christmas?"},
{"role": "assistant", "content": "At the beginning of the story, Ebenezer Scrooge has a very negative attitude towards Christmas..."},
{"role": "user", "content": "How does his attitude change?"}
]
# Create query parameters with conversation history
query_param = QueryParam(
mode="mix", # or any other mode: "local", "global", "hybrid"
conversation_history=conversation_history, # Add the conversation history
history_turns=3 # Number of recent conversation turns to consider
)
# Make a query that takes into account the conversation history
response = rag.query(
"What causes this change in his character?",
param=query_param
)
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:
# 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
Basic Insert
# Basic Insert
rag.insert("Text")
Batch Insert
# 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.
Insert with ID
If you want to provide your own IDs for your documents, number of documents and number of IDs must be the same.
# 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"])
Insert using Pipeline
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.
rag = LightRAG(..)
await rag.apipeline_enqueue_documents(input)
# Your routine in loop
await rag.apipeline_process_enqueue_documents(input)
Insert Multi-file Type Support
The textract supports reading file types such as TXT, DOCX, PPTX, CSV, and PDF.
By providing file paths, the system ensures that sources can be traced back to their original documents.
# 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)
Storage
LightRAG uses four types of storage, each of which has multiple implementation options. When initializing LightRAG, the implementation schemes for these four types of storage can be set through parameters. For details, please refer to the previous LightRAG initialization parameters.
Using Neo4J for Storage
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.
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.
Using PostgreSQL for Storage
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 is lightweight,the whole binary distribution including all necessary plugins can be zipped to 40MB: Ref to Windows Release as it is easy to install for Linux/Mac.
Create index for AGE example: (Change below dickens to your graph name if necessary)
load 'age';
SET search_path = ag_catalog, "$user", public;
CREATE INDEX CONCURRENTLY entity_p_idx ON dickens."Entity" (id);
CREATE INDEX CONCURRENTLY vertex_p_idx ON dickens."_ag_label_vertex" (id);
CREATE INDEX CONCURRENTLY directed_p_idx ON dickens."DIRECTED" (id);
CREATE INDEX CONCURRENTLY directed_eid_idx ON dickens."DIRECTED" (end_id);
CREATE INDEX CONCURRENTLY directed_sid_idx ON dickens."DIRECTED" (start_id);
CREATE INDEX CONCURRENTLY directed_seid_idx ON dickens."DIRECTED" (start_id,end_id);
CREATE INDEX CONCURRENTLY edge_p_idx ON dickens."_ag_label_edge" (id);
CREATE INDEX CONCURRENTLY edge_sid_idx ON dickens."_ag_label_edge" (start_id);
CREATE INDEX CONCURRENTLY edge_eid_idx ON dickens."_ag_label_edge" (end_id);
CREATE INDEX CONCURRENTLY edge_seid_idx ON dickens."_ag_label_edge" (start_id,end_id);
create INDEX CONCURRENTLY vertex_idx_node_id ON dickens."_ag_label_vertex" (ag_catalog.agtype_access_operator(properties, '"node_id"'::agtype));
create INDEX CONCURRENTLY entity_idx_node_id ON dickens."Entity" (ag_catalog.agtype_access_operator(properties, '"node_id"'::agtype));
CREATE INDEX CONCURRENTLY entity_node_id_gin_idx ON dickens."Entity" using gin(properties);
ALTER TABLE dickens."DIRECTED" CLUSTER ON directed_sid_idx;
-- drop if necessary
drop INDEX entity_p_idx;
drop INDEX vertex_p_idx;
drop INDEX directed_p_idx;
drop INDEX directed_eid_idx;
drop INDEX directed_sid_idx;
drop INDEX directed_seid_idx;
drop INDEX edge_p_idx;
drop INDEX edge_sid_idx;
drop INDEX edge_eid_idx;
drop INDEX edge_seid_idx;
drop INDEX vertex_idx_node_id;
drop INDEX entity_idx_node_id;
drop INDEX entity_node_id_gin_idx;
Known issue of the Apache AGE: The released versions got below issue:
You can Compile the AGE from source code and fix it.
Using Faiss for Storage
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.
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,
max_token_size=8192,
func=embedding_func,
),
vector_storage="FaissVectorDBStorage",
vector_db_storage_cls_kwargs={
"cosine_better_than_threshold": 0.3 # Your desired threshold
}
)
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.
Create Entities and Relations
# 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
})
Edit Entities and Relations
# 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).
Insert Custom KG
custom_kg = {
"chunks": [
{
"content": "Alice and Bob are collaborating on quantum computing research.",
"source_id": "doc-1"
}
],
"entities": [
{
"entity_name": "Alice",
"entity_type": "person",
"description": "Alice is a researcher specializing in quantum physics.",
"source_id": "doc-1"
},
{
"entity_name": "Bob",
"entity_type": "person",
"description": "Bob is a mathematician.",
"source_id": "doc-1"
},
{
"entity_name": "Quantum Computing",
"entity_type": "technology",
"description": "Quantum computing utilizes quantum mechanical phenomena for computation.",
"source_id": "doc-1"
}
],
"relationships": [
{
"src_id": "Alice",
"tgt_id": "Bob",
"description": "Alice and Bob are research partners.",
"keywords": "collaboration research",
"weight": 1.0,
"source_id": "doc-1"
},
{
"src_id": "Alice",
"tgt_id": "Quantum Computing",
"description": "Alice conducts research on quantum computing.",
"keywords": "research expertise",
"weight": 1.0,
"source_id": "doc-1"
},
{
"src_id": "Bob",
"tgt_id": "Quantum Computing",
"description": "Bob researches quantum computing.",
"keywords": "research application",
"weight": 1.0,
"source_id": "doc-1"
}
]
}
rag.insert_custom_kg(custom_kg)
Other Entity and Relation Operations
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.
Entity Merging
Merge Entities and Their Relationships
LightRAG now supports merging multiple entities into a single entity, automatically handling all relationships:
# 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:
# 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:
# 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
Token Usage Tracking
Overview and Usage
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
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.
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
Basic Usage
# Basic CSV export (default format)
rag.export_data("knowledge_graph.csv")
# Specify any format
rag.export_data("output.xlsx", file_format="excel")
Different File Formats supported
#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")
Additional Options
Include vector embeddings in the export (optional):
The LightRAG Server is designed to provide Web UI and API support. For more information about LightRAG Server, please refer to LightRAG Server.
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 uses the following prompt to generate high-level queries, with the corresponding code in example/generate_query.py.
Prompt
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]
...
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 example/batch_eval.py.
Prompt
---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]"
}}
}}
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.
Code
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.")
Step-1 Insert Contexts
For the extracted contexts, we insert them into the LightRAG system.
Code
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")
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.
For the queries generated in Step-2, we will extract them and query LightRAG.
Code
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
Star History
Contribution
Thank you to all our contributors!
🌟Citation
@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: Simple and Fast Retrieval-Augmented Generation
🎉 News
textract
.Algorithm Flowchart
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 LightRAG Core
Quick Start
Quick Start for LightRAG Server
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 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: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 thekv_store_llm_response_cache.json
file while clearing the data directory.Note 2: Only
lightrag_openai_demo.py
andlightrag_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
A Simple Program
Use the below Python snippet to initialize LightRAG, insert text to it, and perform queries:
Important notes for the above snippet:
LightRAG init parameters
A full list of LightRAG init parameters:
Parameters
str
lightrag_cache+timestamp
str
JsonKVStorage
,PGKVStorage
,RedisKVStorage
,MongoKVStorage
JsonKVStorage
str
NanoVectorDBStorage
,PGVectorStorage
,MilvusVectorDBStorage
,ChromaVectorDBStorage
,FaissVectorDBStorage
,MongoVectorDBStorage
,QdrantVectorDBStorage
NanoVectorDBStorage
str
NetworkXStorage
,Neo4JStorage
,PGGraphStorage
,AGEStorage
NetworkXStorage
str
JsonDocStatusStorage
,PGDocStatusStorage
,MongoDocStatusStorage
JsonDocStatusStorage
int
1200
int
100
Tokenizer
TokenizerInterface
protocol. If you don’t specify one, it will use the default Tiktoken tokenizer.TiktokenTokenizer
str
gpt-4o-mini
int
1
int
500
str
node2vec
dict
{"dimensions": 1536,"num_walks": 10,"walk_length": 40,"window_size": 2,"iterations": 3,"random_seed": 3,}
EmbeddingFunc
openai_embed
int
32
int
16
callable
gpt_4o_mini_complete
str
meta-llama/Llama-3.2-1B-Instruct
int
32768
(default value changed by env var MAX_TOKENS)int
4
(default value changed by env var MAX_ASYNC)dict
dict
bool
TRUE
, stores LLM results in cache; repeated prompts return cached responsesTRUE
bool
TRUE
, stores LLM results in cache for entity extraction; Good for beginners to debug your applicationTRUE
dict
{"example_number": 1, "language": "Simplified Chinese", "entity_types": ["organization", "person", "geo", "event"]}
: sets example limit, entiy/relation extraction output languageexample_number: all examples, language: English
callable
convert_response_to_json
dict
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.{"enabled": False, "similarity_threshold": 0.95, "use_llm_check": False}
Query Param
Use QueryParam to control the behavior your query:
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:
Using Open AI-like APIs
Using Hugging Face Models
See
lightrag_hf_demo.py
Using Ollama Models
**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:
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:
num_ctx
parameter in Modelfilenum_ctx
via Ollama APITiy can use
llm_model_kwargs
param to configure ollama: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 onbook.txt
.LlamaIndex
LightRAG supports integration with LlamaIndex (
llm/llama_index_impl.py
):Example Usage
For detailed documentation and examples, see:
Conversation History Support
LightRAG now supports multi-turn dialogue through the conversation history feature. Here’s how to use it:
Usage Example
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:Insert
Basic Insert
Batch Insert
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.Themax_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.Insert with ID
If you want to provide your own IDs for your documents, number of documents and number of IDs must be the same.
Insert using Pipeline
The
apipeline_enqueue_documents
andapipeline_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.
Insert Multi-file Type Support
The
textract
supports reading file types such as TXT, DOCX, PPTX, CSV, and PDF.Citation Functionality
By providing file paths, the system ensures that sources can be traced back to their original documents.
Storage
LightRAG uses four types of storage, each of which has multiple implementation options. When initializing LightRAG, the implementation schemes for these four types of storage can be set through parameters. For details, please refer to the previous LightRAG initialization parameters.
Using Neo4J for Storage
see test_neo4j.py for a working example.
Using PostgreSQL for Storage
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 is lightweight,the whole binary distribution including all necessary plugins can be zipped to 40MB: Ref to Windows Release 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
Create index for AGE example: (Change below
dickens
to your graph name if necessary)Known issue of the Apache AGE: The released versions got below issue:
Using Faiss for Storage
You can also install
faiss-gpu
if you have GPU support.sentence-transformers
but you can also useOpenAIEmbedding
model with3072
dimensions.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.
Create Entities and Relations
Edit Entities and Relations
All operations are available in both synchronous and asynchronous versions. The asynchronous versions have the prefix “a” (e.g.,
acreate_entity
,aedit_relation
).Insert Custom KG
Other Entity and Relation Operations
These operations maintain data consistency across both the graph database and vector database components, ensuring your knowledge graph remains coherent.
Entity Merging
Merge Entities and Their Relationships
LightRAG now supports merging multiple entities into a single entity, automatically handling all relationships:
With custom merge strategy:
With custom target entity data:
Advanced usage combining both approaches:
When merging entities:
Token Usage Tracking
Overview and Usage
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
Usage Tips
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 modelexamples/lightrag_siliconcloud_track_token_demo.py
: Token tracking example using SiliconCloud modelThese examples demonstrate how to effectively use the TokenTracker feature with different models and scenarios.
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
Basic Usage
Different File Formats supported
Additional Options
Include vector embeddings in the export (optional):
Data Included in Export
All exports include:
Cache
Clear Cache
You can clear the LLM response cache with different modes:
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 cacheLightRAG API
The LightRAG Server is designed to provide Web UI and API support. For more information about LightRAG Server, please refer to LightRAG Server.
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.
Evaluation
Dataset
The dataset used in LightRAG can be downloaded from TommyChien/UltraDomain.
Generate Query
LightRAG uses the following prompt to generate high-level queries, with the corresponding code in
example/generate_query.py
.Prompt
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
example/batch_eval.py
.Prompt
Overall Performance Table
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.
Code
Step-1 Insert Contexts
For the extracted contexts, we insert them into the LightRAG system.
Code
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.
Code
Step-3 Query
For the queries generated in Step-2, we will extract them and query LightRAG.
Code
Star History
Contribution
Thank you to all our contributors!
🌟Citation
Thank you for your interest in our work!