law-kb/run.md

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 数据准备

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 确认依赖服务

# 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 全量构建

# [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 增量构建

# [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 索引验证

# [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 启动服务

# [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 停止服务

docker stop law-kb

4.3 重启服务

docker restart law-kb

4.4 查看日志

docker logs law-kb --tail 50
docker logs -f law-kb

---

五、构建与部署

5.1 构建镜像

# 在 114 上构建
cd /data/project/law-kb  # 或项目实际路径
docker build -t law-kb:latest .

5.2 一键部署

# 使用部署脚本(本机执行,自动 rsync + 构建 + 启动)
bash scripts/deploy.sh

---

六、备份与恢复

6.1 备份索引

# 索引文件可独立备份(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 恢复索引

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)。