# addressAlignment

**Repository Path**: nlp-learning/address-alignment

## Basic Information

- **Project Name**: addressAlignment
- **Description**: `address-alignment` 是一个中文地址解析项目，目标是把一段混合了**省市区镇、详细地址、姓名、手机号**的非结构化文本，转换成可直接消费的结构化结果
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 📍 Address Alignment

> **面向中文收货地址场景的地址解析与标准化项目**：基于中文预训练模型完成字符级序列标注，并结合行政区划库对省、市、区、镇等字段进行纠偏与结构化输出。

---

## 📘 许可说明

### 🪪 使用说明

本项目仅供个人学习与研究使用，采用 **MIT License** 协议。

> **💡 说明**：你可以自由地使用、修改本项目的代码进行学习。如果觉得好用，欢迎 Star 支持！

---

## ✨ 项目简介

`address-alignment` 是一个中文地址解析项目，目标是把一段混合了**省市区镇、详细地址、姓名、手机号**的非结构化文本，转换成可直接消费的结构化结果。

项目主体流程包括两部分：

- 🧠 **NER 序列标注**：使用 `uer/roberta-small-wwm-chinese-cluecorpussmall` 做字符级标签预测。
- 🗺️ **地址纠偏校验**：结合 MySQL 中的行政区划表与模糊匹配结果，对模型抽取出的行政区进行标准化。

### 🌟 核心特性

- 🧩 **字符级地址抽取**：按字粒度处理中文地址，适合姓名、手机号、门牌号混排的文本输入。
- 🤖 **Transformer 训练链路完整**：包含数据预处理、训练、最佳模型保存和推理代码。
- 🧭 **行政区划纠偏**：将模型结果与数据库中的 `region` 表做匹配，提升省市区镇字段稳定性。
- 🚀 **FastAPI 服务封装**：提供批量地址解析接口，同时内置简单前端页面。
- 🧪 **Notebook 实验记录**：`test/` 目录保留了数据处理、训练、预测等实验过程，便于回溯。

---

## 🛠️ 技术栈

- 🐍 **语言环境**：Python 3.12
- 🤗 **模型框架**：Transformers、Datasets、Evaluate
- 🔥 **深度学习**：PyTorch 2.10.0、TorchVision 0.25.0
- 🌐 **服务框架**：FastAPI、Uvicorn、Pydantic
- 🗃️ **数据校验**：PyMySQL、RapidFuzz
- 📦 **依赖管理**：uv

---

## 🧱 项目结构

```bash
address_alignment/
├── src/                         # 📦 核心源码
│   ├── configuration/
│   │   └── config.py            # ⚙️ 路径、模型、标签、MySQL 与训练超参数配置
│   ├── process/
│   │   └── preprocess.py        # 🧹 原始 jsonl 数据切分与 token/label 对齐
│   ├── runner/
│   │   ├── train.py             # 🎯 模型训练与 best_model_f1 导出
│   │   ├── predict.py           # 🔍 单条/批量文本标签预测
│   │   └── aglinment.py         # 🗺️ 地址字段抽取、纠偏与合并输出
│   ├── web/
│   │   ├── app.py               # 🌐 FastAPI 服务入口
│   │   └── templates/
│   │       └── index.html       # 🖥️ 简单演示页面
│   └── main.py                  # 📝 预留入口文件
├── data/
│   ├── raw/
│   │   ├── data.jsonl           # 📄 原始训练数据
│   │   └── region.sql           # 🗂️ 行政区划建表/数据脚本
│   └── preprocessed/            # 📚 预处理后 train/valid/test 数据集
├── checkpoint/
│   └── best_model_f1/           # 🏆 当前最佳模型
├── logs/                        # 📈 训练日志
├── scripts/                     # 🔧 辅助脚本
├── test/                        # 🧪 Notebook 与测试脚本
├── images/                      # 🖼️ README 展示图片
├── pyproject.toml               # 📦 项目依赖定义
├── uv.lock                      # 🔒 锁定依赖版本
├── refence.md                   # 📝 README 编写规范参考
└── README.md                    # 📘 项目说明文档
```

---

## 🔄 核心流程

```text
原始地址文本
    ↓
data/raw/data.jsonl
    ↓
src/process/preprocess.py
    ↓
data/preprocessed/{train,valid,test}
    ↓
src/runner/train.py
    ↓
checkpoint/best_model_f1
    ↓
src/runner/predict.py
    ↓
src/runner/aglinment.py
    ↓
MySQL region 表纠偏
    ↓
结构化地址结果 / FastAPI 接口输出
```

---

## 🚀 快速开始

### 1. 环境准备

**依赖服务**

- 🐬 **MySQL**：`127.0.0.1:3306`，用于地址行政区划校验，默认库名为 `address_alignment`
- 🤗 **模型下载环境**：首次运行会从 Hugging Face 拉取 `uer/roberta-small-wwm-chinese-cluecorpussmall`

**安装依赖**

```bash
uv sync
```

### 2. 数据与配置

先修改 [`src/configuration/config.py`](/D:/github/A-project-nlp/address_alignment/src/configuration/config.py) 中的关键配置：

| 配置项 | 默认值 | 说明 |
| --- | --- | --- |
| `MYSQL_CONFIG.host` | `127.0.0.1` | MySQL 地址 |
| `MYSQL_CONFIG.port` | `3306` | MySQL 端口 |
| `MYSQL_CONFIG.user` | `root` | 数据库用户名 |
| `MYSQL_CONFIG.password` | `123456` | 数据库密码 |
| `MYSQL_CONFIG.database` | `address_alignment` | 数据库名 |
| `MODEL_NAME` | `uer/roberta-small-wwm-chinese-cluecorpussmall` | 预训练模型 |
| `BATCH_SIZE` | `64` | 训练 batch size |
| `LEARNING_RATE` | `2e-5` | 学习率 |
| `EPOCHES` | `10` | 训练轮数 |
| `SAVE_STEP` | `500` | 保存与评估间隔 |

导入行政区划数据：

```bash
mysql -u root -p address_alignment < data/raw/region.sql
```

### 3. 预处理数据

```bash
$env:PYTHONPATH="src"
python src/process/preprocess.py
```

执行后会生成：

```bash
data/preprocessed/train
data/preprocessed/valid
data/preprocessed/test
```

### 4. 训练模型

```bash
$env:PYTHONPATH="src"
python src/runner/train.py
```

训练完成后，最佳模型会保存到：

```bash
checkpoint/best_model_f1
```

### 5. 启动 Web 服务

```bash
$env:PYTHONPATH="src"
python src/web/app.py
```

- 🌍 **服务地址**：`http://localhost:8089`
- 📄 **Swagger 文档**：`http://localhost:8089/docs`
- 📚 **ReDoc 文档**：`http://localhost:8089/redoc`

---

## 🔌 API 示例

### 📥 请求地址

```http
POST /address_alignment
Content-Type: application/json
```

### 📤 请求体

```json
{
  "messages": [
    "中国浙江省杭州市余杭区葛墩路27号楼傅婕15830444519",
    "高雷 13139243427北京市市辖区东风街道27号楼"
  ]
}
```

### 📦 返回示例

```json
{
  "results": [
    {
      "prov": "浙江省",
      "city": "杭州市",
      "district": "余杭区",
      "town": null,
      "detail": "葛墩路27号楼",
      "name": "傅婕",
      "phone": "15830444519"
    }
  ],
  "count": 1,
  "success": true
}
```

---

## 💡 项目亮点

- **模型抽取与规则校验结合**：不是只做 NER，而是在抽取后继续做行政区划纠偏，结果更接近真实业务需要。
- **支持批量输入**：接口层直接接收 `List[str]`，适合清洗任务或服务化调用。
- **代码链路清晰**：从数据准备、训练、推理到接口封装都已具备，适合作为中文地址解析项目模板继续扩展。

---

## 🖼️ 效果展示

### 首页示意

![首页截图](images/img.png)

### 接口演示

![接口截图](images/img2.png)

---

## 📮 交流说明

如果你准备继续完善这个项目，比较值得优先补的部分有：

- 🧹 补充 `LICENSE`、`.env.example` 和更安全的配置管理方式
- 🧪 增加自动化测试，覆盖地址抽取与数据库纠偏逻辑
- 📏 修复部分代码中的命名与异常处理问题，例如 `aglinment.py` 拼写和数据库失败分支
- ⚙️ 将训练、推理、服务启动封装为统一 CLI

---

## 📧 欢迎交流

如果你在学习过程中有任何疑问，或者想探讨技术细节，**欢迎与我交流！**

📧 **邮箱**：[3120942614@qq.com]()

**Made with ❤️ by Xsy**