chem-risk-detect/README.md

# 涉毒风险监测数据处理系统

从文本和图片中识别化学品 CAS 号、关键词，并进行多模态风险分析。

## 快速开始

```bash
# 安装依赖
pip install pandas openpyxl

# 进入脚本目录
cd scripts/

# 关键词匹配
python3 keyword_matcher.py

# 图片识别（模拟模式，无需 API）
python3 image_batch_recognizer.py --mock --limit 5
```

---

## 功能 1：关键词匹配

从文本中识别 CAS 号和关键词。

**两种匹配模式：**
- **CAS 号识别**：正则提取并标准化为 `XXX-XX-X` 格式
- **精确匹配**：匹配中文名、英文名、简称等

### 基本用法

```bash
cd scripts/

# 默认运行两种模式
python3 keyword_matcher.py

# 仅 CAS 号识别
python3 keyword_matcher.py -m cas

# 仅精确匹配
python3 keyword_matcher.py -m exact

# 自定义文件路径
python3 keyword_matcher.py \
  -k ../data/input/keyword_all.xlsx \
  -t ../data/input/clickin_text_img.xlsx \
  -o ../data/output/results.xlsx

# 指定多个文本列
python3 keyword_matcher.py -c detected_text 文本
```

### 参数说明

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `-k, --keywords` | 关键词文件 | `../data/input/keywords.xlsx` |
| `-t, --text` | 文本文件 | `../data/input/clickin_text_img.xlsx` |
| `-o, --output` | 输出文件 | `../data/output/keyword_matched_results.xlsx` |
| `-c, --text-columns` | 文本列名（支持多列） | 自动检测 `detected_text` 和 `文本` |
| `-m, --modes` | 匹配模式 | `cas exact` |
| `--separator` | 关键词分隔符 | `\|\|\|` |

### 输出说明

输出合并后的匹配结果文件，包含以下列：
- `匹配到的关键词` - 匹配的关键词列表（` | ` 分隔）
- `匹配模式` - 使用的匹配模式（如 "CAS号识别 + 精确匹配"）

---

## 功能 2：图片批量识别

调用大模型 API 识别图片中的文字、物品和风险信息。

### 基本用法

```bash
cd scripts/

# 模拟模式（无需 API，用于测试）
python3 image_batch_recognizer.py --mock --limit 5

# 使用 Dify API
python3 image_batch_recognizer.py --api-type dify --limit 10

# 使用 OpenAI API
python3 image_batch_recognizer.py --api-type openai --limit 10

# 使用 DMX API
python3 image_batch_recognizer.py --api-type dmx --limit 10

# 并行处理
python3 image_batch_recognizer.py --api-type dify --max-workers 3
```

### 参数说明

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--image-dir` | 图片目录 | `../data/images` |
| `--output` | 输出文件 | `../data/output/image_recognition_results.xlsx` |
| `--api-type` | API 类型 (openai/dmx/dify/anthropic/mock) | 从 `.env` 读取 |
| `--model` | 模型名称 | 从 `.env` 读取 |
| `--limit` | 最大处理数 | 无限制 |
| `--offset` | 跳过前 N 张 | 0 |
| `--max-workers` | 并行线程数 | 1 |
| `--mock` | 模拟模式 | 否 |
| `--recursive` | 递归子目录 | 否 |

### 输出说明

输出 Excel 包含以下列：
- `detected_text` - 识别的文字
- `detected_objects` - 物品描述
- `sensitive_items` - 敏感要素
- `summary` - 风险摘要
- `confidence` - 置信度 (High/Medium/Low)
- `raw_response` - 原始 LLM 响应

---

## 功能 3：数据收集与合并

收集批处理结果并与原始数据合并。

```bash
cd scripts/

# 默认合并 batch_output 和 data_all 中的数据
python3 collect_xlsx.py

# 指定输出目录
python3 collect_xlsx.py -o ../data/merged

# 预览模式（不执行）
python3 collect_xlsx.py -n

# 仅复制，不合并原始数据
python3 collect_xlsx.py --no-merge
```

合并逻辑：
- 从 `data/batch_output/{name}/results.xlsx` 读取识别结果
- 与 `data/data_all/{name}_text_img.xlsx` 按图片名匹配合并
- 输出到 `data/collected_xlsx/{name}.xlsx`

---

## 功能 4：高置信度记录验证

对关键词未匹配但置信度为 High/Medium 的记录进行 LLM 二次验证。

```bash
cd scripts/

# 完整示例
python3 verify_high_confidence.py \
  -o ../data/pho_analysis_merged/clickin.xlsx \
  -m ../data/output/clickin_matched.xlsx \
  -r ../data/output/clickin_verify.xlsx

# Mock 模式测试（不调用 API）
python3 verify_high_confidence.py \
  -o ../data/pho_analysis_merged/clickin.xlsx \
  -m ../data/output/clickin_matched.xlsx \
  --mock --limit 5

# 使用 DMX API
python3 verify_high_confidence.py -o original.xlsx -m matched.xlsx --api dmx
```

### 参数说明

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `-o, --original` | 原始 Excel 文件 | 必填 |
| `-m, --matched` | keyword_matcher 匹配结果 | 必填 |
| `-r, --result` | 输出文件 | `{原始文件名}_llm_verified.xlsx` |
| `--api` | API 类型 (openai/dmx/dify/ollama) | 从 `.env` 读取 |
| `--mock` | 模拟模式 | 否 |
| `--confidence` | 验证的置信度级别 | `High Medium` |
| `--limit` | 限制验证条数 | 全部 |

### 输出说明

输出 Excel 在原始列基础上添加以下验证结果列：
- `llm_is_risky` - 是否涉及风险（布尔值）
- `llm_substances` - 涉及的物质名称或 CAS 号（` | ` 分隔）
- `llm_risk_level` - 风险等级（高/中/低）
- `llm_reason` - 判定理由
- `llm_raw_response` - LLM 原始响应

---

## API 配置

复制 `.env.example` 并填写：

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

`.env` 示例：

```bash
# 默认 API 类型
LLM_API_TYPE="dify"

# DMX API（OpenAI 兼容）
DMX_API_KEY="sk-xxx"
DMX_BASE_URL="https://www.dmxapi.cn"
DMX_MODEL="gpt-4o-mini"

# Dify API（图片识别使用）
DIFY_API_KEY="app-xxx"
DIFY_BASE_URL="https://your-dify-server:4433"
DIFY_USER_ID="default-user"

# OpenAI API
OPENAI_API_KEY="sk-xxx"
OPENAI_MODEL="gpt-4o-mini"

# verify_high_confidence.py 独立配置（VERIFY_ 前缀）
VERIFY_API_TYPE="dmx"
VERIFY_API_KEY="sk-xxx"
VERIFY_BASE_URL="https://www.dmxapi.cn"
VERIFY_MODEL="gpt-4o-mini"
```

---

## 目录结构

```
chem-risk-detect/
├── scripts/
│   ├── keyword_matcher.py         # 关键词匹配
│   ├── image_batch_recognizer.py  # 图片识别
│   ├── collect_xlsx.py            # 数据收集合并
│   ├── verify_high_confidence.py  # LLM 二次验证
│   ├── run.sh                     # 批处理管理
│   └── run_batch_background.sh    # 后台运行
├── data/
│   ├── input/                     # 输入数据
│   │   ├── clickin_text_img.xlsx  # 文本数据
│   │   └── keywords.xlsx          # 关键词库
│   ├── images/                    # 图片文件
│   ├── batch_output/              # 批处理输出
│   │   └── {name}/results.xlsx
│   ├── data_all/                  # 原始数据
│   │   └── {name}_text_img.xlsx
│   ├── collected_xlsx/            # 合并后数据
│   └── output/                    # 最终输出结果
├── .env                           # API 配置
└── .env.example                   # 配置模板
```

---

## 处理流程

```
1. 图片识别
   image_batch_recognizer.py → batch_output/{name}/results.xlsx

2. 数据合并
   collect_xlsx.py → 合并 results.xlsx + {name}_text_img.xlsx → collected_xlsx/

3. 关键词匹配
   keyword_matcher.py → output/keyword_matched_results.xlsx

4. 二次验证
   verify_high_confidence.py → 验证未匹配的高置信度记录 → *_llm_verified.xlsx
```

---

## 批处理管理

使用 `run.sh` 管理后台任务：

```bash
cd scripts/

./run.sh start    # 启动任务
./run.sh stop     # 停止任务
./run.sh status   # 查看状态
./run.sh log      # 实时日志
```

设置参数：
```bash
API_TYPE=dify MAX_WORKERS=3 ./run.sh start
```

---

## 依赖安装

```bash
# 必需
pip install pandas openpyxl

# 可选（提升性能和功能）
pip install pyahocorasick  # 关键词匹配加速（5x）
pip install requests       # Dify API 必需
pip install tqdm           # 进度条
pip install openai         # verify 脚本的 OpenAI 兼容 API
```

---

## 常见问题

**Q: 如何提升匹配速度？**
安装 `pyahocorasick`，精确模式自动使用 Aho-Corasick 算法加速。

**Q: 没有 API Key 能测试吗？**
使用 `--mock` 参数运行模拟模式。

**Q: 输出的分隔符能改吗？**
使用 `--separator` 参数，默认 `|||` 不与化学名称冲突。

**Q: verify 脚本和 image_batch_recognizer 能用不同的 API 吗？**
可以。verify 脚本使用 `VERIFY_` 前缀的环境变量，与其他脚本独立配置。

---

## 技术要求

- Python 3.7+
- 查看帮助：`python3 script.py -h`