# LQKgDataGovernance

数据治理涉及工作：原始文件上传OSS、 文档统一转换MinerU、文档层级修复、数据切分处理（父子段）、数据集JSON构建，数据集入库（基本信息、父子分片向量数据库）

路桥知识库数据治理脚本集合，主要处理：
- 编制依据（标准规范）
- 施工方案
- 编制依据时效性状态
- 编制依据实体（术语/背景信息）

数据会按脚本流程写入 `Milvus`、`MinIO`、`MySQL`。

## 快速上手（建议先看）

### 1) 环境准备
- Python `3.12+`
- 建议使用 `uv`
- 需要可访问的服务：`Milvus`、`MinIO`、`MySQL`（按你要跑的脚本决定）

PowerShell 安装 `uv`：

```powershell
irm https://astral.sh/uv/install.ps1 | iex
```

项目根目录安装依赖：

```bash
uv venv
uv sync --index-url https://pypi.tuna.tsinghua.edu.cn/simple
```

### 2) 先改配置再运行

本项目多数脚本是“一次性批处理”，参数直接写在脚本顶部（例如 `ROOT_DIR`、`EXCEL_PATH`、`OUTPUT_JSON`、数据库连接参数等）。

运行前请先打开目标脚本，改成你本机路径和连接信息，再执行命令。

### 3) 运行方式

统一推荐：

```bash
uv run -m src.app.scripts.<script_name>
```

示例（状态 Excel 转 JSON）：

```bash
uv run -m src.app.scripts.status_excel_info_json
```

## 常用流程（按业务）

### A. 编制依据（base）

最常见顺序：
1. `base_count.py`：Excel 与目录编号对比（找缺失）
2. `base_check.py`：目录结构与命名校验
3. `base_info_json_generation.py`：生成入库 JSON（含 parent/children）
4. `base_in_minio.py`：上传原始文件/MD/JSON 到 MinIO
5. `base_info_in_database.py`：写入 MySQL
6. `base_collections_create.py`：创建 Milvus 集合（首次）
7. `base_in_collection.py`：向量化并写入 Milvus

### B. 施工方案（plan）

流程与 base 基本一致：
1. `plan_count.py`：Excel 与目录编号对比（找缺失）
2. `plan_check.py`：目录结构与命名校验
3. `plan_info_json_generation.py`：生成入库 JSON（含 parent/children）
4. `plan_info_in_minio.py`上传原始文件/MD/JSON 到 MinIO
5. `plan_info_in_database.py`：写入 MySQL
6. `plan_info_in_collection.py`：JSON向量化并写入 Milvus

`t_kngs_construction_plan_collections_create.py` 与 `t_kngs_construction_plan_collections_import.py` 是施工方案知识结构片段的另一套父子表流程。

### C. 时效性状态（status）

常见顺序：
1. `status_excel_info_json.py`：Excel 提取关键字段生成 JSON
2. `status_info_in_database.py`：JSON 写入 MySQL 状态表
3. `first_bfp_collection_status_create.py`：创建状态检索集合（首次）
4. `status_to_milvus.py`：状态文本向量化写入 Milvus

### D. 实体数据（entity）

常见顺序：
1. `first_bfp_collection_entity_create.py`：创建实体集合（首次）
2. `first_bfp_collection_entity_import.py` 或 `first_bfp_collection_entity_import_v2.py`：抽取并导入实体

## 目录说明（重点）

- `src/app/scripts/`：主脚本目录（base / plan / status / entity / 工具脚本）
- `src/app/scripts/tool/`：抓取、去重、对比等辅助工具
- `src/app/scripts/ceshi/`：专家意见筛选脚本

## 全量脚本清单（当前仓库）

### `src/app/scripts/`

- `base_check.py`：检查编制依据目录结构与命名是否和 Excel 一致，输出问题清单。
- `base_collections_create.py`：创建编制依据 Milvus 父子 collection（含索引与 BM25 稀疏配置）。
- `base_count.py`：对比 Excel `id` 与目录子文件夹，输出缺失编号清单。
- `base_create_collection.py`：创建编制依据 collection 的测试/示例版脚本，用于先跑通 schema。
- `base_in_collection.py`：将编制依据 JSON 的 `parent/children` 向量化后批量写入 Milvus。
- `base_in_minio.py`：上传编制依据原始文件、MD、JSON 到 MinIO 指定前缀。
- `base_info_in_database.py`：将编制依据 JSON 写入 MySQL（文档主表 + 标准基础信息表）。
- `base_info_json_generation.py`：按 Excel + 文件夹生成编制依据 JSON，并补充 parent/children 结构。
- `character_repair.py`：批量修复文本中的异常字符/乱码字符。
- `ceshi_embdding.py`：测试 embedding 接口连通性与返回向量维度。
- `ceshi_minio.py`：测试 MinIO 上传流程是否正常。
- `copy_pdf_md_files.py`：复制各子目录下 PDF/MD 到目标目录并保留层级结构。
- `extract_bfp.py`：从 PDF/DOCX 抽取编制依据相关章节并汇总标准/法规条目。
- `first_bfp_collection_entity_create.py`：创建实体检索用 Milvus collection。
- `first_bfp_collection_entity_import.py`：从文档中抽取实体并向量化导入 Milvus。
- `first_bfp_collection_entity_import_v2.py`：实体导入增强版（更强抽取与结构处理能力）。
- `first_bfp_collection_status_create.py`：创建时效性状态检索的 Milvus collection。
- `html_tables_to_md.py`：将 Markdown 文件中的 HTML 表格转换为 Markdown 表格。
- `page_index_md.py`：解析 Markdown 标题层级并生成树形索引 JSON。
- `pdf_info_image.py`：按页将 PDF 转成图片并输出到同名目录。
- `plan_chaxun.py`：读取缺失清单，在目录中做名称包含匹配辅助排查。
- `plan_check.py`：检查施工方案目录结构/命名与 Excel 的一致性。
- `plan_count.py`：对比施工方案 Excel 与目录 ID，输出缺失目录清单。
- `plan_entity_import_engine.py`：从施工方案/编制依据 MD 抽取实体并批量导入实体库的通用引擎版脚本。
- `plan_info_in_collection.py`：将施工方案 JSON 的 parent/children 向量化后写入 Milvus。
- `plan_info_in_collection_v2.py`：施工方案入库增强版，支持断点续传、失败报告、Milvus 进度校验与更细分文本切分。
- `plan_info_in_database.py`：将施工方案 JSON 写入 MySQL（文档主表 + 方案基础信息表）。
- `plan_info_in_minio.py`：上传施工方案原始文件、MD、JSON 到 MinIO。
- `plan_info_json_generation.py`：按 Excel + 文件夹生成施工方案 JSON，并补充 parent/children。
- `python_processed_article.py`：调用 LLM 对文章内容做结构化整理与分块输出。
- `run_all.py`：批量调用 `mineru` 转换 PDF，记录成功/失败与重跑进度日志。
- `select_url.py`：抓取标准网站信息（状态/发布日期/发布部门等）并增量保存结果。
- `status_excel_info_json.py`：从时效性 Excel 提取关键字段并导出 JSON。
- `status_info_in_database.py`：将状态 JSON 异步写入 MySQL 状态表，输出失败记录。
- `t_kngs_construction_plan_collections_create.py`：创建 `t_kngs` 施工方案知识结构父子 collection。
- `t_kngs_construction_plan_collections_import.py`：将施工方案知识结构 JSON 切分后导入 `t_kngs` 父子表。
- `专家意见提取对比.py`：比对原始文件与转换结果，将未匹配的 PDF/DOCX 移动到指定目录。
- `提取json.py`：从根目录数字子文件夹收集 JSON 并集中拷贝到输出目录。

### `src/app/scripts/tool/`（时效性核对）

- `excel_info_csv.py`：将 Excel（xlsx）转换为 CSV。
- `gongbiaoku_check.py`：从 工标库 抓取标准状态/发布日期/发布单位等信息。
- `gongbiaowang_select.py`：从 工标网 抓取标准状态/发布日期/发布单位等信息。
- `samr_select.py`：从全国标准信息服务平台抓取标准状态与时间字段。
- `时效性去重.py`：按编号/名称/状态对结果去重并输出删除汇总。
- `时效性查询结果对比.py`：对比源数据与查询结果，输出缺失/不一致/多余项。

### `src/app/scripts/ceshi/`

- `03-施工方案筛选.py`：施工方案评审意见筛选脚本（初始版本）。
- `03-施工方案筛选_服务器版.py`：施工方案筛选的服务器并发版（多进程与增量缓存）。

## 常见问题

### 1) 脚本一运行就报路径不存在
优先检查脚本顶部路径常量是否是你本机真实路径（很多脚本默认是历史路径）。

### 2) 能不能一键全跑
有 `run_all.py`，但该脚本内默认路径是服务器目录（例如 `/home/ubuntu/...`），本地使用前必须先改。

### 3) Milvus 插入失败或字段不匹配
先确认目标 collection schema 与脚本写入字段一致；必要时先执行对应 `*_create.py` 重建/初始化集合。
注意问题：创建collection注意使用chinese分词器，字段创建索引 嵌入不使用OpenAI embedding