lth/1818web-hoduan

Fork 0

Files

Claude Workbench 0f7bc05697 [Claude Workbench] Initial commit - preserving existing code

2025-11-14 17:41:15 +08:00

15 KiB

Raw Blame History

管理端 - AI积分与模型配置 API 接口文档

📋 目录

概述
认证说明
积分配置管理
系统配置管理
AI任务监控
业务流程说明
常见问题

概述

本文档描述了管理员如何通过后台接口管理AI模型的积分价格、系统参数配置以及监控所有用户的AI任务。

基础信息

Base URL: https://your-domain.com
接口前缀: /admin
认证方式: JWT Token (需要 ADMIN 角色)
数据格式: JSON

积分与人民币兑换标准

根据系统设计，积分兑换标准如下：

1 元人民币 = 100 积分

定价策略： 在第三方API成本的基础上加价 50%

认证说明

获取管理员Token

接口: POST /admin/auth/login

请求示例:

{
  "username": "admin",
  "password": "your_password"
}

响应示例:

{
  "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模型的积分配置列表

请求示例:

curl -X GET "https://your-domain.com/admin/configs/points" \
  -H "Authorization: Bearer <token>"

响应示例:

{
  "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模型添加积分配置

请求示例:

{
  "modelName": "dalle-3",
  "pointsCost": 50,
  "description": "DALL-E 3图片生成",
  "isEnabled": 1
}

字段说明:

modelName (必填): 模型唯一标识，需与第三方API的模型名称一致
pointsCost (必填): 调用一次该模型需要消耗的积分数
description (可选): 模型的描述信息
isEnabled (必填): 是否启用 (1=启用, 0=禁用)

响应示例:

{
  "code": 200,
  "message": "配置创建成功",
  "data": {
    "id": 8,
    "modelName": "dalle-3",
    "pointsCost": 50,
    "description": "DALL-E 3图片生成",
    "isEnabled": 1
  }
}

3. 更新积分配置

接口: PUT /admin/configs/points/{id}

描述: 修改现有模型的积分价格或其他配置

请求示例:

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
  }'

响应示例:

{
  "code": 200,
  "message": "配置更新成功",
  "data": {
    "id": 1,
    "modelName": "sora_image",
    "pointsCost": 15,
    "description": "Sora高质量图片生成（已调价）",
    "isEnabled": 1
  }
}

4. 删除积分配置

接口: DELETE /admin/configs/points/{id}

描述: 删除指定的积分配置（逻辑删除）

请求示例:

curl -X DELETE "https://your-domain.com/admin/configs/points/8" \
  -H "Authorization: Bearer <token>"

响应示例:

{
  "code": 200,
  "message": "配置删除成功"
}

系统配置管理

管理员可以调整AI队列、任务超时等系统级参数。

1. 获取所有系统配置

接口: GET /admin/configs/system

描述: 获取所有系统配置项

请求示例:

curl -X GET "https://your-domain.com/admin/configs/system" \
  -H "Authorization: Bearer <token>"

响应示例:

{
  "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

请求示例:

{
  "configKey": "ai.queue.scan_interval",
  "configValue": "3000",
  "description": "队列扫描间隔（毫秒）"
}

3. 更新系统配置

接口: PUT /admin/configs/system/{id}

描述: 修改系统配置值

请求示例:

{
  "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 (可选): 按任务编号模糊搜索

请求示例:

curl -X GET "https://your-domain.com/admin/ai/tasks/list?page=1&size=20&status=completed" \
  -H "Authorization: Bearer <token>"

响应示例:

{
  "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}

描述: 查询指定任务的详细信息

请求示例:

curl -X GET "https://your-domain.com/admin/ai/tasks/TASK20251019143022ABC123" \
  -H "Authorization: Bearer <token>"

3. 强制取消任务

接口: POST /admin/ai/tasks/{taskNo}/cancel

描述: 手动取消一个处于排队中（queued）的任务，并退还用户积分

请求示例:

curl -X POST "https://your-domain.com/admin/ai/tasks/TASK20251019143022ABC123/cancel" \
  -H "Authorization: Bearer <token>"

响应示例:

{
  "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: 有两种方式：

修改 application.yml: 增加 ai.queue.max-concurrent 的值（需要重启服务）
修改数据库: 更新 system_config 表中 ai.queue.max_concurrent 的配置值（立即生效，无需重启）

推荐使用方式2，因为它更加灵活，可以根据服务器负载动态调整。

Q5: 用户的积分是如何退款的？

A: 系统在以下情况会自动退还积分：

任务失败（status: failed）
任务超时
管理员手动取消任务
API调用异常

退款会记录在 points_consumption_log 表中，change_type 为 refund。

Q6: WebSocket推送是如何工作的？

用户连接到 WebSocket 端点: wss://your-domain.com/ws
用户订阅自己的进度频道: /user/queue/tasks-progress
任务状态变化时（创建、开始处理、完成、失败），系统自动推送JSON格式的进度数据
前端接收数据并更新UI（如进度条、状态文本）

Q7: 如何查看系统当前的运行状态？

A: 可以通过以下方式监控：

使用 GET /admin/ai/tasks/list?status=processing 查看当前正在处理的任务数量
使用 GET /admin/ai/tasks/list?status=queued 查看队列中等待的任务数量
检查 Redis 中的队列长度（技术手段）

Q8: 如何备份和恢复积分配置？

备份: 导出 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

15 KiB Raw Blame History Unescape Escape

管理端 - AI积分与模型配置 API 接口文档

📋 目录

概述

基础信息

积分与人民币兑换标准

认证说明

获取管理员Token

后续请求认证

积分配置管理

1. 获取所有积分配置

2. 创建新的积分配置

3. 更新积分配置

4. 删除积分配置

系统配置管理

1. 获取所有系统配置

2. 创建系统配置

3. 更新系统配置

4. 删除系统配置

AI任务监控

1. 获取任务列表（分页）

2. 获取单个任务详情

3. 强制取消任务

业务流程说明

1. 积分定价流程

2. 用户调用AI模型的完整流程

3. 任务超时保护机制

4. 并发控制说明

常见问题

Q1: 如何修改某个模型的积分价格？

Q2: 积分配置修改后，正在处理的任务会受影响吗？

Q3: 如何临时禁用某个AI模型？

Q4: 如何提高系统的处理能力？

Q5: 用户的积分是如何退款的？

Q6: WebSocket推送是如何工作的？

Q7: 如何查看系统当前的运行状态？

Q8: 如何备份和恢复积分配置？

附录：数据库表结构

points_config 表

system_config 表

ai_task 表

技术支持

15 KiB

Raw Blame History