# pdf-loader

**Repository Path**: bluedream_pp/pdf-loader

## Basic Information

- **Project Name**: pdf-loader
- **Description**: 测试一下如何切分数据字典
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-10
- **Last Updated**: 2026-09-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 数据字典 PDF 向量化工具（Text-to-SQL 专用）

将数仓数据字典 PDF 智能提取、表级切分后写入 Chroma 向量数据库，供 AI 参照表结构生成查询 SQL。

## 技术栈

| 组件 | 技术 | 说明 |
|------|------|------|
| PDF 解析 | pdfplumber | 表格提取能力强，按行按列精确提取 |
| 切分策略 | **表级切分（Table-Level）** | 每张表一个完整 chunk，保证 AI 写 SQL 时一次命中完整表结构 |
| 辅助切分 | 字段级子 chunk | 大表字段分组，父子检索 |
| Embedding | OpenAI 兼容接口 | 通义千问 / OpenAI / 任意兼容服务 |
| 向量库 | Chroma | 轻量嵌入式，持久化本地 |

## 为什么用表级切分而不是固定大小切分？

| 对比项 | 固定大小切分（512字符） | 表级切分（本项目） |
|--------|----------------------|-------------------|
| 切分单元 | 固定字符数 | 一张完整的表 |
| 字段完整性 | 可能把一张表的字段拆散到多个 chunk | 所有字段在同一个 chunk |
| 检索"订单表有哪些字段" | 可能只命中部分字段，AI 写 SQL 缺字段 | 一次命中完整表结构 |
| 表名与字段关联 | 表名可能在上一个 chunk，字段在下一个 | 表名+业务说明+所有字段在一起 |
| 召回率 | 中（需要命中多个 chunk 再拼合） | 高（单 chunk 即完整答案） |
| 适用场景 | 通用长文本 | **数据字典 / Text-to-SQL** |

## 项目结构

```
pdf-loader/
├── main.py                  # 命令行入口（extract/ingest/query/stats）
├── config.yaml              # 配置文件
├── requirements.txt
├── README.md
├── src/
│   ├── config.py            # 配置管理
│   ├── pdf_table_extractor.py  # PDF 表格提取 + 跨页表合并（核心）
│   ├── table_splitter.py    # 表级切分器（父块+子块）
│   ├── embedding.py         # Embedding 工厂
│   ├── vector_store.py      # Chroma 封装
│   └── pipeline.py          # 主流程编排
├── data/                    # PDF 文件目录
├── db/                      # Chroma 持久化
├── logs/                    # 日志
└── tests/
    └── test_pipeline.py     # 16 个单元测试
```

## 核心能力

### 1. 智能表格识别
- 自动识别表名行（`ods_order_info 销售订单主表`）
- 自动识别业务说明行（`业务说明：...`）
- 自动识别表头行（`字段名 数据类型 键 说明`）
- 自动识别字段行
- 自动识别主键（PK）、索引（IDX）

### 2. 跨页表自动合并
- 一张表的字段分布在两页时，自动识别续页并合并到同一张表
- 例如 `ods_product_info` 跨第 5-6 页，20 个字段完整合并

### 3. 表级切分
- 每张表生成一个完整 chunk，包含：表名、中文名、数仓层级、业务说明、所有字段
- 大表（字段 > 8 个）额外生成字段级子 chunk，支持父子检索
- 辅助文档：枚举值速查、数仓分层说明

## 快速开始

### 1. 安装依赖

```bash
D:/Python3/python.exe -m pip install -r requirements.txt
```

### 2. 配置 API

编辑 `config.yaml`，填入你的 Embedding API：

```yaml
embedding:
  model: "text-embedding-v3"
  api_key: "你的-api-key"
  base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"
```

### 3. 预览提取结果（不需要 API key）

```bash
D:/Python3/python.exe main.py extract
```

### 4. 导入向量库

```bash
D:/Python3/python.exe main.py ingest
```

### 5. 检索表结构

```bash
D:/Python3/python.exe main.py query --question "订单表有哪些字段" -k 3
```

### 6. 查看统计

```bash
D:/Python3/python.exe main.py stats
```

## 运行测试

```bash
D:/Python3/python.exe -m pytest tests/ -v
```

16 个测试全部通过，覆盖：
- PDF 提取（表数量、表名、字段、主键、跨页合并、枚举值、分层说明）
- 表级切分（字段完整性、元数据、子 chunk 生成）
- 配置加载

## 提取效果示例

```
【ODS】ods_order_info — 销售订单主表
  业务说明: 交易订单主记录，以订单为粒度，聚合订单金额、优惠、支付方式和退款状态。
  字段数: 18 | 页: 6-7
  字段列表:
    order_id (VARCHAR(40)) [PK+IDX]: 订单唯一ID（如 OD20260514001）
    order_no (VARCHAR(40)): 订单业务编号（对外展示）
    order_type (TINYINT): 类型：1=门店 / 2=线上 / 3=外卖
    store_id (VARCHAR(20)) [IDX]: 归属门店ID
    total_amount (DECIMAL(12,2)): 标价总金额（优惠前）
    actual_amount (DECIMAL(12,2)): 实付金额 = total - discount
    pay_type (TINYINT): 方式：1=现金/2=微信/3=支付宝/4=银行卡/5=积分
    ...
```

## 数据字典概览（本 PDF）

| 层级 | 数量 | 表名 |
|------|------|------|
| ODS | 6 | ods_store_info, ods_product_info, ods_member_info, ods_order_info, ods_order_detail, ods_inventory_snapshot |
| DIM | 2 | dim_date, dim_product |
| DWD | 1 | dwd_sale_order_detail |
| DWS | 3 | dws_store_sale_day, dws_product_sale_day, dws_member_consume_summary |
| ADS | 1 | ads_sale_daily_report |
| **合计** | **13** | |

> 注：PDF 封面写"11 张表"，但各层明细加总为 13 张，以实际表定义页为准。