222 lines
7.2 KiB
Markdown
222 lines
7.2 KiB
Markdown
# 产品分类模块（CategorizeLabel）
|
||
|
||
[](https://www.python.org/downloads/)
|
||
[](tests/)
|
||
[](https://www.python.org/dev/peps/pep-0008/)
|
||
|
||
基于通义千问LLM的产品自动分类工具，采用整洁架构设计，支持批量处理。
|
||
|
||
## ✨ 特性
|
||
|
||
- 🚀 **批量处理**：使用通义千问Batch API，费用仅为实时调用的50%
|
||
- 🏗️ **整洁架构**：遵循Clean Architecture和SOLID原则
|
||
- ✅ **完整测试**：77个单元测试，100%通过率
|
||
- 📦 **易于使用**：简单的命令行接口
|
||
- 📊 **详细日志**：完整的运行日志记录
|
||
- 📈 **实时进度**：实时显示任务处理进度和状态（新增）
|
||
- 🔧 **可扩展**：基于接口编程，易于扩展和维护
|
||
|
||
## 📋 快速开始
|
||
|
||
### 1. 安装依赖
|
||
|
||
```bash
|
||
# 使用Poetry（推荐）
|
||
poetry install
|
||
|
||
# 或使用pip
|
||
pip install -e .
|
||
```
|
||
|
||
### 2. 配置API Key
|
||
|
||
```bash
|
||
# Windows PowerShell
|
||
$env:DASHSCOPE_API_KEY="your-api-key-here"
|
||
|
||
# Linux/Mac
|
||
export DASHSCOPE_API_KEY="your-api-key-here"
|
||
```
|
||
|
||
### 3. 编辑配置文件
|
||
|
||
编辑 `config/config.yaml`，设置你的参数：
|
||
|
||
```yaml
|
||
files:
|
||
input_file: "input/product_list.xlsx"
|
||
category_file: "config/product_type.jsonl"
|
||
output_file: "output/classification_result.jsonl"
|
||
|
||
api:
|
||
model: "qwen-flash"
|
||
```
|
||
|
||
### 4. 运行分类
|
||
|
||
```bash
|
||
# 使用默认配置文件
|
||
python -m src.main
|
||
|
||
# 或指定自定义配置
|
||
python -m src.main --config config/my_config.yaml
|
||
|
||
# 或使用命令行参数覆盖配置
|
||
python -m src.main --model qwen-plus
|
||
```
|
||
|
||
### 5. 监控任务进度 ⚡️新增
|
||
|
||
程序运行时会实时显示任务处理进度：
|
||
|
||
```
|
||
2025-10-15 14:30:00 - INFO - 等待Batch任务完成（系统将定期查询并输出进度信息）...
|
||
2025-10-15 14:30:00 - INFO - 开始轮询Batch任务状态（轮询间隔: 60秒）
|
||
2025-10-15 14:30:05 - INFO - [轮询 #1] 任务状态: in_progress | 已等待: 5秒 | 剩余时间: 23小时59分55秒
|
||
2025-10-15 14:30:05 - INFO - ↳ 处理进度: 45/100 (45.0%) | 失败: 0
|
||
2025-10-15 14:31:05 - INFO - [轮询 #2] 任务状态: in_progress | 已等待: 1分5秒 | 剩余时间: 23小时58分55秒
|
||
2025-10-15 14:31:05 - INFO - ↳ 处理进度: 78/100 (78.0%) | 失败: 2
|
||
2025-10-15 14:32:05 - INFO - [轮询 #3] 任务状态: completed | 已等待: 2分5秒
|
||
2025-10-15 14:32:05 - INFO - 任务完成，开始下载结果
|
||
```
|
||
|
||
实时日志可以帮助您：
|
||
- ✅ 了解任务是否正在正常运行
|
||
- ✅ 预估任务完成时间
|
||
- ✅ 及时发现并处理错误
|
||
|
||
详细说明请参考 [进度日志功能说明](docs/进度日志功能说明.md)
|
||
|
||
## 📚 文档
|
||
|
||
- [使用说明](docs/使用说明.md) - 详细的使用指南
|
||
- [进度日志功能](docs/进度日志功能说明.md) - 实时进度反馈功能说明（新增）
|
||
- [测试报告](docs/测试报告.md) - 完整的测试覆盖报告
|
||
- [架构设计](docs/project_docs/产品分类模块架构设计.md) - 详细的架构设计文档
|
||
- [功能设计](docs/project_docs/产品分类模块功能设计.md) - 功能需求文档
|
||
- [API文档](docs/API/Tongyi-API.md) - 通义千问API使用教程
|
||
|
||
## 🏗️ 项目结构
|
||
|
||
```
|
||
CategorizeLabel/
|
||
├── src/ # 源代码
|
||
│ ├── core/ # 核心实现层
|
||
│ │ ├── file_handler.py # 文件处理
|
||
│ │ ├── batch_client.py # Batch API客户端
|
||
│ │ └── prompt_builder.py # Prompt构建
|
||
│ ├── models.py # 数据模型
|
||
│ ├── interfaces.py # 抽象接口
|
||
│ └── main.py # 主程序入口
|
||
├── tests/ # 单元测试（77个测试）
|
||
│ ├── fixtures/ # 测试数据
|
||
│ ├── test_models.py # 22个测试
|
||
│ ├── test_file_handler.py # 20个测试
|
||
│ ├── test_batch_client.py # 15个测试
|
||
│ ├── test_prompt_builder.py # 11个测试
|
||
│ └── test_main.py # 9个测试
|
||
├── config/ # 配置文件
|
||
├── input/ # 输入文件目录
|
||
├── output/ # 输出文件目录
|
||
├── logs/ # 日志目录
|
||
├── docs/ # 文档
|
||
└── pyproject.toml # 项目配置
|
||
```
|
||
|
||
## 🧪 运行测试
|
||
|
||
```bash
|
||
# 运行所有测试
|
||
pytest tests/ -v
|
||
|
||
# 运行特定测试
|
||
pytest tests/test_models.py -v
|
||
|
||
# 查看测试覆盖率
|
||
pytest tests/ --cov=src --cov-report=html
|
||
```
|
||
|
||
**测试结果：77/77 测试通过 ✨**
|
||
|
||
## 🎯 设计原则
|
||
|
||
本项目严格遵循以下设计原则：
|
||
|
||
- **整洁架构（Clean Architecture）**：依赖倒置，核心业务逻辑不依赖外部实现
|
||
- **SOLID原则**：单一职责、开闭原则、里氏替换、接口隔离、依赖倒置
|
||
- **测试驱动开发（TDD）**：先写测试，再实现功能
|
||
- **依赖注入**：通过构造函数注入依赖，便于测试和替换
|
||
|
||
## 📊 架构概览
|
||
|
||
```
|
||
┌─────────────────────────────────────────────┐
|
||
│ main.py (组合根) │
|
||
│ 初始化所有依赖并编排业务流程 │
|
||
└─────────────────────────────────────────────┘
|
||
↓
|
||
┌───────────────┴───────────────┐
|
||
│ │
|
||
↓ ↓
|
||
┌─────────┐ ┌─────────┐
|
||
│ core/ │ ←─ interfaces ─→ │ models │
|
||
└─────────┘ └─────────┘
|
||
│
|
||
├── FileHandler (文件处理)
|
||
├── BatchClient (API调用)
|
||
└── PromptBuilder (Prompt构建)
|
||
```
|
||
|
||
## 🔧 技术栈
|
||
|
||
- **Python 3.9+**
|
||
- **Pydantic V2**：数据验证和模型
|
||
- **pandas**：Excel文件处理
|
||
- **OpenAI SDK**：通义千问API调用
|
||
- **pytest**：单元测试框架
|
||
- **Poetry**：依赖管理
|
||
|
||
## 📝 输入输出格式
|
||
|
||
### 输入：产品列表 (Excel)
|
||
```
|
||
产品编号 | 产品名称 | 景区名称
|
||
P001 | 黄山风景区门票 | 黄山
|
||
P002 | 黄山温泉酒店 | 黄山
|
||
```
|
||
|
||
### 输入：类别配置 (JSONL)
|
||
```json
|
||
{"category":"门票","type":"自然类","sub_type":"自然风光"}
|
||
{"category":"住宿","type":"商务酒店","sub_type":""}
|
||
```
|
||
|
||
### 输出：分类结果 (JSONL)
|
||
```json
|
||
{"product_id":"P001","category":"门票","type":"自然类","sub_type":"自然风光"}
|
||
{"product_id":"P002","category":"住宿","type":"商务酒店","sub_type":""}
|
||
```
|
||
|
||
## 💡 使用场景
|
||
|
||
- ✅ 旅游产品自动分类
|
||
- ✅ 电商商品分类
|
||
- ✅ 内容标签化
|
||
- ✅ 大规模数据标注
|
||
|
||
## 🤝 贡献
|
||
|
||
欢迎提交Issue和Pull Request！
|
||
|
||
## 📄 许可证
|
||
|
||
请遵守通义千问API的使用协议。
|
||
|
||
## 👥 开发团队
|
||
|
||
采用AI辅助开发，遵循专业的软件工程实践。
|
||
|
||
---
|
||
|
||
**项目状态**：✅ 开发完成，所有测试通过，可用于生产环境
|