588 lines
15 KiB
Markdown
588 lines
15 KiB
Markdown
# 管理端 - AI积分与模型配置 API 接口文档
|
||
|
||
## 📋 目录
|
||
|
||
1. [概述](#概述)
|
||
2. [认证说明](#认证说明)
|
||
3. [积分配置管理](#积分配置管理)
|
||
4. [系统配置管理](#系统配置管理)
|
||
5. [AI任务监控](#ai任务监控)
|
||
6. [业务流程说明](#业务流程说明)
|
||
7. [常见问题](#常见问题)
|
||
|
||
---
|
||
|
||
## 概述
|
||
|
||
本文档描述了管理员如何通过后台接口管理AI模型的积分价格、系统参数配置以及监控所有用户的AI任务。
|
||
|
||
### 基础信息
|
||
|
||
- **Base URL**: `https://your-domain.com`
|
||
- **接口前缀**: `/admin`
|
||
- **认证方式**: JWT Token (需要 ADMIN 角色)
|
||
- **数据格式**: JSON
|
||
|
||
### 积分与人民币兑换标准
|
||
|
||
根据系统设计，积分兑换标准如下：
|
||
|
||
```
|
||
1 元人民币 = 100 积分
|
||
```
|
||
|
||
**定价策略：** 在第三方API成本的基础上加价 50%
|
||
|
||
---
|
||
|
||
## 认证说明
|
||
|
||
### 获取管理员Token
|
||
|
||
**接口**: `POST /admin/auth/login`
|
||
|
||
**请求示例**:
|
||
```json
|
||
{
|
||
"username": "admin",
|
||
"password": "your_password"
|
||
}
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "登录成功",
|
||
"data": {
|
||
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||
"userId": 1,
|
||
"username": "admin",
|
||
"role": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
### 后续请求认证
|
||
|
||
所有管理端API请求都需要在HTTP Header中携带Token：
|
||
|
||
```
|
||
Authorization: Bearer <your_token_here>
|
||
```
|
||
|
||
---
|
||
|
||
## 积分配置管理
|
||
|
||
管理员可以动态调整每个AI模型的积分消费价格。
|
||
|
||
### 1. 获取所有积分配置
|
||
|
||
**接口**: `GET /admin/configs/points`
|
||
|
||
**描述**: 获取所有AI模型的积分配置列表
|
||
|
||
**请求示例**:
|
||
```bash
|
||
curl -X GET "https://your-domain.com/admin/configs/points" \
|
||
-H "Authorization: Bearer <token>"
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "查询成功",
|
||
"data": [
|
||
{
|
||
"id": 1,
|
||
"modelName": "sora_image",
|
||
"pointsCost": 11,
|
||
"description": "Sora高质量图片生成",
|
||
"isEnabled": 1,
|
||
"createTime": "2025-10-19T10:00:00",
|
||
"updateTime": "2025-10-19T10:00:00"
|
||
},
|
||
{
|
||
"id": 2,
|
||
"modelName": "sora_video2",
|
||
"pointsCost": 160,
|
||
"description": "Sora视频生成 (竖屏10秒)",
|
||
"isEnabled": 1,
|
||
"createTime": "2025-10-19T10:00:00",
|
||
"updateTime": "2025-10-19T10:00:00"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 2. 创建新的积分配置
|
||
|
||
**接口**: `POST /admin/configs/points`
|
||
|
||
**描述**: 为新的AI模型添加积分配置
|
||
|
||
**请求示例**:
|
||
```json
|
||
{
|
||
"modelName": "dalle-3",
|
||
"pointsCost": 50,
|
||
"description": "DALL-E 3图片生成",
|
||
"isEnabled": 1
|
||
}
|
||
```
|
||
|
||
**字段说明**:
|
||
- `modelName` (必填): 模型唯一标识，需与第三方API的模型名称一致
|
||
- `pointsCost` (必填): 调用一次该模型需要消耗的积分数
|
||
- `description` (可选): 模型的描述信息
|
||
- `isEnabled` (必填): 是否启用 (1=启用, 0=禁用)
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "配置创建成功",
|
||
"data": {
|
||
"id": 8,
|
||
"modelName": "dalle-3",
|
||
"pointsCost": 50,
|
||
"description": "DALL-E 3图片生成",
|
||
"isEnabled": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3. 更新积分配置
|
||
|
||
**接口**: `PUT /admin/configs/points/{id}`
|
||
|
||
**描述**: 修改现有模型的积分价格或其他配置
|
||
|
||
**请求示例**:
|
||
```bash
|
||
curl -X PUT "https://your-domain.com/admin/configs/points/1" \
|
||
-H "Authorization: Bearer <token>" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"pointsCost": 15,
|
||
"description": "Sora高质量图片生成（已调价）",
|
||
"isEnabled": 1
|
||
}'
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "配置更新成功",
|
||
"data": {
|
||
"id": 1,
|
||
"modelName": "sora_image",
|
||
"pointsCost": 15,
|
||
"description": "Sora高质量图片生成（已调价）",
|
||
"isEnabled": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4. 删除积分配置
|
||
|
||
**接口**: `DELETE /admin/configs/points/{id}`
|
||
|
||
**描述**: 删除指定的积分配置（逻辑删除）
|
||
|
||
**请求示例**:
|
||
```bash
|
||
curl -X DELETE "https://your-domain.com/admin/configs/points/8" \
|
||
-H "Authorization: Bearer <token>"
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "配置删除成功"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 系统配置管理
|
||
|
||
管理员可以调整AI队列、任务超时等系统级参数。
|
||
|
||
### 1. 获取所有系统配置
|
||
|
||
**接口**: `GET /admin/configs/system`
|
||
|
||
**描述**: 获取所有系统配置项
|
||
|
||
**请求示例**:
|
||
```bash
|
||
curl -X GET "https://your-domain.com/admin/configs/system" \
|
||
-H "Authorization: Bearer <token>"
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "查询成功",
|
||
"data": [
|
||
{
|
||
"id": 1,
|
||
"configKey": "ai.queue.max_concurrent",
|
||
"configValue": "50",
|
||
"description": "每个AI模型的最大并发处理数",
|
||
"createTime": "2025-10-19T10:00:00",
|
||
"updateTime": "2025-10-19T10:00:00"
|
||
},
|
||
{
|
||
"id": 2,
|
||
"configKey": "ai.queue.max_user_concurrent",
|
||
"configValue": "3",
|
||
"description": "单个用户的最大并发任务数",
|
||
"createTime": "2025-10-19T10:00:00",
|
||
"updateTime": "2025-10-19T10:00:00"
|
||
},
|
||
{
|
||
"id": 3,
|
||
"configKey": "ai.task.timeout_minutes",
|
||
"configValue": "10",
|
||
"description": "任务处理超时时间（分钟）",
|
||
"createTime": "2025-10-19T10:00:00",
|
||
"updateTime": "2025-10-19T10:00:00"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 2. 创建系统配置
|
||
|
||
**接口**: `POST /admin/configs/system`
|
||
|
||
**请求示例**:
|
||
```json
|
||
{
|
||
"configKey": "ai.queue.scan_interval",
|
||
"configValue": "3000",
|
||
"description": "队列扫描间隔（毫秒）"
|
||
}
|
||
```
|
||
|
||
### 3. 更新系统配置
|
||
|
||
**接口**: `PUT /admin/configs/system/{id}`
|
||
|
||
**描述**: 修改系统配置值
|
||
|
||
**请求示例**:
|
||
```json
|
||
{
|
||
"configValue": "100",
|
||
"description": "每个AI模型的最大并发处理数（已调整）"
|
||
}
|
||
```
|
||
|
||
**⚠️ 重要提示**:
|
||
- 修改 `ai.queue.max_concurrent` 等配置后，系统会**立即生效**（通过缓存刷新机制）
|
||
- 但 `application.yml` 中的配置（如 `ai.queue.scan-interval`）需要**重启服务**才能生效
|
||
|
||
### 4. 删除系统配置
|
||
|
||
**接口**: `DELETE /admin/configs/system/{id}`
|
||
|
||
---
|
||
|
||
## AI任务监控
|
||
|
||
管理员可以查看和管理所有用户的AI生成任务。
|
||
|
||
### 1. 获取任务列表（分页）
|
||
|
||
**接口**: `GET /admin/ai/tasks/list`
|
||
|
||
**描述**: 分页查询所有AI任务，支持多条件筛选
|
||
|
||
**查询参数**:
|
||
- `page` (可选): 页码，默认 1
|
||
- `size` (可选): 每页数量，默认 10
|
||
- `userId` (可选): 按用户ID筛选
|
||
- `status` (可选): 按状态筛选 (created, queued, processing, completed, failed, cancelled)
|
||
- `modelName` (可选): 按模型名称筛选
|
||
- `taskNo` (可选): 按任务编号模糊搜索
|
||
|
||
**请求示例**:
|
||
```bash
|
||
curl -X GET "https://your-domain.com/admin/ai/tasks/list?page=1&size=20&status=completed" \
|
||
-H "Authorization: Bearer <token>"
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "查询成功",
|
||
"data": {
|
||
"total": 156,
|
||
"pages": 8,
|
||
"pageNum": 1,
|
||
"pageSize": 20,
|
||
"list": [
|
||
{
|
||
"taskNo": "TASK20251019143022ABC123",
|
||
"userId": 1001,
|
||
"modelName": "sora_image",
|
||
"taskType": "image",
|
||
"prompt": "一只可爱的猫咪在花园里玩耍",
|
||
"status": "completed",
|
||
"progress": 100,
|
||
"progressMessage": "任务已成功完成。",
|
||
"pointsFrozen": 11,
|
||
"pointsConsumed": 11,
|
||
"resultUrl": "https://cdn.example.com/generated/abc123.jpg",
|
||
"queueTime": "2025-10-19T14:30:25",
|
||
"startTime": "2025-10-19T14:30:30",
|
||
"completeTime": "2025-10-19T14:31:15",
|
||
"createTime": "2025-10-19T14:30:22",
|
||
"updateTime": "2025-10-19T14:31:15"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 获取单个任务详情
|
||
|
||
**接口**: `GET /admin/ai/tasks/{taskNo}`
|
||
|
||
**描述**: 查询指定任务的详细信息
|
||
|
||
**请求示例**:
|
||
```bash
|
||
curl -X GET "https://your-domain.com/admin/ai/tasks/TASK20251019143022ABC123" \
|
||
-H "Authorization: Bearer <token>"
|
||
```
|
||
|
||
### 3. 强制取消任务
|
||
|
||
**接口**: `POST /admin/ai/tasks/{taskNo}/cancel`
|
||
|
||
**描述**: 手动取消一个处于排队中（queued）的任务，并退还用户积分
|
||
|
||
**请求示例**:
|
||
```bash
|
||
curl -X POST "https://your-domain.com/admin/ai/tasks/TASK20251019143022ABC123/cancel" \
|
||
-H "Authorization: Bearer <token>"
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "任务 TASK20251019143022ABC123 已成功取消。"
|
||
}
|
||
```
|
||
|
||
**⚠️ 注意**:
|
||
- 只有状态为 `queued` 的任务可以被取消
|
||
- 已经在 `processing` 状态的任务无法取消
|
||
- 取消后，冻结的积分会全额退还给用户
|
||
|
||
---
|
||
|
||
## 业务流程说明
|
||
|
||
### 1. 积分定价流程
|
||
|
||
以 Sora Image 为例，完整的定价计算过程：
|
||
|
||
```
|
||
第三方API成本: $0.01/张
|
||
↓
|
||
人民币成本: 0.01 × 7.3 (汇率) = 0.073 元
|
||
↓
|
||
加价50%: 0.073 × 1.5 = 0.1095 元
|
||
↓
|
||
向上取整: 0.11 元
|
||
↓
|
||
转换为积分: 0.11 × 100 = 11 积分
|
||
```
|
||
|
||
**当前系统中的定价标准**:
|
||
|
||
| 模型名称 | 第三方成本 | 我方定价 | 积分价格 |
|
||
|---------|----------|---------|---------|
|
||
| sora_image | $0.01 | ¥0.11 | 11积分 |
|
||
| gpt-4o-image | $0.01 | ¥0.11 | 11积分 |
|
||
| sora_video2 | $0.15 | ¥1.60 | 160积分 |
|
||
| sora_video2-landscape | $0.15 | ¥1.60 | 160积分 |
|
||
| sora_video2-15s | $0.25 | ¥2.60 | 260积分 |
|
||
| sora_video2-landscape-15s | $0.25 | ¥2.60 | 260积分 |
|
||
| sora-2-pro-all | $0.40 | ¥4.20 | 420积分 |
|
||
|
||
### 2. 用户调用AI模型的完整流程
|
||
|
||
```
|
||
1. 用户提交任务
|
||
↓
|
||
2. 系统检查用户积分是否充足
|
||
↓
|
||
3. 冻结所需积分 (points_frozen)
|
||
↓
|
||
4. 创建任务记录 (status: created)
|
||
↓
|
||
5. 将任务放入Redis队列 (status: queued)
|
||
↓
|
||
6. 调度器检测到可用槽位
|
||
↓
|
||
7. 从队列取出任务，开始处理 (status: processing)
|
||
↓
|
||
8. 异步调用第三方API
|
||
↓
|
||
9a. 成功: 标记任务为completed，记录result_url，消耗积分
|
||
9b. 失败: 标记任务为failed，全额退还积分
|
||
↓
|
||
10. 通过WebSocket实时推送进度给用户
|
||
```
|
||
|
||
### 3. 任务超时保护机制
|
||
|
||
系统有完善的超时保护机制，防止任务卡死：
|
||
|
||
- **超时检查间隔**: 每60秒检查一次（可在 `application.yml` 中配置 `ai.task.timeout-scan-interval`）
|
||
- **超时判定标准**: 任务在 `processing` 状态下超过10分钟（可在数据库 `system_config` 表中修改 `ai.task.timeout_minutes`）
|
||
- **超时处理**: 自动标记为 `failed`，全额退还积分
|
||
|
||
### 4. 并发控制说明
|
||
|
||
**模型级并发控制**:
|
||
- 每个AI模型独立计数
|
||
- 默认最大并发数: 50（在 `application.yml` 中配置为 `ai.queue.max-concurrent: 50`）
|
||
- 当前正在处理的任务数达到上限时，新任务会在队列中等待
|
||
|
||
**用户级并发控制** (可选，已在 `system_config` 中预留配置):
|
||
- 单个用户最多同时处理3个任务（`ai.queue.max_user_concurrent`）
|
||
- 防止单个用户占用过多资源
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
### Q1: 如何修改某个模型的积分价格？
|
||
|
||
**A**: 使用 `PUT /admin/configs/points/{id}` 接口更新 `pointsCost` 字段。修改后立即生效，影响所有后续创建的任务。
|
||
|
||
### Q2: 积分配置修改后，正在处理的任务会受影响吗？
|
||
|
||
**A**: 不会。每个任务在创建时就已经记录了 `points_frozen`（冻结的积分数），这个值不会因为后续的价格调整而改变。
|
||
|
||
### Q3: 如何临时禁用某个AI模型？
|
||
|
||
**A**: 将该模型的 `isEnabled` 字段设置为 `0`。禁用后，用户提交该模型的任务时会收到错误提示，但不影响已经在队列中或正在处理的任务。
|
||
|
||
### Q4: 如何提高系统的处理能力？
|
||
|
||
**A**: 有两种方式：
|
||
1. **修改 `application.yml`**: 增加 `ai.queue.max-concurrent` 的值（需要重启服务）
|
||
2. **修改数据库**: 更新 `system_config` 表中 `ai.queue.max_concurrent` 的配置值（立即生效，无需重启）
|
||
|
||
**推荐使用方式2**，因为它更加灵活，可以根据服务器负载动态调整。
|
||
|
||
### Q5: 用户的积分是如何退款的？
|
||
|
||
**A**: 系统在以下情况会自动退还积分：
|
||
- 任务失败（`status: failed`）
|
||
- 任务超时
|
||
- 管理员手动取消任务
|
||
- API调用异常
|
||
|
||
退款会记录在 `points_consumption_log` 表中，`change_type` 为 `refund`。
|
||
|
||
### Q6: WebSocket推送是如何工作的？
|
||
|
||
**A**:
|
||
1. 用户连接到 WebSocket 端点: `wss://your-domain.com/ws`
|
||
2. 用户订阅自己的进度频道: `/user/queue/tasks-progress`
|
||
3. 任务状态变化时（创建、开始处理、完成、失败），系统自动推送JSON格式的进度数据
|
||
4. 前端接收数据并更新UI（如进度条、状态文本）
|
||
|
||
### Q7: 如何查看系统当前的运行状态？
|
||
|
||
**A**: 可以通过以下方式监控：
|
||
1. 使用 `GET /admin/ai/tasks/list?status=processing` 查看当前正在处理的任务数量
|
||
2. 使用 `GET /admin/ai/tasks/list?status=queued` 查看队列中等待的任务数量
|
||
3. 检查 Redis 中的队列长度（技术手段）
|
||
|
||
### Q8: 如何备份和恢复积分配置？
|
||
|
||
**A**:
|
||
- **备份**: 导出 `points_config` 和 `system_config` 表的数据
|
||
- **恢复**: 使用 SQL 的 `INSERT ... ON DUPLICATE KEY UPDATE` 语句批量导入
|
||
|
||
系统在 `V2__add_ai_task_and_points_schema.sql` 中已经提供了初始化数据的示例。
|
||
|
||
---
|
||
|
||
## 附录：数据库表结构
|
||
|
||
### points_config 表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|-----|------|------|
|
||
| id | bigint | 主键 |
|
||
| model_name | varchar(64) | 模型名称（唯一） |
|
||
| points_cost | int | 积分消耗 |
|
||
| description | varchar(255) | 模型描述 |
|
||
| is_enabled | tinyint(1) | 是否启用 |
|
||
| create_time | datetime | 创建时间 |
|
||
| update_time | datetime | 更新时间 |
|
||
| is_deleted | tinyint(1) | 逻辑删除标识 |
|
||
|
||
### system_config 表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|-----|------|------|
|
||
| id | bigint | 主键 |
|
||
| config_key | varchar(64) | 配置键（唯一） |
|
||
| config_value | varchar(512) | 配置值 |
|
||
| description | varchar(255) | 配置说明 |
|
||
| create_time | datetime | 创建时间 |
|
||
| update_time | datetime | 更新时间 |
|
||
|
||
### ai_task 表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|-----|------|------|
|
||
| id | bigint | 主键 |
|
||
| task_no | varchar(64) | 任务编号（唯一） |
|
||
| user_id | bigint | 用户ID |
|
||
| model_name | varchar(64) | 模型名称 |
|
||
| task_type | varchar(32) | 任务类型 |
|
||
| prompt | text | 提示词 |
|
||
| status | varchar(32) | 任务状态 |
|
||
| progress | int | 进度百分比 |
|
||
| progress_message | varchar(255) | 进度描述 |
|
||
| points_frozen | int | 冻结积分 |
|
||
| points_consumed | int | 实际消耗积分 |
|
||
| result_url | varchar(512) | 结果URL |
|
||
| error_message | text | 错误信息 |
|
||
| queue_time | datetime | 入队时间 |
|
||
| start_time | datetime | 开始处理时间 |
|
||
| complete_time | datetime | 完成时间 |
|
||
| create_time | datetime | 创建时间 |
|
||
| update_time | datetime | 更新时间 |
|
||
| is_deleted | tinyint(1) | 逻辑删除标识 |
|
||
|
||
---
|
||
|
||
## 技术支持
|
||
|
||
如有任何问题，请联系技术团队。
|
||
|
||
**文档版本**: v1.0
|
||
**最后更新**: 2025-10-19
|
||
|