freedak
641e33b834
- 语义检索(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>
248 lines
6.3 KiB
Markdown
248 lines
6.3 KiB
Markdown
# 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)。
|