iomgaa/PolyGateway
1
0
Fork 0
Code Issues 5 Pull Requests Actions Packages Projects Releases 17 Wiki Activity

feat: redefine generation_ms as net generation time with stall attribution

Browse Source 
CallStats gains stall_ms/stall_count (None = no stall observation);
winner sample triple (wall, stall_ms, stall_count) converted once in
_attempt success branch; net = max(0, wall - stall) converged into the
shared _record_winner_sample used by both the single-path guard and
hedge winner registration. Two-fail hedge rounds record nothing
(no winner to attribute). Design section 4.2; issues #27.
This commit is contained in:
iomgaa
2026-09-14 00:56:54 -04:00
parent 901a193514
commit 53bcf43172
5 changed files with 173 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/polygateway/middleware/retry.py
+41 -16
View File
@@ -58,6 +58,7 @@ if TYPE_CHECKING:
RetryPolicy,
SourceConfig,
TransportResult,
_CallContext,
)
@@ -165,6 +166,11 @@ def _is_rate_limited(outcome: LLMResponse | _Failed) -> bool:
_HEDGE_LOSER_ATTR = "_polygateway_hedge_loser"
# 生成样本三元组(1.3.8 设计 §4.2 N8): (墙钟 ms, 沉默总额 ms, 超阈值沉默段数)。
# 取整换算全库只在 _attempt 成功分支发生一次,消费侧(_record_generation/
# _register_hedge)只做净口径换算与透传,不再取整。
_GenerationSample = tuple[int, int | None, int | None]
"""编排在 cancel() 之前给输家任务置位的标记;_attempt 读它选遥测标签。"""
@@ -262,9 +268,10 @@ class RetryMW:
await self._admission.on_no_runnable(gate_rejections, reasons, clock)
continue
async with clock.attempting() as attempt:
# 每轮一个 sink: 裸生成时间由编排裁定归属(T2 单路 = 成功那轮;
# T3 对冲 = 赢家那一路),`_attempt` 只负责把本次 transport 耗时投进来
generation_sink: list[int] = []
# 每轮一个 sink: 生成样本(墙钟+沉默归因)由编排裁定归属
# (单路 = 成功那轮;对冲 = 赢家那一路),`_attempt` 只负责把本次
# transport 耗时与沉默观测投进来
generation_sink: list[_GenerationSample] = []
if self._hedge_after_s is None:
# 默认关闭: 逐字 1.3.6 单路路径(默认关闭回归门据此成立)
outcome = await self._attempt(
@@ -284,10 +291,9 @@ class RetryMW:
# 免了重试预算就得进 stall 账,否则这段耗时无人治理(见 StallClock)
attempt.refund()
if isinstance(outcome, LLMResponse):
# 与 register_attempt 同款 None 守卫: 库内现场构造的请求跳过登记;
# 对冲轮由 _attempt_hedged 按赢家归属登记,此处外层 sink 恒为空
if request.call_context is not None and generation_sink:
request.call_context.record_generation(generation_sink[0], accumulate=False)
# (守卫在 _record_generation 内: 上下文缺失/空 sink 均跳过)
self._record_generation(request, generation_sink)
return outcome
if not rate_limited:
fails += 1
@@ -314,7 +320,7 @@ class RetryMW:
*,
first_token_event: asyncio.Event | None,
content_event: asyncio.Event | None,
generation_sink: list[int],
generation_sink: list[_GenerationSample],
) -> LLMResponse | _Failed:
call_id = str(uuid.uuid4())
started = self._now()
@@ -328,8 +334,9 @@ class RetryMW:
if request.call_context is not None:
request.call_context.register_attempt()
try:
# 裸生成时间(1.3.7 H8): 计时只包 transport 调用本身,起点紧贴调用前、
# 终点为返回后首句(中间无 await);取消落进来时 transport 未返回,不计。
# 净生成时间(1.3.8): 此处只量 transport 墙钟(起点紧贴调用前、
# 终点为返回后首句,中间无 await),沉默扣减在消费侧统一换算;
# 取消落进来时 transport 未返回,不计。
# 与该链路 total_latency_ms 同一只注入钟,差值(波动开销)才有意义
gen_started = self._now()
result = await self._transport.complete(
@@ -348,7 +355,12 @@ class RetryMW:
# T4 才在启用 stall 对冲的流式原路上接真事件(设计 §5.2 N3③)
content_event=content_event,
)
generation_sink.append(int((self._now() - gen_started) * 1000))
# 取整全库唯一处(设计 §4.2 N8): transport 的 float 沉默值在此
# 一次性转 int;None(非流式/增量 chunk<2)透传,消费侧不退减
wall_ms = int((self._now() - gen_started) * 1000)
stall_ms_i = None if result.stall_ms is None else int(result.stall_ms)
stall_count_i = None if result.stall_count is None else int(result.stall_count)
generation_sink.append((wall_ms, stall_ms_i, stall_count_i))
if result.usage_source == "unavailable":
# 用量不可得时按入场预扣量结算(delta==0),否则押金会被整笔退回,
# 对"从不返回 usage 帧"的源等于 TPM 闸失效(设计 §3.2 #9)
@@ -429,7 +441,7 @@ class RetryMW:
# Phase 1 启动原路: 事件与 sink 每轮新建(局部状态,严禁实例属性)
source, permit, entry = picked
first_token: asyncio.Event = asyncio.Event()
sink_p: list[int] = []
sink_p: list[_GenerationSample] = []
primary = asyncio.create_task(
self._attempt(
request,
@@ -480,7 +492,7 @@ class RetryMW:
return outcome
# Phase 4 启动对冲路(v1 单路,H5): 对冲路恒传 first_token_event=None,
# 不再触发梯次对冲;content_event 同恒 None(N3③,v1 不梯次)
sink_h: list[int] = []
sink_h: list[_GenerationSample] = []
hedge = asyncio.create_task(
self._attempt(
request,
@@ -579,14 +591,27 @@ class RetryMW:
)
@staticmethod
def _record_generation(request: ChatRequest, sink: list[int]) -> None:
def _record_generation(request: ChatRequest, sink: list[_GenerationSample]) -> None:
"""record_generation 的共享守卫: 上下文缺失(库内现场构造)或空 sink 均跳过。"""
if request.call_context is not None and sink:
request.call_context.record_generation(sink[0], accumulate=False)
RetryMW._record_winner_sample(request.call_context, sink[0])
@staticmethod
def _record_winner_sample(context: _CallContext, sample: _GenerationSample) -> None:
"""净口径唯一换算(设计 §4.2): net = max(0, 墙钟 − 沉默),clamp 防御(N4)。
stall 两值透传: None(非流式/增量 chunk<2)时 net=墙钟不退减、快照归因
保持 None(排除条款——None 透传天然达成,无需分支)。
"""
wall_ms, stall_ms, stall_count = sample
net_ms = max(0, wall_ms - (stall_ms or 0))
context.record_generation(
net_ms, accumulate=False, stall_ms=stall_ms, stall_count=stall_count
)
@staticmethod
def _register_hedge(
request: ChatRequest, *, hedge_won: bool, winner_sink: list[int] | None
request: ChatRequest, *, hedge_won: bool, winner_sink: list[_GenerationSample] | None
) -> None:
"""对冲登记(赢家裁定后一次性;同 register_attempt 的 None 守卫)。
@@ -597,7 +622,7 @@ class RetryMW:
if context is None:
return
if winner_sink:
context.record_generation(winner_sink[0], accumulate=False)
RetryMW._record_winner_sample(context, winner_sink[0])
context.register_hedge(hedge_won=hedge_won)
async def _on_rejected(
src/polygateway/types.py
+34 -3
View File
@@ -320,9 +320,20 @@ class CallStats:
hedges: int = 0
"""本次逻辑调用实际并发发出的对冲路数(触发但准入失败静默不计);1.3.6 及以前恒 0。"""
generation_ms: int = 0
"""裸生成时间: 赢家/成功那次 transport 调用的墙钟时长(口径见设计 §4.5 H8)。"""
"""净生成时间(1.3.8 起重定义,设计 §4.2): 赢家/成功那次 transport 墙钟
− Σ(超阈值中段沉默);仍含 TTFT 与尾部(末 chunk→流结束)。
非流式/增量 chunk<2 无沉默观测、不退减(= 原墙钟,此时 stall 两值 None)。
墙钟还原 = generation_ms + stall_ms。1.3.7 及以前本字段是完整墙钟,
口径变化见 CHANGELOG 行为变更段。"""
hedge_won: bool = False
"""赢家是否为对冲路;无对冲恒 False。"""
stall_ms: int | None = None
"""赢家路超阈值中段沉默总额(净口径归因;None = 非流式/chunk<2/无赢家)。
墙钟 = generation_ms + stall_ms;None 是"无沉默观测",不是 0。"""
stall_count: int | None = None
"""超阈值相邻间隔个数(归因成对报告,Gregg 原则,调研 §B2)。"""
class _CallContext:
@@ -340,6 +351,8 @@ class _CallContext:
"_hedge_won",
"_hedges",
"_now",
"_stall_count",
"_stall_ms",
"_started",
"_terminal_claimed",
"logical_call_id",
@@ -353,6 +366,8 @@ class _CallContext:
self._generation_ms = 0
self._hedges = 0
self._hedge_won = False
self._stall_ms: int | None = None
self._stall_count: int | None = None
self._terminal_claimed = False
def register_attempt(self) -> None:
@@ -363,9 +378,23 @@ class _CallContext:
"""
self._attempts += 1
def record_generation(self, elapsed_ms: int, *, accumulate: bool) -> None:
"""chat/OCR 覆盖(结构化重问最后一轮为准);embedding 分批累加。"""
def record_generation(
self,
elapsed_ms: int,
*,
accumulate: bool,
stall_ms: int | None = None,
stall_count: int | None = None,
) -> None:
"""chat/OCR 覆盖(结构化重问最后一轮为准);embedding 分批累加。
stall 两值(1.3.8 净口径归因): chat 赢家路传入;embedding/ocr 既有调用
恒 None = "无沉默观测"(不是"沉默为 0")——它们是各自链路的墙钟,无中段
沉默概念。与 generation 同一次登记覆盖,不单独累加。
"""
self._generation_ms = self._generation_ms + elapsed_ms if accumulate else elapsed_ms
self._stall_ms = stall_ms
self._stall_count = stall_count
def register_hedge(self, *, hedge_won: bool) -> None:
"""对冲路实际发出即计数;赢家裁定后一次性登记。"""
@@ -381,6 +410,8 @@ class _CallContext:
hedges=self._hedges,
generation_ms=self._generation_ms,
hedge_won=self._hedge_won,
stall_ms=self._stall_ms,
stall_count=self._stall_count,
)
def claim_terminal(self) -> bool: