freedak/law-kb
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: QYLAW 法律法规知识库

Browse Source 
- 语义检索(FAISS + embedding)+ 精确查找(法规名+条号)
- RAG 问答(SSE 流式,支持 thinking 折叠显示)
- 法规浏览(原文阅读)
- 历史记录(检索+对话持久化到 SQLite)
- 设置页(系统提示词/模板/LLM 参数可配置)
- 检索质量评估脚本

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
This commit is contained in:
freedak
2026-08-07 14:55:25 +08:00
commit 641e33b834
39 changed files with 5254 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
run.md
+247
View File
@@ -0,0 +1,247 @@
# run.md — QYLAW 法律法规知识库 运行手册
> 项目:QYLAW 法律法规知识库
> 部署:192.168.110.114 (Docker, --network host)
> 更新:2026-08-06
---
## 一、技术栈
| 项目 | 版本/说明 |
|------|------|
| 后端 | Python 3.11 + FastAPI + Uvicorn |
| 向量库 | FAISS (faiss-cpu, HNSW 索引) |
| metadata | SQLite (Python 内置 sqlite3) |
| 向量化 | Qwen3-Embedding-0.6B (114:8003, 复用) |
| RAG 生成 | Qwen3.5-35B (114:7000, 复用) |
| 前端 | HTML + Vanilla JS + Tailwind CDN |
| 部署 | Docker (--network host) |
| 端口 | 8090 |
---
## 二、首次准备
### 2.1 数据准备
```bash
ssh nvidia@192.168.110.114
# 密码: qy123.
# 确认 law-pack 已传输到 114
ls /data/law-pack-2026-07-01-markdown/
# 预期: 法律/ 行政法规/ 监察法规/ 司法解释/ 地方性法规/ 地方性法规区域映射.json
# 若不存在,从本机 rsync 传输(310MB)
# 在本机执行:
rsync -avz --progress /Users/freedak/Documents/AIDashboard/qy123/law-pack-2026-07-01-markdown/ \
nvidia@192.168.110.114:/data/law-pack-2026-07-01-markdown/
# 创建索引数据目录
mkdir -p /data/law-kb-data/faiss /data/law-kb-data/logs
```
### 2.2 确认依赖服务
```bash
# embedding 服务(8003)
curl -s http://localhost:8003/v1/models | python3 -m json.tool
# qwen35 服务(7000)
curl -s http://localhost:7000/v1/models | python3 -m json.tool
```
---
## 三、索引构建
### 3.1 全量构建
```bash
# [Docker] 在容器内执行(构建脚本需要访问 embedding 服务)
docker run --rm --network host \
-v /data/law-pack-2026-07-01-markdown:/data/law-pack-2026-07-01-markdown:ro \
-v /data/law-kb-data:/data/law-kb-data \
law-kb:latest \
python scripts/build_index.py --mode full
# [Native] 本地直接执行(需已安装依赖)
cd law-kb
python scripts/build_index.py --mode full
```
**输出示例**:
```
============================================
QYLAW 索引构建 — 全量模式
时间: 2026-08-06 14:00:00
============================================
扫描目录: /data/law-pack-2026-07-01-markdown
[法律] 349 文件, 切片 12500 条
[行政法规] 606 文件, 切片 28000 条
...
跳过文件(null 映射): 23 篇
总切片: 520000 条
向量维度: 1024
FAISS 索引大小: 1.2 GB
耗时: 2.5 小时
索引文件: /data/law-kb-data/faiss/index.faiss
SQLite: /data/law-kb-data/metadata.db
============================================
```
### 3.2 增量构建
```bash
# [Docker]
docker run --rm --network host \
-v /data/law-pack-2026-07-01-markdown:/data/law-pack-2026-07-01-markdown:ro \
-v /data/law-kb-data:/data/law-kb-data \
law-kb:latest \
python scripts/build_index.py --mode incremental
```
### 3.3 索引验证
```bash
# [Docker]
docker run --rm --network host \
-v /data/law-pack-2026-07-01-markdown:/data/law-pack-2026-07-01-markdown:ro \
-v /data/law-kb-data:/data/law-kb-data \
law-kb:latest \
python scripts/verify_index.py
```
---
## 四、应用启停
### 4.1 启动服务
```bash
# [Docker] 启动 law-kb 容器
docker run -d --name law-kb --network host \
--restart unless-stopped \
-v /data/law-pack-2026-07-01-markdown:/data/law-pack-2026-07-01-markdown:ro \
-v /data/law-kb-data:/data/law-kb-data \
law-kb:latest
# 验证
curl -s http://localhost:8090/health
curl -s http://localhost:8090/api/stats | python3 -m json.tool
```
### 4.2 停止服务
```bash
docker stop law-kb
```
### 4.3 重启服务
```bash
docker restart law-kb
```
### 4.4 查看日志
```bash
docker logs law-kb --tail 50
docker logs -f law-kb
```
---
## 五、构建与部署
### 5.1 构建镜像
```bash
# 在 114 上构建
cd /data/project/law-kb # 或项目实际路径
docker build -t law-kb:latest .
```
### 5.2 一键部署
```bash
# 使用部署脚本(本机执行,自动 rsync + 构建 + 启动)
bash scripts/deploy.sh
```
---
## 六、备份与恢复
### 6.1 备份索引
```bash
# 索引文件可独立备份(FAISS + SQLite)
ssh nvidia@192.168.110.114
tar -czf /data/backup/law-kb-index-$(date +%Y%m%d).tar.gz \
-C /data/law-kb-data faiss/ metadata.db
```
### 6.2 恢复索引
```bash
ssh nvidia@192.168.110.114
docker stop law-kb
tar -xzf /data/backup/law-kb-index-YYYYMMDD.tar.gz -C /data/law-kb-data/
docker start law-kb
```
---
## 七、排错
| 问题 | 原因 | 解决方案 |
|------|------|------|
| 启动后 stats 返回 ready=false | 索引未构建 | 执行全量构建(三、3.1) |
| 检索返回 503 | embedding 服务未启动 | `docker ps` 确认 embedding 容器运行 |
| RAG 返回 503 | qwen35 服务未启动 | `docker ps` 确认 qwen35 容器运行 |
| RAG 返回 no_result | 相似度低于阈值(0.3) | 检查索引质量或调整问题表述 |
| 构建脚本 OOM | 切片数过多内存不足 | 减小 EMBEDDING_BATCH_SIZE |
| 容器无法访问 8003/7000 | 未用 --network host | 确认启动命令含 `--network host` |
---
## 八、端口表
| 端口 | 服务 | 类型 | 说明 |
|------|------|------|------|
| 8090 | law-kb | HTTP | QYLAW 知识库 Web + API |
| 8003 | embedding | HTTP | 向量化服务(复用) |
| 7000 | qwen35 | HTTP | RAG 生成服务(复用) |
---
## 九、环境变量
| 变量 | 默认值 | 说明 |
|------|------|------|
| `LAW_PACK_DIR` | /data/law-pack-2026-07-01-markdown | 法规原文目录 |
| `LAW_KB_DATA_DIR` | /data/law-kb-data | 索引数据目录 |
| `EMBEDDING_URL` | http://localhost:8003/v1 | embedding 服务地址 |
| `LLM_URL` | http://localhost:7000/v1 | LLM 服务地址 |
| `EMBEDDING_MODEL` | qwen3-embedding-0.6b | embedding 模型名 |
| `LLM_MODEL` | qwen3.5-35b | LLM 模型名 |
| `EMBEDDING_BATCH_SIZE` | 32 | embedding 批量大小 |
| `APP_PORT` | 8090 | 应用端口 |
---
## 十、FAQ
**Q: 为什么用 --network host?**
A: 容器需要访问 114 本地的 8003(embedding)和 7000(qwen35)端口。host 网络模式下容器直接用宿主网络,无需 --add-host 或端口映射,最简配置。内网环境无安全顾虑。
**Q: 索引构建中断了怎么办?**
A: 构建脚本先写临时文件,成功后原子替换。中断不会损坏已有索引。直接重跑即可。
**Q: 地方性法规 null 映射文件如何补?**
A: 编辑 `地方性法规区域映射.json` 补充映射,然后执行增量构建。
**Q: 如何更新法规数据?**
A: 替换 `/data/law-pack-2026-07-01-markdown/` 下的文件,执行增量构建(三、3.2)。