300 lines
6.9 KiB
Markdown
300 lines
6.9 KiB
Markdown
# AI 分析接口实现总结
|
||
|
||
## ✅ 实现完成
|
||
|
||
`/api/v1/inventory/ai-analyze` 接口已实现完成。
|
||
|
||
## 📋 实现内容
|
||
|
||
### 1. 数据模型（Schemas）
|
||
|
||
**文件**: `app/schemas/inventory.py`
|
||
|
||
- ✅ `FieldInput` - 字段输入模型
|
||
- ✅ `TableInput` - 表输入模型
|
||
- ✅ `AnalyzeOptions` - AI 分析选项
|
||
- ✅ `AIAnalyzeRequest` - AI 分析请求模型
|
||
- ✅ `FieldOutput` - 字段输出模型
|
||
- ✅ `TableOutput` - 表输出模型
|
||
- ✅ `Statistics` - 统计信息模型
|
||
- ✅ `TokenUsage` - Token 使用情况模型
|
||
- ✅ `AIAnalyzeResponse` - AI 分析响应模型
|
||
|
||
### 2. 业务逻辑服务（Services）
|
||
|
||
**文件**: `app/services/ai_analyze_service.py`
|
||
|
||
- ✅ `AIAnalyzeService` - AI 分析服务类
|
||
- ✅ `analyze()` - 主要分析方法
|
||
- ✅ `build_prompt()` - 提示词构建
|
||
- ✅ `validate_pii_detection()` - PII 识别规则引擎
|
||
- ✅ `calculate_confidence()` - 置信度评分算法
|
||
|
||
### 3. 路由处理（Routes）
|
||
|
||
**文件**: `app/api/v1/inventory/routes.py`
|
||
|
||
- ✅ `ai_analyze()` - 路由处理函数
|
||
- ✅ 请求验证（通过 Pydantic 模型）
|
||
- ✅ 调用业务服务
|
||
- ✅ 异常处理
|
||
- ✅ 日志记录
|
||
|
||
### 4. 提示词模板
|
||
|
||
- ✅ 系统提示词（`SYSTEM_PROMPT`）
|
||
- ✅ 用户提示词模板（`USER_PROMPT_TEMPLATE`）
|
||
- ✅ JSON Schema 定义（`JSON_SCHEMA`）
|
||
|
||
### 5. 规则引擎
|
||
|
||
- ✅ PII 识别规则（`PII_KEYWORDS`）
|
||
- 手机号识别
|
||
- 身份证号识别
|
||
- 姓名识别
|
||
- 邮箱识别
|
||
- 地址识别
|
||
- 银行卡号识别
|
||
|
||
### 6. 置信度评分算法
|
||
|
||
- ✅ 命名规范度评分（30分）
|
||
- ✅ 注释完整性评分（20分）
|
||
- ✅ AI 识别结果质量评分（30分）
|
||
- ✅ 基础分（50分）
|
||
|
||
## 🔧 核心功能
|
||
|
||
### 1. 表名和字段名中文命名识别
|
||
|
||
- 使用大模型将英文表名/字段名转换为中文名称
|
||
- 识别业务含义
|
||
|
||
### 2. 业务含义描述生成
|
||
|
||
- 自动生成表的中文描述
|
||
- 自动生成字段的中文描述
|
||
|
||
### 3. PII（个人信息）识别
|
||
|
||
- 符合《个人信息保护法》(PIPL) 要求
|
||
- 识别类型：
|
||
- 手机号
|
||
- 身份证号
|
||
- 姓名
|
||
- 邮箱
|
||
- 地址
|
||
- 银行卡号
|
||
- 规则引擎补充识别
|
||
|
||
### 4. 重要数据识别
|
||
|
||
- 识别《数据安全法》定义的重要数据
|
||
- 涉及国家安全、公共利益的数据
|
||
|
||
### 5. 置信度评分
|
||
|
||
- 评估识别结果的可靠性（0-100%）
|
||
- 考虑因素：
|
||
- 字段命名规范度
|
||
- 注释完整性
|
||
- 业务含义明确度
|
||
|
||
## 📊 接口信息
|
||
|
||
### 请求路径
|
||
|
||
```
|
||
POST /api/v1/inventory/ai-analyze
|
||
```
|
||
|
||
### 请求格式
|
||
|
||
```json
|
||
{
|
||
"tables": [
|
||
{
|
||
"raw_name": "t_user_base_01",
|
||
"fields": [
|
||
{
|
||
"raw_name": "user_id",
|
||
"type": "varchar(64)",
|
||
"comment": "用户ID"
|
||
}
|
||
]
|
||
}
|
||
],
|
||
"project_id": "project_001",
|
||
"industry": "retail-fresh",
|
||
"context": "业务背景信息",
|
||
"options": {
|
||
"model": "qwen-max",
|
||
"temperature": 0.3,
|
||
"enable_pii_detection": true,
|
||
"enable_important_data_detection": true
|
||
}
|
||
}
|
||
```
|
||
|
||
### 响应格式
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"code": 200,
|
||
"message": "数据资产识别成功",
|
||
"data": {
|
||
"tables": [...],
|
||
"statistics": {
|
||
"total_tables": 1,
|
||
"total_fields": 3,
|
||
"pii_fields_count": 2,
|
||
"important_data_fields_count": 0,
|
||
"average_confidence": 97.3
|
||
},
|
||
"processing_time": 5.2,
|
||
"model_used": "qwen-max",
|
||
"token_usage": {
|
||
"prompt_tokens": 1200,
|
||
"completion_tokens": 800,
|
||
"total_tokens": 2000
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 🧪 测试
|
||
|
||
测试文件：`tests/test_ai_analyze.py`
|
||
|
||
包含以下测试用例：
|
||
- ✅ 测试 AI 分析成功
|
||
- ✅ 测试请求验证
|
||
- ✅ 测试空表列表
|
||
|
||
## 🚀 使用示例
|
||
|
||
### Python 调用示例
|
||
|
||
```python
|
||
import httpx
|
||
import asyncio
|
||
|
||
async def test_ai_analyze():
|
||
async with httpx.AsyncClient() as client:
|
||
response = await client.post(
|
||
"http://localhost:8000/api/v1/inventory/ai-analyze",
|
||
json={
|
||
"tables": [
|
||
{
|
||
"raw_name": "t_user_base_01",
|
||
"fields": [
|
||
{
|
||
"raw_name": "user_id",
|
||
"type": "varchar(64)",
|
||
"comment": "用户ID"
|
||
},
|
||
{
|
||
"raw_name": "phone",
|
||
"type": "varchar(11)",
|
||
"comment": "手机号"
|
||
}
|
||
]
|
||
}
|
||
],
|
||
"project_id": "project_001",
|
||
"industry": "retail-fresh",
|
||
"context": "某连锁生鲜零售企业",
|
||
"options": {
|
||
"model": "qwen-max",
|
||
"temperature": 0.3
|
||
}
|
||
}
|
||
)
|
||
print(response.json())
|
||
|
||
asyncio.run(test_ai_analyze())
|
||
```
|
||
|
||
### cURL 调用示例
|
||
|
||
```bash
|
||
curl -X POST "http://localhost:8000/api/v1/inventory/ai-analyze" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"tables": [
|
||
{
|
||
"raw_name": "t_user_base_01",
|
||
"fields": [
|
||
{
|
||
"raw_name": "user_id",
|
||
"type": "varchar(64)",
|
||
"comment": "用户ID"
|
||
}
|
||
]
|
||
}
|
||
],
|
||
"project_id": "project_001",
|
||
"industry": "retail-fresh"
|
||
}'
|
||
```
|
||
|
||
## ⚙️ 配置要求
|
||
|
||
### 环境变量
|
||
|
||
需要在 `.env` 文件中配置：
|
||
|
||
```bash
|
||
# 通义千问 API Key（必须）
|
||
DASHSCOPE_API_KEY=your_dashscope_api_key_here
|
||
|
||
# 默认大模型
|
||
DEFAULT_LLM_MODEL=qwen-max
|
||
|
||
# 默认温度参数
|
||
DEFAULT_TEMPERATURE=0.3
|
||
|
||
# 超时时间（秒）
|
||
LLM_TIMEOUT=60
|
||
|
||
# 最大重试次数
|
||
LLM_MAX_RETRIES=3
|
||
```
|
||
|
||
## 📝 注意事项
|
||
|
||
1. **API Key 配置**：必须配置 `DASHSCOPE_API_KEY` 才能使用通义千问模型
|
||
2. **Token 消耗**：大模型调用会消耗 Token，注意成本控制
|
||
3. **超时处理**：默认超时 60 秒，大表可能需要更长时间
|
||
4. **重试机制**：已实现自动重试（指数退避），最多重试 3 次
|
||
5. **规则引擎**：PII 识别使用规则引擎补充，提高准确率
|
||
6. **置信度评分**：基于命名规范、注释完整性和 AI 识别质量
|
||
|
||
## 🎯 下一步优化建议
|
||
|
||
1. **缓存机制**：对相同输入进行缓存，减少 API 调用
|
||
2. **批量处理**：对于大量表，考虑批量调用或分批处理
|
||
3. **流式输出**：对于大表，考虑流式返回结果
|
||
4. **更精确的 Token 统计**：使用实际 API 返回的 Token 统计
|
||
5. **更多 PII 类型**：扩展 PII 识别规则，支持更多类型
|
||
6. **重要数据识别优化**：改进重要数据识别算法
|
||
|
||
## ✅ 完成状态
|
||
|
||
- [x] 请求和响应模型
|
||
- [x] 业务逻辑服务
|
||
- [x] 路由处理函数
|
||
- [x] 提示词模板
|
||
- [x] 规则引擎验证
|
||
- [x] 置信度评分算法
|
||
- [x] 异常处理
|
||
- [x] 日志记录
|
||
- [x] API 文档（自动生成）
|
||
- [x] 单元测试（基础）
|
||
|
||
---
|
||
|
||
**实现完成时间**: 2025-01-XX
|
||
**接口状态**: ✅ 已完成并可用
|