From 9bd2061f2664a212f081699095213fb1a0394ac2 Mon Sep 17 00:00:00 2001 From: iomgaa Date: Fri, 31 Jul 2026 11:13:53 -0400 Subject: [PATCH] docs: correct the version to 1.0.4 and the backfill wording --- Home.md | 2 +- 参考-公共API.md | 4 ++-- 参考-配置键.md | 2 +- 指南-遥测与成本.md | 8 ++++---- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/Home.md b/Home.md index 7d49f57..9cff5b0 100644 --- a/Home.md +++ b/Home.md @@ -2,7 +2,7 @@ 实验室统一的大语言模型调度与中转库:LLM / VLM / OCR / Embedding 共用同一套生产级治理栈(多源多账号、限流、错误分类重试、熔断、响应缓存、流式看门狗、遥测与成本)。治理单位是**一次模型调用**;任务编排与业务解析留在业务侧。 -当前版本 **v1.1.0**,已通过 GovDoc-SaaS 与 CHSAnalyzer 两个真实项目的全量迁移验收。 +当前版本 **v1.0.4**,已通过 GovDoc-SaaS 与 CHSAnalyzer 两个真实项目的全量迁移验收。 ## 文档地图(按你此刻要干什么选入口) diff --git a/参考-公共API.md b/参考-公共API.md index a5b2637..992bfd5 100644 --- a/参考-公共API.md +++ b/参考-公共API.md @@ -25,8 +25,8 @@ | cost | float\|None | 按价格表折算(缺表为 None) | | usage_source | str | measured / estimated / unavailable(v1.0.3 起三态,口径见 [[指南-遥测与成本]]) | | structured_data | Any\|None | `structured=` 时的校验结果 | -| cached_prompt_tokens | int\|None | 供应商 prompt cache 命中的输入 token 数(v1.1.0 新增)。`None` = 该源未上报;`0` = 上报了真实零命中——两者不可混同,口径见 [[指南-遥测与成本]] | -| model_reported | str\|None | API 响应体实际返回的 model(v1.1.0 新增);`None` = 未上报。与 `model`(配置别名)可能分叉,实验复现应认这个串 | +| cached_prompt_tokens | int\|None | 供应商 prompt cache 命中的输入 token 数(v1.0.4 新增)。`None` = 该源未上报;`0` = 上报了真实零命中——两者不可混同,口径见 [[指南-遥测与成本]] | +| model_reported | str\|None | API 响应体实际返回的 model(v1.0.4 新增);`None` = 未上报。与 `model`(配置别名)可能分叉,实验复现应认这个串 | ## EmbeddingClient diff --git a/参考-配置键.md b/参考-配置键.md index 5a6bb2a..274f31c 100644 --- a/参考-配置键.md +++ b/参考-配置键.md @@ -37,7 +37,7 @@ | `PGW_CACHE_BACKEND` | none / memory / redis | 必填;redis 需 NAMESPACE + TTL_S + REDIS_URL | | `PGW_CACHE_NAMESPACE` / `PGW_CACHE_TTL_S` | | 缓存启用时必填;TTL 必须 > 0 | | `PGW_TELEMETRY_BACKEND` | none / sqlite / postgres | 必填;sqlite 需 `PGW_TELEMETRY_SQLITE_PATH`,postgres 需 `PGW_TELEMETRY_PG_DSN` | -| `PGW_PRICING_PATH` | 路径 | 可选,价格表 JSON;缺省 cost 恒 None。条目支持可选第三档 `cached_input_per_1m`(v1.1.0,供应商 prompt cache 命中部分的单价;不填则命中部分也按 input 全额计) | +| `PGW_PRICING_PATH` | 路径 | 可选,价格表 JSON;缺省 cost 恒 None。条目支持可选第三档 `cached_input_per_1m`(v1.0.4,供应商 prompt cache 命中部分的单价;不填则命中部分也按 input 全额计) | | `PGW_STRUCTURED_MAX_RETRIES` | int | 结构化重问上限,缺省 2 | | `PGW_LEASE_TTL_S` | float | permit 租约,缺省 1500;须 ≥ 最大源 timeout | | `REDIS_URL` | dsn | redis 后端共用 | diff --git a/指南-遥测与成本.md b/指南-遥测与成本.md index 742112f..276a5e0 100644 --- a/指南-遥测与成本.md +++ b/指南-遥测与成本.md @@ -22,9 +22,9 @@ PGW_TELEMETRY_SQLITE_PATH=logs/telemetry.db # sqlite 时必填 | 用量 | prompt_tokens / completion_tokens / usage_source(三态,见下) | | 时延 | latency_ms / ttft_ms / max_inter_token_ms | | 结果 | cache_hit / error(异常类名前缀,如 `TransientError: ...`)/ cost | -| 可观测(v1.1.0) | cached_prompt_tokens / model_reported(见下) | +| 可观测(v1.0.4) | cached_prompt_tokens / model_reported(见下) | -v1.1.0 新增的两列会**自动补到已存在的旧表上**(SQLite 与 Postgres 都在初始化期幂等 ALTER),无需手工迁移;历史行的新列为 NULL。 +v1.0.4 新增的两列会**自动补到已存在的旧表上**,无需手工迁移;历史行的新列为 NULL。两个后端都是先探测缺列、只在真缺列时才 ALTER——稳态下一条 ALTER 都不发(`ADD COLUMN IF NOT EXISTS` 即使列已存在也会先取排他锁,而遥测是内联写入,锁住共享审计表会拖慢业务调用);补列失败也只是这几行遥测被丢弃,不会让遥测整体停摆。 `session_id`/`parent_call_id` 由调用方传入(`client.chat(..., session_id=...)`),用于把一次业务任务下的多次调用串成链。 @@ -50,7 +50,7 @@ PGW_PRICING_PATH=config/prices.json 配了价格表后每行遥测带 `cost`(元);缓存命中 token=0 天然零成本。缺价格表时 cost 恒 None,不报错。 -`cached_input_per_1m` 是**可选**的第三档(v1.1.0):供应商 prompt cache 命中的那部分输入按更低单价计费。配了它,cost 就按 `(prompt - cached) × input + cached × cached_input` 分段算;**不配就退化为全额输入价**——库不会替你猜一个折扣率,所以不配时 cost 会比实际账单偏高。命中数若超过输入总数(网关口径异常),按总数夹取并记一条 warning,不会算出负数。 +`cached_input_per_1m` 是**可选**的第三档(v1.0.4):供应商 prompt cache 命中的那部分输入按更低单价计费。配了它,cost 就按 `(prompt - cached) × input + cached × cached_input` 分段算;**不配就退化为全额输入价**——库不会替你猜一个折扣率,所以不配时 cost 会比实际账单偏高。命中数若超过输入总数(网关口径异常),按总数夹取并记一条 warning,不会算出负数。 **cost 的口径**:产生了真实调用、但用量不可得的行 `cost` 为 NULL——库不会编一个数字,免得"免费"与"未知"在数据上混为一谈。缓存命中行**不在此列**:它没产生新调用,`0.0` 是事实,所以即便 `usage_source='unavailable'`,cost 仍是 `0.0`。 @@ -67,7 +67,7 @@ WHERE usage_source = 'unavailable' AND cache_hit = false; 遥测后端不可用 → warning 后静默丢弃该行,**绝不影响业务调用**。共享后端注意:不要在真实批跑期间并发跑库的集成测试(时序隔离,详见主仓库 CLAUDE.md)。 -## 供应商 prompt cache(v1.1.0) +## 供应商 prompt cache(v1.0.4) `cached_prompt_tokens` 是**供应商服务器**复用了你的提示词前缀、按更低单价计费的那部分输入 token 数。它和 `cache_hit` 是两件事: