限流策略使用指南

OLC 支持四种限流模式，可配置为单机限流或集群限流。

限流模式总览

模式	flowControlMode	说明	适用场景
QPS 限流	qps	每秒请求数控制	普通 API 接口
并发限流	concurrent	并发连接数控制	长连接、流式响应
配额限流	quota	总量配额控制	按总量计费的场景

单机 vs 集群：

特性	单机（NODE）	集群（CLUSTER）
policyType	NODE 或不填	CLUSTER
依赖	无	Redis
精度	单机精确	全局近似精确
性能	内存操作，极快	Redis + Lua，毫秒级

---

QPS 限流

基于令牌桶算法，控制每秒允许通过的请求数。

配置示例

{
  "group": {
    "name": "qpsGroup",
    "tags": [
      {"tag": "URL", "match": "equal", "values": ["/api/chat"]}
    ]
  },
  "flow": {
    "name": "qpsFlow",
    "enabled": true,
    "flowControlMode": "qps",
    "policyType": "NODE",
    "timeUnit": "second",
    "timeInterval": 1,
    "rateLimit": 100,
    "burstLimit": 120
  }
}

参数说明

参数	说明
rateLimit	每个时间窗口内允许的请求数（令牌生成速率）
burstLimit	令牌桶容量，允许短时突发（burstLimit >= rateLimit）
timeUnit + timeInterval	时间窗口，如 second + 1 表示每秒

rateLimit 与 burstLimit 的关系：

• rateLimit = 100, burstLimit = 100：严格每秒 100 个请求，无突发
• rateLimit = 100, burstLimit = 120：允许短时突发到 120，但持续速率不超过 100/s
• 建议 burstLimit >= rateLimit，否则令牌桶无法填满

---

并发限流

控制同时处理的请求数，适用于长连接和流式响应场景。

配置示例

{
  "group": {
    "name": "concurrentGroup",
    "tags": [
      {"tag": "URL", "match": "equal", "values": ["/api/stream"]}
    ]
  },
  "flow": {
    "name": "concurrentFlow",
    "enabled": true,
    "flowControlMode": "concurrent",
    "policyType": "NODE",
    "timeUnit": "second",
    "timeInterval": 1,
    "rateLimit": 50,
    "burstLimit": 50
  }
}

参数说明

参数	说明
rateLimit	最大并发数
burstLimit	与 rateLimit 保持一致

工作原理：请求进入时并发计数 +1，请求完成时 -1。当并发数超过 rateLimit 时拒绝新请求。

适用场景：

• SSE 流式响应
• WebSocket 长连接
• LLM 推理（GPU 资源有限）

---

配额限流

quota 模式配置示例

{
  "group": {
    "name": "quotaGroup",
    "tags": [
      {"tag": "URL", "match": "equal", "values": ["/api/chat"]}
    ]
  },
  "flow": {
    "name": "quotaFlow",
    "enabled": true,
    "flowControlMode": "quota",
    "policyType": "NODE",
    "timeUnit": "minute",
    "timeInterval": 1,
    "rateLimit": 1000,
    "burstLimit": 1000
  }
}

token_number 的使用

通过适配器配置 token_number 控制每次请求预扣的令牌数：

from olc.adapters.fastapi import OlcFastAPIAdapter, OlcAdapterConfig

config = OlcAdapterConfig(token_number=1)
app.add_middleware(OlcFastAPIAdapter, config=config)

---

集群限流

集群限流基于 Redis + Lua 脚本实现，确保多实例部署时限流全局生效。

Redis 配置

在 overload-config.properties 中添加 Redis 配置：

单机模式：

olc.redis.mode=alone
olc.redis.nodeList=localhost:6379
olc.redis.passwd=your_password
olc.redis.timeout=2000
olc.redis.maxConnections=64

集群模式：

olc.redis.mode=cluster
olc.redis.nodeList=redis1:6379,redis2:6379,redis3:6379
olc.redis.passwd=your_password

哨兵模式：

olc.redis.mode=sentinel
olc.redis.nodeList=sentinel1:26379,sentinel2:26379,sentinel3:26379
olc.redis.serviceName=mymaster
olc.redis.passwd=your_password

集群 QPS 限流配置

{
  "group": {
    "name": "clusterQpsGroup",
    "tags": [
      {"tag": "URL", "match": "equal", "values": ["/api/chat"]}
    ]
  },
  "flow": {
    "name": "clusterQpsFlow",
    "enabled": true,
    "flowControlMode": "qps",
    "policyType": "CLUSTER",
    "timeUnit": "second",
    "timeInterval": 1,
    "rateLimit": 1000,
    "burstLimit": 1000,
    "assignAlg": {
      "algName": "DEFAULT_TOKEN",
      "algParam": {
        "safeMode": "1",
        "safeRateLimit": "5"
      }
    }
  }
}

集群配额限流配置

{
  "group": {
    "name": "clusterQuotaGroup",
    "tags": [
      {"tag": "URL", "match": "equal", "values": ["/api/chat"]}
    ]
  },
  "flow": {
    "name": "clusterQuotaFlow",
    "enabled": true,
    "flowControlMode": "quota",
    "policyType": "CLUSTER",
    "timeUnit": "minute",
    "timeInterval": 1,
    "rateLimit": 50000,
    "burstLimit": 50000,
    "assignAlg": {
      "algName": "DEFAULT_TOKEN",
      "algParam": {
        "safeMode": "1",
        "safeRateLimit": "500"
      }
    }
  }
}

字段解释

• assignAlg 集群分配算法 当前只支持DEFAULT_TOKEN(默认算法)
• algParam 算法参数
• safeMode 安全模式，只有当集群流控中心(redis)出现故障时才会降级,降级后速率如何决定由safeMode决定，对应value值-1(全放通)、0(全部拒绝)和1(按照指定速率safeRateLimit限流)
• safeRateLimit 指定速率

注意事项

• 集群限流依赖 Redis，确保 Redis 服务可用
• 集群限流是近似精确：各节点定期从 Redis 获取令牌，存在少量误差
• Redis 密码支持 ENC(...) 加密格式

---

标签匹配与分组

匹配方式

匹配方式	match 值	说明	示例
精确匹配	equal	请求值必须完全等于配置值	"/api/chat"
正则匹配	regex	请求值匹配正则表达式	"/api/v[0-9]+/.*"
通配匹配	default	匹配所有值（配置值为 *）	"*"

分组类型

normal 类型（默认）：标签间做笛卡尔积，生成多个 TagGroup。

{
  "name": "apiModelGroup",
  "type": "normal",
  "tags": [
    {"tag": "URL", "match": "equal", "values": ["/api/chat"]},
    {"tag": "Model", "match": "equal", "values": ["gpt-4", "gpt-3.5"]}
  ]
}

这会生成两个分组：/api/chat + gpt-4 和 /api/chat + gpt-3.5，各自独立限流。

global 类型：每个标签值独立生成一个 TagGroup。

{
  "name": "globalGroup",
  "type": "global",
  "tags": [
    {"tag": "URL", "match": "equal", "values": ["/api/chat", "/api/stream"]}
  ]
}

这会生成两个独立分组：globalGroup_1（/api/chat）和 globalGroup_2（/api/stream）。

share 机制

share 控制是否按请求的实际值创建子组：

• share = true（默认用于 regex 匹配）：所有匹配的请求共享限流配额
• share = false（默认用于 default 匹配）：根据请求中的实际值创建子组，实现细粒度限流

示例 — 按 Model 维度拆分限流：

{
  "name": "modelSplitGroup",
  "type": "normal",
  "tags": [
    {"tag": "URL", "match": "equal", "values": ["/api/chat"]},
    {"tag": "Model", "match": "default", "values": ["*"], "share": false}
  ]
}

• Model 维度 share=false：按请求中实际的 Model 值创建子组，每个 Model 独立限流