# ESG Extractor
### ESG 报告指标智能提取系统
[](DEPLOYMENT.md)
[](pyproject.toml)
[](config/indicators.yaml)
[](scripts/test_smoke_behaviors.py)
[](LICENSE)
🇨🇳 中文 |
🇬🇧 English
---
## 🎯 核心功能
| 功能 | 说明 |
|---|---|
| **报告采集** | 按关键字、日期范围从 CNINFO 下载 ESG 报告，支持公司-年份去重 |
| **PDF 解析** | 本地 Docling 解析 + 可选豆包/火山方舟文档理解解析；当前冻结基准使用已锁定 Markdown 语料 |
| **OCR 注入** | PaddleOCR PP-OCRv6 对报告中图表图片进行文字识别与注入 |
| **向量索引** | BGE-M3 稠密嵌入 + Milvus 持久化，HNSW 索引 + 标量字段过滤 |
| **混合检索** | 稠密/混合双模式，支持指标别名/关键字/子查询扩展、元数据加分 |
| **级联式提取** | 检索 → 匹配 → 验证；表格、正则、公式、Profile 等确定性策略优先，必要时进入 LLM 复核或语义回退 |
| **对话智能体** | 自然语言对话、统一工具调用、批量矩阵提取、本地历史记录与工具执行日志 |
| **确定性提取** | 约 87% 定量指标零 API 成本提取（469/540），假高置信率 < 0.5% |
| **检查点续传** | 批量级检查点，中断后自动续传 |
| **验证工具** | 环境检查、Milvus 巡检、检索-提取验证、smoke 回归测试 |
---
## 🛠 技术栈
PDF 解析 · Docling（主） / Docling Pipeline（备选）
RAG 框架 · LlamaIndex 0.14.22
嵌入模型 · BGE-M3（ModelScope 国内 CDN 下载）
向量数据库 · Milvus Standalone（HNSW 索引）
LLM · `config/config.yaml` 中的 OpenAI 兼容多渠道配置（当前冻结复现实验：Agnes `agnes-2.0-flash`；DeepSeek/GLM/豆包可切换）
重排序 · BAAI/bge-reranker-v2-m3
后端 · Python FastAPI + SSE 流式 + OpenAPI 自动文档
前端 · Vue 3 + Vite SPA（17 页面，5 大功能组）
部署 · Docker Compose 双模式（All-in-One / DB-Only）
配置 · YAML + Pydantic 类型校验
---
## 🚀 快速开始
完整部署指南详见 [DEPLOYMENT.md](DEPLOYMENT.md)。
### 方式一：Docker 一键启动（推荐）
无需宿主机安装 Python/Node/模型，一条命令启动全部服务：
```powershell
git clone https://github.com/LPK3215/esg-extractor-V2.git esg-extractor
cd esg-extractor
copy .env.example .env
# 编辑 .env，填入 config/config.yaml 当前 active provider 对应的 Key/Base URL/Model
docker compose up -d
```
首次启动自动构建镜像 + 下载模型（共约 5GB，约 10-30 分钟）。启动后访问 [http://localhost](http://localhost)。
运行数据管线（容器内执行）：
```powershell
# 烟测（推荐首次）：3 份文档，约 30 分钟
docker exec -it esg-backend python scripts/run_pipeline.py --target-count 3 --parse-limit 3 --build-limit-docs 3
# 全量管线
docker exec -it esg-backend python scripts/run_pipeline.py
```
### 方式二：手动部署
```powershell
scripts\setup_env.bat # 一键环境配置（venv + PyTorch + 依赖 + 模型）
docker compose up -d etcd minio milvus # 启动 Milvus 数据库
.\scripts\run_pipeline.ps1 # 运行全量管线
```
### 验证命令
```powershell
.venv\Scripts\python.exe scripts\check_env.py # 环境健康检查
.venv\Scripts\python.exe scripts\inspect_database.py --short # 向量库巡检
.venv\Scripts\python.exe -m pytest scripts\test_smoke_behaviors.py -q # 8 项 smoke 回归测试
```
---
## 📊 管线流程
系统包含 **9 个环节** 的统一管线，由 `run_pipeline.py` 串联：
```
环境检查(0) → 报告下载(1) → Docling 解析(2) → 索引构建(3)
→ 数据库巡检(4) → 检索验证(5) → 指标提取(6) → smoke 回归测试(7)
→ 可视化图表生成(8)
```
### 级联式提取流程
| 阶段 | 方式 | 覆盖 |
|---|---|---|
| **Stage 1 — 检索** | 定量指标优先 BM25/全文关键词检索，定性指标优先 BGE-M3 向量语义检索，并结合关键字扩展与元数据过滤 | 所有指标 |
| **Stage 2 — 匹配** | HTML/Markdown 表格解析、正则定位、公式计算、定性 Profile 聚合和术语同义词匹配 | 高置信候选段落与候选值 |
| **Stage 3 — 验证** | 规则置信度门控 + OpenAI 兼容 LLM 上下文复核/语义回退；无证据时安全终止 | 歧义候选、长尾定性指标和低置信结果 |
---
## 📈 准确率指标
基于开发/回归验证集的冻结评估：15 家公司 × 60 指标 = 900 条黄金标准记录：
| 维度 | 准确率 | 数值 |
|---|---|---|
| **综合** | **97.9%** | 881/900 |
| 环境 (E) | 98.5% | 266/270 |
| 社会 (S) | **98.9%** | 267/270 |
| 治理 (G) | 96.7% | 348/360 |
| 定量 | **99.1%** | 535/540 |
| 定性 | 96.1% | 346/360 |
| **最佳公司** | **100.0%** | 派林生物 / 理奇智能 / 金种子酒 / 正元地信 |
**错误类型分布：** 误提 10、漏提 7、数值偏差 2。
**检索命中率：** 55.8%（502/900）。
最终准确率明细见：[docx/FINAL_ACCURACY_REPORT.md](docx/FINAL_ACCURACY_REPORT.md)；逐文档/公司准确率见：[docx/PER_DOCUMENT_ACCURACY_REPORT.md](docx/PER_DOCUMENT_ACCURACY_REPORT.md)。
---
## 🔬 评估说明
上述 97.9%（881/900）是开发/回归验证集上的冻结结果，不是独立留出测试结果。论文配对消融使用最终冻结架构在两份代表性报告的 120 项指标上评估：完整框架 116/120；关闭确定性管道 96/120；关闭定量候选 LLM 复核 109/120；关闭向量语义召回 113/120；固定既有索引、仅收缩查询侧 aliases/keywords 后为 116/120。同一 120 项指标上的外部对比为本框架 116/120、LLM one-shot 94/120、纯规则基线 106/120。两报告实验只用于描述性机制诊断，不能表述为 15 家公司证据；881/900 的开发/回归结果仍是独立的统计口径。
---
## 📁 项目结构
```text
esg-extractor/
├── config/ # 8 个 YAML + 6 个提示词配置文件
├── scripts/ # 70 个脚本：下载/解析/构建/巡检/烟测/图表/消融
├── src/ # 55 个 Python 源文件：核心引擎 + FastAPI 后端
├── docx/ # 最终报告、文档归档与回归日志
├── frontend/ # Vue 3 + Vite SPA（17 页面，5 大功能组）
├── DEPLOYMENT.md # 完整部署指南
├── CHANGELOG.md # 版本变更日志
├── FAQ.md # 常见问题
├── .env.example # 环境变量模板
├── docker-compose.yml # Docker 编排（5 容器）
├── requirements.txt # 锁定依赖（48 个包）
└── pyproject.toml # 项目元数据
```
---
## 📚 文档导航
| 文档 | 说明 |
|---|---|
| [部署指南](DEPLOYMENT.md) | Docker 一键部署 + 手动分步部署完整流程 |
| [项目当前状态](PROJECT_STATUS.md) | 三部分完成状态、冻结结果与下一步目标 |
| [最终准确率报告](docx/FINAL_ACCURACY_REPORT.md) | 锁定 97.9% 基准、逐公司准确率与错误类型 |
| [逐文档准确率报告](docx/PER_DOCUMENT_ACCURACY_REPORT.md) | 每个文档/公司的准确率、剩余错误与耗时 |
| [开发规格与诊断记录](DEVELOPMENT_SPEC.md) | 智能体架构、诊断记录与工程备注 |
| [检索验证流程](RETRIEVAL_VERIFICATION_FLOW.md) | 检索与提取验证流程 |
| [数据目录说明](data/数据说明.md) | 锁定数据资产、可清理目录与 Milvus 数据说明 |
| [在线演示](https://lpk3215.github.io/esg-extractor-V2/) | GitHub Pages 在线展示（17 交互页面） |
---
## 👥 作者
- [LPK3215](https://github.com/LPK3215)
- [Max-jmon](https://github.com/Max-jmon)
- [qwerty1-bit](https://github.com/qwerty1-bit)
---
## 📄 许可证
MIT License。详见 [LICENSE](LICENSE)。