# RunningHub集成快速参考卡

**版本：** v2.2.0 | **更新：** 2025-10-20

---

## 🎯 一分钟快速了解

### 完成的功能
- ✅ 集成RunningHub Sora2 API（文生视频 + 图生视频）
- ✅ 12个预配置模型（竖屏/横屏 × 普通/高清 × 10秒/15秒）
- ✅ 多厂商架构（OpenAI + RunningHub无缝切换）
- ✅ 10秒轮询优化（成本降低50%）
- ✅ 完整URL支持（图生视频无需预先上传）
- ✅ **并发控制**（最多100个轮询任务）
- ✅ **队列管理**（超出自动排队）

### 核心配置

```yaml
# application.yml
ai.providers.runninghub:
  polling-interval: 10000      # 10秒轮询
  max-polling-times: 60        # 最大10分钟
  max-polling-tasks: 100       # 最多100个并发轮询
  queue-check-interval: 5000   # 5秒检查队列
  api-key: "5c44cef12da3470e9f24da70c63787dc"
```

---

## 📝 快速测试

### 1. 文生视频（竖屏10秒）

```bash
curl -X POST "http://localhost:8081/user/ai/tasks/submit" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "modelName": "rh_sora2_text_portrait",
    "prompt": "一个人在海边奔跑"
  }'
```

### 2. 图生视频（横屏高清）

```bash
curl -X POST "http://localhost:8081/user/ai/tasks/submit" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "modelName": "rh_sora2_img_landscape_hd",
    "prompt": "让场景动起来",
    "imageUrl": "https://example.com/image.jpg"
  }'
```

---

## 📊 模型列表（12个）

| 模型名称 | 类型 | 时长 | 分辨率 | 积分 |
|---------|------|------|--------|------|
| rh_sora2_text_portrait | 文生视频 | 10秒 | 竖屏 | 160 |
| rh_sora2_text_landscape | 文生视频 | 10秒 | 横屏 | 160 |
| rh_sora2_text_portrait_hd | 文生视频 | 10秒 | 高清竖屏 | 420 |
| rh_sora2_text_landscape_hd | 文生视频 | 10秒 | 高清横屏 | 420 |
| rh_sora2_text_portrait_15s | 文生视频 | 15秒 | 竖屏 | 260 |
| rh_sora2_text_landscape_15s | 文生视频 | 15秒 | 横屏 | 260 |
| rh_sora2_img_portrait | 图生视频 | 10秒 | 竖屏 | 180 |
| rh_sora2_img_landscape | 图生视频 | 10秒 | 横屏 | 180 |
| rh_sora2_img_portrait_hd | 图生视频 | 10秒 | 高清竖屏 | 480 |
| rh_sora2_img_landscape_hd | 图生视频 | 10秒 | 高清横屏 | 480 |
| rh_sora2_img_portrait_15s | 图生视频 | 15秒 | 竖屏 | 280 |
| rh_sora2_img_landscape_15s | 图生视频 | 15秒 | 横屏 | 280 |

---

## 🚀 部署步骤（3步）

```bash
# 1. 数据库迁移
mysql -u root -p 1818ai < V5__add_provider_support.sql

# 2. 编译部署
mvn clean package -DskipTests
sudo systemctl restart spring_1818_user_server

# 3. 验证
sudo journalctl -u spring_1818_user_server | grep "注册AI Provider"
# 应看到：openai + runninghub
```

---

## 🔍 监控命令

```bash
# 查看队列状态（管理员接口）
curl "http://localhost:8081/admin/runninghub/queue/status" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

# 查看处理中的任务数
mysql -u root -p 1818ai -e "SELECT COUNT(*) FROM ai_task WHERE status='processing' AND provider_type='runninghub';"

# 查看等待队列中的任务数
mysql -u root -p 1818ai -e "SELECT COUNT(*) FROM ai_task WHERE status='queued' AND provider_type='runninghub';"

# 实时轮询日志
sudo journalctl -u spring_1818_user_server -f | grep -E "(RunningHub|队列)"

# 手动处理队列（管理员操作）
curl "http://localhost:8081/admin/runninghub/queue/process" \
  -H "Authorization: Bearer $ADMIN_TOKEN"
```

---

## 📚 完整文档

| 文档 | 说明 |
|-----|------|
| `RUNNINGHUB_FINAL_SUMMARY.md` | **总览**（推荐首读） |
| `RUNNINGHUB_QUEUE_OPTIMIZATION.md` | **队列优化方案**（v2.2.0新增） |
| `RUNNINGHUB_USAGE_GUIDE.md` | 使用指南（12个模型详解） |
| `RUNNINGHUB_CONCURRENCY_ANALYSIS.md` | 并发能力分析 |
| `POLLING_INTERVAL_OPTIMIZATION.md` | 轮询优化说明 |
| `DEPLOYMENT_CHECKLIST.md` | 部署检查清单 |
| `MULTI_VENDOR_ADAPTER_DESIGN.md` | 架构设计 |

---

## ⚠️ 注意事项

1. **图生视频不支持真人图像**
2. **轮询任务上限100个**（超出自动进入等待队列）
3. **imageUrl支持完整HTTP/HTTPS地址**
4. **任务失败自动退还积分**
5. **等待队列自动处理**（每5秒检查一次）

---

## 💡 常见问题

**Q：任务一直processing？**  
A：正常，RunningHub需要2-5分钟处理。查看轮询日志确认。

**Q：任务卡在queued状态？**  
A：说明当前轮询任务已满（100个），正在等待队列。任务完成后会自动提交。

**Q：如何查看队列状态？**  
A：使用管理员接口：`GET /admin/runninghub/queue/status`

**Q：如何调整并发上限？**  
A：修改 `application.yml` 中的 `max-polling-tasks`（默认100）

**Q：等待队列会堆积吗？**  
A：不会。任务完成后自动从队列提交新任务，队列持续消化。

---

**快速参考完毕！详细信息请查看完整文档。** 📖