# parseSmartAddress

**Repository Path**: xskywalker/parse-smart-address

## Basic Information

- **Project Name**: parseSmartAddress
- **Description**: 使用AI大模型智能识别收货地址信息，返回结构化的JSON数据
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-04-10
- **Last Updated**: 2025-08-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 智能地址解析项目 (Smart Address Parser)

本项目利用 AI 大模型将非结构化的中文收货地址信息解析为结构化的 JSON 数据。项目支持多种AI模型（目前支持 DeepSeek 和豆包大模型），提供 Web UI 和 API 两种使用方式，并支持 Docker 部署。

## 项目功能

1.  **智能解析**: 输入任意包含姓名、电话、省、市、区、街道、详细地址的文本，输出结构化的 JSON 对象。
2.  **电话号码智能区分**: 可自动识别并区分手机号码、固定电话和虚拟号码，分别存储在不同字段。
3.  **Web 界面**: 提供简洁的网页界面，用户可以粘贴地址文本，点击按钮即可看到解析结果。
4.  **API 接口**: 提供 `/api/parse` 接口 (POST)，接收包含 `address` 字段的 JSON 请求，返回解析后的 JSON 结果，方便其他程序集成调用。
5.  **API 认证**: 使用API Key认证机制保护API接口，防止未授权访问和滥用。
6.  **缓存机制**: 自动缓存已解析的地址结果，避免重复调用API，减少请求次数和响应时间。
7.  **隐私保护**: 本地缓存采用加密存储，保护用户地址隐私信息安全。
8.  **多模型支持**: 支持多种AI大模型（当前支持DeepSeek和豆包大模型），可通过配置自动选择或手动指定使用的模型。
9.  **模型可扩展**: 代码结构设计上预留了接口 (`AIParserInterface`)，方便未来接入或切换其他 AI 大模型。
10. **Docker 支持**: 提供 `Dockerfile`，方便快速构建和部署。

## 项目结构

```
parse-smart-address/
│
├── app/                     # 应用核心目录
│   ├── __init__.py
│   ├── main.py              # Flask 路由和视图函数
│   ├── core/                # 核心解析逻辑
│   │   ├── __init__.py
│   │   └── parser.py        # 地址解析器模块
│   ├── templates/           # HTML 模板文件
│   │   └── index.html       # 前端页面
│   └── static/              # 静态文件 (CSS, JS) - 可选
│
├── cache/                   # 缓存目录 (自动创建)
│   └── address_cache.json   # 加密的缓存文件
│
├── tests/                   # 测试目录
│   ├── __init__.py
│   └── test_parser.py       # 解析器单元测试 (待完善)
│
├── .env                     # 环境变量 (存储 API Key 等 - **需自行创建和配置**)
├── .env.example             # 环境变量示例文件 (可用作配置参考)
├── .gitignore               # Git 忽略文件
├── Dockerfile               # Docker 配置文件
├── docker-compose.yml       # Docker Compose 基础配置
├── docker-compose.prod.yml  # Docker Compose 生产环境配置
├── deploy.sh                # Docker 部署脚本
├── requirements.txt         # Python 依赖项
├── start.py                 # 应用运行入口文件
├── test_parser.py           # 独立解析器测试脚本
└── README.md                # 项目文档
```

## 环境要求

*   Python 3.8+
*   Docker (可选，用于容器化部署)
*   AI模型API Key (DeepSeek 或豆包大模型，至少需要其中一个)

## 项目部署与使用

### 1. 本地运行

**a. 克隆仓库**

```bash
git clone <your-repository-url>
cd parse-smart-address
```

**b. 创建并配置 `.env` 文件**

项目根目录提供了 `.env.example` 示例文件，您可以基于此创建自己的 `.env` 文件:

```bash
# 复制示例文件
cp .env.example .env

# 编辑.env文件，填入您的API密钥等信息
nano .env  # 或使用其他编辑器
```

`.env` 文件包含以下配置项:

```text
# Docker部署配置
PORT=5000                          # Web服务端口
PROD_CPU_LIMIT=1                   # 生产环境CPU限制
PROD_MEMORY_LIMIT=2G               # 生产环境内存限制
HEALTHCHECK_INTERVAL=30s           # 健康检查间隔
HEALTHCHECK_TIMEOUT=3s             # 健康检查超时
HEALTHCHECK_RETRIES=3              # 健康检查重试次数

# AI模型配置 (至少配置一个模型的API密钥)
# DeepSeek API 配置
DEEPSEEK_API_KEY="YOUR_DEEPSEEK_API_KEY"
DEEPSEEK_API_BASE="https://api.deepseek.com/v1"

# 豆包大模型 API 配置
DOUBAO_API_KEY="YOUR_DOUBAO_API_KEY"
DOUBAO_API_BASE="https://ark.cn-beijing.volces.com/api/v3"
DOUBAO_MODEL_NAME="doubao-seed-1-6-flash-250615"

# 模型选择配置
AI_MODEL_TYPE="auto"  # 可选值: auto, deepseek, doubao

# 缓存配置
ADDRESS_CACHE_MAX_AGE_DAYS=7              # 缓存有效期天数，默认7天
ADDRESS_CACHE_ENCRYPTION_KEY="YOUR_ENCRYPTION_KEY" # 缓存加密密钥

# API认证配置
API_KEY="YOUR_API_KEY"                     # API访问密钥
EXTRA_API_KEYS="KEY1,KEY2,KEY3"            # 额外的API密钥，用逗号分隔

# 应用环境设置
# 可选值: production, development
APP_ENV="production"                       # 生产环境会关闭debug模式
```

**请务必将相应的API密钥替换为你的真实密钥。至少需要配置一个模型的API密钥，系统会自动选择可用的模型。**

**c. 创建虚拟环境并安装依赖**

```bash
# 创建虚拟环境 (推荐)
python -m venv venv

# 激活虚拟环境
# Windows (PowerShell/Git Bash)
./venv/Scripts/activate
# macOS/Linux
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt
```

**d. 运行应用**

```bash
# 从项目根目录运行
python start.py
```

如需启用开发模式（包含热重载等功能），可设置环境变量：
```bash
# Windows (PowerShell)
$env:APP_ENV="development"; python start.py

# Linux/Mac
APP_ENV=development python start.py
```

应用将在 `http://127.0.0.1:5000` (或 .env 中定义的 PORT) 运行。

### 2. Docker 部署

**a. 构建 Docker 镜像**

在项目根目录运行：

```bash
docker build -t smart-address-parser .
```

**b. 运行 Docker 容器**

```bash
# 将你的API Key作为环境变量传入（至少需要一个AI模型的密钥）
docker run -d -p 5000:5000 --name address-parser-app \
       -e DEEPSEEK_API_KEY="YOUR_DEEPSEEK_API_KEY" \
       -e DOUBAO_API_KEY="YOUR_DOUBAO_API_KEY" \
       -e AI_MODEL_TYPE="auto" \
       -e API_KEY="YOUR_API_KEY" \
       smart-address-parser
```

*   `-d`: 后台运行容器。
*   `-p 5000:5000`: 将主机的 5000 端口映射到容器的 5000 端口。
*   `--name address-parser-app`: 为容器命名。
*   `-e DEEPSEEK_API_KEY="..."`: **可选** 通过环境变量将你的 DeepSeek API Key 传递给容器。
*   `-e DOUBAO_API_KEY="..."`: **可选** 通过环境变量将你的豆包大模型 API Key 传递给容器。
*   `-e AI_MODEL_TYPE="..."`: **可选** 指定使用的AI模型类型（auto/deepseek/doubao），默认为auto自动选择。
*   `-e API_KEY="..."`: **重要** 通过环境变量将你的API访问密钥传递给容器。

**c. 运行仅API模式的容器**

如果你只需要API接口而不需要Web界面，可以设置 `DISABLE_WEB_UI=true`：

```bash
# 运行仅API模式的容器
docker run -d -p 5000:5000 --name address-parser-api \
       -e DISABLE_WEB_UI=true \
       -e DEEPSEEK_API_KEY="YOUR_DEEPSEEK_API_KEY" \
       -e DOUBAO_API_KEY="YOUR_DOUBAO_API_KEY" \
       -e AI_MODEL_TYPE="auto" \
       -e API_KEY="YOUR_API_KEY" \
       smart-address-parser
```

*   `-e DISABLE_WEB_UI=true`: **可选** 禁用Web界面，仅提供API接口。在此模式下，访问 `/` 和 `/api/docs` 将返回403错误提示信息，但API接口 `/api/parse` 和 `/api/info` 仍然正常工作。

**注意：至少需要配置一个AI模型的API密钥（DEEPSEEK_API_KEY 或 DOUBAO_API_KEY）。**

或者，如果你不想在命令行暴露 Key，可以将 `.env` 文件挂载到容器中（确保 `.env` 文件存在于运行 `docker run` 命令的目录或指定绝对路径）：

```bash
# 挂载本地的 .env 文件到容器的 /app/.env
docker run -d -p 5000:5000 --name address-parser-app -v "${PWD}/.env:/app/.env" smart-address-parser
```

**c. 使用部署脚本（推荐）**

项目提供了便捷的部署脚本`deploy.sh`，用于管理Docker环境：

```bash
# 赋予脚本执行权限
chmod +x deploy.sh

# 运行部署脚本
./deploy.sh
```

部署脚本提供以下功能：
* 启动生产环境 - 使用docker-compose启动服务
* 查看容器日志 - 实时监控应用日志
* 停止生产环境 - 安全停止所有服务
* 重建生产环境 - 完全重建镜像和容器
* 配置环境设置 - 选择使用生产或开发环境配置
* 进入容器Shell - 直接进入容器进行调试

脚本支持从`.env`文件读取配置，可通过环境设置菜单切换不同环境的配置文件。生产环境使用`docker-compose.prod.yml`配置文件，已针对生产环境进行了优化设置，包括资源限制和自动重启策略。

**d. 访问应用**

应用将在 `http://localhost:5000` (或你的 Docker 主机 IP 地址的 5000 端口) 运行。

## 项目使用

### 1. Web 界面

浏览器访问 `http://<your-host>:5000`，在文本框中输入地址，点击"解析地址"按钮。

示例输入：
```
广东省广州市天河区体育西路101号 王芳 020-38889999 13522223333
```

### 2. API 接口

#### API认证

所有API接口调用需要通过API密钥认证（除了`/api/info`接口）。认证方式有三种：

1. **请求头认证**（推荐）：
   ```
   X-API-Key: YOUR_API_KEY
   ```

2. **URL参数认证**：
   ```
   /api/parse?api_key=YOUR_API_KEY
   ```

3. **请求体认证**：
   ```json
   {
     "api_key": "YOUR_API_KEY",
     "address": "..."
   }
   ```

#### 接口说明

*   **解析地址接口**
    *   **URL**: `http://<your-host>:5000/api/parse`
    *   **Method**: `POST`
    *   **Headers**:
        ```
        Content-Type: application/json
        X-API-Key: YOUR_API_KEY
        ```
    *   **Body (raw JSON)**:
        ```json
        {
          "address": "广东省深圳市南山区粤海街道科技南十二路 中科纳能大厦 A座 3楼 张三 13800138000 0755-12345678"
        }
        ```

    *   **成功响应 (200 OK)**:
        ```json
        {
          "province": "广东省",
          "city": "深圳市",
          "district": "南山区",
          "street": "粤海街道",
          "address_detail": "科技南十二路 中科纳能大厦 A座 3楼",
          "name": "张三",
          "mobile": "13800138000",
          "telephone": "0755-12345678"
        }
        ```

    *   **错误响应 (4xx/5xx)**:
        ```json
        {
          "error": "具体的错误信息..."
        }
        ```

*   **API信息接口**（无需认证）
    *   **URL**: `http://<your-host>:5000/api/info`
    *   **Method**: `GET`
    *   **成功响应 (200 OK)**:
        ```json
        {
          "name": "智能地址解析API",
          "version": "1.0",
          "description": "智能解析中文地址信息为结构化数据",
          "authentication": {
            "method": "API Key",
            "header": "X-API-Key"
          },
          // ...更多API信息
        }
        ```

*   **生成API密钥接口**（仅开发环境可用）
    *   **URL**: `http://<your-host>:5000/api/generate-key`
    *   **Method**: `GET`
    *   **成功响应 (200 OK)**:
        ```json
        {
          "message": "新API密钥已生成",
          "api_key": "生成的新密钥",
          "note": "此密钥仅在本次服务运行期间有效..."
        }
        ```

## 缓存功能

系统实现了智能缓存机制，提高性能并减少API调用：

1. **自动缓存**: 成功解析的地址会自动缓存，相同地址再次请求时直接返回缓存结果。
2. **加密存储**: 缓存数据采用AES加密存储，保护用户地址隐私。
3. **自动清理**: 默认缓存保留7天，过期数据会自动清理，避免积累过多历史数据。
4. **配置选项**: 
   - `ADDRESS_CACHE_MAX_AGE_DAYS`: 设置缓存保留天数（默认7天）
   - `ADDRESS_CACHE_ENCRYPTION_KEY`: 设置加密密钥（若不设置则自动生成）

## 号码识别规则

系统可以智能识别并区分不同类型的号码：

1. **手机号码 (mobile)**：
   * 常规手机号码：11位数字，通常以13/14/15/16/17/18/19开头（如13800138000）
   * 虚拟号码：通常为手机号后带分机号（如14749871654-8722）
   * 国际格式号码：如86-138-00000000

2. **固定电话 (telephone)**：
   * 座机号码：通常格式为区号-号码，如0755-12345678
   * 400/800电话：如400-0211880

## 环境变量配置

本项目支持通过环境变量进行灵活配置，以下是可用的环境变量及其功能：

### Docker部署配置
| 环境变量 | 默认值 | 说明 |
|---------|-------|------|
| PORT | 5000 | Web服务监听端口 |
| DISABLE_WEB_UI | false | 是否禁用Web UI界面，仅提供API接口 |
| PROD_CPU_LIMIT | 1 | 生产环境CPU核心限制 |
| PROD_MEMORY_LIMIT | 2G | 生产环境内存限制 |
| HEALTHCHECK_INTERVAL | 30s | 健康检查间隔时间 |
| HEALTHCHECK_TIMEOUT | 3s | 健康检查超时时间 |
| HEALTHCHECK_RETRIES | 3 | 健康检查重试次数 |

### API配置
| 环境变量 | 默认值 | 说明 |
|---------|-------|------|
| DEEPSEEK_API_KEY | - | DeepSeek API密钥（可选，至少需要一个AI模型密钥） |
| DEEPSEEK_API_BASE | https://api.deepseek.com/v1 | DeepSeek API基础URL |
| DOUBAO_API_KEY | - | 豆包大模型API密钥（可选，至少需要一个AI模型密钥） |
| DOUBAO_API_BASE | https://ark.cn-beijing.volces.com/api/v3 | 豆包大模型API基础URL |
| DOUBAO_MODEL_NAME | doubao-seed-1-6-flash-250615 | 豆包大模型名称 |
| AI_MODEL_TYPE | auto | AI模型类型选择（auto/deepseek/doubao） |
| API_KEY | *自动生成* | 本服务API访问密钥 |
| EXTRA_API_KEYS | - | 其他可用的API密钥，用逗号分隔 |

### 缓存与应用配置
| 环境变量 | 默认值 | 说明 |
|---------|-------|------|
| ADDRESS_CACHE_MAX_AGE_DAYS | 7 | 缓存有效期（天） |
| ADDRESS_CACHE_ENCRYPTION_KEY | *自动生成* | 缓存数据加密密钥 |
| APP_ENV | production | 应用环境（production或development） |

这些环境变量可以在以下位置配置：
1. `.env`文件中（推荐，便于管理）
2. Docker容器启动时通过`-e`参数传入
3. 使用`docker-compose.yml`或`docker-compose.prod.yml`中的`environment`部分

如果配置环境变量对您来说不方便，系统对大多数变量都提供了合理的默认值。只需要配置至少一个AI模型的API密钥（`DEEPSEEK_API_KEY` 或 `DOUBAO_API_KEY`）即可。

## 模型选择说明

项目支持两种AI大模型：
- **DeepSeek**: 高性能通用大模型，适合各种地址解析场景
- **豆包大模型**: 字节跳动推出的大模型，提供优异的中文理解能力

### 模型选择策略

通过 `AI_MODEL_TYPE` 环境变量可以控制模型选择：
- `auto` (默认): 系统自动选择可用的模型，优先使用豆包大模型，如果不可用则使用DeepSeek
- `deepseek`: 强制使用DeepSeek模型
- `doubao`: 强制使用豆包大模型

如果指定的模型不可用，系统会自动回退到其他可用模型。

## 项目测试 (待完善)

测试用例位于 `tests/` 目录下。可以使用 `pytest` 运行测试：

```bash
# 确保已安装 pytest (包含在 requirements.txt 中)
# 激活虚拟环境后
pytest tests/
```

也可以单独测试解析器功能：

```bash
# 测试DeepSeek模型
python test_parser.py

# 测试豆包大模型
python test_doubao_parser.py
```

## 项目优化 (思考方向)

1.  **模型选择与微调**:
    *   评估不同AI模型（DeepSeek、豆包大模型或其他模型）的效果和成本。
    *   考虑是否需要针对特定地址格式进行模型微调（如果平台支持）。
2.  **Prompt 工程**: 持续优化 `system_prompt` 和 `user_prompt` 以提高解析准确率和鲁棒性。
3.  **结果校验**: 对 AI 返回的 JSON 进行更严格的格式和内容校验（例如，使用 Pydantic 模型）。
4.  **性能**:
    *   对于高并发场景，使用生产级 WSGI 服务器（如 Gunicorn, uWSGI）替代 Flask 开发服务器。
    *   考虑异步处理 API 请求（例如使用 FastAPI 或 Flask + Celery）。
    *   已添加缓存机制，对于完全相同的地址输入，直接返回缓存结果，减少 API 调用。
    *   可进一步优化缓存策略，如考虑模糊匹配相似地址。
5.  **错误处理**: 提供更细致、用户友好的错误提示。
6.  **安全性**: 
    *   已实现API Key认证，保护API接口不被滥用。
    *   已实现缓存数据加密存储，保护用户地址隐私。
    *   可考虑添加请求频率限制(Rate Limiting)，进一步提高安全性。
7.  **可配置性**: 将模型名称、API 地址等配置移到配置文件或环境变量中，提高灵活性。
8.  **部署和运维**:
    *   已提供`deploy.sh`脚本简化部署操作，可进一步增加监控和告警功能。
    *   考虑添加自动备份数据、滚动更新和版本回滚等功能。
    *   优化Docker镜像，减小体积并提高启动速度。

## 总结

本项目提供了一个实用工具，通过多种AI大模型（DeepSeek和豆包大模型）简化了地址信息的结构化处理。它易于部署和使用，支持智能模型选择和自动切换，并通过缓存机制和数据加密提供了性能和隐私保护，API认证机制确保了服务的安全使用，为未来的功能扩展和性能优化奠定了基础。