# 规范标准检索系统

**Repository Path**: apsara/gfbzjsxt

## Basic Information

- **Project Name**: 规范标准检索系统
- **Description**: 基于 PageIndex 树索引的建筑规范智能检索与问答系统。上传建筑规范 PDF，自动解析并构建结构化索引，通过 LLM 实现自然语言问答，精准定位规范条文。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-03-08
- **Last Updated**: 2026-03-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 建筑规范标准检索系统

基于 PageIndex 树索引的建筑规范智能检索与问答系统。上传建筑规范 PDF，自动解析并构建结构化索引，通过 LLM 实现自然语言问答，精准定位规范条文。

## 功能特性

- **智能问答** — 输入自然语言问题，自动从规范库中检索相关条文并生成回答
- **三层检索** — 类别筛选 → 文档匹配 → 章节定位（基于 PageIndex 树搜索），精准定位条文
- **PDF 在线解析** — 上传 PDF，调用 MinerU 在线 API 自动转换为结构化 Markdown
- **Markdown 上传** — 支持直接上传已转换好的 Markdown + 图片 ZIP 包，支持批量导入
- **引用溯源** — 回答附带原文引用，显示来源文档、章节和页码，可展开查看原文及图片
- **Web 管理界面** — 内置前端页面，涵盖规范查询、文件解析、系统设置、管理中心四大模块

## 技术栈

| 组件 | 技术 |
|------|------|
| 后端框架 | FastAPI + Uvicorn |
| LLM | DeepSeek（通过 OpenAI 兼容接口，可切换其他模型） |
| PDF 解析 | MinerU 在线 API |
| 树索引 | PageIndex |
| 前端 | Vue 3 (CDN) + 原生 CSS，无需构建工具 |
| 桌面客户端 | pywebview + PyInstaller 打包 |
| 终端客户端 | Textual (TUI) + httpx |

## 项目结构

```
├── api/
│   ├── main.py              # FastAPI 入口
│   ├── routers/
│   │   ├── admin.py         # 管理接口：文件上传、解析、索引、类别管理
│   │   ├── search.py        # 问答检索接口（同步 + SSE 流式）
│   │   └── settings.py      # 设置接口
│   └── services/
│       ├── catalog.py       # catalog.json 读写管理（线程安全）
│       ├── mineru.py        # MinerU API 调用
│       ├── organizer.py     # 文件组织整理
│       ├── pipeline.py      # 数据管道：MD → PageIndex 树结构
│       ├── retrieval.py     # 三层检索逻辑 + 回答生成
│       └── settings.py      # 配置读写管理
├── frontend/
│   └── index.html           # 前端单页应用（Vue 3）
├── pageindex/               # PageIndex 树索引组件
├── desktop/
│   ├── main.py              # 桌面客户端入口（pywebview）
│   ├── updater.py           # 自动更新检查
│   ├── version.py           # 版本号
│   └── build.spec           # PyInstaller 打包配置
├── tui/
│   └── app.py               # 终端客户端（Textual TUI）
├── extensions/
│   └── pi-building-code/    # Pi 扩展：建筑规范查询
├── installer/
│   ├── setup.iss            # Inno Setup 安装包脚本
│   └── app.ico              # 应用图标
├── scripts/
│   ├── batch_index.py       # 批量建索引脚本
│   └── organize_mineru.py   # 整理 MinerU 输出目录脚本
├── data/
│   ├── pdfs/                # 原始 PDF（按类别子目录存放）
│   ├── markdown/            # 转换后的 Markdown 及图片
│   └── trees/               # PageIndex 树结构 JSON
├── index/
│   └── catalog.json         # 全局文档目录（核心索引文件）
├── config/
│   ├── settings.json        # 运行时配置（不提交，需自行创建）
│   └── settings.json.example
├── .env.example
├── requirements.txt
├── start.bat                # Windows 一键启动
└── build.bat                # Windows 桌面版打包构建
```

## 快速开始

### 环境要求

- Python 3.9+
- LLM API Key（推荐 DeepSeek，也支持其他 OpenAI 兼容接口）
- MinerU API Token（用于 PDF 在线解析，可选）

### 安装

```bash
# 克隆仓库
git clone https://gitee.com/tianhongyu001/gfbzjsxt.git
cd gfbzjsxt

# 安装依赖
pip install -r requirements.txt
```

### 配置

支持两种配置方式，**Web 界面配置**更推荐：

#### 方式一：Web 界面配置（推荐）

启动服务后，在「系统设置」页面填写 LLM 和 MinerU 的配置信息，保存后即时生效，无需重启。

#### 方式二：配置文件

复制示例配置并填写真实凭证：

```bash
cp config/settings.json.example config/settings.json
```

编辑 `config/settings.json`：

```json
{
  "llm": {
    "base_url": "https://api.deepseek.com",
    "model": "deepseek-chat",
    "api_key": "your_api_key_here"
  },
  "mineru": {
    "model_version": "vlm",
    "enable_formula": true,
    "enable_table": true,
    "is_ocr": false,
    "output_dir": "",
    "method": "auto",
    "api_token": "your_mineru_api_token_here"
  }
}
```

也可以通过根目录的 `.env` 文件提供 LLM 配置（优先级低于 settings.json）：

```bash
cp .env.example .env
```

```env
CHATGPT_API_KEY=your_api_key_here
OPENAI_BASE_URL=https://api.deepseek.com
```

### 启动

```bash
# 命令行启动
uvicorn api.main:app --host 0.0.0.0 --port 8000

# Windows 可直接双击 start.bat（自动打开浏览器）
```

启动后访问 [http://localhost:8000](http://localhost:8000)

---

## 配置说明

### LLM 配置

系统通过 OpenAI 兼容接口调用 LLM，支持多种模型服务：

| 服务商 | `base_url` | `model` 示例 |
|--------|-----------|-------------|
| DeepSeek（推荐） | `https://api.deepseek.com` | `deepseek-chat` |
| OpenAI | `https://api.openai.com/v1` | `gpt-4o` |
| 阿里云百炼 | `https://dashscope.aliyuncs.com/compatible-mode/v1` | `qwen-plus` |
| 本地 Ollama | `http://localhost:11434/v1` | `qwen2.5:14b` |

- **DeepSeek API Key** 申请地址：[https://platform.deepseek.com](https://platform.deepseek.com)

### MinerU 配置

MinerU 用于将 PDF 解析为结构化 Markdown，支持公式、表格、图片识别。

- **API Token 获取**：[https://mineru.net/apiManage/token](https://mineru.net/apiManage/token)

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| `api_token` | MinerU API Token | — |
| `model_version` | 解析模型：`vlm`（推荐）或 `pipeline` | `vlm` |
| `enable_formula` | 公式识别 | `true` |
| `enable_table` | 表格识别 | `true` |
| `is_ocr` | OCR 模式（扫描件建议开启） | `false` |

> **注意**：如果不需要 PDF 解析功能，可以不配置 MinerU Token，直接上传已转换的 Markdown ZIP 包使用。

---

## 使用指南

### 规范查询

进入「规范查询」页面：

1. 在搜索框输入自然语言问题，例如：
   > 施工现场临时用房的防火间距要求是多少？

2. 可选择「规范类别」和「工程类别」缩小检索范围
3. 系统自动完成三层检索并流式输出回答
4. 点击引用来源卡片可展开查看原文、页码及图片

### 文件解析（导入规范文档）

进入「文件解析」页面，支持两种导入方式：

**方式一：PDF 上传**

1. 拖拽或选择 PDF 文件（支持多文件）
2. 选择所属规范类别和工程类别
3. 勾选「自动建立索引」（需配置 LLM）
4. 点击「开始解析」，系统调用 MinerU API 解析并实时显示进度

**方式二：Markdown ZIP 上传**

适用于已通过 MinerU 本地工具或其他方式转换好的文档：

- **单个模式**：ZIP 包含 `document.md` + `images/` 目录
- **批量模式**：ZIP 包含多个子目录，每个子目录是一个文档

ZIP 包结构示例：

```
# 单个模式
my_document.zip
├── document.md
└── images/
    └── img_001.png

# 批量模式
batch.zip
├── GB50194-2014/
│   ├── document.md
│   └── images/
└── GB50720-2011/
    ├── document.md
    └── images/
```

### 系统设置

进入「系统设置」页面，可配置：

- **LLM 配置**：API Key、Base URL、模型名称
- **MinerU 配置**：API Token、解析模型、公式/表格/OCR 识别开关

配置保存后立即生效，无需重启服务。

### 管理中心

进入「管理中心」页面，可以：

- **类别管理**：添加或删除规范类别、工程类别（有引用保护，非空类别不可删除）
- **文档管理**：查看所有已索引文档的详情（名称、类别、描述、节点数）
- **索引管理**：对未索引的文档手动触发建立 PageIndex 索引

---

## 检索原理

```
用户提问
  │
  ▼
第一层：LLM 从类别列表中识别最相关的 1-2 个类别
  │
  ▼
第二层：LLM 从候选文档中匹配最相关的 Top-3 文档
       （结合文档描述和工程类别过滤）
  │
  ▼
第三层：PageIndex 树搜索，从每篇文档的树结构中
       定位最相关章节节点（含文本、页码、图片）
  │
  ▼
汇总所有相关章节作为上下文
  │
  ▼
LLM 生成最终回答 + 引用来源
```

---

## 批量脚本

### 批量建索引

适用于已有大量 Markdown 文件需要批量建立 PageIndex 索引的场景：

```bash
python scripts/batch_index.py --category 安全 --concurrency 3
```

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--category` | 规范类别（必填） | — |
| `--dir` | Markdown 目录 | `data/markdown/<category>/` |
| `--concurrency` | 并发数 | `3` |
| `--force` | 强制重建已存在的索引 | 否 |

断点续跑：已索引的文档自动跳过，失败记录写入 `data/failed.log`。

### 整理 MinerU 输出目录

将 MinerU 本地工具的输出目录整理为项目所需目录结构：

```bash
# 单个文档
python scripts/organize_mineru.py \
    --src "D:/mineru_output/GB50720-2011" \
    --category 安全 \
    --doc-id GB50720-2011

# 批量处理（src 下每个子目录视为一个文档）
python scripts/organize_mineru.py \
    --src "D:/mineru_output/安全" \
    --category 安全 \
    --batch
```

---

## 许可证

版权所有 © 2025-2026 tianhongyu001

本项目仅供个人学习、研究和非商业用途使用。

**允许**：个人学习与研究、非商业环境中的功能扩展、保留版权声明前提下的非商业分享。

**禁止**：任何商业用途、收费软件或盈利性服务集成、商业分发或再授权。

如需商业合作，请联系作者另行获得书面许可。

本软件按"原样"提供，不附带任何担保。详见 [LICENSE](./LICENSE) 文件。