LightRAG 如何用 Gunicorn 多 worker 运行 API 服务并安装为 systemd 系统服务

LightRAG 如何用 Gunicorn 多 worker 运行 API 服务并安装为 systemd 系统服务【免费下载链接】LightRAG[EMNLP2025] LightRAG: Simple and Fast Retrieval-Augmented Generation项目地址: https://gitcode.com/GitHub_Trending/li/LightRAG当 LightRAG 服务器既要处理文档索引又要响应 RAG 查询时文档索引任务可能阻塞查询请求。LightRAG Server 提供了一个多进程运行模式Gunicorn Uvicornpreload 模式文档中称为 production mode通过 Gunicorn 的多个 worker 进程让文档索引不占用查询进程的处理时间。本文覆盖从安装、配置.env、以多 worker 启动到把服务安装为 systemd 系统服务lightrag.service并验证的完整路径。该模式不支持 Windows 环境systemd 部分适用于 Ubuntu 等 Linux 发行版。准备条件安装与 .env 配置多 worker 模式与单进程的lightrag-server模式使用同一套安装和配置先完成这两项安装带 API 功能的 LightRAG Server### Install LightRAG Server as tool using uv (recommended) uv tool install lightrag-hku[api]也可以用 pippip install lightrag-hku[api]先创建并激活虚拟环境。源码安装git clone仓库后执行make dev同样可用。配置 LLM 与 Embedding 模型。LightRAG 依赖 LLM 和 Embedding Model 才能完成文档索引与查询。从项目根目录把env.example复制到启动目录并改名为.env然后修改其中 LLM 和 Embedding 相关参数。例如 OpenAI LLM Ollama Embedding 的组合LLM_BINDINGopenai LLM_MODELgpt-4o LLM_BINDING_HOSThttps://api.openai.com/v1 LLM_BINDING_API_KEYyour_api_key EMBEDDING_BINDINGollama EMBEDDING_BINDING_HOSThttp://localhost:11434 EMBEDDING_MODELbge-m3:latest EMBEDDING_DIM1024这里your_api_key需要替换为你自己的密钥其余值来自文档示例可换成你实际使用的模型。也可以用交互式向导生成.envmake env-base # Required first step: LLM, embedding, reranker有两点设计约束必须遵守.env文件必须放在启动目录当前工作目录。这是刻意设计允许用不同的.env同时启动多个 LightRAG 实例。修改.env后需要重开终端或对服务执行 restart才生效每次启动时.env会加载进系统环境变量而系统环境变量优先级高于.env。Embedding 模型与维度必须在首次文档索引前确定之后变更需要清空对应工作区/向量数据并重新索引。用 Gunicorn 多 worker 启动LightRAG Server 有两种运行模式单进程 Uvicorn 模式lightrag-server多进程 Gunicorn Uvicorn 模式lightrag-gunicorn不支持 Windows。手动启动多 worker 模式的命令lightrag-gunicorn --workers 4--workers的默认值是1单 worker。也可以用环境变量WORKERS配置 worker 数量文档给出的建议上限是(2 x number_of_cores) 1示例值### Number of worker processes, not greater than (2 x number_of_cores) 1 WORKERS2多 worker 下的并发控制多 worker 模式下只有一个 worker 处理文档索引管线但借助 Uvicorn 的异步任务支持多个文件可以并行处理。与并发相关的环境变量附文档示例值### Number of worker processes, not greater than (2 x number_of_cores) 1 WORKERS2 ### Number of parallel files to process in one batch MAX_PARALLEL_INSERT3 ### Base LLM concurrency and the per-document chunk-extraction task limit ### (MAX_ASYNC is still accepted as a deprecated alias) MAX_ASYNC_LLM4MAX_PARALLEL_INSERT控制一批并行处理几个文件MAX_ASYNC_LLM是基础 LLM 并发度也是单文档分块抽取任务的上限每个实体/关系合并阶段使用两倍的该任务上限。索引速度的瓶颈主要在 LLM如果你的 LLM 支持高并发可以提高 LLM 并发来加速文档索引。此外文档提醒CPU 密集型文档抽取工具如外部 parser 服务应部署为外部服务避免阻塞 API 进程。macOS 用户的额外要求在 macOS 上运行 Gunicorn 多 worker 模式必须在 Python 进程启动前设置 Objective-C fork-safety 覆盖变量不能依赖.env.env在 Python 启动之后才加载对 Objective-C runtime 来说太晚export OBJC_DISABLE_INITIALIZE_FORK_SAFETYYES lightrag-gunicorn --workers 2多行命令和配置使用带语言标识的三个反引号围栏--workers参数可调整为你需要的 worker 数。创建 systemd 服务文件仓库根目录提供了示例文件 lightrag.service.example按它创建你自己的lightrag.service并修改启动选项。示例文件的关键内容[Unit] DescriptionLightRAG XYJ Service Afternetwork.target [Service] Typesimple Usernetman # Memory settings MemoryHigh8G MemoryMax12G # Set the LightRAG installation directory (change this to match your installation path) EnvironmentLIGHTRAG_HOME/home/netman/lightrag-xyj # Set Environment to your Python virtual environment EnvironmentPATH${LIGHTRAG_HOME}/.venv/bin WorkingDirectory${LIGHTRAG_HOME} ExecStart${LIGHTRAG_HOME}/.venv/bin/lightrag-server # ExecStart${LIGHTRAG_HOME}/.venv/bin/lightrag-gunicorn # Kill mode require ExecStart must be gunicorn or unvicorn main process KillModeprocess ExecStop/bin/kill -s TERM $MAINPID TimeoutStopSec60 Restartalways RestartSec30 [Install] WantedBymulti-user.target使用时需要按你的实际环境修改这些值User改为运行服务用的 Linux 用户LIGHTRAG_HOME及由此派生的PATH、WorkingDirectory改为你实际的 LightRAG 安装目录即存放.env的启动目录MemoryHigh/MemoryMax示例中的内存限制值可按机器内存调整。要用多 worker 模式运行把ExecStart指向lightrag-gunicorn取消注释第二行、注释掉第一行ExecStart${LIGHTRAG_HOME}/.venv/bin/lightrag-gunicorn # ExecStart${LIGHTRAG_HOME}/.venv/bin/lightrag-server文档中给出的最小修改示例对应把路径改成你的虚拟环境和安装目录# Set environment to your Python virtual environment EnvironmentPATH/home/netman/lightrag-xyj/venv/bin WorkingDirectory/home/netman/lightrag-xyj # ExecStart/home/netman/lightrag-xyj/venv/bin/lightrag-server ExecStart/home/netman/lightrag-xyj/venv/bin/lightrag-gunicorn限制条件ExecStart命令必须是lightrag-gunicorn或lightrag-server本身不允许包一层 wrapper 脚本因为服务终止要求主进程必须是这两个可执行文件之一示例文件中的KillModeprocessExecStop/bin/kill -s TERM $MAINPID依赖这一点。安装并启动服务Ubuntu 系统下的安装命令sudo cp lightrag.service /etc/systemd/system/ sudo systemctl daemon-reload sudo systemctl start lightrag.service sudo systemctl status lightrag.service sudo systemctl enable lightrag.service前两条命令把服务文件复制到系统目录并让 systemd 重新加载配置start立即启动服务status查看运行状态enable让服务在开机时自启。这些命令需要 sudo 权限会把lightrag.service写入系统级目录执行前确认你已有该文件的所有权与复制权限。验证服务运行systemctl status lightrag.service显示服务处于运行状态systemctl journalctl -u lightrag.service之外应用自身的日志默认写入lightrag.log可通过LOG_DIR、ERROR_LOG、ACCESS_LOG环境变量调整位置。用/health端点探活。该端点始终返回 HTTP 200可用作 liveness probe未认证请求只返回存活信号status、auth_mode、core_version、pipeline_busy等带凭据的请求返回完整配置与运行诊断curl http://localhost:9621/health curl -H X-API-Key: 你的API密钥 http://localhost:9621/health在http://localhost:9621/webui打开 WebUI上传一个小文档等待索引完成再执行一次hybrid或mix查询即可确认多 worker 模式下索引与查询链路可用。限制与注意事项ExecStart只能是lightrag-server或lightrag-gunicornwrapper 脚本会导致服务无法正常终止。macOS 多 worker 必须提前export OBJC_DISABLE_INITIALIZE_FORK_SAFETYYESLinux 无此要求。WORKERS建议不超过(2 x number_of_cores) 1。多 worker 模式下跨 worker 的全局并发上限由MAX_ASYNC_LLM等MAX_ASYNC系列值派生这些值既作为单个 worker 的本地上限也作为跨 worker 的全局上限否则真实总量约等于MAX_ASYNC x workers无需额外配置。文档升级尤其涉及有界管线调度的版本升级要求先停掉共享同一存储和工作区的全部旧 worker 与旧实例再启动新版本滚动重启中遗留一个旧 worker 就是失败场景。停止前可在认证过的/health中确认scheduling.drain_waiting_on_workers为false、scheduling.drain_pending_enqueues为0。服务以Restartalways、RestartSec30配置进程异常退出后 systemd 会在 30 秒后自动拉起。下一步如果要将服务暴露给外部网络参考 docs/LightRAG-API-Server.md 中的 Nginx 反向代理配置/documents/upload需要调大client_max_body_size以及 API Key / 账号认证配置默认无认证的服务不应直接暴露到不可信网络。【免费下载链接】LightRAG[EMNLP2025] LightRAG: Simple and Fast Retrieval-Augmented Generation项目地址: https://gitcode.com/GitHub_Trending/li/LightRAG创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考