# Knowledge-Base-Tools

**Repository Path**: bigplan/Knowledge-Base-Tools

## Basic Information

- **Project Name**: Knowledge-Base-Tools
- **Description**: 知识库工具集，秦坤维护
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-27
- **Last Updated**: 2026-04-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Document Metadata Extractor

基于本地大模型（LLM + VL）的文档元数据抽取工具，支持批量处理 PDF/DOCX 文档，抽取结构化元数据写入 Excel，并推送到 RAGFlow 知识库。

## 功能概览

| 功能 | 说明 |
|------|------|
| 文档解析 | 支持 PDF、DOCX、DOC、Markdown 格式 |
| LLM 元数据抽取 | 使用本地大模型提取文档元数据（标题、类型、关键词、摘要等） |
| VL 图文识别 | PDF 无文本时自动调用 VL 大模型进行 OCR 识别 |
| 表格提取 | 自动提取文档中的表格并转为 Markdown |
| Excel 导出 | 元数据结果写入 Excel（追加模式，不覆盖已有数据） |
| RAGFlow 推送 | 上传文档到 RAGFlow 知识库并自动设置元数据 |
| 元数据补设 | 从已有 Excel 补设已上传文档的元数据 |
| 图片丰富化 | 对 RAGFlow 中的图片 chunk 补充 caption/kind/hint 4 个字段 |

## 环境要求

- Python 3.8+
- 需要以下服务：
  - **LLM 服务**（OpenAI 兼容 API）：用于元数据抽取
  - **VL 服务**（视觉语言模型）：用于图片 OCR 和分类（可选，`--enrich-images` 时需要）
  - **RAGFlow 服务**：知识库平台（可选，`--push-ragflow` 时需要）

## 安装

```bash
# 克隆项目
git clone <repo-url>
cd Document-Metadata-Extractor-main

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

`requirements.txt` 内容：

```
PyPDF2>=3.0.0
python-docx>=1.0.0
openpyxl>=3.1.0
openai>=1.0.0
requests>=2.28.0
pdfplumber>=0.10.0
PyMuPDF>=1.23.0
Pillow>=10.0.0
```

## 配置

在项目根目录创建 `config.json`：

```json
{
  "llm_base_url": "http://your-llm-host/v1/chat/completions",
  "llm_model_name": "your-llm-model-name",
  "llm_api_key": "your-llm-api-key",
  "vl_base_url": "http://your-vl-host/v1/chat/completions",
  "vl_model_name": "your-vl-model-name",
  "vl_api_key": "your-vl-api-key",
  "ragflow_base_url": "http://your-ragflow-host:8808",
  "ragflow_api_key": "your-ragflow-api-key",
  "ragflow_dataset_name": "知识库名称"
}
```

### 配置项说明

| 配置项 | 必需 | 说明 |
|--------|------|------|
| `llm_base_url` | 是 | LLM API 地址（OpenAI 兼容格式） |
| `llm_model_name` | 是 | LLM 模型名称 |
| `llm_api_key` | 是 | LLM API 密钥 |
| `vl_base_url` | 否* | VL 模型 API 地址（`--enrich-images` 时必需） |
| `vl_model_name` | 否* | VL 模型名称 |
| `vl_api_key` | 否* | VL API 密钥 |
| `ragflow_base_url` | 否* | RAGFlow 服务地址（`--push-ragflow` 时必需） |
| `ragflow_api_key` | 否* | RAGFlow API 密钥 |
| `ragflow_dataset_name` | 否 | RAGFlow 知识库名称（默认 `延崇项目库`） |

## 使用方法

### 1. 基本用法：仅提取元数据

```bash
python main.py --dir "D:\文档目录"
```

- 扫描目录下所有 PDF/DOCX/DOC/MD 文件
- 调用 LLM 提取元数据
- 结果写入 `output/文件信息抽取表.xlsx`（追加模式）
- 每个文件单独生成 JSON 到 `output/` 目录

### 2. 提取元数据 + 推送 RAGFlow

```bash
python main.py --dir "D:\文档目录" --push-ragflow
```

- 完成元数据提取后，自动上传文档到 RAGFlow 知识库
- 上传成功后自动设置文档元数据
- 全部上传完成后自动触发知识库解析

### 3. 指定知识库名称

```bash
python main.py --dir "D:\文档目录" --push-ragflow --dataset "项目A知识库"
```

### 4. 自定义输出文件名和目录

```bash
python main.py --dir "D:\文档目录" -o "项目A抽取结果.xlsx" --output-dir "output_a"
```

### 5. 补设已上传文档的元数据

```bash
python main.py --dir "D:\文档目录" --retry-meta
```

- 从已有的 Excel 读取元数据
- 自动更新知识库元数据字段配置
- 为已上传的文档补设元数据（跳过未上传的文件）

### 6. 图片 chunk 丰富化

```bash
# 对所有已解析文档执行图片丰富化
python main.py --dir "D:\文档目录" --enrich-images

# 仅对指定文档执行
python main.py --dir "D:\文档目录" --enrich-images --enrich-docs "doc_id_1,doc_id_2"
```

- 需要配置 VL 模型
- 自动等待文档解析完成
- 为每个图片 chunk 补充 4 个字段：`image_caption`、`image_kind`、`chapter_hint`、`context_text`

### 7. 一站式：提取 + 推送 + 图片丰富化

```bash
python main.py --dir "D:\文档目录" --push-ragflow --enrich-images
```

## 命令行参数

| 参数 | 缩写 | 必需 | 默认值 | 说明 |
|------|------|------|--------|------|
| `--dir` | `-d` | 是 | — | 待处理文档目录 |
| `--output` | `-o` | 否 | `文件信息抽取表.xlsx` | 输出 Excel 文件名 |
| `--output-dir` | — | 否 | `output` | 输出文件保存目录 |
| `--config` | `-c` | 否 | `config.json` | 配置文件路径 |
| `--push-ragflow` | — | 否 | `False` | 提取后推送到 RAGFlow |
| `--retry-meta` | — | 否 | `False` | 补设已上传文档的元数据 |
| `--dataset` | `-ds` | 否 | 从 config 读取 | RAGFlow 知识库名称 |
| `--enrich-images` | — | 否 | `False` | 图片 chunk 丰富化 |
| `--enrich-docs` | — | 否 | `None` | 指定 doc_id（逗号分隔） |

## 输出文件

### Excel 输出

默认路径：`output/文件信息抽取表.xlsx`

包含以下列：
- `Filename` — 文件名
- `FileSize` — 文件大小
- `DocumentTitle` — 文档标题
- `DocumentType` — 文档类型
- `Keywords` — 关键词
- `AbstractSummary` — 摘要
- `SourceOrigin` — 来源/发布单位
- `DatePublishedCreated` — 发布日期
- `Classification5C` — 5C 分类
- `ProjectName` — 项目名称
- `ProjectStage` — 项目阶段
- `RAGDocType` — RAG 文档类型
- `TopicTags` — 主题标签
- `DomainTags` — 领域标签
- `ReferencedStandards` — 引用标准
- `EntityLocations` — 实体地点
- `EntityEquipment` — 实体设备
- `EntityMaterials` — 实体材料
- `TableInfo` — 表格信息
- `ImageCount` — 图片数量
- 以及其他元数据字段

### JSON 输出

每个文件单独生成 JSON 文件到 `output/` 目录，包含 LLM 的完整响应。

### 日志文件

`metadata_extraction.log` — 运行日志，包含详细的处理记录和错误信息。

## 典型工作流

```
1. 准备文档 → 放入待处理目录
2. 配置 config.json → 填入 LLM/RAGFlow 地址和密钥
3. 执行 python main.py --dir "目录" --push-ragflow
4. 检查 output/文件信息抽取表.xlsx → 人工审核元数据
5. (可选) python main.py --dir "目录" --retry-meta → 补设失败的元数据
6. (可选) python main.py --dir "目录" --enrich-images → 图片丰富化
7. 在 RAGFlow 界面查看知识库 → 确认文档和元数据正确
```

## 注意事项

1. **追加模式**：Excel 采用追加写入，重复运行不会覆盖已有数据。已处理的文件会自动跳过。
2. **去重**：推送到 RAGFlow 时，同名文件会自动跳过，不会重复上传。
3. **解析等待**：`--enrich-images` 会自动等待文档解析完成（最长 10 分钟）。
4. **VL 限频**：图片丰富化每次调用 VL 模型后间隔 0.5 秒，避免 API 限频。
5. **PIL 依赖**：图片丰富化需要 `Pillow`，用于过滤过小（<120px）的装饰性图标。