docs: 采纳独立复核精化 v6 注释与不变量(reserve 阈值/consume 快照口径)

volc_limit_sync.py

@@ -101,6 +101,14 @@ CHECK_INTERVAL = 10
 # 未设置时 fallback 本常量。堵住"并发请求穿过闸门后集体撞线"的窗口。
 PREBLOCK_RESERVE_TOKENS = int(os.getenv("PREBLOCK_RESERVE_TOKENS", "50000"))
 
+# 思考模型输出侧兜底下限：deepseek-v4-flash 等默认思考模式，
+# usage.total_tokens 含 reasoning tokens，且不受 max_tokens 限制
+# （max_tokens 只约束正文 completion，思考 token 另计照常计费）。
+# 短文本请求若客户端声明 max_tokens=16，reserve 输出侧仅 16，
+# 实际消耗 ~150+（思考占大头），闸门形同虚设。取
+# max(声明值, 本下限) 兜住思考开销；2M 限额下 4096 偏差仅 0.2%。
+THINKING_RESERVE_FLOOR = int(os.getenv("THINKING_RESERVE_FLOOR", "4096"))
+
 # stable_limit 缺失时（首次同步前/新增模型/TTL 过期）的保守兜底限额。
 # 免费模型余额常态 < 2M（昨日采多少返多少），若 fallback 裸奔到采集上限 2M，
 # 余额不足的模型会被烧穿扣费。宁可短时收紧，不可裸奔。
@@ -424,7 +432,8 @@ def format_limit_debug_fields(static_limit=None, balance_at_sync=None, usage_at_
 def get_effective_limit(clean_model, api_base, current_usage=None):
     """
     Calculate effective limit using the Snapshot-Offset strategy.
-    limit = balance_at_sync + usage_at_sync - SMALL_BUFFER (= B0 - SMALL_BUFFER)
+    limit = balance_at_sync + usage_at_sync - SMALL_BUFFER
+          = B0 + L - SMALL_BUFFER   # L = 同步时点滞后窗口未结算消耗(滞后收敛时 L=0, 虚高随消费增长, 见 docs/volc-quota-notes.md §4.2/§7.5)
     _check_request_block 用 current_usage + reserve >= limit 撞线,语义正确。
     current_usage 参数仅用于无同步数据的 fallback 路径,非公式必需。
     """
@@ -435,8 +444,9 @@ def get_effective_limit(clean_model, api_base, current_usage=None):
     static_limit = get_static_limit(clean_model, api_base)
 
     # 2. Get Dynamic Limit from Snapshot
-    # balance_at_sync + usage_at_sync = 当日初始免费池 B0(常数)
-    # 累计限额 = B0 - SMALL_BUFFER,两次同步间不变
+    # balance_at_sync + usage_at_sync = B0 + L(B0 当日初始免费池, L 同步时点滞后未结算消耗;
+    # 仅滞后收敛 L=0 时恰为 B0, 未收敛时虚高 L, 见 docs/volc-quota-notes.md §7.5)
+    # 累计限额 = B0 + L - SMALL_BUFFER,两次同步间不变
     balance_key = f"limit:dynamic:volcengine:balance_at_sync:{clean_model}"
     usage_key = f"limit:dynamic:volcengine:usage_at_sync:{clean_model}"
 
@@ -449,7 +459,7 @@ def get_effective_limit(clean_model, api_base, current_usage=None):
         try:
             balance_at_sync = float(balance_val)
             usage_at_sync = float(usage_val)
-            # 累计限额 = B0 - SMALL_BUFFER,不依赖 current_usage
+            # 累计限额 = B0 + L - SMALL_BUFFER(L=同步时点滞后未结算消耗),不依赖 current_usage
             dynamic_limit = balance_at_sync + usage_at_sync - SMALL_BUFFER
             dynamic_limit = max(0, dynamic_limit)
 
@@ -827,17 +837,23 @@ class DailyLimitHandler(CustomLogger):
         if not data or not data.get("model"):
             return None
 
-        # 预留本次请求的预估消耗 = 输入 token(精确) + 输出上限(max_tokens)
+        # 预留本次请求的预估消耗 = 输入 token(精确) + 输出上限(max_tokens)。
         # 输入用 litellm.token_counter 精确计数(未知模型 fallback cl100k_base,
-        # 对中文偏高更安全);输出用请求声明的 max_tokens,未声明时 fallback 常量。
+        # 对中文偏高更安全)。
+        # 输出侧：思考模型 usage 含 reasoning tokens 且不受 max_tokens 限制，
+        # 故取 max(请求声明 max_tokens, THINKING_RESERVE_FLOOR) 兜底思考开销，
+        # 防短文本 + 小 max_tokens 请求 reserve 低估（实测 34 vs 实际 150+）。
         try:
-            max_out = float(
+            declared = (
                 data.get("max_tokens")
                 or data.get("max_completion_tokens")
                 or PREBLOCK_RESERVE_TOKENS
             )
+            max_out = max(float(declared), float(THINKING_RESERVE_FLOOR))
         except (TypeError, ValueError):
-            max_out = float(PREBLOCK_RESERVE_TOKENS)
+            max_out = max(
+                float(THINKING_RESERVE_FLOOR), float(PREBLOCK_RESERVE_TOKENS)
+            )
 
         input_tokens = 0
         try: