PolyGateway

v1.3.5 ab00aa4457

v1.3.5 Stable

iomgaa released this 2026-09-10 01:53:20 +08:00 | 0 commits to main since this release

把治理单位从「一次尝试」补齐到「一次逻辑调用」(issue #19、#23)。此前重试、换源、结构化重问、embedding 分批都各自独立可见,而「这一次调用总共打了几次、总共花了多久、最后为什么失败」在库外拼不出来;结构化耗尽、embedding／OCR 的无源与准入拒绝更是一条遥测行都没有。

公共面四项变更

#	位置	变更	谁会当场断
1	`polygateway.CallStats`	新导出的 frozen dataclass(`logical_call_id` / `attempts` / `total_latency_ms`)	无(纯新增)
2	`LLMResponse` / `EmbeddingResponse` / `OcrTextResult` / `OcrLayoutResult`	各追加末尾字段 `call_stats: CallStats \| None = None`	按位置解包这四个类型的代码
3	`ports.TelemetryRecorder.record_llm_call()`	新增 10 个无默认值 keyword-only 参数(26 → 36 参)	任何自建 recorder——且在装配期当场报错,不再是运行期静默丢行
4	遥测表 `llm_calls`	追加 10 列(INSERT 字段 26 → 36,物理列 27 → 37);新增 `event_kind='terminal_failure'` 行	按旧口径计失败调用数的 SQL

第 3 条的装配期报错是有意的:_record 的 except Exception 会把旧签名 recorder 的 TypeError 吞成 warning,后果是下游升级后 100% 丢遥测且调用照常成功。降级方向的铁律管的是运行期写失败,不是装配错误。**fields 形态的 recorder 不受影响。

下游必须做的事

动作	说明
计失败调用改 `WHERE event_kind = 'terminal_failure'`	一次逻辑调用恰好一条终态行。`error IS NOT NULL` 跨尝试行与终态行,升级后计数会变大
`AVG(latency_ms)` 按 `event_kind` 分组	终态行的 `latency_ms` 是整个逻辑调用的总耗时,与单次尝试不同量纲
自建 recorder 补齐 10 参	或改成 `**fields`;同时同步自己的 schema 与 INSERT 字段
PG manual 档下游补列	`telemetry_schema_sql("postgres")` 自取;不补则这 10 个维度按现有列裁剪后静默不落库(库发一条点名警告)
注意失败行可能带 `http_status_code = 200`	MonkeyOCR 的 `success != true` 就是 200 下的失败,该列不可当成败判据

费用口径不变:终态行 cost IS NULL、usage_source='unavailable'、token 为 0,不参与 SUM(cost)。400 密集负载下错误行会翻倍(既有 attempt 错误行 + 新增终态行),这是已批准的下游可见变化。

其他

新列全部可空、无默认值、追加在现有末列之后;旧行不回填(NULL 表达「补列之前根本没记过这件事」),滚动升级期新旧进程可写同一张表。
error_body 沿用 summarize_body 上限,结构化耗尽终态行的 error 带有界说明(不含模型原始正文);两者都不在 PGW_TELEMETRY_TEXT_CAP 覆盖面内。
修正历史误标:embed() 非 200 的失败现在报 operation="embedding"。遥测新列 operation 由调用点给定,与 exc.operation 是两个语义。
重试预算与退避、429 免预算与 stall 算法、取消结算、限流/熔断语义、缓存 key 公式一字未改。

Downloads

11 Releases 18 Tags

v1.3.5 Stable

公共面四项变更

下游必须做的事

其他