182 lines
4.9 KiB
Markdown
182 lines
4.9 KiB
Markdown
# 发送消息与任务系统（后台运行 + 轮询）
|
||
|
||
本节覆盖：
|
||
|
||
- 创建对话（可选）：`POST /api/v1/conversations`
|
||
- 发送消息（创建后台任务）：`POST /api/v1/messages`
|
||
- 轮询事件：`GET /api/v1/tasks/<task_id>`
|
||
- 停止任务：`POST /api/v1/tasks/<task_id>/cancel`
|
||
|
||
## 1) 创建对话
|
||
|
||
### POST `/api/v1/conversations`
|
||
|
||
创建一个新的对话，并返回 `conversation_id`。
|
||
|
||
请求：
|
||
|
||
- Headers：`Authorization: Bearer <TOKEN>`
|
||
- Body：无
|
||
|
||
响应（200）：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"conversation_id": "conv_20260123_234245_036"
|
||
}
|
||
```
|
||
|
||
可能错误：
|
||
|
||
- `401`：缺少或无效 token
|
||
- `503`：系统未初始化（资源繁忙/容器不可用等）
|
||
- `500`：创建失败
|
||
|
||
## 2) 发送消息（创建后台任务）
|
||
|
||
### POST `/api/v1/messages`
|
||
|
||
创建一个后台任务执行智能体流程，并立即返回 `task_id`。
|
||
|
||
#### 请求
|
||
|
||
Headers：
|
||
|
||
- `Authorization: Bearer <TOKEN>`
|
||
- `Content-Type: application/json`
|
||
|
||
Body(JSON)：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|---|---:|---:|---|
|
||
| `message` | string | 是（或 images） | 用户消息文本；`message` 与 `images` 至少其一不为空 |
|
||
| `conversation_id` | string | 否 | 不传则自动新建对话；建议显式传入以便客户端管理会话 |
|
||
| `model_key` | string/null | 否 | 指定模型 key（可选）；具体可用值取决于服务端配置 |
|
||
| `run_mode` | string/null | 否 | 运行模式：`"fast"` \| `"thinking"` \| `"deep"`；若传入则优先使用 |
|
||
| `thinking_mode` | boolean/null | 否 | 兼容字段：true=thinking，false=fast；当 `run_mode` 为空时才使用 |
|
||
| `max_iterations` | integer/null | 否 | 最大迭代次数，默认服务端配置为 **100**（`config.MAX_ITERATIONS_PER_TASK`）；传入可覆盖 |
|
||
| `images` | string[] | 否 | 图片路径列表（服务端可访问的路径）；一般配合特定模型使用 |
|
||
|
||
优先级：`run_mode` > `thinking_mode` > 终端当前配置。`run_mode="deep"` 将启用深度思考模式（若模型与配置允许）。
|
||
|
||
#### 响应
|
||
|
||
成功（202）：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"task_id": "60322db3-f884-4a1e-a9b3-6eeb07fbab47",
|
||
"conversation_id": "conv_20260123_234245_036",
|
||
"status": "running",
|
||
"created_at": 1769182965.3038778
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
|
||
- `task_id`：任务唯一 ID（用于轮询/停止）
|
||
- `conversation_id`：本次任务归属对话
|
||
- `status`：初始为 `running`
|
||
- `created_at`：UNIX 时间戳（秒，float）
|
||
|
||
可能错误：
|
||
|
||
- `400`：`message/images` 都为空；或 `conversation_id` 无法加载
|
||
- `401`：缺少或无效 token
|
||
- `409`：该 API 用户已有运行中的任务（禁止并发）
|
||
- `503`：系统未初始化/资源繁忙
|
||
|
||
并发冲突示例（409）：
|
||
|
||
```json
|
||
{ "success": false, "error": "已有运行中的任务，请稍后再试。" }
|
||
```
|
||
|
||
## 3) 轮询任务事件（增量）
|
||
|
||
### GET `/api/v1/tasks/<task_id>?from=<offset>`
|
||
|
||
用于以 **HTTP 轮询**方式获取任务执行过程中的流式事件（与 WebSocket 同粒度）。
|
||
|
||
#### 请求
|
||
|
||
- Headers：`Authorization: Bearer <TOKEN>`
|
||
- Query：
|
||
- `from`：起始 offset（默认 0）
|
||
|
||
#### 响应（200）
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"task_id": "60322db3-f884-4a1e-a9b3-6eeb07fbab47",
|
||
"status": "running",
|
||
"created_at": 1769182965.30,
|
||
"updated_at": 1769182968.15,
|
||
"error": null,
|
||
"events": [
|
||
{ "idx": 0, "type": "ai_message_start", "data": {}, "ts": 1769182965.30 },
|
||
{ "idx": 1, "type": "text_start", "data": {}, "ts": 1769182968.09 },
|
||
{ "idx": 2, "type": "text_chunk", "data": { "content": "我来", "index": 1, "elapsed": 0.0 }, "ts": 1769182968.15 }
|
||
],
|
||
"next_offset": 3
|
||
}
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
|
||
- `status`：任务状态，常见值：
|
||
- `running`：执行中
|
||
- `cancel_requested`：已请求停止，等待实际停下
|
||
- `canceled`：已停止
|
||
- `succeeded`：成功结束
|
||
- `failed`：失败结束（`error` 会给出原因）
|
||
- `events`：从 `idx>=from` 的事件列表（按 idx 升序）
|
||
- `next_offset`：建议下一次轮询的 `from` 值
|
||
|
||
可能错误：
|
||
|
||
- `401`：缺少或无效 token
|
||
- `404`：任务不存在（或不属于该 API 用户）
|
||
|
||
#### 推荐轮询策略
|
||
|
||
- 轮询间隔：`0.5s ~ 2s`（任务越密集越推荐更快）
|
||
- 客户端必须：
|
||
1) 保存 `next_offset`
|
||
2) 追加处理 events
|
||
3) 当 `status != running` 时停止轮询
|
||
|
||
> 重要：服务端事件缓冲是 `deque(maxlen=1000)`，轮询过慢会丢失早期事件；客户端应自行落盘你需要的内容。
|
||
|
||
## 4) 停止任务
|
||
|
||
### POST `/api/v1/tasks/<task_id>/cancel`
|
||
|
||
请求停止某个任务。
|
||
|
||
请求：
|
||
|
||
- Headers：`Authorization: Bearer <TOKEN>`
|
||
- Body：无
|
||
|
||
成功（200）：
|
||
|
||
```json
|
||
{ "success": true }
|
||
```
|
||
|
||
说明：
|
||
|
||
- 该接口是“请求停止”，任务可能不会立刻停下；
|
||
- 停止后的最终状态在轮询里体现：`status` 变为 `canceled` 或 `failed/succeeded`（极少数情况下已接近结束）。
|
||
|
||
可能错误：
|
||
|
||
- `401`：缺少或无效 token
|
||
- `404`：任务不存在
|