# 劳动仲裁案件要素抽取与画像构建系统

面向劳动仲裁领域的多源异构案件材料要素抽取、多维画像构建与辅助分析系统。系统采用"规则引擎 + Chinese RoBERTa 多任务神经网络 + Ollama 大语言模型"三层混合架构，覆盖六大案由类型共计 70 余个要素字段，实现从文件上传到结构化要素、三维画像、相似案件匹配的一站式处理。

## 系统架构

```
frontend/ (React 18 + Vite 5, :5173)
    │ Axios HTTP
    ▼
backend/ (FastAPI, :8000)
    ├── RuleBasedExtractor     正则规则抽取（70+ 字段基线覆盖）
    ├── HybridExtractor        三层混合调度（规则/BERT/Ollama 按字段路由）
    ├── PortraitGenerator      法律/事实/风险三维画像评分
    ├── SimilarCaseMatcher     Jaccard 三维加权相似度匹配
    └── RiskPredictor          风险等级评估
    │ HTTP
    ▼
nlp-service/ (FastAPI, :8001)
    ├── ChineseRobertaMultiTask    BERT 多任务模型（NER + 分类 + QA + 回归）
    └── Ollama Qwen 2.5 3B        LLM 零样本增强（可选）
    │
    ▼
MySQL 8.0 (graduation) + Qdrant 向量库（可选）
```

## 项目结构

```
second_type/
├── frontend/                          # React 前端（:5173）
│   └── src/
│       ├── App.jsx                    # 主界面（上传、要素表、画像、相似案件、评估）
│       ├── api.js                     # Axios HTTP 客户端
│       └── styles.css                 # 样式表
├── backend/                           # FastAPI 业务后端（:8000）
│   ├── app/
│   │   ├── main.py                    # 路由与业务逻辑（API 入口）
│   │   ├── models.py                  # ORM 模型（Case, CaseFile, ProcessingTask 等）
│   │   ├── schemas.py                 # Pydantic 请求/响应模型
│   │   ├── config.py                  # 配置管理（读取 .env）
│   │   ├── extractor.py               # 规则抽取器（22 个函数，770 行）
│   │   ├── anj.py                     # Ollama LLM 调用封装
│   │   ├── hierarchy_extract.py       # 案由层级模板
│   │   ├── db.py                      # 数据库连接与 Session
│   │   ├── migrate.py                 # 数据库迁移
│   │   ├── services/
│   │   │   ├── hybrid_extractor.py    # 混合抽取器（4 模式切换）
│   │   │   ├── portrait_generator.py  # 画像生成（三维度评分）
│   │   │   ├── similar_cases_local.py # 相似案件匹配（Jaccard）
│   │   │   ├── document_parser.py     # 文件解析（PDF/DOCX/TXT）
│   │   │   ├── complexity_classifier.py # 复杂度分类
│   │   │   └── risk_predictor.py      # 风险评估
│   │   └── extractors/
│   │       └── rule_extractor.py      # 独立规则提取器
│   ├── data/
│   │   ├── case_elements_schema.json  # 要素 Schema（277 行）
│   │   ├── case_elements_hierarchy.json # 案由层级模板
│   │   ├── raw_corpus.json            # 清洗后语料
│   │   ├── training_dataset.json      # 训练数据
│   │   └── augmented_dataset.json     # 增强数据（150+ 条）
│   ├── tools/
│   │   ├── prepare_dataset.py         # 数据清洗脚本
│   │   ├── evaluate_extraction.py     # 评估脚本
│   │   └── evaluate_extractor.py      # 提取器评估
│   ├── uploads/                       # 上传文件存储
│   ├── .env                           # 环境变量配置
│   └── requirements.txt               # Python 依赖
├── nlp-service/                       # NLP 模型微服务（:8001）
│   ├── app/
│   │   ├── main.py                    # API 路由（/extract, /health）
│   │   ├── schemas.py                 # 请求模型
│   │   └── services/
│   │       ├── extractor.py           # BERT 提取器（模型 + 规则回退）
│   │       ├── bert_multi_task_model.py # 多任务模型定义
│   │       └── model_loader.py        # 单例模型加载器
│   ├── training/
│   │   ├── train_bert.py              # 训练脚本
│   │   ├── bio_schema.py              # BIO 标签体系（15 类实体，31 标签）
│   │   ├── prepare_training_data.py   # 自动标注流水线
│   │   ├── augment_data.py            # 数据增强
│   │   └── evaluate.py                # 统一评估框架
│   └── models/
│       └── chinese_roberta_labor_extractor_v2/  # 训练好的模型（~391MB）
├── config.py                          # 根目录配置兼容模块
├── docker-compose.yml                 # PostgreSQL + Qdrant 容器（可选）
├── test_e2e.py                        # 端到端测试脚本
└── README.md
```

## 快速开始

### 环境要求

- Python 3.10+（推荐 Conda）
- Node.js 18+
- MySQL 8.0+
- （可选）Ollama + Qwen 2.5 3B

### 1. 数据库

```sql
CREATE DATABASE graduation CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

配置 `backend/.env`：

```env
DATABASE_URL=mysql+pymysql://root:密码@127.0.0.1:3306/graduation?charset=utf8mb4
USE_OLLAMA=true
OLLAMA_BASE_URL=http://127.0.0.1:11434
OLLAMA_MODEL_NAME=qwen2.5:3b
```

### 2. 安装依赖

```bash
# 后端
cd backend
pip install -r requirements.txt

# NLP 服务
cd nlp-service
pip install -r requirements.txt

# 前端
cd frontend
npm install
```

### 3. 启动服务

```bash
# 终端 1：后端
cd backend
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# 终端 2：NLP 模型服务
cd nlp-service
uvicorn app.main:app --reload --host 0.0.0.0 --port 8001

# 终端 3：前端
cd frontend
npm run dev -- --host 0.0.0.0 --port 5173
```

浏览器访问 **http://localhost:5173**

### 4.（可选）启动 Ollama

```bash
ollama serve
ollama pull qwen2.5:3b
```

## API 参考

### 后端 API（:8000）

| 方法 | 端点 | 说明 |
|------|------|------|
| GET | `/health` | 健康检查 |
| POST | `/api/cases/upload` | 上传案件材料，触发自动抽取 |
| GET | `/api/cases/{id}` | 获取案件详情 |
| GET | `/api/cases/{id}/elements` | 获取结构化要素 |
| PUT | `/api/cases/{id}/elements` | 更新要素（前端编辑后保存） |
| GET | `/api/cases/{id}/portrait` | 获取案件画像 |
| POST | `/api/cases/{id}/similar` | 获取相似案件（`{"top_k": 5}`） |
| GET | `/api/evaluation/metrics` | 获取评估指标 |

完整文档：**http://localhost:8000/docs**（Swagger 自动生成）

### NLP 微服务 API（:8001）

| 方法 | 端点 | 说明 |
|------|------|------|
| GET | `/health` | 模型状态检查 |
| POST | `/extract` | BERT 模型要素抽取 |
| POST | `/extract/compare` | 规则 vs 模型对比 |

## 模型架构

```
Chinese RoBERTa (hfl/chinese-roberta-wwm-ext, ~102M)
    ├── Token Classification Head (768 → 31) ─── NER（15 类实体 BIO 标签）
    ├── Classification Heads (768 → 6, 768 → 4) ─── 案由/合同分类
    ├── Span QA Head (768 → 2) ─── 事实片段抽取
    └── Regression Head (768 → 128 → 64 → 1) ─── 金额预测

联合损失：L = 0.40×L_NER + 0.30×L_CLS + 0.15×L_QA + 0.15×L_REG
优化器：AdamW (lr=2e-5)，FP16 混合精度，早停 patience=3
```

## 三层混合抽取策略

| 层级 | 实现 | 负责字段 | 优势 |
|------|------|---------|------|
| Layer 1 规则层 | RuleBasedLaborExtractor（22 个正则函数） | 姓名、日期、金额、法条、案号 | 精确率高、速度快（0.02s） |
| Layer 2 BERT 层 | ChineseRobertaMultiTask（4 任务头） | 案由分类、实体识别、片段抽取 | 语义理解强、召回率提升 12pp |
| Layer 3 LLM 层 | Ollama Qwen 2.5 3B（零样本） | 仲裁请求、解除原因、自由文本 | 零样本泛化、覆盖极端变体 |

三层通过 `HybridExtractor` 按字段类型路由，任一层不可用时自动降级至下层，核心链路不中断。

## 配置说明

`backend/.env` 主要配置项：

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `DATABASE_URL` | - | MySQL 连接字符串 |
| `extractor_mode` | `rules` | 抽取模式：rules / bert / ollama / hybrid |
| `use_ollama` | `false` | 启用 Ollama LLM 增强 |
| `ollama_base_url` | `http://127.0.0.1:11434` | Ollama 服务地址 |
| `ollama_model_name` | `qwen2.5:3b` | 使用的模型 |
| `use_remote_nlp_service` | `false` | 使用远程 NLP 微服务 |
| `bert_model_service_url` | `http://localhost:8001/extract` | BERT 服务地址 |
| `use_vector_store` | `false` | 启用 Qdrant 向量检索 |

## 模型训练

### 数据准备

```bash
# 1. 清洗语料
cd backend
python tools/prepare_dataset.py

# 2. 自动标注（规则抽取 → BIO 标签 + 分类标签）
cd nlp-service/training
PYTHONPATH="..;../../backend" python prepare_training_data.py

# 3. 数据增强
PYTHONPATH="..;../../backend" python augment_data.py
```

### 训练

```bash
cd nlp-service/training
HF_ENDPOINT="https://hf-mirror.com" PYTHONPATH="..;../../backend" \
    python train_bert.py \
    --dataset ../../backend/data/augmented_dataset.json \
    --output ../models/chinese_roberta_labor_extractor \
    --epochs 10 \
    --batch_size 4 \
    --lr 2e-5
```

### 评估

```bash
cd nlp-service/training
PYTHONPATH="..;../../backend" python evaluate.py \
    --dataset ../../backend/data/augmented_dataset.json \
    --output eval_results.json \
    --methods rules,bert
```

## 端到端测试

确保三服务已启动后运行：

```bash
python test_e2e.py
```

测试覆盖：健康检查 → 上传案件 → 获取要素 → 获取画像 → 相似案件匹配 → NLP 直接调用。

## 技术栈

| 层级 | 技术 |
|------|------|
| 前端 | React 18 + Vite 5 + Recharts + Axios |
| 后端 | FastAPI + SQLAlchemy + PyMySQL |
| NLP 模型 | Chinese RoBERTa (hfl/chinese-roberta-wwm-ext) + Multi-Task |
| LLM | Ollama + Qwen 2.5 3B（本地部署） |
| 文档解析 | pypdf + python-docx + python-magic |
| 中文分词 | jieba |
| 向量检索 | Qdrant + sentence-transformers（可选） |
| 数据库 | MySQL 8.0 |

## 六案由要素体系

| 案由类型 | 核心要素 |
|----------|---------|
| 劳动关系纠纷 | 劳动关系确认、未签合同双倍工资 |
| 工伤保险待遇 | 伤残补助金、医疗费、停工留薪期工资 |
| 追索劳动报酬 | 拖欠工资、加班费、高温津贴 |
| 经济补偿金 | 协商解除补偿、代通知金 |
| 赔偿金 | 违法解除赔偿金（2N） |
| 生育保险待遇 | 生育津贴、生育医疗费 |

## 已知限制

- **训练数据**：当前增强后约 150 条样本，NER 标注稀疏，实体识别仍高度依赖规则层
- **Ollama 依赖**：LLM 增强需本地运行 Ollama 服务，不可用时可回退至规则模式
- **BERT 模型**：嵌套实体和边界模糊实体的预测不够稳定
- **匹配性能**：相似案件使用线性扫描 O(N)，大规模时建议启用 Qdrant 向量检索

## 许可证

本项目仅用于学术研究与毕业设计展示。