From 429d767737f80b018d90b07559b18c7474725e30 Mon Sep 17 00:00:00 2001 From: iomgaa Date: Wed, 19 Aug 2026 22:35:45 -0400 Subject: [PATCH] docs: carry the 1.2.3 boundary into the packaged README The README is the only prose the sdist freezes, so anything a downstream needs after `pip install` has to be in it before the build. Four gaps: the install pin still floored at 1.2.1, which lets an explicit install land on a version without the schema mode or the text cap the same README documents; the capability table never mentioned either new key, telemetry_schema_sql, the retention script, or the DDL template; the "your llm_calls may be silently empty" warning about the 1.2.1 RLS template lived only in CHANGELOG.md, which is not in the sdist; and both references to tools/telemetry_retention.py read as if pip shipped it. The RLS note goes above the pg-template:rls anchor, not between it and the fence, so the block parser in test_postgres_telemetry.py still finds all seven blocks. Telemetry field count re-measured against inspect.signature(TelemetryRecorder.record_llm_call) and schema.COLUMNS: still 24, so the table's number stands. --- README.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 8f4c084..7e9ca17 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,7 @@ | 流式看门狗 | TTFT / inter-token / 总超时三层活性;thinking token 刷活性不计结果;截断流(缺 `[DONE]`)判瞬时不入缓存 | | 遥测与成本 | 每次调用(含缓存命中与失败)必录 24 字段;SQLite / Postgres 后端(表已存在时**不需要** schema 建表权限,最小权限账号可直接用);按价格表折算成本落库(注意 `LLMResponse.cost` 本身恒为 `None`,成本只进遥测);多模态内容摘要落库不存原图 | | 调用方维度 | 每次调用可带 `tenant_id`(遥测表的真实列,可挂 RLS、可建复合索引)与 `meta`(≤16 个自定义 KV);四个公共方法全覆盖,校验超限即报错;**库只交付列,不启用 RLS、不建索引** | +| 遥测表治理 | `llm_calls` 是**下游的表**:PG 侧缺省**不再自动 `ALTER` 补列**(`PGW_TELEMETRY_SCHEMA_MODE` 三态,不设则 sqlite→auto、postgres→manual),manual 档点名缺列并按现有列裁剪写入;`telemetry_schema_sql(backend)` 自取可粘进迁移文件的建表/补列 SQL;`PGW_TELEMETRY_TEXT_CAP` 限正文长度(**不设 = 存全文**);保留期与访问控制走[生产部署 DDL 模板](#生产部署-ddl-模板postgresql)加 `tools/telemetry_retention.py` | | 结构化输出 | json_repair 修复 / 原生 schema 双策略 + 校验失败有界带反馈重问 | | OCR | MonkeyOCR 双端点(文本转录 + 版面解析),bbox 数值防御下沉,逐源健康预检 `check_health()` | | Embedding | 分批、维度校验、与 chat 同一治理栈 | @@ -32,7 +33,7 @@ ```bash pip install --extra-index-url https://gitea.iomgaa.online/api/packages/iomgaa/pypi/simple/ \ - "polygateway[redis,postgres,structured]>=1.2.1,<2" + "polygateway[redis,postgres,structured]>=1.2.3,<2" ``` 核心仅依赖 `httpx` + `pydantic`;按需选 extras: @@ -287,6 +288,8 @@ CREATE TRIGGER llm_calls_immutable BEFORE UPDATE OR DELETE ON llm_calls ### 4. 行级安全与多租户隔离 +> **照抄过 1.2.1 那份 RLS 模板的部署请先查一遍**:那份模板把**写侧**也绑在 `app.tenant_id` 这个 GUC 上,而库从不设这个 GUC,于是它的每一条 `INSERT` 都被 policy 拒绝——遥测的失败方向是静默降级,表现不是报错而是**整张表零行**。用能绕过 RLS 的角色(superuser 或带 `BYPASSRLS`)执行 `SELECT count(*) FROM llm_calls;`,并在应用日志里搜 `Postgres 遥测写入失败(丢弃该行):`。下面这份是修正后的模板。 + ```sql @@ -357,6 +360,8 @@ SQLite 侧**不建议**对着一个大库文件跑 `DELETE` + `VACUUM`,而应** `tools/telemetry_retention.py` 的 SQLite 分支是给**存量场景**兜底的——已经攒成一个大库、来不及改轮转时用它,不是推荐路径。 +该脚本**随仓库分发,不在 pip 包内**(它是运维工具而非库能力,库本体不 import 它,也不该拿到 `DELETE` 权限),请从仓库的 [`tools/telemetry_retention.py`](https://gitea.iomgaa.online/iomgaa/PolyGateway/src/branch/main/tools/telemetry_retention.py) 取,用维护角色跑。 + ## 错误模型(四分类) 一切失败在 transport 层翻译为四类之一,治理行为由分类决定,业务侧不需要判断状态码: