diff --git a/README.md b/README.md index 0e46b01..7d22c36 100644 --- a/README.md +++ b/README.md @@ -87,6 +87,7 @@ - 普通响应、流式响应和异步任务响应。 - 3D 生成等任务型模型的任务提交、进度查询、结果文件和失败处理。 - 模型选择和基础路由。 +- 基础速率限制、并发控制、排队和任务状态。 - 用户余额、套餐和共享额度(具体规则待定)。 - Token、图片张数、音视频时长、任务次数、GPU 时间或其他模型资源的用量统计。 - 调用记录、费用明细和余额流水。 diff --git a/docs/01-product-definition-and-prototype.md b/docs/01-product-definition-and-prototype.md index 6e0bd7c..225ddcc 100644 --- a/docs/01-product-definition-and-prototype.md +++ b/docs/01-product-definition-and-prototype.md @@ -45,6 +45,27 @@ - 用户付费方式、免费试用、套餐、计价单位、扣费和退款规则暂未确定。 - 平台负责模型调用、用量统计、余额扣减和基础服务支持;具体账务规则进入待决策清单。 +### 并发、排队与任务规则 + +并发和排队是第一阶段的核心产品规则,不等到系统上线后再临时决定。第一阶段先定义用户可感知的行为和限制,具体队列、调度器、限流器和资源池在系统设计阶段确定。 + +| 调用类型 | 产品形态 | 用户可见状态 | 需要确定的规则 | +|---|---|---|---| +| 同步请求 | 在可接受等待时间内返回结果 | 处理中、成功、失败、超时、被限流 | 是否允许短队列、最大等待时间、容量不足时返回 429/503 或其他错误 | +| 流式请求 | 建立连接后持续返回内容 | 排队中、首字节等待、生成中、完成、中断 | 连接并发、首字节延迟、空闲超时、断线重连和重试 | +| 异步任务 | 提交任务后后台排队执行 | 已创建、排队中、运行中、成功、失败、取消、过期 | 最大队列长度、预计等待时间、取消、重试、结果保留和回调 | + +并发和排队规则至少需要覆盖以下维度: + +- 平台总并发、供应商并发、模型并发、用户/组织并发、项目并发和 API Key 并发。 +- 请求速率限制、同时执行数、队列长度、最大排队时间和任务过期时间。 +- 不同模型的资源差异,例如 Token、GPU、文件处理、音视频时长和 3D 生成任务。 +- 队列满、余额不足、供应商限流、供应商故障和平台过载时的提示与处理。 +- 任务取消、重复提交、幂等、自动重试、部分成功和失败扣费的关系。 +- 管理员能够观察队列深度、排队时间、执行时间、成功率和资源使用率。 + +第一版不要求现在确定所有容量数字,但必须为这些数字和策略保留决策位置。 + ## 三、目标用户 ### 用户 A:模灵科技内部业务与 AI SoulMate 团队 @@ -145,6 +166,8 @@ | UR-006 | 团队希望隔离项目凭证和预算 | 项目级 Key、权限和额度限制 | P1 | 不同项目可独立统计并限制用量 | | UR-007 | 用户希望上游异常时服务尽量可用 | 健康检查、路由和故障切换 | P1 | 可按策略切换可用供应商且不重复计费 | | UR-008 | 运营人员希望管理供给、价格和风险 | 供应商、模型、定价、用户和风控后台 | P0 | 配置变更可审计并按权限生效 | +| UR-009 | 用户希望在高峰期知道请求是排队、执行还是失败 | 并发限制、排队、任务状态、超时和容量提示 | P0 | 同步、流式和异步请求在容量不足时有明确且可预期的结果 | +| UR-010 | 运营人员希望控制不同模型和供应商的资源 | 模型/供应商并发、速率、队列和资源配额 | P1 | 可按模型和供应商查看并调整容量策略 | > 当前为需求矩阵初稿。正常流程、异常场景、非功能指标和测试用例将在需求评审中继续补齐。 @@ -206,6 +229,13 @@ 记录资源用量并完成额度结算 ``` +### 容量不足时的通用处理原则 + +- 同步和流式请求不能在用户无明确预期的情况下无限排队;超过等待上限应返回明确错误和重试建议。 +- 异步模型应优先返回任务 ID,让用户通过任务中心查询状态,而不是长时间占用请求连接。 +- 队列中的任务应显示当前状态;如果无法提供准确进度,应显示排队时间或预计开始时间,而不是伪造百分比。 +- 每次重试、取消和供应商切换都要能关联到原始请求或任务,避免重复扣费和重复生成。 + ### 运营人员管理流程 ```text @@ -314,7 +344,7 @@ - Key 名称和所属项目。 - 创建时间、最后使用时间和状态。 -- 调用权限和额度限制。 +- 调用权限、额度、速率、并发和队列限制。 - 创建、禁用和轮换操作。 **主要操作**:创建 Key、复制一次性密钥、禁用泄漏密钥。 @@ -384,6 +414,7 @@ - API Key 创建和禁用。 - 统一模型调用入口。 - 支持同步、流式和异步任务三种调用模式。 +- 基础速率限制、并发限制、队列状态和超时处理。 - 首批模型清单至少覆盖文本/多模态能力,并预留或接入 AI 生成 3D 模型能力。 - 至少一个首批模型供应商的真实调用(供应商和模型清单待填写)。 - 内部/平台额度账户和基础额度记账(具体扣费、试用和退款规则待定)。 @@ -400,6 +431,7 @@ - 项目级 Key 和额度。 - 更完整的账单和对账。 - 调用状态、错误和服务状态页。 +- 队列优先级、租户公平性、动态调度和容量预测。 - 基础风控和异常用量处理。 ### P2:后续阶段 @@ -431,6 +463,7 @@ - 外部开发者首次使用流程可以从注册走到第一次调用。 - 模型目录、API Key、用量和账务记录之间的关系清楚,具体价格规则可暂时留空。 - 同步、流式和异步任务型模型的核心流程可以分别说明。 +- 并发限制、排队、超时、取消、重试和容量不足时的行为可以说明。 - 运营人员的供应商、模型、价格和用户管理路径清楚。 - P0/P1/P2 范围已经确认。 - 用户需求和产品需求之间可以追踪。 @@ -509,6 +542,21 @@ | 基础设施 | 域名、服务器、数据库、对象存储、监控和支付资源 | 待填写 | | 规模目标 | 用户数、并发、请求量、异步任务量和存储量 | 待填写 | +### F. 并发、排队与容量 + +| 待填写项 | 需要确认的内容 | 当前状态 | +|---|---|---| +| 规模基线 | 内部项目和外部用户的并发用户数、请求速率、任务量和峰值时段 | 待填写 | +| 平台限制 | 全局速率、全局并发、队列长度和最大排队时间 | 待填写 | +| 用户限制 | 用户、组织、项目和 API Key 的速率、并发、额度和队列限制 | 待填写 | +| 模型限制 | 每个模型的并发、队列、超时、输入大小和结果大小 | 待填写 | +| 供应商限制 | 供应商 API 限流、账户额度、并发、区域和服务时间 | 待填写 | +| 队列策略 | 先进先出、按用户公平、按优先级或按模型资源分类 | 待填写 | +| 容量不足 | 同步拒绝、流式拒绝、异步排队、降级模型或延迟执行 | 待填写 | +| 状态与通知 | 轮询、Webhook、站内通知、回调签名和任务状态保留 | 待填写 | +| 重试与幂等 | 自动重试次数、退避规则、重复任务识别和扣费关系 | 待填写 | +| 观测指标 | 队列深度、排队时间、执行时间、成功率、超时率和资源利用率 | 待填写 | + ## 十二、下一阶段产物 本阶段确认后,进入阶段 2 的可视化原型设计,产物包括: diff --git a/docs/DEVELOPMENT_PROCESS.md b/docs/DEVELOPMENT_PROCESS.md index 85227d5..3ff0e56 100644 --- a/docs/DEVELOPMENT_PROCESS.md +++ b/docs/DEVELOPMENT_PROCESS.md @@ -93,6 +93,7 @@ - 建立用户角色、用户故事和用户流程。 - 把需求拆成 P0、P1、P2 优先级。 - 明确功能需求和非功能需求。 +- 明确首版的并发、延迟、排队、超时、可用性和任务完成时间等关键质量目标;容量数字可以先记录为假设。 - 建立“用户需求—产品功能—验收标准—测试用例”的追踪关系。 - 评审正常流程、异常流程、业务闭环和跨系统影响。 - 编写 MVP 范围与验收标准。 @@ -105,6 +106,7 @@ - 用户故事地图。 - 功能清单和优先级。 - 业务规则说明。 +- 非功能需求和容量假设。 - MVP 验收标准。 - 需求评审记录。