RAG-Anything 与 vLLM 集成指南:用 OpenAI 兼容 API 打造生产级高吞吐 RAG 推理后端

发布时间:2026/9/12 1:39:26

RAG-Anything 与 vLLM 集成指南:用 OpenAI 兼容 API 打造生产级高吞吐 RAG 推理后端 RAG-Anything 与 vLLM 集成指南用 OpenAI 兼容 API 打造生产级高吞吐 RAG 推理后端【免费下载链接】RAG-AnythingRAG-Anything: All-in-One RAG Framework项目地址: https://gitcode.com/GitHub_Trending/ra/RAG-Anything导读本文基于 RAG-Anything 官方文档 docs/vllm_integration.md 编写系统讲解如何将 vLLM支持 Continuous Batching、PagedAttention、张量并行与 AWQ/GPTQ/FP8 量化的高性能推理引擎接入 RAG-Anything 的多模态文档处理与图检索管线。阅读完本文你将掌握vLLM 服务端与 Embedding 服务的启动参数、.env环境变量的完整配置、OpenAI 兼容函数注入的源码级原理以及并发调优与常见故障排障的实战方法。为什么选择 vLLM 作为 RAG 后端RAG-Anything 的 LLM 与 Embedding 后端采用可插拔绑定Binding设计官方支持openai、ollama、lmstudio、azure_openai、lollms、vllm等类型见 env.example 中的注释。vLLM 暴露的是 OpenAI 兼容 API因此可以直接作为 RAG-Anything 在生产环境中的即插即用drop-in后端无需任何协议适配层。与 Ollama、LM Studio 相比vLLM 的核心差异如下表所示FeaturevLLMOllamaLM StudioContinuous batching✅❌❌PagedAttention✅❌❌Tensor parallelism✅❌❌Production throughput✅ HighModerateLowQuantization (AWQ/GPTQ/FP8)✅✅ (GGUF)✅ (GGUF)Multi-GPU support✅ NativeLimited❌Ease of setupModerateEasyEasyGUI❌❌✅选择 vLLM 的典型场景需要生产级吞吐、同时服务多个并发用户或在多张 GPU 上运行大模型如 70B 参数级别。Continuous Batching 让 vLLM 可以持续吸收并批量处理并发请求避免排队空转PagedAttention 通过分页式 KV Cache 管理显著降低显存浪费Tensor Parallelism 则把大模型切分到多卡上协同推理。前置条件NVIDIA GPU支持 CUDA计算能力Compute Capability≥ 7.0Python 3.9安装 vLLMpip install vllm安装 RAG-Anythingpip install raganything此外运行仓库自带的 examples/vllm_integration_example.py 还需要安装openaiPython 包示例通过AsyncOpenAI与lightrag.llm.openai模块通信以及python-dotenv。快速开始三步跑通 vLLM RAG-Anything第一步启动 vLLM 服务端Chat / Completion 模型用于实体抽取、摘要、查询回答vllm serve Qwen/Qwen2.5-72B-Instruct \ --tensor-parallel-size 4 \ --max-model-len 32768 \ --port 8000Embedding 模型建议独立进程、独立端口避免与对话推理互相抢占显存vllm serve BAAI/bge-m3 \ --task embedding \ --port 8001第二步配置环境变量在项目根目录或示例运行目录创建.env文件### vLLM Configuration LLM_BINDINGvllm LLM_MODELQwen/Qwen2.5-72B-Instruct LLM_BINDING_HOSThttp://localhost:8000/v1 LLM_BINDING_API_KEYtoken-abc123 ### Embedding via vLLM EMBEDDING_BINDINGvllm EMBEDDING_MODELBAAI/bge-m3 EMBEDDING_DIM1024 EMBEDDING_BINDING_HOSThttp://localhost:8001/v1 EMBEDDING_BINDING_API_KEYtoken-abc123仓库根目录的 env.example 同样收录了 vLLM 配置段默认注释状态并指向本文作为设置指南。第三步运行示例脚本cd examples python vllm_integration_example.py该脚本examples/vllm_integration_example.py的执行流程依次为测试 vLLM 连接列出可用模型→ 测试 Chat 补全 → 初始化 RAG-Anything → 注入演示内容并执行 hybrid 查询。全部通过后退出码为 0。环境变量全表VariableDefaultDescriptionLLM_BINDING—设为vllmLLM_MODELQwen/Qwen2.5-72B-Instruct模型名必须与 vLLM 实际服务的模型名完全一致LLM_BINDING_HOSThttp://localhost:8000/v1vLLM API base URLLLM_BINDING_API_KEYtoken-abc123API keyvLLM 默认接受任意非空字符串EMBEDDING_BINDING—设为vllmEMBEDDING_MODELBAAI/bge-m3Embedding 模型名EMBEDDING_DIM1024Embedding 向量维度bge-m3 默认 1024EMBEDDING_BINDING_HOSThttp://localhost:8001/v1Embedding 端点 URLEMBEDDING_BINDING_API_KEYtoken-abc123Embedding API key相关并发参数在 env.example 中有默认值定义MAX_ASYNC4LLM 最大并发请求数、TIMEOUT240LLM 超时秒数None为无限、MAX_TOKENS32768发送给 LLM 的实体/关系摘要最大 token 数需小于模型上下文长度。vLLM 场景下可适当调大MAX_ASYNC以充分利用其批量推理能力见下文性能调优。支持的模型配置组合Qwen 2.5RAG 场景推荐vllm serve Qwen/Qwen2.5-72B-Instruct \ --tensor-parallel-size 4 \ --max-model-len 32768Mistral / Mixtralvllm serve mistralai/Mixtral-8x7B-Instruct-v0.1 \ --tensor-parallel-size 2 \ --max-model-len 32768Llama 3.1 70Bvllm serve meta-llama/Llama-3.1-70B-Instruct \ --tensor-parallel-size 4 \ --max-model-len 8192AWQ 量化显著降低显存占用vllm serve Qwen/Qwen2.5-72B-Instruct-AWQ \ --tensor-parallel-size 2 \ --quantization awq \ --max-model-len 32768GPTQ 量化vllm serve TheBloke/Mixtral-8x7B-Instruct-v0.1-GPTQ \ --tensor-parallel-size 2 \ --quantization gptq性能调优建议张量并行Tensor Parallelism将大模型分布到多张 GPU 上--tensor-parallel-size设置为 GPU 数量# 4x A100 80GB → 可以全精度服务 72B 模型 vllm serve Qwen/Qwen2.5-72B-Instruct --tensor-parallel-size 4显存利用率若显存有富余可调高默认 0.9vllm serve ... --gpu-memory-utilization 0.95最大模型长度若不需要完整上下文可调低以节省显存# RAG 分块通常小于 4K token8192 往往已经足够 vllm serve ... --max-model-len 8192并发vLLM 自动处理批处理batching。在 RAG-Anything 一侧调大.env中的MAX_ASYNCMAX_ASYNC16 # vLLM 可高效处理并发请求投机解码Speculative DecodingvLLM ≥ 0.4使用小模型作 draft model 加速生成vllm serve Qwen/Qwen2.5-72B-Instruct \ --speculative-model Qwen/Qwen2.5-0.5B-Instruct \ --num-speculative-tokens 5 \ --tensor-parallel-size 4Embedding 方案三选一RAG 管线的向量化环节可以独立于对话模型选择后端甚至可以在同一个 RAG-Anything 实例中混合使用不同后端。方案 AvLLM Embedding Server推荐为 Embedding 运行一个专用 vLLM 实例vllm serve BAAI/bge-m3 --task embedding --port 8001方案 B继续用 Ollama 做 Embedding如果已经在运行 Ollama可以混合后端——对话走 vLLMEmbedding 走 OllamaEMBEDDING_BINDINGollama EMBEDDING_MODELbge-m3:latest EMBEDDING_BINDING_HOSThttp://localhost:11434方案 COpenAI Embeddings对话使用 vLLMEmbedding 走 OpenAI APIEMBEDDING_BINDINGopenai EMBEDDING_MODELtext-embedding-3-large EMBEDDING_DIM3072 EMBEDDING_BINDING_HOSThttps://api.openai.com/v1 EMBEDDING_BINDING_API_KEYsk-...系统架构┌──────────────────────┐ │ RAG-Anything │ │ (Document Processing│ │ Query Engine) │ └──────┬───────────────┘ │ OpenAI-compatible API ▼ ┌──────────────────────┐ ┌──────────────────────┐ │ vLLM Chat Server │ │ vLLM Embedding Server│ │ :8000/v1 │ │ :8001/v1 │ │ (Qwen-72B, etc.) │ │ (bge-m3, etc.) │ └──────────────────────┘ └──────────────────────┘ │ │ ▼ ▼ ┌──────────────────────────────────────────────┐ │ GPU Cluster │ │ PagedAttention · Continuous Batching │ │ Tensor Parallelism · Quantization │ └──────────────────────────────────────────────┘源码视角vLLM 是如何接入 RAG-Anything 的RAG-Anything 并不内置 vLLM 客户端而是依赖 OpenAI 兼容协议与 LightRAG 的 LLM/Embedding 函数注入机制。理解这一层有助于你在不修改仓库源码的前提下自由组合任意 OpenAI 兼容后端。1. LLM 函数openai_complete_if_cache在 examples/vllm_integration_example.py 中顶层 LLM 函数vllm_llm_model_func直接委托给lightrag.llm.openai.openai_complete_if_cache并将LLM_BINDING_HOST作为base_url传入。由于 vLLM 暴露 OpenAI 兼容 API该函数天然支持带缓存的补全调用cache 命中可显著降低重复抽取的推理成本。函数被设计为模块级top-level定义以保证进程内可 pickle 序列化——这是 LightRAG 在异步任务与存储系统中传递函数的关键约束。2. Embedding 函数openai_embedvllm_embedding_asyncexamples/vllm_integration_example.py调用lightrag.llm.openai.openai_embed连接 vLLM 的 Embedding 端点可位于独立端口 8001返回List[List[float]]向量列表。随后通过EmbeddingFunc(embedding_dim1024, max_token_size8192, funcvllm_embedding_async)封装为可序列化的嵌入函数bge-m3 默认维度 1024、上下文 8192。3. 注入到RAGAnything在initialize_rag中两个函数通过构造参数注入self.rag RAGAnything( configself.config, llm_model_funcvllm_llm_model_func, embedding_funcself.embedding_func_factory(), )从 raganything/raganything.py 的_ensure_lightrag_initialized实现可以看到当未预置 LightRAG 实例时llm_model_func与embedding_func是创建新LightRAG实例的必需参数缺失会直接报错返回当预置 LightRAG 时若未显式传入会自动从 LightRAG 实例继承这两个函数raganything.py。这也解释了为什么 vLLM 场景下示例采用传入函数 由 RAGAnything 内部创建 LightRAG的方式。RAGAnythingConfigraganything/config.py负责文档解析侧配置示例中通过parsermineru、parse_methodauto选择解析器并通过enable_table_processingTrue、enable_equation_processingTrue开启表格与公式的模态处理此时modal_caption_func会使用注入的llm_model_func即 vLLM 后端见 raganything.py。示例还使用了带 UUID 的全新working_dir./rag_storage_vllm/{uuid4()}以避免旧版doc_status模式冲突。4. 内容插入与查询内容插入await self.rag.insert_content_list(content_list..., file_path..., doc_id..., display_statsTrue)按 RAGAnything 约定的 content_list 格式含type: text、text、page_idx字段注入演示文本查询await self.rag.aquery(query, modehybrid | local | global)支持 LightRAG 的三种检索模式混合、局部、全局查询底层通过QueryMixinraganything/query.py封装。文档处理示例中默认注释取消注释后使用真实文件路径即可await self.rag.process_document_complete(file_path..., output_dir./output_vllm, parse_methodauto, display_statsTrue)完成解析 → 多模态处理 → 入库的完整链路。故障排查Troubleshooting连接被拒绝Connection Refused❌ Connection failed: Connection refused确认 vLLM 正在运行curl http://localhost:8000/v1/models检查端口与LLM_BINDING_HOST是否一致大模型加载可能耗时数分钟请等待模型加载完成后再发起请求显存不足Out of Memorytorch.cuda.OutOfMemoryError改用量化模型--quantization awq或gptq调小--max-model-len增大--tensor-parallel-size需要更多 GPU调低--gpu-memory-utilization模型找不到Model Not FoundModel xxx not foundLLM_MODEL必须与 vLLM 实际服务的模型名精确一致用curl http://localhost:8000/v1/models查看当前可用的模型列表首次请求慢Slow First Request属于正常现象——vLLM 首次使用时需要编译 CUDA kernel后续请求会明显变快。可将首次请求视为预热warm-up在服务正式对外前主动发一次健康请求。结语vLLM RAG-Anything 的组合在架构上非常简洁RAG-Anything 侧只依赖 OpenAI 兼容协议与函数注入vLLM 侧只需按需启动 Chat 与 Embedding 两个服务端点。通过本文的环境变量表、模型启动参数与源码级调用链你可以将任意 OpenAI 兼容的高性能推理引擎平滑接入多模态 RAG 管线并在并发、量化与多卡维度持续调优吞吐。更多细节可进一步阅读仓库中的 env.example、examples/vllm_integration_example.py 以及 docs/offline_setup.md离线部署场景。【免费下载链接】RAG-AnythingRAG-Anything: All-in-One RAG Framework项目地址: https://gitcode.com/GitHub_Trending/ra/RAG-Anything创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
延伸阅读

更多相关文章

2026/9/12 1:39:26

一文读懂 HCCL Reduce:集合通信里的多卡归约接口

一文读懂 HCCL Reduce:集合通信里的多卡归约接口 【免费下载链接】runner-images GitHub Actions runner images 项目地址: https://gitcode.com/GitHub_Trending/ru/runner-images HcclReduce 是 HCCL 集合通信中的归约算子:多台 NPU 各持一份数…

2026/9/12 2:29:35

基于YOLOv5与Dlib的疲劳驾驶检测系统:从目标框选到PERCLOS判定

简介:这份基于YOLOv5、dlib与OpenCV的疲劳驾驶检测完整项目,面向正在准备毕业设计或课程设计的计算机专业学生,也适合需要实战练习的开发者。整套方案包含算法源代码、预训练权重文件与详细文档,从人脸关键点定位、眼部纵横比计算…

2026/9/12 2:29:34

下水道缺陷检测实战:从CCTV图像预处理到YOLOv8部署

简介:这是一份面向计算机视觉学习者和工业检测从业者的下水道管道缺陷检测项目包,聚焦图像视觉在管道堵塞、裂缝、渗漏识别中的应用。项目以Python算法实现为核心,涵盖normalizeRGB、circularMask、arcDetect、Main等模块,涉及灰度…

2026/9/12 2:29:34

MediaPipe+Kalidokit:零基础构建实时面部捕捉驱动3D角色

简介:这套基于MediaPipe与Kalidokit的面捕软件源码,配套VRM模型、文档说明与前端工程文件,主要面向虚拟主播、数字人交互等实时面部捕捉场景,适合计算机相关专业学生用于毕业设计、课程设计或项目初期演示,也适合希望快…

2026/9/12 2:29:34

基于YOLOv8与OpenCV的柚子缺陷检测项目实战

简介:这是一套基于Python的柚子缺陷检测项目,包含完整源码与项目文档,主要面向毕业设计、课程设计与实战开发场景。项目核心思路是利用水果坏损区域呈现黑色、与正常表皮颜色差异明显的特征,通过饱和度分析提取柚子表皮黑色斑块&a…

2026/9/12 2:24:34

Java+Vue超市管理系统实战:高校实训轻量部署方案

简介:本资源是面向高校计算机专业学生与Web全栈初学者的超市管理系统课程设计实践项目,基于Java后端、Vue前端及HTML/JavaScript技术栈完整实现湖北工业大学超市管理业务场景,涵盖商品管理、库存统计、员工权限与基础订单流程。压缩包共240个…

2026/9/12 2:05:33

超人会飞不算本事:系统稳定依赖清晰规则与边界设计

开头先不绕弯子。“#斯坦李吐槽dc 所以超人是无缘无故会飞的嘛哈哈哈哈哈哈哈锤哥真是技术人才啊!#雷神 #复联”这类调侃式短标题,第一波冲击力在于它把两个宇宙的角色塞进同一个吐槽箱里,但细想一下就能发现,它真正碰到的根本不是…

2026/9/10 11:16:38

超人VS蜘蛛侠:拆解超级IP的影响力与传播方法论

把“蜘蛛侠 vs 超人”放在 CSDN 上聊,可能很多人第一反应是走错片场了。但如果把这两个角色看成“两个持续运营了 80 多年的文化产品”,你会发现,这场比较本质上是两个不同 IP 策略的长期结果对比:超人赢在定义了整个超级英雄题材…

2026/9/9 16:31:09

基于CNN的调制信号识别:MATLAB实现时频图分类实战

简介:本资源是一套面向通信工程与信号处理方向学习者、研究者的深度学习实践方案,聚焦调制信号自动检测与识别这一典型无线通信任务,解决传统方法依赖人工特征、低信噪比下性能下降等痛点。压缩包共12个文件(10.73MB)&…

2026/9/12 0:04:17

MATLAB仿生优化框架:长鼻浣熊算法多策略融合实现

简介:本资源是一份面向智能优化算法研究者与MATLAB初学者的仿生智能算法实践代码包,聚焦于长鼻浣熊优化算法(COA)的多策略改进与性能验证。针对传统COA易陷局部最优、收敛精度不足等问题,作者融合Circle映射初始化提升…

2026/9/12 0:04:17

【JAVA毕设源码分享】基于 JavaWeb 的校园一卡通管理系统的设计与实现 基于 JavaWeb 的校园卡业务管理系统(程序+文档+代码讲解+一条龙定制)

博主介绍:✌️码农一枚 ,专注于大学生项目实战开发、讲解和毕业🚢文撰写修改等。全栈领域优质创作者,博客之星、掘金/华为云/阿里云/InfoQ等平台优质作者、专注于Java、小程序技术领域和毕业项目实战 ✌️技术范围:&am…

2026/9/12 0:04:17

【JAVA毕设源码分享】基于 Java 的图书馆借阅管理平台的搭建与实现 基于 Java 的图书馆综合管理系统(程序+文档+代码讲解+一条龙定制)

博主介绍:✌️码农一枚 ,专注于大学生项目实战开发、讲解和毕业🚢文撰写修改等。全栈领域优质创作者,博客之星、掘金/华为云/阿里云/InfoQ等平台优质作者、专注于Java、小程序技术领域和毕业项目实战 ✌️技术范围:&am…

2026/9/10 12:32:02

USB Type-C PCB布局分区设计:电源、高速信号与PD协议全攻略

做硬件这行,Type-C接口算是典型的“看着简单,做起来全坑”的东西。光引脚就24个,高低速信号、电源、控制线全部塞在一个小小的连接器里,如果PCB布局不做规划,打样回来基本就是“插上没反应”、“高速掉线”、“静电一打…

2026/9/10 15:19:50

系统编程学习原型如何补齐稳定性边界

系统编程学习原型如何补齐稳定性边界预算有限时&#xff0c;我先优化明显多余的复制&#xff0c;而不是猜测性地换容器。用借用传递只读数据通常就能减少分配&#xff1a; fn parse(line: &str) -> Result<Item, Error> { /* ... */ }用基准确认热点确实在分配&am…

2026/9/10 15:49:53

雨花区哪家财务公司代理记账比较好?

在雨花区&#xff0c;企业处理财税事务常常面临诸多挑战&#xff0c;选择一家靠谱的财务公司至关重要。湖南巨勤财务管理咨询有限公司就是本地正规实体财税服务机构&#xff0c;深耕本地工商财税行业多年&#xff0c;熟悉当地工商局、税务局最新政策与申报流程。主营公司注册、…

还想了解更多?直接咨询顾问

免费诊断 + 免费方案 + 透明报价。

全国咨询热线400-8866-253
免费获取方案
咨询二维码