法律知识图谱 - Windows 本地部署指南

本说明介绍如何在 Windows 本地计算机上一键部署 Neo4j 法律知识图谱服务。部署完成后，直接通过 localhost 访问查询接口。

如果自动安装脚本执行失败，可参考 MANUAL-INSTALL.md 进行手动安装。

目录结构

├── app/                       # FastAPI 查询服务
│   ├── main.py                # FastAPI 服务主文件（GraphRAG + Text2Cypher）
│   ├── requirements.txt       # Python 依赖
│   ├── .env.template          # 环境变量模板
│   ├── .env                   # 实际环境变量（安装后生成）
│   ├── start.ps1              # 仅启动 API（安装后生成）
│   ├── start.bat              # 仅启动 API（安装后生成）
│   └── venv/                  # Python 虚拟环境（安装后生成）
├── data/                      # 法律知识图谱数据
│   ├── 法律/                  # 法律领域 CSV 数据
│   ├── 宪法/                  # 宪法领域 CSV 数据
│   ├── 行政法规/              # 行政法规 CSV 数据
│   ├── 司法解释/              # 司法解释 CSV 数据
│   ├── 地方法规/              # 地方法规 CSV 数据
│   ├── 监察法规/              # 监察法规 CSV 数据
│   └── import_*.cypher        # Cypher 导入脚本
└── scripts/                   # 自动化部署脚本
    ├── install.ps1            # Windows 本地一键部署脚本（PowerShell）
    ├── install.bat            # CMD 包装器，可直接双击运行
    ├── import_with_progress.py # Cypher 导入进度条助手（被 install.ps1 调用）
    ├── start-all.ps1          # 启动 Neo4j + API（安装后生成）
    └── start-all.bat          # 启动 Neo4j + API（安装后生成）

环境要求

• Windows 10/11
• **Java 21+**（Neo4j 2025.x 需要）
  • 下载地址：https://adoptium.net/
  • 若使用 Java 25，请选择 Neo4j 2025.10 或更高版本（脚本默认 2025.12.1 已支持）
• Python 3.10+
  • 下载地址：https://www.python.org/downloads/
  • 安装时建议勾选 “Add Python to PATH”
• LLM API Key（自然语言查询需要）
  • 默认使用 DeepSeek，可替换为 OpenAI / Kimi / DashScope / 本地 vLLM / Ollama

快速开始

1. 进入脚本目录

cd scripts

2. 运行部署脚本

方式 A：CMD 一键安装（推荐，双击可用）

直接双击 scripts\install.bat，无需打开终端。

• 如果系统没有 Java 21+ 或 Python 3.10+，脚本会自动静默安装。
• 如果没有设置任何 LLM API Key，脚本会自动使用本地 Ollama 提供商以完成零输入安装。
  • 后续使用自然语言查询前，需要单独安装并运行 Ollama。
  • 如需使用 DeepSeek 等在线模型，先设置环境变量再运行，或显式传入参数：

    scripts\install.bat -LlmProvider deepseek -DeepSeekApiKey "sk-..."

• 安装完成后会自动启动 Neo4j + FastAPI 服务并做健康检查。

需要交互式/高级安装请直接使用 .\setup.ps1 或 .\scripts\install.ps1。

方式 B：PowerShell

.\install.ps1

如果提示执行策略限制，可先运行：

Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process -Force

3. 交互式安装时按提示输入配置

如果直接运行 PowerShell 脚本（.\setup.ps1 或 .\scripts\install.ps1），脚本会先检查 Java、Python、数据目录等环境条件，并在解析/安装 Neo4j 之后弹出需要用户输入的配置信息。输入内容会在终端中显示，方便核对：

• Neo4j 密码：至少 8 位字符
• LLM 服务商：DeepSeek / OpenAI / Kimi / DashScope / 本地 vLLM / Ollama
• API Key：根据选择的服务商填写（本地模型可跳过）
• Base URL：模型服务地址（提供默认值，可直接回车）
• Model：模型名称（提供默认值，可直接回车）
• Temperature：LLM 温度参数（默认 0）

配置完成后会显示摘要，按回车继续部署。部署结束后会在项目根目录生成 deployment-info.txt，记录 Neo4j 密码等部署信息。

4. 完成部署

脚本共 10 个步骤，数据导入阶段会显示语句级进度条，例如：

[8/10] Importing data into Neo4j
    Running import scripts with progress bar ...
      Importing 1250 statement(s)...
      [########----------------------------]  25% (313/1250)

部署完成后会输出访问地址，并在项目根目录生成 deployment-info.txt：

Deployment complete
Neo4j is running at: bolt://localhost:7687
Neo4j Browser:       http://localhost:7474
FastAPI Health:      http://localhost:8000/health
FastAPI Query:       http://localhost:8000/query
Deployment info:     D:\...\deployment-info.txt

deployment-info.txt 中记录了 Neo4j 密码、URI、LLM 配置等部署信息，请妥善保管。

安装后测试

1. 启动服务

scripts\start-all.bat

等待几秒后分别测试以下接口。

2. 健康检查

CMD 或 PowerShell 中执行：

curl http://localhost:8000/health

若系统未安装 curl，可在 PowerShell 中使用：

Invoke-WebRequest -Uri http://localhost:8000/health -UseBasicParsing

正常应返回 JSON，例如：

{"status":"ok"}

3. 自然语言查询测试

curl -X POST http://localhost:8000/query -H "Content-Type: application/json" -d "{\"query_text\":\"查询劳动合同法中关于劳动者权利的规定\"}"

PowerShell 等价命令：

$body = @{ query_text = "查询劳动合同法中关于劳动者权利的规定" } | ConvertTo-Json
Invoke-WebRequest -Uri http://localhost:8000/query -Method POST -ContentType "application/json" -Body $body -UseBasicParsing

返回格式：

{
  "answer": "AI 生成的自然语言回答...",
  "cypher": "MATCH (l:Law)-[:HAS_ARTICLE]->(a:Article) ...",
  "context": ["图数据库原始记录..."]
}

4. 直接查询 Neo4j（可选）

%LOCALAPPDATA%\law-kg\neo4j\bin\cypher-shell.bat -u neo4j -p your-password -f query.cypher

其中 query.cypher 为包含 Cypher 查询语句的文件，例如：

MATCH (n) RETURN count(n) AS node_count;

注意：Neo4j 2025.x 的 cypher-shell 不再支持把 Cypher 语句作为位置参数直接传入，请使用 -f 指定查询文件。

手动下载 Neo4j（网络受限时）

如果自动下载被网络限制（如出现 CloudFront 403 错误），请手动下载 Neo4j：

1. 下载对应版本的 Windows zip 包：

   https://dist.neo4j.org/neo4j-community-2025.12.1-windows.zip

2. 将下载的 zip 放到项目根目录或 %LOCALAPPDATA%\law-kg\ 目录下。

3. 重新运行 install.bat，脚本会自动检测并使用本地 zip 包。

或者，如果你已经解压好了 Neo4j，可以直接指定路径：

.\install.ps1 -Neo4jHome "C:\path\to\neo4j-community-2025.12.1"

通过环境变量自动配置

如需避免交互式输入，可在运行脚本前设置环境变量：

set NEO4J_PASSWORD=your-password
set LLM_PROVIDER=deepseek
set DEEPSEEK_API_KEY=your-api-key
install.bat

或在 PowerShell 中：

$env:NEO4J_PASSWORD = "your-password"
$env:LLM_PROVIDER = "deepseek"
$env:DEEPSEEK_API_KEY = "your-api-key"
.\install.ps1

可用环境变量

变量	说明	默认值
NEO4J_PASSWORD	Neo4j 密码	必填
NEO4J_VERSION	Neo4j 版本号	2025.12.1
NEO4J_HOME	已有 Neo4j 安装路径	自动检测 / 自动下载
NEO4J_URI	Neo4j 连接地址	bolt://localhost:7687
LLM_PROVIDER	模型服务商	deepseek
LLM_TEMPERATURE	LLM 温度参数	0
DEEPSEEK_API_KEY / DEEPSEEK_BASE_URL / DEEPSEEK_MODEL	DeepSeek 配置	https://api.deepseek.com/v1 / deepseek-chat
OPENAI_API_KEY / OPENAI_BASE_URL / OPENAI_MODEL	OpenAI 配置	https://api.openai.com/v1 / gpt-4
KIMI_API_KEY / KIMI_BASE_URL / KIMI_MODEL	Moonshot Kimi 配置	https://api.moonshot.cn/v1 / moonshot-v1-8k
DASHSCOPE_API_KEY / DASHSCOPE_BASE_URL / DASHSCOPE_MODEL	阿里云 DashScope 配置	https://dashscope.aliyuncs.com/compatible-mode/v1 / qwen-turbo
VLLM_API_KEY / VLLM_BASE_URL / VLLM_MODEL	本地 vLLM 配置	not-needed / http://localhost:8000/v1 / llama3-8b-instruct
OLLAMA_API_KEY / OLLAMA_BASE_URL / OLLAMA_MODEL	本地 Ollama 配置	not-needed / http://localhost:11434/v1 / llama3.1

日常使用

同时启动 Neo4j + API

scripts\start-all.bat

仅启动 API（Neo4j 已运行）

app\start.bat

停止服务

• Neo4j：在任务管理器中结束 java.exe 进程，或运行 <neo4j-home>\bin\neo4j.bat stop
• FastAPI：关闭 app\start.bat 运行的命令行窗口

API 调用示例

健康检查

curl http://localhost:8000/health

自然语言查询

curl -X POST http://localhost:8000/query ^
  -H "Content-Type: application/json" ^
  -d "{\"query_text\": \"查询劳动合同法中关于劳动者权利的规定\"}"

返回格式：

{
  "answer": "AI 生成的自然语言回答...",
  "cypher": "MATCH (l:Law)-[:HAS_ARTICLE]->(a:Article) ...",
  "context": ["图数据库原始记录..."]
}

已有 Neo4j 安装

如果你已经在本地安装了 Neo4j，可通过 -Neo4jHome 参数指定路径，跳过下载：

.\install.ps1 -Neo4jHome "C:\neo4j"

或设置环境变量：

$env:NEO4J_HOME = "C:\neo4j"
.\install.ps1

如果该 Neo4j 已经初始化过密码，请确保输入的 NEO4J_PASSWORD 与现有密码一致，否则数据导入会失败。

重新安装 / 清理旧 Neo4j

脚本默认会检测已有的 Neo4j 安装并询问是否清除后重新安装。如需静默强制重新安装，使用：

.\install.ps1 -ForceReinstall

这会停止相关 Neo4j 进程并删除旧目录，然后下载安装全新的 Neo4j。

仅执行部分步骤

# 跳过 Neo4j 下载（假设已手动安装）
.\install.ps1 -SkipNeo4jDownload

# 跳过数据导入（数据已导入过）
.\install.ps1 -SkipDataImport

# 强制重新安装 Neo4j
.\install.ps1 -ForceReinstall

故障排查

问题	解决方案
提示 Java 版本不足	安装 Java 21+ 并配置环境变量；Java 25 需 Neo4j 2025.10+
提示 Python 版本不足	安装 Python 3.10+ 并添加到 PATH
Neo4j 下载失败	手动下载对应版本 zip，解压到 %LOCALAPPDATA%\law-kg\neo4j，然后使用 -Neo4jHome 参数
重装时提示文件被占用	脚本会自动停止 Neo4j/Java 进程并重试删除；如仍失败，请手动结束 java.exe 后重试
Neo4j 启动后无法连接	查看 <neo4j-home>\logs\neo4j.log
数据导入失败	确认 CSV 文件已复制到 <neo4j-home>\import\；查看导入进度条停止位置及错误输出
API 启动失败	检查 app\.env 中的密码和 URI 是否正确；确认 app\venv 已创建
自然语言查询无结果	检查是否配置了有效的 LLM API Key

卸载

本地版没有注册系统服务。可直接运行一键卸载脚本：

scripts\uninstall.bat

静默卸载（不弹确认）：

scripts\uninstall.bat -Force

该脚本会停止 Neo4j + FastAPI 服务，并删除以下安装产物：

• %LOCALAPPDATA%\law-kg\neo4j（自动下载的 Neo4j）
• app\venv（Python 虚拟环境）
• app\.env、deployment-info.txt
• 安装时生成的启动脚本
• skill 状态文件和 config.json 中的 local_service 字段

如需保留自动安装的 Java / Python，可加上 -KeepJava / -KeepPython 参数。

本知识图谱包含以下领域的法律数据：

领域	节点数（约）
法律	82,797
行政法规	24,000+
司法解释	24,000+
地方法规	14,000+
监察法规	523
宪法	145

总计约 145,792 节点 / 89,618 关系，涵盖 13 种节点类型和 36 种关系类型。