在 Lab4AI 上部署 LightLLM 并用 LlamaIndex 搭建法律 RAG 智能体

大语言模型在专业场景落地时，最常被诟病的两点是知识静态滞后与专业内容幻觉。法律、医疗这类强合规领域对答案的准确性要求很高，模型凭记忆作答很容易给出过时或凭空捏造的结论。检索增强生成（RAG）的思路是让模型在生成答案之前先检索外部知识库，把检索到的权威资料作为上下文输入模型，从而缓解这两个问题。但 RAG 真正跑起来之后，新的瓶颈出现在推理侧：在有限的硬件资源下，如何做到低延迟、高吞吐的推理。

LightLLM 是一个纯 Python 实现的大语言模型推理与服务框架，聚焦轻量化部署与推理优化，通过内存管理、算子融合、多进程协同等手段提升运行速度，并支持多种模型规模与量化策略。本文要做的，是在 Lab4AI 平台上复现「LightLLM + LlamaIndex 法律智能体」这个项目：用 LightLLM 起一个本地推理服务，用 LlamaIndex 构建基于私有文档的检索增强生成应用，用 Streamlit 提供交互页面，最终得到一个可以上传本地知识库并针对法律问题作答的文档搜索助手。

这篇教程适合三类读者：想理解 RAG 中检索与生成如何协同的学习者；需要在资源受限环境下部署推理服务的中小团队开发者；以及希望用真实业务文档验证轻量化 RAG 方案可行性的实践者。阅读前需要对 Python 虚拟环境、命令行操作和 HTTP 服务有基本概念，不需要提前熟悉 LightLLM 的内部实现。

准备工作

账号与项目入口

整个流程在 Lab4AI 平台上完成，不需要自备 GPU 机器。前置条件只有一项：拥有可登录的 Lab4AI 账号。登录之后，在平台的「项目复现」板块中找到名为「构建 LightLLM + LlamaIndex 法律智能体」的项目，进入该项目即可获得预置好的运行环境。

平台的价值主要体现在环境准备这一环。如果从零手工搭建，需要完成的事情包括：从 LightLLM 仓库获取源代码并安装项目所需的全部 Python 依赖；在 Conda 环境中安装 LlamaIndex，用于构建基于私有数据的 RAG 应用；安装 Streamlit，用于快速创建交互式网页应用；安装 LightLLM 运行所需的计算机视觉处理库与 WebSocket 通信支持依赖；以及安装 LlamaIndex 对 HuggingFace 本地嵌入模型的支持包。这些依赖彼此之间存在版本约束，逐项安装耗时且容易出错。项目环境已经把这些依赖打包好，进入项目后可以直接开始部署，把精力放在实验本身而不是环境排错上。

环境与目录约定

项目自带一个名为 lightllm 的 Conda 环境。实际实验时不要直接在这个基础环境里操作，而是基于它创建一个完全相同的副本环境，命名为 lightllm-exp。这样做的好处是基础环境保持干净，实验过程中的改动、日志和临时文件都隔离在副本里，需要重来时删掉副本重建即可，不必重新配置依赖。

部署命令中会出现两个路径，需要提前确认它们与项目中的实际位置一致：

模型目录：/workspace/codelab/基于LightLLM结合LlamaIndex构建法律智能体/model/Qwen3-8B，这是项目预置的 Qwen3-8B 模型权重所在位置。
日志目录：./output_dirs/logs，部署脚本会在当前工作目录下创建它，并把服务输出写入带时间戳的日志文件。

另外需要确认 Streamlit 应用文件 app.py 的位置，后面的启动命令默认它在当前目录下执行。如果项目结构把应用放在子目录里，启动前先切换到对应目录，或者把命令中的文件名改成相对路径。

依赖构成说明

了解环境里装了什么，有助于后面排查问题。项目环境大致包含以下几类组件：

组件	作用
LightLLM	大模型推理与服务框架，提供 HTTP 推理接口
LlamaIndex	构建 RAG 应用，负责文档加载、切分、索引与检索
Streamlit	快速搭建交互式网页界面
计算机视觉处理库	LightLLM 运行所需的多模态相关依赖
WebSocket 通信支持包	LightLLM 服务通信所需
HuggingFace 嵌入模型支持包	让 LlamaIndex 能加载本地嵌入模型

这些依赖的具体版本会随项目更新而变化，安装前请以平台项目页与各组件官网当前信息为准。

操作步骤

第一步：创建实验环境副本

进入项目后，先基于现有的 lightllm 环境创建一个完全相同的副本环境 lightllm-exp。创建完成后激活该副本环境，后续所有命令都在这个环境中执行。这一步是隔离实验改动的前提，跳过它会让基础环境被污染，后续复现其他项目时可能出现依赖冲突。

第二步：启动 LightLLM 推理服务

在副本环境中执行部署命令。命令会先创建日志目录，再以 nohup 方式在后台启动 LightLLM 的 API 服务，并把标准输出与标准错误都重定向到带时间戳的日志文件：

mkdir -p ./output_dirs/logs
LOG_FILE="./output_dirs/logs/lightllm_$(date +'%Y%m%d_%H%M%S').log"
nohup python -m lightllm.server.api_server \
  --enable_fa3 \
  --model_dir /workspace/codelab/基于LightLLM结合LlamaIndex构建法律智能体/model/Qwen3-8B \
  > "$LOG_FILE" 2>&1 &

命令中的几个部分各自承担明确职责：

mkdir -p ./output_dirs/logs：创建日志目录，-p 保证目录已存在时不会报错。
LOG_FILE=...：用当前日期时间生成日志文件名，格式为 lightllm_年月日_时分秒.log。每次启动都会产生独立日志，便于对比不同次启动的输出。
python -m lightllm.server.api_server：以模块方式启动 LightLLM 的 API 服务。
--enable_fa3：启用 FlashAttention 3 相关加速路径。
--model_dir：指定模型权重目录，这里指向项目预置的 Qwen3-8B。
nohup ... &：让服务在后台运行，退出终端后不中断。

启动后不要立刻认为服务已经就绪。模型加载需要时间，尤其是 8B 规模的模型。判断服务是否正常，可以查看日志文件末尾的输出，确认没有报错并且出现服务监听相关的信息；也可以直接访问服务地址，看是否返回正常响应。服务正常启动后，页面会呈现可用的推理接口状态。

如果日志里出现显存不足、模型路径不存在或依赖缺失之类的错误，先检查模型目录是否与命令中一致，再确认当前激活的是 lightllm-exp 副本环境而不是其他环境。

第三步：启动 Streamlit 前端页面

推理服务在后台跑起来之后，启动 RAG 文档搜索助手的前端。在项目目录下执行：

streamlit run app.py \
  --server.address 0.0.0.0 \
  --server.port 6666 \
  --server.enableCORS false \
  --server.enableXsrfProtection false

各参数的含义如下：

--server.address 0.0.0.0：监听所有网络接口，这样平台的外部访问入口才能把请求转发进来。如果只监听 127.0.0.1，从浏览器侧将无法打开页面。
--server.port 6666：指定服务端口为 6666，与平台对外服务配置的端口保持一致。
--server.enableCORS false：关闭跨域限制。
--server.enableXsrfProtection false：关闭 XSRF 防护，避免在平台代理转发场景下出现请求被拦截的问题。

这两个安全选项被关闭，是为了适配平台的反向代理访问方式，属于实验环境的配置。如果要把这套应用搬到真实对外环境，应当重新评估这两个选项，不要直接沿用。

第四步：通过对外服务打开页面

Streamlit 启动后，在平台的「对外服务」入口中找到对应的服务链接，复制该链接并在浏览器中打开。点击服务链接后，会进入本地的 RAG 文档搜索助手页面。页面能够正常渲染，说明前端与后端推理服务之间的链路已经打通。

如果页面打不开，按顺序排查：Streamlit 进程是否仍在运行；端口是否与对外服务配置一致；推理服务是否已经就绪。前端能打开但提问无响应，问题通常出在推理服务侧，回到日志文件里找线索。

第五步：构建知识库并提问

服务部署完成后，就可以在页面上自定义构建知识库，并基于库内信息查询相关问题。操作顺序是：上传本地知识库文件，等待文档被解析、切分并建立索引，然后在输入框中提出与文档内容相关的问题，系统会先检索知识库中相关片段，再把这些片段作为上下文交给模型生成答案。

这一步是整个方案的核心验证点。RAG 的效果取决于检索质量与生成质量两个环节：检索环节由 LlamaIndex 负责，把上传的文档转成可检索的索引；生成环节由 LightLLM 承载的 Qwen3-8B 负责，根据检索到的上下文组织回答。两个环节任何一处出问题，最终答案都会失真。

一个完整示例

下面用一个劳动争议场景把整个流程串起来，从启动服务到拿到答案，走一遍最小可运行路径。

场景设定：用户手上有考勤记录截图和与领导沟通加班的微信记录。劳动合同写明月薪 8000 元，但公司一直按基本工资 3000 元为基数计算加班费。用户想主张最近一年的加班费差额，需要知道这类主张在法律上如何成立、需要准备哪些证据。

第一步，准备环境。登录 Lab4AI，进入「项目复现」中的「构建 LightLLM + LlamaIndex 法律智能体」项目，基于 lightllm 环境创建副本环境 lightllm-exp 并激活。

第二步，启动推理服务。在副本环境中执行前面给出的部署命令，把 Qwen3-8B 的推理服务放到后台运行，日志写入 ./output_dirs/logs/ 下带时间戳的文件。等待模型加载完成，确认服务状态正常。

第三步，启动前端。执行 Streamlit 启动命令，监听 0.0.0.0 的 6666 端口，关闭 CORS 与 XSRF 防护。

第四步，打开页面。在「对外服务」中复制链接，在浏览器打开，进入 RAG 文档搜索助手页面。

第五步，上传知识库。把与劳动法、加班费计算基数、举证责任相关的法规文本、司法解释或整理好的资料文件上传到知识库，等待索引构建完成。

第六步，提问。在输入框中输入类似这样的问题：「我有考勤记录截图和与领导沟通加班的微信记录。劳动合同写的是月薪 8000 元，但公司一直按基本工资 3000 元为基数算加班费。我主张最近一年的加班费差额，需要哪些证据，法律依据是什么？」

第七步，检查回答。观察返回的答案是否引用了知识库中的内容、是否围绕加班费计算基数与举证责任展开。如果答案空泛或与上传资料无关，说明检索环节没有命中有效片段，需要检查文档格式是否被正确解析、问题表述是否与文档内容存在足够的语义关联。

这个示例的意义在于验证「轻量化 RAG 技术」在实际业务环境中的可行性：通过构建外部文档库、数据库或知识管理系统，让模型在生成答案前先检索最新且权威的资料，把检索结果作为上下文输入模型。借助 LightLLM 的高效推理与扩展能力，可以在单机环境下支撑起专业级的法律智能服务，明显缓解模型知识滞后与幻觉的问题。

注意事项

服务启动与日志

推理服务是后台进程，启动命令返回不代表服务已就绪。模型加载期间请求会失败，务必先看日志确认服务可用，再进行前端提问。
日志文件名带时间戳，多次启动会产生多个文件。排查问题时先确认自己看的是最近一次启动对应的日志。
如果服务启动失败后重新执行命令，先确认旧进程是否已经退出，避免端口被占用导致新进程启动失败。

环境隔离

始终在 lightllm-exp 副本环境中操作，不要在基础 lightllm 环境中直接安装或修改依赖。基础环境被污染后，后续复现其他项目可能遇到难以定位的依赖冲突。
实验出现无法解释的异常时，删除副本环境重建，往往比逐项排查依赖更快。

网络与安全配置

--server.address 0.0.0.0 与关闭 CORS、XSRF 的组合是为平台代理访问准备的。在非受控网络中暴露同样配置会带来安全风险，迁移到其他环境时应重新配置。
端口 6666 需要与平台对外服务配置保持一致，改端口后要同步更新对外服务设置，否则页面无法访问。

RAG 效果相关

答案质量高度依赖知识库内容。上传的资料如果与问题领域不匹配，或者文档解析后文本质量差，检索环节就难以命中有效片段。
问题表述尽量具体，把事实要素写清楚，比笼统提问更容易检索到相关法条与解释。
模型生成的内容仅作为参考，法律等专业场景的实际判断应以现行法规与专业人士意见为准，不要把系统输出直接当作结论使用。

可迁移性

这套架构具备较高的可复用性。法律场景只是其中一个验证方向，同样的组合可以迁移到金融、医疗、政务等强知识依赖的领域：替换知识库内容、调整检索与提示策略，就能形成稳定、可解释、可扩展的行业方案。迁移时需要注意的是，不同领域对答案准确性的容忍度不同，知识库的权威性与更新频率也需要相应提高。

易变信息提示

本文涉及的模型版本、依赖包版本、平台功能与资源配额都可能随时间调整，实际操作时请以 Lab4AI 平台项目页与相关组件官网的当前信息为准。