From 8fb99094afbd385e529a15d8144d4e15ed9ac6db Mon Sep 17 00:00:00 2001
From: WangLiZhao <1838393649@qq.com>
Date: Mon, 27 Apr 2026 10:57:05 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=20README=20=E4=BB=A5?=
 =?UTF-8?q?=E5=8F=8D=E6=98=A0=20API=20Key=20=E6=A0=BC=E5=BC=8F=E5=92=8C?=
 =?UTF-8?q?=E6=B5=81=E7=A8=8B=E4=BC=98=E5=8C=96?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 92 +++++++++++++++++++++++++++++++++----------------------
 1 file changed, 55 insertions(+), 37 deletions(-)

diff --git a/README.md b/README.md
index 925caff..98dfd3f 100644
--- a/README.md
+++ b/README.md
@@ -13,7 +13,7 @@
 - 支持配置：
   - 请求地址：`base_url + route`
   - 请求方式：`http_method`（GET/POST）
-  - 请求密钥：`api_key`（以请求头注入，示例：`TTS_API_KEY:your-key`）
+  - 请求密钥：`api_key`（以请求头注入，支持多个 header）
   - 超时：`timeout_seconds`
   - 并发：`max_concurrency`（按租户+模型的 Redis 分布式信号量限流）
   - 重试：`retry_times`（失败后最多再重试 N 次）
@@ -26,47 +26,73 @@
   - 调用模型服务（GET/POST）
   - 结果上传 OSS（调用你们的 OSS 文件服务 `oss/file/uploadFile`，透传 `Authorization/X-User-Info`）
 - 批量领取结果：批量查询 `task_id` 列表，返回 `task_id/state/oss_file`，并把成功的任务从 `state=2` 更新为 `state=4`
-- 自动重试：失败 `state=3` 会由清理器按 `retry_times` 重新入队到队尾（保证先来后到）
+- 自动重试：失败 `state=3` 会由清理器按 `retry_times` 重新入队到队尾
 - 自动清理：
-  - `state=4` 且 `expire_at` 到期 → 硬删除任务（并尝试删除 OSS）
-  - 失败重试耗尽仍失败 → 硬删除任务（并尝试删除 OSS）
+  - `state=4` 且 `expire_at` 到期 → 硬删除任务
+  - 失败重试耗尽仍失败 → 硬删除任务
   - `state=0/1` 超时 → 标记失败（防止卡死）
 
 ### 1.3 统计（asynch_model_stat）
 - 按天统计：`day + tenant_id + creator + model_name -> request_count`
 - 统计口径：仅在 Worker 真正调用模型服务时计数（OSS 重试不计数）
-- 用途：给其他服务提供全局限流/监控依据（分布式场景下通过数据库 UPSERT 原子累加保证一致性）
+- 用途：给其他服务提供全局限流/监控依据
 
 ---
 
 ## 2. 使用流程（业务方如何接入）
 
-### 2.1 第一步：配置模型
-调用“模型管理”接口新增模型配置（例：TTS）：
-- `model_name=tts`
-- `base_url=http://xxx:port`
-- `route=/tts`
-- `http_method=POST`
-- `api_key=TTS_API_KEY:your-key`（可选）
+### 第一步：创建模型配置
+业务方（或运维）先在中间件里创建/更新模型配置（`model_name` 为唯一键），例如：
+- `POST /model/createModel`（或 `/model/updateModel`）
 
-### 2.2 第二步：创建任务拿 task_id
-业务方调用 `CreateTask`，传 `modelName + requestPayload`，中间件返回 `task_id`。
-业务方把 `task_id` 落到自己的业务表（状态=生成中）。
+请求示例（JSON）：
+```json
+{
+  "modelName": "model-service",
+  "baseUrl": "http://127.0.0.1:8000",
+  "route": "/api/v1/chat",
+  "httpMethod": "POST",
+  "apiKey": "API_KEY:model-key,API_STATE:true,API_NUM:123",
+  "enabled": 1,
+  "maxConcurrency": 5,
+  "queueLimit": 20,
+  "timeoutSeconds": 1800,
+  "retryTimes": 3,
+  "retryQueueMaxSeconds": 600,
+  "autoCleanSeconds": 3600,
+  "remark": "Model-Service 模型服务"
+}
+```
 
-### 2.3 第三步：业务方领取结果（推荐批量）
-业务方在自己的“定时任务服务/轮询器”中，批量把 `task_id` 列表传给中间件：
-- 返回每个任务的 `state + oss_file`
-- 对 `state=2(成功)` 的任务，中间件会更新为 `state=4(已下载)` 并写入 `expire_at = now + auto_clean_seconds`
+参数说明：
+- `modelName`：模型名称（唯一标识/路由键）
+- `baseUrl`：模型服务地址（Base URL）
+- `route`：模型服务路由（拼接到 baseUrl 后）
+- `httpMethod`：请求方式（GET/POST）
+- `apiKey`：请求头绑定（支持多个 header，逗号分隔，格式 `Key:Value`；布尔/数字也会以字符串形式注入 header）
+- `enabled`：是否启用（0禁用/1启用）
+- `maxConcurrency`：单模型最大并发（按租户+模型维度限流）
+- `queueLimit`：排队上限（近似控制，超过则拒绝创建）
+- `timeoutSeconds`：调用模型服务超时（秒）
+- `retryTimes`：失败后最多再重试 N 次（不含首次）
+- `retryQueueMaxSeconds`：失败重试最大排队时间（秒）；0 表示重试插队到队首；>0 表示排队超过该时间后插队，否则仍到队尾
+- `autoCleanSeconds`：任务被领取到 `state=4` 后的保留时间（秒），到期清理
+- `remark`：备注说明
 
-业务方拿到 `oss_file` 后做“业务转移”：
-- 方案 A：直接在业务表保存 `oss_file` 作为最终资源地址
-- 方案 B：业务侧下载后重新上传到业务自己的资产域，再保存新地址
+### 第二步：创建任务拿到 task_id
+业务方发起推理请求时调用：
+- `POST /task/createTask`（传 `modelName + requestPayload (+ bizName)`）
+- 中间件返回 `task_id`
+- 业务方将 `task_id` 落到自己的业务表，并把业务状态置为「生成中」
 
-> `state=4` 的数据允许重复获取，避免业务侧偶发中断导致“领取不到结果”。
+### 第三步：同步任务进度（推荐批量）
+业务方通过轮询/定时任务同步进度：
+- 推荐：`POST /task/getTaskBatch`（批量传 `taskIds`，返回每个任务的 `state + oss_file`）
+- 或单条：`GET /task/getTaskResult?taskId=...`
 
-### 2.4 获取统计（用于业务侧限流/监控）
-业务方可调用统计接口按时间段获取请求次数（默认分页 10 条）：
-- `/stat/listModelStat`：支持 `startDay/endDay/tenantId/creator/modelName` 条件筛选
+业务侧拿到 `oss_file` 后自行做资源处理（直接保存或转存），并把业务状态更新为「成功/失败」。
+
+> 说明：批量接口对 `state=2(成功)` 的任务会自动标记为 `state=4(已下载)` 并写入 `expire_at`，用于后续清理。
 
 ---
 
@@ -102,21 +128,13 @@
 
 ---
 
-## 5. 数据库初始化/升级
+## 5. 数据库初始化
 
-项目根目录提供 `update.sql`：
-- 首次部署：执行建表 SQL
-- 升级：执行 `ALTER TABLE ... ADD COLUMN IF NOT EXISTS ...` 的增量语句
+项目根目录提供 `update.sql`：首次部署执行建表 SQL。
 
 ---
 
-## 6. 接口文档
-
-更详细接口示例见：`docs/api.md`（包含模型管理、任务接口、批量领取接口、字段说明）。
-
----
-
-## 7. 开发与发布建议（Git）
+## 6. 开发与发布建议（Git）
 
 - `dev`：日常开发与联调
 - `main`：线上稳定分支