fix: harden the observability fields against the verifier findings

2026-07-31 08:28:41 -04:00
parent 966d548245
commit 32d7869043
9 changed files with 148 additions and 10 deletions
@@ -1,6 +1,6 @@
 # Research Wiki 索引

-> 自动生成，更新时间：2026-07-31 11:11 UTC
+> 自动生成，更新时间：2026-07-31 12:25 UTC

 ## design (18)
 - [2026-07-20-m1-core-design](designs/2026-07-20-m1-core-design.md) `design:2026-07-20-m1-core-design`
@@ -52,7 +52,7 @@
 - [响应可观测字段扩展实现计划](plans/response-observability-fields.md) `plan:response-observability-fields`

 ## schema (1)
- [表结构: llm_calls(遥测 18 字段)](schemas/llm-calls.md) `schema:llm-calls`
+- [表结构: llm_calls(遥测 20 字段)](schemas/llm-calls.md) `schema:llm-calls`

 ## metric (2)
 - [OCR 治理调用成功率与错误分类分布](metrics/ocr-call-success.md) `metric:ocr-call-success`
@@ -63,3 +63,4 @@
 - [2026-07-31 11:10 UTC] 新增边: plan:response-observability-fields --implements--> design:response-observability-fields
 - [2026-07-31 11:10 UTC] 重建索引: 46 篇页面
 - [2026-07-31 11:11 UTC] 重建索引: 46 篇页面
+- [2026-07-31 12:25 UTC] 重建索引: 46 篇页面
@@ -1,11 +1,11 @@
 ---
 type: schema
 node_id: schema:llm-calls
-title: "表结构: llm_calls(遥测 18 字段)"
+title: "表结构: llm_calls(遥测 20 字段)"
 date: 2026-07-20
 ---

-# 表结构: llm_calls(遥测 18 字段)
+# 表结构: llm_calls(遥测 20 字段)


 ## 列定义(冻结,M1 设计 §4.4 / ARCH §7.8)
@@ -24,6 +24,8 @@ date: 2026-07-20
 | error | TEXT | 异常信息;取消记 "cancelled" |
 | cost | REAL | M2 起 pricing 换算;`usage_source='unavailable'` 的真实调用行为 NULL(缓存命中行例外,仍为 0.0) |
 | created_at | TEXT NOT NULL DEFAULT (datetime('now')) | 落库时刻 |
+| cached_prompt_tokens | INTEGER | 供应商 prompt cache 命中的输入 token(2026-07-31,issue #3);NULL = 该源未上报,`0` = 上报了真实零命中,两者不可混同 |
+| model_reported | TEXT | API 响应体实际返回的 model;NULL = 未上报。与 `model`(配置别名)可能分叉 |

 ## usage/成本口径(2026-07-30,est_tokens 解耦)

@@ -35,6 +37,19 @@ date: 2026-07-20

 `SUM(cost)` 天然跳过 NULL,故账单汇总不再被虚构的估值污染;账目缺口的度量口径固定为 `WHERE usage_source = 'unavailable' AND cache_hit = false`。**`cache_hit` 限定不可省**:缓存命中行未产生新调用,cost 是事实上的 `0.0` 而非未知,本无账目缺口,漏掉该条件会让缺口度量偏高。

+## 供应商 prompt cache 口径(2026-07-31,issue #3)
+
+新增两列排在 `created_at` **之后**——旧表只能经 `ALTER TABLE ADD COLUMN` 追加到末尾,DDL 里若插在前面,新建库与升级库的物理列序会分叉(列序断言无合规修法)。两个后端在初始化期幂等补列:`CREATE TABLE IF NOT EXISTS` 不会给旧表加列,不补则每行写入被逐行 warning 丢弃、遥测静默全失;补列失败只降级为逐行丢弃,绝不让 recorder 整体失能。
+
+`cache_hit` 指 **PolyGateway 自身响应缓存**,与供应商 prompt cache 是两回事。缓存命中行的这两列是**原样回放**的历史值(与 `model`/`prompt_tokens` 同一口径),故命中率度量口径固定为:
+
+```sql
+SELECT SUM(cached_prompt_tokens)::float / NULLIF(SUM(prompt_tokens), 0)
+FROM llm_calls WHERE cache_hit = false AND cached_prompt_tokens IS NOT NULL;
+```
+
+`WHERE cache_hit = false` 不可省,理由与上面 cost 缺口口径同源:回放行计入即重复计数。
+
 ## 埋点位置(单一 helper 铁律)

 - `middleware/telemetry.py::TelemetryEmitter` 是全库**唯一** `record_llm_call` 调用点;