本项目实现了一个基于LangChain框架的劳动与社会保障法律法规领域的智能问答系统，结合RAG（检索增强生成）与ReAct 风格智能体两大核心能力，底层使用DeepSeek大模型与Tavily联网搜索，提供专业、可靠、可解释的法律咨询服务。
系统提供两套交互入口：
- 🖥️ Web 界面（推荐） — 基于 Streamlit 的现代化交互界面
- 💻 命令行模式 — 终端交互式问答
| 能力 | 说明 |
|---|---|
| 三模检索 | 关键词 / 语义 / 混合（RRF 融合）可切换 |
| 向量检索 | Chroma + HuggingFace Embedding 语义召回 |
| RRF 融合 | 倒数排名融合算法，同时利用词法 + 语义通道 |
| 文档解析 | 支持 PDF / DOCX / TXT / MD 多格式 |
| 自动分块 | chunk_size=500，overlap=50，保留上下文 |
| 来源追溯 | 引用知识库文档，输出可溯源 |
| 联网增强 | 可选启用 Tavily 搜索，融合最新法规政策 |
| 多会话记忆 | 每会话独立上下文窗口，默认 10 轮 |
- LangGraph ReAct 风格推理与任务规划
- 三大核心工具：
- 📚
knowledge_search— 在劳动法知识库中检索法律条文与实务信息 - ⚖️
legal_calculator— 劳动法专项赔偿计算器（经济补偿金 N、违法解除 2N、加班费、年假补偿） - 🔍
web_search— 基于 Tavily 的联网检索最新法规政策
- 📚
- 流式输出：推理过程（工具调用+结果）与最终答案分步呈现
- 深度思考模式：先分析再检索，多角度 + 交叉验证 + 精确计算 + 结构化报告
- 可开关的思考链生成（目标 → 法规 → 方案 → 风险）
- 思考过程与最终答案分开展示、可折叠
- 实时流式输出，过程透明
- 多文件批量上传（PDF / DOCX / TXT / MD）
- 自动解析 → 写入
knowledge_base/→ 刷新索引 - 文件列表展示、单文件删除与批量删除
- 上传/删除后提示重启以完成初始化
- Radio 导航栏：📖 知识问答 / 🤖 智能体 / 📁 文件上传（固定顶部）
- 固定底栏输入区，检索模式 / 联网搜索 / 深度思考复选框内置，长对话不丢视野
- 浅色 / 深色模式自适应（JS 实时监听）
- 侧边栏系统状态可视化、对话记忆管理、一键清空
- 启动时书本翻页加载动画，上传/删除后一键重启对话框
- 关于页面（Lex Laboris 品牌页）：侧边栏使用说明图标可打开独立页面
┌────────────────────────────────────────────────────────┐
│ 用户交互层 │
│ Streamlit Web 界面 / 命令行终端 (main.py) │
└────────────────┬───────────────────────┬───────────────┘
│ │
┌────────▼─────────┐ ┌────────▼─────────┐
│ RAG 模块 │ │ Agent 模块 │
│ (rag_module.py) │ │ (agent_module.py)│
│ │ │ │
│ • 关键词检索 │ │ • ReAct 推理 │
│ • 语义检索 │ │ • 工具调用 │
│ • RRF 融合 │ │ • 流式输出 │
└────────┬─────────┘ └────────┬─────────┘
│ │
└───────────┬───────────┘
│
┌────────────────────┼────────────────────┐
│ │ │
┌────▼─────┐ ┌───────▼───────┐ ┌───────▼──────┐
│ DeepSeek │ │ Chroma DB │ │ Tavily │
│ LLM │ │ 向量库 │ │ 联网搜索 │
└──────────┘ └───────────────┘ └──────────────┘
| 类别 | 选型 |
|---|---|
| LLM 框架 | LangChain 0.3.30 |
| 大语言模型 | DeepSeek Chat（deepseek-chat） |
| 向量数据库 | Chroma 0.4.24（langchain-chroma 0.1.0） |
| Embedding | paraphrase-multilingual-MiniLM-L12-v2（多语言 384 维） |
| 检索策略 | 关键词 / 语义 / RRF 混合 |
| 联网搜索 | Tavily Search API |
| Web 框架 | Streamlit 1.54.0 |
| 文档解析 | pypdf、python-docx |
| 运行环境 | Python 3.10+（已在 3.13.7 验证） |
git clone <your-repo-url>
cd llm-qa-system
# 创建虚拟环境（推荐）
python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux / macOS
source .venv/bin/activate
# 安装依赖
pip install -r requirements.txt在根目录编辑 .env 文件（可参考下方 配置说明）：
# 必填
DEEPSEEK_API_KEY=your_deepseek_api_key_here
TAVILY_API_KEY=your_tavily_api_key_here
# 可选（默认值已可用）
DEEPSEEK_API_BASE=https://api.deepseek.com
HF_ENDPOINT=https://hf-mirror.com # 国内推荐🖥️ 方式一：启动脚本（Windows 推荐）
双击项目根目录的 start.bat，在菜单中选择 1（Web 界面）或 2（命令行模式）即可。
启动脚本
start.bat会自动调用同目录下的start.ps1，无需额外配置。首次运行如遇 PowerShell 执行策略限制，脚本已内置-ExecutionPolicy Bypass参数。
🖥️ 方式二：Web 界面（命令行）
streamlit run app.py启动后默认访问 http://localhost:8501
💻 方式三：命令行模式
python main.py根据菜单提示选择 1（知识问答）或 2（智能体任务），输入 0 退出。
🌐 同网段设备访问（手机/同 WiFi 的其他电脑访问本机服务）
第 1 步：启动时绑定到所有网卡
streamlit run app.py --server.address 0.0.0.0 --server.port 8501第 2 步：查看本机 IP
- Windows：
ipconfig（查看IPv4 地址）- Linux / macOS：
ifconfig或ip addr第 3 步：同网段设备在浏览器中访问
http://<本机IP>:8501
⚠️ 注意事项：
- 手机/其他设备必须与本机连接同一 WiFi / 局域网
- 如被 Windows 防火墙拦截，首次访问会弹出"是否允许"提示，请选择允许
- 若路由器开启了 AP 隔离，跨设备访问会被禁用，请关闭 AP 隔离
llm-qa-system/
├── start.bat # Windows 一键启动脚本（推荐）
├── start.ps1 # PowerShell 启动脚本
├── main.py # 命令行入口
├── app.py # Streamlit Web 界面
├── config.py # 配置加载与校验
├── requirements.txt # 依赖清单
├── README.md # 项目说明
├── LICENSE # GPL-3.0 开源协议
├── .gitignore # Git 忽略规则
├── .env # 环境变量（API Key 等）
├── .restart_marker # 重启标记文件（运行时生成）
│
├── modules/
│ ├── __init__.py
│ ├── rag_module.py # RAG 知识问答模块
│ ├── agent_module.py # Agent 智能体模块
│ └── tools.py # 工具定义：知识库检索 / 赔偿计算器 / 联网搜索
│
├── knowledge_base/ # 法律知识库（自动加载）
│ ├── labor_law_overview.md # 劳动法总览
│ ├── labor_contract.md # 劳动合同
│ ├── labor_dispute.md # 劳动争议
│ ├── social_security.md # 社会保险
│ ├── female_protection.md # 女职工特殊保护
│ ├── housing_fund.md # 住房公积金
│ └── judicial_interpretations.md # 司法解释
│
├── static/ # 静态资源
│ ├── about.html # 关于页面（Lex Laboris 品牌页）
│ └── book-loader.html # 启动加载动画（书本翻页效果）
│
├── chroma_db/ # Chroma 向量库持久化（首次运行后生成）
├── models_cache/ # Embedding 模型本地缓存
└── uploads/ # 上传文件临时目录（运行时生成）
- 启动时自动加载
knowledge_base/下所有文档 - 在「📖 知识问答」Tab 输入法律相关问题
- 可在底部下拉菜单切换检索模式（混合 / 语义 / 关键词）
- 系统检索 Top-K 文档并结合 DeepSeek 生成答案
- 勾选「🌐 联网搜索」可融合最新法规
- 支持上下文连续多轮问答
- 在「🤖 智能体」Tab 输入复杂任务（如案件分析、赔偿计算、维权方案）
- Agent 会自动调用知识库检索、赔偿计算器、联网搜索等工具
- 勾选「🧠 深度思考」启用多角度检索+交叉验证+精确计算的结构化分析
- 勾选「🌐 联网搜索」允许 Agent 联网获取最新法规
- 推理过程（含工具调用与结果）与最终答案分开展示，可折叠查看
- 进入「📁 文件上传」Tab
- 选择 PDF / DOCX / TXT / MD 文件（支持多选），点击「📥 上传并添加到知识库」
- 上传后提示重启，一键完成初始化
- 已有文件可单文件删除或批量删除，删除后同样提示重启
- 侧边栏查看两个 Tab 的对话轮数
- 点击「🗑️ 清空所有对话记忆」可一键重置
- 最大记忆轮数默认为 10，可在
app.py中调整st.session_state.max_history
.env 文件完整配置项：
# ============ DeepSeek API ============
DEEPSEEK_API_KEY=your_deepseek_api_key_here
DEEPSEEK_API_BASE=https://api.deepseek.com
DEEPSEEK_CHAT_MODEL=deepseek-chat
DEEPSEEK_EMBEDDING_MODEL=deepseek-embedding
# ============ Tavily 搜索 API ============
TAVILY_API_KEY=your_tavily_api_key_here
# ============ 向量数据库（Chroma）=========
CHROMA_PERSIST_DIRECTORY=./chroma_db
COLLECTION_NAME=labor_law_kb
# ============ Embedding ============
EMBEDDING_PROVIDER=huggingface
EMBEDDING_MODEL_NAME=sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2
EMBEDDING_CACHE_DIR=./models_cache
EMBEDDING_DEVICE=cpu
HF_ENDPOINT=https://hf-mirror.com # 国内推荐 hf-mirror.com
# ============ RAG 检索 ============
CHUNK_SIZE=500
CHUNK_OVERLAP=50
TOP_K=5
SEARCH_MODE=hybrid # semantic / keyword / hybrid
SEMANTIC_TOP_K=8
KEYWORD_TOP_K=8
# ============ 知识库路径 ============
KNOWLEDGE_BASE_PATH=./knowledge_base
UPLOADS_PATH=./uploads
⚠️ DEEPSEEK_API_KEY与TAVILY_API_KEY为必填项。
获取 API Key：
| 服务 | 申请地址 |
|---|---|
| DeepSeek | https://platform.deepseek.com/api_keys |
| Tavily | https://tavily.com/ |
三种检索模式对比：
| 模式 | 说明 | 适用场景 |
|---|---|---|
keyword |
纯关键词 + 字符匹配 + 自研评分 | 精确术语检索（如法条编号） |
semantic |
Chroma + Embedding 余弦相似度 | 同义词 / 口语化表达召回 |
hybrid ⭐ |
RRF 融合关键词 + 语义 | 默认推荐，兼顾准确率与召回率 |
关键实现：
- 关键词评分：命中关键词 +3 分，子串匹配 +1 分，共现字符 +0.5 分
- 文本分块：
RecursiveCharacterTextSplitter（chunk_size=500，overlap=50） - RRF 公式：
score(d) = Σ 1 / (k + rank_i)，k=60 - 多会话：以
session_id为 key 隔离上下文，使用deque限制最大轮数 - 降级策略：Embedding 加载失败时自动切换为
keyword模式
三种检索模式效果对比：
| 查询 | 关键词 | 语义 | 混合（RRF） |
|---|---|---|---|
| 老板把我开了，n+1 怎么算 | ❌ | ✅ | ✅ 综合最优 |
| 养老保险的缴费比例 | ❌ | ✅ | ✅ 社保+补偿结合 |
| 试用期最长能签多久 | ✅ | ✅ 试用期条款优先 |
- LangGraph ReAct Agent：基于
create_agent构建，自动推理与工具调用循环 - 三大工具：
knowledge_search（知识库检索）、legal_calculator（劳动法赔偿计算器，Pydantic 结构化输入）、web_search（Tavily 联网搜索） - 两套系统提示：Agent 内置"法律小智"普通模式与深度分析模式两套 prompt
- 流式输出：通过
yield逐步返回thinking/tool_start/tool_end/answer事件 - 深度思考：Phase 1 生成结构化分析 → Phase 2 执行 ReAct Agent 工具调用
- 多会话管理：以
session_id为 key 隔离上下文，deque限制最大轮数
🙋 用户：养老保险的缴费比例是多少？企业需要缴纳多少？
⚖️ 助手：根据《社会保险法》及相关规定，基本养老保险由用人单位和职工共同缴纳：
- 用人单位：按本单位职工工资总额的 16%~20% 缴纳（具体比例由各省确定）
- 职工个人：按本人缴费工资的 8% 缴纳
- 灵活就业人员：按缴费基数的 20% 左右缴纳
【来源：knowledge_base/social_security.md】
🙋 用户：分析员工被无故辞退后的维权途径和注意事项
🤖 助手：
🔍 思考过程：
- 明确任务目标：员工被无故辞退，需要梳理维权途径
- 分析劳动法依据：《劳动合同法》第 39/40/41 条
- 评估维权途径：协商 → 调解 → 仲裁 → 诉讼
- 制定执行计划：收集证据 → 申请仲裁 → 准备诉讼
- 预判风险：仲裁时效 1 年，需注意证据保存
📋 最终答案：
- 【协商】与用人单位协商补偿
- 【调解】申请企业劳动争议调解委员会调解
- 【仲裁】向劳动人事争议仲裁委员会申请仲裁（必经程序）
- 【诉讼】对仲裁裁决不服可向法院起诉
注意事项：保留劳动合同、工资条、辞退通知等证据……
Q1：启动时报 DEEPSEEK_API_KEY 缺失？
A：请在 .env 中正确填写 Key，注意不要有多余空格。
Q2：联网搜索失败？
A：检查 TAVILY_API_KEY 是否有效，或临时取消勾选「🌐 联网搜索」。
Q3：知识库为空？
A：将法律文档放入 knowledge_base/ 目录，重启或点击「📥 上传并添加到知识库」。
Q4：流式输出卡顿？ A：网络不稳定时可能出现，可切换至非深度思考模式。
Q5：Embedding 模型下载失败？
A：国内网络可能超时，在 .env 中设置 HF_ENDPOINT=https://hf-mirror.com 使用国内镜像。
Q6：能否修改检索模式？
A：可以。在 .env 中将 SEARCH_MODE 修改为 hybrid（混合）/ semantic（语义）/ keyword（关键词）后重启即可。Web 界面也可在底部输入区通过下拉菜单实时切换检索模式。
Q7：能否换用更大的中文 Embedding 模型？
A：可以。修改 .env 中 EMBEDDING_MODEL_NAME：
BAAI/bge-small-zh-v1.5（512 维）BAAI/bge-base-zh-v1.5（768 维）shibing624/text2vec-base-chinese
- 🌐 网络要求：需要访问 DeepSeek 与 Tavily API
- 🔐 密钥安全：
.env文件请勿提交至公开仓库 - 📚 知识库维护：定期更新
knowledge_base/中的法律文档以保持时效性 - ⚖️ 免责声明：系统回答仅供参考，具体法律问题请咨询专业律师
- 💰 API 费用：DeepSeek 与 Tavily 均按调用计费，请关注额度
- 引入 ReAct Agent 自动工具调用循环（已通过 LangGraph
create_agent实现） - 增加用户登录与多租户隔离
- 引入 RAGAS 评估指标体系
- 支持 DeepSeek 自家的 Embedding API（替代本地模型）
项目维护者名称：YJY-XYYC GitHub 仓库地址：https://github.com/YJY-XYYC/Legal-Consultation-Assistant 问题反馈地址:https://github.com/YJY-XYYC/Legal-Consultation-Assistant/issues
⭐ 如果这个项目对你有帮助，欢迎 Star！