392 lines
12 KiB
Markdown
392 lines
12 KiB
Markdown
# RunningHub集成完成报告
|
||
|
||
**完成时间：** 2025-10-20
|
||
**版本号：** v2.1.0
|
||
|
||
---
|
||
|
||
## ✅ 实现完成清单
|
||
|
||
### 1. 核心接口和DTO ✅
|
||
|
||
| 文件 | 说明 | 状态 |
|
||
|------|------|------|
|
||
| `AIProvider.java` | 统一服务商接口 | ✅ 完成 |
|
||
| `ProviderTaskRequest.java` | 统一请求DTO | ✅ 完成 |
|
||
| `ProviderTaskResponse.java` | 统一响应DTO | ✅ 完成 |
|
||
| `ProviderTaskStatus.java` | 任务状态DTO | ✅ 完成 |
|
||
| `ProviderTaskResult.java` | 任务结果DTO | ✅ 完成 |
|
||
|
||
### 2. RunningHub专用DTO ✅
|
||
|
||
| 文件 | 说明 | 状态 |
|
||
|------|------|------|
|
||
| `RunningHubSubmitRequest.java` | 提交请求 | ✅ 完成 |
|
||
| `RunningHubNodeInfo.java` | 节点信息 | ✅ 完成 |
|
||
| `RunningHubSubmitResponse.java` | 提交响应 | ✅ 完成 |
|
||
| `RunningHubStatusResponse.java` | 状态查询响应 | ✅ 完成 |
|
||
| `RunningHubOutputResponse.java` | 结果查询响应 | ✅ 完成 |
|
||
|
||
### 3. Provider实现 ✅
|
||
|
||
| 文件 | 说明 | 状态 |
|
||
|------|------|------|
|
||
| `OpenAIProviderImpl.java` | OpenAI适配器（同步） | ✅ 完成 |
|
||
| `RunningHubProviderImpl.java` | RunningHub适配器（异步） | ✅ 完成 |
|
||
|
||
### 4. 核心服务 ✅
|
||
|
||
| 文件 | 说明 | 状态 |
|
||
|------|------|------|
|
||
| `AIProviderService.java` | Provider路由服务 | ✅ 完成 |
|
||
| `RunningHubPollingScheduler.java` | 轮询调度器 | ✅ 完成 |
|
||
| `AiTaskServiceImpl.java` | 任务服务（已集成） | ✅ 完成 |
|
||
|
||
### 5. 数据库和配置 ✅
|
||
|
||
| 文件 | 说明 | 状态 |
|
||
|------|------|------|
|
||
| `V5__add_provider_support.sql` | 数据库迁移脚本 | ✅ 完成 |
|
||
| `application.yml` | 多厂商配置 | ✅ 完成 |
|
||
| `AiTask.java` | 实体类更新 | ✅ 完成 |
|
||
| `PointsConfig.java` | 实体类更新 | ✅ 完成 |
|
||
| `AiTaskMapper.xml` | SQL映射更新 | ✅ 完成 |
|
||
|
||
---
|
||
|
||
## 🎯 系统架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 用户提交任务 │
|
||
│ (JWT or API Key认证) │
|
||
└────────────────────────┬────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ AiTaskController │
|
||
└────────────────────────┬────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ AiTaskServiceImpl │
|
||
│ 1. 扣积分 │
|
||
│ 2. 创建任务 │
|
||
│ 3. 读取 points_config.provider_type │
|
||
│ 4. 路由到不同流程 │
|
||
└────────┬──────────────────────────────┬─────────────────────┘
|
||
│ │
|
||
▼ ▼
|
||
┌──────────────────┐ ┌──────────────────┐
|
||
│ OpenAI流程 │ │ RunningHub流程 │
|
||
│ (同步) │ │ (异步) │
|
||
└──────┬───────────┘ └─────────┬─────────┘
|
||
│ │
|
||
↓ ↓
|
||
┌──────────────────┐ ┌──────────────────┐
|
||
│1. 加入队列 │ │1. 直接提交 │
|
||
│2. TaskScheduler │ │2. 返回taskId │
|
||
│ 定时调度 │ │3. 更新DB │
|
||
│3. AsyncExecutor │ │ │
|
||
│ 同步执行 │ │ │
|
||
│4. 立即返回结果 │ │ │
|
||
└──────────────────┘ └─────────┬─────────┘
|
||
│
|
||
↓
|
||
┌──────────────────┐
|
||
│RunningHub │
|
||
│PollingScheduler │
|
||
│ │
|
||
│每5秒轮询: │
|
||
│1. 查询状态 │
|
||
│2. SUCCESS→获取 │
|
||
│3. FAILED→退款 │
|
||
│4. 更新DB+通知 │
|
||
└──────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 📋 工作流程对比
|
||
|
||
### OpenAI流程（同步）
|
||
|
||
1. 用户提交任务
|
||
2. 系统扣除积分，创建任务
|
||
3. 任务加入队列（status='queued'）
|
||
4. `TaskScheduler` 调度任务
|
||
5. `AsyncTaskExecutor` 调用OpenAI API
|
||
6. 立即返回结果URL
|
||
7. 更新status='completed'
|
||
8. 发送WebSocket通知
|
||
|
||
**耗时：** ~10-30秒
|
||
|
||
### RunningHub流程（异步）
|
||
|
||
1. 用户提交任务
|
||
2. 系统扣除积分，创建任务
|
||
3. 直接调用RunningHub API
|
||
4. 获得taskId，更新status='processing'
|
||
5. `RunningHubPollingScheduler` 每5秒轮询
|
||
6. 检测到SUCCESS状态
|
||
7. 调用outputs接口获取结果URL
|
||
8. 更新status='completed'
|
||
9. 发送WebSocket通知
|
||
|
||
**耗时：** ~2-5分钟
|
||
|
||
---
|
||
|
||
## 🔧 配置说明
|
||
|
||
### application.yml
|
||
|
||
```yaml
|
||
ai:
|
||
providers:
|
||
openai:
|
||
enabled: true
|
||
base-url: https://api.apiyi.com/v1/chat/completions
|
||
api-key: "sk-xxx"
|
||
runninghub:
|
||
enabled: true
|
||
base-url: https://www.runninghub.cn
|
||
submit-url: /task/openapi/ai-app/run
|
||
status-url: /task/openapi/status
|
||
output-url: /task/openapi/outputs
|
||
default-webapp-id: "1973555977595301890"
|
||
api-key: "your_runninghub_api_key"
|
||
polling-interval: 5000
|
||
max-polling-times: 120
|
||
```
|
||
|
||
### points_config表配置
|
||
|
||
```sql
|
||
-- RunningHub模型示例
|
||
INSERT INTO `points_config` VALUES
|
||
(8, 'rh_sora2_portrait', 160, 'RunningHub Sora2 竖屏视频（10秒）', 1, 'runninghub',
|
||
'{"webappId":"1973555977595301890","duration":10,"model":"portrait"}', NOW(), NOW());
|
||
```
|
||
|
||
**providerConfig字段说明：**
|
||
- `webappId`: RunningHub应用ID
|
||
- `duration`: 视频时长（秒）
|
||
- `model`: 模型类型（portrait/landscape/portrait-hd/landscape-hd）
|
||
|
||
---
|
||
|
||
## 🚀 部署步骤
|
||
|
||
### 1. 数据库迁移
|
||
|
||
```bash
|
||
mysql -u root -p 1818ai < V5__add_provider_support.sql
|
||
```
|
||
|
||
### 2. 更新配置
|
||
|
||
编辑 `application.yml`，填入RunningHub API Key：
|
||
|
||
```yaml
|
||
ai:
|
||
providers:
|
||
runninghub:
|
||
api-key: "YOUR_RUNNINGHUB_API_KEY"
|
||
```
|
||
|
||
### 3. 编译部署
|
||
|
||
```bash
|
||
# 编译
|
||
mvn clean package -DskipTests
|
||
|
||
# 停止服务
|
||
sudo systemctl stop spring_1818_user_server
|
||
|
||
# 备份旧版本
|
||
sudo cp /www/wwwroot/1818_user_server/1818_user_server-1.0-SNAPSHOT.jar \
|
||
/www/wwwroot/1818_user_server/1818_user_server-1.0-SNAPSHOT.jar.bak
|
||
|
||
# 部署新版本
|
||
sudo cp target/1818_user_server-1.0-SNAPSHOT.jar \
|
||
/www/wwwroot/1818_user_server/
|
||
|
||
# 启动服务
|
||
sudo systemctl start spring_1818_user_server
|
||
|
||
# 查看日志
|
||
sudo journalctl -u spring_1818_user_server -f
|
||
```
|
||
|
||
---
|
||
|
||
## 🧪 测试指南
|
||
|
||
### 1. 测试OpenAI模型（验证兼容性）
|
||
|
||
```bash
|
||
curl -X POST "http://localhost:8081/user/ai/tasks/submit" \
|
||
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"modelName": "sora_image",
|
||
"prompt": "一只可爱的猫咪"
|
||
}'
|
||
```
|
||
|
||
**预期结果：**
|
||
- 任务立即执行
|
||
- 30秒内返回completed状态
|
||
- resultUrl包含图片地址
|
||
|
||
### 2. 测试RunningHub模型
|
||
|
||
```bash
|
||
curl -X POST "http://localhost:8081/user/ai/tasks/submit" \
|
||
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"modelName": "rh_sora2_portrait",
|
||
"prompt": "一个人在海边奔跑，镜头从远到近"
|
||
}'
|
||
```
|
||
|
||
**预期结果：**
|
||
- 任务提交成功，status='processing'
|
||
- 返回taskNo和providerTaskId
|
||
- 2-5分钟后status变为'completed'
|
||
- resultUrl包含视频地址
|
||
|
||
### 3. 查看轮询日志
|
||
|
||
```bash
|
||
tail -f logs/application.log | grep "RunningHub"
|
||
```
|
||
|
||
**正常日志示例：**
|
||
```
|
||
2025-10-20 15:30:05 INFO - 提交任务到RunningHub: TASK20251020153005ABC
|
||
2025-10-20 15:30:06 INFO - RunningHub任务提交成功: TASK20251020153005ABC, providerTaskId: 1980149306768457730
|
||
2025-10-20 15:30:11 DEBUG - RunningHub轮询 - 发现1个待处理任务
|
||
2025-10-20 15:30:11 DEBUG - 轮询任务: TASK20251020153005ABC, providerTaskId: 1980149306768457730
|
||
2025-10-20 15:30:11 DEBUG - 任务 TASK20251020153005ABC 状态: RUNNING
|
||
...
|
||
2025-10-20 15:33:21 INFO - 任务成功 - taskNo: TASK20251020153005ABC
|
||
2025-10-20 15:33:22 INFO - 任务 TASK20251020153005ABC 处理完成，结果URL: https://rh-images.xiaoyaoyou.com/...
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 数据库变更
|
||
|
||
### ai_task表新增字段
|
||
|
||
```sql
|
||
ALTER TABLE `ai_task`
|
||
ADD COLUMN `provider_type` VARCHAR(50) NULL,
|
||
ADD COLUMN `provider_task_id` VARCHAR(100) NULL,
|
||
ADD COLUMN `provider_response` TEXT NULL;
|
||
```
|
||
|
||
### points_config表新增字段
|
||
|
||
```sql
|
||
ALTER TABLE `points_config`
|
||
ADD COLUMN `provider_type` VARCHAR(50) NOT NULL DEFAULT 'openai',
|
||
ADD COLUMN `provider_config` TEXT NULL;
|
||
```
|
||
|
||
---
|
||
|
||
## ⚠️ 注意事项
|
||
|
||
### 1. 兼容性
|
||
|
||
- ✅ 现有OpenAI模型完全不受影响
|
||
- ✅ 现有API接口保持不变
|
||
- ✅ 现有数据可正常使用
|
||
|
||
### 2. 轮询性能
|
||
|
||
- 每5秒轮询一次RunningHub任务
|
||
- 最多同时处理100个任务
|
||
- 建议生产环境增加Redis缓存减少数据库压力
|
||
|
||
### 3. 错误处理
|
||
|
||
- RunningHub任务失败会自动退还积分
|
||
- 超时任务会被标记为failed
|
||
- 所有异常都有详细日志记录
|
||
|
||
### 4. 监控建议
|
||
|
||
```bash
|
||
# 查看RunningHub任务数量
|
||
SELECT COUNT(*) FROM ai_task
|
||
WHERE provider_type='runninghub' AND status='processing';
|
||
|
||
# 查看平均处理时间
|
||
SELECT AVG(TIMESTAMPDIFF(SECOND, start_time, complete_time)) as avg_seconds
|
||
FROM ai_task
|
||
WHERE provider_type='runninghub' AND status='completed'
|
||
AND complete_time > DATE_SUB(NOW(), INTERVAL 1 DAY);
|
||
```
|
||
|
||
---
|
||
|
||
## 🎯 功能对比
|
||
|
||
| 特性 | OpenAI格式 | RunningHub |
|
||
|------|-----------|------------|
|
||
| **认证方式** | Bearer Token | API Key |
|
||
| **调用方式** | 同步 | 异步 |
|
||
| **返回方式** | 立即返回 | 轮询查询 |
|
||
| **处理时间** | 10-30秒 | 2-5分钟 |
|
||
| **支持类型** | 图片、视频 | 视频 |
|
||
| **横竖屏** | URL参数 | model字段 |
|
||
| **队列管理** | Redis队列 | RunningHub内部 |
|
||
| **进度追踪** | WebSocket | WebSocket |
|
||
|
||
---
|
||
|
||
## 🔮 未来扩展
|
||
|
||
1. **更多服务商**：可以继续添加其他AI服务商（Midjourney、Stable Diffusion等）
|
||
2. **智能路由**：根据价格、速度、成功率自动选择最优服务商
|
||
3. **负载均衡**：同一个模型配置多个服务商，实现负载分担
|
||
4. **降级策略**：主服务商故障时自动切换到备用服务商
|
||
5. **成本优化**：根据用户等级选择不同价格的服务商
|
||
|
||
---
|
||
|
||
## 📞 技术支持
|
||
|
||
如遇问题，请检查：
|
||
|
||
1. **数据库迁移是否成功**
|
||
```sql
|
||
DESC ai_task; -- 检查是否有provider_type字段
|
||
```
|
||
|
||
2. **配置是否正确**
|
||
```bash
|
||
grep "runninghub" src/main/resources/application.yml
|
||
```
|
||
|
||
3. **服务是否启动**
|
||
```bash
|
||
ps aux | grep spring_1818_user_server
|
||
```
|
||
|
||
4. **日志是否有报错**
|
||
```bash
|
||
tail -100 logs/application.log
|
||
```
|
||
|
||
---
|
||
|
||
**集成完成！** 🎉
|
||
|
||
系统现已支持OpenAI和RunningHub双服务商，用户可以无感切换使用不同的AI生成服务！
|
||
|