Initial commit: MSH System\n\n- msh_single_uniapp: Vue 2 + UniApp 前端（微信小程序/H5/App/支付宝小程序）\n- msh_crmeb_22: Spring Boot 2.2 后端（C端API/管理端/业务逻辑）\n- models-integration: AI服务集成（Coze/KieAI/腾讯ASR）\n- docs: 产品文档与设计稿
This commit is contained in:
117
models-integration/docs/NANO_BANANA_INTEGRATION_SUMMARY.md
Normal file
117
models-integration/docs/NANO_BANANA_INTEGRATION_SUMMARY.md
Normal file
@@ -0,0 +1,117 @@
|
||||
# Nano Banana API 集成项目总结
|
||||
|
||||
## 项目状态
|
||||
✅ **项目集成完成并成功启动**
|
||||
|
||||
应用程序已在端口 5081 上成功启动，所有API端点均可正常访问。
|
||||
|
||||
## 已完成的功能模块
|
||||
|
||||
### 1. 核心业务组件
|
||||
- ✅ **KieAI2ImageController** - REST API控制器，提供完整的任务管理接口
|
||||
- ✅ **NanoBananaService** - 业务逻辑服务层，实现任务创建、查询、状态管理
|
||||
- ✅ **NanoBananaHelper** - HTTP客户端工具类，封装与Nano Banana API的通信
|
||||
- ✅ **NanoBananaTask** - 任务实体模型，使用MyBatis Plus注解
|
||||
- ✅ **NanoBananaTaskMapper** - 数据访问层接口
|
||||
|
||||
### 2. 枚举类定义
|
||||
- ✅ **NanoBananaModelType** - 模型类型枚举（NANO_BANANA, NANO_BANANA_EDIT）
|
||||
- ✅ **NanoBananaTaskState** - 任务状态枚举（PENDING, RUNNING, SUCCESS, FAILED）
|
||||
- ✅ **OutputFormat** - 输出格式枚举（PNG, JPG, WEBP）
|
||||
- ✅ **ImageSize** - 图片尺寸枚举（多种预设尺寸）
|
||||
|
||||
### 3. 请求响应模型
|
||||
- ✅ **CreateTaskRequest** - 创建任务请求模型
|
||||
- ✅ **TaskResponse** - 任务响应模型
|
||||
- ✅ **ApiResponse** - 统一API响应格式
|
||||
|
||||
### 4. 配置文件
|
||||
- ✅ **application.yml** - 添加了Nano Banana API相关配置
|
||||
- ✅ **RestTemplate Bean** - 在Application类中配置HTTP客户端
|
||||
- ✅ **MyBatis扫描配置** - 启用Mapper自动扫描
|
||||
|
||||
### 5. 数据库支持
|
||||
- ✅ **SQL脚本** - nano_banana_task表创建脚本
|
||||
- ✅ **MyBatis XML映射** - 完整的CRUD操作映射（已备份，待数据库表创建后启用）
|
||||
|
||||
## API端点列表
|
||||
|
||||
### 任务管理接口
|
||||
- `POST /api/nano-banana/text-to-image` - 创建文本转图片任务
|
||||
- `POST /api/nano-banana/image-edit` - 创建图片编辑任务
|
||||
- `GET /api/nano-banana/tasks/{taskId}/status` - 查询任务状态
|
||||
- `GET /api/nano-banana/tasks/{taskId}/wait` - 等待任务完成
|
||||
- `POST /api/nano-banana/callback` - 处理回调通知
|
||||
- `GET /api/nano-banana/tasks/{taskId}` - 获取任务详情
|
||||
- `GET /api/nano-banana/tasks` - 获取任务列表
|
||||
- `POST /api/nano-banana/tasks/{taskId}/retry` - 重试任务
|
||||
- `DELETE /api/nano-banana/tasks/{taskId}` - 取消任务
|
||||
|
||||
## 访问地址
|
||||
- **应用程序**: http://localhost:5081
|
||||
- **Swagger文档**: http://localhost:5081/swagger-ui/index.html
|
||||
- **API基础路径**: http://localhost:5081/api/nano-banana
|
||||
|
||||
## 待完成事项
|
||||
|
||||
### 数据库初始化
|
||||
需要手动执行SQL脚本创建数据库表：
|
||||
|
||||
```sql
|
||||
-- 连接信息
|
||||
Host: 118.89.113.119:3306
|
||||
Database: jzjg_jxz
|
||||
Username: baisui
|
||||
Password: fFmTJhBEFSnYGYW7
|
||||
|
||||
-- 执行脚本
|
||||
src/main/resources/sql/nano_banana_task.sql
|
||||
```
|
||||
|
||||
### MyBatis XML映射启用
|
||||
数据库表创建完成后，需要：
|
||||
1. 将 `NanoBananaTaskMapper.xml.bak` 重命名为 `NanoBananaTaskMapper.xml`
|
||||
2. 重启应用程序
|
||||
|
||||
## 配置说明
|
||||
|
||||
### Nano Banana API配置
|
||||
```yaml
|
||||
nano-banana:
|
||||
base-url: https://api.nanobanana.com
|
||||
api-token: your-api-token-here
|
||||
connect-timeout: 30000
|
||||
read-timeout: 60000
|
||||
write-timeout: 60000
|
||||
retry-max-attempts: 3
|
||||
retry-delay: 1000
|
||||
poll-interval: 2000
|
||||
max-wait-time: 300000
|
||||
callback-enabled: true
|
||||
default-output-format: PNG
|
||||
default-image-size: "1024x1024"
|
||||
```
|
||||
|
||||
## 技术栈
|
||||
- **Spring Boot 2.7.5** - 应用框架
|
||||
- **MyBatis Plus** - ORM框架
|
||||
- **RestTemplate** - HTTP客户端
|
||||
- **Swagger 3** - API文档
|
||||
- **MySQL** - 数据库
|
||||
- **Druid** - 数据库连接池
|
||||
|
||||
## 项目特点
|
||||
1. **完整的任务生命周期管理** - 从创建到完成的全流程跟踪
|
||||
2. **异步任务处理** - 支持轮询和回调两种方式
|
||||
3. **错误处理和重试机制** - 提供完善的异常处理
|
||||
4. **RESTful API设计** - 遵循REST规范
|
||||
5. **完整的API文档** - 集成Swagger UI
|
||||
6. **数据持久化** - 任务状态和结果的完整记录
|
||||
|
||||
## 使用建议
|
||||
1. 首先完成数据库表的创建
|
||||
2. 配置正确的Nano Banana API Token
|
||||
3. 根据实际需求调整超时和重试参数
|
||||
4. 监控日志文件以跟踪任务执行状态
|
||||
|
||||
项目已准备就绪，可以开始使用Nano Banana API进行图片生成和编辑任务！
|
||||
363
models-integration/docs/TENCENT_ASR_README.md
Normal file
363
models-integration/docs/TENCENT_ASR_README.md
Normal file
@@ -0,0 +1,363 @@
|
||||
# 腾讯云语音识别API对接文档
|
||||
|
||||
## 功能概述
|
||||
|
||||
本项目已成功集成腾讯云语音识别（ASR）服务，提供了以下功能：
|
||||
|
||||
1. **录音文件识别**：适用于较长的音频文件，采用异步方式识别
|
||||
2. **一句话识别**：适用于60秒以内的短音频，采用同步方式识别
|
||||
3. **任务状态查询**：查询异步识别任务的状态和结果
|
||||
|
||||
## API文档参考
|
||||
|
||||
- 官方文档：https://cloud.tencent.com/document/product/1093/35637
|
||||
- API概览：https://cloud.tencent.com/document/api/1093/35640
|
||||
|
||||
## 配置说明
|
||||
|
||||
### 1. 配置文件 (application.yml)
|
||||
|
||||
```yaml
|
||||
# 腾讯云语音识别配置
|
||||
tencent-asr:
|
||||
# API密钥ID
|
||||
secret-id: AKIDf9OM3TdWBZqqZ1C7k6B0Ypqb6KIzQaT5
|
||||
# API密钥Key（需要在实际使用时提供）
|
||||
secret-key: ${TENCENT_SECRET_KEY:}
|
||||
# API地区
|
||||
region: ap-shanghai
|
||||
# 连接超时时间（毫秒）
|
||||
connect-timeout: 30000
|
||||
# 读取超时时间（毫秒）
|
||||
read-timeout: 60000
|
||||
# 默认引擎模型类型（16k_zh：中文普通话、16k_en：英文）
|
||||
default-engine-model: 16k_zh
|
||||
# 默认结果文本格式（0：识别结果文本，包含标点符号；1：不带标点的识别结果）
|
||||
default-res-text-format: 0
|
||||
# 默认音频声道数（1：单声道；2：双声道）
|
||||
default-channel-num: 1
|
||||
# 是否启用
|
||||
enabled: true
|
||||
```
|
||||
|
||||
### 2. 环境变量配置
|
||||
|
||||
为了安全起见，建议通过环境变量设置 SecretKey：
|
||||
|
||||
```bash
|
||||
export TENCENT_SECRET_KEY=your_secret_key_here
|
||||
```
|
||||
|
||||
或在启动命令中指定：
|
||||
|
||||
```bash
|
||||
java -jar models-integration-0.0.1.jar --tencent-asr.secret-key=your_secret_key_here
|
||||
```
|
||||
|
||||
## API接口说明
|
||||
|
||||
### 基础URL
|
||||
|
||||
```
|
||||
http://localhost:5081/api/tencent/asr
|
||||
```
|
||||
|
||||
### 1. 创建录音文件识别任务
|
||||
|
||||
**接口地址**：`POST /api/tencent/asr/create-task`
|
||||
|
||||
**适用场景**：适用于较长的音频文件（支持多种格式：wav、pcm、mp3、silk、speex、amr、m4a等）
|
||||
|
||||
**请求示例**：
|
||||
|
||||
```json
|
||||
{
|
||||
"url": "https://example.com/audio.wav",
|
||||
"engineModelType": "16k_zh",
|
||||
"channelNum": 1,
|
||||
"resTextFormat": 0,
|
||||
"sourceType": 0,
|
||||
"callbackUrl": "https://your-callback-url.com/callback",
|
||||
"filterDirty": false,
|
||||
"filterModal": false,
|
||||
"convertNumMode": true
|
||||
}
|
||||
```
|
||||
|
||||
**请求参数说明**：
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| url | String | 是 | 音频文件URL地址 |
|
||||
| engineModelType | String | 否 | 引擎模型类型，默认：16k_zh |
|
||||
| channelNum | Integer | 否 | 音频声道数，1：单声道；2：双声道，默认：1 |
|
||||
| resTextFormat | Integer | 否 | 识别结果文本格式，0：带标点；1：不带标点，默认：0 |
|
||||
| sourceType | Integer | 否 | 音频来源，0：音频URL；1：音频数据（base64），默认：0 |
|
||||
| callbackUrl | String | 否 | 回调URL，任务完成后将结果POST到该地址 |
|
||||
| hotwordId | String | 否 | 热词表ID，用于提高专有名词识别准确率 |
|
||||
| filterDirty | Boolean | 否 | 是否过滤脏词，默认：false |
|
||||
| filterModal | Boolean | 否 | 是否过滤语气词，默认：false |
|
||||
| convertNumMode | Boolean | 否 | 是否进行阿拉伯数字智能转换，默认：false |
|
||||
|
||||
**响应示例**：
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"taskId": "1234567890",
|
||||
"status": 0,
|
||||
"statusStr": "等待处理",
|
||||
"requestId": "req_abc123def456",
|
||||
"errorCode": 0,
|
||||
"errorMsg": "成功"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**引擎模型类型说明**：
|
||||
|
||||
- `16k_zh`：16k 中文普通话通用
|
||||
- `16k_zh_video`：16k 音视频领域
|
||||
- `16k_en`：16k 英语
|
||||
- `16k_ca`：16k 粤语
|
||||
- `8k_zh`：8k 中文普通话通用
|
||||
|
||||
### 2. 查询识别任务状态
|
||||
|
||||
**接口地址**：`GET /api/tencent/asr/query-status/{taskId}`
|
||||
|
||||
**适用场景**：查询异步识别任务的状态和结果
|
||||
|
||||
**请求示例**：
|
||||
|
||||
```
|
||||
GET /api/tencent/asr/query-status/1234567890
|
||||
```
|
||||
|
||||
**响应示例**：
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"taskId": "1234567890",
|
||||
"status": 2,
|
||||
"statusStr": "识别成功",
|
||||
"result": "你好，这是一段语音识别测试内容。",
|
||||
"audioDuration": 5.5,
|
||||
"errorCode": 0,
|
||||
"errorMsg": "",
|
||||
"resultDetail": "{\"Result\":[{\"Text\":\"你好，这是一段语音识别测试内容。\"}]}"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**任务状态说明**：
|
||||
|
||||
- `0`：等待处理
|
||||
- `1`：执行中
|
||||
- `2`：识别成功
|
||||
- `3`：识别失败
|
||||
|
||||
### 3. 一句话识别
|
||||
|
||||
**接口地址**：`POST /api/tencent/asr/sentence-recognition`
|
||||
|
||||
**适用场景**：适用于60秒以内的短音频，同步返回识别结果
|
||||
|
||||
**请求示例**：
|
||||
|
||||
```json
|
||||
{
|
||||
"url": "https://example.com/short-audio.wav",
|
||||
"engineModelType": "16k_zh",
|
||||
"sourceType": 0,
|
||||
"filterDirty": false,
|
||||
"filterModal": false,
|
||||
"convertNumMode": true
|
||||
}
|
||||
```
|
||||
|
||||
**请求参数说明**：参数与创建任务接口相同，但不需要 callbackUrl
|
||||
|
||||
**响应示例**：
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"status": 2,
|
||||
"statusStr": "识别成功",
|
||||
"result": "你好世界",
|
||||
"audioDuration": 1.5,
|
||||
"requestId": "req_xyz789",
|
||||
"errorCode": 0,
|
||||
"errorMsg": "成功"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 健康检查
|
||||
|
||||
**接口地址**：`GET /api/tencent/asr/health`
|
||||
|
||||
**适用场景**：检查服务是否正常运行
|
||||
|
||||
**响应示例**：
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "success",
|
||||
"data": "腾讯云语音识别服务运行正常"
|
||||
}
|
||||
```
|
||||
|
||||
## 使用流程
|
||||
|
||||
### 场景1：长音频识别（异步）
|
||||
|
||||
1. 调用 **创建录音文件识别任务** 接口，获取 taskId
|
||||
2. 使用 taskId 调用 **查询识别任务状态** 接口
|
||||
3. 当 status 为 2 时，表示识别成功，可从 result 字段获取识别结果
|
||||
|
||||
### 场景2：短音频识别（同步）
|
||||
|
||||
1. 直接调用 **一句话识别** 接口
|
||||
2. 同步返回识别结果
|
||||
|
||||
## 测试示例
|
||||
|
||||
### 使用 curl 测试
|
||||
|
||||
#### 1. 创建识别任务
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:5081/api/tencent/asr/create-task \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"url": "https://example.com/audio.wav",
|
||||
"engineModelType": "16k_zh",
|
||||
"channelNum": 1,
|
||||
"resTextFormat": 0,
|
||||
"convertNumMode": true
|
||||
}'
|
||||
```
|
||||
|
||||
#### 2. 查询任务状态
|
||||
|
||||
```bash
|
||||
curl http://localhost:5081/api/tencent/asr/query-status/1234567890
|
||||
```
|
||||
|
||||
#### 3. 一句话识别
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:5081/api/tencent/asr/sentence-recognition \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"url": "https://example.com/short-audio.wav",
|
||||
"engineModelType": "16k_zh",
|
||||
"convertNumMode": true
|
||||
}'
|
||||
```
|
||||
|
||||
### 使用 Swagger UI 测试
|
||||
|
||||
启动应用后，访问：http://localhost:5081/swagger-ui.html
|
||||
|
||||
在 Swagger UI 中找到 "腾讯云语音识别接口" 分组，即可进行可视化测试。
|
||||
|
||||
## 音频格式要求
|
||||
|
||||
### 支持的音频格式
|
||||
|
||||
- wav
|
||||
- pcm
|
||||
- mp3
|
||||
- silk
|
||||
- speex
|
||||
- amr
|
||||
- m4a
|
||||
|
||||
### 音频参数建议
|
||||
|
||||
- **采样率**：16k 或 8k（根据选择的引擎模型）
|
||||
- **位深度**：16bit
|
||||
- **声道数**：1（单声道）或 2（双声道）
|
||||
- **编码**：PCM
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **API密钥安全**：
|
||||
- 不要将 SecretKey 直接写入配置文件
|
||||
- 建议使用环境变量或密钥管理服务
|
||||
|
||||
2. **音频时长限制**：
|
||||
- 一句话识别：≤ 60秒
|
||||
- 录音文件识别：≤ 5小时
|
||||
|
||||
3. **音频大小限制**：
|
||||
- 单个音频文件 ≤ 500MB
|
||||
|
||||
4. **回调地址**：
|
||||
- 如果设置了 callbackUrl，任务完成后会自动回调
|
||||
- 回调地址必须是公网可访问的 HTTP/HTTPS 地址
|
||||
|
||||
5. **费用说明**：
|
||||
- 腾讯云语音识别服务按使用量计费
|
||||
- 请在腾讯云控制台查看具体计费标准
|
||||
|
||||
## 错误处理
|
||||
|
||||
常见错误码：
|
||||
|
||||
| 错误码 | 说明 | 解决方案 |
|
||||
|--------|------|----------|
|
||||
| InvalidParameter | 参数错误 | 检查请求参数是否正确 |
|
||||
| AuthFailure.SignatureFailure | 签名错误 | 检查 SecretId 和 SecretKey 是否正确 |
|
||||
| ResourceUnavailable.NotFound | 资源不存在 | 检查 taskId 是否正确 |
|
||||
| LimitExceeded | 超过配额限制 | 联系腾讯云增加配额 |
|
||||
|
||||
## 项目结构
|
||||
|
||||
```
|
||||
src/main/java/com/integration/api/
|
||||
├── config/
|
||||
│ └── TencentAsrConfig.java # 腾讯云ASR配置类
|
||||
├── controller/
|
||||
│ └── TencentAsrController.java # ASR控制器
|
||||
├── dto/
|
||||
│ ├── TencentAsrRequest.java # ASR请求DTO
|
||||
│ ├── TencentAsrResponse.java # ASR响应DTO
|
||||
│ └── TencentAsrTaskStatus.java # ASR任务状态DTO
|
||||
└── service/
|
||||
├── TencentAsrService.java # ASR服务接口
|
||||
└── impl/
|
||||
└── TencentAsrServiceImpl.java # ASR服务实现类
|
||||
```
|
||||
|
||||
## 依赖说明
|
||||
|
||||
项目使用了腾讯云官方 Java SDK：
|
||||
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>com.tencentcloudapi</groupId>
|
||||
<artifactId>tencentcloud-sdk-java</artifactId>
|
||||
<version>3.1.909</version>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
## 联系方式
|
||||
|
||||
如有问题，请联系项目维护者或查看腾讯云官方文档。
|
||||
|
||||
## 更新日志
|
||||
|
||||
- **2025-11-05**：初始版本，实现录音文件识别、一句话识别和任务查询功能
|
||||
|
||||
221
models-integration/docs/TENCENT_ASR_配置指南.md
Normal file
221
models-integration/docs/TENCENT_ASR_配置指南.md
Normal file
@@ -0,0 +1,221 @@
|
||||
# 腾讯云语音识别 - 快速配置指南
|
||||
|
||||
## ⚠️ 当前错误
|
||||
|
||||
您遇到的错误：
|
||||
```
|
||||
The provided credentials could not be validated. Please check your signature is correct.
|
||||
```
|
||||
|
||||
**原因**：SecretKey 未配置或配置错误
|
||||
|
||||
---
|
||||
|
||||
## 🔧 解决方案（3种方式任选其一）
|
||||
|
||||
### 方式1：环境变量配置（✅ 推荐，最安全）
|
||||
|
||||
#### 步骤1：获取完整的密钥对
|
||||
1. 登录腾讯云控制台
|
||||
2. 访问：https://console.cloud.tencent.com/cam/capi
|
||||
3. 找到您的 SecretId：`AKIDf9OM3TdWBZqqZ1C7k6B0Ypqb6KIzQaT5`
|
||||
4. 复制对应的 **SecretKey**（通常是一个40位的字符串）
|
||||
|
||||
#### 步骤2：设置环境变量
|
||||
```bash
|
||||
# 设置环境变量
|
||||
export TENCENT_SECRET_KEY="你的SecretKey"
|
||||
|
||||
# 验证是否设置成功
|
||||
echo $TENCENT_SECRET_KEY
|
||||
```
|
||||
|
||||
#### 步骤3：重启应用
|
||||
```bash
|
||||
# 停止应用
|
||||
./stop.sh
|
||||
|
||||
# 启动应用（会自动读取环境变量）
|
||||
./start.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 方式2：修改 application.yml（⚠️ 不推荐生产环境）
|
||||
|
||||
编辑配置文件：
|
||||
```yaml
|
||||
tencent-asr:
|
||||
secret-id: AKIDf9OM3TdWBZqqZ1C7k6B0Ypqb6KIzQaT5
|
||||
secret-key: 你的SecretKey # 直接填写，但不要提交到Git
|
||||
```
|
||||
|
||||
然后重启应用。
|
||||
|
||||
---
|
||||
|
||||
### 方式3：启动时指定参数
|
||||
|
||||
```bash
|
||||
java -jar target/models-integration-0.0.1.jar \
|
||||
--tencent-asr.secret-key=你的SecretKey
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✅ 验证配置
|
||||
|
||||
重启应用后，访问配置检查接口验证：
|
||||
|
||||
```bash
|
||||
curl http://localhost:5081/api/tencent/asr/config-check
|
||||
```
|
||||
|
||||
**成功响应示例**：
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "success",
|
||||
"data": "✅ 配置已正确加载（API密钥验证通过）"
|
||||
}
|
||||
```
|
||||
|
||||
**失败响应示例**：
|
||||
```json
|
||||
{
|
||||
"code": 500,
|
||||
"message": "fail",
|
||||
"data": "❌ 配置错误：SecretKey 未配置。\n\n解决方案：\n1. 设置环境变量：export TENCENT_SECRET_KEY=你的密钥\n2. 或在 application.yml 中配置 tencent-asr.secret-key"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧪 测试接口
|
||||
|
||||
### 1. 配置检查（新增）
|
||||
```bash
|
||||
curl http://localhost:5081/api/tencent/asr/config-check
|
||||
```
|
||||
|
||||
### 2. 健康检查
|
||||
```bash
|
||||
curl http://localhost:5081/api/tencent/asr/health
|
||||
```
|
||||
|
||||
### 3. 一句话识别测试
|
||||
```bash
|
||||
curl -X POST http://localhost:5081/api/tencent/asr/sentence-recognition \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"url": "http://jxz.uj345.cc/static/images/xhs-wechat.mp3",
|
||||
"engineModelType": "16k_zh"
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔐 安全提醒
|
||||
|
||||
### ❌ 不要做：
|
||||
- ❌ 将 SecretKey 提交到 Git 仓库
|
||||
- ❌ 在代码中硬编码密钥
|
||||
- ❌ 在公共场合分享密钥
|
||||
- ❌ 在日志中输出完整密钥
|
||||
|
||||
### ✅ 应该做：
|
||||
- ✅ 使用环境变量管理密钥
|
||||
- ✅ 使用密钥管理服务（如 Vault）
|
||||
- ✅ 定期轮换密钥
|
||||
- ✅ 为不同环境使用不同的密钥
|
||||
|
||||
---
|
||||
|
||||
## 📋 当前配置状态
|
||||
|
||||
### application.yml 中的配置：
|
||||
```yaml
|
||||
tencent-asr:
|
||||
secret-id: AKIDf9OM3TdWBZqqZ1C7k6B0Ypqb6KIzQaT5 # ✅ 已配置
|
||||
secret-key: ${TENCENT_SECRET_KEY:} # ❌ 需要配置
|
||||
region: ap-shanghai # ✅ 已配置
|
||||
default-engine-model: 16k_zh # ✅ 已配置
|
||||
```
|
||||
|
||||
**问题**：`secret-key: ${TENCENT_SECRET_KEY:}` 表示从环境变量读取，如果环境变量不存在，值为空。
|
||||
|
||||
---
|
||||
|
||||
## 🚀 快速开始（完整流程）
|
||||
|
||||
### 1. 获取密钥
|
||||
访问：https://console.cloud.tencent.com/cam/capi
|
||||
|
||||
### 2. 设置环境变量
|
||||
```bash
|
||||
export TENCENT_SECRET_KEY="你的40位SecretKey"
|
||||
```
|
||||
|
||||
### 3. 重启应用
|
||||
```bash
|
||||
./stop.sh && ./start.sh
|
||||
```
|
||||
|
||||
### 4. 验证配置
|
||||
```bash
|
||||
curl http://localhost:5081/api/tencent/asr/config-check
|
||||
```
|
||||
|
||||
### 5. 测试识别
|
||||
```bash
|
||||
curl -X POST http://localhost:5081/api/tencent/asr/sentence-recognition \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"url": "http://jxz.uj345.cc/static/images/xhs-wechat.mp3",
|
||||
"engineModelType": "16k_zh",
|
||||
"convertNumMode": true
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💡 常见问题
|
||||
|
||||
### Q1: 如何知道密钥是否配置成功？
|
||||
A: 访问 `/api/tencent/asr/config-check` 接口，会明确告诉您配置状态。
|
||||
|
||||
### Q2: 重启应用后环境变量丢失怎么办？
|
||||
A: 将 `export TENCENT_SECRET_KEY="..."` 添加到 `~/.bashrc` 或 `~/.zshrc` 文件中，或使用启动脚本。
|
||||
|
||||
### Q3: 可以把密钥写到配置文件吗？
|
||||
A: 可以，但不推荐。如果必须这样做，请确保：
|
||||
- 将 `application.yml` 添加到 `.gitignore`
|
||||
- 使用 `application-prod.yml` 区分环境
|
||||
- 只在测试环境使用
|
||||
|
||||
### Q4: 如何在启动脚本中设置环境变量？
|
||||
A: 修改 `start.sh` 文件：
|
||||
```bash
|
||||
#!/bin/bash
|
||||
export TENCENT_SECRET_KEY="你的密钥"
|
||||
nohup java -jar target/models-integration-0.0.1.jar > logs/api-demo.log 2>&1 &
|
||||
echo $! > app.pid
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📞 需要帮助？
|
||||
|
||||
如果按照以上步骤操作后仍有问题，请检查：
|
||||
|
||||
1. ✅ SecretId 和 SecretKey 是否匹配（同一对密钥）
|
||||
2. ✅ 环境变量是否在应用启动前设置
|
||||
3. ✅ 应用是否已重启
|
||||
4. ✅ 密钥是否有语音识别服务的权限
|
||||
5. ✅ 腾讯云账号是否已开通语音识别服务
|
||||
|
||||
访问配置检查接口可获得详细的错误信息：
|
||||
```bash
|
||||
curl http://localhost:5081/api/tencent/asr/config-check
|
||||
```
|
||||
|
||||
196
models-integration/docs/coze-integration-prd.md
Normal file
196
models-integration/docs/coze-integration-prd.md
Normal file
@@ -0,0 +1,196 @@
|
||||
# Coze API Java 集成产品需求文档 (PRD)
|
||||
扣子团队版
|
||||
|
||||
## 1. 产品概述
|
||||
|
||||
### 1.1 产品背景
|
||||
Coze (扣子) 是一个强大的 AI Agent 开发平台，支持用户快速构建基于大语言模型的各类 Bot 和 Workflow。为了将 Coze 平台构建的智能体能力接入到我们的 Java 后端系统中，实现业务流程自动化和智能对话功能，本项目计划集成 Coze Open API。
|
||||
|
||||
### 1.2 产品定位
|
||||
为内部系统和第三方应用提供统一的 Coze 能力接入网关，屏蔽底层 API 细节，提供标准化的 Java 接口和 RESTful API，支持对话（Chat）、工作流（Workflow）和文件上传等核心功能。
|
||||
|
||||
### 1.3 目标用户
|
||||
- 内部业务系统开发团队
|
||||
- 需要接入 AI 客服/助手的前端应用
|
||||
- 自动化任务流程设计者
|
||||
|
||||
## 2. 核心功能需求
|
||||
|
||||
### 2.1 功能模块概览
|
||||
| 功能模块 | 描述 | 优先级 | 备注 |
|
||||
|---------|------|--------|------|
|
||||
| 鉴权管理 (Auth) | 支持 PAT (个人访问令牌) 和 OAuth JWT 两种模式 | P0 | 初期使用 PAT 快速接入 |
|
||||
| 智能对话 (Chat) | 与 Coze Bot 进行多轮对话，支持流式 (SSE) / 非流式响应 | P0 | 核心交互能力 |
|
||||
| 工作流执行 (Workflow) | 调用 Coze 定义的工作流，处理复杂业务逻辑 | P0 | 业务自动化 |
|
||||
| 文件上传 (File) | 上传图片或文档，用于多模态对话或工作流输入 | P1 | 支持多模态 |
|
||||
| 语音交互 (Voice) | 文本转语音 (TTS) / 语音转文本 (ASR) | P2 | 依赖 SDK WebSocket 能力 |
|
||||
|
||||
### 2.2 API 接口设计
|
||||
|
||||
#### 2.2.1 鉴权管理
|
||||
支持两种鉴权方式，通过配置文件切换：
|
||||
1. **PAT (Personal Access Token)**: 适用于内部系统后台调用，长期有效。
|
||||
2. **OAuth JWT**: 适用于需要代表不同用户身份调用的场景（高阶需求）。
|
||||
|
||||
*参考文档*: [OAuth JWT 授权](https://www.coze.cn/open/docs/developer_guides/oauth_jwt)
|
||||
|
||||
#### 2.2.2 智能对话 (Chat)
|
||||
支持与指定 Bot 进行交互。
|
||||
- **非流式**: 等待完整回复后返回。
|
||||
- **流式 (Streaming)**: 使用 Server-Sent Events (SSE) 实时推送 Token，提升用户体验。
|
||||
|
||||
**接口地址**: `POST /chat`
|
||||
|
||||
**请求参数**:
|
||||
```json
|
||||
{
|
||||
"bot_id": "730454116184516****", // Coze Bot ID
|
||||
"user_id": "user_123", // 业务系统用户ID
|
||||
"query": "帮我写一个 Java 冒泡排序", // 用户输入
|
||||
"stream": true, // true: 返回 SSE 流; false: 返回 JSON
|
||||
"chat_history": [ // (可选) 历史上下文
|
||||
{"role": "user", "content": "你好", "content_type": "text"},
|
||||
{"role": "assistant", "content": "你好！", "content_type": "text"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**响应示例 (非流式)**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"data": {
|
||||
"conversation_id": "737999610479815****",
|
||||
"messages": [
|
||||
{
|
||||
"role": "assistant",
|
||||
"type": "answer",
|
||||
"content": "当然，这是 Java 冒泡排序的代码...",
|
||||
"content_type": "text"
|
||||
}
|
||||
],
|
||||
"usage": {
|
||||
"token_count": 150
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**响应示例 (流式)**:
|
||||
Content-Type: `text/event-stream`
|
||||
```
|
||||
data: {"event":"message", "content":"当然", "is_finish":false}
|
||||
data: {"event":"message", "content":"，", "is_finish":false}
|
||||
...
|
||||
data: {"event":"done", "usage":{...}}
|
||||
```
|
||||
|
||||
#### 2.2.3 工作流执行 (Workflow)
|
||||
触发 Coze 预定义的工作流。
|
||||
|
||||
**接口地址**: `POST /workflow/run`
|
||||
|
||||
**请求参数**:
|
||||
```json
|
||||
{
|
||||
"workflow_id": "73505836754923****",
|
||||
"parameters": {
|
||||
"input_text": "分析文本",
|
||||
"input_image": "https://example.com/img.jpg"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 2.2.4 文件上传
|
||||
上传文件到 Coze 平台，获取 file_id。
|
||||
|
||||
**接口地址**: `POST /file/upload`
|
||||
**Content-Type**: `multipart/form-data`
|
||||
|
||||
**请求参数**:
|
||||
- `file`: (Binary) 文件内容
|
||||
|
||||
## 3. 技术实现规范
|
||||
|
||||
### 3.1 项目结构
|
||||
在 `com.integration.api` 包下扩展 Coze 相关模块：
|
||||
|
||||
```
|
||||
models-integration/
|
||||
├── src/main/java/com/integration/api/
|
||||
│ ├── config/
|
||||
│ │ └── CozeConfig.java # Coze Client Bean 配置
|
||||
│ ├── controller/
|
||||
│ │ └── CozeController.java # 对外 API 接口 (REST)
|
||||
│ ├── service/
|
||||
│ │ ├── CozeService.java # 业务逻辑接口
|
||||
│ │ └── impl/
|
||||
│ │ └── CozeServiceImpl.java # 调用 Coze SDK 实现
|
||||
│ ├── dto/
|
||||
│ │ ├── coze/
|
||||
│ │ ├── CozeChatRequest.java # 请求 DTO
|
||||
│ │ └── CozeBaseResponse.java # 统一响应 DTO
|
||||
│ └── utils/
|
||||
│ └── SseEmitterUtil.java # SSE 推送工具类
|
||||
```
|
||||
|
||||
### 3.2 依赖管理
|
||||
使用 Coze 官方 Java SDK。
|
||||
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>com.coze</groupId>
|
||||
<artifactId>coze-api</artifactId>
|
||||
<version>0.4.2</version> <!-- 请检查 Maven Central 获取最新版本 -->
|
||||
</dependency>
|
||||
```
|
||||
|
||||
### 3.3 配置文件
|
||||
在 `application.yml` 中配置：
|
||||
|
||||
```yaml
|
||||
coze:
|
||||
api:
|
||||
base-url: https://api.coze.cn
|
||||
token: ${COZE_API_TOKEN} # 优先使用环境变量
|
||||
connect-timeout: 30000
|
||||
read-timeout: 60000
|
||||
```
|
||||
|
||||
### 3.4 异常处理
|
||||
需捕获 SDK 抛出的异常并转换为标准 HTTP 响应：
|
||||
- `CozeClientException`: 客户端错误 (配置、网络) -> 500
|
||||
- `CozeServiceException`: 服务端错误 (参数、权限) -> 400/401/429
|
||||
- **401**: Token 无效
|
||||
- **429**: Rate Limit Exceeded (需实现重试机制)
|
||||
|
||||
## 4. 非功能需求
|
||||
|
||||
### 4.1 安全性
|
||||
- Token 不得提交到代码仓库。
|
||||
- 生产环境建议使用 OAuth JWT 模式以获得更细粒度的权限控制。
|
||||
|
||||
### 4.2 性能与稳定性
|
||||
- **连接池**: 使用 OkHttp 连接池复用连接。
|
||||
- **流式响应**: Chat 接口必须支持 SSE，避免长轮询等待。
|
||||
- **超时控制**: 明确设置 ReadTimeout，防止请求挂起。
|
||||
|
||||
### 4.3 可观测性
|
||||
- 记录每次调用的 `conversation_id` 和 `log_id` (SDK 返回)，便于排查问题。
|
||||
- 监控 Token 消耗量 (Usage)。
|
||||
|
||||
## 5. 项目里程碑
|
||||
|
||||
### 5.1 第一阶段 (MVP)
|
||||
- [ ] 引入 Coze SDK (v0.4.2+)。
|
||||
- [ ] 接入 OAuth JWT 授权流程
|
||||
- [ ] 实现文件上传接口。
|
||||
- [ ] 实现 Workflow 接口。
|
||||
- [ ] 实现基础 Chat 接口 (非流式)。
|
||||
- [ ] 实现 SSE 流式 Chat 接口。
|
||||
|
||||
## 6. 验收标准
|
||||
1. Chat 接口能正确响应 Bot 回复。
|
||||
2. Workflow 能执行并返回 JSON 结果。
|
||||
3. 流式请求能通过 SSE 逐步输出内容。
|
||||
4. 异常情况下能返回友好的错误信息，不暴露堆栈。
|
||||
1250
models-integration/docs/kieai-dev.md
Normal file
1250
models-integration/docs/kieai-dev.md
Normal file
File diff suppressed because it is too large
Load Diff
909
models-integration/docs/nano-banana-prd.md
Normal file
909
models-integration/docs/nano-banana-prd.md
Normal file
@@ -0,0 +1,909 @@
|
||||
# Kie AI Nano Banana API Java集成产品需求文档 (PRD)
|
||||
|
||||
## 1. 产品概述
|
||||
|
||||
### 1.1 产品背景
|
||||
Nano Banana API是Google Gemini 2.5 Flash Image Preview模型的别名，是一个先进的AI图像生成和编辑平台。通过Kie AI平台提供的API接口，开发者可以以更低的成本（约0.02美元/图片）访问这一强大的AI图像处理能力，相比Google官方API（0.039美元/图片）节省近50%的成本。
|
||||
|
||||
### 1.2 产品定位
|
||||
为Java开发者提供便捷、经济的AI图像生成和编辑解决方案，支持文本生成图像、图像编辑、背景替换、角色一致性保持等核心功能。
|
||||
|
||||
### 1.3 目标用户
|
||||
- Java后端开发者
|
||||
- 内容创作平台开发团队
|
||||
- 电商图像处理系统
|
||||
- 社交媒体应用开发者
|
||||
- AI图像处理服务提供商
|
||||
|
||||
## 2. 核心功能需求
|
||||
|
||||
### 2.1 功能模块概览
|
||||
基于Nano Banana API的核心能力，本次集成将实现以下功能模块：
|
||||
|
||||
| 功能模块 | 描述 | 优先级 |
|
||||
|---------|------|--------|
|
||||
| 文本生成图像 | 根据自然语言描述生成高质量图像 | P0 |
|
||||
| 图像编辑 | 基于指令对现有图像进行精确编辑 | P0 |
|
||||
| 背景替换 | 智能替换或增强图像背景 | P1 |
|
||||
| 角色一致性 | 在不同场景中保持角色外观一致 | P1 |
|
||||
| 任务状态查询 | 查询异步任务的处理状态和结果 | P0 |
|
||||
|
||||
### 2.2 API接口设计
|
||||
|
||||
#### 2.2.1 接口基础信息
|
||||
- **统一接口地址**: `https://api.kie.ai/api/v1/jobs/createTask`
|
||||
- **请求方法**: POST
|
||||
- **认证方式**: Bearer Token
|
||||
- **请求格式**: JSON (UTF-8)
|
||||
- **响应格式**: JSON
|
||||
|
||||
#### 2.2.2 认证配置
|
||||
```
|
||||
Authorization: Bearer {API_KEY}
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
#### 2.2.3 通用请求结构
|
||||
所有功能都使用统一的接口地址，通过 `model` 参数区分不同的功能模块：
|
||||
|
||||
```json
|
||||
{
|
||||
"model": "模型名称",
|
||||
"callBackUrl": "回调地址（可选）",
|
||||
"input": {
|
||||
// 具体功能参数
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 2.2.4 支持的模型类型
|
||||
| 模型名称 | 功能描述 | 对应功能模块 |
|
||||
|---------|---------|-------------|
|
||||
| google/nano-banana | 文本生成图像 | 文本生成图像 |
|
||||
| google/nano-banana-edit | 图像编辑 | 图像编辑/背景替换/角色一致性 |
|
||||
|
||||
## 3. 详细功能规格
|
||||
|
||||
### 3.1 文本生成图像 (google/nano-banana)
|
||||
|
||||
#### 3.1.1 业务场景
|
||||
- 内容创作：根据文章内容自动生成配图
|
||||
- 电商营销：根据产品描述生成宣传图片
|
||||
- 社交媒体：为用户文本内容生成视觉化表达
|
||||
|
||||
#### 3.1.2 接口规格
|
||||
**请求路径**: `POST https://api.kie.ai/api/v1/jobs/createTask`
|
||||
|
||||
**请求参数**:
|
||||
```json
|
||||
{
|
||||
"model": "google/nano-banana",
|
||||
"callBackUrl": "https://your-domain.com/api/callback",
|
||||
"input": {
|
||||
"prompt": "图像生成的文本描述",
|
||||
"output_format": "输出格式",
|
||||
"image_size": "图像尺寸比例"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**参数说明**:
|
||||
| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|
||||
|--------|------|------|------|--------|
|
||||
| model | String | 是 | 模型名称，固定值 | "google/nano-banana" |
|
||||
| callBackUrl | String | 否 | 异步回调地址 | "https://your-domain.com/api/callback" |
|
||||
| input.prompt | String | 是 | 图像生成的文本描述 | "A surreal painting of a giant banana floating in space, stars and galaxies in the background, vibrant colors, digital art" |
|
||||
| input.output_format | String | 否 | 输出格式 | "png", "jpg", "webp" |
|
||||
| input.image_size | String | 否 | 图像尺寸比例 | "1:1", "16:9", "9:16", "4:3" |
|
||||
|
||||
**请求示例**:
|
||||
```bash
|
||||
curl -X POST "https://api.kie.ai/api/v1/jobs/createTask" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer YOUR_API_KEY" \
|
||||
-d '{
|
||||
"model": "google/nano-banana",
|
||||
"callBackUrl": "https://your-domain.com/api/callback",
|
||||
"input": {
|
||||
"prompt": "A surreal painting of a giant banana floating in space, stars and galaxies in the background, vibrant colors, digital art",
|
||||
"output_format": "png",
|
||||
"image_size": "1:1"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
**响应格式**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"taskId": "nano_text_12345678",
|
||||
"model": "google/nano-banana",
|
||||
"state": "processing",
|
||||
"createTime": 1698765400000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 图像编辑 (google/nano-banana-edit)
|
||||
|
||||
#### 3.2.1 业务场景
|
||||
- 产品图片优化：调整商品图片的细节
|
||||
- 人像美化：对人物照片进行精细调整
|
||||
- 场景修改：修改图片中的特定元素
|
||||
- 创意设计：将照片转换为角色模型等创意内容
|
||||
|
||||
#### 3.2.2 接口规格
|
||||
**请求路径**: `POST https://api.kie.ai/api/v1/jobs/createTask`
|
||||
|
||||
**请求参数**:
|
||||
```json
|
||||
{
|
||||
"model": "google/nano-banana-edit",
|
||||
"callBackUrl": "https://your-domain.com/api/callback",
|
||||
"input": {
|
||||
"prompt": "编辑指令描述",
|
||||
"image_urls": ["图像URL数组"],
|
||||
"output_format": "输出格式",
|
||||
"image_size": "图像尺寸比例"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**参数说明**:
|
||||
| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|
||||
|--------|------|------|------|--------|
|
||||
| model | String | 是 | 模型名称，固定值 | "google/nano-banana-edit" |
|
||||
| callBackUrl | String | 否 | 异步回调地址 | "https://your-domain.com/api/callback" |
|
||||
| input.prompt | String | 是 | 编辑指令描述 | "turn this photo into a character figure. Behind it, place a box with the character's image printed on it" |
|
||||
| input.image_urls | Array | 是 | 原始图像URL数组 | ["https://example.com/image.png"] |
|
||||
| input.output_format | String | 否 | 输出格式 | "png", "jpg", "webp" |
|
||||
| input.image_size | String | 否 | 图像尺寸比例 | "1:1", "16:9", "9:16", "4:3" |
|
||||
|
||||
**请求示例**:
|
||||
```bash
|
||||
curl -X POST "https://api.kie.ai/api/v1/jobs/createTask" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer YOUR_API_KEY" \
|
||||
-d '{
|
||||
"model": "google/nano-banana-edit",
|
||||
"callBackUrl": "https://your-domain.com/api/callback",
|
||||
"input": {
|
||||
"prompt": "turn this photo into a character figure. Behind it, place a box with the character'\''s image printed on it, and a computer showing the Blender modeling process on its screen. In front of the box, add a round plastic base with the character figure standing on it. set the scene indoors if possible",
|
||||
"image_urls": [
|
||||
"https://file.aiquickdraw.com/custom-page/akr/section-images/1756223420389w8xa2jfe.png"
|
||||
],
|
||||
"output_format": "png",
|
||||
"image_size": "1:1"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
**响应格式**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"taskId": "nano_edit_12345678",
|
||||
"model": "google/nano-banana-edit",
|
||||
"state": "processing",
|
||||
"createTime": 1698765400000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3.3 背景替换 (google/nano-banana-edit)
|
||||
|
||||
#### 3.3.1 业务场景
|
||||
- 电商产品图：统一产品背景风格
|
||||
- 证件照处理：更换证件照背景
|
||||
- 营销素材：为产品图片添加品牌背景
|
||||
|
||||
#### 3.3.2 接口规格
|
||||
**请求路径**: `POST https://api.kie.ai/api/v1/jobs/createTask`
|
||||
|
||||
**请求参数**:
|
||||
```json
|
||||
{
|
||||
"model": "google/nano-banana-edit",
|
||||
"callBackUrl": "https://your-domain.com/api/callback",
|
||||
"input": {
|
||||
"prompt": "背景替换描述",
|
||||
"image_urls": ["原始图像URL"],
|
||||
"output_format": "输出格式",
|
||||
"image_size": "图像尺寸比例"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**参数说明**:
|
||||
| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|
||||
|--------|------|------|------|--------|
|
||||
| model | String | 是 | 模型名称，固定值 | "google/nano-banana-edit" |
|
||||
| callBackUrl | String | 否 | 异步回调地址 | "https://your-domain.com/api/callback" |
|
||||
| input.prompt | String | 是 | 背景替换描述 | "replace background with white studio background" |
|
||||
| input.image_urls | Array | 是 | 原始图像URL数组 | ["https://example.com/image.png"] |
|
||||
| input.output_format | String | 否 | 输出格式 | "png", "jpg", "webp" |
|
||||
| input.image_size | String | 否 | 图像尺寸比例 | "1:1", "16:9", "9:16", "4:3" |
|
||||
|
||||
**响应格式**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"taskId": "nano_bg_12345678",
|
||||
"model": "google/nano-banana-edit",
|
||||
"state": "processing",
|
||||
"createTime": 1698765400000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3.4 角色一致性 (google/nano-banana-edit)
|
||||
|
||||
#### 3.4.1 业务场景
|
||||
- 动画制作：保持角色在不同场景的一致性
|
||||
- 品牌营销：维持品牌吉祥物形象统一
|
||||
- 故事创作：确保故事角色外观连贯
|
||||
|
||||
#### 3.4.2 接口规格
|
||||
**请求路径**: `POST https://api.kie.ai/api/v1/jobs/createTask`
|
||||
|
||||
**请求参数**:
|
||||
```json
|
||||
{
|
||||
"model": "google/nano-banana-edit",
|
||||
"callBackUrl": "https://your-domain.com/api/callback",
|
||||
"input": {
|
||||
"prompt": "角色场景描述",
|
||||
"image_urls": ["参考角色图像URL"],
|
||||
"output_format": "输出格式",
|
||||
"image_size": "图像尺寸比例"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**参数说明**:
|
||||
| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|
||||
|--------|------|------|------|--------|
|
||||
| model | String | 是 | 模型名称，固定值 | "google/nano-banana-edit" |
|
||||
| callBackUrl | String | 否 | 异步回调地址 | "https://your-domain.com/api/callback" |
|
||||
| input.prompt | String | 是 | 角色场景描述 | "keep the character consistent, place in a forest scene" |
|
||||
| input.image_urls | Array | 是 | 参考角色图像URL数组 | ["https://example.com/character.png"] |
|
||||
| input.output_format | String | 否 | 输出格式 | "png", "jpg", "webp" |
|
||||
| input.image_size | String | 否 | 图像尺寸比例 | "1:1", "16:9", "9:16", "4:3" |
|
||||
|
||||
**响应格式**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"taskId": "nano_char_12345678",
|
||||
"model": "google/nano-banana-edit",
|
||||
"state": "processing",
|
||||
"createTime": 1698765400000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3.5 任务状态查询
|
||||
|
||||
#### 3.5.1 业务场景
|
||||
- 异步任务监控：实时跟踪图像生成进度
|
||||
- 结果获取：获取完成任务的结果图像
|
||||
- 错误处理：处理任务失败情况
|
||||
|
||||
#### 3.5.2 接口规格
|
||||
**请求路径**: `GET https://api.kie.ai/api/v1/jobs/{taskId}`
|
||||
|
||||
**请求参数**:
|
||||
| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|
||||
|--------|------|------|------|--------|
|
||||
| taskId | String | 是 | 任务ID | "nano_12345678" |
|
||||
|
||||
**响应格式**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"taskId": "nano_12345678",
|
||||
"model": "google/nano-banana",
|
||||
"state": "success",
|
||||
"progress": 100,
|
||||
"resultUrls": [
|
||||
"https://cdn.kie.ai/results/nano_12345678_1.png"
|
||||
],
|
||||
"createTime": 1698765400000,
|
||||
"completeTime": 1698765432000,
|
||||
"errorMessage": null
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**状态说明**:
|
||||
| 状态值 | 说明 | 处理建议 |
|
||||
|--------|------|----------|
|
||||
| queuing | 任务排队中 | 继续轮询 |
|
||||
| generating | 任务处理中 | 继续轮询 |
|
||||
| success | 任务完成 | 获取结果 |
|
||||
| fail | 任务失败 | 查看错误信息 |
|
||||
|
||||
## 4. 技术实现规范
|
||||
|
||||
### 4.1 项目结构
|
||||
基于现有项目结构，在 `com.integration.api` 包下新增 nano-banana 相关功能模块：
|
||||
|
||||
```
|
||||
models-integration/
|
||||
├── src/main/java/com/integration/api/
|
||||
│ ├── Application.java # 主启动类
|
||||
│ ├── config/
|
||||
│ │ ├── SwaggerConfig.java # 现有Swagger配置
|
||||
│ │ └── NanoBananaConfig.java # 新增：Nano Banana API配置
|
||||
│ ├── controller/
|
||||
│ │ ├── ArticleController.java # 现有文章控制器
|
||||
│ │ ├── KieAI2VideoController.java # 现有KieAI视频生成控制器
|
||||
│ │ ├── KieAICallbackController.java # 现有回调控制器
|
||||
│ │ └── KieAI2ImageController.java # 新增：Kie AI图像生成控制器
|
||||
│ ├── dto/
|
||||
│ │ ├── CreateTaskRequest.java # 新增：统一任务创建请求
|
||||
│ │ ├── TextToImageInput.java # 新增：文本生图输入参数
|
||||
│ │ ├── ImageEditInput.java # 新增：图像编辑输入参数
|
||||
│ │ ├── NanoBananaResponse.java # 新增：响应基类
|
||||
│ │ ├── CreateTaskResponse.java # 新增：创建任务响应
|
||||
│ │ └── QueryTaskResponse.java # 新增：查询任务响应
|
||||
│ ├── helper/
|
||||
│ │ ├── ConfigConstant.java # 现有配置常量
|
||||
│ │ ├── DigestUtil.java # 现有摘要工具
|
||||
│ │ ├── HttpRequestUtils.java # 现有HTTP工具
|
||||
│ │ ├── XbbException.java # 现有异常类
|
||||
│ │ └── NanoBananaHelper.java # 新增：Nano Banana工具类
|
||||
│ ├── mapper/
|
||||
│ │ ├── ArticleMapper.java # 现有文章映射器
|
||||
│ │ └── NanoBananaTaskMapper.java # 新增：任务映射器
|
||||
│ ├── model/
|
||||
│ │ ├── Article.java # 现有文章实体
|
||||
│ │ ├── NanoBananaTask.java # 新增：任务实体
|
||||
│ │ ├── ResponseResult.java # 现有响应结果
|
||||
│ │ ├── Sora2Request.java # 现有Sora2请求
|
||||
│ │ ├── TaskStatus.java # 现有任务状态
|
||||
│ │ └── request/ # 现有请求模型目录
|
||||
│ ├── enums/
|
||||
│ │ ├── ModelType.java # 新增：模型类型枚举
|
||||
│ │ ├── NanoBananaTaskState.java # 新增：任务状态枚举
|
||||
│ │ ├── OutputFormat.java # 新增：输出格式枚举
|
||||
│ │ └── ImageSize.java # 新增：图像尺寸枚举
|
||||
│ └── service/
|
||||
│ ├── ArticleService.java # 现有文章服务接口
|
||||
│ ├── KieAIService.java # 现有KieAI服务
|
||||
│ ├── NanoBananaService.java # 新增：Nano Banana服务接口
|
||||
│ └── impl/
|
||||
│ ├── ArticleServiceImpl.java # 现有文章服务实现
|
||||
│ └── NanoBananaServiceImpl.java # 新增：Nano Banana服务实现
|
||||
├── src/main/resources/
|
||||
│ ├── application.yml # 应用配置（需更新）
|
||||
│ └── logback.xml # 日志配置
|
||||
├── pom.xml # Maven依赖配置（需更新）
|
||||
└── logs/ # 日志文件目录
|
||||
```
|
||||
|
||||
### 4.2 核心依赖
|
||||
基于现有项目依赖，无需新增额外依赖，现有依赖已满足 Nano Banana API 集成需求：
|
||||
|
||||
```xml
|
||||
<!-- 现有依赖已包含以下核心组件 -->
|
||||
<dependencies>
|
||||
<!-- Spring Boot Web Starter -->
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-starter-web</artifactId>
|
||||
<version>2.7.5</version>
|
||||
</dependency>
|
||||
|
||||
<!-- Spring Boot Validation -->
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-starter-validation</artifactId>
|
||||
<version>2.7.5</version>
|
||||
</dependency>
|
||||
|
||||
<!-- HTTP Client (现有OkHttp和HttpAsyncClient) -->
|
||||
<dependency>
|
||||
<groupId>com.squareup.okhttp3</groupId>
|
||||
<artifactId>okhttp</artifactId>
|
||||
<version>3.14.9</version>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>org.apache.httpcomponents</groupId>
|
||||
<artifactId>httpasyncclient</artifactId>
|
||||
<version>4.1</version>
|
||||
</dependency>
|
||||
|
||||
<!-- JSON处理 (现有FastJSON) -->
|
||||
<dependency>
|
||||
<groupId>com.alibaba</groupId>
|
||||
<artifactId>fastjson</artifactId>
|
||||
<version>1.2.48.sec06</version>
|
||||
</dependency>
|
||||
|
||||
<!-- Lombok -->
|
||||
<dependency>
|
||||
<groupId>org.projectlombok</groupId>
|
||||
<artifactId>lombok</artifactId>
|
||||
<version>1.18.24</version>
|
||||
<optional>true</optional>
|
||||
</dependency>
|
||||
|
||||
<!-- 日志 -->
|
||||
<dependency>
|
||||
<groupId>ch.qos.logback</groupId>
|
||||
<artifactId>logback-classic</artifactId>
|
||||
<version>1.2.11</version>
|
||||
</dependency>
|
||||
|
||||
<!-- Swagger3文档 -->
|
||||
<dependency>
|
||||
<groupId>org.springdoc</groupId>
|
||||
<artifactId>springdoc-openapi-ui</artifactId>
|
||||
<version>1.7.0</version>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
```
|
||||
|
||||
### 4.3 配置文件
|
||||
在现有 `application.yml` 基础上新增 Nano Banana API 相关配置：
|
||||
|
||||
```yaml
|
||||
# 现有配置保持不变，新增以下配置
|
||||
nano-banana:
|
||||
api:
|
||||
base-url: https://api.kie.ai/api/v1
|
||||
api-key: ${NANO_BANANA_API_KEY:your-api-key}
|
||||
timeout: 30000
|
||||
retry-count: 3
|
||||
retry-delay: 1000
|
||||
callback:
|
||||
base-url: ${server.domain:http://localhost:8080}
|
||||
path: /api/nano-banana/callback
|
||||
task:
|
||||
max-concurrent: 10
|
||||
cleanup-interval: 3600000 # 1小时清理一次过期任务
|
||||
expire-time: 86400000 # 24小时任务过期时间
|
||||
|
||||
# 现有配置示例（保持不变）
|
||||
server:
|
||||
port: 8080
|
||||
servlet:
|
||||
context-path: /
|
||||
|
||||
spring:
|
||||
application:
|
||||
name: models-integration
|
||||
datasource:
|
||||
type: com.alibaba.druid.pool.DruidDataSource
|
||||
driver-class-name: com.mysql.cj.jdbc.Driver
|
||||
url: jdbc:mysql://localhost:3306/models_integration?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai
|
||||
username: ${DB_USERNAME:root}
|
||||
password: ${DB_PASSWORD:123456}
|
||||
|
||||
# 日志配置（现有基础上新增）
|
||||
logging:
|
||||
level:
|
||||
com.integration.api: DEBUG
|
||||
org.springframework.web: INFO
|
||||
pattern:
|
||||
console: "%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n"
|
||||
```
|
||||
|
||||
### 4.4 核心模型类
|
||||
基于现有项目实体设计模式，新增 Nano Banana 任务模型类：
|
||||
|
||||
#### 4.4.1 NanoBananaTask 模型类
|
||||
```java
|
||||
package com.integration.api.model;
|
||||
|
||||
import com.baomidou.mybatisplus.annotation.IdType;
|
||||
import com.baomidou.mybatisplus.annotation.TableId;
|
||||
import com.baomidou.mybatisplus.annotation.TableName;
|
||||
import io.swagger.annotations.ApiModel;
|
||||
import io.swagger.annotations.ApiModelProperty;
|
||||
import lombok.Data;
|
||||
import lombok.EqualsAndHashCode;
|
||||
import lombok.experimental.Accessors;
|
||||
|
||||
import java.io.Serializable;
|
||||
import java.util.Date;
|
||||
|
||||
/**
|
||||
* Nano Banana任务管理表
|
||||
*/
|
||||
@Data
|
||||
@EqualsAndHashCode(callSuper = false)
|
||||
@Accessors(chain = true)
|
||||
@TableName("nano_banana_task")
|
||||
@ApiModel(value="NanoBananaTask对象", description="Nano Banana任务管理表")
|
||||
public class NanoBananaTask implements Serializable {
|
||||
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
@ApiModelProperty(value = "任务ID")
|
||||
@TableId(value = "id", type = IdType.AUTO)
|
||||
private Long id;
|
||||
|
||||
@ApiModelProperty(value = "外部任务ID")
|
||||
private String taskId;
|
||||
|
||||
@ApiModelProperty(value = "模型类型")
|
||||
private String modelType;
|
||||
|
||||
@ApiModelProperty(value = "任务状态")
|
||||
private String status;
|
||||
|
||||
@ApiModelProperty(value = "提示词")
|
||||
private String prompt;
|
||||
|
||||
@ApiModelProperty(value = "输入图片URLs")
|
||||
private String imageUrls;
|
||||
|
||||
@ApiModelProperty(value = "输出格式")
|
||||
private String outputFormat;
|
||||
|
||||
@ApiModelProperty(value = "图片尺寸")
|
||||
private String imageSize;
|
||||
|
||||
@ApiModelProperty(value = "回调URL")
|
||||
private String callbackUrl;
|
||||
|
||||
@ApiModelProperty(value = "结果图片URLs")
|
||||
private String resultUrls;
|
||||
|
||||
@ApiModelProperty(value = "错误信息")
|
||||
private String errorMessage;
|
||||
|
||||
@ApiModelProperty(value = "创建时间")
|
||||
private Date createTime;
|
||||
|
||||
@ApiModelProperty(value = "更新时间")
|
||||
private Date updateTime;
|
||||
|
||||
@ApiModelProperty(value = "完成时间")
|
||||
private Date completeTime;
|
||||
|
||||
@ApiModelProperty(value = "用户ID")
|
||||
private String userId;
|
||||
|
||||
@ApiModelProperty(value = "备注")
|
||||
private String remark;
|
||||
}
|
||||
```
|
||||
|
||||
#### 4.4.2 数据传输对象类
|
||||
基于现有项目的包结构，在 `dto` 包下创建请求响应传参对象：
|
||||
|
||||
**CreateTaskRequest.java**
|
||||
```java
|
||||
package com.integration.api.dto;
|
||||
|
||||
import io.swagger.annotations.ApiModel;
|
||||
import io.swagger.annotations.ApiModelProperty;
|
||||
import lombok.Data;
|
||||
import javax.validation.constraints.NotBlank;
|
||||
import javax.validation.constraints.NotNull;
|
||||
|
||||
@Data
|
||||
@ApiModel(description = "创建任务请求")
|
||||
public class CreateTaskRequest {
|
||||
|
||||
@ApiModelProperty(value = "模型类型", required = true)
|
||||
@NotBlank(message = "模型类型不能为空")
|
||||
private String model;
|
||||
|
||||
@ApiModelProperty(value = "回调URL")
|
||||
private String callBackUrl;
|
||||
|
||||
@ApiModelProperty(value = "输入参数", required = true)
|
||||
@NotNull(message = "输入参数不能为空")
|
||||
private Object input;
|
||||
}
|
||||
```
|
||||
|
||||
**TextToImageInput.java**
|
||||
```java
|
||||
package com.integration.api.dto;
|
||||
|
||||
import io.swagger.annotations.ApiModel;
|
||||
import io.swagger.annotations.ApiModelProperty;
|
||||
import lombok.Data;
|
||||
import javax.validation.constraints.NotBlank;
|
||||
|
||||
@Data
|
||||
@ApiModel(description = "文本生图输入参数")
|
||||
public class TextToImageInput {
|
||||
|
||||
@ApiModelProperty(value = "提示词", required = true)
|
||||
@NotBlank(message = "提示词不能为空")
|
||||
private String prompt;
|
||||
|
||||
@ApiModelProperty(value = "输出格式", example = "png")
|
||||
private String output_format = "png";
|
||||
|
||||
@ApiModelProperty(value = "图片尺寸", example = "1:1")
|
||||
private String image_size = "1:1";
|
||||
}
|
||||
```
|
||||
|
||||
**ImageEditInput.java**
|
||||
```java
|
||||
package com.integration.api.dto;
|
||||
|
||||
import io.swagger.annotations.ApiModel;
|
||||
import io.swagger.annotations.ApiModelProperty;
|
||||
import lombok.Data;
|
||||
import javax.validation.constraints.NotBlank;
|
||||
import javax.validation.constraints.NotEmpty;
|
||||
import java.util.List;
|
||||
|
||||
@Data
|
||||
@ApiModel(description = "图像编辑输入参数")
|
||||
public class ImageEditInput {
|
||||
|
||||
@ApiModelProperty(value = "提示词", required = true)
|
||||
@NotBlank(message = "提示词不能为空")
|
||||
private String prompt;
|
||||
|
||||
@ApiModelProperty(value = "图片URLs", required = true)
|
||||
@NotEmpty(message = "图片URLs不能为空")
|
||||
private List<String> image_urls;
|
||||
|
||||
@ApiModelProperty(value = "输出格式", example = "png")
|
||||
private String output_format = "png";
|
||||
|
||||
@ApiModelProperty(value = "图片尺寸", example = "1:1")
|
||||
private String image_size = "1:1";
|
||||
}
|
||||
```
|
||||
|
||||
#### 4.4.3 枚举类
|
||||
**ModelType.java**
|
||||
```java
|
||||
package com.integration.api.enums;
|
||||
|
||||
import lombok.AllArgsConstructor;
|
||||
import lombok.Getter;
|
||||
|
||||
@Getter
|
||||
@AllArgsConstructor
|
||||
public enum ModelType {
|
||||
TEXT_TO_IMAGE("google/nano-banana", "文本生成图像"),
|
||||
IMAGE_EDIT("google/nano-banana-edit", "图像编辑");
|
||||
|
||||
private final String code;
|
||||
private final String description;
|
||||
|
||||
public static ModelType fromCode(String code) {
|
||||
for (ModelType type : values()) {
|
||||
if (type.getCode().equals(code)) {
|
||||
return type;
|
||||
}
|
||||
}
|
||||
throw new IllegalArgumentException("不支持的模型类型: " + code);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**NanoBananaTaskState.java**
|
||||
```java
|
||||
package com.integration.api.enums;
|
||||
|
||||
import lombok.AllArgsConstructor;
|
||||
import lombok.Getter;
|
||||
|
||||
@Getter
|
||||
@AllArgsConstructor
|
||||
public enum NanoBananaTaskState {
|
||||
PENDING("pending", "等待中"),
|
||||
PROCESSING("processing", "处理中"),
|
||||
COMPLETED("completed", "已完成"),
|
||||
FAILED("failed", "失败");
|
||||
|
||||
private final String code;
|
||||
private final String description;
|
||||
|
||||
public static NanoBananaTaskState fromCode(String code) {
|
||||
for (NanoBananaTaskState state : values()) {
|
||||
if (state.getCode().equals(code)) {
|
||||
return state;
|
||||
}
|
||||
}
|
||||
throw new IllegalArgumentException("不支持的任务状态: " + code);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**OutputFormat.java**
|
||||
```java
|
||||
package com.integration.api.enums;
|
||||
|
||||
import lombok.AllArgsConstructor;
|
||||
import lombok.Getter;
|
||||
|
||||
@Getter
|
||||
@AllArgsConstructor
|
||||
public enum OutputFormat {
|
||||
PNG("png", "PNG格式"),
|
||||
JPG("jpg", "JPG格式"),
|
||||
JPEG("jpeg", "JPEG格式"),
|
||||
WEBP("webp", "WEBP格式");
|
||||
|
||||
private final String code;
|
||||
private final String description;
|
||||
}
|
||||
```
|
||||
|
||||
**ImageSize.java**
|
||||
```java
|
||||
package com.integration.api.enums;
|
||||
|
||||
import lombok.AllArgsConstructor;
|
||||
import lombok.Getter;
|
||||
|
||||
@Getter
|
||||
@AllArgsConstructor
|
||||
public enum ImageSize {
|
||||
SQUARE("1:1", "正方形"),
|
||||
PORTRAIT_9_16("9:16", "竖版9:16"),
|
||||
LANDSCAPE_16_9("16:9", "横版16:9"),
|
||||
LANDSCAPE_4_3("4:3", "横版4:3");
|
||||
|
||||
private final String code;
|
||||
private final String description;
|
||||
}
|
||||
```
|
||||
|
||||
## 5. 接口实现要点
|
||||
|
||||
### 5.1 异常处理策略
|
||||
- **网络异常**: 自动重试机制，最多重试3次
|
||||
- **API限流**: 实现请求队列和并发控制
|
||||
- **参数验证**: 统一参数校验和错误提示
|
||||
- **超时处理**: 设置合理的超时时间（30秒）
|
||||
|
||||
### 5.2 安全考虑
|
||||
- **API密钥管理**: 使用环境变量存储敏感信息
|
||||
- **请求签名**: 实现请求参数签名验证
|
||||
- **访问控制**: 添加IP白名单和访问频率限制
|
||||
- **数据加密**: 敏感数据传输加密
|
||||
|
||||
### 5.3 性能优化
|
||||
- **连接池**: 使用HTTP连接池提高性能
|
||||
- **异步处理**: 长时间任务采用异步处理模式
|
||||
- **缓存策略**: 对频繁查询的任务状态进行缓存
|
||||
- **监控告警**: 添加API调用监控和异常告警
|
||||
|
||||
## 6. 测试策略
|
||||
|
||||
### 6.1 单元测试
|
||||
- Controller层接口测试
|
||||
- Service层业务逻辑测试
|
||||
- 工具类方法测试
|
||||
- 异常处理测试
|
||||
|
||||
### 6.2 集成测试
|
||||
- API接口端到端测试
|
||||
- 异步任务处理测试
|
||||
- 错误场景测试
|
||||
- 性能压力测试
|
||||
|
||||
### 6.3 测试数据
|
||||
```java
|
||||
// 测试用例示例
|
||||
public class NanoBananaTestData {
|
||||
public static final String TEST_PROMPT = "一只可爱的橙色小猫坐在阳光明媚的窗台上";
|
||||
public static final String TEST_IMAGE_URL = "https://example.com/test-image.jpg";
|
||||
public static final String TEST_API_KEY = "test-api-key-12345";
|
||||
}
|
||||
```
|
||||
|
||||
## 7. 部署和运维
|
||||
|
||||
### 7.1 环境配置
|
||||
- **开发环境**: 使用测试API密钥，启用详细日志
|
||||
- **测试环境**: 模拟生产环境配置，进行性能测试
|
||||
- **生产环境**: 使用正式API密钥，启用监控告警
|
||||
|
||||
### 7.2 监控指标
|
||||
- API调用成功率
|
||||
- 平均响应时间
|
||||
- 任务处理时长
|
||||
- 错误率统计
|
||||
- 并发请求数
|
||||
|
||||
### 7.3 日志规范
|
||||
```java
|
||||
// 日志记录示例
|
||||
log.info("开始处理文本生成图像任务, taskId: {}, prompt: {}", taskId, prompt);
|
||||
log.warn("API调用超时, taskId: {}, 耗时: {}ms", taskId, duration);
|
||||
log.error("任务处理失败, taskId: {}, 错误信息: {}", taskId, errorMsg);
|
||||
```
|
||||
|
||||
## 8. 成本分析
|
||||
|
||||
### 8.1 API调用成本
|
||||
- **Kie AI平台**: 0.02美元/图片
|
||||
- **Google官方**: 0.039美元/图片
|
||||
- **成本节省**: 约48.7%
|
||||
|
||||
### 8.2 开发成本
|
||||
- **开发周期**: 预计2-3周
|
||||
- **人力投入**: 1名高级Java开发工程师
|
||||
- **测试周期**: 1周
|
||||
|
||||
### 8.3 运维成本
|
||||
- **服务器资源**: 中等配置云服务器
|
||||
- **监控工具**: 使用开源监控方案
|
||||
- **维护成本**: 每月约2-4小时
|
||||
|
||||
## 9. 风险评估
|
||||
|
||||
### 9.1 技术风险
|
||||
- **API稳定性**: Kie AI平台服务可用性依赖
|
||||
- **性能瓶颈**: 高并发场景下的处理能力
|
||||
- **兼容性**: 不同Java版本的兼容性问题
|
||||
|
||||
### 9.2 业务风险
|
||||
- **成本控制**: API调用量超预期导致成本上升
|
||||
- **质量保证**: 生成图像质量不符合业务要求
|
||||
- **合规风险**: 生成内容的版权和合规性问题
|
||||
|
||||
### 9.3 风险缓解措施
|
||||
- 实施API调用量监控和预警
|
||||
- 建立图像质量评估机制
|
||||
- 制定内容审核和过滤策略
|
||||
- 准备备用API服务商方案
|
||||
|
||||
## 10. 项目里程碑
|
||||
|
||||
### 10.1 第一阶段 (Week 1-2)
|
||||
- [ ] 完成基础架构搭建
|
||||
- [ ] 实现文本生成图像功能
|
||||
- [ ] 实现任务状态查询功能
|
||||
- [ ] 完成单元测试
|
||||
|
||||
### 10.2 第二阶段 (Week 3)
|
||||
- [ ] 实现图像编辑功能
|
||||
- [ ] 实现背景替换功能
|
||||
- [ ] 完成集成测试
|
||||
- [ ] 性能优化
|
||||
|
||||
### 10.3 第三阶段 (Week 4)
|
||||
- [ ] 实现角色一致性功能
|
||||
- [ ] 完善异常处理和监控
|
||||
- [ ] 部署测试环境
|
||||
- [ ] 文档完善
|
||||
|
||||
## 11. 验收标准
|
||||
|
||||
### 11.1 功能验收
|
||||
- [ ] 所有API接口正常调用
|
||||
- [ ] 异步任务处理机制完善
|
||||
- [ ] 错误处理和重试机制有效
|
||||
- [ ] 性能指标达到预期
|
||||
|
||||
### 11.2 质量验收
|
||||
- [ ] 单元测试覆盖率 > 80%
|
||||
- [ ] 集成测试通过率 100%
|
||||
- [ ] 代码质量检查通过
|
||||
- [ ] 安全扫描无高危漏洞
|
||||
|
||||
### 11.3 文档验收
|
||||
- [ ] API接口文档完整
|
||||
- [ ] 部署运维文档齐全
|
||||
- [ ] 用户使用指南清晰
|
||||
- [ ] 故障排除手册完备
|
||||
|
||||
---
|
||||
13
models-integration/docs/饮食打卡发布到社区功能需求.md
Normal file
13
models-integration/docs/饮食打卡发布到社区功能需求.md
Normal file
@@ -0,0 +1,13 @@
|
||||
|
||||
## 用户提交打卡记录（shop_msh)
|
||||
|
||||
### 根据最新的eb_user_sign.sql 和 v2_community_posts.sql 文件修改实体类，并添加相应的字段。
|
||||
|
||||
**情况一：当用户提交打卡记录时“启用AI视频生成”**
|
||||
1. 在ai图生视频接口的回调方法中根据taskid查询eb_user_sign表，获取打卡记录信息
|
||||
2. 将此信息和ai回调接口中返回的信息梳理后插入v2_community_posts表。
|
||||
|
||||
**情况二：当用户提交打卡记录时“启用AI分析”**
|
||||
1. 在ai图生图接口的回调方法中根据taskid查询eb_user_sign表，获取打卡记录信息，
|
||||
2. 根据此信息调用coze饮食打卡记录ai分析工作流，获取ai分析结果
|
||||
2. 将ai分析结果梳理后（含营养成分分析，推荐配餐方案）插入v2_community_posts表。
|
||||
Reference in New Issue
Block a user