v1.4.9.5

Important Notes

• 🚀 PostgreSQL migration performance problem for large dataset in v1.4.9.4
• 🛑 Introduces a graceful pipeline cancellation mechanism for document processing operations

• ✏️ Enable entity merging when renaming an entity to a target entity that already exists.

What's New

• Feat: Add Pipeline Cancellation Feature with Enhanced Reliability by @danielaskdd in #2258
• Allow users to provide keywords with QueryRequest by @Mobious in #2253
• Refact: Add offline Swagger UI support with custom static file serving by @danielaskdd in
• Refactor: Enhanced Entity Merging with Chunk Tracking by @danielaskdd in #2266

What's Fixed

• Fix: PostgreSQL Data Migration Performance Problem by @danielaskdd in #2259
• Fix: Ensure Storage Consistency When Creating Implicit Nodes from Relationships by @danielaskdd in #2262
• Refactor: Enhance KG Editing with Chunk Tracking by @danielaskdd in #2265
  #2273
• Update redis requirement from <7.0.0,>=5.0.0 to >=5.0.0,<8.0.0 by @dependabot[bot] in #2272
• Fix Entity Source IDs Tracking ProblemDuring Relationship Processing by @danielaskdd in #2279

New Contributors

• @Mobious made their first contribution in #2253

Full Changelog: v1.4.9.4...v1.4.9.5

v1.4.9.4

Important Notes: Eliminate Bottlenecks in Processing Large-scale Datasets

In production deployments, entity and relation metadata can grow unbounded as documents are continuously ingested. The source_id (chunk IDs) and file_path fields in entities and relations can accumulate thousands of entries, leading to:

• Performance degradation in vector database operations
• Increased storage costs
• Memory pressure during query operations
• Slower merge operations when processing new documents

LightRAG implements a configurable metadata size control system with two key features:

• Source ID limiting: Controls the maximum number of chunk IDs stored per entity/relation
• File path limiting: Controls the maximum number of file paths displayed in metadata (display-only, doesn't affect query performance)

Both features support two strategies:

• FIFO (First In First Out): Removes oldest entries when limit is reached. Best for evolving knowledge bases, keeps most recent information.
• KEEP: Keeps oldest entries, skips new ones when limit is reached. Best for stable knowledge bases, faster (fewer merge operations)

New environment variables with default values:

# Source ID limits (affects query performance)
MAX_SOURCE_IDS_PER_ENTITY=300
MAX_SOURCE_IDS_PER_RELATION=300
SOURCE_IDS_LIMIT_METHOD=FIFO

# File path limits (display only)
MAX_FILE_PATHS=100

Auto Data Migration

Upgrading to this version requires data migration. If your current system contains a large number of entity relationships, the upgrade process may take an extended period of time.

What's New

• Feat: Add offline Docker build support with embedded models and cache by @danielaskdd in #2222
• Refact: Limit Vector Database Metadata Size to Support Large Scale Dataset by @danielaskdd in #2240
• Feat: Add Optional LLM Cache Deletion for Document Deletion by @danielaskdd in #2244
• Refact: Add Entity Identifier Length Truncation to Prevent Storage Failures by @danielaskdd in #2245
• Refact: Add Multimodal Processing Status Support to DocProcessingStatus for RayAnything Compatibility by @danielaskdd in #2248

What's Changed

• Refact: Improve query result with semantic null returns by @danielaskdd in #2218
• remove deprecated dotenv package. by @wkpark in #2229
• Refact: Frontend UI Fixes and Performance Improvements by @danielaskdd in #2234
• Security: Fix SQL injection vulnerabilities in PostgreSQL storage by @lucky-verma in #2235
• Update openai requirement from <2.0.0,>=1.0.0 to >=1.0.0,<3.0.0 by @dependabot[bot] in #2238
• Update pandas requirement from <2.3.0,>=2.0.0 to >=2.0.0,<2.4.0 by @dependabot[bot] in #2239
• Optimize PostgreSQL initialization performance by @yrangana in #2237
• fix(docs): correct typo "acivate" → "activate" by @xiaojunxiang2023 in #2243

New Contributors

• @wkpark made their first contribution in #2229
• @lucky-verma made their first contribution in #2235
• @dependabot[bot] made their first contribution in #2238
• @xiaojunxiang2023 made their first contribution in #2243

Full Changelog: v1.4.9.3...v1.4.9.4

v1.4.9.3

Important Notes

• Add temporary solution implemented to ensure compatibility with the newly introduced document status in Rayanything.
• Frontend build artifacts is removed from git repo now, manual build action is required after cloning/pulling the repo.

What's Changed

• Refactor: WebUI Optimization and Simplification by @danielaskdd in #2198
• i18n: fix mustache brackets by @zl7261 in #2196
• fix: advise excluding dev dependencies in prod build by @kevinnkansah in #2201
• Exclude Frontend Build Artifacts from Git Repository by @danielaskdd in #2208
• Add PREPROCESSED (multimodal_processed) status for multimodal document processing by @danielaskdd in #2211

Full Changelog: v1.4.9.2...v1.4.9.3

v1.4.9.2

What's New

• feat: Add endpoint and UI to retry failed documents by @RooseveltAdvisors in #2168
• Refactor(webui): Improve document tooltip display with track ID and better formatting by @danielaskdd in #2170
• feat: add options for Postgres connection by @kevinnkansah in #2172
• feat: Add token tracking support to openai_embed function by @yrangana in #2181
• Add knowledge graph manipulation endpoints by @NeelM0906 in #2183
• Feat: Add Comprehensive Offline Deployment Solution by @danielaskdd in #2194

What's Fixed

• Fix: Add file_path field to full_docs storage by @danielaskdd in #2171
• Fixed typo in log message when creating new graph file by @aleksvujic in #2178
• Fixed: Add PostgreSQL Connection Retry Mechanism with Network Robustness by @danielaskdd in #2192
• Adding support for imagePullSecrets, envFrom, and deployment strategy in Helm chart by @tcyran in #2175
• Hotfix: Preserve ordering in get_by_ids methods across all storage implementations by @danielaskdd in #2195
• Update Web Dependencies by @kevinnkansah in #2193

New Contributors

• @RooseveltAdvisors made their first contribution in #2168
• @aleksvujic made their first contribution in #2178
• @kevinnkansah made their first contribution in #2172
• @yrangana made their first contribution in #2181
• @NeelM0906 made their first contribution in #2183
• @tcyran made their first contribution in #2175

Full Changelog: v1.4.9.1...v1.4.9.2

v1.4.9.1

What's Changed

• Feature(webui): Add KaTeX chemical formula rendering by supporting mhchem extension by @danielaskdd in #2154
• Feat(webui): Prevent LaTeX Parsing Errors Show-up During Streaming by @danielaskdd in #2155
• Fix dark mode graph labels for system theme and improve colors by @roman-marchuk in #2163
• web_ui: check node source and target by @zl7261 in #2156

Full Changelog: v1.4.9...v1.4.9.1

v1.4.9

Importance Notes

v1.4.9 introduces key enhancements focused on refining the reference output format and incorporating structured references into query results. All query API endpoints now include a references field, enabling frontend applications to retrieve cited documents and their corresponding identifiers associated with LightRAG query results.

The context format sent to the LLM has been updated. The streaming response from the LLM now includes a references field (ignored by the frontend by default). If your application relies on context data returned by the LightRAG query API, you may need to update your code accordingly.

By leveraging the user_prompt parameter, users can instruct the LLM to generate responses with footnote annotations. The footnote numbers in the LLM output can be seamlessly mapped to the document IDs returned in the references field. This integration enables tighter alignment between LightRAG and your business system, empowering users to access original source materials directly.

user_prompt act as additional output instruction for LLM. Here provide two examples:

1. user_prompt for gpt-4.1-mini or Qwen3

For inline citations, employ the footnote reference format `[^1]`, where the `^` following the opening square bracket denotes a superscript link. When multiple citations are required at a single location, enclose each reference ID within separate footnote markers (e.g., `[^1][^2][^3]`).

2. user_prompt for DeepSeek:

内嵌引文标注使用Markdown脚注格式`[^1]`, 当某处有多个引文标注时,应将每个引用ID分别置于独立的中括号内（例如：`[^1][^2][^3]`）。仅需对回答的关键事实和依据信息给出标注。出现在引文标中的引文ID都应该列在最后生成的参考文献中段落中。不要在参考文献段落之后生成脚注段落。

This screenshot illustrates the functionality of the user_prompt parameter in the WebUI:

What's New

• Refactor: Provide Citation Context to LLM and Improve Reference Section Generation Quality by @danielaskdd in #2140
• Feature: Add Reference List Support for All Query Endpoints by @danielaskdd in #2147
• Refactor(WebUI): Change Client-side Search Logic with Server-driven Enity Name Search by @danielaskdd in #2124
• Feature(webui): Force sending history messages in bypass mode by @danielaskdd in #2132
• Feature(webui): Add footnotes support to markdown rendering in chat messages by @danielaskdd in #2145
• Feature(webui): Add user prompt history dropdown to query settings by @danielaskdd in #2146

What's Fixed

• Add path traversal security validation for file deletion operations by @danielaskdd in #2113
• Fix WebUI: Enhance tooltip readability by fix tooltip text wrapping of error message by @danielaskdd in #2114
• Fix Retrieval Page Parameter Options: Enforce Mutual Exclusivity Between "Only Need Context" and "Only Need Prompt" by @Saravanakumar26 in #2118
• Refactor: Optimize Query Prompts and User Prompt Handling by @danielaskdd in #2127
• WebUI Bugfix and Improvement by @danielaskdd in #2129
• Fix: Restore browser autocomplete functionality in message input box by @danielaskdd in #2131
• feat: Implement Comprehensive Document Duplication Prevention System by @danielaskdd in #2135
• Refactor node type legend and color mapping by @danielaskdd in #2137
• Fix typo: "Oputput" -> output by @SeungAhSon in #2139
• Feature: Add Enhanced Markdown Support for WebUI by @danielaskdd in #2143
• Fix: Robust clipboard functionality with fallback strategies by @danielaskdd in #2144
• Optimize Footnote Marker Display in WebUI by @danielaskdd in #2151
• Fix double query problem by add aquery_llm function for consistent response handling by @danielaskdd in #2152
• Web UI - center the loading icon and adjust GraphSeach width by @zl7261 in #2150

New Contributors

• @Saravanakumar26 made their first contribution in #2118
• @SeungAhSon made their first contribution in #2139
• @zl7261 made their first contribution in #2150

Full Changelog: v1.4.8.2...v1.4.9

v1.4.8.2

What's Changed

• Refactor: Add error handling with chunk ID prefixing in entity extraction by @danielaskdd in #2107
• fix: resolve dark mode text visibility issue in knowledge graph view by @roman-marchuk in #2106
• Fix: Resolve DocumentManager UI freezing and enhance error handling by @danielaskdd in #2109

New Contributors

• @roman-marchuk made their first contribution in #2106

Full Changelog: v1.4.8.1...v1.4.8.2

v1.4.8.1

Import Notes

1. Introduced a raw data query API /query/data, enabling developers to retrieve complete raw data recalled by LightRAG for fine-grained processing.
2. Optimized the system to efficiently handle hundreds of documents and hundreds of thousands of ten-relationships in one batch job, resolving UI lag and enhancing overall system stability.
3. Drop entities with short numeric names that negatively impact performance and query results; dropping names containing only two digits, names shorter than six characters, and names mixed with digits and dots, like 1.1, 12.3, 1.2.3 etc.
4. Significantly improves the quantity and quality of entity and relation extraction for smaller parameter models, leading to a substantial improvement in query performance
5. Optimized the prompt engineering for Qwen3-30B-A3B-Instruct and gpt-oss-120b models, incorporating targeted fault tolerance for model outputs.
6. Implemented max tokens and tempreture configuration to prevent excessively long or endless output loop during the entity relationship extraction phase for Large Language Model (LLM) responses.

# Increased temperature values may mitigate infinite inference loops in certain LLM, such as Qwen3-30B.
OPENAI_LLM_TEMPERATURE=0.9

# For vLLM/SGLang doployed models, or most of OpenAI compatible API provider
OPENAI_LLM_MAX_TOKENS=9000

# For Ollama Deployed Modeles
OLLAMA_LLM_NUM_PREDICT=9000

# For OpenAI o1-mini or newer modles
OPENAI_LLM_MAX_COMPLETION_TOKENS=9000

The purpose of setting max tokens parameter is to truncate LLM output before timeouts occur, thereby preventing document extraction failures. This addresses issues where certain text blocks (e.g., tables or citations) containing numerous entities and relationships can lead to overly long or even endless loop outputs from LLMs. This setting is particularly crucial for locally deployed, smaller-parameter models. Max tokens value can be calculated by this formula:
LLM_TIMEOUT * llm_output_tokens/second (i.e. 9000 = 180s * 50 tokens/s)

What's New

• refact: Enhance KG Extraction with Improved Prompts and Parser Robustness by @danielaskdd in #2032
• feat: Limit Pipeline Status History Messages to Latest 1000 Entries by @danielaskdd in #2064
• feature: Enhance document status display with metadata tooltips and better icons by @danielaskdd in #2070
• refactor: Optimize Entity Extraction for Small Parameter LLMs with Enhanced Prompt Caching by @danielaskdd in #2076 #2072
• Feature: Add LLM COT Rendering support for WebUI by @danielaskdd in #2077
• feat: Add Deepseek Sytle CoT Support for Open AI Compatible LLM Provider by @danielaskdd in #2086
• Add query_data function and /query/data API endpoint to LightRag for retrieval structured response by @tongda in #2036 #2100

What's Fixed

• Fix: Eliminate Lambda Closure Bug in Embedding Function Creation by @avchauzov in #2028
• refac: Eliminate Conditional Imports and Simplify Initialization by @danielaskdd in #2029
• Fix: Preserve Leading Spaces in Graph Label Selection by @danielaskdd in #2030
• Fix ENTITY_TYPES Environment Variable Handling by @danielaskdd in #2034
• refac: Enhanced Entity Relation Extraction Text Sanitization and Normalization by @danielaskdd in #2031
• Fix LLM output instability for <|> tuple delimiter by @danielaskdd in #2035
• Enhance KG Extraction for LLM with Small Parameters by @danielaskdd in #2051
• Add VDB error handling with retries for data consistency by @danielaskdd in #2055
• Fix incorrect variable name in NetworkXStorage file path by @danielaskdd in #2060
• refact: Smart Configuration Caching and Conditional Logging by @danielaskdd in #2068
• refactor: Improved Exception Handling with Context-Aware Error Messages by @danielaskdd in #2069
• fix env file example by @k-shlomi in #2075
• Increase default Gunicorn worker timeout from 210 to 300 seconds by @danielaskdd in #2078
• Fix assistant message display with content fallback by @danielaskdd in #2079
• Prompt Optimization: remove angle brackets from entity and relationship output formats by @danielaskdd in #2082
• Refactor PostgreSQL Graph Query by Native SQL and Standardized Parameter Passing by @Matt23-star in #2027
• Update env.example by @rolotumazi in #2091
• refactor: Optimize Prompt and Fault Tolerance for LLM with Smaller Param LLM by @danielaskdd in #2093

New Contributors

• @avchauzov made their first contribution in #2028
• @k-shlomi made their first contribution in #2075
• @rolotumazi made their first contribution in #2091
• @tongda made their first contribution in #2036

Full Changelog: v1.4.7...v1.4.8

v1.4.8rc9

What's Changed

• Prompt Optimization: remove angle brackets from entity and relationship output formats by @danielaskdd in #2082
• Refactor PostgreSQL Graph Query by Native SQL and Standardized Parameter Passing by @Matt23-star in #2027
• feat: Add Deepseek Sytle CoT Support for Open AI Compatible LLM Provider by @danielaskdd in #2086

Full Changelog: v1.4.8rc8...v1.4.8rc9

v1.4.8rc8

What's New

• Optimize Entity Extraction for Small Parameter LLMs with Enhanced Prompt Caching by @danielaskdd in #2076 #2072
• Add LLM COT Rendering support for WebUI by @danielaskdd in #2077
• Enhance document status display with metadata tooltips by @danielaskdd in #2070

What's Fixed

• Limit Pipeline Status History Messages to Latest 1000 Entries by @danielaskdd in #2064
• Optimized Function Factories for LLM and Embedding function @danielaskdd in #2068
• Improved LLM Exception Handling with Context-Aware Error Messages by @danielaskdd in #2069
• fix env file example by @k-shlomi in #2075

New Contributors

• @k-shlomi made their first contribution in #2075

Full Changelog: v1.4.8rc4...v1.4.8rc8