在您提交issue前，请确认以下信息：

• 我已经搜索过现有和历史issues，确认这是一个新问题

文档链接

当前仓库缺少独立的服务限流特性文档。已有入口只给配置片段，docs/zh/user_guide/features/ 下没有 rate_limiting.md：

• master：https://gitcode.com/Ascend/MindIE-Motor/blob/master/docs/zh/user_guide/deployment/k8s/pd_disaggregation_deployment.md
• master：https://gitcode.com/Ascend/MindIE-Motor/blob/master/docs/zh/user_guide/configuration/config_reference.md
• master：https://gitcode.com/Ascend/MindIE-Motor/blob/master/docs/zh/user_guide/configuration/update_config_whitelist.md
• master：https://gitcode.com/Ascend/MindIE-Motor/blob/master/docs/zh/user_guide/api/README.md

问题文档片段

PD 分离部署文档「服务限流」小节仅给出最小配置示例：

"motor_coordinator_config": {
  "rate_limit_config": {
    "enable_rate_limit": true,
    "max_requests": 10000,
    "window_size": 60
  }
}

配置参考中的 rate_limit_config 字段表只列出字段名与默认值，未说明生效范围、多 Worker 令牌桶、OLC 降级、429/413 响应、响应头，以及热更新何时能改 enable_rate_limit。

存在的问题

1. 特性指南中无法检索到服务限流的配置方法、原理与排障说明。
2. 未说明限流只挂在 Coordinator 推理面，且 simple 按每个推理 Worker 独立持有令牌桶，总通过量约为 max_requests × num_workers（默认 num_workers 为 4）。
3. 未说明 provider: olc 需要安装库和已存在的规则目录，加载失败时回退为 simple。
4. 未说明请求体超限返回 HTTP 413 且不消耗令牌，限流超限返回 HTTP 429，放行和拒绝都会带 X-RateLimit-*。
5. 未说明 scope 当前不改变分桶；启动时未开启限流则热更新不能补装中间件。启动时已创建 simple 限流器后，热更新可以改 enable_rate_limit、skip_paths、错误响应和令牌桶参数。
6. simple 拥堵告警用剩余令牌 available 与 max_requests × 85% 比较。桶接近满（空闲）时会误报，令牌快耗尽时反而不告警。应按已用额度 used = max_requests - available 判定：已用达到 85% 上报告警，低于 75% 恢复。该缺陷同时见 #513。
7. 未写清 max_request_body_size：默认 0 不限制，启动校验拒绝负数，运行时 <= 0 不检查。
8. 未说明拥堵告警按推理 Worker 进程分别上报，多个 Worker 同时接近额度时 Controller 会收到多条事件。
9. 未说明 max_requests 为 1、2、3、4、7、8 时，85% 与 75% 取整后阈值相同，边界附近会反复上报；为 1 时恢复条件 used < 0 无法成立，告警置位后不会清除。max_requests >= 10 时两个整数阈值至少相差 1。
10. report_alarms 失败时返回 ok=false 且不抛异常，但限流器在调用前就把拥堵状态置位，Controller 恢复后不会重试，告警一直漏报。该点与 #513 一并修。

同步提交：master https://gitcode.com/Ascend/MindIE-Motor/merge_requests/1041 ，v3.2.0 https://gitcode.com/Ascend/MindIE-Motor/merge_requests/1078 。两条分支都合入后问题才算在对应版本关闭。