Compare commits
20 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 iomgaa
|
25a90ebd05 | ||
|
iomgaa
|
1201a04449 | ||
|
iomgaa
|
abcdf6930e | ||
|
iomgaa
|
31942f55f1 | ||
|
iomgaa
|
779a9b29a3 | ||
|
iomgaa
|
48ba36dd94 | ||
|
iomgaa
|
39a319e34e | ||
|
iomgaa
|
16743ca11d | ||
|
iomgaa
|
e5ad67408a | ||
|
iomgaa
|
ab0e924849 | ||
|
iomgaa
|
607523ef5c | ||
|
iomgaa
|
95104af2a5 | ||
|
iomgaa
|
5d2ad40336 | ||
|
iomgaa
|
22609c90d6 | ||
|
iomgaa
|
a0cf8546dc | ||
|
iomgaa
|
ce10881eb0 | ||
|
iomgaa
|
bd82f16921 | ||
|
iomgaa
|
2c9c5a3aa7 | ||
|
iomgaa
|
9185eab8c9 | ||
|
iomgaa
|
0e29deac1a |
@@ -41,10 +41,35 @@ for CODE_DIR in "${CODE_DIRS[@]}"; do
|
||||
fi
|
||||
fi
|
||||
|
||||
# 复杂度只对"本次改动触及的函数"硬拦: 全量拦截会让存量债务挡住一切提交
|
||||
# (含纯文档提交),久之只剩绕过一条路;存量 ≥C 函数降为告警,随触及随还。
|
||||
# 用 HEAD 对比工作区+暂存区: 钩子在 `git add && git commit` 同一命令里先于 add 运行
|
||||
if command -v radon &> /dev/null; then
|
||||
RADON_OUTPUT=$(radon cc "$CODE_DIR" -n C -s 2>&1 || true)
|
||||
if echo "$RADON_OUTPUT" | grep -qE '^\s+[FMC]\s'; then
|
||||
ERRORS+="[radon] 存在圈复杂度 ≥ C 的函数：\n$RADON_OUTPUT\n"
|
||||
mapfile -t CHANGED_PY < <(git diff HEAD --name-only --diff-filter=AM -- "$CODE_DIR" | grep '\.py$' || true)
|
||||
if [[ ${#CHANGED_PY[@]} -gt 0 ]]; then
|
||||
TOUCHED=$(git diff HEAD -U0 -- "${CHANGED_PY[@]}" | python3 -c '
|
||||
import json, re, subprocess, sys
|
||||
hunks, path = {}, None
|
||||
for line in sys.stdin:
|
||||
if line.startswith("+++ "):
|
||||
path = line[6:].strip() if line.startswith("+++ b/") else None
|
||||
m = re.match(r"@@ -\S+ \+(\d+)(?:,(\d+))? @@", line)
|
||||
if m and path:
|
||||
start, count = int(m.group(1)), int(m.group(2) or 1)
|
||||
hunks.setdefault(path, []).append((start, start + max(count, 1) - 1))
|
||||
data = json.loads(subprocess.run(["radon", "cc", "-j", "-n", "C", *hunks], capture_output=True, text=True).stdout or "{}")
|
||||
for path, blocks in data.items():
|
||||
for b in blocks if isinstance(blocks, list) else []:
|
||||
if any(s <= b["endline"] and e >= b["lineno"] for s, e in hunks.get(path, [])):
|
||||
print("%s:%s %s - %s (%s)" % (path, b["lineno"], b["name"], b["rank"], b["complexity"]))
|
||||
' 2>&1 || true)
|
||||
if [[ -n "$TOUCHED" ]]; then
|
||||
ERRORS+="[radon] 本次改动触及的函数圈复杂度 ≥ C：\n$TOUCHED\n"
|
||||
fi
|
||||
fi
|
||||
LEGACY_COUNT=$(radon cc "$CODE_DIR" -n C 2>/dev/null | grep -cE '^\s+[FMC]\s' || true)
|
||||
if [[ "$LEGACY_COUNT" -gt 0 ]]; then
|
||||
WARNINGS+="[radon] $CODE_DIR/ 存量 ${LEGACY_COUNT} 个函数圈复杂度 ≥ C(未被本次改动触及,不阻塞)。\n"
|
||||
fi
|
||||
fi
|
||||
|
||||
|
||||
+5
-1
@@ -31,7 +31,7 @@ LLM__QWEN__1__TIMEOUT_S=120
|
||||
# 模型不支持所配档位时报错并列出它真正支持的档(库带能力表,含出处与实测日期)
|
||||
# LLM__QWEN__1__EFFORT_FALLBACK=error # 档位打空时: error(默认,报错) | nearest(映射到最近的档)
|
||||
# 默认报错的理由是钱: 静默的 medium→max 在部分模型上是数倍账单;nearest 等距取弱侧
|
||||
# LLM__QWEN__1__MISSING_DONE=retry # SSE 缺 [DONE]: retry(默认) | salvage
|
||||
# LLM__QWEN__1__MISSING_DONE=retry # SSE 真截断(无 [DONE] 且无 finish+其后实测 usage): retry(默认) | salvage;1.3.10 起 finish+实测 usage+干净关闭的无 DONE 流恒视为完整
|
||||
# LLM__QWEN__1__TRUST_ENV=true # false = 绕过本地代理(LAN 直连)
|
||||
# LLM__QWEN__1__EXTRA_BODY={"temperature":0} # 本源恒定的采样参数(JSON 对象串)
|
||||
# 并入请求体,优先级低于 chat(overlay=...);受控实验固定解码用它,免得漏传
|
||||
@@ -200,3 +200,7 @@ PGW_TELEMETRY_BACKEND=none # sqlite | postgres | none(必填)
|
||||
# SOAK_OCR__GLOBAL__MAX_CONCURRENCY=16
|
||||
# SOAK_OCR__GLOBAL__RPM=300
|
||||
# SOAK_OCR_FAULT_SOURCES=monkey_3,monkey_4
|
||||
|
||||
# OpenAI 保真模式是 per-call response_mode="openai"，无新增环境键。
|
||||
# raw-only reasoning_effort 放调用 overlay；对应源不得设置 ENABLE_THINKING 或
|
||||
# REASONING_EFFORT，请求 reasoning_effort=None 只继承源配置，不撤销源级意图。
|
||||
|
||||
@@ -1,5 +1,51 @@
|
||||
# Changelog
|
||||
|
||||
## 1.3.10(2026-10-15)
|
||||
|
||||
#30/#31 同根修复: 1.3.9 以 `[DONE]` 存在、正文非空、字段白名单判定成功,上游的正常结局被当瞬时错误重试到耗尽(magpie/glm 不发 `[DONE]` 时单次调用挂 1216s;只有思考的 length 截断每次写满 max_tokens 后重抽)。本版改以上游 `finish_reason` 与传输完整性为准,流式/非流式/缓存读写共用一份判定。设计 `research-wiki/designs/2026-10-14-issue30-31-completion-verdict-design.md`。
|
||||
|
||||
### 修复
|
||||
|
||||
- **缺 `[DONE]` 但完整的流**(#31,**两种模式**): finish_reason 已到、其同帧或之后收到实测 usage、连接干净关闭 → 完整交回,用量记 measured,`stream_end="eof_after_finish"`。文本模式默认 `MISSING_DONE=retry` 原本同样会重试到耗尽;该键现在只管真截断(无 finish 或 finish 后无实测 usage)。
|
||||
- **只有思考的 length 截断**(#30): 保真模式原样交回(content 空、思考完整、finish_reason=length),不再重抽。
|
||||
- **`null` 与未知字段**(#30): 任意层 `null` 视为缺省(`refusal: null`、`tool_calls: null` 不再判失败,**非流式同样修复**);保真模式未知字段按 OpenAI 流式惯例无损合并(字符串拼接、对象递归、带 `index` 数组按 index 合并、`index/type/id/format` 同值幂等),Gemini `extra_content` 一类工具层扩展可原样回传。
|
||||
- **`reasoning` 别名**: vLLM/OpenRouter 的 `reasoning` 字段计入活性(此前只有思考的流会被 TTFT 看门狗误杀),文本模式无非空 `reasoning_content` 时投影为 `thinking`。
|
||||
- **截断结果不再写缓存**: 文本 salvage 结果此前会被缓存并在 TTL 内反复回放。
|
||||
|
||||
### 行为变更
|
||||
|
||||
- **文本模式 length/过滤且无正文 → `ResultInvalidError`**(原 `TransientError` 重试到耗尽): 不重试、不换源、熔断记成功不计窗口;**不经 `AllSourcesExhausted` 包装**,直接到调用方。原因码见异常消息(`length_without_content` / `filtered_without_content`)。文本模式"只有思考 + stop"维持瞬时(证据收集中)。
|
||||
- **finish_reason 为 `network_error`/`error`**(GLM 等上游自报失败)即使有正文也判瞬时。
|
||||
- **保真模式**: 只有思考/拒答/空白 + 明确 finish(非上游错误)→ 原样交回;length 截断的半截工具(缺 id/name)→ `ResultInvalidError` `tool_truncated`;无参函数全程只发 `arguments: null`(其余字段齐全)→ `ResultInvalidError` `tool_arguments_null`(确定性方言,交付值不改写)。
|
||||
- 文本模式 `choice.index: null` 视为 0(此前整帧被丢弃);`tool_calls` 中全为 `null` 的元素按 `tool_calls: null` 处理,不产出会被上游拒收的空数组。
|
||||
- **缓存**: 只有自然结束(stop/tool_calls/无 finish 的旧口径)且有正文的结果写入;length/过滤/未登记 finish 值、salvaged、空正文均交付但不缓存,读到此类条目按 miss。未登记 finish 值按源告警一次。
|
||||
- **活性口径增补**: 未知字段的非空字符串片段(如 `reasoning`)算进展,`index/type/id/format` 等标签键不算;`stall_ms` 计量随之覆盖。
|
||||
|
||||
### 新增
|
||||
|
||||
- `LLMResponse` / `TransportResult` 末尾追加 `finish_reason: str | None`、`stream_end: StreamEnd | None`(`done` / `eof_after_finish` / `salvaged`;非流式、缓存命中为 None);包根导出 `StreamEnd`。
|
||||
- 遥测 `llm_calls` 末尾追加可空列 `stream_end`(INSERT 字段 38 → 39,物理列 39 → 40;旧行 NULL 不回填;auto 档幂等补列,manual 档裁剪写入并点名缺列,补列 SQL 由 `telemetry_schema_sql()` 自取)。
|
||||
|
||||
### 破坏性(请先读)
|
||||
|
||||
- **`TelemetryRecorder.record_llm_call` 新增必填 keyword `stream_end`**: 自建 recorder 未跟进会在装配期被形状闸拒绝(`**fields` 形态不受影响)。
|
||||
|
||||
### 提醒
|
||||
|
||||
- 保真模式交付 `finish_reason=length` 的工具调用时 arguments 可能是半截 JSON: **执行工具前先查 `finish_reason`**。
|
||||
- 未知字段合并冲突时会**删除该字段**并按(源, 路径)告警一次: 结果可能缺字段,以告警为准。典型形态: 带 `index` 的数组(如 `reasoning_details`)后续帧元素缺 `index` 即判形态改变,**整个字段被删**。
|
||||
- 诚实边界: 中转在上游出错后主动正常关闭连接,与真完整在传输层不可区分;防线是"finish 必须存在、不属上游错误、且其后有实测 usage"。
|
||||
- 旧版本写入的 salvage/length 文本缓存无法辨认: 受影响集合须在升级后首次读写前更换 namespace/salt(同 1.3.9 提醒)。
|
||||
|
||||
## 1.3.9(2026-10-01)
|
||||
|
||||
- 新增 `chat(response_mode="openai")`，返回 `LLMResponse.completion`：assistant 消息、工具调用、finish_reason、上游 response_id、usage 快照；支持流式聚合及非流式。
|
||||
- 修复 SSE 顶层 error 后接 DONE 被当成功、同帧 content/reasoning_content 丢失；工具实际进展纳入看门狗、首 token 与中段对冲。
|
||||
- 保真仅支持单 choice，拒绝 structured 组合；工具参数逐字拼接，不执行或修复工具；缺 DONE 不允许 salvage。
|
||||
- 保真缓存独立身份并完整回放；缺协议、畸形协议及无正文无工具的坏条目均按 miss 回源。**旧文本缓存可能含曾被吞错的半截结果，受影响集合须在升级首次读写前更换 namespace/salt（含 per-call 覆盖）**，库不会自动辨认旧污染。
|
||||
- 新模式不绕过 managed/raw 冲突校验；raw-only 仍须源级/请求级均无受管意图。`Transport.complete` 新增必填 `response_mode`，自定义实现需适配。
|
||||
- 分发采用 Apache-2.0；README 补充常驻事件循环线程桥接，不新增同步 API。
|
||||
|
||||
## 1.3.8(2026-09-14)
|
||||
|
||||
流式中段沉默的计量与应对(issue #27 / #28):`generation_ms` 口径重定义为**净生成时间**(扣除所有超阈值中段沉默)并配 `stall_ms`/`stall_count` 归因字段与遥测两列;另加一条**默认关闭**的中段沉默对冲(主路首 token 之后相邻增量 chunk 间隔超阈值时,向异源并发再发一次)。两键均不设时行为逐字等于 1.3.7(默认关闭回归门: 既有 unit/contracts 全套件语义断言一行未改)。
|
||||
|
||||
@@ -2,10 +2,12 @@
|
||||
|
||||
> [!URGENT]
|
||||
> **实验室内部通用基础库(生产级、非 MVP、零业务假设)**
|
||||
>
|
||||
> 1. 本项目是被多个科研/生产项目依赖的**库**,不是应用:稳定性、并发性、防御性、可观测与测试不可为"简单"让步(YAGNI 仍适用,但不削减健壮性)。库的 bug 会同时击穿所有下游项目。
|
||||
> 2. 你的所有思考过程和回复必须使用 **简体中文**。
|
||||
|
||||
## 1. 项目元数据
|
||||
|
||||
- **核心目标**: PolyGateway = 统一的大语言模型(LLM/VLM/OCR,音频预留)调度与中转库。治理单位是**一次模型调用**:请求封装、多源多账号、限流、错误分类与重试、熔断、Redis 响应缓存、流式看门狗、遥测(含成本)、结构化输出策略。全组件端口化可插拔。
|
||||
- **架构权威文档**: `research-wiki/ARCHITECTURE.md`(架构单一事实源,含 D1-D14 决策及讨论过程、子系统设计、三项目迁移验收标准;**不受 400 行设计文档限制**,以无歧义传达既有讨论为准绳)。开发顺序见 `research-wiki/ROADMAP.md`;`research-wiki/designs/` 仅存放每次实现具体功能的设计文档。
|
||||
- **参考项目**: `reference/` 下三个项目是本库的需求来源与代码蓝本(**只读,勿改**;M4 起"只读"指工作区文件与 main 检出不变——迁移实施经 `git worktree` 在 `~/Projects/m4-worktrees/` 的 feature 分支进行,worktree 的 git 操作会写 `reference/*/.git` 元数据,属预期);库必须能按 ARCHITECTURE.md §11 被它们迁移接入,否则即边界缺口。
|
||||
@@ -35,11 +37,13 @@ make ci # 只读验证(check + test)
|
||||
> **同一理由适用于长跑命令**: 需要后台跑时(如全套件测试),命令末尾**不得接管道**,否则退出码失真;要判完成用 `wait`/轮询 PID,不要用会匹配到自身的 `pgrep -f "<完整命令串>"`。
|
||||
|
||||
### Phase 1: 规划与设计
|
||||
|
||||
1. 涉及**公共 API、端口签名、架构边界、新子系统**的变更**必须**调用 `brainstorming`(产出 2-3 备选方案+权衡)并经**人类确认**后实施;其余任务自判(判据: 是否改变库对下游的承诺)。动手前查阅 `research-wiki/`(单一事实源)。
|
||||
2. 功能产生运行时数据时**必须**调用 `structured-logging`。
|
||||
3. **里程碑级/跨多文件**功能编码前**必须**调用 `writing-plans`;小改动自判。审核门控: design 走 Claude 自审 → Codex 审 → **人类审**;plan 走 Claude 自审 → Codex 审 → 直接执行。
|
||||
|
||||
### Phase 2: 执行与验证
|
||||
|
||||
1. **测试结果门**: 合并前每个行为变更必须有"先失败后通过"的测试证据(`test-driven-development`);bug 修复必带回归测试;不规定中间怎么走。
|
||||
2. **独立验证**: 里程碑级/跨多文件/合并前**必须**派全新上下文的 verifier subagent(`verification-before-completion`);任何规模的完成声明都必须逐条对应本会话内的工具输出(证据化声明,禁止虚报)。
|
||||
3. **反 gold-plating**: 不做任务外的重构、抽象与"顺手清理"。
|
||||
@@ -47,6 +51,7 @@ make ci # 只读验证(check + test)
|
||||
## 4. 核心规则
|
||||
|
||||
### 4.1 核心原则(按优先级)
|
||||
|
||||
- **P1 YAGNI**: 不写当前用不到的代码;但并发控制、防御校验、可观测埋点、错误隔离与测试是"当前需要",不在削减之列。
|
||||
- **P2 高可读性**: 领域术语命名;注释解释"为什么"。
|
||||
- **P3 单一职责**: 一句话说不清职责(需要"和")= 拆分。
|
||||
@@ -58,7 +63,7 @@ make ci # 只读验证(check + test)
|
||||
### 4.2 库铁律(本项目特有,违反即 bug)
|
||||
|
||||
| 铁律 | 内容 |
|
||||
|---|---|
|
||||
| --- | --- |
|
||||
| 零业务假设 | 库内禁止出现任何下游业务领域词汇(视频/文书/超声等)与业务 fixtures;扩展点一律 Protocol |
|
||||
| 纯 asyncio 中立 | 无全局状态、无框架假设、无模块级单例;同一 `GatewayClient` 在 arq worker 与裸脚本中行为一致 |
|
||||
| 取消可穿透 | `asyncio.CancelledError` 永不捕获吞没;重试循环、限流等待、流式读取全部可被取消;in-flight 资源在 finally 释放 |
|
||||
@@ -69,6 +74,7 @@ make ci # 只读验证(check + test)
|
||||
| 无缓存毒化 | 缓存 key 必含 model + messages 摘要 + 命名空间/租户 + salt;多模态 content 先摘要再 hash |
|
||||
|
||||
### 4.3 代码开发规范
|
||||
|
||||
- 模块/类/方法必须有**中文 Docstring**;复杂逻辑用 `# Phase N` 注释组织。
|
||||
- 校验分层: 外部输入校验用显式异常(Python `-O` 移除 assert,禁止 assert 承担生产校验);assert 仅用于内部不变量。
|
||||
- 类名 `PascalCase`,私有前缀 `_`;导入顺序标准库→第三方→项目内。
|
||||
@@ -76,6 +82,7 @@ make ci # 只读验证(check + test)
|
||||
- 不考虑向后兼容,直接修改原文件。**例外**: `LLMResponse` 等已被三项目消费的公共类型,字段只增不删不改名(迁移兼容约束,见 ARCHITECTURE.md §5.1)。
|
||||
|
||||
### 4.4 Git 工作流
|
||||
|
||||
- 一切开发在 feature 分支,严禁直改 main;频繁语义化提交;提交**必须**调用 `commit` skill;大改动前先提交回滚点。
|
||||
|
||||
### 4.4.1 发布流程(每步都是历史欠账换来的,不得跳步)
|
||||
@@ -87,7 +94,7 @@ make ci # 只读验证(check + test)
|
||||
按顺序执行,**构建之前**必须先改完所有文档:
|
||||
|
||||
| # | 动作 | 要点 |
|
||||
|---|---|---|
|
||||
| --- | --- | --- |
|
||||
| 1 | **更新 README** | 打包会把当时的 README 固化进 sdist,**发布后再改就来不及了**(包里那份永远是旧的)。逐项核对: 安装命令的版本约束(`==1.1.*` 这类**极易漏改**,漏了下游就被锁在旧版)、能力表是否覆盖新行为、数字型断言是否仍成立(如遥测字段数,须用 `inspect.signature` 实测而非凭记忆) |
|
||||
| 2 | CHANGELOG 定版 | "未发布" → `## X.Y.Z(日期)` |
|
||||
| 3 | 版本号 | `pyproject.toml` + `src/polygateway/__init__.py` 两处必须一致 |
|
||||
@@ -106,11 +113,13 @@ Gitea 包 registry 是 **owner 级**(`/iomgaa/-/packages/`)不是仓库级;PyPI
|
||||
发布验证补充（2026-09-09 实测）：私有索引不镜像 setuptools，下载 sdist 时 pip 即使带 `--no-deps` 仍可能尝试安装构建依赖；已具备构建工具的 conda 环境可加 `--no-build-isolation`，仍须核对下载来源与散列。包关联 POST 本次返回400，但匿名包页面和认证 GET 包 API 均证实已关联目标仓库；**400本身不算成功，也不能直接推断已关联**，必须读取实际 `repository.full_name` 与页面链接。包 API 可能要求认证（匿名401），页面仍应匿名亲查；不要为重试关联先解绑现有正确关系。
|
||||
|
||||
### 4.5 配置管理
|
||||
|
||||
- 工程配置走 `pydantic-settings` + `.env`(模板 `.env.example`,敏感项不提交);严禁硬编码默认值;缺失关键配置直接报错。
|
||||
- 多源命名约定 `{SCOPE}__{PROVIDER}__{N}__{FIELD}`;韧性参数键名沿用三项目习惯(`LLM_TIMEOUT` 等),降低迁移成本。
|
||||
- 装配只有两条路: `GatewayClient.from_env()`/`from_settings()`(工厂)或构造函数全量注入(测试/高级);库内部任何组件不得自读环境变量。
|
||||
|
||||
### 4.6 测试组织
|
||||
|
||||
- `tests/{unit,integration,e2e}`;真实场景优先(录制的真实网关响应二次构造优于凭空 mock)。
|
||||
- 覆盖率目标 80%;并发/韧性行为是一等测试对象: 重试穿透取消、熔断开路半开、限流结算退款、Redis 掉线降级方向、缓存 key 隔离。
|
||||
- Redis 相关测试用真实 Redis(integration),不 mock Lua 行为;限流契约测试随实现一起交付(参考 CHSAnalyzer `tests/contracts_limiter.py`)。
|
||||
@@ -140,7 +149,7 @@ project_root/
|
||||
## 6. 上下文导航
|
||||
|
||||
| 需求 | 路径 |
|
||||
|---|---|
|
||||
| --- | --- |
|
||||
| 架构全貌: 决策 D1-D14 及讨论过程、端口清单、错误分类、子系统设计、迁移验收 | `research-wiki/ARCHITECTURE.md`(单一事实源) |
|
||||
| 开发顺序与里程碑状态 | `research-wiki/ROADMAP.md`(活文档,随进度更新) |
|
||||
| 三项目迁移文档(ARCHITECTURE §11 的展开,库设计的常驻约束) | `research-wiki/migrations/`(govdoc-saas / video-tree-trm5 / chsanalyzer) |
|
||||
@@ -154,6 +163,7 @@ project_root/
|
||||
| 第一次抽库尝试(教训与蓝本) | `reference/GovDoc-SaaS/packages/docagent-core/` |
|
||||
|
||||
## 7. 输出规范
|
||||
|
||||
- 所有输出**中文**;文档优先表格/伪代码/Mermaid;禁止超 15 行代码块入文档、禁止连续超 5 条碎片列点;设计 ≤400 行、计划 ≤1000 行、报告 ≤300 行。
|
||||
- **例外**: `research-wiki/ARCHITECTURE.md` 不受行数限制——它的准绳是"后来的 AI/人类无需还原原始讨论即可准确理解全部决策及理由",宁详勿略(详细 ≠ 琐碎:记录论证与取舍,不堆砌实现细节)。
|
||||
|
||||
@@ -163,7 +173,7 @@ project_root/
|
||||
> **Skill 的 description 即触发边界。** 下表标注 **MANDATORY** 的情形是硬门(设计人类门、合并前测试证据门、合并前独立验证门、commit 格式),不得跳过;其余情形按 description 边界自判——自判看任务实质(规模/风险/是否触及公共承诺),不是省事。任何 skill 流程不得引入任务外的重构或抽象。优先级: 用户显式指令 > Skill 详细流程 > 本文件宏观规则。
|
||||
|
||||
| Skill | 触发边界 |
|
||||
|-------|---------|
|
||||
| ------- | --------- |
|
||||
| `brainstorming` | **MANDATORY**: 公共 API/端口签名/架构边界/新子系统变更;其余自判 |
|
||||
| `writing-plans` | **MANDATORY**: 里程碑级/跨多文件功能;小改动自判 |
|
||||
| `test-driven-development`(测试结果门) | **MANDATORY**: 合并前——行为变更须有先失败后通过的测试证据 |
|
||||
|
||||
@@ -0,0 +1,202 @@
|
||||
|
||||
Apache License
|
||||
Version 2.0, January 2004
|
||||
http://www.apache.org/licenses/
|
||||
|
||||
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
||||
|
||||
1. Definitions.
|
||||
|
||||
"License" shall mean the terms and conditions for use, reproduction,
|
||||
and distribution as defined by Sections 1 through 9 of this document.
|
||||
|
||||
"Licensor" shall mean the copyright owner or entity authorized by
|
||||
the copyright owner that is granting the License.
|
||||
|
||||
"Legal Entity" shall mean the union of the acting entity and all
|
||||
other entities that control, are controlled by, or are under common
|
||||
control with that entity. For the purposes of this definition,
|
||||
"control" means (i) the power, direct or indirect, to cause the
|
||||
direction or management of such entity, whether by contract or
|
||||
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
||||
outstanding shares, or (iii) beneficial ownership of such entity.
|
||||
|
||||
"You" (or "Your") shall mean an individual or Legal Entity
|
||||
exercising permissions granted by this License.
|
||||
|
||||
"Source" form shall mean the preferred form for making modifications,
|
||||
including but not limited to software source code, documentation
|
||||
source, and configuration files.
|
||||
|
||||
"Object" form shall mean any form resulting from mechanical
|
||||
transformation or translation of a Source form, including but
|
||||
not limited to compiled object code, generated documentation,
|
||||
and conversions to other media types.
|
||||
|
||||
"Work" shall mean the work of authorship, whether in Source or
|
||||
Object form, made available under the License, as indicated by a
|
||||
copyright notice that is included in or attached to the work
|
||||
(an example is provided in the Appendix below).
|
||||
|
||||
"Derivative Works" shall mean any work, whether in Source or Object
|
||||
form, that is based on (or derived from) the Work and for which the
|
||||
editorial revisions, annotations, elaborations, or other modifications
|
||||
represent, as a whole, an original work of authorship. For the purposes
|
||||
of this License, Derivative Works shall not include works that remain
|
||||
separable from, or merely link (or bind by name) to the interfaces of,
|
||||
the Work and Derivative Works thereof.
|
||||
|
||||
"Contribution" shall mean any work of authorship, including
|
||||
the original version of the Work and any modifications or additions
|
||||
to that Work or Derivative Works thereof, that is intentionally
|
||||
submitted to Licensor for inclusion in the Work by the copyright owner
|
||||
or by an individual or Legal Entity authorized to submit on behalf of
|
||||
the copyright owner. For the purposes of this definition, "submitted"
|
||||
means any form of electronic, verbal, or written communication sent
|
||||
to the Licensor or its representatives, including but not limited to
|
||||
communication on electronic mailing lists, source code control systems,
|
||||
and issue tracking systems that are managed by, or on behalf of, the
|
||||
Licensor for the purpose of discussing and improving the Work, but
|
||||
excluding communication that is conspicuously marked or otherwise
|
||||
designated in writing by the copyright owner as "Not a Contribution."
|
||||
|
||||
"Contributor" shall mean Licensor and any individual or Legal Entity
|
||||
on behalf of whom a Contribution has been received by Licensor and
|
||||
subsequently incorporated within the Work.
|
||||
|
||||
2. Grant of Copyright License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
copyright license to reproduce, prepare Derivative Works of,
|
||||
publicly display, publicly perform, sublicense, and distribute the
|
||||
Work and such Derivative Works in Source or Object form.
|
||||
|
||||
3. Grant of Patent License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
(except as stated in this section) patent license to make, have made,
|
||||
use, offer to sell, sell, import, and otherwise transfer the Work,
|
||||
where such license applies only to those patent claims licensable
|
||||
by such Contributor that are necessarily infringed by their
|
||||
Contribution(s) alone or by combination of their Contribution(s)
|
||||
with the Work to which such Contribution(s) was submitted. If You
|
||||
institute patent litigation against any entity (including a
|
||||
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
||||
or a Contribution incorporated within the Work constitutes direct
|
||||
or contributory patent infringement, then any patent licenses
|
||||
granted to You under this License for that Work shall terminate
|
||||
as of the date such litigation is filed.
|
||||
|
||||
4. Redistribution. You may reproduce and distribute copies of the
|
||||
Work or Derivative Works thereof in any medium, with or without
|
||||
modifications, and in Source or Object form, provided that You
|
||||
meet the following conditions:
|
||||
|
||||
(a) You must give any other recipients of the Work or
|
||||
Derivative Works a copy of this License; and
|
||||
|
||||
(b) You must cause any modified files to carry prominent notices
|
||||
stating that You changed the files; and
|
||||
|
||||
(c) You must retain, in the Source form of any Derivative Works
|
||||
that You distribute, all copyright, patent, trademark, and
|
||||
attribution notices from the Source form of the Work,
|
||||
excluding those notices that do not pertain to any part of
|
||||
the Derivative Works; and
|
||||
|
||||
(d) If the Work includes a "NOTICE" text file as part of its
|
||||
distribution, then any Derivative Works that You distribute must
|
||||
include a readable copy of the attribution notices contained
|
||||
within such NOTICE file, excluding those notices that do not
|
||||
pertain to any part of the Derivative Works, in at least one
|
||||
of the following places: within a NOTICE text file distributed
|
||||
as part of the Derivative Works; within the Source form or
|
||||
documentation, if provided along with the Derivative Works; or,
|
||||
within a display generated by the Derivative Works, if and
|
||||
wherever such third-party notices normally appear. The contents
|
||||
of the NOTICE file are for informational purposes only and
|
||||
do not modify the License. You may add Your own attribution
|
||||
notices within Derivative Works that You distribute, alongside
|
||||
or as an addendum to the NOTICE text from the Work, provided
|
||||
that such additional attribution notices cannot be construed
|
||||
as modifying the License.
|
||||
|
||||
You may add Your own copyright statement to Your modifications and
|
||||
may provide additional or different license terms and conditions
|
||||
for use, reproduction, or distribution of Your modifications, or
|
||||
for any such Derivative Works as a whole, provided Your use,
|
||||
reproduction, and distribution of the Work otherwise complies with
|
||||
the conditions stated in this License.
|
||||
|
||||
5. Submission of Contributions. Unless You explicitly state otherwise,
|
||||
any Contribution intentionally submitted for inclusion in the Work
|
||||
by You to the Licensor shall be under the terms and conditions of
|
||||
this License, without any additional terms or conditions.
|
||||
Notwithstanding the above, nothing herein shall supersede or modify
|
||||
the terms of any separate license agreement you may have executed
|
||||
with Licensor regarding such Contributions.
|
||||
|
||||
6. Trademarks. This License does not grant permission to use the trade
|
||||
names, trademarks, service marks, or product names of the Licensor,
|
||||
except as required for reasonable and customary use in describing the
|
||||
origin of the Work and reproducing the content of the NOTICE file.
|
||||
|
||||
7. Disclaimer of Warranty. Unless required by applicable law or
|
||||
agreed to in writing, Licensor provides the Work (and each
|
||||
Contributor provides its Contributions) on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
||||
implied, including, without limitation, any warranties or conditions
|
||||
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
||||
PARTICULAR PURPOSE. You are solely responsible for determining the
|
||||
appropriateness of using or redistributing the Work and assume any
|
||||
risks associated with Your exercise of permissions under this License.
|
||||
|
||||
8. Limitation of Liability. In no event and under no legal theory,
|
||||
whether in tort (including negligence), contract, or otherwise,
|
||||
unless required by applicable law (such as deliberate and grossly
|
||||
negligent acts) or agreed to in writing, shall any Contributor be
|
||||
liable to You for damages, including any direct, indirect, special,
|
||||
incidental, or consequential damages of any character arising as a
|
||||
result of this License or out of the use or inability to use the
|
||||
Work (including but not limited to damages for loss of goodwill,
|
||||
work stoppage, computer failure or malfunction, or any and all
|
||||
other commercial damages or losses), even if such Contributor
|
||||
has been advised of the possibility of such damages.
|
||||
|
||||
9. Accepting Warranty or Additional Liability. While redistributing
|
||||
the Work or Derivative Works thereof, You may choose to offer,
|
||||
and charge a fee for, acceptance of support, warranty, indemnity,
|
||||
or other liability obligations and/or rights consistent with this
|
||||
License. However, in accepting such obligations, You may act only
|
||||
on Your own behalf and on Your sole responsibility, not on behalf
|
||||
of any other Contributor, and only if You agree to indemnify,
|
||||
defend, and hold each Contributor harmless for any liability
|
||||
incurred by, or claims asserted against, such Contributor by reason
|
||||
of your accepting any such warranty or additional liability.
|
||||
|
||||
END OF TERMS AND CONDITIONS
|
||||
|
||||
APPENDIX: How to apply the Apache License to your work.
|
||||
|
||||
To apply the Apache License to your work, attach the following
|
||||
boilerplate notice, with the fields enclosed by brackets "[]"
|
||||
replaced with your own identifying information. (Don't include
|
||||
the brackets!) The text should be enclosed in the appropriate
|
||||
comment syntax for the file format. We also recommend that a
|
||||
file or class name and description of purpose be included on the
|
||||
same "printed page" as the copyright notice for easier
|
||||
identification within third-party archives.
|
||||
|
||||
Copyright [yyyy] [name of copyright owner]
|
||||
|
||||
Licensed under the Apache License, Version 2.0 (the "License");
|
||||
you may not use this file except in compliance with the License.
|
||||
You may obtain a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
See the License for the specific language governing permissions and
|
||||
limitations under the License.
|
||||
@@ -19,11 +19,13 @@
|
||||
| 调用期限 | 一次逻辑调用可选一条**墙钟硬边界**(`{SCOPE}__CALL_DEADLINE_S` 或 `chat(call_deadline_s=...)`,缺省不启用):治理的是**等待**——重试退避、配额轮询、熔断冷却、结构化重问与 embedding 分批共享同一份期限。三条须知:①**返回时刻 = 期限 + 清理耗时**(遥测/结算/缓存收尾在 `finally` 里跑完,允许超期;实测构造达期限的 5–7 倍),库只承诺切断等待、不给返回上界;②**到期 ≠ 未产出、≠ 未计费**,上游可能已算完并计费;③**不配置即逐字保持 1.3.5 语义**(纯 429 序列仍可能长等、有限大 `Retry-After` 仍照睡)。到期抛 `CallDeadlineExceeded`,**不属四分类、不属 `GatewayUnavailableError` 族** |
|
||||
| 长尾对冲 | **默认关闭**的可选加速(`{SCOPE}__HEDGE__AFTER_S`,仅 chat):一次尝试挂起超阈值时向**异源**并发再发一次,先回者赢、输家取消。流式以「首 token 未至」为触发判据(不误杀慢生成),非流式只有纯总时长阈值;对冲走完整限流/熔断准入,拿不到配额静默放弃。成本须知:开启即用配额换延迟(触发窗口内 in-flight 翻倍),输家取消按 est 保留预扣且**可能已被上游计费**(取消止不住上游);输家不喂熔断,遥测 attempt 行标 `error="hedge_cancelled"` 可按 `logical_call_id` join 对账;两路皆败只计一次重试预算;与 `call_deadline_s` 正交组合(装配守卫强制对冲阈值 < 期限)
|
||||
| 中段沉默对冲(可选,超业界现状能力) | **默认关闭**(`{SCOPE}__HEDGE__STALL_AFTER_S`,仅流式 chat):主路**首 token 之后**相邻增量 chunk 沉默超阈值时向异源并发再发一次,与首 token 对冲 `HEDGE__AFTER_S` **独立生效**、可独设可组合;仅设它且请求非流式 → 逐字走单路(中段沉默无非流式概念)。**诚实标注:中段沉默触发并发副本在主流网关/库中无公开先例**(业界收敛为看门狗掐流重试)。成本须知:下游实测沉默 >20s 占 19.0%,触发率远高于首 token 对冲,开启即用配额换延迟,输家可能已被上游计费;看门狗掐死**喂**熔断而对冲输家取消**不喂**(不对称声明),详见[1.3.8 生成时间口径与中段沉默对冲](#138-生成时间口径与中段沉默对冲) |
|
||||
| OpenAI 消息保真(1.3.9) | `chat(response_mode="openai")` 返回完整 assistant 消息/工具调用、finish_reason、上游 ID 与 usage；单 choice，复用治理，不执行工具；默认仍为文本模式 |
|
||||
| 完成判定(1.3.10) | 以上游 `finish_reason` 为准判定"生成结束、结果可交付":缺 `[DONE]` 但 finish 与其后的实测 usage 齐全即完整(两模式);length/过滤等确定性结局不再被当瞬时错误重试;未知/`null` 字段不再判失败;`LLMResponse.finish_reason` / `stream_end` 给出结束原因与方式,详见[1.3.10 统一完成判定](#1310-统一完成判定) |
|
||||
| 响应缓存 | Redis/内存;key 含 model + messages 摘要 + namespace(缓存隔离单位)+ salt + 采样参数 + 请求级推理档位(同 messages 跑 low 与 max 不互相命中),多模态 content 先摘要再 hash(防毒化);可 per-call 绕过(科研重采样) |
|
||||
| 流式看门狗 | TTFT / inter-token / 总超时三层活性;thinking token 刷活性不计结果;截断流(缺 `[DONE]`)判瞬时不入缓存 |
|
||||
| 流式看门狗 | TTFT / inter-token / 总超时三层活性;thinking token(含 `reasoning` 别名)刷活性不计结果;截断流(无 `[DONE]` 且无 finish+其后实测 usage)默认判瞬时(`MISSING_DONE=salvage` 的文本打捞结果交付但不入缓存) |
|
||||
| 推理可观测性 | "这次到底推理没推理"由多信号裁定(推理正文压倒 usage 明细),三态落在 `LLMResponse.thinking_observation`:`observed` / `absent` / `unknown`——**`unknown` 是"本次判不出",不是"没推理"**;本次实发档位与实测观测矛盾时按 `(源, 模型, 生效档位)` 各告警一次(能力表过期、开启未生效、注入了却观测不到;同一模型的 low 与 max 是两个独立的矛盾,不共用节流键);裁定结果随遥测落库 |
|
||||
| 推理档位 | 推理是**八档**(`none`/`auto`/`minimal`/`low`/`medium`/`high`/`xhigh`/`max`)而非开关:源级 `REASONING_EFFORT` + 请求级 `chat(reasoning_effort=...)`,`ENABLE_THINKING` 保留为语法糖;库带 24 条能力表(逐条 evidence 自报实测/文档推定),档位打空**默认报错并给出该模型最省的可用档与该配的键**,要静默映射需显式配 `EFFORT_FALLBACK=nearest`;实发档随 `LLMResponse.applied_effort` 与遥测落库 |
|
||||
| 遥测与成本 | 每次调用(含缓存命中与失败)必录 38 字段;三类行(`event_kind` = `attempt` / `cache_hit` / `terminal_failure`)加逐源诊断列(`http_status_code` / `error_type` / `cause_type` / `error_body`);SQLite / Postgres 后端(表已存在时**不需要** schema 建表权限,最小权限账号可直接用);按价格表折算成本落库(注意 `LLMResponse.cost` 本身恒为 `None`,成本只进遥测);多模态内容摘要落库不存原图 |
|
||||
| 遥测与成本 | 每次调用(含缓存命中与失败)必录 39 字段;三类行(`event_kind` = `attempt` / `cache_hit` / `terminal_failure`)加逐源诊断列(`http_status_code` / `error_type` / `cause_type` / `error_body`);SQLite / Postgres 后端(表已存在时**不需要** schema 建表权限,最小权限账号可直接用);按价格表折算成本落库(注意 `LLMResponse.cost` 本身恒为 `None`,成本只进遥测);多模态内容摘要落库不存原图 |
|
||||
| 逻辑调用统计 | 治理单位是**一次逻辑调用**而非一次尝试:四种响应(chat / embedding / OCR 两种)带 `call_stats`(`logical_call_id` / `attempts` / `total_latency_ms`,及生成时间 `generation_ms`——**1.3.8 起为净口径**:赢家那次 transport 调用墙钟 − Σ超阈值中段沉默,仍含 TTFT 与尾部,排除准入排队/退避/触发前等待;1.3.7 的墙钟值由 `generation_ms + stall_ms` 还原——与沉默归因 `stall_ms` / `stall_count`(成对报告,None = 无沉默观测)、对冲计数 `hedges` / `hedge_won`),重试、换源、结构化重问、embedding 分批共享同一逻辑 ID;每次**领域失败**另落一条 `terminal_failure` 行,失败调用数从此是一条 `WHERE event_kind = 'terminal_failure'`,详见[1.3.5 逻辑调用统计与失败诊断](#135-逻辑调用统计与失败诊断)与[1.3.8 生成时间口径与中段沉默对冲](#138-生成时间口径与中段沉默对冲) |
|
||||
| 遥测的资源与降级 | Postgres 池**闲时占 0 条连接**、忙时上限可配(`PGW_TELEMETRY_PG_POOL_MAX`,缺省 4),每次写入有硬预算(`PGW_TELEMETRY_PG_WRITE_TIMEOUT_S`,缺省 5s);后端不可用是**可恢复的降级**(冷却 60s 后自动重试,DBA 建完表/放开权限即自愈),永久失能只留给 DSN 本身写错;降级状态可编程查询——`client.telemetry_status` 给出 `degraded`/`fatal`/`reason`/`dropped_rows` 等只读快照,不必再靠人工对账。**对账要同时看 `degraded` 与 `dropped_rows`**: 池饱和超预算丢的行走行级丢弃,`degraded` 保持 `False`(后端没挂,是本进程并发超了),只按 `degraded` 告警会看不见这一类丢行——而它恰是 `pool_max` 配小了的唯一信号 |
|
||||
| 调用方维度 | 每次调用可带 `tenant_id`(遥测表的真实列,可挂 RLS、可建复合索引)与 `meta`(≤16 个自定义 KV);四个公共方法全覆盖,校验超限即报错;**库只交付列,不启用 RLS、不建索引** |
|
||||
@@ -124,7 +126,7 @@ stats.total_latency_ms # 含缓存 IO、退避、准入等待、重
|
||||
| 定义 | **净生成时间** = 赢家那次 transport 调用的墙钟 − Σ(所有 > `STALL_THRESHOLD_MS`(缺省 1000ms)的相邻增量 chunk 沉默);仍**排除**准入排队/退避/对冲触发前等待(同 1.3.7) |
|
||||
| 边界 | 仍含 **TTFT 与尾部**(末 chunk → 流结束归活跃侧,墙钟基底口径的有意选择) |
|
||||
| 还原公式 | **墙钟 = `generation_ms + stall_ms`**(`stall_ms is None` 时墙钟 = `generation_ms`) |
|
||||
| `stall_ms` / `stall_count` | 沉默总额(毫秒)与超阈值相邻间隔个数,**成对报告**(只报净数无法行动);chunk = 任何增量产出(`content` 或 `reasoning_content` 均计),空 chunk / usage 帧 / SSE keepalive 不计时 |
|
||||
| `stall_ms` / `stall_count` | 沉默总额(毫秒)与超阈值相邻间隔个数,**成对报告**(只报净数无法行动);chunk = 任何增量产出(`content`、`reasoning_content`、工具实际增量,1.3.10 起另含未知字段的非空字符串片段如 `reasoning`),空 chunk / usage 帧 / SSE keepalive / 仅标签键(`index`/`type`/`id`/`format`)不计时 |
|
||||
| `stall_ms is None` 分支条件 | 非流式 / 增量 chunk <2 → 两字段 None 且 `generation_ms` **不退减**;None = 「无沉默观测」而非 0,下游预算公式以此为分支条件 |
|
||||
| 与基准口径的区隔 | NVIDIA TTFT/ITL/E2EL 与 vLLM 的基准口径**均不扣除**沉默——扣沉默是本库自造口径,与基准数字比较时不得混用 |
|
||||
|
||||
@@ -137,7 +139,7 @@ stats.total_latency_ms # 含缓存 IO、退避、准入等待、重
|
||||
| `{SCOPE}__STREAM__STALL_THRESHOLD_MS` | 正整数毫秒 | **1000** | 仅改计量口径,不改任何行为;三层调整接口同权(env 键 / `GatewaySettings.stall_threshold_ms` / `GatewayClient(stall_threshold_ms=...)`);无 per-call 覆盖,不做自适应(防与对冲阈值耦出反馈环) |
|
||||
| `{SCOPE}__HEDGE__STALL_AFTER_S` | 有限正数秒 | **未设 = 关闭** | 独立于 `HEDGE__AFTER_S` 生效;守卫: `≥ min(各源 inter_token_timeout_s 或 timeout_s)`(对冲窗永不开)或 `≥ call_deadline_s` → 装配期 **ValueError**,单源 scope → warning;三层调整接口同权(env 键 / `GatewaySettings.hedge_stall_after_s` / `GatewayClient(hedge_stall_after_s=...)`);Embedding/OCR scope 配任一对冲键 → warning 后静默退化 |
|
||||
|
||||
对冲语义(两阶段触发窗/复检防误触发/取消穿透)与成本披露见 [CHANGELOG 未发布段](CHANGELOG.md);运维「挂起率」统计须知不对称:看门狗掐死**喂**熔断失败计数,对冲输家取消**不喂**熔断。
|
||||
对冲语义(两阶段触发窗/复检防误触发/取消穿透)与成本披露见 [CHANGELOG 1.3.8 段](CHANGELOG.md);运维「挂起率」统计须知不对称:看门狗掐死**喂**熔断失败计数,对冲输家取消**不喂**熔断。
|
||||
|
||||
## 安装
|
||||
|
||||
@@ -145,7 +147,7 @@ stats.total_latency_ms # 含缓存 IO、退避、准入等待、重
|
||||
|
||||
```bash
|
||||
pip install --extra-index-url https://gitea.iomgaa.online/api/packages/iomgaa/pypi/simple/ \
|
||||
"polygateway[redis,postgres,structured]>=1.3.8,<2"
|
||||
"polygateway[redis,postgres,structured]>=1.3.10,<2"
|
||||
```
|
||||
|
||||
核心仅依赖 `httpx` + `pydantic`;按需选 extras:
|
||||
@@ -610,3 +612,110 @@ make ci # 只读全量验证
|
||||
## 兼容性承诺
|
||||
|
||||
`LLMResponse` 等被下游消费的公共类型,字段**只增不删不改名**且新增字段必带默认值;`{SCOPE}__{PROVIDER}__{N}__{FIELD}` 与平铺韧性键名(`LLM_TIMEOUT` 等)沿用三项目既有习惯,不做破坏性改名。实验室内部库,随实验室项目需求演进。
|
||||
|
||||
## 1.3.9 OpenAI 工具消息保真（单 choice）
|
||||
|
||||
`chat(..., response_mode="openai")` 仍返回 `LLMResponse`，完整协议结果在
|
||||
`response.completion`：`message`、`finish_reason`、`response_id`、`usage`。
|
||||
`content/thinking` 是旧文本投影（可剥离 think 标签）；回传代理或继续对话应使用
|
||||
completion.message，不能从旧投影重建工具响应。嵌套 JSON 是独立快照但仍可修改。
|
||||
|
||||
```python
|
||||
response = await client.chat(
|
||||
messages,
|
||||
response_mode="openai",
|
||||
overlay={"tools": tools, "tool_choice": "auto"},
|
||||
)
|
||||
completion = response.completion
|
||||
messages.append(completion.message)
|
||||
# 工具执行与 role=tool 结果由调用方添加；库不会执行工具。
|
||||
```
|
||||
|
||||
保真是 JSON 字段和值保真，不是 HTTP 字节透明代理。仅支持单 choice（`n=1`），
|
||||
可含多个并行 function tool_calls；arguments 逐字拼接，不解析、修复或执行。
|
||||
SSE 的 role/content/reasoning_content/tool_calls 按原语义聚合；1.3.10 起 `null` 视为缺省，
|
||||
未知增量字段按流式惯例无损合并（冲突删键并告警，见下节）；
|
||||
非流式保留整个 message 扩展字段，不返回顶层 logprobs/created 等其他字段。
|
||||
上游实际模型仍读 `model_reported`，配置别名是 `model`。
|
||||
|
||||
| 边界 | 行为 |
|
||||
| --- | --- |
|
||||
| 空文本且有完整工具 | 正常成功；不完整工具失败（length 截断的半截工具归 ResultInvalid），其余见 1.3.10 结局表 |
|
||||
| error 帧 | 所有模式立即判失败并走已有重试；后续 DONE 不挽救 |
|
||||
| 缺 DONE | 1.3.10 起 finish + 其后实测 usage + 干净 EOF 即完整；真截断仍不受 salvage 放宽，防截断工具被执行 |
|
||||
| finish_reason=length | 原样返回（含只有思考的回答），不修补参数；**执行工具前先查 finish_reason**，arguments 可能是半截 JSON |
|
||||
| structured | 不可与保真并用；自行传 overlay.response_format 不启用库的修复/重问阶梯 |
|
||||
| raw 推理 | 保真不是校验逃生口；raw-only 要求源 ENABLE_THINKING/REASONING_EFFORT 均未设置，请求档为 None，再通过 overlay.reasoning_effort 传原值 |
|
||||
|
||||
工具实际增量与正文/推理共用首 token、inter-token、stall 对冲及沉默计量；注释、
|
||||
usage、role-only、重复工具身份不算进展。非流式无中段事件，保持纯时长阈值对冲。
|
||||
`Transport.complete` 的自定义实现须接收必填 `response_mode`；不支持保真时明确
|
||||
RequestRejected，不能伪造 completion 或静默退回文本。
|
||||
|
||||
缓存按返回模式隔离；缺协议、畸形协议或无正文无工具的条目按 miss 回源。命中保留历史上游 response_id/usage，生成本次治理 call_id，
|
||||
本次 attempts=0、cost=0。**旧文本缓存可能含修复前 error+DONE 的截断产物**：
|
||||
受影响调用集合须在首次读写前更换从未承载旧语义的 namespace 或 salt，包含工厂、
|
||||
全量注入和 per-call 覆盖，保留租户前缀与 epoch。未迁移仍可能读旧值，库不自动清除。
|
||||
遥测继续单一出口，不新增工具全文列；既有 TEXT_CAP 不覆盖 tool_calls.arguments。
|
||||
|
||||
### 线程模型的异步桥接
|
||||
|
||||
库不新增同步客户端。socketserver 等工作线程应向**一个常驻事件循环线程**提交：
|
||||
client 必须在该 loop 内创建、使用并关闭，不能每请求 asyncio.run 或跨 loop 共用
|
||||
httpx/Redis 组件。下例的 loop 和 client 已由宿主完成初始化：
|
||||
|
||||
```python
|
||||
future = asyncio.run_coroutine_threadsafe(
|
||||
client.chat(messages, response_mode="openai", overlay=overlay), loop
|
||||
)
|
||||
try:
|
||||
response = future.result(timeout=timeout_s)
|
||||
except TimeoutError:
|
||||
future.cancel() # 断连也应取消；取消不等于上游未计费。
|
||||
raise
|
||||
```
|
||||
|
||||
应用退出时先停止接单、取消/等待在途调用，在同一个 loop 中 await client.aclose()，
|
||||
再停 loop 并 join 线程；注入组件仍由所有者关闭。不要从 loop 本身阻塞调用 future.result。
|
||||
|
||||
## 1.3.10 统一完成判定
|
||||
|
||||
#30/#31 同根: 1.3.9 以 `[DONE]` 存在、正文非空、字段白名单作为成功判据,上游的正常结局
|
||||
(不发 `[DONE]`、只有思考的 length 截断、`refusal: null`)被当瞬时错误重试到耗尽。1.3.10
|
||||
改以上游 `finish_reason` 与传输完整性为准,流式/非流式/缓存四处共用一份判定。
|
||||
|
||||
| 结束方式(`stream_end`) | 条件 |
|
||||
| --- | --- |
|
||||
| `done` | 收到 `[DONE]` |
|
||||
| `eof_after_finish` | 未发 `[DONE]`,但 finish 已到、其同帧或之后收到的 usage 为实测,连接干净关闭(用量记 measured) |
|
||||
| `salvaged` | 文本模式 `MISSING_DONE=salvage` 打捞的截断结果(用量降 estimated,**不写缓存**) |
|
||||
| `None` | 非流式 / 缓存命中 / 失败行 |
|
||||
|
||||
| 结局(首个匹配行生效) | `openai` 模式 | `text` 模式 |
|
||||
| --- | --- | --- |
|
||||
| finish 为 `network_error`/`error`(上游自报失败) | 瞬时错误 | 瞬时错误 |
|
||||
| 工具快照不成立 | length → `ResultInvalidError`;其余瞬时 | — |
|
||||
| 无任何产物 + length/过滤 | 原样交回 | `ResultInvalidError`(不重试、不计熔断) |
|
||||
| 无任何产物 + 其余(零增量抖动) | 瞬时错误 `empty_completion` | 同左 |
|
||||
| 有正文 | 交付 | 交付 |
|
||||
| 只有思考/拒答/空白 + length/过滤 | 原样交回 | `ResultInvalidError` |
|
||||
| 只有思考/拒答/空白 + stop 等 | 原样交回 | 瞬时错误(证据收集中) |
|
||||
| 只有思考/拒答/空白 + 无 finish | 瞬时错误 | 同左 |
|
||||
|
||||
`ResultInvalidError` 不经 `AllSourcesExhausted` 包装,直接到调用方;原因码在异常消息里
|
||||
(`length_without_content` / `filtered_without_content` / `tool_truncated` 等,遥测 `error`
|
||||
列可检索)。只有自然结束(stop/tool_calls/function_call,或未上报 finish 的旧口径)且投影正文非空
|
||||
(或工具完整)的结果才写缓存;未登记的 finish 值按正常交付、不缓存并告警一次。无参函数只发
|
||||
`arguments: null` 的工具判 `ResultInvalidError`(`tool_arguments_null`,确定性方言,不改写不重试)。文本模式 `thinking` 在无非空 `reasoning_content` 时取
|
||||
`reasoning`(vLLM/OpenRouter 新名)。保真模式未知字段:字符串拼接、对象递归、带 `index` 的
|
||||
数组按 index 合并、`index/type/id/format` 同值幂等;冲突时**删除该字段**并按(源, 路径)
|
||||
告警一次——结果可能缺字段,以告警为准。诚实边界:中转在上游出错后主动正常关闭连接与真
|
||||
完整在传输层不可区分,防线是"finish 必须存在、不属上游错误、且其后有实测 usage"。
|
||||
|
||||
遥测 `llm_calls` 追加可空列 `stream_end`;`TelemetryRecorder.record_llm_call` 新增必填
|
||||
keyword `stream_end`(**自建 recorder 须跟进,否则装配期被形状闸拒绝**)。
|
||||
|
||||
## 许可证
|
||||
|
||||
PolyGateway 使用 [Apache License 2.0](LICENSE)。内部移植代码的原创 owner 已明确授权；
|
||||
分发范围不包含 `reference/` 外部参考仓。
|
||||
|
||||
+2
-1
@@ -4,11 +4,12 @@ build-backend = "setuptools.build_meta"
|
||||
|
||||
[project]
|
||||
name = "polygateway"
|
||||
version = "1.3.8"
|
||||
version = "1.3.10"
|
||||
description = "PolyGateway：实验室统一的大语言模型（LLM/VLM/OCR）调度与中转库——多源、限流、重试、熔断、缓存、遥测"
|
||||
# registry 包页面的正文只认这一项:缺了页面就是一片空白(1.1.2 的教训,twine 会警告
|
||||
# long_description missing 但不阻塞上传)。README 在打包时被固化进产物,发布后再改无效。
|
||||
readme = "README.md"
|
||||
license = {file = "LICENSE"}
|
||||
requires-python = ">=3.12"
|
||||
dependencies = [
|
||||
"httpx>=0.27",
|
||||
|
||||
@@ -413,7 +413,7 @@ flowchart TB
|
||||
| 值 | 含义 | 生产者 | cost |
|
||||
| --- | --- | --- | --- |
|
||||
| `measured` | usage 帧完整可信 | 正常路径;OCR 成功行(0 token 是**事实**而非未知) | 按 token 换算 |
|
||||
| `estimated` | 有实测数字但可信度降级 | 打捞路径(收到 usage 帧但流被截断,§7.1) | 按 token 换算 |
|
||||
| `estimated` | 有实测数字但可信度降级 | 打捞路径(收到 usage 帧但流被截断,§7.1;1.3.10 起即 `stream_end="salvaged"`) | 按 token 换算 |
|
||||
| `unavailable` | 用量信息不可得 | usage 帧缺失、失败尝试、终态失败 | **NULL** |
|
||||
|
||||
值域在 `types.py` 以模块级 frozenset 常量 `USAGE_SOURCES` 落地,**仅约束库内生产侧**(所有写入点从该常量取值),不在 `LLMResponse`/`Usage`/`TransportResult` 上加 `__post_init__` 值域校验——它们是运行时构造点,裸 `ValueError` 不属 §6 四分类、`RetryMW` 不捕会逃出 `chat()`;且 `LLMResponse` 是三项目已消费的公共类型,新增运行时校验属下游可见行为变更。历史库里既有的 `estimated` 行在新值域中依然合法可读。
|
||||
@@ -470,7 +470,9 @@ flowchart TB
|
||||
| HTTP 429(body 无 insufficient_quota)、500/502/503/504 | `TransientError`(携 `Retry-After` 解析值,仅支持秒数形态) |
|
||||
| HTTP 429 + body 含 insufficient_quota、401、403 | `SourceDeadError` |
|
||||
| HTTP 400 | `RequestRejectedError` |
|
||||
| **空补全**: 200 且流程完整([DONE]/usage 正常)但 content 为空(2026-07-20 M1 验证发现,人类裁决) | `TransientError`(服务抖动,重试/换源;绝不缓存空响应) |
|
||||
| **空补全**: 200 且流程完整([DONE]/usage 正常)但 content 为空(2026-07-20 M1 验证发现,人类裁决) | `TransientError`(服务抖动,重试/换源;绝不缓存空响应)。1.3.10 起仅限**零产物**或无法区分抖动与结局的情形;上游明确的 length/过滤结局见 §15 |
|
||||
| finish_reason 为 `network_error`/`error`(上游自报失败,1.3.10) | `TransientError` |
|
||||
| 文本模式 length/过滤且无正文;保真模式 length 截断的半截工具(1.3.10) | `ResultInvalidError`(确定性结局,不重试、不计熔断) |
|
||||
| 解析层失败(结构化输出/OCR ZIP) | `ResultInvalidError` |
|
||||
|
||||
**响应体留存(2026-08-16,Gitea issue #10;设计 `designs/2026-08-16-issue10-error-body-retention-design.md`)**: 上表每一条 HTTP 翻译**都必须携带响应体摘要**——摘要同时进入异常 message 与 `PolyGatewayError.body_text`(1.2.0 新增基类字段)。两者都要,因为逐次遥测写的是 `str(exc)`,只加字段进不了遥测表,而"事后可查"正是这条要求的目的。摘要口径由 `transports/_http_errors.summarize_body` 单点实现(折叠空白 → 限长 2048 字符 → 超长保留头 1400 + 尾 600 并记省略字数),两个 transport 共用,**不得各写一份**——issue #10 的成因正是"只有 429 那一支用了响应体"。`body_text` 是旁路数据,不参与任何治理判定;`_translate_429` 的类型细分仍解析未截断原文(摘要会破坏 JSON,改用它会让超长 body 的 `insufficient_quota` 退化成普通限速)。
|
||||
@@ -566,7 +568,7 @@ flowchart TB
|
||||
|
||||
### 7.8 遥测与成本
|
||||
|
||||
**必录字段**(继承三项目 15 字段规范;当前 38 个 INSERT 字段,物理表列 39 = 38 + 数据库自填的 `created_at`,两套口径的区分见 `telemetry/schema.py` 模块 docstring): call_id、parent_call_id、session_id、model、provider、source_name、messages(JSON)、response、thinking、prompt_tokens、completion_tokens、usage_source、latency_ms、ttft_ms、max_inter_token_ms、cache_hit、error、**cost**、**cached_prompt_tokens**、**model_reported**、**sampling**、**reasoning_tokens**、**tenant_id**、**meta**、**thinking_observation**、**reasoning_effort**、**scope**、**operation**、**logical_call_id**、**event_kind**、**http_status_code**、**error_type**、**cause_type**、**error_body**、**attempts**、**total_latency_ms**、**stall_ms**、**stall_count**。
|
||||
**必录字段**(继承三项目 15 字段规范;当前 39 个 INSERT 字段,物理表列 40 = 39 + 数据库自填的 `created_at`,两套口径的区分见 `telemetry/schema.py` 模块 docstring): call_id、parent_call_id、session_id、model、provider、source_name、messages(JSON)、response、thinking、prompt_tokens、completion_tokens、usage_source、latency_ms、ttft_ms、max_inter_token_ms、cache_hit、error、**cost**、**cached_prompt_tokens**、**model_reported**、**sampling**、**reasoning_tokens**、**tenant_id**、**meta**、**thinking_observation**、**reasoning_effort**、**scope**、**operation**、**logical_call_id**、**event_kind**、**http_status_code**、**error_type**、**cause_type**、**error_body**、**attempts**、**total_latency_ms**、**stall_ms**、**stall_count**、**stream_end**(1.3.10,§15)。
|
||||
|
||||
**`stall_ms`/`stall_count` 两列(2026-09-11,1.3.8,issue #27,端口 36 → 38)**: 沉默归因进库,口径见 §7.2 净口径段。取 INTEGER 而非 REAL——落库值是 retry 层已取整的 int,与换算唯一处纪律(N8)一致。追加在 `total_latency_ms` 之后,可空无默认、旧行 NULL 不回填;`emit_cache_hit`/`emit_terminal_failure` 与失败/取消 attempt 行恒 NULL(缓存命中与终态行无 transport 观测;被取消的对冲输家无 TransportResult,其 `hedge_cancelled` 行 stall 恒 NULL,存在性由该行表达)。`generation_ms` **仍不进遥测列**(YAGNI)——墙钟由 `generation_ms + stall_ms` 还原。
|
||||
|
||||
@@ -789,3 +791,36 @@ src/polygateway/
|
||||
| Q6 | CHSAnalyzer 的 judge 迁移路径 | **已拍板(2026-07-22 用户)**: M4 实测 judge/core-eval 评估流水线**零调用方、从未接线**(全仓仅自测消费),且实验室网关无 claude 系模型——本轮**豁免不动**,judge.py 原样保留;待评估流水线真正启用时再收编走库(届时裁判模型从网关现有模型选) |
|
||||
| Q4 | conda 环境名 | `PolyGateway` |
|
||||
| Q5 | 本仓库工程脚手架(git init、`.claude/` skills、Makefile、pyproject、import-linter)何时落地 | 本文档终审通过后、M1 编码前一次落地 |
|
||||
|
||||
|
||||
## 14. OpenAI 单 choice 消息保真（2026-10-01，#29 已批准增量）
|
||||
|
||||
本节明确修订 §5/§6.2/§7.1/§7.2/§7.5/§7.6 中原仅文本契约，详细边界见 [设计](designs/2026-10-01-issue29-openai-fidelity-design.md)。不新增 Agent Loop 或第二套治理。
|
||||
|
||||
| 接缝 | 增量契约 |
|
||||
|---|---|
|
||||
| 公共返回 | chat 追加 response_mode=text/openai，默认 text；LLMResponse/TransportResult 末尾追加 completion，内含 assistant message、finish_reason、response_id、usage；旧字段继续文本兼容投影 |
|
||||
| 请求所有权 | messages 字段保真；overlay 仍受 model/messages/stream/stream_options 保护；raw-only 复用既有路径，模式不绕过 managed 校验 |
|
||||
| 协议 | openai 单 choice；工具按 index 排序，name/arguments 逐片拼接；SSE 支持 role/content/reasoning_content/tool_calls，未知增量拒绝；非流式保留消息扩展字段；成功必含 assistant role |
|
||||
| 失败 | 所有 chat 模式 error 帧立即 TransientError；openai 缺 DONE 一律重试、不 salvage；tool-only 成功，纯空/不完整工具失败；text salvage 原语义不变 |
|
||||
| 活性 | 同帧正文/推理/工具实际进展只记一次；role/usage/finish/空帧/重复身份不算；沿既有看门狗、首 token、stall 对冲与唯一取整点 |
|
||||
| 缓存 | 仅 openai key 新增 response_mode 语义维度，默认 text key 不变；完整快照显式重建，缺 completion/role 或无有效正文/工具按 miss（与 transport 共用内核纯值判据，不依赖 transport 实现）；历史上游 id 回放，本次治理 id 重建 |
|
||||
| 迁移 | 旧 text 污染无法自动判断，受影响集合必须迁移 namespace/salt；新模式天然隔离；无新遥测列/表，统一 helper 与取消结算不变 |
|
||||
|
||||
本增量不会执行工具；length 结束原因与参数原样交回，由下游判断可执行性。嵌套 JSON 是独立可变快照，不承诺深冻结。许可已由原创 owner 明确批准 Apache-2.0。
|
||||
|
||||
## 15. 统一完成判定（2026-10-14，#30/#31 已授权增量）
|
||||
|
||||
本节修订 §6.2 空补全行、§7 `usage_source` 映射与 §14 协议/失败/缓存三行，详细边界见 [设计](designs/2026-10-14-issue30-31-completion-verdict-design.md)。
|
||||
|
||||
| 接缝 | 增量契约 |
|
||||
|---|---|
|
||||
| 根因 | 1.3.9 以 `[DONE]` 存在、正文非空、字段白名单判定成功，上游正常结局落 Transient 被重试放大；本版以上游 `finish_reason` 与传输完整性为准 |
|
||||
| 内核 | `types.py` 纯函数 `_stream_is_complete` / `_classify_finish` / `_judge_outcome` / `_is_cacheable`，流式、非流式、缓存读写四处共用；只返回判定值，错误由调用点翻译 |
|
||||
| 流完整性 | `[DONE]` → `done`；无 DONE 但 finish 已到且其同帧或之后的 usage 为实测、干净 EOF → `eof_after_finish`；其余为截断：保真不打捞，文本按 `missing_done` |
|
||||
| 结局 | 首匹配表：上游错误 finish → Transient；坏工具（length → ResultInvalid）；零产物 + length/过滤 → 保真交付、文本 ResultInvalid；零产物其余 → Transient（保 2026-07-20 裁决）；有正文交付；有产物无正文按 finish 分模式 |
|
||||
| 字段 | 五层 null 视缺省；保真未知字段无损合并（字符串拼接、index 数组按 index、标签键幂等），冲突删键 + 有界告警；未知字符串片段计活性 |
|
||||
| 缓存 | 可缓存 ⊂ 可交付：salvaged、无正文、length/过滤/未知 finish 不写，读到即 miss；判定先于命中覆盖 |
|
||||
| 公共面 | `LLMResponse`/`TransportResult` 追加 `finish_reason`、`stream_end`；遥测加 `stream_end` 列，`record_llm_call` 加必填参数 |
|
||||
|
||||
`usage_source` 与 `stream_end` 分工：前者答"账单可信吗"，后者答"内容完整吗"。`eof_after_finish ⇒ measured`；`salvaged ⇒ estimated|unavailable`；`estimated ⇒ salvaged`，逆命题不成立。诚实边界：中转在上游出错后主动正常关闭连接，与真完整在传输层不可区分。
|
||||
|
||||
@@ -13,7 +13,7 @@
|
||||
## 1. 总览与状态
|
||||
|
||||
| 阶段 | 内容 | 接入方 | 状态 |
|
||||
|---|---|---|---|
|
||||
| --- | --- | --- | --- |
|
||||
| P0 奠基 | 调研、ARCHITECTURE.md、CLAUDE.md、skill Fable 5 改造、hooks 硬边界、脚手架(git/pyproject/Makefile/conda 环境/CI 绿) | — | ✅ 完成(2026-07-20) |
|
||||
| M1 核心 | 内核类型 + httpx transport + 治理中间件(内存后端)+ 多源多账号 + 缓存 + SQLite 遥测 + 结构化输出 + from_env | GovDoc、Video-Tree | ✅ 完成(2026-07-20;239 测试全绿、覆盖 92%、真实网关+真实 Redis 验收通过、独立 verifier 问题清零;见 designs/2026-07-20-m1-core-design.md 状态行) |
|
||||
| M2 分布式 | Redis 限流/熔断后端、多源 × Redis 联合验证、背压、Postgres 遥测、成本、Embedding(Q3)、压测 harness | CHSAnalyzer(治理) | ✅ 完成(2026-07-21;契约双后端全绿 + 时间语义真实等待变体 10/10、跨连接联合验证、CHS 对标十项打钩、P3 真实验收 300 次双进程七不变量 PASS、独立 verifier 0 Critical 且 Important 清零;见 designs/2026-07-20-m2-distributed-design.md 与 findings/m2-verifier-fixes.md。压测收官: P5 故障混编 40 次八不变量 PASS,P6 首跑 58.1% 暴露三大治理盲区(findings/2026-07-21-p6-soak-baseline.md)→ **M2.5 治理韧性**六轮迭代(双通道熔断/健康选源/AIMD/429 免预算/健康门槛降权/连败抑制)后同场景 **98.96%**、八不变量全 PASS,验收见 findings/2026-07-21-m25-acceptance.md 与 designs/2026-07-21-m25-resilience-design.md) |
|
||||
@@ -25,7 +25,7 @@
|
||||
**内部开发顺序**(编号即依赖顺序,同号可并行):
|
||||
|
||||
| 步 | 内容 | 顺序理由 |
|
||||
|---|---|---|
|
||||
| --- | --- | --- |
|
||||
| 1 | `types.py` + `errors.py` + `ports.py` 全量设计与冻结 | 原则 2:公共承诺先行;这是 M1 设计文档(人类门)的主体 |
|
||||
| 2a | `streaming.py` 看门狗移植 | 原则 4:纯函数,零依赖,直接移植+补测 |
|
||||
| 2b | `providers.py` 注册表 | 叶子模块;transport 的前置(思考流字段声明;thinking 注入的**决策**已于 issue #16/#17 搬到 `thinking.py`,这里只留形态声明) |
|
||||
@@ -72,9 +72,11 @@
|
||||
|
||||
**已交付增补(2026-09-14)**: 流式中段沉默计量与对冲(issue #27/#28,1.3.8)——`generation_ms` 口径重定义为**净生成时间**(墙钟 − Σ超阈值中段沉默,仍含 TTFT 与尾部;1.3.7 墙钟口径由 `generation_ms + stall_ms` 还原,披露见 CHANGELOG 未发布段),`CallStats` 增 `stall_ms`/`stall_count` 归因字段,遥测表加同两列(INSERT 字段 36→38);`{SCOPE}__HEDGE__STALL_AFTER_S` 中段沉默对冲(独立于 `HEDGE__AFTER_S` 生效、默认关闭;无业界公开先例,超业界现状能力),`{SCOPE}__STREAM__STALL_THRESHOLD_MS` 计量阈值(默认 1000,三层可调)。设计 designs/2026-09-11-streaming-stall-design.md(人类已批准 + 独立审查补遗 B1-B4/N1-N9),实施 plans/2026-09-11-streaming-stall.md,验证 findings/2026-09-11-streaming-stall-validation.md。后续储备:自适应分位阈值(防反馈环,现不做)、流式透传下的 commit 点重审、embedding/OCR 对冲(现不做)。
|
||||
|
||||
**已交付增补(2026-10-15,1.3.10 已发布)**: 统一完成判定(issue #30/#31,1.3.10)——以上游 `finish_reason` 与传输完整性判定流完成与结局,流式/非流式/缓存读写共用内核纯函数;缺 `[DONE]` 但 finish+实测 usage 完整即成功(两模式),文本 length/过滤无正文改 `ResultInvalidError`,保真模式 null/未知字段无损合并;`LLMResponse` 增 `finish_reason`/`stream_end`,遥测加 `stream_end` 列。设计 designs/2026-10-14-issue30-31-completion-verdict-design.md(人类授权 Claude 与独立 subagent 两轮审查后直接执行),实施 plans/2026-10-14-issue30-31-completion-verdict.md。后续储备:文本 n>1 混流修复、文本"只有思考+stop"证据收集。
|
||||
|
||||
## 7. 开放决策依赖
|
||||
|
||||
| 决策 | 阻塞点 | 需拍板时间 |
|
||||
|---|---|---|
|
||||
| --- | --- | --- |
|
||||
| Q1 打包分发(git+ssh vs 内网 index) | 不阻塞开发,阻塞 M4 发布 | M4 前 |
|
||||
| Q3 Embedding 是否纳入 | ~~影响 M2 范围~~ **已拍板纳入 M2**(2026-07-20) | ✅ 已决 |
|
||||
|
||||
@@ -0,0 +1,171 @@
|
||||
---
|
||||
type: design
|
||||
node_id: design:2026-10-01-issue29-openai-fidelity-design
|
||||
title: OpenAI消息保真设计
|
||||
date: 2026-10-01
|
||||
---
|
||||
|
||||
# #29 OpenAI 消息保真设计
|
||||
|
||||
> **修订指针(2026-10-14)**: §4.1"未知 delta 拒绝"、§4.2"reasoning-only 不算成功"与"缺 DONE 一律失败"、§5 活性口径、§6 缓存判据已由 [统一完成判定设计](2026-10-14-issue30-31-completion-verdict-design.md)(1.3.10)修订,以后者为准。
|
||||
|
||||
> 状态：方向已获人类批准；计划独立审查 P1/P2 已修订并实施，首轮独立代码审查发现的缓存空产物及测试双向依赖已修复，等待父会话最终复核；按人类最终指定准备 1.3.9，取代未发布的 1.4.0；尚未发布。
|
||||
> 基线：`0e29deac1a72bfee348ed2f8061ea2c33be217e8` / 1.3.8；日期：2026-10-01。
|
||||
> 需求：[issue #29](https://gitea.iomgaa.online/iomgaa/PolyGateway/issues/29)。
|
||||
> 权威约束：ARCHITECTURE §2.3、§5、§6、§7.1–7.8；实现前按本文修订对应架构段落。
|
||||
|
||||
## 1. 批准记录与范围
|
||||
|
||||
用户已明确同意：现有 `chat()` 增加显式 OpenAI 保真模式，`LLMResponse` 增加完整协议结果，复用治理链，修复工具聚合、活性、error 帧和缓存隔离；首版单 choice、不执行工具、不增加 Agent Loop。用户随后确认内部移植代码均为其原创且本人 owner，并明确授权 PolyGateway 使用 Apache-2.0；dissect3 也是其项目。以上不再重复请示。
|
||||
|
||||
Codex 不可用，人类已授权原生 subagent 替代独立审查。具体 API 拼写与防御约束由本设计落实，经独立审查后实施；若审查要求改变已批准边界，才重新讨论。设计阶段已结束；实现验证记录见计划末尾，独立代码审查/发布前禁止宣称 issue 已解决。
|
||||
|
||||
“保真”是受支持 OpenAI Chat Completions 消息字段和值保真，不是 HTTP 字节级透明代理，不覆盖任意供应商增量方言。model、stream、stream_options 仍由库控制；没有逐块回调、工具执行、同步客户端、美元预算或失败用量取证新功能。
|
||||
|
||||
## 2. 源码核验与方案比较
|
||||
|
||||
| 已核实接缝 | 现状与修复目标 |
|
||||
| --- | --- |
|
||||
| `transports/openai_compat.py::_sse_delta` | 只读首 choice；content 早返回丢同帧 reasoning；忽略 tool_calls/error |
|
||||
| `_complete_stream` / `_complete_once` | 纯文本判空；raw 只存 usage；需新增协议快照与 tool-only 成功语义 |
|
||||
| `client.py::chat` / `_build_payload` | messages 已直传，overlay 已合并，无需白名单重写 |
|
||||
| `thinking.py::validate_thinking_raw` | raw-only 已支持；受管与 raw 冲突是既定保护，不得绕过 |
|
||||
| `middleware/retry.py::_build_response` | 唯一响应构造出口，新增字段在此搬运，不新增治理循环 |
|
||||
| `middleware/cache.py` | 已有完整消息/overlay 身份，但嵌套新类型需重建、模式需隔离 |
|
||||
|
||||
| 方案 | 优势 | 代价/结论 |
|
||||
| --- | --- | --- |
|
||||
| A：chat 显式模式 + LLMResponse 内嵌协议结果 | 生命周期、取消、缓存、遥测和对冲单一实现；兼容旧投影 | 需定义组合约束和缓存身份；**选定** |
|
||||
| B：新增 chat_completion 入口，复用私有核心 | 接口像 OpenAI | 重复公共签名、输入校验和终态封装，收益不足，否决 |
|
||||
| C：独立 SDK 客户端或代理自聚合 | 局部改动直观 | 无法自动解决响应上浮/缓存/线路错误，复制治理，否决 |
|
||||
|
||||
## 3. 公共契约
|
||||
|
||||
### 3.1 模式与类型
|
||||
|
||||
在 `types.py` 定义并从包根导出 `ResponseMode` 和 `OpenAIChatCompletion`：
|
||||
|
||||
```python
|
||||
ResponseMode = Literal["text", "openai"]
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class OpenAIChatCompletion:
|
||||
"""单 choice 的协议消息快照；嵌套 JSON 并非深度不可变。"""
|
||||
message: dict[str, Any]
|
||||
finish_reason: str | None
|
||||
response_id: str | None
|
||||
usage: dict[str, Any] | None
|
||||
```
|
||||
|
||||
`GatewayClient.chat` 末尾追加 keyword-only `response_mode: ResponseMode = "text"`；`ChatRequest` 末尾同字段同默认。`TransportResult`、`LLMResponse` 末尾追加 `completion: OpenAIChatCompletion | None = None`，已有字段不改名、不改位置。保真模式成功时 completion 必非 None；文本模式不承诺提供 completion。
|
||||
|
||||
`Transport.complete` 追加必填 keyword-only `response_mode: ResponseMode`，依照现有端口纪律不使用默认值掩盖漏传。默认 transport 实现和测试 transport 一并适配；不新增 SDK 适配器（当前文件树尚无该实现）。自定义 transport 须实现新参数与返回契约，不支持模式时抛 RequestRejectedError，不静默回退。
|
||||
|
||||
completion 是独立于上游容器的深拷贝 JSON 快照；frozen 只保证字段不能重绑，不伪称深度不可变。调用方可用 `copy.deepcopy(response.completion.message)` 构造下一轮；其修改不得污染别次调用、缓存条目或另一路对冲。不上 MappingProxyType，避免与既有 dataclasses.asdict/JSON 序列化冲突。
|
||||
|
||||
### 3.2 请求与组合校验
|
||||
|
||||
| 条件 | 规则 |
|
||||
| --- | --- |
|
||||
| 未知模式 | 公共入口 ValueError，尚未创建逻辑调用上下文 |
|
||||
| openai + structured 非 None | 公共入口 ValueError；不注入 schema、不自动重问；overlay 的 response_format 仍可直传 |
|
||||
| openai + n | 仅允许缺省或严格整数 1（不接受 bool）；调用 overlay 在入口校验，选中源 extra_body 及最终 payload 在 HTTP 前校验，不接受被 overlay 遮蔽的非法源级 n |
|
||||
| text + n | 保留旧行为，本次不扩大旧文本多 choice 语义；明确只投影第一 choice |
|
||||
| 消息 | 保留 assistant/tool/reasoning_content/扩展字段，JSON 值不改写；保真入口校验可序列化并深拷贝，避免并发/重试期间调用方改动 |
|
||||
| overlay | 复用既有保护键、源级→请求级优先级；保真调用对快照作深拷贝，不原地改调用方容器 |
|
||||
|
||||
源级 n 错误属选源后的请求拒绝，抛 RequestRejectedError，finally 结算规则不变。保真响应必须恰好一个 choice；SSE choice.index 必须为整数 0，usage-only choices=[] 合法；非流式一个 choice 可省略 index，存在时必须为 0。上游返回多 choice 是协议失败 TransientError，不能静默截取。
|
||||
|
||||
### 3.3 推理所有权不随返回模式变化
|
||||
|
||||
复用 `effective_effort`、`resolve_thinking`、`validate_thinking_raw`，不改能力表与档位映射。raw-only 示例前提：源级 enable_thinking=None、reasoning_effort=None，请求级 reasoning_effort=None，然后 overlay 传 `{"reasoning_effort": "max"}`。`chat(reasoning_effort=None)` 是继承源，不是撤销源意图；raw 与任何有效受管意图（含 NONE）并存仍拒绝。raw-only 的 applied_effort 仍 None，不编造受管档位。
|
||||
|
||||
### 3.4 兼容投影与上游身份
|
||||
|
||||
完整协议 `message` 不过 `_finalize_text`，保留 content 的缺省/null/空串区别、空白、think 标签；非流式保留整个 message 的 JSON 扩展字段。`LLMResponse.content/thinking` 仍是旧 `_finalize_text` 投影，content 为 null/缺省时投影空串；只用于旧消费面和现有遥测，代理回传以 completion 为准。
|
||||
|
||||
response_id 是上游 id，允许未上报为 None，绝不拿 call_id 补齐；finish_reason 原样保存，缺失为 None，不从工具存在与否猜测；usage 保存原对象快照（最后一个非 null usage），不因 token 归一或 salvage 修改原文。字段存在但类型不符是协议失败。`length` 原样返回，不修复工具参数；下游决定是否执行。
|
||||
|
||||
## 4. 协议聚合与完成规则
|
||||
|
||||
新增内部模块 `transports/_openai_completion.py`，只处理 chat 单 choice 协议校验、每尝试聚合与快照；不做 I/O、重试、计时、provider 推理或缓存。现有 openai_compat 保留 HTTP、看门狗、投影、usage 归一化与领域上下文。
|
||||
|
||||
### 4.1 SSE 聚合状态
|
||||
|
||||
每次 complete 独立创建聚合器，不放 transport 实例共享状态。逐 JSON 帧先校验对象并查 error，再读取 choices/delta、元信息和 usage；坏类型统一转 TransientError，不让 AttributeError/TypeError 逃出治理。
|
||||
|
||||
| 字段 | 合并规则 |
|
||||
| --- | --- |
|
||||
| content / reasoning_content | 非 null 必为 str，逐片拼接；同帧同时收集；不 trim；从未出现则不造键，仅 null 则保留 null |
|
||||
| role | openai 模式若出现必须 assistant；只出现 role 不算活性；最终成功必须含 assistant role；缺失失败，不伪造字段 |
|
||||
| tool_calls | 必为列表；每项 index 必为非负严格整数；按 index 分桶，末尾按 index 排序，索引不输出到最终工具对象 |
|
||||
| id / type | 每工具的身份字段，缺失片段不覆盖；相同重复幂等，冲突拒绝；不把重复完整 id 拼两次 |
|
||||
| function.name / function.arguments | 字符串增量按到达顺序逐字拼接，允许空片段；arguments 不 JSON 解析/修复/重排 |
|
||||
| response id / finish_reason | 首个非 null 固定，后续相同值允许、冲突拒绝；model_reported 沿用既有首有效值口径 |
|
||||
|
||||
最终有效工具需非空 id、type="function"、非空 function.name，以及至少出现一次字符串 arguments（允许空串）；重复工具 id、缺字段、非 function 工具类型都拒绝，不伪造或丢弃。index 可非连续，按排序输出，不按列表位置猜 index。JSON 参数内容及工具业务 schema 不由库验证。
|
||||
|
||||
SSE、非流式及缓存最终快照均要求 role="assistant"；缺失或其他 role 为协议失败/缓存 miss；合法 role-only 开头不算活性。
|
||||
|
||||
非流式工具是完整列表：保留条目及扩展字段，仅校验上述必要字段/类型/唯一 id，不要求 index；存在的扩展字段不删除。SSE 保真仅支持 role/content/reasoning_content/tool_calls；未知 delta 字段或未知工具增量字段无法推定合并语义，明确拒绝为协议失败，避免宣称任意扩展字段无损；元数据如 logprobs 不属于本协议结果字段，文档明确不返回。
|
||||
|
||||
### 4.2 成功、截断与错误
|
||||
|
||||
| 场景 | 行为 |
|
||||
| --- | --- |
|
||||
| openai：空正文 + 有完整工具 | 成功，不触发空补全重试 |
|
||||
| openai：非空投影正文、无工具 | 成功；存在任何不完整工具则仍拒绝，不用正文掩盖坏工具 |
|
||||
| openai：无正文且无有效工具 | 维持 empty_completion 瞬时失败；reasoning-only 不算成功 |
|
||||
| openai：EOF 无 DONE | 无论 missing_done=salvage、是否已有正文/工具/finish，都失败；不打捞潜在可执行结果 |
|
||||
| text：EOF 无 DONE | 保持已有 early_eof/retry/salvage 及 estimated/unavailable 行为 |
|
||||
| 任一 chat 模式出现顶层 error 键 | 立即 TransientError，即使值 null/空对象；不读取后续 usage/DONE 挽救，不缓存 |
|
||||
| 非流式 200 error / 非 JSON / 坏 envelope | TransientError；HTTP 非 200 分类沿用现有规则 |
|
||||
|
||||
text 仍不接收 tool-only 成功，不承诺工具结果；共用解析路径的 error 检查、同帧双文本采集和真实工具进展活性修复适用于两模式。纯文本消费不新增工具完整性要求，以免把未承诺的工具结果变成默认请求失败。
|
||||
|
||||
## 5. 活性、治理、取消和可观测
|
||||
|
||||
一帧有非空正文、非空推理、非空工具 name/arguments 增量或首次建立工具身份时，产生**一次**进展事件。重复相同身份、空 arguments、空 delta、role-only、usage-only、finish-only、注释不刷新活性。同帧多个字段和两个工具仍只记录一个时间戳，避免制造零间隔或虚增 stall_count。
|
||||
|
||||
`stream_with_liveness_timeouts` 继续包进展迭代器；openai_compat 用同一事件更新时间戳、TTFT、max_gap、first_token_event、content_event。保持 `_stall_from_chunk_times` 与 retry 唯一取整点不变；真正沉默照常触发中段对冲。非流式不置两事件，stall=None，只保留纯时长阈值对冲。
|
||||
|
||||
请求经原 Telemetry→Cache→Structured（None 直通）→Retry→准入→Transport 链。重试、异源对冲、失败预算、源健康、限流结算均原样复用；输家取消仍保守 est 结算、不喂熔断，赢家携自身完整快照。CancelledError 全栈穿透，连接与 permit finally 释放，无新的 shield 或后台任务。
|
||||
|
||||
遵循 structured-logging：不新增数据库列/表/Recorder 参数。`_build_response` 搬运 completion；错误由 transport 抛出，经过既有 RetryMW._emit→TelemetryEmitter 单出口记 attempt/terminal 行。SSE error 使用现有 summarize_body/compose_message 有界摘要，携 source_name/operation=chat，最多记录有界错误体，不在日志新增完整工具参数、密钥或成功消息。
|
||||
|
||||
现有 `llm_calls` schema（`research-wiki/schemas/llm-calls.md`）及覆盖指标复用。确定性验收指标：error→成功恰好 attempts=2；tool-only attempts=1；命中 attempts=0；失败不写缓存；无孤儿 permit/task。失败 usage 仍 unavailable，费用仍未知，不删除失败事件；不扩展遥测全文覆盖，tool_calls.arguments 不受现有 TEXT_CAP 截断的已知边界须继续声明。
|
||||
|
||||
## 6. 缓存语义
|
||||
|
||||
`build_cache_key` 追加 `response_mode: ResponseMode = "text"`；仅非 text 时将 response_mode 写入 key 对象。默认文本 key 逐字不变；这是请求语义维度，不引入包版本/revision。tools、tool_choice、raw effort 已在 sampling/source fingerprint；assistant/tool 消息全字段已在 digest_messages，直接复用。
|
||||
|
||||
CacheMW 显式序列化和重建 OpenAIChatCompletion，读时验证容器、单消息/工具必要字段与元信息类型。openai 条目 completion 缺失/null/畸形或无有效产物视 miss+warning，不能补默认伪造协议成功；text 旧条目允许缺新字段。transport 与缓存共用 types 内部纯值判据：完整工具或非空投影正文；无工具时还要求协议原正文非空，不能靠缓存旧投影伪装成功；不收紧快照构造用途。错误条目回源成功后覆写，失败不写。
|
||||
|
||||
缓存中的 message/usage 与调用结果独立；命中保留历史上游 id/finish/usage，生成本次 call_id、清除历史 call_stats，最终返回本次 attempts=0；cost=0 延续原口径。缓存读写和序列化失败仅 warning，不冒泡，取消例外穿透；将 `_serialize` 异常纳入缓存降级边界，避免新增嵌套字段扩大失败面。
|
||||
|
||||
旧文本缓存可能已被 error+DONE 毒化，不能自动判别。发布文档要求受影响调用集合首次读写前迁移 namespace/salt，保留租户前缀与 epoch；覆盖工厂和 per-call 身份。未迁移仍会回放旧值，不能宣称修复自动清除历史缓存；openai 新身份天然不命中旧文本。
|
||||
|
||||
## 7. 旧行为审计与非功能约束
|
||||
|
||||
| 既有行为 | 处置 |
|
||||
| --- | --- |
|
||||
| 旧字段/默认文本/structured 阶梯/受管推理 | 保留；默认文本同帧漏 reasoning 属修复 |
|
||||
| HTTP 分类、retry/backoff、两类对冲、TPM/熔断 | 保留，不改算法与预算 |
|
||||
| 空补全、missing_done salvage | 文本保留；openai tool-only 放行、缺 DONE 强制失败 |
|
||||
| Redis TTL、命名空间、遥测幂等与单 helper | 保留；新增模式隔离与嵌套协议结果回放 |
|
||||
| 并发与取消 | 每尝试状态隔离，重试/对冲不得复用聚合器，CancelledError 穿透 |
|
||||
| 降级方向 | 缓存/遥测 warning；准入后端 fail-closed；不新增后端 |
|
||||
| 持久化/原子性/恢复 | 仅成功后一次写完整缓存值；沿用后端原子 set；无新的任务持久化或断点状态 |
|
||||
| 幂等与重复 | 重试/对冲可能产生重复上游计费，库不执行工具，因此不产生本地工具副作用；不承诺上游生成幂等 |
|
||||
|
||||
## 8. 测试、许可证与交付门
|
||||
|
||||
单元测试复用 MockTransport/SSE/受控事件设施；新增两工具交错分片、同帧 content+reasoning、原样下一轮、raw=max、stream=False、缺 DONE、安全判错、缓存和治理组合。每个行为组须保留基线红、新实现绿日志；不以本阶段基线通过冒充新功能证据。
|
||||
|
||||
真实 Redis 只测完整协议缓存往返/隔离与取消关联契约，不 mock Lua。真实模型跑专用通用函数工具双轮冒烟（标 slow，输出 Markdown），复用 `.env` 配置与预算，不在源码硬编码凭据；网络/额度失败如实失败，不改成无覆盖成功。不默认重跑全模型推理矩阵；本次不改 thinking 能力算法。
|
||||
|
||||
许可证：采用 Apache-2.0 已授权；实施前核查实际分发文件及注明移植/参考的片段，区分参考协议事实与复制代码。reference/ 只读且不打包；AGPL 仓存在不自动污染本库，也不由授权覆盖第三方权利。发现实际复制的不兼容片段须上报，不擅自改许可证。加入标准 LICENSE 与 pyproject 元数据；只有确有通知义务才加 NOTICE，不捏造第三方来源。
|
||||
|
||||
源码 docstring、README、CHANGELOG、ARCHITECTURE 同步；无新 env 键，`.env.example` 仅补 raw-only 源配置提示（不改默认）。Gitea Wiki 当前下线，不重建过期页面。线程代理文档说明：client 在同一常驻事件循环线程内创建/使用/关闭；工作线程 run_coroutine_threadsafe，等待超时/断连取消 Future；不逐请求 asyncio.run，不跨 loop 共享 client。
|
||||
|
||||
发布由父会话在独立代码审查、全套件、相关 slow、构建包 LICENSE/元数据核验之后执行；沿 CLAUDE 发布九步，外部验证 registry/Release/包页和下游下载，不仅 bump。issue 只有在可安装产物及验收证据齐备后关闭；本阶段不触发这些动作。
|
||||
@@ -0,0 +1,251 @@
|
||||
---
|
||||
type: design
|
||||
node_id: design:2026-10-14-issue30-31-completion-verdict-design
|
||||
title: 统一完成判定设计(#30/#31)
|
||||
date: 2026-10-14
|
||||
---
|
||||
|
||||
# #30/#31 统一完成判定设计
|
||||
|
||||
> 状态: 方向已获人类批准(2026-10-14,四项取舍与五个拍板点按推荐);人类授权"Claude 与独立 subagent 确认无误后直接执行",不再走人类设计审阅。两轮独立审查已闭合(R1 3 阻塞 + 9 应修;R2 通过,2 应修已并入),见 §11。
|
||||
> 基线: `22609c9`(1.3.9);目标版本 **1.3.10**;分支 `fix/issue30-31-completion-verdict`。
|
||||
> 需求: [#30](https://gitea.iomgaa.online/iomgaa/PolyGateway/issues/30)、[#31](https://gitea.iomgaa.online/iomgaa/PolyGateway/issues/31)。
|
||||
> 修订对象: [1.3.9 保真设计](2026-10-01-issue29-openai-fidelity-design.md) §4.1/§4.2/§5/§6、ARCHITECTURE §6.2/§7/§14。
|
||||
|
||||
## 1. 问题与根因
|
||||
|
||||
两条 issue 是**同一根因**: 库判定"生成结束了、结果可交付"时,依赖库自己的推断(`[DONE]` 存在、正文非空、字段在白名单内、快照字段类型),而不是上游的权威声明(`finish_reason`)与传输完整性(干净 EOF + 结尾 usage)。推断失败一律落 `TransientError` → 重试/换源/计熔断,把确定性结局放大成 `max_attempts` 次付费重抽并推高健康源的熔断计数。
|
||||
|
||||
| 表现 | 位置(1.3.9) | 后果 |
|
||||
| --- | --- | --- |
|
||||
| #31 缺 `[DONE]` 但 finish+usage 完整 | `openai_compat.py:668-671`(保真无条件拒);`_check_done:714`(文本 `missing_done=retry` 默认同样拒) | magpie/glm 两模式均重试到耗尽;实测 1216s 挂起、dissect3 38 次终败 |
|
||||
| #30-1 reasoning-only + `length` | `types.py:478-490`、`_reject_empty_completion` | 每次写满 max_tokens 后丢弃重抽 |
|
||||
| #30-2 未知键 / `tool_calls:null` | `_openai_completion.py:97-98,112-114,139-140,146-147`;**非流式也中**: `OpenAIChatCompletion` 拒 `tool_calls: None`(`types.py:451-453`,已实测) | 渠道一换 100% 失败,且以"瞬时"形态出现 |
|
||||
| 隐患: 只有 `reasoning` 字段的流 | 活性只认 content/reasoning_content | 两模式被看门狗当无进展 → TTFT 超时 |
|
||||
| 隐患: 文本 salvage 的截断结果被缓存 | `cache.py:197-204` 写路径无判定 | 半截结果 TTL 内反复回放 |
|
||||
|
||||
补充事实: GLM 的 finish_reason 含 `network_error`/`sensitive`;2026-07-20 空补全裁决针对的是 stop/无 finish 的"零增量"抖动(`findings/2026-07-21-m25-acceptance.md:48`);vLLM 等实现每帧带累计 usage,finish 之前的 usage 不证明走完。
|
||||
|
||||
## 2. 方案比较
|
||||
|
||||
| 方案 | 内容 | 结论 |
|
||||
| --- | --- | --- |
|
||||
| A 局部放行 | 按 issue 字面在三处各加例外 | 否决: 流式/非流式/缓存判据继续分叉;文本 #31 残留;`network_error` 被当成功 |
|
||||
| B 统一完成判定(选定) | 内核纯函数分两步(流完整性 → 结局分类),流式/非流式/缓存读写四处共用;"可交付"与"可缓存"拆两判据;未知字段无损合并 | 一次消除根因;代价是公共字段追加与遥测端口加参 |
|
||||
| C 透明透传 | 保真模式不做结局判定,原样交回 | 否决: 零增量抖动回归(违背 2026-07-20 裁决),截断流也被交出 |
|
||||
|
||||
## 3. 公共契约变更(只增不改)
|
||||
|
||||
| 位置 | 变更 |
|
||||
| --- | --- |
|
||||
| `types.py` | 新增 `StreamEnd = Literal["done", "eof_after_finish", "salvaged"]`,包根导出 |
|
||||
| `TransportResult` / `LLMResponse` 末尾 | 追加 `finish_reason: str \| None = None`、`stream_end: StreamEnd \| None = None` |
|
||||
| `OpenAIChatCompletion` 校验 | `tool_calls: null` 合法(视同无工具,原样保留键) |
|
||||
| `TelemetryRecorder.record_llm_call` | 追加**无默认值** keyword-only `stream_end: str \| None`(**破坏性**: 自建 recorder 装配期被形状闸拒绝,CHANGELOG 单列) |
|
||||
| `llm_calls` 表 | 末尾追加可空列 `stream_end TEXT`(落点见 §7) |
|
||||
| `Transport.complete` 签名 | **不变** |
|
||||
|
||||
`finish_reason` 取值: 流式取 choice 0(保真已强制单 choice;文本取 `index` 缺省或为 0 的 choice)首个非 null 值;非流式取 `choices[0].finish_reason`。保真模式非字符串维持 1.3.9 拒绝(Transient);文本模式非字符串记 None。`finish_reason` 不进遥测列(未获批)。
|
||||
|
||||
| 场景 | `stream_end` |
|
||||
| --- | --- |
|
||||
| 流式收到 `[DONE]` | `"done"` |
|
||||
| 干净 EOF + finish + 结尾 measured usage | `"eof_after_finish"` |
|
||||
| 文本 `missing_done=salvage` 打捞 | `"salvaged"` |
|
||||
| 非流式 / 缓存命中 / 失败行 | `None`(与 `ttft_ms`/`stall_ms` 同"无从观测"口径) |
|
||||
|
||||
与 `usage_source` 分工: 后者答"账单可信吗",前者答"内容完整吗"。`eof_after_finish ⇒ measured`(由 §4.2 条件保证);`salvaged ⇒ estimated|unavailable`;`estimated ⇒ salvaged`,逆命题不成立。
|
||||
|
||||
## 4. 统一完成判定
|
||||
|
||||
### 4.1 位置与形态
|
||||
|
||||
全部放 `types.py` 内部纯函数(下划线前缀,不导出): CacheMW 要复用,import-linter 禁止 middleware 依赖 transports,而内核层 `ports : types : errors : streaming` 允许。函数只返回判定值,**不抛领域错误**(错误需 `source_name` 等上下文,由调用点翻译),不捕获任何异常,取消天然穿透。
|
||||
|
||||
| 函数 | 职责 |
|
||||
| --- | --- |
|
||||
| `_tool_snapshot_ok(message)` | 工具快照是否成立(id/type/function.name/arguments 规则 + 唯一 id);`OpenAIChatCompletion.__post_init__` 复用 |
|
||||
| `_classify_finish(value)` | 映射到 finish 类别(下表) |
|
||||
| `_stream_is_complete(...)` | 第一步,返回 `StreamEnd \| None`(None = 截断) |
|
||||
| `_judge_outcome(...)` | 第二步,返回 `deliver` 或 `(reject_transient \| reject_result, 原因码)` |
|
||||
| `_is_cacheable(...)` | §6 判据 |
|
||||
|
||||
| finish 类别 | 值(大小写敏感) |
|
||||
| --- | --- |
|
||||
| natural | `stop`、`tool_calls`、`function_call` |
|
||||
| truncated | `length` |
|
||||
| filtered | `content_filter`、`sensitive` |
|
||||
| upstream_error | `network_error`、`error` |
|
||||
| unknown | 其余非空字符串: 按 natural 交付、**不可缓存**、按源+值告警一次(文案写明"该值不缓存",便于下游定位命中率下降);`end_turn`/`stop_sequence` 等无证据不预先归类 |
|
||||
| absent | None |
|
||||
|
||||
### 4.2 第一步: 流完整性(仅流式)
|
||||
|
||||
| 条件 | 结果 |
|
||||
| --- | --- |
|
||||
| 读取异常 / 活性超时 / error 帧 / 畸形帧 | 照旧 Transient(不动) |
|
||||
| 收到 `[DONE]` | `done` |
|
||||
| 干净 EOF、无 DONE、finish 已见、finish 帧**同帧或之后**收到的 usage 被 `_resolve_usage` 判为 measured | `eof_after_finish`,usage 记 measured(不降级) |
|
||||
| 干净 EOF、其余情形 | 截断: openai → Transient `missing_done`(仍不打捞);text → 原 `_check_done` 语义(零产物 early_eof、`retry` 抛、`salvage` 记 `salvaged`) |
|
||||
|
||||
聚合器每尝试记录 `finish_seen` 与 `usage_after_finish`: 收到非 null usage 时,若 `finish_seen` 已真或同帧带 finish,则置后者为真;是否 measured 以**最后一个**非 null usage(与计费所用 `sink["usage"]` 同一对象)在流结束时判定;usage-only 帧(`choices: []`)在 finish 之后到达是常规形态,正确置位。状态随重试/对冲每尝试新建。
|
||||
|
||||
诚实边界: 中转站在上游出错后主动正常结束响应,与真完整在传输层不可区分;防线是"finish 必须存在、不属 upstream_error、且其后有 measured usage",文档如实写明。
|
||||
|
||||
### 4.3 第二步: 结局分类
|
||||
|
||||
产物定义——**保真模式**: 任何产物 = 消息中任一非空字符串片段(content、reasoning_content、reasoning、refusal、合并保留的未知字符串,空白也算)或至少一个非 null 工具条目;**文本模式**: 任何产物 = 投影 content 或 thinking(含 §4.4 别名)非空串(含空白),未知字段与工具增量只计活性不计产物,`_check_done` 零产物判据同口径。两模式**正文产物** = 投影 content strip 后非空,或(仅保真)工具快照成立且非空。
|
||||
|
||||
表格**自上而下取首个匹配行**:
|
||||
|
||||
| # | 条件 | openai 模式 | text 模式 |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | finish 为 upstream_error | Transient `upstream_finish_error` | 同左 |
|
||||
| 2 | (仅保真)存在工具条目但 `_tool_snapshot_ok` 不成立 | truncated → ResultInvalid `tool_truncated`;其余 → Transient `tool_incomplete` | 不适用 |
|
||||
| 3 | 无任何产物 + truncated/filtered | 交付(#30;隐藏推理模型写满预算的形态) | ResultInvalid `length_without_content` / `filtered_without_content` |
|
||||
| 4 | 无任何产物 + natural/unknown/absent | Transient `empty_completion`(保 2026-07-20 裁决) | 同左 |
|
||||
| 5 | 有正文产物 | 交付 | 交付 |
|
||||
| 6 | 有产物无正文 + truncated | 交付(#30) | ResultInvalid `length_without_content` |
|
||||
| 7 | 有产物无正文 + filtered | 交付 | ResultInvalid `filtered_without_content` |
|
||||
| 8 | 有产物无正文 + natural/unknown | 交付 | Transient `empty_completion`(待证据;消息带 finish 与 thinking 长度) |
|
||||
| 9 | 有产物无正文 + absent(流式仅 DONE 收尾,或非流式 body finish 为 null) | Transient `empty_completion` | 同左 |
|
||||
|
||||
ResultInvalid 理由: `retry.py:409-414` 对其"不重试、不换源、熔断记成功不计窗口";length/过滤是预算或内容策略的确定性结局,不是源坏了。对冲下原路 ResultInvalid 等对冲路裁定,两败原样上抛(`retry.py:548-560`);StructuredMW 只捕 parse 抛出的 ResultInvalid,不会误重问(`structured.py:79`)。已知代价: 该分支 TPM 全额退款、用量不落成本(`actual=0`),与 Transient 丢成本同级,登记为已知边界。文本 length 改抛 ResultInvalid 后不再经 `AllSourcesExhausted` 包装,§10 要求核对下游 catch 点。
|
||||
|
||||
原因码以固定格式 `"{源} {code}: …"` 写进异常 message,从而进遥测 `error` 列(LIKE 可检索);不新增列、不改 `_failure_reason`(Transient 一族熔断原因记 `network_error` 属已知口径)。
|
||||
|
||||
保真模式行 2 之外的工具快照成立 + `length`: 交付,arguments 可能是半截 JSON——docstring 与 CHANGELOG 提醒调用方先查 `finish_reason` 再执行工具。非流式跳过第一步,直接以 body 的 finish_reason 走第二步。
|
||||
|
||||
### 4.4 文本模式 reasoning 别名
|
||||
|
||||
投影 `thinking`: 本次尝试出现过**非空** `reasoning_content` 则只用它,否则用 `reasoning`。保真 `completion.message` 保留上游原键不改名。两模式活性、产物摘要、`thinking_observation` 均基于该投影。
|
||||
|
||||
## 5. 字段合并与活性
|
||||
|
||||
### 5.1 null 与已知字段
|
||||
|
||||
null 规则**优先于**已知字段类型校验: chunk、choice、delta、工具条目、function 五层任意键值为 null 视为缺省,数组中的 null 元素(如 `tool_calls: [null]`)跳过;键从未出现时保留 `key: null`(含 `tool_calls`、`refusal`、`role`、`function.arguments`)。保真成功仍须最终 role=assistant(全程只有 `role: null` 即缺 role,照旧失败)。其余已知字段(content/reasoning_content/role/tool_calls 及工具 id/type/function.name/arguments)非 null 时语义逐字沿用 1.3.9。
|
||||
|
||||
### 5.2 未知字段(delta、`tool_calls[]` 条目、`function` 三层统一)
|
||||
|
||||
| 值 | 规则 |
|
||||
| --- | --- |
|
||||
| 标签键 `index`/`type`/`id`/`format`(任意未知层级) | 同值幂等,不拼接;不同值 = 冲突 |
|
||||
| 其他字符串 | 按到达顺序拼接(OpenAI SDK 流式累加惯例) |
|
||||
| 数字/布尔 | 同值幂等;不同值 = 冲突(不学 SDK 相加) |
|
||||
| 对象 | 递归套用本表 |
|
||||
| 数组且元素均为带整数 `index` 的对象 | 按 index 合并(`reasoning_details` 一类);合并策略由该键首次出现形态决定,之后形态改变 = 冲突 |
|
||||
| 其他数组 | 追加 |
|
||||
| 冲突 | 删除该键路径,本尝试内不再接收;按 (源, 归一路径) 告警一次 |
|
||||
|
||||
冲突删键是有损的: docstring 与 CHANGELOG 写明"可能缺字段,以告警为准"。上游方言确定,重拉同样结果,不视为缓存毒化。
|
||||
|
||||
### 5.3 活性
|
||||
|
||||
已知字段活性逐字沿用 1.3.9(非空 content/reasoning_content、工具 name/arguments 非空增量、首次建立工具身份)。未知字段仅当本帧在非标签键上并入非空字符串片段(含追加型数组中的字符串元素)时算进展(`reasoning` 由此计入);同帧只记一次。残余风险如实登记: 上游每帧重复下发的非标签字符串(如 `status`)会被拼接并持续刷新看门狗。文本模式同口径。README 中"增量 chunk = content 或 reasoning_content"的 stall/TTFT 口径表述同步更新为本节口径。
|
||||
|
||||
### 5.4 告警节流
|
||||
|
||||
节流集合放 transport 实例(与 `_warned_mismatches` 分立,纯 asyncio 中立),键为 (源, 归一路径) 与 (源, 未知 finish 值):路径中数组下标归一为 `[]`,finish 值截断至 64 字符;集合上限 1024,饱和后记一次"告警已饱和"不再增长。日志只写源名与路径,不回显值(可能含工具参数)。聚合器以只读集合交出冲突路径,transport 负责告警。
|
||||
|
||||
## 6. 可交付 vs 可缓存
|
||||
|
||||
可缓存 ⊂ 可交付。两模式同一判据 `_is_cacheable`,读写共用:
|
||||
|
||||
| 条件(任一成立即不可缓存) | 理由 |
|
||||
| --- | --- |
|
||||
| `stream_end == "salvaged"` | 截断结果,修现存毒化 |
|
||||
| 无正文产物 | 不把空回答固化进 TTL |
|
||||
| finish 类别为 truncated/filtered/unknown | 截断有随机性,同 key 换时可成功;未知值不可证明是自然结束 |
|
||||
| openai 模式 completion 原文 content 为空且无工具(沿 1.3.9) | 不信任旧投影 |
|
||||
|
||||
| 路径 | 规则 |
|
||||
| --- | --- |
|
||||
| 写 | 不可缓存 → 跳过,debug 日志 |
|
||||
| 读 | `_is_cacheable` 在命中覆盖(`cache.py:224` `fields.update`)**之前**、对存储原值判定;不可缓存 → miss + warning |
|
||||
| 读: 非法 `stream_end` | 不在 Literal 域内 → miss + warning(关乎内容完整性,故与 `_coerce_observation` 的宽容方向相反) |
|
||||
| 读: 顶层无 finish_reason | 回退 `completion.finish_reason`(1.3.9 保真 length 条目因此可识别);文本旧条目两字段缺省 → None → 仍可命中 |
|
||||
| 命中返回 | `stream_end=None`;`finish_reason` 取判定所用值(顶层缺省时为回退值),非字符串视 miss |
|
||||
| 序列化 | `_RESPONSE_FIELDS` 由 `dataclasses.fields` 自动派生,无需改动 |
|
||||
|
||||
旧 salvage/length 文本污染无法辨认: CHANGELOG 继续要求受影响集合迁移 namespace/salt。
|
||||
|
||||
## 7. 遥测落点
|
||||
|
||||
| 位置 | 变更 |
|
||||
| --- | --- |
|
||||
| `middleware/telemetry.py` `_AttemptUsage.of(response)` | 读 `response.stream_end`(本次 LLMResponse 有字段,不像 1.3.8 走 `emit_attempt` kw,避免约 50 处调用点) |
|
||||
| `_record` | 新增参数,单一 helper 下沉 recorder |
|
||||
| `emit_cache_hit` / `emit_terminal_failure` / 失败与取消 attempt 行 | 显式 None |
|
||||
| `telemetry/schema.py` | SQLite/PG 两份 CREATE 末尾、`SQLITE_BACKFILL`、`_PG_BACKFILL_DECLS`(列序对齐)、`COLUMNS`;`telemetry_schema_sql()` 随之输出 |
|
||||
| sqlite/postgres recorder | 按 `COLUMNS` 写入;auto 档幂等补列、manual 档裁剪写入并点名缺列(沿 1.3.8) |
|
||||
| tests | 约 20 处测试替身 `record_llm_call` 补参数 |
|
||||
| 文档 | README "必录字段数"按 `inspect.signature` 实测更新;`schemas/llm-calls.md` 加列并修正陈旧计数 |
|
||||
|
||||
## 8. 旧行为审计
|
||||
|
||||
| 既有行为 | 处置 |
|
||||
| --- | --- |
|
||||
| 保真缺 DONE 一律失败 | **替换**: §4.2 判完整时成功;其余仍失败、仍不打捞 |
|
||||
| 文本 `missing_done=retry` 遇缺 DONE 即抛 | **替换**: 同上;`missing_done` 只管真截断 |
|
||||
| 文本 salvage + estimated | 保留,另标 `salvaged`,不再写缓存 |
|
||||
| 零增量 + DONE → Transient | **保留**(`test_stream_zero_content_with_done_is_transient` 红线回归) |
|
||||
| 保真 reasoning-only/空产物失败 | **替换**: §4.3 行 3/6/7/8 |
|
||||
| 未知 delta/工具/function 字段拒绝;null 已知字段拒绝 | **替换**: §5 |
|
||||
| 非流式 `tool_calls: null` 拒绝 | **替换**: 合法 |
|
||||
| 多 choice/index≠0 拒绝、最终 role 必须 assistant、error 帧立即失败 | 保留 |
|
||||
| 工具快照强校验 | 保留;仅 length 截断时改归 ResultInvalid |
|
||||
| finish_reason 冲突拒绝(Transient) | 保留(登记: 确定性方言,将来可改 ResultInvalid) |
|
||||
| 已知字段活性口径 | 保留;未知字段按 §5.3 增补 |
|
||||
| 缓存写路径无判定 | **替换**: 按 `_is_cacheable` |
|
||||
| 文本 n>1 混流 | 不在范围,另开 issue |
|
||||
|
||||
## 9. 非功能维度
|
||||
|
||||
| 维度 | 回答 |
|
||||
| --- | --- |
|
||||
| 并发与取消 | 新状态在每尝试聚合器/sink 内;判定为纯函数,不新增 try/except,`CancelledError` 原路穿透;finally 结算与 permit 释放不变 |
|
||||
| 降级方向 | 缓存跳写/视 miss 只 debug/warning;遥测新列缺失按 manual 档裁剪 + 告警,不冒泡;限流/熔断不涉及 |
|
||||
| 幂等与重复 | 减少重复付费重抽;标签键与身份字段幂等;告警节流有界 |
|
||||
| 持久化与原子性 | 仅新增一可空列,补列沿既有探测后 ALTER 幂等流程;缓存仍成功后单次原子 set |
|
||||
| 错误分类 | 仅落 Transient 与 ResultInvalid 两类,不新增类;原因码见 §4.3 |
|
||||
| 可观测 | `stream_end` 字段 + 遥测列;冲突路径与未知 finish 有界告警;遵 structured-logging 更新 `schemas/llm-calls.md` |
|
||||
|
||||
## 10. 测试、文档与交付
|
||||
|
||||
全部用假 SSE / MockTransport 复现,每条先红后绿;真实中转冒烟标 slow 按发布清单 diff 交集跑。
|
||||
|
||||
| 组 | 用例 |
|
||||
| --- | --- |
|
||||
| #31 验收 | 1 stop+usage+EOF 成功、`eof_after_finish`、measured、attempts=1;2 tool_calls 同上工具完整;3 无 finish 即关 → 失败;4 finish 无 usage → 失败;5 中途 `RemoteProtocolError` → 失败;6 带 DONE → `done` 不变 |
|
||||
| #31 补充 | usage 早于 finish(累计 usage)+EOF → 不完整;finish 后 usage 为 `{}` → 不完整;`network_error`+usage+EOF → Transient;文本模式 1/3/4(`retry`、`salvage` 两档) |
|
||||
| #30 验收 | reasoning-only+length → 交付、content 空、思考完整、attempts=1;流式 `refusal:null`+`tool_calls:null` 成功;非流式 message 带 `tool_calls:null`+`refusal:null` 成功 |
|
||||
| 结局表 | §4.3 每行至少一例,两模式、流式与非流式;文本 length → ResultInvalid 且熔断未计失败;零增量+DONE(带 stop/不带 finish)仍 Transient;content 非空 + 坏工具 + stop → Transient |
|
||||
| 合并/活性 | 只有 `reasoning` 刷新活性不超时;二次构造 OpenRouter `reasoning_details` 往返(`format`/`id` 不拼接);工具层嵌套对象原样保留可回传;数值冲突删键、告警一次、调用成功;节流饱和;`role:null`/`arguments:null` 视缺省 |
|
||||
| 缓存 | 四类不可缓存均不写、注入后读视 miss;非法 `stream_end` 视 miss;1.3.9 旧文本条目仍命中;1.3.9 保真 length 条目经回退识别为不可缓存;命中 `stream_end=None` |
|
||||
| 遥测 | sqlite/pg(integration)新列写入、旧库补列、manual 档裁剪;形状闸拒绝缺参 recorder |
|
||||
| 改写 | `test_openai_never_salvages`;`test_invalid_delta_is_domain_error` 中 `{"audio": {}}`、`{"index":0,"extra":1}`、null 已知字段参数;提交说明列出 |
|
||||
|
||||
同步: 源码 docstring、README(能力表、`1.3.*` 安装约束核对、活性口径、字段数)、CHANGELOG 1.3.10(行为变更段、破坏性段: recorder 端口、namespace/salt 提醒、半截工具参数提醒、冲突删键提醒)、ARCHITECTURE §6.2/§7/§14、1.3.9 设计加修订指针、`schemas/llm-calls.md`、`research-wiki/migrations/` 三份核对下游对 ResultInvalid 的 catch 点、`docs-convention.md` §2 清单。另开 issue: 文本 n>1 混流;文本"有产物无正文 + stop"证据收集。发布按 CLAUDE.md §4.4.1 九步,#30/#31 在 registry 可安装且验收证据齐备后关闭。
|
||||
|
||||
证据: `retry.py:404-450,548-560`;`cache.py:197-236`;`structured.py:79`;[openai-python `_streaming.py`](https://github.com/openai/openai-python/blob/main/src/openai/_streaming.py) 与 `lib/streaming/_deltas.py`;[vLLM reasoning outputs](https://docs.vllm.ai/en/latest/features/reasoning_outputs/);GLM finish 枚举来自第三方镜像,实现前以真实中转探针再核;Gemini `extra_content` 路径未核实原文,测试按通用嵌套对象构造。
|
||||
|
||||
## 11. 审查修订记录
|
||||
|
||||
| 轮次 | 意见 | 处置 |
|
||||
| --- | --- | --- |
|
||||
| R1 | B1 `tool_calls:null` 被快照拒(非流式现存) | 采纳: §3/§5.1/§10 |
|
||||
| R1 | B2 结局表行重叠 | 采纳: 首匹配行序 + `_tool_snapshot_ok` 前置 |
|
||||
| R1 | B3 文本"任何产物"不可计算 | 采纳: §4.3 分模式定义 |
|
||||
| R1 | S1 eof_after_finish 但 usage 非 measured | 采纳: 条件加 measured |
|
||||
| R1 | S2/S3 活性冲突与标签拼接 | 采纳: §5.2/§5.3 |
|
||||
| R1 | S4 告警集合无界 | 采纳: §5.4 |
|
||||
| R1 | S5 无产物 + length 与 #30 原文冲突 | 采纳(人类授权代决): 保真交付、文本 ResultInvalid、stop/absent 仍 Transient |
|
||||
| R1 | S6-S9 缓存顺序、遥测落点、原因码、null 优先 | 采纳: §6/§7/§4.3/§5.1 |
|
||||
| R1 | 建议 1-7 | 采纳 1/2/3/5/6/7;建议 4 不标不可缓存(上游确定性,非毒化) |
|
||||
| R2 | 结论通过;N1 measured 以最后 usage 判定、N2 非空 reasoning_content | 采纳: §4.2/§4.4 |
|
||||
| R2 | 建议 1-4: 命中回退值、未知 finish 告警文案、数组字符串活性与残余风险、null 五层与数组 null 元素 | 全部采纳: §6/§4.1/§5.3/§5.1 |
|
||||
| 代码审查 | I1 保真可缓存须同时要求投影正文非空(think 标签剥净后为空不缓存) | 采纳: `_is_cacheable` |
|
||||
| 代码审查 | I2 无参函数 `arguments` 全程 null → 快照不成立被判 Transient 重试 | 人类授权代决: 归 ResultInvalid `tool_arguments_null`(确定性方言);不改写交付值(改写破坏保真,重试救不回) |
|
||||
| 代码审查 | I3 文本 `index:null` 整帧丢弃、`index:False` 冒充 0 | 采纳: null 视 0,bool 拒 |
|
||||
| 代码审查 | Minor: `[null]` 产出空 `tool_calls`、非流式缺 role 先于判定、告警路径长度有界、README 表述 | 采纳;index 数组缺 index 整键删除登记于 CHANGELOG 提醒 |
|
||||
@@ -96,3 +96,12 @@ T1–T4 全部行为变更具备先红后绿证据(§1),默认关闭回归门成
|
||||
| PG 遥测 30 用例 | `pg-integration-rerun2.log` | 30 passed exit=0(首轮 12 failed → 根因: `_minimal_fields` 测试 helper 未同步 1.3.8 两列,`postgres.py:450` 按物理列取值 KeyError;修复 helper + `test_pre_135` 期望字典,同类 B1 测试同步缺口,非生产缺陷——生产路径由装配闸强制全签名) |
|
||||
| 关键用例重跑 | `key-reruns.log` | 10 passed exit=0(净口径精确值/复检防误触发/看门狗掐死汇合/遥测迁移幂等) |
|
||||
| make lint | `verify/lint.log` | exit=0,Contracts: 1 kept, 0 broken |
|
||||
|
||||
## 6. 发布门(2026-09-14,main b0232b7)
|
||||
|
||||
| 门 | 证据 | 结果 |
|
||||
| --- | --- | --- |
|
||||
| 合并后 make lint | `tests/outputs/138/release-lint.log` | exit=0,Contracts: 1 kept |
|
||||
| 合并后全套件 | `tests/outputs/138/release-full-gate.log` | 1764 passed, 23 skipped, exit=0 |
|
||||
| slow 交集(Redis 时间语义变体+网关冒烟) | `tests/outputs/138/release-slow-scoped.log` | 22 passed,EXIT_CODE=0,20m17s |
|
||||
| thinking 矩阵豁免 | 交集规则(CLAUDE.md §4.4.1 第4步) | 本 diff 未动 thinking/能力注册表/e2e 设施,复用 1.3.7 矩阵证据 |
|
||||
|
||||
@@ -0,0 +1,18 @@
|
||||
# #29 分发来源前置核查
|
||||
|
||||
日期：2026-10-01；基线 0e29dea；在 T1 前执行。本记录不是法律认证。
|
||||
|
||||
| 范围 | 实际核查与结论 |
|
||||
|---|---|
|
||||
| 跟踪源码 | `git ls-files src` 列出 polygateway Python 模块与 py.typed，无 vendor 子树、外部 LICENSE/NOTICE、打包外部代码目录 |
|
||||
| 内部移植 | rg 检索移植/参考/Copyright/SPDX/copied/adapted：streaming、sources、Redis Lua、ports、openai_compat 的来源为三个内部项目；用户已明确均本人原创并授权 Apache-2.0 |
|
||||
| 外部参考声明 | 阅读 types.py Effort、providers.py ThinkingWire/注册表、thinking.py 能力证据段；使用的是协议词汇/参数形态/实测结论，未发现来自外部仓的成段实现或第三方版权头；不把相同协议字符串认定为复制实现 |
|
||||
| 打包边界 | pyproject 仅从 src 发现包，reference 不跟踪、不纳入分发；本次不复制外部参考实现 |
|
||||
| 许可来源 | 系统 `/usr/share/common-licenses/Apache-2.0` 提供标准许可正文；构建时核对包内文本与元数据 |
|
||||
|
||||
未发现需额外通知的实际复制片段，因此不编造 NOTICE。外部参考仓含 AGPL 不等于本库受其许可约束；用户对原创代码的授权也不能覆盖第三方。实施/审查若发现新的实际复制证据，停止并提交主管处理，不用本文替代核查。
|
||||
|
||||
## 审查意见处置
|
||||
|
||||
P1 采纳：协议快照缺 role 不可直接进入下一轮，SSE/非流式/缓存统一要求 assistant；不补造 role，默认 text 不变。
|
||||
P2 采纳：将本次来源核查前移到 T0，T6 仅复核及落实 LICENSE/打包/文档。两项均是已批准方向的正确性修订，无需新增用户授权。
|
||||
@@ -225,6 +225,31 @@
|
||||
"id": "finding:2026-09-09-134-thinking-contracts-validation",
|
||||
"label": "1.3.4 T0–T4 与 T7 确定性验证",
|
||||
"type": "finding"
|
||||
},
|
||||
{
|
||||
"id": "design:2026-10-01-issue29-openai-fidelity-design",
|
||||
"label": "OpenAI消息保真设计",
|
||||
"type": "design"
|
||||
},
|
||||
{
|
||||
"id": "plan:2026-10-01-issue29-openai-fidelity",
|
||||
"label": "OpenAI消息保真实现计划",
|
||||
"type": "plan"
|
||||
},
|
||||
{
|
||||
"id": "review:2026-10-01-issue29-cache-review",
|
||||
"label": "保真缓存审查修复与1.4.0准备",
|
||||
"type": "review"
|
||||
},
|
||||
{
|
||||
"id": "plan:2026-09-10-24-hedged-requests",
|
||||
"label": "issue #24 长尾对冲请求与裸生成时间实施计划",
|
||||
"type": "plan"
|
||||
},
|
||||
{
|
||||
"id": "design:2026-09-10-24-hedged-requests-design",
|
||||
"label": "长尾对冲请求(issue #24)设计",
|
||||
"type": "design"
|
||||
}
|
||||
],
|
||||
"links": [
|
||||
@@ -472,6 +497,34 @@
|
||||
"relation": "implements",
|
||||
"evidence": "1.3.5 逻辑调用统计与结构化失败诊断实施计划落地已批准设计",
|
||||
"added": "2026-09-09T13:42:00.298915+00:00"
|
||||
},
|
||||
{
|
||||
"source": "plan:2026-10-01-issue29-openai-fidelity",
|
||||
"target": "design:2026-10-01-issue29-openai-fidelity-design",
|
||||
"relation": "implements",
|
||||
"evidence": "已批准方向与独立审查P1/P2修订",
|
||||
"added": "2026-10-01T17:52:42.425248+00:00"
|
||||
},
|
||||
{
|
||||
"source": "schema:llm-calls",
|
||||
"target": "design:2026-10-01-issue29-openai-fidelity-design",
|
||||
"relation": "implements",
|
||||
"evidence": "复用既有单出口与schema，无新增列；工具error为attempt失败",
|
||||
"added": "2026-10-01T17:52:43.831331+00:00"
|
||||
},
|
||||
{
|
||||
"source": "review:2026-10-01-issue29-cache-review",
|
||||
"target": "design:2026-10-01-issue29-openai-fidelity-design",
|
||||
"relation": "informs",
|
||||
"evidence": "统一缓存与transport的有效产物判据，保持内核依赖边界",
|
||||
"added": "2026-10-01T18:27:16.434742+00:00"
|
||||
},
|
||||
{
|
||||
"source": "plan:2026-09-10-24-hedged-requests",
|
||||
"target": "design:2026-09-10-24-hedged-requests-design",
|
||||
"relation": "implements",
|
||||
"evidence": "计划头部与设计 §9 批准状态(2026-09-10 H1-H8 全数获批)",
|
||||
"added": "2026-09-10T16:48:37.849653+00:00"
|
||||
}
|
||||
]
|
||||
}
|
||||
+23
-5
@@ -1,8 +1,8 @@
|
||||
# Research Wiki 索引
|
||||
|
||||
> 自动生成，更新时间：2026-09-09 18:01 UTC
|
||||
> 自动生成，更新时间：2026-10-02 02:23 UTC
|
||||
|
||||
## design (43)
|
||||
## design (47)
|
||||
|
||||
- [1.3.4 推理意图与测试证据设计](designs/2026-09-09-134-thinking-contracts-design.md) `design:2026-09-09-134-thinking-contracts-design`
|
||||
- [2026-07-20-m1-core-design](designs/2026-07-20-m1-core-design.md) `design:2026-07-20-m1-core-design`
|
||||
@@ -25,6 +25,9 @@
|
||||
- [2026-08-24-issue15-telemetry-pool-lifecycle-design](designs/2026-08-24-issue15-telemetry-pool-lifecycle-design.md) `design:2026-08-24-issue15-telemetry-pool-lifecycle-design`
|
||||
- [2026-09-04-reasoning-effort-design](designs/2026-09-04-reasoning-effort-design.md) `design:2026-09-04-reasoning-effort-design`
|
||||
- [2026-09-09-135-call-observability-design](designs/2026-09-09-135-call-observability-design.md) `design:2026-09-09-135-call-observability-design`
|
||||
- [2026-09-09-136-call-budgets-design](designs/2026-09-09-136-call-budgets-design.md) `design:2026-09-09-136-call-budgets-design`
|
||||
- [2026-09-10-24-hedged-requests-design](designs/2026-09-10-24-hedged-requests-design.md) `design:2026-09-10-24-hedged-requests-design`
|
||||
- [2026-09-11-streaming-stall-design](designs/2026-09-11-streaming-stall-design.md) `design:2026-09-11-streaming-stall-design`
|
||||
- [est_tokens 解耦: 拆分限流预扣与遥测用量兜底(issue #2)](designs/est-tokens-decoupling.md) `design:est-tokens-decoupling`
|
||||
- [GatewaySettings 装配校验补齐(第二轮)](designs/settings-invariants-round-2.md) `design:settings-invariants-round-2`
|
||||
- [GatewaySettings 跨字段不变量守卫的生效范围](designs/settings-invariant-guards.md) `design:settings-invariant-guards`
|
||||
@@ -38,6 +41,7 @@
|
||||
- [M2.5 治理韧性: 半死源隔离与健康感知调度](designs/m25-resilience.md) `design:m25-resilience`
|
||||
- [M3 OCR 端口族设计](designs/m3-ocr.md) `design:m3-ocr`
|
||||
- [M4 迁移验证设计(GovDoc→CHS,发 v1.0)](designs/m4-migration.md) `design:m4-migration`
|
||||
- [OpenAI消息保真设计](designs/2026-10-01-issue29-openai-fidelity-design.md) `design:2026-10-01-issue29-openai-fidelity-design`
|
||||
- [stall 判定改为非生产性等待口径](designs/issue8-stall-budget.md) `design:issue8-stall-budget`
|
||||
- [响应可观测字段扩展(Issue #3)](designs/response-observability-fields.md) `design:response-observability-fields`
|
||||
- [建表前先探测,判死只认「确定写不进去」](designs/issue9-telemetry-ddl-probe.md) `design:issue9-telemetry-ddl-probe`
|
||||
@@ -48,18 +52,23 @@
|
||||
- [调用方自定义维度设计(issue #11)](designs/issue11-caller-dimensions.md) `design:issue11-caller-dimensions`
|
||||
- [采样参数透传设计(issue #4)](designs/sampling-params.md) `design:sampling-params`
|
||||
|
||||
## finding (17)
|
||||
## finding (22)
|
||||
|
||||
- [1.3.4 推理契约验证与发布准备](findings/2026-09-09-134-thinking-contracts-validation.md) `finding:2026-09-09-134-thinking-contracts-validation`
|
||||
- [1.3.5 T2/T3/T4 验收证据：36 列遥测、失败终态、PG 存储兼容与变异矩阵](findings/2026-09-09-135-call-observability-validation.md) `finding:2026-09-09-135-call-observability-validation`
|
||||
- [1.3.5 发布完成与外部验收：合并后门、registry 产物与页面亲查](findings/2026-09-09-135-release-completion.md) `finding:2026-09-09-135-release-completion`
|
||||
- [1.3.6 可选调用期限与取消结算验证记录](findings/2026-09-10-136-call-deadline-validation.md) `finding:2026-09-10-136-call-deadline-validation`
|
||||
- [1.3.8 流式中段沉默:净口径与中段对冲验证报告](findings/2026-09-11-streaming-stall-validation.md) `finding:2026-09-11-streaming-stall-validation`
|
||||
- [2026-07-20-m2-soak-workload](findings/2026-07-20-m2-soak-workload.md) `finding:2026-07-20-m2-soak-workload`
|
||||
- [2026-07-21-m25-acceptance](findings/2026-07-21-m25-acceptance.md) `finding:2026-07-21-m25-acceptance`
|
||||
- [2026-07-21-p6-soak-baseline](findings/2026-07-21-p6-soak-baseline.md) `finding:2026-07-21-p6-soak-baseline`
|
||||
- [2026-07-22-m4-acceptance](findings/2026-07-22-m4-acceptance.md) `finding:2026-07-22-m4-acceptance`
|
||||
- [2026-07-22-p7-ocr-soak](findings/2026-07-22-p7-ocr-soak.md) `finding:2026-07-22-p7-ocr-soak`
|
||||
- [2026-09-11-streaming-stall-hedging-research](findings/2026-09-11-streaming-stall-hedging-research.md) `finding:2026-09-11-streaming-stall-hedging-research`
|
||||
- [2026-10-01-issue29-license-audit](findings/2026-10-01-issue29-license-audit.md) `finding:2026-10-01-issue29-license-audit`
|
||||
- [issue #16/#17 实测: M3 推理正常,失效的是推理的可观测信号](findings/2026-08-25-thinking-observability-regression.md) `finding:2026-08-25-thinking-observability-regression`
|
||||
- [issue #18 实测: 偶发红的是安全网本身,不是被测脚本](findings/2026-08-26-issue18-shared-pg-test-isolation.md) `finding:2026-08-26-issue18-shared-pg-test-isolation`
|
||||
- [issue #24 长尾对冲请求与裸生成时间验证报告](findings/2026-09-10-24-hedged-requests-validation.md) `finding:2026-09-10-24-hedged-requests-validation`
|
||||
- [M2 verifier 三项 Important 补齐(不变量接线/网关保护/P3 验收)](findings/m2-verifier-fixes.md) `finding:m2-verifier-fixes`
|
||||
- [M2 真实数据压测: 场景矩阵与数据清单](findings/m2-soak-workload.md) `finding:m2-soak-workload`
|
||||
- [M2.5 验收: P6 同场景 58.1% → 98.96%](findings/m25-acceptance.md) `finding:m25-acceptance`
|
||||
@@ -68,10 +77,12 @@
|
||||
- [P7 OCR soak 验收: 99.73% 与 13 不变量全 PASS](findings/p7-ocr-soak.md) `finding:p7-ocr-soak`
|
||||
- [推理开关与 reasoning_tokens: 供应商实测与业界做法](findings/2026-08-02-thinking-switch-and-reasoning-tokens.md) `finding:2026-08-02-thinking-switch-and-reasoning-tokens`
|
||||
|
||||
## plan (38)
|
||||
## plan (42)
|
||||
|
||||
- [1.3.4 推理契约实施计划](plans/2026-09-09-134-thinking-contracts.md) `plan:2026-09-09-134-thinking-contracts`
|
||||
- [1.3.5 逻辑调用统计与结构化失败诊断实施计划](plans/2026-09-09-135-call-observability.md) `plan:2026-09-09-135-call-observability`
|
||||
- [1.3.6 可选调用期限与取消结算修复实施计划](plans/2026-09-10-136-call-deadline.md) `plan:2026-09-10-136-call-deadline`
|
||||
- [1.3.8 流式中段沉默:计量口径与对冲实施计划](plans/2026-09-11-streaming-stall.md) `plan:2026-09-11-streaming-stall`
|
||||
- [2026-07-20-m1-core-plan](plans/2026-07-20-m1-core-plan.md) `plan:2026-07-20-m1-core-plan`
|
||||
- [2026-07-20-m2-distributed-plan](plans/2026-07-20-m2-distributed-plan.md) `plan:2026-07-20-m2-distributed-plan`
|
||||
- [2026-07-21-m25-resilience-plan](plans/2026-07-21-m25-resilience-plan.md) `plan:2026-07-21-m25-resilience-plan`
|
||||
@@ -90,12 +101,14 @@
|
||||
- [2026-09-04-reasoning-effort](plans/2026-09-04-reasoning-effort.md) `plan:2026-09-04-reasoning-effort`
|
||||
- [est_tokens 解耦实施计划](plans/est-tokens-decoupling.md) `plan:est-tokens-decoupling`
|
||||
- [issue #18 实现计划: 权限边界替代行数快照 + --table 锁死目标](plans/2026-08-26-issue18-pg-test-isolation.md) `plan:2026-08-26-issue18-pg-test-isolation`
|
||||
- [issue #24 长尾对冲请求与裸生成时间实施计划](plans/2026-09-10-24-hedged-requests.md) `plan:2026-09-10-24-hedged-requests`
|
||||
- [issue #8 实施计划: stall 非生产性等待口径](plans/issue8-stall-budget-plan.md) `plan:issue8-stall-budget-plan`
|
||||
- [M1 核心里程碑实现计划](plans/m1-core-plan.md) `plan:m1-core-plan`
|
||||
- [M2 分布式实现计划](plans/m2-distributed.md) `plan:m2-distributed`
|
||||
- [M2.5 治理韧性实现计划](plans/m25-resilience.md) `plan:m25-resilience`
|
||||
- [M3 OCR 实现计划](plans/m3-ocr.md) `plan:m3-ocr`
|
||||
- [M4 迁移实现计划(T0-T14)](plans/m4-migration.md) `plan:m4-migration`
|
||||
- [OpenAI消息保真实现计划](plans/2026-10-01-issue29-openai-fidelity.md) `plan:2026-10-01-issue29-openai-fidelity`
|
||||
- [plan-issue14-admission-wait-policy](plans/plan-issue14-admission-wait-policy.md) `plan:plan-issue14-admission-wait-policy`
|
||||
- [响应可观测字段扩展实现计划](plans/response-observability-fields.md) `plan:response-observability-fields`
|
||||
- [实现计划: HTTP 错误响应体留存(Issue #10)](plans/issue10-error-body-retention-plan.md) `plan:issue10-error-body-retention-plan`
|
||||
@@ -109,8 +122,13 @@
|
||||
- [调用方自定义维度实现计划(issue #11)](plans/issue11-caller-dimensions.md) `plan:issue11-caller-dimensions`
|
||||
- [采样参数透传实现计划(issue #4)](plans/sampling-params-plan.md) `plan:sampling-params-plan`
|
||||
|
||||
## review (1)
|
||||
## review (6)
|
||||
|
||||
- [2026-09-11-138-branch-review](reviews/2026-09-11-138-branch-review.md) `review:2026-09-11-138-branch-review`
|
||||
- [2026-09-11-138-verifier](reviews/2026-09-11-138-verifier.md) `review:2026-09-11-138-verifier`
|
||||
- [2026-09-11-streaming-stall-design-review](reviews/2026-09-11-streaming-stall-design-review.md) `review:2026-09-11-streaming-stall-design-review`
|
||||
- [2026-09-11-streaming-stall-plan-review](reviews/2026-09-11-streaming-stall-plan-review.md) `review:2026-09-11-streaming-stall-plan-review`
|
||||
- [保真缓存审查修复与1.4.0准备](reviews/2026-10-01-issue29-cache-review.md) `review:2026-10-01-issue29-cache-review`
|
||||
- [整分支审查: issue #14 熔断等待档](reviews/issue14-branch-review.md) `review:issue14-branch-review`
|
||||
|
||||
## schema (1)
|
||||
|
||||
@@ -160,3 +160,14 @@
|
||||
- [2026-09-09 13:42 UTC] 重建索引: 100 篇页面
|
||||
- [2026-09-09 16:49 UTC] 重建索引: 101 篇页面
|
||||
- [2026-09-09 18:01 UTC] 重建索引: 102 篇页面
|
||||
- [2026-09-10 16:48 UTC] 新增边: plan:2026-09-10-24-hedged-requests --implements--> design:2026-09-10-24-hedged-requests-design
|
||||
- [2026-09-10 16:48 UTC] 重建索引: 107 篇页面
|
||||
- [2026-10-01 17:52 UTC] 新增 design: OpenAI消息保真设计 (design:2026-10-01-issue29-openai-fidelity-design)
|
||||
- [2026-10-01 17:52 UTC] 新增 plan: OpenAI消息保真实现计划 (plan:2026-10-01-issue29-openai-fidelity)
|
||||
- [2026-10-01 17:52 UTC] 新增边: plan:2026-10-01-issue29-openai-fidelity --implements--> design:2026-10-01-issue29-openai-fidelity-design
|
||||
- [2026-10-01 17:52 UTC] 新增边: schema:llm-calls --implements--> design:2026-10-01-issue29-openai-fidelity-design
|
||||
- [2026-10-01 17:52 UTC] 重建索引: 119 篇页面
|
||||
- [2026-10-01 18:24 UTC] 新增 review: 保真缓存审查修复与1.4.0准备 (review:2026-10-01-issue29-cache-review)
|
||||
- [2026-10-01 18:27 UTC] 新增边: review:2026-10-01-issue29-cache-review --informs--> design:2026-10-01-issue29-openai-fidelity-design
|
||||
- [2026-10-01 18:27 UTC] 重建索引: 120 篇页面
|
||||
- [2026-10-02 02:23 UTC] 重建索引: 120 篇页面
|
||||
|
||||
@@ -31,3 +31,9 @@ date: 2026-07-20
|
||||
| 存储兼容 | 真实 PG 沙箱: auto 追加十列、manual 裁剪写入、旧行新列恒 NULL、新旧进程混写共存 | 2026-09-09 实跑 30 passed(见下方证据索引) |
|
||||
|
||||
本版**新增十列**(见 schema:llm-calls),不新建表、不新增依赖。证据索引见 `findings/2026-09-09-135-call-observability-validation.md`;覆盖度真实基线仍待首次生产运行填入,不写伪百分比。
|
||||
|
||||
## #29 验收增量（2026-10-01）
|
||||
|
||||
复用指标及 llm_calls，不另建表：error→正常 attempts=2、tool-only attempts=1、
|
||||
cache_hit attempts=0；协议失败不写缓存，取消不得遗留 permit/task。
|
||||
确定性证据位于 `tests/unit/test_openai_fidelity.py`；完整协议不新增遥测正文列。
|
||||
|
||||
@@ -202,3 +202,7 @@ stack = ExtractionProviderStack(
|
||||
| **AIMD 自适应并发**(库常量: 每源初始 8、429 削减 ×0.5、成功 +1/limit、下限 1、ceiling=max(64, 源级 max_concurrency)) | 冷启动每源并发从"无上限"变为 8 起步爬升——高吞吐下游首分钟吞吐低于旧行为;无 env 开关(韧性常量,同 jitter 系数先例),需要禁用者构造函数注入自定义 pacer |
|
||||
| 连败通道受健康证据抑制(窗口样本 ≥ min_calls 且失败率 < fail_rate 时 5 连败不开路) | CHS "连败必开"在高流量健康源上不再成立(防随机噪声误熔唯一好源);冷启动/低流量语义不变 |
|
||||
| 结构化重问缺省 1→2 | 解析失败时最多多一跳成本;`PGW_STRUCTURED_MAX_RETRIES=1` 可显式还原 |
|
||||
|
||||
## 1.3.10 影响核对(2026-10-14,#30/#31)
|
||||
|
||||
CHS 已把 `ResultInvalidError` 作终态(坏结果≠坏服务,熔断记成功),1.3.10 文本 length/过滤且无正文落该分类与既有语义同向,worker `_TERMINAL` 分支无需改;缺 `[DONE]` 而完整的流从此直接成功。
|
||||
|
||||
@@ -170,3 +170,7 @@ loop = AgentLoop(client, max_steps=...,
|
||||
| R7 | 内存限流在多进程(arq)下的口径须在文档/配置中显式警示(B7 过渡期语义),避免误配全局限额 | M1 |
|
||||
|
||||
以上 G1/G2 若按本文方向解决,GovDoc 全量迁移中业务代码(agent/workflow/govdoc api)对治理层的消费**零改动**,改动收敛于: 装配净新增、types.py/protocols.py/test_imports.py 三处改写、`.env` 改键。
|
||||
|
||||
## 1.3.10 影响核对(2026-10-14,#30/#31)
|
||||
|
||||
装配处 `retryable_exceptions=(TransientError, AllSourcesExhausted)`(§4)**不含** `ResultInvalidError`:文本 length/过滤且无正文改抛它后,AgentLoop 步级重试**不再**重抽该步——这正是本次修复的意图(确定性结局重抽只花钱)。业务侧若想对 length 截断做"加大 max_tokens 再试",须显式 except `ResultInvalidError` 并按异常消息原因码 `length_without_content` 分支;其余缺 `[DONE]` 而完整的流(#31)从此直接成功。
|
||||
|
||||
@@ -200,3 +200,7 @@ ocr = FrameOcrAdapter(OcrTextPort_from_env()) # 业务适配器包装库 OCR 端
|
||||
---
|
||||
|
||||
*不确定项声明*: 库侧 `from_env(role=...)`、OCR 装配工厂的具体 API 名称以 M1/M3 设计文档定稿为准，本文 §5.2/§6 中相应伪代码届时同步修订；`telemetry.db` 是否存在项目外的离线分析脚本消费方未能实测（项目内 grep 无读取方）。
|
||||
|
||||
## 1.3.10 影响核对(2026-10-14,#30/#31)
|
||||
|
||||
AgentLoop 注入的 `(TransientError, AllSourcesExhausted)`(§4 点 3)**不含** `ResultInvalidError`:文本 length/过滤且无正文改抛它后,步级重试不再重抽该步(意图如此)。需要"加大 max_tokens 再试"的业务须显式 except 并按原因码 `length_without_content` 分支。§保留项 3"缺 `[DONE]` 判瞬时、不写缓存"在 1.3.10 收窄为"无 finish 或 finish 后无实测 usage 才算截断";finish+实测 usage+干净 EOF 视完整。
|
||||
|
||||
@@ -228,7 +228,7 @@ generation_sink.append((wall_ms, stall_ms_i, stall_count_i))
|
||||
| --- | --- |
|
||||
| loader | `_load_hedge`(:745-769)扩读 `STALL_AFTER_S`:`_first` + `_cast` + `ensure_call_deadline`(origin 传实际命中键名),返回字典加 `"hedge_stall_after_s"` 键;未设 = None(关闭) |
|
||||
| 字段 | `GatewaySettings` 加 `hedge_stall_after_s: float \| None = None`;`_validate_hedge`(:382-392)扩传 |
|
||||
| 守卫(全部落进 `check_hedge_assembly` :772-849,签名加 keyword-only `stall_after_s` 参;**返回契约钉死(审查 B2)**:返回 `tuple[float | None, float | None]` = (归一化 after_s, 归一化 stall_after_s),`config.py:384` 与 `client.py:252` 两处调用点随之解构,`test_config.py:1174/:1184` 列入 T4 同步清单(`is None` 断言按新返回形态改写);**两阈值皆 None 才早退**——"同 `after is None` 早退形态"字面执行会让仅 stall 配置绕过守卫②③④,禁止) | ①值域 = `ensure_call_deadline` 同款(有限正数);②`stall_after_s ≥ min over sources of (inter_token_timeout_s or timeout_s)`(有效最小值,与 openai_compat.py:573 回落同款)→ **ValueError**(对冲窗永不开,装配期直接拒绝;stall 场景无非流式残留收益,warning 论证不足,N5);③`stall_after_s ≥ call_deadline_s`(两者皆设)→ ValueError(与 `after_s` 同款,config.py:825-828 邻域);④单源 scope 设阈值 → warning 允许(1.3.7 §5 同款);⑤**B4**:Embedding/OCR scope 装配 warning 落 `EmbeddingSettings.__post_init__`(:865-869 邻域)与 `OcrSettings`(新增 `__post_init__`):内嵌 gateway 的 `hedge_after_s` **或** `hedge_stall_after_s` 非 None → warning"对冲键仅对 chat scope 生效,本 scope 非流式静默退化"(1.3.7 `AFTER_S` 同病顺带补齐,缺陷修复不扩公共面);chat 侧装配 warning 明确不做(per-call stream,装配期无信号,B4 裁决) |
|
||||
| 守卫(全部落进 `check_hedge_assembly` :772-849,签名加 keyword-only `stall_after_s` 参;**返回契约钉死(审查 B2)**:返回 `tuple[float | None, float | None]`= (归一化 after_s, 归一化 stall_after_s),`config.py:384` 与 `client.py:252`两处调用点随之解构,`test_config.py:1174/:1184`列入 T4 同步清单(`is None` 断言按新返回形态改写);**两阈值皆 None 才早退**——"同 `after is None` 早退形态"字面执行会让仅 stall 配置绕过守卫②③④,禁止) | ①值域 = `ensure_call_deadline` 同款(有限正数);②`stall_after_s ≥ min over sources of (inter_token_timeout_s or timeout_s)`(有效最小值,与 openai_compat.py:573 回落同款)→ **ValueError**(对冲窗永不开,装配期直接拒绝;stall 场景无非流式残留收益,warning 论证不足,N5);③`stall_after_s ≥ call_deadline_s`(两者皆设)→ ValueError(与 `after_s` 同款,config.py:825-828 邻域);④单源 scope 设阈值 → warning 允许(1.3.7 §5 同款);⑤**B4**:Embedding/OCR scope 装配 warning 落 `EmbeddingSettings.__post_init__`(:865-869 邻域)与 `OcrSettings`(新增 `__post_init__`):内嵌 gateway 的 `hedge_after_s` **或** `hedge_stall_after_s` 非 None → warning"对冲键仅对 chat scope 生效,本 scope 非流式静默退化"(1.3.7 `AFTER_S` 同病顺带补齐,缺陷修复不扩公共面);chat 侧装配 warning 明确不做(per-call stream,装配期无信号,B4 裁决) |
|
||||
| client | `GatewayClient.__init__` 加 `hedge_stall_after_s: float \| None = None` keyword-only,:252-257 守卫调用扩传;RetryMW 构造(:264-283)传 `stall_after_s=` 归一化值(取守卫返回二元组第二元,B2);`from_settings`(:525 邻域)透传 |
|
||||
|
||||
### 3.6 T4:retry 编排改动(P2 唯一实现形态)
|
||||
|
||||
@@ -0,0 +1,345 @@
|
||||
---
|
||||
type: plan
|
||||
node_id: plan:2026-10-01-issue29-openai-fidelity
|
||||
title: OpenAI消息保真实现计划
|
||||
date: 2026-10-01
|
||||
---
|
||||
|
||||
# #29 OpenAI 消息保真实现计划
|
||||
|
||||
> 状态：计划及首轮代码独审已完成，P1/P2 均采纳；缓存空产物和测试双向依赖已修复，发布目标按人类最终指定改为 1.3.9（取代未发布的 1.4.0），最终独审与 T8 外部发布仍由父会话执行。
|
||||
> 设计：[批准方向的设计落实稿](../designs/2026-10-01-issue29-openai-fidelity-design.md)。
|
||||
> 目标：同一 chat 治理链返回可供下游继续工具对话的完整单 choice 协议结果，拒绝截断和 error 帧伪成功。
|
||||
> 方案：增加 response_mode 与嵌套 completion；协议解析与聚合内聚在 transport 内部模块，治理层仅传模式/搬结果；旧文本默认保持兼容。
|
||||
> 技术：Python 3.12+、frozen dataclass、httpx SSE、现有 asyncio 看门狗/对冲、pytest、真实 Redis；不加运行时依赖。
|
||||
|
||||
## 0. 工作区、审批与执行纪律
|
||||
|
||||
| 项目 | 已核验值 |
|
||||
| --- | --- |
|
||||
| 工作目录 | `/home/iomgaa/.config/superpowers/worktrees/PolyGateway/issue29-openai-fidelity` |
|
||||
| 分支 | `feat/issue29-openai-fidelity` |
|
||||
| 基线 | `0e29deac1a72bfee348ed2f8061ea2c33be217e8` / 1.3.8 |
|
||||
| 原工作区 | `/home/iomgaa/Projects/PolyGateway`，main 上已有未提交文档与 .pi，不得覆盖或夹带提交 |
|
||||
| 基线命令 | `conda run -n PolyGateway pytest tests/unit -q` |
|
||||
| 基线结果 | 1627 passed in 12.25s；仅单元基线，不代表集成/slow/新增功能通过 |
|
||||
|
||||
所有 Python 命令用 PolyGateway conda 环境；始终从上述隔离目录执行，确认 pytest 配置 pythonpath=src，避免误测主工作区 editable 安装。不要复制主树 `.env` 到受跟踪路径；需要真实验证时显式读取已有配置，不输出秘密。reference/ 不存在于新 worktree 的跟踪树，不为规划复制/修改参考仓。
|
||||
|
||||
技术方向、内部原创权属和 Apache-2.0 已获用户明确批准；细化设计与计划由独立 subagent 审查，Codex 不再调用。只在新产品/权利边界未获授权时暂停。父会话掌握审查、后续编码、合并/发布权限；当前任务不执行这些步骤。
|
||||
|
||||
本计划不涉及参考实现迁移，保真校验不适用；涉及既有移植流式看门狗的消费面，必须对照本库 `streaming.py`、1.3.8 stall 设计逐段保持其超时/取消/换算语义，不能借工具支持改算法。
|
||||
|
||||
## 1. 文件结构与职责锁定
|
||||
|
||||
| 路径（相对工作目录） | 动作与职责 |
|
||||
| --- | --- |
|
||||
| `src/polygateway/types.py` | 新 ResponseMode/OpenAIChatCompletion；末尾追加 ChatRequest.response_mode、两个响应 completion |
|
||||
| `src/polygateway/__init__.py` | 导出新公共类型；最终发布时同步版本 |
|
||||
| `src/polygateway/ports.py` | complete 增必填模式参数；说明工具进展与单 choice 契约 |
|
||||
| `src/polygateway/client.py` | chat 新模式校验、消息/overlay 快照、组合拒绝；不重写治理入口 |
|
||||
| `src/polygateway/transports/_openai_completion.py`（新） | 协议结构校验、每尝试聚合、非流式快照；无 I/O/计时 |
|
||||
| `src/polygateway/transports/openai_compat.py` | error 检查、解析器接线、投影/usage/空补全/DONE、统一进展事件 |
|
||||
| `src/polygateway/middleware/retry.py` | 模式传入、completion 搬运；无重试/对冲算法改写 |
|
||||
| `src/polygateway/middleware/cache.py` | 模式 key、嵌套序列化/重建、缺协议 miss、序列化降级 |
|
||||
| `tests/unit/test_openai_completion.py`（新） | 纯协议聚合与非流式校验的源命名测试 |
|
||||
| `tests/unit/test_openai_compat.py` | 真实 transport 的 SSE/非流式/error/raw/DONE/活性测试 |
|
||||
| `tests/unit/test_types.py`, `test_client.py`, `test_ports.py`, `test_cache.py` | 公共类型、校验、端口、缓存往返与兼容 |
|
||||
| `tests/unit/test_retry.py`, `test_hedge.py`, `test_stall_hedge.py`, `test_deadline.py`, `test_backpressure.py` | 模式传递、错误重试、工具活性/对冲、取消与结算 |
|
||||
| `tests/integration/test_governance_stack.py`, `test_redis_cache.py`, `test_redis_cross_connection.py` | 完整链路、真实缓存往返、必要 fake 签名适配 |
|
||||
| `tests/e2e/conftest.py` | 现有取证 transport 包装显式转传模式，不改变 thinking 矩阵判据 |
|
||||
| `tests/e2e/test_openai_tools_live.py`（新） | 受控少量真实工具双轮冒烟，独立 slow 用例 |
|
||||
| `tests/unit/test_package.py` | LICENSE 文件/包元数据回归 |
|
||||
| `LICENSE`, `pyproject.toml` | 标准 Apache-2.0 与打包元数据；不捆绑 reference/ |
|
||||
| `README.md`, `CHANGELOG.md`, `.env.example`, `research-wiki/ARCHITECTURE.md` | 新模式、限制、raw 配置、缓存迁移、同步桥接说明 |
|
||||
| `research-wiki/findings/2026-10-01-issue29-license-audit.md`（新） | 分发源码第三方来源核查证据与范围 |
|
||||
| `research-wiki/graph/edges.json`, `index.md`, `log.md`, `schemas/llm-calls.md`, `metrics/call-telemetry-coverage.md` | 审查通过后的设计/计划/复用遥测关系注册，不新增表或指标实体 |
|
||||
|
||||
其余测试若显式调用 complete 必须补参数，仅机械适配；不重构不相关 fixture。`thinking.py`/能力表/streaming.py 算法不在预期改动内。不要为“兼容 SDK”创建不存在的 openai_sdk.py。
|
||||
|
||||
## 2. 跨任务接口
|
||||
|
||||
T1 定义公共字段，T2–T5 均消费同一类型名，禁止再起 tool_response/raw_response 别名。
|
||||
|
||||
```python
|
||||
ResponseMode = Literal["text", "openai"]
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class OpenAIChatCompletion:
|
||||
"""单 choice 协议结果，message/usage 是独立 JSON 快照。"""
|
||||
message: dict[str, Any]
|
||||
finish_reason: str | None
|
||||
response_id: str | None
|
||||
usage: dict[str, Any] | None
|
||||
```
|
||||
|
||||
公共与端口变化均是追加参数/字段：
|
||||
|
||||
```python
|
||||
# GatewayClient.chat 的末尾 keyword-only 参数；其余参数保持原样。
|
||||
response_mode: ResponseMode = "text"
|
||||
# ChatRequest 末尾字段。
|
||||
response_mode: ResponseMode = "text"
|
||||
# Transport.complete 末尾必填 keyword-only 参数。
|
||||
response_mode: ResponseMode
|
||||
# TransportResult / LLMResponse 末尾字段。
|
||||
completion: OpenAIChatCompletion | None = None
|
||||
```
|
||||
|
||||
`build_cache_key` 在已有 keyword-only 参数之后增加 `response_mode: ResponseMode = "text"`，仅非 text 时参与摘要。缓存重建只依赖内核类型/本层校验，不 import transports；若复用协议类型重建的最低形态检查，把纯 JSON 快照检查放类型自身的具名构造方法，不把 transport 的 SSE 状态机下沉到内核。
|
||||
|
||||
T2 内部模块只由同目录 transport 消费，不成为公共导出。采用以下窄接口（内部类型在该模块定义）：
|
||||
|
||||
```python
|
||||
@dataclass(frozen=True)
|
||||
class ChatDelta:
|
||||
"""一帧提取结果；progress 表示真实生成进展。"""
|
||||
content: str
|
||||
reasoning_content: str
|
||||
progress: bool
|
||||
```
|
||||
|
||||
```python
|
||||
class ChatCompletionAccumulator:
|
||||
"""每次 transport 尝试独享的单 choice 聚合状态。"""
|
||||
def __init__(self, *, response_mode: ResponseMode) -> None: ...
|
||||
def add_chunk(self, chunk: dict[str, Any]) -> ChatDelta: ...
|
||||
def finish(self) -> OpenAIChatCompletion: ...
|
||||
|
||||
|
||||
def parse_chat_completion(body: dict[str, Any]) -> OpenAIChatCompletion: ...
|
||||
```
|
||||
|
||||
上述 `...` 是签名约定而非待交付占位实现。聚合器抛含判据的 TransientError（operation=chat）；openai_compat 负责补选中源上下文、复用有界摘要。聚合器不判断 DONE、不读时钟；transport 掌握线路完整性。text 模式可共用帧提取与进展识别，但不调用严格 openai finish，保持旧文本工具容忍边界。
|
||||
|
||||
## 3. 分任务与独立验收
|
||||
|
||||
### T0 — 审查与来源前置核查
|
||||
|
||||
- [x] T1 前已核查分发来源，见 findings/2026-10-01-issue29-license-audit.md；发现不兼容复制即停止。
|
||||
- [ ] 父会话安排全新上下文原生 subagent 审查设计/计划，重点：单 choice、未知增量字段、身份重复/冲突、raw/managed、缓存错误降级及取消。
|
||||
- [ ] 核对每条意见，修订文档并记录接受/不接受的理由；如改变用户已批边界，走主管决定，不静默改契约。
|
||||
- [ ] 在隔离树注册文档关系，复用 llm-calls schema/call-telemetry-coverage 指标；不在主树运行生成器。
|
||||
- [ ] 文档审查通过后才调用 commit skill 提交设计/计划；当前阶段禁止提交。
|
||||
|
||||
验证命令：`wc -l research-wiki/designs/2026-10-01-issue29-openai-fidelity-design.md research-wiki/plans/2026-10-01-issue29-openai-fidelity.md` → 分别 ≤400、≤1000；`git diff --check` → 无错误。Wiki 命令经 `conda run -n PolyGateway python .claude/tools/research_wiki.py --help` 核对实际参数后执行 add_entity/add_edge/rebuild_index；检查生成 diff 不改原有条目正文。
|
||||
|
||||
### T1 — 公共契约贯穿完整治理链
|
||||
|
||||
文件：types.py、__init__.py、ports.py、client.py、middleware/retry.py；单元 types/client/ports/retry；所有显式 fake complete 签名。
|
||||
|
||||
先补测试：默认 text 不变、新类型可导入、末尾带默认字段不破旧构造；非法 response_mode、openai+structured、n=2/0/True 在适用边界拒绝；保真消息与嵌套 overlay 脱离调用方容器，返回上一轮 assistant 和 role=tool 请求 JSON 逐字段相同。
|
||||
|
||||
实现：chat 校验放在 context/handler 前；选源后非法 source.extra_body.n 在 transport HTTP 前 RequestRejected；模式作为必填端口参数穿透重试/对冲，_build_response 原样搬 completion。不把模式塞进发给上游的 payload。
|
||||
|
||||
验收：调用级拒绝不发 HTTP；源级拒绝结算/释放正常；自定义 transport fake 看见准确模式；既有旧构造回归全绿。命令：
|
||||
|
||||
```bash
|
||||
conda run -n PolyGateway pytest tests/unit/test_types.py tests/unit/test_client.py tests/unit/test_ports.py tests/unit/test_retry.py -q
|
||||
```
|
||||
|
||||
先红测试须为行为断言或缺失 API 的明确证据，记录基线 SHA 与测试名；绿后提交点：`feat: add explicit OpenAI response contract`。
|
||||
|
||||
### T2 — 内聚协议解析器与 error 帧修复
|
||||
|
||||
文件：新增 _openai_completion.py、openai_compat.py；新增 test_openai_completion.py，扩展 test_openai_compat.py。
|
||||
|
||||
补测 SSE/非流式/缓存缺 role、非 assistant role；合法 role-only 起始帧后工具成功。先红测试至少含下表各组；复用现有 SSE/MockTransport，不引入第二套 HTTP fake 框架。
|
||||
|
||||
| 组 | 输入与精确预期 |
|
||||
| --- | --- |
|
||||
| 并行工具 | 2 工具交错 index；同帧两工具；name/arguments 分片；空白/Unicode/引号逐字相等；最终按 index 排序 |
|
||||
| 身份 | id/type 同值重复只保留一次，冲突失败；缺 id/type/name/arguments、重复 id、bool/负数 index、非 function 类型失败 |
|
||||
| 文本 | 同帧正文+推理均保留；缺省/null/空串区别；原消息 think 标签不剥，旧投影仍剥 |
|
||||
| envelope | 顶层数组/null、choices/delta/tool_calls 非容器、坏字段类型、多 choice/非零 choice index 均受控失败 |
|
||||
| 非流式 | 完整消息、扩展字段、usage/finish/id 全保留；工具参数不做业务 JSON 修复；原响应对象改动不影响快照 |
|
||||
| error | 首帧 error、正文后 error+usage+DONE、error=null、error={}、salvage 配置下 error 都立即失败；text/openai 两模式参数化 |
|
||||
|
||||
复用现有 summarize_body/compose_message，断言异常与遥测诊断有界，不打印工具参数正文。默认文本模式不因无用工具字段的严格 finish 校验而新增失败，但不吞顶层 error。无新 HTTP 状态映射。
|
||||
|
||||
命令：`conda run -n PolyGateway pytest tests/unit/test_openai_completion.py tests/unit/test_openai_compat.py tests/unit/test_http_error_body.py -q` → PASS；提交点：`fix: preserve chat deltas and reject upstream error frames`。
|
||||
|
||||
### T3 — 完成语义、活性与非流式接线
|
||||
|
||||
文件：openai_compat.py、ports.py docstring；test_openai_compat.py、test_streaming.py。
|
||||
|
||||
先红：tool-only + DONE 成功 attempts=1；空文本且空工具失败；正文+坏工具不成功；openai 缺 DONE 即使 missing_done=salvage 仍失败；text salvage 保持；finish_reason=length 原样交回，不解析 arguments。非流式工具同样成功，两事件永不置位、ttft/stall=None。
|
||||
|
||||
按设计接线：一帧一进展，同帧多个字段只记一个 chunk_time；真正非空工具增量/首次身份触发事件，重复身份和 role/usage/finish/空片段不触发。看门狗仍包进展迭代器，stall 派生/净额取整不动。
|
||||
|
||||
测试以受控 Event/FakeClock 驱动，避免用几十毫秒竞争制造脆弱测试：持续工具片段撑过 TTFT/inter-token；只有注释/usage 必超时；工具首进展设置 first_token_event；真实停顿计入 max_inter_token/stall，两字段与正文相同口径。
|
||||
|
||||
命令：`conda run -n PolyGateway pytest tests/unit/test_openai_completion.py tests/unit/test_openai_compat.py tests/unit/test_streaming.py -q` → PASS；提交点：`feat: complete tool responses with unified stream liveness`。
|
||||
|
||||
### T4 — 完整协议缓存往返与隔离
|
||||
|
||||
文件：middleware/cache.py；test_cache.py、tests/integration/test_redis_cache.py。
|
||||
|
||||
先红测试：同消息 text/openai key 不同、旧默认 text key 字节不变；tools、tool_choice、raw effort、tool result、assistant arguments 改动均 miss；相同请求完整 completion round-trip，非流式扩展字段不丢，message 的 null/缺省可区别；usage 缺省/null 均为 None；openai 缺 completion/null/坏 message/坏工具条目 miss 后回源，不冒 dict 假装 dataclass。
|
||||
|
||||
检查命中历史 response_id 不变、本次 call_id 重建、attempts=0、cache_hit=true、cost=0；变更一次命中消息不污染下一次命中；旧 text 缓存继续可读。失败路径无 set；序列化/backend set 抛错 warning 后仍返回结果；CancelledError 原样穿透。
|
||||
|
||||
实现保真重建校验不能 import transport（import-linter 必守）；内核值类型可提供纯值构造校验，协议拼接算法只保留在 transport；避免两份 SSE/tool 聚合逻辑。
|
||||
|
||||
命令：
|
||||
|
||||
```bash
|
||||
conda run -n PolyGateway pytest tests/unit/test_cache.py -q
|
||||
conda run -n PolyGateway pytest tests/integration/test_redis_cache.py -q
|
||||
conda run -n PolyGateway lint-imports
|
||||
```
|
||||
|
||||
真实 Redis 专用测试 namespace，沿既有 fixture 清理自有 key，不 flush 共享 DB；未配置 skip 必须记录为未覆盖，发布前补实测。提交点：`fix: isolate and round-trip OpenAI completion caches`。
|
||||
|
||||
### T5 — 完整链路、对冲、取消与遥测不变量
|
||||
|
||||
文件：test_retry.py、test_hedge.py、test_stall_hedge.py、test_deadline.py、test_backpressure.py、tests/integration/test_governance_stack.py、test_redis_cross_connection.py、tests/e2e/conftest.py；生产 retry 仅修必要搬运漏项，不改算法。
|
||||
|
||||
先红→绿证据须覆盖真实 OpenAICompatTransport 接入 GatewayClient，而不是只用返回预制 completion 的 fake 证明解析成功：
|
||||
|
||||
| 场景 | 断言 |
|
||||
| --- | --- |
|
||||
| 第一次部分正文/工具→error→DONE，第二次正常 | 只返回第二次 completion，attempts=2；第一次 error 的字段不会污染结果或缓存 |
|
||||
| 工具持续进展 | 首 token 对冲及时止窗，中段 event 复位，未错误触发 |
|
||||
| 真沉默触发对冲 | 副路完整工具结果胜出，返回自己的 id/usage，输家不泄露半成品 |
|
||||
| primary 超时但副路尚在运行 | 不提前判总失败；两败仍只烧一次超级尝试预算 |
|
||||
| 流中/准入中/退避中取消与 deadline | CancelledError/CallDeadlineExceeded 类型保留，permit/inflight/task 收口，TPM 保守结算 |
|
||||
| 观测与降级 | 正常/失败/cache_hit 遥测沿单 helper；attempt 行/terminal 行口径不变；后端写失败不影响结果 |
|
||||
|
||||
命令：
|
||||
|
||||
```bash
|
||||
conda run -n PolyGateway pytest tests/unit/test_retry.py tests/unit/test_hedge.py tests/unit/test_stall_hedge.py tests/unit/test_deadline.py tests/unit/test_backpressure.py -q
|
||||
conda run -n PolyGateway pytest tests/integration/test_governance_stack.py tests/integration/test_redis_cross_connection.py -q
|
||||
```
|
||||
|
||||
不删除“不需要失败计费”对应的现有失败遥测/attempts/结算；本任务不新增失败 token 取证。提交点：`test: cover governed tool retries hedges and cancellation`。
|
||||
|
||||
### T6 — 来源审计、Apache-2.0 与用户文档
|
||||
|
||||
文件：LICENSE、pyproject.toml、test_package.py、新 license-audit finding、README、CHANGELOG、.env.example、ARCHITECTURE；设计/计划 Wiki 注册关系。
|
||||
|
||||
| 工作 | 验收 |
|
||||
| --- | --- |
|
||||
| 来源审计复核（初审前置 T0） | 查 tracked 分发文件的移植/参考/版权注释及具体片段；列内部原创授权记录，外部只读 reference 的路径/许可/实际使用范围；未发现不等于法律认证 |
|
||||
| 第三方义务 | 对实际复制片段核实许可、保留通知；发现 AGPL 不兼容复制须上报，不借用户授权覆盖第三方 |
|
||||
| LICENSE | 使用标准 Apache-2.0 全文，不自行重写；版权归属沿项目元数据，不猜用户真实姓名；NOTICE 仅在实际需要时新增 |
|
||||
| 包元数据 | 当前 setuptools>=68，采用 `license = {file = "LICENSE"}` 兼容现有后端；验证 wheel/sdist 包含 license，不为 PEP 639 单独提高构建依赖 |
|
||||
| 文档 | 新 chat 示例 ≤15 行；response_mode 与 raw 所有权分开；单 choice、未知 SSE 方言失败、非流式、length、无 DONE 不打捞、缓存旧值迁移、取消/线程桥接限制写清 |
|
||||
|
||||
`.env.example` 只解释 raw-only 必须去掉源级受管意图，不加模式 env 键。README 应说明“完整协议结果”仅四字段及已定义 SSE 字段，不能暗示返回所有顶层 logprobs/created 等；上游模型使用 LLMResponse.model_reported，不把 model 配置别名当真实版本。
|
||||
|
||||
ARCHITECTURE 更新 §5 类型/签名、§6.2 空补全与 error、§7.1 DONE 与工具协议、§7.2/7.6 工具活性、§7.5 缓存维度，并明确这些只是批准方向的增量，不引入 Agent Loop。站点下线，无具体 Wiki 页面可同步。
|
||||
|
||||
验证：`conda run -n PolyGateway pytest tests/unit/test_package.py -q` 先红后绿；`git diff --check`；构建验收见 T8。提交点：`docs: document faithful chat and Apache-2.0 distribution`。
|
||||
|
||||
### T7 — 少量真实工具冒烟与独立验证
|
||||
|
||||
新增 tests/e2e/test_openai_tools_live.py，复用 tests/e2e/conftest.py 的请求取证/输出机制，不为本次重跑整个 thinking 矩阵。fixture 的 complete 显式转传 response_mode 是机械接线，不改取证判分算法。
|
||||
|
||||
测试使用通用无业务领域的函数，如 echo_value；强制工具选择但工具在测试内执行纯函数，库本体不执行。流式、非流式各一次工具请求，随后带原 assistant+tool 消息做第二轮；断言 ID、finish、arguments 可用和请求消息相等。并行两工具完整逐字拼接的硬门由确定性 fixture 保证，不把模型偶尔不发两个工具解释为库聚合正确。
|
||||
|
||||
真实测试标 slow/requires_llm，预算与超时不紧于现有 `.env` 生产配置。raw=max 使用已配支持模型的 raw-only 源；不发明新模型/API。Markdown 安全报告记录模式、源/model_reported、attempts、finish、工具数、结果/失败原因；不输出 key、敏感消息或完整参数。费用/网络异常如实呈现，不宽泛 skip。
|
||||
|
||||
命令：
|
||||
|
||||
```bash
|
||||
conda run -n PolyGateway pytest -m slow tests/e2e/test_openai_tools_live.py tests/e2e/test_smoke_gateway.py -q
|
||||
make ci
|
||||
```
|
||||
|
||||
全套件由当前前台执行；若预计长跑需 tmux，禁用缓冲、保存原退出码，不在 pytest 末尾接管道。生成唯一日志路径 `tests/outputs/issue29/<任务>-<red|green>-<时间>.log`，不提交产物。无新增功能代码的当前阶段仅跑过单元基线，不预填完成框。
|
||||
|
||||
父会话安排全新上下文 verifier 独立查实际 diff 与测试输出。若修改了准入/取消/退避生产逻辑，补 `tests/integration/test_redis_governance_time.py` 和 `test_redis_cross_connection.py` 对应 slow 子集；仅机械传参/协议解析时记录无 Lua/退避算法交集的理由。慢测试 skip/失败不得当通过。
|
||||
|
||||
- [ ] 审查员检查依赖铁律、未知字段策略、旧文本回归与大对象保留成本。
|
||||
- [ ] 每项行为能链接红绿日志、命令、SHA、退出码；基线失败必须归因，不能“重跑绿了”掩盖。
|
||||
- [ ] 合并前测试/独立审查通过；提交均调用 commit skill，不夹带主树既有文档差异。
|
||||
|
||||
### T8 — 发布与 issue 外部验收（父会话持有，不由本设计任务执行）
|
||||
|
||||
发布版本已由人类最终指定为 1.3.9（取代未发布的 1.4.0），不能在规划中冒称已发布。遵守 CLAUDE.md §4.4.1 全步骤：README/CHANGELOG/两处版本先完成 → 合并 main/push → 合并后 lint/全套件/相交 slow → tag push → 构建/twine check → registry 上传 → 实际下载核验 → Release/挂库/包页核验。
|
||||
|
||||
| 发布门 | 可接受证据 |
|
||||
| --- | --- |
|
||||
| 构建 | `conda run -n PolyGateway python -m build` 和 twine check 成功；解包核 LICENSE、许可元数据、completion 类型/参数/解析器均在产物中 |
|
||||
| 安装 | 在独立临时环境从私有索引下载/安装已发布版本；必要时 --no-build-isolation 避免索引无 setuptools；核来源/hash，不误用本地 editable |
|
||||
| 外部页面 | registry 包正文与仓库链接、Gitea Release/tag 实际可见；不以 POST 返回码代替最终状态 |
|
||||
| 下游 | 以发布包运行不含业务逻辑的 tool 双轮接入验收；给 dissect3 说明同 loop 线程桥接和 raw-only 配置，不在本计划越权修改其业务仓 |
|
||||
| 关闭 issue | 再查询 open issue，#29 评论附版本/验收/限制与缓存迁移说明后关闭；若出现新 issue 单独定范围，不假称本计划涵盖未来问题 |
|
||||
|
||||
## 4. 自审清单与残余边界
|
||||
|
||||
| 需求 | 覆盖任务 |
|
||||
| --- | --- |
|
||||
| 工具双并行、消息往返、raw=max、非流式 | T1–T3、T7 |
|
||||
| error+DONE 所有模式失败、attempts=2 | T2、T5 |
|
||||
| 缺 DONE 不 salvage 工具、length 不修复 | T3 |
|
||||
| 活性、对冲、取消、准入/结算 | T3、T5 |
|
||||
| 完整缓存、模式隔离、旧默认 key 与污染迁移 | T4、T6 |
|
||||
| Apache 授权与第三方来源、分发验证 | T6、T8 |
|
||||
| 测试先红后绿、独立审查、外部发布完成 | 各任务、T7、T8 |
|
||||
|
||||
当前残余：首轮代码独审已完成，修复后待父会话最终复核；严格 SSE 方言会拒绝未定义增量字段，不承诺任意 OpenAI 兼容网关；旧文本毒化缓存只能由使用方迁移身份；公共 dataclass 嵌套 JSON 可变，靠快照隔离而非深冻结；模型真实冒烟依赖外部可用性。以上均需在文档和验收中如实保留，不当成全部自动解决。
|
||||
|
||||
## 5. 本轮实施记录（2026-10-01，未发布）
|
||||
|
||||
P1 最终 assistant role、P2 来源核查前置均已采纳，证据见来源核查 finding。
|
||||
T1–T6 代码/文档/许可已落实；T7 工具真实冒烟、Redis、质量门已执行，独立代码审查由父会话接续；T8 禁止本 worker 执行。
|
||||
|
||||
| 验证 | 实际结果/证据 |
|
||||
| --- | --- |
|
||||
| 基线红 | tests/outputs/issue29/baseline-red.log：error+DONE 未抛、双文本丢 reasoning、模式 API 缺失，3 failed |
|
||||
| 扩展红绿 | expanded-red.log 19 failed（git archive 0e29dea 的 src，不改主树）；expanded-green.log 同19 passed |
|
||||
| 防御红绿 | defense-red.log 3 failed：usage 裸错误/空 tool_calls 丢失；defense-green.log 同3 passed |
|
||||
| 全量 | ci-final.log + ci-final.exit=0：1812 passed、23 skipped、110 deselected，覆盖率95%；之后仅增测试/文档，无生产变更 |
|
||||
| 最后定向 | targeted-final.log：264 passed，包含后增的非流式事件/取消/managed冲突/名称分片回归 |
|
||||
| 真实缓存 | test_redis_cache.py 6 passed，专用随机 key，无共享数据清理 |
|
||||
| 真实工具 | live-final.log + live-final.exit=0：流式/非流式双轮2 passed，101.34s；安全Markdown在 tests/outputs/issue29/live |
|
||||
| 构建 | /tmp/pgw-issue29-dist-final 的 wheel/sdist、twine check、LICENSE/源码字节核验通过；仍1.3.8本地测试产物，绝非发布 |
|
||||
|
||||
23 skips 为17个已转专用时间语义的 Redis 契约变体、6个缺私有图像语料的 OCR 测试；未把这些当本次通过。110 deselected 为默认 slow；未重跑全模型 thinking 矩阵，因为只机械转传端口参数、未改其判据或能力表。
|
||||
|
||||
未提交代码，供父会话独立验收完整工作区。conda 启动有基础环境 RequestsDependencyWarning（pytest本体无该告警），pi-lens 使用错误环境时的缺包/枚举提示已用 conda 实证排除，不据此改变依赖。
|
||||
Wiki add_entity 会覆写无frontmatter同名文件，现场检查发现后已从本会话原始 tool-write 精确恢复两文档，并加 frontmatter 后保留 P1/P2 修订；没有丢失设计内容。
|
||||
|
||||
补充最终证据：unit-final.log 1678 passed（23.84s），smoke.log + smoke.exit=0 为既有真实 chat 冒烟4 passed（97.18s）；未跑昂贵全模型矩阵。源代码最后变更早于 ci-final，后续只增测试/文档；最后单元覆盖全部新增测试。
|
||||
|
||||
## 6. 审查修复与1.4.0准备（2026-10-01，未发布）
|
||||
|
||||
已读取首轮独立报告并核验采纳 P2 空产物缓存、Minor 测试双向依赖，详见 [审查处置](../reviews/2026-10-01-issue29-cache-review.md)。本轮只在隔离 feature 树写入，主树既有脏文档未改；不合并、不 push/tag/上传、不关issue。
|
||||
|
||||
| 本轮命令/证据（日志均在 tests/outputs/issue29，不提交） | 实际结果 |
|
||||
| --- | --- |
|
||||
| 新缓存回归修复前：review-cache-red.log | 10 failed、1 passed：五种无效产物×两种缓存投影误命中；合法tool-only通过 |
|
||||
| 四模块定向：review-cache-green.log | 268 passed，17.71s；包含11项新增缓存回归 |
|
||||
| 真实Redis+包测试：review-redis-package.log | 13 passed，2.66s（6 Redis、7包） |
|
||||
| 首次 lint / make ci | 测试import顺序失败；已修正，不作为通过证据 |
|
||||
| tmux make ci：review-ci-final.log / .exit=0 | 1827 passed、23 skipped、110 deselected，317.28s；95%覆盖；格式102文件、ruff通过、依赖契约1 kept/0 broken |
|
||||
| 远端 tags 与 registry simple | 最大均1.3.8，没有1.4.0；版本两处改1.4.0，README约束>=1.4.0,<2，CHANGELOG定版 |
|
||||
| build / twine / 解包：review-build-final.log、review-twine.log、review-artifacts.log | 1.4.0 wheel/sdist 均通过；所有Python源码、README、标准LICENSE逐字相同，Version/License-File正确且无reference |
|
||||
| README数字断言 | inspect.signature 实测 TelemetryRecorder.record_llm_call 为38字段，未凭记忆更新 |
|
||||
|
||||
wheel SHA256 `3186d01d7710c3b5ef727b59f95e8c2db0821277a79491ffb913dd2ce34a888d`；sdist SHA256 `b254dedf65d25673cf57986a613a1f4e9895da8b5be1e6ee241f00065a95ad90`。这些是隔离树本地构建，不是registry产物。解包探针首次使用email默认ASCII解码比较中文README产生误报，改为METADATA正文原始字节比较后通过，未改包来迎合错误探针。
|
||||
|
||||
跳过项仍为17个独立slow Redis时间变体及6个缺私有图像语料OCR；110 slow未选中。本轮不重复付费网关：复用前轮流式/非流式工具双轮2通过和chat冒烟4通过，当前生产改动只统一空产物判据，工具/文本正常行为已有定向与全套件证明；合并后slow发布门由父执行。构建有setuptools许可表格弃用提醒（兼容setuptools>=68设计），并有基础conda RequestsDependencyWarning；均不等于当前构建或测试失败。
|
||||
|
||||
按commit skill提交feature全部实现、修复、许可与发布准备，原main脏文件及运行产物不纳入。提交后交父最终独立复核；T8外部发布尚未完成，不能提前关闭#29。
|
||||
|
||||
## 7. 版本定案与历史文档归档（2026-10-01 EDT / 2026-10-02 UTC）
|
||||
|
||||
用户最终指定本次发布 __1.3.9__，取代尚未打 tag/上传的 1.4.0。上节 1.4.0 构建散列、测试结果与历史提交标题均是当时实证，保留原样，不冒充 1.3.9 产物。README 安装约束、能力标题、CHANGELOG 与两处版本同步；自定义 `Transport.complete(response_mode=...)` 适配要求及旧缓存更换 namespace/salt 提醒保持不变。CHANGELOG 使用执行环境本地日期 2026-10-01（EDT），知识库时间戳明确使用 UTC。
|
||||
|
||||
历史六文档独立归档提交 `ce10881`；采纳独审发现，仅补 #24 implements 边缺少的 plan/design 两节点。验证旧新节点/边/日志并集完整、120 个索引链接与计数一致、三文件仅空白/空引用格式、无冲突标记。剩余 15 个历史未注册端点以及 wiki lint 的 15 条孤立/稀疏提示均未扩大处理。原始备份 `/tmp/pgw140-release` 及 stash 保留。
|
||||
|
||||
本轮只准备与本地构建，不合并、不 push/tag/上传、不关闭 issue；后续独审及发布外部验收仍是硬门。相关功能代码未变，可复用 `/tmp/pgw140-release/main-ci.log` 的 1828 项通过、95% 覆盖及 `main-slow.log` 的 6 项真实网关通过（205.81s）；本轮另执行包/协议定向、质量检查和 1.3.9 构建解包验证。
|
||||
|
||||
| 本轮证据（`/tmp/pgw139-prepare/`） | 实际结果 |
|
||||
| --- | --- |
|
||||
| source.log / tests.log | 显式 `PYTHONPATH=/home/iomgaa/Projects/PolyGateway/src` 确认源码位置及1.3.9；包+缓存+协议四模块276 passed，12.43s，无新增行为测试 |
|
||||
| check.log | `make check` 格式、ruff、依赖契约通过，1 kept/0 broken |
|
||||
| docs-validation.log / wiki-lint.log | #24两端点补齐；原新记录保全、120链接计数通过；存量15个端点缺口及15条lint提示未清理 |
|
||||
| remote-tags.txt / registry-simple.html | 2026-10-02 UTC读取远端tag与匿名simple均无1.3.9/1.4.0，无版本冲突；发布前仍须复查 |
|
||||
| build.log / twine.log / artifacts.log / unpacked-import.log | 1.3.9 wheel/sdist构建、twine及全Python源码/README/LICENSE逐字核验通过；解包路径独立导入成功，38遥测字段实测不变 |
|
||||
|
||||
本地 wheel SHA256 `45306557152fd44f8135928041e47924834c3b4039c586f72d521f51b4590dd3`；sdist SHA256 `8f455973e7fef71811e2b86f5a14cb03469d893ac9720b902f522d2b1a8dcd40`。产物位于 `/tmp/pgw139-prepare/dist`，不是已发布包。构建仅有已知许可证表格弃用提示、conda基础环境依赖警告；不为清警告增加依赖。
|
||||
@@ -0,0 +1,230 @@
|
||||
---
|
||||
type: plan
|
||||
node_id: plan:2026-10-14-issue30-31-completion-verdict
|
||||
title: 统一完成判定实现计划(#30/#31)
|
||||
date: 2026-10-14
|
||||
---
|
||||
|
||||
# #30/#31 统一完成判定实现计划
|
||||
|
||||
**目标**: 按[设计](../designs/2026-10-14-issue30-31-completion-verdict-design.md)(下称"设计")实现统一完成判定,修复 #30/#31 并发布 1.3.10。
|
||||
|
||||
**方案概述**: 在 `types.py` 内核放一组纯判定函数(流完整性 → 结局分类 → 可缓存),transport 两条路径、CacheMW 读写共用;聚合器改为 null 优先 + 未知字段无损合并;`LLMResponse`/`TransportResult` 追加 `finish_reason`/`stream_end`,遥测加 `stream_end` 列。
|
||||
|
||||
**技术**: Python 3.12、httpx、pydantic、pytest(asyncio)、SQLite/PG 遥测、Redis 缓存。环境 `conda run -n PolyGateway`。
|
||||
|
||||
本计划不涉及参考实现迁移,保真校验不适用。
|
||||
|
||||
## 0. 执行纪律
|
||||
|
||||
- 分支 `fix/issue30-31-completion-verdict`。每个任务一次提交,经 `commit` skill;pre-commit 钩子会跑全套件 + ruff + "改动触及函数复杂度 < C",故**每个提交点必须全绿**,改到的既有高复杂度函数(`add_chunk` F42、`_complete_stream`/`_complete_once` C、`_rehydrate` C、`OpenAIChatCompletion.__post_init__` D)须在同一提交内拆到 B 及以下;钩子(2026-10-14 经人类同意改为只拦"本次改动触及"的块,存量 ≥C 降为告警,提交 5d2ad40)按 radon 块判定,**类块**(`ChatCompletionAccumulator` C16、`OpenAIChatCompletion` D24)同样须降到 B 及以下。不改 `OpenAICompatTransport.complete()`(C14),新增逻辑一律放在拆出的 helper 中。
|
||||
- 每个任务的统一验证(与钩子一致): `conda run -n PolyGateway pytest tests/ -q`(含 integration,本地有 Redis/PG 时真跑)+ `conda run -n PolyGateway ruff check src` + `conda run -n PolyGateway radon cc -n C <本任务改动文件>`(输出必须为空,或仅含本任务未触及的存量块)。各任务列出的子集命令只作开发期快速回路。
|
||||
- 测试结果门: 每个任务的新增/改写测试先在未改实现的代码上运行并记录**失败**输出(粘贴进提交说明正文的"Red:"一行,写明失败用例名与断言),再实现至通过。
|
||||
- 后台长跑命令末尾禁止接管道(CLAUDE.md §3)。
|
||||
|
||||
## 1. 文件结构
|
||||
|
||||
| 文件 | 职责变化 |
|
||||
| --- | --- |
|
||||
| `src/polygateway/types.py` | 新增 `StreamEnd`、`FinishClass`、`_OutputSummary`、`_Verdict` 与七个纯函数(§2 列出;另 `_effective_finish`);`TransportResult`/`LLMResponse` 末尾追加两字段;`OpenAIChatCompletion` 接受 `tool_calls: None` 并复用 `_tool_snapshot_ok` |
|
||||
| `src/polygateway/__init__.py` | 导出 `StreamEnd`;`__version__` → 1.3.10(T6) |
|
||||
| `src/polygateway/transports/_openai_completion.py` | 聚合器: null 优先、未知字段合并、标签键、冲突路径、finish/usage 位置记录、reasoning 别名;`parse_chat_completion` 容忍 null |
|
||||
| `src/polygateway/transports/openai_compat.py` | 两条路径改走判定;有界告警节流;`finish_reason`/`stream_end` 填充;投影别名 |
|
||||
| `src/polygateway/middleware/retry.py` | `_build_response` 搬运两字段 |
|
||||
| `src/polygateway/middleware/cache.py` | 写/读按 `_is_cacheable`;`stream_end` 校验;finish 回退 |
|
||||
| `src/polygateway/ports.py` | `record_llm_call` 追加 `stream_end` |
|
||||
| `src/polygateway/middleware/telemetry.py` | `_AttemptUsage.stream_end`、`_record` 搬运、两 emit 显式 None |
|
||||
| `src/polygateway/telemetry/schema.py`、`sqlite.py`、`postgres.py` | 新列 + 补列 |
|
||||
| tests | 新增 `tests/unit/test_completion_verdict.py`;改写/扩充 `test_openai_completion.py`、`test_openai_fidelity.py`、`test_openai_compat.py`、`test_cache.py`、`test_telemetry.py`、`test_types.py`、`test_ports.py`、`tests/integration/test_postgres_telemetry.py` 及各 `record_llm_call` 替身 |
|
||||
| 文档 | README、CHANGELOG、ARCHITECTURE §6.2/§7/§14、1.3.9 设计修订指针、`schemas/llm-calls.md`、`migrations/` 三份、pyproject 版本 |
|
||||
|
||||
## 2. 跨任务接口(T1 定义,后续任务只消费)
|
||||
|
||||
```python
|
||||
StreamEnd = Literal["done", "eof_after_finish", "salvaged"]
|
||||
FinishClass = Literal["natural", "truncated", "filtered", "upstream_error", "unknown", "absent"]
|
||||
|
||||
def _classify_finish(value: str | None) -> FinishClass: ...
|
||||
def _tool_snapshot_ok(message: Mapping[str, Any]) -> bool: ...
|
||||
def _stream_is_complete(
|
||||
*, done: bool, finish_reason: str | None, usage_after_finish: bool, usage_measured: bool
|
||||
) -> StreamEnd | None: ...
|
||||
```
|
||||
|
||||
```python
|
||||
@dataclass(frozen=True)
|
||||
class _OutputSummary:
|
||||
any_output: bool # 设计 §4.3 "任何产物"
|
||||
body_output: bool # 设计 §4.3 "正文产物"
|
||||
tools_present: bool # 至少一个非 null 工具条目(仅保真有意义)
|
||||
tools_ok: bool # tools_present 时 _tool_snapshot_ok 结果;无工具恒 True
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class _Verdict:
|
||||
deliver: bool
|
||||
error_kind: Literal["transient", "result_invalid"] | None # deliver 时为 None
|
||||
code: str | None # 设计 §4.3 原因码
|
||||
```
|
||||
|
||||
```python
|
||||
def _summarize_text(content: str, thinking: str) -> _OutputSummary: ...
|
||||
def _summarize_message(message: Mapping[str, Any], projected_content: str) -> _OutputSummary: ...
|
||||
def _judge_outcome(*, mode: ResponseMode, summary: _OutputSummary, finish: FinishClass) -> _Verdict: ...
|
||||
def _is_cacheable(
|
||||
*, mode: ResponseMode, content: str, finish_reason: str | None,
|
||||
stream_end: str | None, completion: OpenAIChatCompletion | None,
|
||||
) -> bool: ...
|
||||
```
|
||||
|
||||
缓存读写共用(T1 定义,T4 消费),顶层优先、回退 `completion.finish_reason`,避免读写口径分叉:
|
||||
|
||||
```python
|
||||
def _effective_finish(finish_reason: Any, completion: OpenAIChatCompletion | None) -> str | None: ...
|
||||
```
|
||||
|
||||
`types.py` 无 `from __future__ import annotations`: `StreamEnd`/`FinishClass` 必须定义在 `TransportResult`/`LLMResponse` 之前。
|
||||
|
||||
聚合器对外只读属性(T2 定义,T3 消费): `finish_reason: str | None`、`finish_seen: bool`、`usage_after_finish: bool`、`conflicts: frozenset[str]`(归一路径)、`raw_message() -> dict[str, Any]`(未校验的合并消息深拷贝,含按 index 排序组装的 `tool_calls`,与 `finish()` 同一组装函数,供 `_tool_snapshot_ok` 判定)、`finish() -> OpenAIChatCompletion`(保真快照,校验失败抛 Transient,与 1.3.9 同)。`ChatDelta` 追加字段 `reasoning: str`(别名片段,默认 `""`)。
|
||||
|
||||
## 3. 任务
|
||||
|
||||
### T1 内核判定函数与公共字段
|
||||
|
||||
- 文件: `src/polygateway/types.py`、`src/polygateway/__init__.py`;测试 `tests/unit/test_completion_verdict.py`(新)、`tests/unit/test_types.py`、`tests/unit/test_package.py`(导出)。
|
||||
- 行为:
|
||||
- `_classify_finish` 按设计 §4.1 表,大小写敏感;None → `absent`。
|
||||
- `_tool_snapshot_ok`: `tool_calls` 缺省或 None → True;否则必须是 list,每个非 None 元素满足 1.3.9 规则(非空唯一 id、`type == "function"`、非空 `function.name`、字符串 `arguments`);list 中 None 元素跳过。`OpenAIChatCompletion.__post_init__` 改为调用它(并拆分以降复杂度),`tool_calls: None` 合法且原样保留键。
|
||||
- `_stream_is_complete`: `done` → `"done"`;否则 `finish_reason is not None and usage_after_finish and usage_measured` → `"eof_after_finish"`;否则 None。
|
||||
- `_summarize_text`: any = `content != "" or thinking != ""`;body = `content.strip() != ""`;tools_present False、tools_ok True。
|
||||
- `_summarize_message`: any = 递归遍历 message 中除 `role`、`tool_calls` 外所有值存在非空字符串,或 tools_present;tools_present = `tool_calls` 为含非 None 元素的 list;tools_ok = `_tool_snapshot_ok(message)`;body = `projected_content.strip() != ""` 或 (tools_present 且 tools_ok)。
|
||||
- `_judge_outcome`: 严格按设计 §4.3 九行首匹配;原因码字面量: `upstream_finish_error`、`tool_truncated`、`tool_incomplete`、`length_without_content`、`filtered_without_content`、`empty_completion`。行 2 仅 `mode == "openai"` 时生效。
|
||||
- `_is_cacheable`: 设计 §6 四条,任一成立 False;`stream_end` 不在 `StreamEnd` 域且非 None → False;openai 模式且 `completion is None` → False。
|
||||
- `TransportResult`、`LLMResponse` 末尾追加 `finish_reason: str | None = None`、`stream_end: StreamEnd | None = None`(放在现有最后一个字段之后,不扰动位置构造);docstring 写清 None 语义与 `usage_source` 分工。
|
||||
- 包根导出 `StreamEnd`;`_has_completion_output` 本任务**保留不动**(T3/T4 迁移后删除)。
|
||||
- 测试(新文件): `_classify_finish` 全值表参数化;`_stream_is_complete` 真值表(含 usage 早于 finish、usage 非 measured);`_judge_outcome` 九行 × 两模式参数化(每行至少一例,含"正文非空+坏工具+stop → transient tool_incomplete");`_summarize_message` 对 refusal-only、reasoning-only、whitespace content、未知嵌套字符串、`tool_calls: [None]`;`_is_cacheable` 四类否例 + 正例 + 非法 stream_end。`test_types.py`: `OpenAIChatCompletion` 接受 `tool_calls=None`、拒非 list、`[None]` 合法;两新字段默认 None。
|
||||
- 验证: `conda run -n PolyGateway pytest tests/unit/test_completion_verdict.py tests/unit/test_types.py tests/unit/test_package.py -q` → 全过;`make lint` 无新增问题。
|
||||
- [ ] 提交 `feat: add kernel completion verdict functions and response fields`
|
||||
|
||||
### T2 聚合器: null 优先、未知字段合并、finish/usage 记录
|
||||
|
||||
- 文件: `src/polygateway/transports/_openai_completion.py`;测试 `tests/unit/test_openai_completion.py`。
|
||||
- 保留 `message`、`tools` 实例属性名与语义(`test_openai_completion.py:70,93` 直接依赖)。
|
||||
- 行为(设计 §5、§4.2):
|
||||
- 每帧: 校验 chunk 对象;`usage` 非 null 时记录为 `last_usage`,若 `finish_seen` 或同帧 choice 带非 null finish → `usage_after_finish = True`。
|
||||
- choices: 保真维持单 choice/index 0 校验;文本模式取 `index` 缺省或为 0 的第一个 choice,其余忽略。
|
||||
- finish_reason: 保真走 `_identity`(非字符串/冲突 → Transient,同 1.3.9);文本模式首个字符串值生效,非字符串忽略。任一模式见到非 null 即 `finish_seen = True`。
|
||||
- null 五层(设计 §5.1): chunk 层 `choices: null`、choice 层 `delta: null` 视为缺省;例外: 顶层 `error` 键(含 `error: null`)仍由 `_check_chat_error` 按 error 帧拒绝(不动,保 `test_error_before_done_is_failure`)。
|
||||
- delta 与工具条目、function 三层: 值为 None 的键 → 若目标无此键则 `setdefault(key, None)`(保真),不做类型校验;`tool_calls` list 中 None 元素跳过。
|
||||
- 已知字段非 None 时逐字沿用 1.3.9 校验与合并(content/reasoning_content 拼接、role 必须 assistant、工具 id/type `_identity`、name/arguments 拼接)。
|
||||
- 未知字段(delta 层除 role/content/reasoning_content/tool_calls;工具层除 index/id/type/function;function 层除 name/arguments): 交给 `_merge_unknown(target, key, value, path)`,规则见设计 §5.2;标签键集合 `{"index", "type", "id", "format"}`;冲突 → 从 target 删除该键、把归一路径(数组下标替换为 `[]`,如 `delta.reasoning_details[].format`)加入 `conflicts` 与本尝试"封禁路径"集合,后续同路径值丢弃。`_merge_unknown` 返回"是否并入非空字符串片段"。
|
||||
- `reasoning`: 在保真模式作为普通未知字符串合并进 message;两模式都把其片段放入 `ChatDelta.reasoning`。
|
||||
- progress: 1.3.9 已知字段口径 **或** 任一 `_merge_unknown` 返回 True(文本模式也调用合并函数计算活性,但合并结果不对外)。
|
||||
- 新增只读属性见 §2;`finish()` 改为: 组装 message(含排序后工具)后构造 `OpenAIChatCompletion`(校验失败仍抛 Transient)。
|
||||
- `parse_chat_completion` 拆为两步: `check_completion_body(body) -> tuple[dict, str | None]`(只校验 body 为对象、恰好一个 choice、index 缺省或为 0、message 为对象、保真下 finish 为字符串或 null,失败抛 Transient;返回原始 message 与 finish)与 `build_completion(message, body) -> OpenAIChatCompletion`(构造快照,失败抛 Transient)。快照构造前剔除 `tool_calls` 中的 None 元素(与流式跳过一致,避免回传 `[null]` 被上游 400);`tool_calls: null` 原样保留。
|
||||
- `_merge_unknown` 按值类型拆分私有函数(标签键、字符串、标量、对象、index 数组、其他数组),每个 ≤ B。
|
||||
- 拆分 `add_chunk` 为 `_take_meta`、`_take_choice`、`_take_delta`、`_take_tools`、`_take_tool` 等私有方法,每个 ≤ B。
|
||||
- 测试: 改写 `test_invalid_delta_is_domain_error` 参数: 删除 `{"audio": {}}`、`{"index":0,"extra":1}` 与 null 已知字段参数(改为正例),保留 role 非 assistant、content 非字符串、tool index 非法等仍应拒绝的参数。新增: `refusal:null`+`tool_calls:null` 帧成功且快照含 `refusal: None`;只有 `reasoning` 的帧 progress=True 且 `ChatDelta.reasoning` 有值;二次构造的 OpenRouter `reasoning_details` 分片(每帧重复 `format`/`id`,`text` 分片)合并后 `format` 不重复、`text` 拼接完整;工具层嵌套对象 `extra_content={"google":{"thought_signature":"s"}}` 原样保留;数值冲突 → 键被删、`conflicts` 含归一路径、调用成功;同路径冲突后再到达的值被丢弃;形态改变(字符串→对象、index 数组→普通数组)即冲突;布尔值冲突;其他数组追加;同帧多个字段/多个未知字符串只产生一次 progress;chunk `choices:null`、choice `delta:null` 视缺省;`role:null`、`arguments:null` 视缺省;全程只有 `role:null` → `finish()` 失败;非流式 `tool_calls:[None, 合法工具]` 快照只含合法工具;`usage_after_finish` 四种顺序(finish 前 usage、finish 同帧、finish 后 usage-only 帧、无 usage);文本模式 index=1 的 choice 被忽略;重复 tool id 不拼接(既有用例保持)。
|
||||
- 验证: §0 统一验证;快速回路 `conda run -n PolyGateway pytest tests/unit/test_openai_completion.py tests/unit/test_openai_fidelity.py tests/unit/test_openai_compat.py -q`。T2 期间 transport 仍调用 `parse_chat_completion` 的组合(保留为两步的薄包装),行为不变。
|
||||
- [ ] 提交 `fix: merge unknown and null stream fields losslessly in completion accumulator`
|
||||
|
||||
### T3 transport 两条路径接入判定
|
||||
|
||||
- 文件: `src/polygateway/transports/openai_compat.py`;测试 `tests/unit/test_openai_fidelity.py`、`tests/unit/test_openai_compat.py`。
|
||||
- 行为:
|
||||
- `_complete_stream`: 流结束后先算 `usage_measured = _resolve_usage(sink.get("usage") or {})[2] == "measured"`,再 `stream_end = _stream_is_complete(done=..., finish_reason=acc.finish_reason, usage_after_finish=acc.usage_after_finish, usage_measured=...)`。
|
||||
- None 且 openai → Transient `"{源} missing_done: …"`;None 且 text → 沿 `_check_done`(零产物按 `_summarize_text` 的 any 判定 early_eof;`retry` 抛;`salvage` → `stream_end="salvaged"`)。
|
||||
- `salvaged` 时 usage 沿 `_resolve_stream_usage(..., salvaged=True)`;`done`/`eof_after_finish` 时 salvaged=False。
|
||||
- 投影: `thinking` = 非空 reasoning_content 片段拼接,否则 `ChatDelta.reasoning` 片段拼接;再走既有 `_finalize_text`(think 标签)。
|
||||
- 判定: openai → `summary = _summarize_message(acc.raw_message(), content)`;text → `_summarize_text(content, thinking)`;`verdict = _judge_outcome(mode, summary, _classify_finish(acc.finish_reason))`;非 deliver → 按 `error_kind` 抛 `TransientError` 或 `ResultInvalidError`,message 固定格式 `f"{source.name} {code}: finish_reason={fr!r}, thinking_len={len(thinking)}"`,带 `source_name`、`operation="chat"`;`ResultInvalidError` 显式 `raw_text=""`(不回显推理内容)。deliver 且 openai → `acc.finish()` 构造快照。
|
||||
- 删除 `_reject_empty_completion` 与 1.3.9 的"保真缺 DONE"分支;`_check_done` 只保留文本截断语义。
|
||||
- `_complete_once`: 跳过第一步。保真: 先 `check_completion_body` 取原始 message 与 finish,用原始 message(剔除 None 工具后)算 `_summarize_message` 与 `_judge_outcome`,**仅 deliver 时**调 `build_completion` 构造快照——否则坏工具 + length 会在构造时抛 Transient,到不了 `tool_truncated`。文本: finish 取 `choices[0].get("finish_reason")`,非字符串记 None;同一判定;`stream_end=None`;投影别名同上(`message.get("reasoning_content") or message.get("reasoning")`,仅取字符串)。
|
||||
- 两路径 `TransportResult` 填 `finish_reason`、`stream_end`。
|
||||
- 告警节流: 实例属性 `_warned_fields: set[tuple[str, str]]`,上限 1024,饱和时记一次 `"告警集合已饱和,后续同类告警省略"`;对 `acc.conflicts` 中每个路径、以及 `_classify_finish == "unknown"` 的 finish 值(截断 64 字符,文案写明"该 finish_reason 不缓存")各告警一次;日志只含源名与路径/值,不回显字段内容。
|
||||
- 拆分 `_complete_stream`/`_complete_once` 至 ≤ B(建议抽 `_consume_stream`、`_verdict_or_raise`、`_project_text`)。
|
||||
- 测试(假 SSE,复用文件内既有 helper):
|
||||
- #31 验收 1-6(设计 §10),断言 `stream_end`、`usage_source`、attempts=1(经 GatewayClient 或 RetryMW 的既有测试设施)。
|
||||
- usage 早于 finish + EOF → 失败;finish 后 usage `{}` → 失败;`network_error`+usage+EOF → Transient。
|
||||
- 文本模式: stop+usage+EOF 无 DONE(`missing_done="retry"`)→ 成功 `eof_after_finish`;无 finish + EOF → retry 抛、salvage 记 `salvaged`。
|
||||
- #30 验收: 保真 reasoning-only+length → 交付,`completion.message["content"]` 缺省或空、`reasoning_content` 完整、`finish_reason=="length"`;文本同输入 → `ResultInvalidError` 且 message 含 `length_without_content`;保真 content 空+length(无任何产物)→ 交付;文本同 → ResultInvalid;保真/文本 零增量+DONE(带 stop、不带 finish)→ Transient(`test_stream_zero_content_with_done_is_transient` 保持不改);非流式 message 带 `tool_calls:null`+`refusal:null` → 成功;工具缺 name + length → ResultInvalid `tool_truncated`;content 非空 + 坏工具 + stop → Transient。
|
||||
- 只有 `reasoning` 字段的流不触发 TTFT 超时(用既有看门狗测试设施设置小 ttft)且文本 `thinking` 等于拼接值;同时有非空 reasoning_content 时以其为准。
|
||||
- 冲突/未知 finish 告警各只一次(loguru sink: `logger.add(list.append, level="WARNING")`,先例 `test_openai_compat.py:877`;caplog 抓不到 loguru);饱和用例预先往 `_warned_fields` 灌 1024 条再触发一次,断言饱和告警一次。
|
||||
- 结局表传输层覆盖: 设计 §4.3 九行 × 两模式,每行至少流式一例 + 非流式一例(行 2 只保真);非流式"工具缺 name + length → ResultInvalid `tool_truncated`";文本 length 用例经 GatewayClient 断言 attempts=1 且熔断窗口失败计数为 0;#30 reasoning-only+length 经 GatewayClient 断言 attempts=1。
|
||||
- 改写 `test_openai_never_salvages`: 断言"无 finish 的 EOF 在 `missing_done=salvage` 下仍失败",并新增"finish+usage+EOF 成功"作为对照。
|
||||
- 验证: `conda run -n PolyGateway pytest tests/unit -q` → 全过。
|
||||
- [ ] 提交 `fix: judge stream completion by finish reason and trailing usage`
|
||||
|
||||
### T4 retry 搬运与缓存读写判据
|
||||
|
||||
- 文件: `src/polygateway/middleware/retry.py`、`src/polygateway/middleware/cache.py`、`src/polygateway/types.py`(删除 `_has_completion_output`);测试 `tests/unit/test_cache.py`、`tests/unit/test_retry.py`、`tests/integration/test_redis_cache.py`。
|
||||
- 行为:
|
||||
- `_build_response` 搬运 `finish_reason`、`stream_end`。
|
||||
- 写路径: 序列化前 `_is_cacheable(mode=request.response_mode, content=response.content, finish_reason=response.finish_reason, stream_end=response.stream_end, completion=response.completion)` 为 False → `logger.debug` 跳写。
|
||||
- 读路径(`_rehydrate`): 重建 completion 后、`fields.update` 之前: `stored_end = fields.get("stream_end")` 非 None 且不在域 → miss+warning;`finish = fields.get("finish_reason")`,非 None 且非 str → miss;为 None 且 completion 存在 → 回退 `completion.finish_reason`;`_is_cacheable(...)` False → miss+warning;命中覆盖加 `stream_end=None`、`finish_reason=finish`。拆分 `_rehydrate` 至 ≤ B。
|
||||
- 删除 `_has_completion_output` 及其 import(全仓 grep 为零)。
|
||||
- 读写判定的 finish 统一取 `_effective_finish(response.finish_reason, response.completion)`(读路径对存储值同样调用)。
|
||||
- 测试: 不可缓存六类(salvaged、reasoning-only length 保真、文本 length 带正文、unknown finish、保真 reasoning-only + stop(交付但无正文产物)、`content_filter` 带正文)均不写入(fake cache backend 断言 set 未调用)且第二次调用 attempts=1;手工注入上述条目 → 读视 miss;非法 `stream_end` 注入 → miss;1.3.9 旧文本条目(无新键)→ 命中;1.3.9 保真条目(无顶层 finish、completion.finish_reason="length")→ miss;命中返回 `stream_end is None`、`finish_reason` 为存储/回退值;retry 测试断言 LLMResponse 两字段来自 TransportResult。Redis integration 一例往返两新字段。
|
||||
- 验证: `conda run -n PolyGateway pytest tests/unit -q` → 全过;`conda run -n PolyGateway pytest tests/integration/test_redis_cache.py -q`(需本地 Redis)→ 全过。
|
||||
- [ ] 提交 `fix: gate cache writes and reads on a shared cacheability verdict`
|
||||
|
||||
### T5 遥测 `stream_end` 列与 recorder 端口
|
||||
|
||||
- 文件: `src/polygateway/ports.py`、`src/polygateway/middleware/telemetry.py`、`src/polygateway/telemetry/schema.py`、`sqlite.py`、`postgres.py`;测试 `tests/unit/test_telemetry.py`、`tests/unit/test_ports.py`、`tests/integration/test_postgres_telemetry.py`,以及全仓 `def record_llm_call` 测试替身(`grep -rn "def record_llm_call" tests`)。
|
||||
- 行为:
|
||||
- `TelemetryRecorder.record_llm_call` 在 `stall_count` 之后追加 keyword-only `stream_end: str | None`(无默认),docstring 注明 1.3.10。
|
||||
- `_AttemptUsage` 加 `stream_end: str | None = None`,`of()` 读 `response.stream_end`;`emit_attempt` 把它传给 `_record`;`_record` 加同名参数并传给 recorder;`emit_cache_hit`、`emit_terminal_failure` 显式 `stream_end=None`。
|
||||
- `schema.py`: SQLite 与 PG CREATE 末尾 `stream_end TEXT`;`SQLITE_BACKFILL`、`_PG_BACKFILL_DECLS` 追加 `("stream_end", "TEXT")`;`COLUMNS` 追加 `"stream_end"`。sqlite/postgres 若有硬编码列数或参数位次随之更新(以 `COLUMNS` 为准)。
|
||||
- 替身与计数(按审查实测清单): ① 固定字段 fixture `tests/unit/test_telemetry.py:142` `_record_minimal`、`tests/integration/test_postgres_telemetry.py:121` `_minimal_fields` 补 `stream_end: None`(sqlite 按 `fields[col]` 取值,缺键 KeyError);② 硬编码计数 38→39 / 列清单追加: `test_ports.py:325`、`test_telemetry.py:53`(`_EXPECTED_COLUMNS`)`:271`、`:301-303`、`:779`、`:829`,`test_postgres_telemetry.py:33`、`:778`、`:1151`、`:1352`(执行时以 grep 复核行号);③ `test_ports.py:112` `_DummyRecorder` 补参数,`stream_end` 加入 `:332` 无默认值参数化列表;④ `**fields` 替身(14 处)无需改动。源码 docstring "38 字段"同步: `ports.py:293`、`middleware/telemetry.py:373`、`sqlite.py:146`、`schema.py:8`。形状闸 `middleware/telemetry.py:323` `_assert_recorder_shape` 从协议签名派生,不改闸本身。
|
||||
- 测试: 成功流式行写 `done`/`eof_after_finish`;非流式、缓存命中、失败、取消、终态行为 NULL;旧库(无列)auto 档补列后写入;manual 档缺列 → 裁剪写入且告警点名 `stream_end`;形状闸拒绝缺 `stream_end` 参数的 recorder;PG integration 同上(需本地 PG,沿既有 fixture)。所有替身补参数。
|
||||
- 验证: `conda run -n PolyGateway pytest tests/unit -q` → 全过;`conda run -n PolyGateway pytest tests/integration/test_postgres_telemetry.py -q` → 全过;`conda run -n PolyGateway python -c "import inspect, polygateway.ports as p; print(len(inspect.signature(p.TelemetryRecorder.record_llm_call).parameters) - 1)"` 记录字段数供 T6 使用。
|
||||
- [ ] 提交 `feat: record stream end mode in telemetry`
|
||||
|
||||
### T6 文档、版本与另开 issue
|
||||
|
||||
- 文件: `README.md`、`CHANGELOG.md`、`research-wiki/ARCHITECTURE.md`、`research-wiki/designs/2026-10-01-issue29-openai-fidelity-design.md`(顶部加"§4.1/§4.2/§5/§6 部分规则已由 2026-10-14 设计修订"指针)、`research-wiki/schemas/llm-calls.md`、`research-wiki/migrations/*.md`、`pyproject.toml`、`src/polygateway/__init__.py`。
|
||||
- 内容:
|
||||
- CHANGELOG `## 1.3.10(未发布)`: 修复段(#31 两模式、#30 两部分、非流式 `tool_calls:null`、reasoning 别名、salvage 不再缓存);**行为变更**段(文本 length/过滤无正文 → ResultInvalid 不再经 `AllSourcesExhausted`;未知 finish 不缓存;活性口径增补);**破坏性**段(`record_llm_call` 新增必填 `stream_end`);提醒(工具快照成立+length 时 arguments 可能半截;冲突删键以告警为准;旧缓存污染迁移 namespace/salt)。
|
||||
- README: 能力表补完成判定/`stream_end`;安装约束 `1.3.*` 核对;遥测字段数用 T5 实测值;活性口径一句。
|
||||
- ARCHITECTURE: §6.2 空补全/missing_done 行、§7 `usage_source` 与 `stream_end` 映射、§14 协议/失败/缓存行按设计改写。
|
||||
- `schemas/llm-calls.md`: 加 `stream_end` 列与取值表,修正陈旧计数。
|
||||
- `migrations/` 三份: 核对下游对 `ResultInvalidError` 的 catch 点,写一行结论(有/无受影响路径)。
|
||||
- 版本 1.3.10 两处一致。
|
||||
- `docs-convention.md` §2 清单逐项过: Gitea Wiki 站点下线,由 README/CHANGELOG/ARCHITECTURE/schemas 承接;`.env.example` 无配置键变更(写明);`research-wiki/ROADMAP.md` 状态同步。
|
||||
- 另开 Gitea issue(tea CLI): "文本模式 n>1 时多 choice 增量混流";"文本模式有产物无正文 + stop 的证据收集(决定是否改 ResultInvalid)"。
|
||||
- 验证: `grep -n "1.3.10" pyproject.toml src/polygateway/__init__.py`;`conda run -n PolyGateway pytest tests/unit/test_package.py -q` → 过。
|
||||
- [ ] 提交 `docs: document completion verdict and bump version to 1.3.10`
|
||||
|
||||
### T7 合并前验证、审查与发布
|
||||
|
||||
- [ ] `make lint`、`make test` 全绿(覆盖率不降);`tests/integration` 中 Redis/PG 相关全绿。
|
||||
- [ ] 派全新上下文 verifier subagent(`verification-before-completion`),逐条对照设计 §4-§7、§10 与本计划验收,输出证据表。
|
||||
- [ ] `requesting-code-review` 整分支审查;按 `receiving-code-review` 核验并修复。
|
||||
- [ ] slow 子集(按 diff 交集): 动了公开入口与 transport → `pytest -m slow tests/e2e/test_smoke_gateway.py tests/e2e/test_openai_tools_live.py`;不跑 `test_thinking_live.py`(未动 thinking 能力表)。另做一次 magpie/glm 真实探针: 记录是否出现 `eof_after_finish`,作为 #31 外部证据。
|
||||
- [ ] 按 CLAUDE.md §4.4.1 九步发布 1.3.10(CHANGELOG 定版日期、合并 main `--no-ff`、main 上重跑、tag、构建、上传、下载验证、Release + 包关联 + 页面核对)。
|
||||
- [ ] 在 #30/#31 评论验收证据与版本,关闭。
|
||||
|
||||
## 4. 设计覆盖自查
|
||||
|
||||
| 设计条目 | 任务 |
|
||||
| --- | --- |
|
||||
| §3 公共字段、`StreamEnd` 导出、`tool_calls:null` | T1 |
|
||||
| §3 recorder 端口、列 | T5 |
|
||||
| §4.1 纯函数与 finish 分类 | T1 |
|
||||
| §4.2 流完整性、usage 位置与 measured | T2(记录)+T3(判定) |
|
||||
| §4.3 结局表、原因码、错误格式 | T1(判定)+T3(翻译) |
|
||||
| §4.4 reasoning 别名 | T2+T3 |
|
||||
| §5.1-5.3 null、合并、标签键、活性 | T2 |
|
||||
| §5.4 告警节流 | T3 |
|
||||
| §6 缓存读写 | T4 |
|
||||
| §7 遥测落点 | T5 |
|
||||
| §8 旧行为审计中的保留项(零增量+DONE、error 帧、多 choice) | T3 回归测试 |
|
||||
| §10 文档、另开 issue、发布 | T6+T7 |
|
||||
|
||||
## 5. 审查修订记录
|
||||
|
||||
| 轮次 | 意见 | 处置 |
|
||||
| --- | --- | --- |
|
||||
| P1 | B1 非流式先构造快照导致 `tool_truncated` 不可达 | 采纳: T2 拆 `check_completion_body`/`build_completion`,T3 先判定后构造 |
|
||||
| P1 | S1 T5 替身/计数清单 | 采纳: T5 逐项列出 |
|
||||
| P1 | S2 类块复杂度、S3 验证与钩子一致 | 采纳: §0 |
|
||||
| P1 | S4 保留内部属性、S5 五层 null、S6 缓存漏两类、S7 结局表与熔断断言、S8 合并规则测试 | 采纳: T2/T3/T4 |
|
||||
| P1 | 建议 1-8 | 全部采纳;建议 4 选"剔除 None 工具元素" |
|
||||
@@ -0,0 +1,29 @@
|
||||
---
|
||||
type: review
|
||||
node_id: review:2026-10-01-issue29-cache-review
|
||||
title: 保真缓存审查修复与1.4.0准备
|
||||
date: 2026-10-01
|
||||
---
|
||||
|
||||
# 保真缓存审查修复与1.4.0准备
|
||||
|
||||
## 审查采纳
|
||||
|
||||
| 级别/问题 | 核验与处置 |
|
||||
| --- | --- |
|
||||
| Important/P2：空协议缓存绕过成功判据 | 已实证：新测试在修复前 10 failed、1 passed；role-only、null/空/空白正文+空工具、reasoning-only，分别带空投影/伪造旧投影均误命中。采纳并修复。 |
|
||||
| Minor：协议/治理测试互相导入 | 已核验双向依赖；将帧构造放基础协议测试中，上层 fidelity 单向复用，没有新增 helpers 抽象。 |
|
||||
|
||||
内核 `types._has_completion_output` 供 transport 和缓存共用：先经协议类型结构校验，有完整工具即有效；无工具须原协议正文和兼容投影均非空。快照类型仍允许描述空消息，不将成功判据强塞进构造器。缓存使用已有 warning/miss，text 旧缓存行为不变。没有 middleware→transport 依赖。
|
||||
|
||||
## 验证证据
|
||||
|
||||
定向 `test_cache/test_openai_completion/test_openai_fidelity/test_openai_compat` 为 268 passed；日志 `tests/outputs/issue29/review-cache-{red,green}.log`（运行产物不提交）。完整质量门1827 passed/23 skipped/110 deselected、95%覆盖、退出0；真实Redis+包13通过；1.4.0 wheel/sdist源码/README/LICENSE逐字校验及twine通过，详见计划最新记录；首轮 lint 发现一个测试 import 顺序，修正后重新运行全门，未掩盖首次失败。
|
||||
|
||||
## 发布准备边界
|
||||
|
||||
1.4.0 对应新增公共协议支持及 transport 端口参数；2026-10-01 远端 tags 和匿名 registry simple 最大版本均1.3.8，无1.4.0冲突。README安装约束、能力表、CHANGELOG定版、两处版本同步。新增 `.env.example` 仅四行说明，无凭据。源码/许可来源核查复用已独审 finding；新产物仍须父会话最终复核后发布。本轮不合并、不 push/tag/上传、不关issue；原main脏文件未改。
|
||||
|
||||
## 后续版本定案（2026-10-01 EDT / 2026-10-02 UTC）
|
||||
|
||||
用户最终指定发布 **1.3.9**，取代本文当时准备但从未发布的 1.4.0。本文标题、历史构建及审查证据保留原值；当前发布目标与新构建核验见[计划 §7](../plans/2026-10-01-issue29-openai-fidelity.md)。版本号变更不撤销自定义 Transport 的 `response_mode` 适配要求。
|
||||
@@ -177,3 +177,26 @@ ORDER BY model, calls DESC;
|
||||
## 1.3.4 测试侧证据（不新增 schema）
|
||||
|
||||
`tests/live_evidence.py`／e2e conftest 只在内存保存完整错误体与独立非流式身份，逐轮 Markdown 白名单输出到 `tests/outputs/134/live/`；凭据、Authorization、提示词、原始异常／响应均不落报告。生产数据仍经 TelemetryEmitter。评估复用 `metric:call-telemetry-coverage`，实际 live 覆盖基线待首次执行。
|
||||
|
||||
## #29 复用声明（2026-10-01）
|
||||
|
||||
OpenAI 保真没有新增遥测表/列；仍经 RetryMW._emit → TelemetryEmitter。
|
||||
error 帧是失败 attempt，正文与思考仍为兼容投影，不新增工具全文列。
|
||||
本页原标题/表格停留 36 字段；实际 `telemetry/schema.py` 已含 stall_ms/stall_count
|
||||
共 38 个 INSERT 字段（§7.8 已登记）。本次不改 DDL，真实定义以源码为准。
|
||||
|
||||
## 1.3.10 `stream_end` 列（#31，2026-10-14）
|
||||
|
||||
`llm_calls` 末尾追加可空 `stream_end TEXT`：INSERT 字段 38 → 39，物理列（含 `created_at`）39 → 40；
|
||||
上文"36 字段"标题为历史口径，以 `telemetry/schema.py` 的 `COLUMNS` 为准。
|
||||
|
||||
| 值 | 含义 | 行 |
|
||||
| --- | --- | --- |
|
||||
| `done` | 收到 `[DONE]` | 流式成功 attempt |
|
||||
| `eof_after_finish` | 无 DONE，finish + 其后实测 usage + 干净 EOF | 流式成功 attempt |
|
||||
| `salvaged` | 文本 `missing_done=salvage` 打捞 | 流式成功 attempt |
|
||||
| NULL | 非流式 / 缓存命中 / 失败 / 取消 / 终态行，或补列前旧行 | — |
|
||||
|
||||
来源: emitter 经 `_AttemptUsage.of(response)` 读 `LLMResponse.stream_end`（不走 `emit_attempt` kw）；
|
||||
命中与终态入口显式 None。评估复用 `metric:call-telemetry-coverage`；新增观察口径
|
||||
`SELECT stream_end, count(*) FROM llm_calls WHERE event_kind='attempt' GROUP BY 1` 统计中转不发 DONE 的比例。
|
||||
|
||||
@@ -47,12 +47,15 @@ from polygateway.types import (
|
||||
OcrLayoutElement,
|
||||
OcrLayoutResult,
|
||||
OcrTextResult,
|
||||
OpenAIChatCompletion,
|
||||
ResponseMode,
|
||||
SourceConfig,
|
||||
StreamEnd,
|
||||
TelemetryStatus,
|
||||
ThinkingObservation,
|
||||
)
|
||||
|
||||
__version__ = "1.3.8"
|
||||
__version__ = "1.3.10"
|
||||
|
||||
__all__ = [
|
||||
"DEFAULT_PROFILES",
|
||||
@@ -70,6 +73,9 @@ __all__ = [
|
||||
"GatewayUnavailableError",
|
||||
"GovernanceBackendError",
|
||||
"LLMResponse",
|
||||
"ResponseMode",
|
||||
"StreamEnd",
|
||||
"OpenAIChatCompletion",
|
||||
"ModelPrice",
|
||||
"OcrClient",
|
||||
"OcrLayoutElement",
|
||||
|
||||
@@ -9,6 +9,7 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import copy
|
||||
import dataclasses
|
||||
import hashlib
|
||||
import json
|
||||
@@ -48,6 +49,7 @@ from polygateway.types import (
|
||||
ChatRequest,
|
||||
Effort,
|
||||
LLMResponse,
|
||||
ResponseMode,
|
||||
TelemetryStatus,
|
||||
_CallContext,
|
||||
coerce_effort,
|
||||
@@ -372,9 +374,15 @@ class GatewayClient:
|
||||
tenant_id: str | None = None,
|
||||
meta: Mapping[str, Any] | None = None,
|
||||
call_deadline_s: float | None = None,
|
||||
response_mode: ResponseMode = "text",
|
||||
) -> LLMResponse:
|
||||
"""一次治理调用(签名冻结,ARCH §5.2;与三项目 LLMProvider 协议兼容)。
|
||||
|
||||
`response_mode="openai"` 返回 `completion` 完整单 choice 消息快照；
|
||||
不支持与 structured 并用，不执行工具。空正文但完整工具是合法结果；
|
||||
缺 [DONE] 不打捞。默认 text 保持既有文本投影。返回模式不绕过受管推理
|
||||
校验；raw-only 要求源级与请求级推理意图均为 None。
|
||||
|
||||
`overlay` 是采样参数覆盖层(`temperature`/`seed`/`max_tokens` 等),优先级
|
||||
高于源级 `extra_body`、低于结构化输出的注入。带默认值的 keyword-only
|
||||
参数不影响既有调用点(issue #4)。
|
||||
@@ -393,6 +401,23 @@ class GatewayClient:
|
||||
`CallDeadlineExceeded`,但到期**不等于未产出、未计费**——在途请求可能已发出、
|
||||
已被上游计费,且清理仍在 `finally` 里完成,故返回时刻 = 期限 + 清理耗时。
|
||||
"""
|
||||
if response_mode not in ("text", "openai"):
|
||||
raise ValueError("response_mode 必须为 text 或 openai")
|
||||
if response_mode == "openai":
|
||||
if structured is not None:
|
||||
raise ValueError("openai 模式不能与 structured 并用")
|
||||
if (
|
||||
overlay is not None
|
||||
and "n" in overlay
|
||||
and (type(overlay["n"]) is not int or overlay["n"] != 1)
|
||||
):
|
||||
raise ValueError("openai 模式仅支持 n=1")
|
||||
try:
|
||||
json.dumps(messages, allow_nan=False)
|
||||
except (ValueError, TypeError) as exc:
|
||||
raise ValueError("messages 必须可 JSON 序列化") from exc
|
||||
messages = copy.deepcopy(messages)
|
||||
overlay = copy.deepcopy(dict(overlay)) if overlay is not None else None
|
||||
if structured is not None and not self._structured_available:
|
||||
raise ImportError(
|
||||
"结构化输出未启用: 安装 pip install 'polygateway[structured]' 后重新装配"
|
||||
@@ -429,6 +454,7 @@ class GatewayClient:
|
||||
context = _CallContext(now=self._now)
|
||||
request = ChatRequest(
|
||||
messages=messages,
|
||||
response_mode=response_mode,
|
||||
session_id=session_id,
|
||||
parent_call_id=parent_call_id,
|
||||
cache_salt=cache_salt,
|
||||
|
||||
@@ -37,7 +37,7 @@ SOURCE_REASONS = frozenset(
|
||||
class PolyGatewayError(Exception):
|
||||
"""库内一切领域错误的基类,携带来源上下文便于遥测与日志定位。
|
||||
|
||||
`body_text` 是**非 2xx 响应体的摘要**——网关拒绝这次调用时说的话(issue #10)。
|
||||
`body_text` 是**HTTP 失败或 200 chat error 帧的摘要**——网关拒绝这次调用时说的话(issue #10)。
|
||||
它与 `ResultInvalidError.raw_text` 是两回事,严禁混用:
|
||||
|
||||
============== ==================================================
|
||||
|
||||
@@ -17,7 +17,16 @@ from typing import TYPE_CHECKING, Any
|
||||
|
||||
from loguru import logger
|
||||
|
||||
from polygateway.types import ChatRequest, Effort, LLMResponse, ThinkingObservation
|
||||
from polygateway.types import (
|
||||
ChatRequest,
|
||||
Effort,
|
||||
LLMResponse,
|
||||
OpenAIChatCompletion,
|
||||
ResponseMode,
|
||||
ThinkingObservation,
|
||||
_effective_finish,
|
||||
_is_cacheable,
|
||||
)
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from collections.abc import Mapping
|
||||
@@ -107,6 +116,7 @@ def build_cache_key(
|
||||
*,
|
||||
sampling: Mapping[str, Any] | None = None,
|
||||
reasoning_effort: Effort | None = None,
|
||||
response_mode: ResponseMode = "text",
|
||||
) -> str:
|
||||
"""缓存 key 公式;salt 仅非 None 时参与(VT 旧键语义: 不传 salt 键形不变)。
|
||||
|
||||
@@ -127,6 +137,8 @@ def build_cache_key(
|
||||
"messages": digest_messages(messages),
|
||||
"namespace": namespace,
|
||||
}
|
||||
if response_mode != "text":
|
||||
key_obj["response_mode"] = response_mode
|
||||
if salt is not None:
|
||||
key_obj["salt"] = salt
|
||||
if sampling:
|
||||
@@ -137,6 +149,54 @@ def build_cache_key(
|
||||
return _KEY_PREFIX + hashlib.sha256(payload.encode("utf-8")).hexdigest()
|
||||
|
||||
|
||||
def _response_cacheable(mode: ResponseMode, response: LLMResponse) -> bool:
|
||||
"""写路径判据;与读路径共用 `_is_cacheable` 与 `_effective_finish`,口径不分叉。"""
|
||||
return _is_cacheable(
|
||||
mode=mode,
|
||||
content=response.content,
|
||||
finish_reason=_effective_finish(response.finish_reason, response.completion),
|
||||
stream_end=response.stream_end,
|
||||
completion=response.completion,
|
||||
)
|
||||
|
||||
|
||||
def _restore_fields(raw: str, mode: ResponseMode) -> dict[str, Any]:
|
||||
"""缓存原文 → LLMResponse 字段;不可缓存或形态坏抛 ValueError(调用方按 miss)。
|
||||
|
||||
可缓存判定对**存储原值**进行、先于命中覆盖: 覆盖后 `stream_end` 恒 None,
|
||||
在那之后判会把 salvaged 条目放行(设计 §6)。
|
||||
"""
|
||||
data = json.loads(raw)
|
||||
fields = {k: v for k, v in data.items() if k in _RESPONSE_FIELDS}
|
||||
completion = fields.get("completion")
|
||||
if completion is not None:
|
||||
if not isinstance(completion, dict):
|
||||
raise ValueError("缓存 completion 必须为对象")
|
||||
fields["completion"] = OpenAIChatCompletion(**completion)
|
||||
finish = _effective_finish(fields.get("finish_reason"), fields.get("completion"))
|
||||
if finish is not None and not isinstance(finish, str):
|
||||
raise ValueError("缓存 finish_reason 必须为字符串或 null")
|
||||
if not _is_cacheable(
|
||||
mode=mode,
|
||||
content=fields.get("content", ""),
|
||||
finish_reason=finish,
|
||||
stream_end=fields.get("stream_end"),
|
||||
completion=fields.get("completion"),
|
||||
):
|
||||
# 非法 stream_end 也落这里: 它关乎内容完整性,不像 thinking_observation
|
||||
# 那样可以宽容降级
|
||||
raise ValueError("缓存条目不可缓存(截断/空正文/非自然结束/非法 stream_end)")
|
||||
fields["finish_reason"] = finish
|
||||
# JSON 里存的是 StrEnum 的字符串值,不转就复活成裸 str,与字段注解分叉
|
||||
# (下游 `is ThinkingObservation.OBSERVED` 会在命中路径上静默为 False);
|
||||
# 键缺失即升级前写入的旧条目,交给 dataclass 默认值
|
||||
if "thinking_observation" in fields:
|
||||
fields["thinking_observation"] = _coerce_observation(fields["thinking_observation"])
|
||||
if "applied_effort" in fields:
|
||||
fields["applied_effort"] = _coerce_applied_effort(fields["applied_effort"])
|
||||
return fields
|
||||
|
||||
|
||||
class CacheMW:
|
||||
"""洋葱第二层(遥测内、结构化外)。
|
||||
|
||||
@@ -176,6 +236,7 @@ class CacheMW:
|
||||
# 请求级档位必须逐次进 key: `self._fingerprint` 是装配期的集合级指纹,
|
||||
# 同一个 client 上 low 与 max 两次调用在它眼里毫无分别(issue #20)
|
||||
reasoning_effort=request.reasoning_effort,
|
||||
response_mode=request.response_mode,
|
||||
)
|
||||
cached = await self._safe_get(key)
|
||||
if cached is not None:
|
||||
@@ -183,7 +244,17 @@ class CacheMW:
|
||||
if hit is not None:
|
||||
return hit
|
||||
response = await call_next(request)
|
||||
await self._safe_set(key, self._serialize(response))
|
||||
if not _response_cacheable(request.response_mode, response):
|
||||
# 交付照常,只是不进 TTL: 截断/空正文/非自然结束固化后会把一次偶然
|
||||
# 变成必然(设计 §6)。debug 级: 这是常规分流,不是故障
|
||||
logger.debug("结果不可缓存(截断/空正文/非自然结束),跳过写入")
|
||||
return response
|
||||
try:
|
||||
serialized = self._serialize(response)
|
||||
except Exception as exc:
|
||||
logger.warning("缓存序列化失败，跳过缓存: {}", type(exc).__name__)
|
||||
else:
|
||||
await self._safe_set(key, serialized)
|
||||
return response
|
||||
|
||||
# —— 命中路径 ——
|
||||
@@ -191,21 +262,15 @@ class CacheMW:
|
||||
def _rehydrate(self, raw: str, request: ChatRequest) -> LLMResponse | None:
|
||||
"""反序列化 + 按本次调用的 structured 档零网络重建;失败按未命中。"""
|
||||
try:
|
||||
data = json.loads(raw)
|
||||
fields = {k: v for k, v in data.items() if k in _RESPONSE_FIELDS}
|
||||
fields = _restore_fields(raw, request.response_mode)
|
||||
structured_data = self._rebuild_structured(fields.get("content", ""), request)
|
||||
# JSON 里存的是 StrEnum 的字符串值,不转就复活成裸 str,与字段注解分叉
|
||||
# (下游 `is ThinkingObservation.OBSERVED` 会在命中路径上静默为 False);
|
||||
# 键缺失即升级前写入的旧条目,交给 dataclass 默认值
|
||||
if "thinking_observation" in fields:
|
||||
fields["thinking_observation"] = _coerce_observation(fields["thinking_observation"])
|
||||
if "applied_effort" in fields:
|
||||
fields["applied_effort"] = _coerce_applied_effort(fields["applied_effort"])
|
||||
fields.update(
|
||||
cache_hit=True,
|
||||
latency_ms=0,
|
||||
ttft_ms=None,
|
||||
max_inter_token_ms=None,
|
||||
# 结束方式描述的是"那次流",命中没有流可言(与 ttft_ms 同口径)
|
||||
stream_end=None,
|
||||
call_id=str(uuid.uuid4()),
|
||||
structured_data=structured_data,
|
||||
# 显式覆盖: 历史条目里的 `call_stats` 是个 dict,而 `_RESPONSE_FIELDS`
|
||||
|
||||
@@ -357,6 +357,7 @@ class RetryMW:
|
||||
gen_started = self._now()
|
||||
result = await self._transport.complete(
|
||||
messages=request.messages,
|
||||
response_mode=request.response_mode,
|
||||
source=source,
|
||||
stream=request.stream,
|
||||
overlay=request.overlay,
|
||||
@@ -739,6 +740,9 @@ class RetryMW:
|
||||
) -> LLMResponse:
|
||||
return LLMResponse(
|
||||
content=result.content,
|
||||
completion=result.completion,
|
||||
finish_reason=result.finish_reason,
|
||||
stream_end=result.stream_end,
|
||||
thinking=result.thinking,
|
||||
model=source.model,
|
||||
provider=source.provider,
|
||||
|
||||
@@ -221,6 +221,9 @@ class _AttemptUsage:
|
||||
# 两字段留在此处只为让"尝试视图"形状完整,默认 None 即"无沉默观测"
|
||||
stall_ms: int | None = None
|
||||
stall_count: int | None = None
|
||||
# 1.3.10(#31): 与 stall 相反,结束方式**从 response 取**——LLMResponse 本次有
|
||||
# 该字段,免去约 50 处 emit_attempt 调用点加参;失败尝试 None = 无流可言
|
||||
stream_end: str | None = None
|
||||
|
||||
@classmethod
|
||||
def of(cls, response: LLMResponse | None) -> _AttemptUsage:
|
||||
@@ -239,6 +242,7 @@ class _AttemptUsage:
|
||||
model_reported=response.model_reported,
|
||||
reasoning_tokens=response.reasoning_tokens,
|
||||
thinking_observation=response.thinking_observation,
|
||||
stream_end=response.stream_end,
|
||||
)
|
||||
|
||||
|
||||
@@ -370,7 +374,7 @@ def _assert_recorder_shape(recorder: TelemetryRecorder) -> None:
|
||||
|
||||
|
||||
class TelemetryEmitter:
|
||||
"""从请求与结果组装 38 字段并写入 recorder;一切写失败降级 warning。"""
|
||||
"""从请求与结果组装 39 字段并写入 recorder;一切写失败降级 warning。"""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
@@ -464,6 +468,7 @@ class TelemetryEmitter:
|
||||
total_latency_ms=None,
|
||||
stall_ms=stall_ms,
|
||||
stall_count=stall_count,
|
||||
stream_end=usage.stream_end,
|
||||
)
|
||||
|
||||
async def emit_cache_hit(
|
||||
@@ -514,6 +519,8 @@ class TelemetryEmitter:
|
||||
# 缓存命中行未产生 transport 观测: 无沉默可言,显式 None
|
||||
stall_ms=None,
|
||||
stall_count=None,
|
||||
# 命中/终态行无流可言(缓存命中已在 CacheMW 置 None,此处显式不信任)
|
||||
stream_end=None,
|
||||
)
|
||||
|
||||
async def emit_terminal_failure(
|
||||
@@ -569,6 +576,8 @@ class TelemetryEmitter:
|
||||
# 终态行无具体源与 transport 观测: 显式 None
|
||||
stall_ms=None,
|
||||
stall_count=None,
|
||||
# 命中/终态行无流可言(缓存命中已在 CacheMW 置 None,此处显式不信任)
|
||||
stream_end=None,
|
||||
)
|
||||
|
||||
async def _record(
|
||||
@@ -615,6 +624,8 @@ class TelemetryEmitter:
|
||||
# 本方法只搬运(同 reasoning_effort 先例)——
|
||||
stall_ms: int | None,
|
||||
stall_count: int | None,
|
||||
# —— 1.3.10: 结束方式(#31);入口已定型,本方法只搬运 ——
|
||||
stream_end: str | None,
|
||||
) -> None:
|
||||
try:
|
||||
# 成本换算(M2 §6): 成功行按单价换算;缓存命中 0.0(未产生新调用);
|
||||
@@ -685,6 +696,7 @@ class TelemetryEmitter:
|
||||
total_latency_ms=total_latency_ms,
|
||||
stall_ms=stall_ms,
|
||||
stall_count=stall_count,
|
||||
stream_end=stream_end,
|
||||
)
|
||||
except asyncio.CancelledError:
|
||||
raise
|
||||
|
||||
@@ -20,6 +20,7 @@ from .types import (
|
||||
OcrLayoutTransportResult,
|
||||
OcrTextResult,
|
||||
OcrTextTransportResult,
|
||||
ResponseMode,
|
||||
SourceConfig,
|
||||
SourceStats,
|
||||
TelemetryStatus,
|
||||
@@ -40,6 +41,10 @@ class Middleware(Protocol):
|
||||
class Transport(Protocol):
|
||||
"""一次原始调用的协议细节(请求组装/流式解析/错误翻译);不含任何治理。
|
||||
|
||||
`response_mode` 为必填返回契约：openai 成功必须提供 completion，
|
||||
不支持者应 RequestRejected，不能静默退回文本。工具的实际增量与首次身份
|
||||
同正文/推理共用活性事件；同帧只置位一次，重复身份不算进展。
|
||||
|
||||
`reasoning_effort` 是本次调用要求的推理档位(`None` = 不表态,随源级配置)。
|
||||
它必须走**协议参数**而不能让 transport 自己去读 `ChatRequest`: 端口只收拆开的
|
||||
请求要素,是为了让 transport 不依赖洋葱内部的请求类型(P7 端口最内层)。
|
||||
@@ -70,6 +75,7 @@ class Transport(Protocol):
|
||||
reasoning_effort: Effort | None,
|
||||
first_token_event: asyncio.Event | None,
|
||||
content_event: asyncio.Event | None,
|
||||
response_mode: ResponseMode,
|
||||
) -> TransportResult: ...
|
||||
|
||||
|
||||
@@ -284,7 +290,7 @@ class TelemetryStatusProvider(Protocol):
|
||||
|
||||
@runtime_checkable
|
||||
class TelemetryRecorder(Protocol):
|
||||
"""遥测后端;38 字段冻结(M1 设计 §4.4 + issue #3/#4/#11/#16/#20 + 1.3.5/1.3.8),唯一调用点是 TelemetryEmitter。
|
||||
"""遥测后端;39 字段冻结(M1 设计 §4.4 + issue #3/#4/#11/#16/#20 + 1.3.5/1.3.8/1.3.10),唯一调用点是 TelemetryEmitter。
|
||||
|
||||
新增参数不设默认值: 库外无第三方实现者(三项目迁移时删除了各自的同名
|
||||
Protocol),完整签名的成本为零,而少写一列会被 emitter 的降级吞成 warning。
|
||||
@@ -351,4 +357,5 @@ class TelemetryRecorder(Protocol):
|
||||
total_latency_ms: int | None,
|
||||
stall_ms: int | None,
|
||||
stall_count: int | None,
|
||||
stream_end: str | None,
|
||||
) -> None: ...
|
||||
|
||||
@@ -5,8 +5,8 @@
|
||||
多处各存一份必然漂移,而漂移的表现是"下游照打印的 SQL 建完表,库仍报缺列"。
|
||||
|
||||
**`COLUMNS` 是 INSERT 字段序,不是物理列序**: 数据库自填的 `created_at` 不在其中(它带
|
||||
`DEFAULT now()` / `datetime('now')`,库从不显式写它)。物理表列 = 38 个 INSERT 字段 +
|
||||
`created_at` = 39;列数断言一律按物理列数写,两套口径混用是最易错处。
|
||||
`DEFAULT now()` / `datetime('now')`,库从不显式写它)。物理表列 = 39 个 INSERT 字段 +
|
||||
`created_at` = 40;列数断言一律按物理列数写,两套口径混用是最易错处。
|
||||
|
||||
本模块只依赖标准库: `telemetry/` 与 `backends/`、`transports/`、`structured/` 同层且
|
||||
互不依赖(import-linter 契约执法)。
|
||||
@@ -64,7 +64,8 @@ CREATE TABLE IF NOT EXISTS llm_calls (
|
||||
attempts INTEGER,
|
||||
total_latency_ms INTEGER,
|
||||
stall_ms INTEGER,
|
||||
stall_count INTEGER
|
||||
stall_count INTEGER,
|
||||
stream_end TEXT
|
||||
);
|
||||
"""
|
||||
|
||||
@@ -108,7 +109,8 @@ CREATE TABLE IF NOT EXISTS llm_calls (
|
||||
attempts INTEGER,
|
||||
total_latency_ms INTEGER,
|
||||
stall_ms INTEGER,
|
||||
stall_count INTEGER
|
||||
stall_count INTEGER,
|
||||
stream_end TEXT
|
||||
);
|
||||
"""
|
||||
|
||||
@@ -145,6 +147,8 @@ SQLITE_BACKFILL = (
|
||||
# 没记过这件事",与"观测过且零沉默"(0)是两回事
|
||||
("stall_ms", "INTEGER"),
|
||||
("stall_count", "INTEGER"),
|
||||
# 1.3.10 结束方式(#31): 可空无默认,旧行 NULL = 补列之前没记过;值域见 StreamEnd
|
||||
("stream_end", "TEXT"),
|
||||
)
|
||||
|
||||
# PG 补列的列定义。语句由此派生成两份文本(见下),使"库内执行的那份"与"打印给
|
||||
@@ -174,6 +178,8 @@ _PG_BACKFILL_DECLS = (
|
||||
# 1.3.8 两列,列序与 SQLITE_BACKFILL 逐项对齐(理由同上)
|
||||
("stall_ms", "INTEGER"),
|
||||
("stall_count", "INTEGER"),
|
||||
# 1.3.10 结束方式(#31): 可空无默认,旧行 NULL = 补列之前没记过;值域见 StreamEnd
|
||||
("stream_end", "TEXT"),
|
||||
)
|
||||
|
||||
# 新列排在 created_at 之后: 与旧表 ALTER 追加的位置一致(见 SQLITE_BACKFILL 同款注释)。
|
||||
@@ -226,6 +232,8 @@ COLUMNS = (
|
||||
# —— 1.3.8 沉默归因(issue #27)——
|
||||
"stall_ms",
|
||||
"stall_count",
|
||||
# —— 1.3.10 结束方式(#31)——
|
||||
"stream_end",
|
||||
)
|
||||
|
||||
_COLUMN_SET = frozenset(COLUMNS)
|
||||
|
||||
@@ -143,7 +143,7 @@ class SQLiteRecorder:
|
||||
logger.warning("SQLite 遥测补列失败(写入将逐行降级): {}", exc)
|
||||
|
||||
async def record_llm_call(self, **fields: object) -> None:
|
||||
"""写一行遥测;字段集合即 38 字段冻结签名(ports.TelemetryRecorder)。
|
||||
"""写一行遥测;字段集合即 39 字段冻结签名(ports.TelemetryRecorder)。
|
||||
|
||||
取值按 `self._columns`(manual 档可能已被裁剪),与 `self._insert` 的
|
||||
占位符同序——两者必须一起改,分开改就是把值写进错位的列。
|
||||
|
||||
@@ -0,0 +1,455 @@
|
||||
"""OpenAI 单 choice 消息聚合：仅协议值处理，不做 I/O 或治理。
|
||||
|
||||
1.3.10(#30): null 一律视为缺省;已知字段沿用 1.3.9 语义;未知字段按 OpenAI 流式
|
||||
累加惯例无损合并,冲突删键并登记路径——方言是确定性的,拒绝只会让重试重演同一失败。
|
||||
"""
|
||||
|
||||
import copy
|
||||
from dataclasses import dataclass
|
||||
from typing import Any
|
||||
|
||||
from polygateway.errors import TransientError
|
||||
from polygateway.types import OpenAIChatCompletion, ResponseMode
|
||||
|
||||
_DELTA_KNOWN = frozenset({"role", "content", "reasoning_content", "tool_calls"})
|
||||
_TOOL_KNOWN = frozenset({"index", "id", "type", "function"})
|
||||
_FUNCTION_KNOWN = frozenset({"name", "arguments"})
|
||||
# 标签键: 每帧可能重复下发的身份/格式标记,同值幂等,绝不拼接(拼成 "x-v1x-v1"
|
||||
# 回传上游会被拒);也不算生成进展
|
||||
_LABEL_KEYS = frozenset({"index", "type", "id", "format"})
|
||||
|
||||
|
||||
def _invalid(reason: str) -> TransientError:
|
||||
"""协议形态失败，不回显可能敏感的工具参数。"""
|
||||
return TransientError(f"OpenAI 协议失败: {reason}", operation="chat")
|
||||
|
||||
|
||||
def _object(value: Any, name: str) -> dict[str, Any]:
|
||||
"""外部对象先校验再读取。"""
|
||||
if not isinstance(value, dict):
|
||||
raise _invalid(f"{name} 必须为对象")
|
||||
return value
|
||||
|
||||
|
||||
def _identity(target: dict[str, Any], key: str, value: Any) -> bool:
|
||||
"""身份字段只接受同值重复，不把重复完整 ID 当分片拼接。"""
|
||||
if value is None:
|
||||
return False
|
||||
if not isinstance(value, str):
|
||||
raise _invalid(f"{key} 必须为字符串")
|
||||
if key in target and target[key] != value:
|
||||
raise _invalid(f"{key} 冲突")
|
||||
changed = key not in target and bool(value)
|
||||
target[key] = value
|
||||
return changed
|
||||
|
||||
|
||||
def _append(target: dict[str, Any], key: str, value: Any) -> str:
|
||||
"""字符串片段逐字拼接，保留缺省/null/空串区别。"""
|
||||
if value is None:
|
||||
target.setdefault(key, None)
|
||||
return ""
|
||||
if not isinstance(value, str):
|
||||
raise _invalid(f"{key} 必须为字符串或 null")
|
||||
target[key] = (target.get(key) or "") + value
|
||||
return value
|
||||
|
||||
|
||||
def _assemble(message: dict[str, Any], tools: dict[int, dict[str, Any]]) -> dict[str, Any]:
|
||||
"""按 index 排序组装工具;`finish()` 与 `raw_message()` 共用,判定与快照同源。"""
|
||||
assembled = copy.deepcopy(message)
|
||||
if tools:
|
||||
assembled["tool_calls"] = [copy.deepcopy(tools[index]) for index in sorted(tools)]
|
||||
return assembled
|
||||
|
||||
|
||||
def _completion(message: dict[str, Any], metadata: dict[str, Any]) -> OpenAIChatCompletion:
|
||||
"""复用内核最终快照校验并翻译领域错误。"""
|
||||
try:
|
||||
return OpenAIChatCompletion(
|
||||
message, metadata.get("finish_reason"), metadata.get("id"), metadata.get("usage")
|
||||
)
|
||||
except (ValueError, TypeError) as exc:
|
||||
raise _invalid(str(exc)) from exc
|
||||
|
||||
|
||||
# —— 未知字段合并(设计 §5.2) ——
|
||||
|
||||
|
||||
class _MergeConflictError(Exception):
|
||||
"""合并冲突(内部控制流): 由 `_ExtensionMerger.merge_key` 就地收口为删键。"""
|
||||
|
||||
|
||||
def _is_indexed(items: list[Any]) -> bool:
|
||||
"""数组元素(忽略 null)均为带整数 index 的对象。"""
|
||||
present = [item for item in items if item is not None]
|
||||
return bool(present) and all(
|
||||
isinstance(item, dict) and type(item.get("index")) is int for item in present
|
||||
)
|
||||
|
||||
|
||||
def _fragment_progress(key: str, value: Any) -> bool:
|
||||
"""不落盘的活性判据(文本模式): 非标签键上的非空字符串片段。"""
|
||||
if isinstance(value, str):
|
||||
return key not in _LABEL_KEYS and value != ""
|
||||
if isinstance(value, dict):
|
||||
return any(_fragment_progress(k, v) for k, v in value.items())
|
||||
if isinstance(value, list):
|
||||
return any(_fragment_progress(key, item) for item in value)
|
||||
return False
|
||||
|
||||
|
||||
class _ExtensionMerger:
|
||||
"""每尝试私有的未知字段合并器;冲突路径即封禁,后续同路径值丢弃。"""
|
||||
|
||||
def __init__(self) -> None:
|
||||
self.conflicts: set[str] = set()
|
||||
self._array_modes: dict[str, bool] = {}
|
||||
|
||||
def merge_key(self, target: dict[str, Any], key: str, value: Any, path: str) -> bool:
|
||||
"""合并一个键;返回是否并入了非空字符串片段(活性)。"""
|
||||
if path in self.conflicts:
|
||||
return False
|
||||
if value is None:
|
||||
target.setdefault(key, None)
|
||||
return False
|
||||
try:
|
||||
merged, grew = self._merge(target.get(key), value, key, path)
|
||||
except _MergeConflictError:
|
||||
target.pop(key, None)
|
||||
self.conflicts.add(path)
|
||||
return False
|
||||
target[key] = merged
|
||||
return grew
|
||||
|
||||
def _merge(self, old: Any, new: Any, key: str, path: str) -> tuple[Any, bool]:
|
||||
if isinstance(new, dict):
|
||||
return self._merge_dict(old, new, path)
|
||||
if isinstance(new, list):
|
||||
return self._merge_list(old, new, key, path)
|
||||
if key in _LABEL_KEYS or not isinstance(new, str):
|
||||
return self._merge_scalar(old, new)
|
||||
if old is not None and not isinstance(old, str):
|
||||
raise _MergeConflictError
|
||||
return (old or "") + new, new != ""
|
||||
|
||||
@staticmethod
|
||||
def _merge_scalar(old: Any, new: Any) -> tuple[Any, bool]:
|
||||
"""标签键与数字/布尔: 同值幂等,不同值冲突(不学 SDK 相加,计数相加会造假)。"""
|
||||
if old is None:
|
||||
return new, False
|
||||
if type(old) is type(new) and old == new:
|
||||
return old, False
|
||||
raise _MergeConflictError
|
||||
|
||||
def _merge_dict(self, old: Any, new: dict[str, Any], path: str) -> tuple[Any, bool]:
|
||||
if old is not None and not isinstance(old, dict):
|
||||
raise _MergeConflictError
|
||||
target = old if old is not None else {}
|
||||
grew = False
|
||||
for sub_key, sub_value in new.items():
|
||||
grew |= self.merge_key(target, sub_key, sub_value, f"{path}.{sub_key}")
|
||||
return target, grew
|
||||
|
||||
def _merge_list(self, old: Any, new: list[Any], key: str, path: str) -> tuple[Any, bool]:
|
||||
if old is not None and not isinstance(old, list):
|
||||
raise _MergeConflictError
|
||||
target = old if old is not None else []
|
||||
items = [item for item in new if item is not None]
|
||||
if not items:
|
||||
return target, False
|
||||
indexed = _is_indexed(items)
|
||||
if self._array_modes.setdefault(path, indexed) != indexed:
|
||||
raise _MergeConflictError # 形态改变: 首次出现决定合并策略
|
||||
if indexed:
|
||||
return target, self._merge_indexed(target, items, f"{path}[]")
|
||||
return target, self._merge_appended(target, items, key, f"{path}[]")
|
||||
|
||||
def _merge_appended(self, target: list[Any], items: list[Any], key: str, path: str) -> bool:
|
||||
grew = False
|
||||
for item in items:
|
||||
merged, item_grew = self._merge(None, item, key, path)
|
||||
target.append(merged)
|
||||
grew |= item_grew
|
||||
return grew
|
||||
|
||||
def _merge_indexed(self, target: list[Any], items: list[Any], path: str) -> bool:
|
||||
grew = False
|
||||
for item in items:
|
||||
slot = next((e for e in target if e.get("index") == item["index"]), None)
|
||||
if slot is None:
|
||||
slot = {}
|
||||
target.append(slot)
|
||||
grew |= self._merge_dict(slot, item, path)[1]
|
||||
return grew
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class ChatDelta:
|
||||
"""一帧提取结果；progress 表示真实生成进展。
|
||||
|
||||
`reasoning` 是 `reasoning` 字段(vLLM/OpenRouter 新名)的片段,投影 thinking 时
|
||||
作为 `reasoning_content` 缺席时的别名(设计 §4.4)。
|
||||
"""
|
||||
|
||||
content: str
|
||||
reasoning_content: str
|
||||
progress: bool
|
||||
reasoning: str = ""
|
||||
|
||||
|
||||
class ChatCompletionAccumulator:
|
||||
"""每次 transport 尝试独享的聚合器，文本模式不严格校验工具产物。"""
|
||||
|
||||
def __init__(self, *, response_mode: ResponseMode) -> None:
|
||||
"""初始化尝试私有状态。"""
|
||||
self.mode = response_mode
|
||||
self.message: dict[str, Any] = {}
|
||||
self.metadata: dict[str, Any] = {}
|
||||
self.tools: dict[int, dict[str, Any]] = {}
|
||||
self._merger = _ExtensionMerger()
|
||||
self._finish_seen = False
|
||||
self._usage_after_finish = False
|
||||
|
||||
# —— 只读视图(transport 判定消费) ——
|
||||
|
||||
@property
|
||||
def finish_reason(self) -> str | None:
|
||||
"""choice 0 首个非 null finish_reason;未见为 None。"""
|
||||
return self.metadata.get("finish_reason")
|
||||
|
||||
@property
|
||||
def finish_seen(self) -> bool:
|
||||
"""是否已收到 finish_reason。"""
|
||||
return self._finish_seen
|
||||
|
||||
@property
|
||||
def usage_after_finish(self) -> bool:
|
||||
"""finish 同帧或之后是否收到非 null usage(设计 §4.2)。"""
|
||||
return self._usage_after_finish
|
||||
|
||||
@property
|
||||
def conflicts(self) -> frozenset[str]:
|
||||
"""被删除的冲突键路径(数组下标已归一为 `[]`)。"""
|
||||
return frozenset(self._merger.conflicts)
|
||||
|
||||
def raw_message(self) -> dict[str, Any]:
|
||||
"""未校验的合并消息深拷贝(含排序工具),供构造快照前的结局判定。"""
|
||||
return _assemble(self.message, self.tools)
|
||||
|
||||
# —— 聚合 ——
|
||||
|
||||
def add_chunk(self, chunk: dict[str, Any]) -> ChatDelta:
|
||||
"""聚合一个已解码帧，一帧至多一个活性事件。"""
|
||||
chunk = _object(chunk, "chunk")
|
||||
if self.mode == "openai":
|
||||
_identity(self.metadata, "id", chunk.get("id"))
|
||||
choice = self._take_choice(chunk.get("choices"))
|
||||
delta = self._take_delta(choice) if choice is not None else ChatDelta("", "", False)
|
||||
self._take_usage(chunk.get("usage"))
|
||||
return delta
|
||||
|
||||
def _take_usage(self, usage: Any) -> None:
|
||||
"""usage 在 finish 处理之后登记,使同帧 finish+usage 算作"之后"。"""
|
||||
if usage is None:
|
||||
return
|
||||
self.metadata["usage"] = _object(usage, "usage")
|
||||
if self._finish_seen:
|
||||
self._usage_after_finish = True
|
||||
|
||||
def _take_choice(self, choices: Any) -> dict[str, Any] | None:
|
||||
"""选出本帧 choice 并登记 finish;usage-only 帧返回 None。"""
|
||||
if choices is None:
|
||||
return None
|
||||
if not isinstance(choices, list):
|
||||
raise _invalid("choices 必须为数组")
|
||||
if not choices:
|
||||
return None
|
||||
if self.mode == "openai":
|
||||
if len(choices) != 1:
|
||||
raise _invalid("仅支持单 choice")
|
||||
choice = _object(choices[0], "choice")
|
||||
if type(choice.get("index")) is not int or choice["index"] != 0:
|
||||
raise _invalid("choice index 必须为 0")
|
||||
_identity(self.metadata, "finish_reason", choice.get("finish_reason"))
|
||||
else:
|
||||
choice = self._text_choice(choices)
|
||||
if choice is None:
|
||||
return None
|
||||
self._finish_seen = self._finish_seen or self.finish_reason is not None
|
||||
return choice
|
||||
|
||||
def _text_choice(self, choices: list[Any]) -> dict[str, Any] | None:
|
||||
"""文本模式取 index 缺省或为 0 的首个 choice,不混入其他 choice(n>1)。"""
|
||||
for raw in choices:
|
||||
choice = _object(raw, "choice")
|
||||
index = choice.get("index")
|
||||
# null 视缺省(=0);bool 不得冒充 0(`False == 0` 为真)
|
||||
if index is None or (type(index) is int and index == 0):
|
||||
finish = choice.get("finish_reason")
|
||||
if isinstance(finish, str) and "finish_reason" not in self.metadata:
|
||||
self.metadata["finish_reason"] = finish
|
||||
return choice
|
||||
return None
|
||||
|
||||
def _take_delta(self, choice: dict[str, Any]) -> ChatDelta:
|
||||
"""拆分已知与未知字段;已知字段语义逐字沿用 1.3.9。"""
|
||||
raw_delta = choice.get("delta")
|
||||
delta = _object(raw_delta if raw_delta is not None else {}, "delta")
|
||||
if self.mode == "openai" and "role" in delta:
|
||||
self._take_role(delta["role"])
|
||||
content = self._take_text(delta, "content")
|
||||
reasoning_content = self._take_text(delta, "reasoning_content")
|
||||
alias = delta.get("reasoning") if isinstance(delta.get("reasoning"), str) else ""
|
||||
progress = bool(content or reasoning_content)
|
||||
if "tool_calls" in delta:
|
||||
progress |= self._take_tools(delta["tool_calls"])
|
||||
progress |= self._take_unknown(delta)
|
||||
return ChatDelta(content, reasoning_content, progress, alias)
|
||||
|
||||
def _take_role(self, role: Any) -> None:
|
||||
if role is None:
|
||||
self.message.setdefault("role", None)
|
||||
return
|
||||
if role != "assistant":
|
||||
raise _invalid("role 必须为 assistant")
|
||||
self.message["role"] = role
|
||||
|
||||
def _take_text(self, delta: dict[str, Any], key: str) -> str:
|
||||
if key not in delta:
|
||||
return ""
|
||||
if self.mode == "openai" or delta[key] is not None:
|
||||
return _append(self.message, key, delta[key])
|
||||
return ""
|
||||
|
||||
def _take_unknown(self, delta: dict[str, Any]) -> bool:
|
||||
"""未知 delta 键: 保真合并进 message;文本只算活性。"""
|
||||
grew = False
|
||||
for key, value in delta.items():
|
||||
if key in _DELTA_KNOWN:
|
||||
continue
|
||||
if self.mode == "openai":
|
||||
grew |= self._merger.merge_key(self.message, key, value, f"delta.{key}")
|
||||
else:
|
||||
grew |= _fragment_progress(key, value)
|
||||
return grew
|
||||
|
||||
def _take_tools(self, tools: Any) -> bool:
|
||||
if self.mode != "openai":
|
||||
return isinstance(tools, list) and self._each_tool(tools, self._text_tool_progress)
|
||||
if tools is None:
|
||||
self.message.setdefault("tool_calls", None)
|
||||
return False
|
||||
if not isinstance(tools, list):
|
||||
raise _invalid("tool_calls 必须为数组")
|
||||
present = [tool for tool in tools if tool is not None]
|
||||
if self.message.get("tool_calls") is None and (present or not tools):
|
||||
# 显式 [] 原样保留;[null] 不造空数组(回传空 tool_calls 会被上游拒)
|
||||
self.message["tool_calls"] = []
|
||||
return self._each_tool(present, lambda raw: self._take_tool(_object(raw, "tool")))
|
||||
|
||||
@staticmethod
|
||||
def _each_tool(tools: list[Any], take: Any) -> bool:
|
||||
"""逐个非 null 工具增量聚合,返回本帧是否有进展。"""
|
||||
progress = False
|
||||
for raw in tools:
|
||||
if raw is not None:
|
||||
progress |= take(raw)
|
||||
return progress
|
||||
|
||||
def _text_tool_progress(self, raw: Any) -> bool:
|
||||
"""文本只消费可识别的工具进展，不承诺工具完整性。"""
|
||||
if not isinstance(raw, dict) or type(raw.get("index")) is not int:
|
||||
return False
|
||||
tool = self.tools.setdefault(raw["index"], {})
|
||||
progress = False
|
||||
for key in ("id", "type"):
|
||||
if isinstance(raw.get(key), str) and raw[key] and key not in tool:
|
||||
tool[key] = raw[key]
|
||||
progress = True
|
||||
fn = raw.get("function")
|
||||
if isinstance(fn, dict):
|
||||
progress |= any(
|
||||
isinstance(fn.get(k), str) and bool(fn[k]) for k in ("name", "arguments")
|
||||
)
|
||||
return progress
|
||||
|
||||
def _take_tool(self, raw: dict[str, Any]) -> bool:
|
||||
index = raw.get("index")
|
||||
if type(index) is not int or index < 0:
|
||||
raise _invalid("tool index 必须为非负整数")
|
||||
tool = self.tools.setdefault(index, {})
|
||||
progress = _identity(tool, "id", raw.get("id"))
|
||||
progress |= _identity(tool, "type", raw.get("type"))
|
||||
if raw.get("function") is not None:
|
||||
progress |= self._take_function(tool, _object(raw["function"], "function"))
|
||||
for key, value in raw.items():
|
||||
if key not in _TOOL_KNOWN:
|
||||
progress |= self._merger.merge_key(tool, key, value, f"tool_calls[].{key}")
|
||||
return progress
|
||||
|
||||
def _take_function(self, tool: dict[str, Any], fn: dict[str, Any]) -> bool:
|
||||
target = tool.setdefault("function", {})
|
||||
progress = False
|
||||
for key, value in fn.items():
|
||||
if key in _FUNCTION_KNOWN:
|
||||
progress |= bool(_append(target, key, value))
|
||||
else:
|
||||
path = f"tool_calls[].function.{key}"
|
||||
progress |= self._merger.merge_key(target, key, value, path)
|
||||
return progress
|
||||
|
||||
def finish(self) -> OpenAIChatCompletion:
|
||||
"""线路完整性由调用者保证；此处只校验最终消息。"""
|
||||
return _completion(self.raw_message(), self.metadata)
|
||||
|
||||
|
||||
def _strip_null_tools(message: dict[str, Any]) -> dict[str, Any]:
|
||||
"""null 工具元素剔除: 与流式跳过同口径,原样回传 [null] 会被上游拒。"""
|
||||
tools = message.get("tool_calls")
|
||||
if isinstance(tools, list) and None in tools:
|
||||
kept = [tool for tool in tools if tool is not None]
|
||||
# 全为 null 视同 tool_calls:null,不造会被上游拒收的空数组
|
||||
return {**message, "tool_calls": kept or None}
|
||||
return message
|
||||
|
||||
|
||||
def _single_choice(body: dict[str, Any]) -> dict[str, Any]:
|
||||
"""恰好一个 choice,index 缺省或为 0;拒绝静默截取多 choice。"""
|
||||
choices = body.get("choices")
|
||||
if not isinstance(choices, list) or len(choices) != 1:
|
||||
raise _invalid("仅支持单 choice")
|
||||
choice = _object(choices[0], "choice")
|
||||
if "index" in choice and (type(choice["index"]) is not int or choice["index"] != 0):
|
||||
raise _invalid("choice index 必须为 0")
|
||||
return choice
|
||||
|
||||
|
||||
def check_completion_body(body: Any) -> tuple[dict[str, Any], str | None]:
|
||||
"""非流式保真形态校验(不构造快照): 单 choice、index 为 0、finish 为字符串或 null。
|
||||
|
||||
与快照构造拆开: 结局判定要先于构造(截断的半截工具须判 ResultInvalid,
|
||||
构造时抛 Transient 就到不了那一行,设计 §4.3 行 2)。
|
||||
"""
|
||||
choice = _single_choice(_object(body, "body"))
|
||||
finish = choice.get("finish_reason")
|
||||
if finish is not None and not isinstance(finish, str):
|
||||
raise _invalid("finish_reason 必须为字符串或 null")
|
||||
message = _object(choice.get("message"), "message")
|
||||
if message.get("role") != "assistant":
|
||||
# 形态失败先于结局判定,否则缺 role 的截断工具会被归成 ResultInvalid
|
||||
raise _invalid("role 必须为 assistant")
|
||||
return _strip_null_tools(message), finish
|
||||
|
||||
|
||||
def build_completion(
|
||||
message: dict[str, Any], body: dict[str, Any], finish: str | None
|
||||
) -> OpenAIChatCompletion:
|
||||
"""非流式快照构造;保留消息扩展字段。"""
|
||||
return _completion(message, {**body, "finish_reason": finish})
|
||||
|
||||
|
||||
def parse_chat_completion(body: dict[str, Any]) -> OpenAIChatCompletion:
|
||||
"""非流式完整消息保留扩展字段，拒绝静默截取多 choice。"""
|
||||
message, finish = check_completion_body(body)
|
||||
return build_completion(message, body, finish)
|
||||
@@ -12,7 +12,7 @@ import json
|
||||
import math
|
||||
import re
|
||||
import time
|
||||
from dataclasses import replace
|
||||
from dataclasses import dataclass, field, replace
|
||||
from typing import TYPE_CHECKING, Any
|
||||
|
||||
import httpx
|
||||
@@ -38,11 +38,24 @@ from polygateway.thinking import (
|
||||
validate_thinking_raw,
|
||||
)
|
||||
from polygateway.transports._http_errors import compose_message, summarize_body
|
||||
from polygateway.transports._openai_completion import (
|
||||
ChatCompletionAccumulator,
|
||||
ChatDelta,
|
||||
build_completion,
|
||||
check_completion_body,
|
||||
)
|
||||
from polygateway.types import (
|
||||
Effort,
|
||||
EmbeddingTransportResult,
|
||||
ResponseMode,
|
||||
SourceConfig,
|
||||
StreamEnd,
|
||||
TransportResult,
|
||||
_classify_finish,
|
||||
_judge_outcome,
|
||||
_stream_is_complete,
|
||||
_summarize_message,
|
||||
_summarize_text,
|
||||
)
|
||||
|
||||
if TYPE_CHECKING:
|
||||
@@ -50,6 +63,10 @@ if TYPE_CHECKING:
|
||||
from collections.abc import AsyncIterator, Callable, Mapping
|
||||
|
||||
_THINK_PATTERN = re.compile(r"<think>(.*?)</think>", re.DOTALL)
|
||||
# 方言告警节流上限与 finish 值截断(设计 §5.4): 键由上游决定,必须有界
|
||||
_WARN_CAP = 1024
|
||||
_FINISH_WARN_CHARS = 64
|
||||
_PATH_WARN_CHARS = 128
|
||||
|
||||
# —— SSE 纯函数(VT llm.py 同款)——
|
||||
|
||||
@@ -62,29 +79,6 @@ def _sse_data_payload(raw: str) -> str | None:
|
||||
return line[len("data:") :].strip()
|
||||
|
||||
|
||||
def _sse_delta(chunk: dict[str, Any], usage_sink: dict[str, Any]) -> tuple[bool, str] | None:
|
||||
"""从 chunk 提取增量: (True, content) 或 (False, reasoning);usage 帧旁路进 sink。"""
|
||||
if chunk.get("usage"):
|
||||
usage_sink["usage"] = chunk["usage"]
|
||||
if "model" not in usage_sink:
|
||||
# 首个**有效**值即固定: 末帧的异常值不得覆盖它;但首帧报空串也不能锁死
|
||||
# sink——否则后续真实版本会丢(issue #3)
|
||||
reported = _coerce_model_reported(chunk.get("model"))
|
||||
if reported is not None:
|
||||
usage_sink["model"] = reported
|
||||
choices = chunk.get("choices") or []
|
||||
if not choices:
|
||||
return None
|
||||
delta = choices[0].get("delta") or {}
|
||||
content = delta.get("content")
|
||||
if content:
|
||||
return (True, content)
|
||||
reasoning = delta.get("reasoning_content")
|
||||
if reasoning:
|
||||
return (False, reasoning)
|
||||
return None
|
||||
|
||||
|
||||
def _stall_from_chunk_times(
|
||||
times: list[float], threshold_ms: int
|
||||
) -> tuple[float | None, float | None]:
|
||||
@@ -108,10 +102,25 @@ def _stall_from_chunk_times(
|
||||
return (total, float(count)) if count else (0.0, 0.0)
|
||||
|
||||
|
||||
def _check_chat_error(chunk: Any) -> None:
|
||||
"""所有模式拒绝顶层 error；诊断复用有界摘要。"""
|
||||
if not isinstance(chunk, dict):
|
||||
raise TransientError("chat 响应必须为 JSON 对象", operation="chat")
|
||||
if "error" in chunk:
|
||||
summary = summarize_body(json.dumps({"error": chunk["error"]}, ensure_ascii=False))
|
||||
raise TransientError(
|
||||
compose_message("上游 chat error 帧", summary), operation="chat", body_text=summary
|
||||
)
|
||||
if chunk.get("usage") is not None and not isinstance(chunk["usage"], dict):
|
||||
raise TransientError("chat usage 必须为对象或 null", operation="chat")
|
||||
|
||||
|
||||
async def _iter_sse_deltas(
|
||||
lines: AsyncIterator[str], usage_sink: dict[str, Any]
|
||||
) -> AsyncIterator[tuple[bool, str]]:
|
||||
"""逐行解析 SSE 流;[DONE] 置 sink["done"];畸形 JSON 帧 → 瞬时错误(可重试)。"""
|
||||
lines: AsyncIterator[str],
|
||||
usage_sink: dict[str, Any],
|
||||
accumulator: ChatCompletionAccumulator,
|
||||
) -> AsyncIterator[ChatDelta]:
|
||||
"""解析 SSE，一帧只产生一次进展事件。"""
|
||||
async for raw in lines:
|
||||
data = _sse_data_payload(raw)
|
||||
if data is None:
|
||||
@@ -122,14 +131,138 @@ async def _iter_sse_deltas(
|
||||
try:
|
||||
chunk = json.loads(data)
|
||||
except json.JSONDecodeError as exc:
|
||||
raise TransientError(
|
||||
f"SSE 帧畸形(malformed_json): {data[:80]!r}", operation="chat"
|
||||
) from exc
|
||||
delta = _sse_delta(chunk, usage_sink)
|
||||
if delta is not None:
|
||||
raise TransientError("SSE 帧畸形(malformed_json)", operation="chat") from exc
|
||||
_check_chat_error(chunk)
|
||||
if chunk.get("usage") is not None:
|
||||
usage_sink["usage"] = chunk["usage"]
|
||||
if "model" not in usage_sink:
|
||||
model = _coerce_model_reported(chunk.get("model"))
|
||||
if model is not None:
|
||||
usage_sink["model"] = model
|
||||
delta = accumulator.add_chunk(chunk)
|
||||
if delta.progress:
|
||||
yield delta
|
||||
|
||||
|
||||
@dataclass
|
||||
class _StreamTiming:
|
||||
"""一次流式尝试的计时与文本片段(每尝试新建,不跨重试/对冲共享)。"""
|
||||
|
||||
content_parts: list[str] = field(default_factory=list)
|
||||
reasoning_parts: list[str] = field(default_factory=list)
|
||||
alias_parts: list[str] = field(default_factory=list)
|
||||
chunk_times: list[float] = field(default_factory=list)
|
||||
ttft_ms: float | None = None
|
||||
max_gap: float = 0.0
|
||||
|
||||
@property
|
||||
def has_reasoning(self) -> bool:
|
||||
"""出现过非空 reasoning_content: 别名 `reasoning` 让位(设计 §4.4)。"""
|
||||
return bool(self.reasoning_parts)
|
||||
|
||||
|
||||
async def _consume_deltas(
|
||||
guarded: AsyncIterator[ChatDelta],
|
||||
started: float,
|
||||
first_token_event: asyncio.Event | None,
|
||||
content_event: asyncio.Event | None,
|
||||
) -> _StreamTiming:
|
||||
"""消费进展事件: 计时、置位对冲事件、收集文本片段。"""
|
||||
timing = _StreamTiming()
|
||||
last = started
|
||||
async for delta in guarded:
|
||||
now = time.monotonic()
|
||||
# 增量 chunk 时间戳(1.3.8 沉默计量): 循环体只会被真实增量触发——
|
||||
# 空 chunk/usage 帧/SSE keepalive 已在聚合器被过滤
|
||||
timing.chunk_times.append(now)
|
||||
if content_event is not None:
|
||||
# 每个增量 chunk 置位一次: 中段沉默对冲的活性复位信号
|
||||
content_event.set()
|
||||
if timing.ttft_ms is None:
|
||||
timing.ttft_ms = (now - started) * 1000
|
||||
# 首个增量即对冲语义上的"首 token"(思考增量同样是存活证据,
|
||||
# 与看门狗活性口径一致);None = 调用方未启用对冲,零分支成本
|
||||
if first_token_event is not None:
|
||||
first_token_event.set()
|
||||
else:
|
||||
timing.max_gap = max(timing.max_gap, (now - last) * 1000)
|
||||
last = now
|
||||
for parts, text in (
|
||||
(timing.content_parts, delta.content),
|
||||
(timing.reasoning_parts, delta.reasoning_content),
|
||||
(timing.alias_parts, delta.reasoning),
|
||||
):
|
||||
if text:
|
||||
parts.append(text)
|
||||
return timing
|
||||
|
||||
|
||||
def _raise_unless_deliverable(
|
||||
mode: ResponseMode,
|
||||
message: dict[str, Any] | None,
|
||||
content: str,
|
||||
thinking: str,
|
||||
finish_reason: str | None,
|
||||
source: SourceConfig,
|
||||
) -> None:
|
||||
"""结局判定(设计 §4.3)的唯一翻译点: 判定值 → 领域错误。
|
||||
|
||||
原因码以固定格式进 message(遥测 error 列可检索);不回显推理/工具内容。
|
||||
"""
|
||||
if mode == "openai" and message is not None:
|
||||
summary = _summarize_message(message, content)
|
||||
else:
|
||||
summary = _summarize_text(content, thinking)
|
||||
verdict = _judge_outcome(mode=mode, summary=summary, finish=_classify_finish(finish_reason))
|
||||
if verdict.deliver:
|
||||
return
|
||||
text = (
|
||||
f"{source.name} {verdict.code}: finish_reason={finish_reason!r}, "
|
||||
f"thinking_len={len(thinking)}"
|
||||
)
|
||||
if verdict.error_kind == "result_invalid":
|
||||
raise ResultInvalidError(text, raw_text="", source_name=source.name, operation="chat")
|
||||
raise TransientError(text, source_name=source.name, operation="chat")
|
||||
|
||||
|
||||
def _text_choice(body: dict[str, Any], source: SourceConfig) -> tuple[Any, str | None]:
|
||||
"""文本模式取首个 choice 的 message 与 finish(非字符串 finish 记 None)。"""
|
||||
choices = body.get("choices") or []
|
||||
if not choices:
|
||||
raise TransientError(
|
||||
f"{source.name} 响应缺 choices", source_name=source.name, operation="chat"
|
||||
)
|
||||
if not isinstance(choices, list) or not isinstance(choices[0], dict):
|
||||
raise TransientError("chat choices 形态非法", operation="chat")
|
||||
finish = choices[0].get("finish_reason")
|
||||
return choices[0].get("message", {}), finish if isinstance(finish, str) else None
|
||||
|
||||
|
||||
def _nonstream_message(
|
||||
body: dict[str, Any], mode: ResponseMode, source: SourceConfig
|
||||
) -> tuple[dict[str, Any], str | None]:
|
||||
"""非流式取单 choice 的原始 message 与 finish;只校验形态,不构造快照。"""
|
||||
if mode == "openai":
|
||||
message, finish = check_completion_body(body)
|
||||
else:
|
||||
message, finish = _text_choice(body, source)
|
||||
if not isinstance(message, dict) or any(
|
||||
message.get(key) is not None and not isinstance(message[key], str)
|
||||
for key in ("content", "reasoning_content")
|
||||
):
|
||||
raise TransientError("chat message 形态非法", operation="chat")
|
||||
return message, finish
|
||||
|
||||
|
||||
def _reasoning_of(message: dict[str, Any]) -> str:
|
||||
"""非流式思考投影: 非空 reasoning_content 优先,否则 `reasoning` 别名。"""
|
||||
primary = message.get("reasoning_content")
|
||||
if isinstance(primary, str) and primary:
|
||||
return primary
|
||||
alias = message.get("reasoning")
|
||||
return alias if isinstance(alias, str) else ""
|
||||
|
||||
|
||||
# —— 错误翻译(CHS invokers.py 同款)——
|
||||
|
||||
|
||||
@@ -387,6 +520,9 @@ class OpenAICompatTransport:
|
||||
# 都会连带改掉另一侧的行为。(键空间恰好不相交,故当下**不会**互相压制;
|
||||
# 分开维护的理由是语义,不是碰撞)
|
||||
self._warned_mismatches: set[tuple[str, str, Effort | None]] = set()
|
||||
# 方言告警(1.3.10)另立集合: 冲突删键/未知 finish 与推理对账语义无关
|
||||
self._warned_fields: set[tuple[str, str]] = set()
|
||||
self._warn_saturated = False
|
||||
self._client_factory = client_factory or _default_client_factory
|
||||
self._clients: dict[str, httpx.AsyncClient] = {}
|
||||
|
||||
@@ -458,6 +594,7 @@ class OpenAICompatTransport:
|
||||
reasoning_effort: Effort | None,
|
||||
first_token_event: asyncio.Event | None,
|
||||
content_event: asyncio.Event | None,
|
||||
response_mode: ResponseMode,
|
||||
) -> TransportResult:
|
||||
"""一次原始调用;HTTP/线路/流式异常按 ARCH §6.2 翻译为领域错误。
|
||||
|
||||
@@ -468,6 +605,16 @@ class OpenAICompatTransport:
|
||||
`content_event` 为中段沉默对冲处置位(1.3.8): 同款约定,流式路径**每个**
|
||||
增量 chunk 置位一次,非流式路径收它但永不置位。
|
||||
"""
|
||||
if response_mode not in ("text", "openai"):
|
||||
raise RequestRejectedError(
|
||||
"非法 response_mode", source_name=source.name, operation="chat"
|
||||
)
|
||||
if response_mode == "openai":
|
||||
for layer in (source.extra_body, overlay):
|
||||
if "n" in layer and (type(layer["n"]) is not int or layer["n"] != 1):
|
||||
raise RequestRejectedError(
|
||||
"openai 模式仅支持 n=1", source_name=source.name, operation="chat"
|
||||
)
|
||||
profile = get_provider(source.provider, registry=self._registry)
|
||||
try:
|
||||
payload, applied_effort = self._build_payload(
|
||||
@@ -492,12 +639,30 @@ class OpenAICompatTransport:
|
||||
try:
|
||||
if stream:
|
||||
result = await self._complete_stream(
|
||||
client, url, payload, source, profile, first_token_event, content_event
|
||||
client,
|
||||
url,
|
||||
payload,
|
||||
source,
|
||||
profile,
|
||||
first_token_event,
|
||||
content_event,
|
||||
response_mode,
|
||||
)
|
||||
else:
|
||||
result = await self._complete_once(
|
||||
client, url, payload, source, profile, first_token_event, content_event
|
||||
client,
|
||||
url,
|
||||
payload,
|
||||
source,
|
||||
profile,
|
||||
first_token_event,
|
||||
content_event,
|
||||
response_mode,
|
||||
)
|
||||
except TransientError as exc:
|
||||
if exc.source_name is None:
|
||||
exc.source_name = source.name
|
||||
raise
|
||||
except StreamLivenessTimeout as exc:
|
||||
raise TransientError(f"{source.name} 流活性超时({exc.kind})", **ctx) from exc
|
||||
except httpx.TimeoutException as exc:
|
||||
@@ -585,6 +750,7 @@ class OpenAICompatTransport:
|
||||
profile: ProviderProfile,
|
||||
first_token_event: asyncio.Event | None,
|
||||
content_event: asyncio.Event | None,
|
||||
response_mode: ResponseMode,
|
||||
) -> TransportResult:
|
||||
started = time.monotonic()
|
||||
async with client.stream("POST", url, json=payload) as resp:
|
||||
@@ -594,55 +760,59 @@ class OpenAICompatTransport:
|
||||
source, resp.status_code, body, resp.headers, operation="chat"
|
||||
)
|
||||
sink: dict[str, Any] = {}
|
||||
accumulator = ChatCompletionAccumulator(response_mode=response_mode)
|
||||
guarded = stream_with_liveness_timeouts(
|
||||
_iter_sse_deltas(resp.aiter_lines(), sink),
|
||||
_iter_sse_deltas(resp.aiter_lines(), sink, accumulator),
|
||||
ttft_s=source.ttft_timeout_s or source.timeout_s,
|
||||
inter_token_s=source.inter_token_timeout_s or source.timeout_s,
|
||||
total_s=source.timeout_s,
|
||||
)
|
||||
content_parts: list[str] = []
|
||||
thinking_parts: list[str] = []
|
||||
ttft_ms: float | None = None
|
||||
last = started
|
||||
max_gap = 0.0
|
||||
chunk_times: list[float] = []
|
||||
async for is_content, text in guarded:
|
||||
now = time.monotonic()
|
||||
# 增量 chunk 时间戳(1.3.8 沉默计量): 循环体只会被真实增量触发——
|
||||
# 空 chunk/usage 帧/SSE keepalive 已在 _sse_data_payload/_sse_delta
|
||||
# 被过滤,这里逐字追加即可;阈值判定不在热路径,派生收敛在
|
||||
# _stall_from_chunk_times(设计 §3 派生原则)
|
||||
chunk_times.append(now)
|
||||
if content_event is not None:
|
||||
# 每个增量 chunk 置位一次: 中段沉默对冲的活性复位信号
|
||||
content_event.set()
|
||||
if ttft_ms is None:
|
||||
ttft_ms = (now - started) * 1000
|
||||
# 首个增量即对冲语义上的"首 token"(思考增量同样是存活证据,
|
||||
# 与看门狗活性口径一致);None = 调用方未启用对冲,零分支成本
|
||||
if first_token_event is not None:
|
||||
first_token_event.set()
|
||||
else:
|
||||
max_gap = max(max_gap, (now - last) * 1000)
|
||||
last = now
|
||||
(content_parts if is_content else thinking_parts).append(text)
|
||||
salvaged = self._check_done(sink, content_parts, thinking_parts, source)
|
||||
content, thinking = self._finalize_text(content_parts, thinking_parts, profile)
|
||||
self._reject_empty_completion(content, source)
|
||||
prompt, completion, usage_source = _resolve_stream_usage(sink, salvaged)
|
||||
timing = await _consume_deltas(guarded, started, first_token_event, content_event)
|
||||
return self._stream_result(sink, accumulator, timing, source, profile, response_mode)
|
||||
|
||||
def _stream_result(
|
||||
self,
|
||||
sink: dict[str, Any],
|
||||
accumulator: ChatCompletionAccumulator,
|
||||
timing: _StreamTiming,
|
||||
source: SourceConfig,
|
||||
profile: ProviderProfile,
|
||||
response_mode: ResponseMode,
|
||||
) -> TransportResult:
|
||||
"""流结束后的统一判定(设计 §4.2-§4.3): 完整性 → 结局 → 组装。"""
|
||||
self._warn_dialect(source, accumulator.conflicts, accumulator.finish_reason)
|
||||
thinking_parts = timing.reasoning_parts if timing.has_reasoning else timing.alias_parts
|
||||
content, thinking = self._finalize_text(timing.content_parts, thinking_parts, profile)
|
||||
stream_end = _stream_is_complete(
|
||||
done=bool(sink.get("done")),
|
||||
finish_reason=accumulator.finish_reason,
|
||||
usage_after_finish=accumulator.usage_after_finish,
|
||||
usage_measured=_resolve_usage(sink.get("usage") or {})[2] == "measured",
|
||||
)
|
||||
if stream_end is None:
|
||||
stream_end = self._truncated(timing, thinking_parts, source, response_mode)
|
||||
message = accumulator.raw_message() if response_mode == "openai" else None
|
||||
_raise_unless_deliverable(
|
||||
response_mode, message, content, thinking, accumulator.finish_reason, source
|
||||
)
|
||||
completion_result = accumulator.finish() if response_mode == "openai" else None
|
||||
prompt, completion, usage_source = _resolve_stream_usage(sink, stream_end == "salvaged")
|
||||
reasoning_tokens = _coerce_reasoning_tokens(sink.get("usage"))
|
||||
stall_ms, stall_count = _stall_from_chunk_times(chunk_times, source.stall_threshold_ms)
|
||||
stall_ms, stall_count = _stall_from_chunk_times(
|
||||
timing.chunk_times, source.stall_threshold_ms
|
||||
)
|
||||
return TransportResult(
|
||||
content=content,
|
||||
thinking=thinking,
|
||||
prompt_tokens=prompt,
|
||||
completion_tokens=completion,
|
||||
usage_source=usage_source,
|
||||
ttft_ms=ttft_ms,
|
||||
max_inter_token_ms=(max_gap if ttft_ms is not None else None),
|
||||
ttft_ms=timing.ttft_ms,
|
||||
max_inter_token_ms=(timing.max_gap if timing.ttft_ms is not None else None),
|
||||
stall_ms=stall_ms,
|
||||
stall_count=stall_count,
|
||||
raw={"usage": sink.get("usage")},
|
||||
completion=completion_result,
|
||||
cached_prompt_tokens=_coerce_cached_tokens(sink.get("usage")),
|
||||
model_reported=_coerce_model_reported(sink.get("model")),
|
||||
reasoning_tokens=reasoning_tokens,
|
||||
@@ -651,38 +821,56 @@ class OpenAICompatTransport:
|
||||
thinking_observation=observe_thinking(
|
||||
thinking=thinking, reasoning_tokens=reasoning_tokens
|
||||
),
|
||||
finish_reason=accumulator.finish_reason,
|
||||
stream_end=stream_end,
|
||||
)
|
||||
|
||||
def _check_done(
|
||||
def _truncated(
|
||||
self,
|
||||
sink: dict[str, Any],
|
||||
content_parts: list[str],
|
||||
timing: _StreamTiming,
|
||||
thinking_parts: list[str],
|
||||
source: SourceConfig,
|
||||
) -> bool:
|
||||
"""缺 [DONE] 语义(设计 §6): 零内容恒 retry;有内容按 missing_done 策略。"""
|
||||
if sink.get("done"):
|
||||
return False
|
||||
response_mode: ResponseMode,
|
||||
) -> StreamEnd:
|
||||
"""截断流(设计 §4.2): 保真不打捞;文本按 missing_done,零产物恒 retry。"""
|
||||
ctx: dict[str, Any] = {"source_name": source.name, "operation": "chat"}
|
||||
if not content_parts and not thinking_parts:
|
||||
if response_mode == "openai":
|
||||
raise TransientError(f"{source.name} missing_done: 保真响应截断,禁止打捞", **ctx)
|
||||
if not any(timing.content_parts) and not any(thinking_parts):
|
||||
raise TransientError(f"{source.name} SSE early_eof: 零内容断流", **ctx)
|
||||
if source.missing_done == "retry":
|
||||
raise TransientError(f"{source.name} SSE missing_done: 截断且无 [DONE]", **ctx)
|
||||
return True
|
||||
return "salvaged"
|
||||
|
||||
def _reject_empty_completion(self, content: str, source: SourceConfig) -> None:
|
||||
"""空补全 → 瞬时错误(2026-07-20 人类裁决,M1 验证发现)。
|
||||
|
||||
服务 200 且流程完整([DONE]/usage 正常)但 content 为空——MiniMax 等
|
||||
网关的间歇异常形态。视为服务抖动: 退避重试/换源,**绝不缓存空响应**;
|
||||
承 CHS "VLM 零 content"归瞬时的先例(invokers.py:309)。
|
||||
"""
|
||||
if not content.strip():
|
||||
raise TransientError(
|
||||
f"{source.name} 空补全(empty_completion): 流程完整但零内容",
|
||||
source_name=source.name,
|
||||
operation="chat",
|
||||
def _warn_dialect(
|
||||
self, source: SourceConfig, conflicts: frozenset[str], finish_reason: str | None
|
||||
) -> None:
|
||||
"""方言告警: 冲突删键与未登记 finish 各按 (源, 路径/值) 只喊一次。"""
|
||||
for raw_path in sorted(conflicts):
|
||||
path = raw_path[:_PATH_WARN_CHARS] # 键名由上游决定,长度同样须有界
|
||||
self._warn_once(
|
||||
source.name, f"field:{path}", f"字段 {path} 合并冲突已删除,保真结果缺该字段"
|
||||
)
|
||||
if finish_reason is not None and _classify_finish(finish_reason) == "unknown":
|
||||
value = finish_reason[:_FINISH_WARN_CHARS]
|
||||
self._warn_once(
|
||||
source.name,
|
||||
f"finish:{value}",
|
||||
f"未登记的 finish_reason {value!r},按正常结束交付,该值的结果不缓存",
|
||||
)
|
||||
|
||||
def _warn_once(self, source_name: str, key: str, text: str) -> None:
|
||||
"""有界节流: 键由上游决定,长跑 worker 不能让集合无限增长(设计 §5.4)。"""
|
||||
if (source_name, key) in self._warned_fields:
|
||||
return
|
||||
if len(self._warned_fields) >= _WARN_CAP:
|
||||
if not self._warn_saturated:
|
||||
self._warn_saturated = True
|
||||
logger.warning("方言告警节流集合已饱和({}),后续同类告警省略", _WARN_CAP)
|
||||
return
|
||||
self._warned_fields.add((source_name, key))
|
||||
# 单参数传入 loguru: 文案可能含上游给的花括号(同 `_warn_on_thinking_mismatch`)
|
||||
logger.warning("源 {} —— {}", source_name, text)
|
||||
|
||||
def _finalize_text(
|
||||
self, content_parts: list[str], thinking_parts: list[str], profile: ProviderProfile
|
||||
@@ -704,6 +892,7 @@ class OpenAICompatTransport:
|
||||
profile: ProviderProfile,
|
||||
first_token_event: asyncio.Event | None,
|
||||
content_event: asyncio.Event | None,
|
||||
response_mode: ResponseMode,
|
||||
) -> TransportResult:
|
||||
"""非流式快路径(三项目均无,库新增): 单 JSON 响应,仅 total 超时。
|
||||
|
||||
@@ -711,6 +900,9 @@ class OpenAICompatTransport:
|
||||
为纯时间阈值(对冲只能靠 `hedge_after_s` 触发)。`content_event`(1.3.8)
|
||||
同款: 接收但**永不置位**——非流式无"中段"概念,stall 两值走
|
||||
TransportResult 默认 None(排除条款)。
|
||||
|
||||
无流完整性可言,直接以 body 的 finish_reason 走结局判定;保真模式**先判定
|
||||
后构造快照**,否则半截工具在构造时就抛 Transient,到不了 `tool_truncated`。
|
||||
"""
|
||||
resp = await client.post(url, json=payload)
|
||||
if resp.status_code != 200:
|
||||
@@ -723,16 +915,17 @@ class OpenAICompatTransport:
|
||||
raise TransientError(
|
||||
f"{source.name} 非流式响应非法 JSON", source_name=source.name, operation="chat"
|
||||
) from exc
|
||||
choices = body.get("choices") or []
|
||||
if not choices:
|
||||
raise TransientError(
|
||||
f"{source.name} 响应缺 choices", source_name=source.name, operation="chat"
|
||||
)
|
||||
message = choices[0].get("message") or {}
|
||||
_check_chat_error(body)
|
||||
message, finish = _nonstream_message(body, response_mode, source)
|
||||
content, thinking = self._finalize_text(
|
||||
[message.get("content") or ""], [message.get("reasoning_content") or ""], profile
|
||||
[message.get("content") or ""], [_reasoning_of(message)], profile
|
||||
)
|
||||
self._warn_dialect(source, frozenset(), finish)
|
||||
raw_message = message if response_mode == "openai" else None
|
||||
_raise_unless_deliverable(response_mode, raw_message, content, thinking, finish, source)
|
||||
completion_result = (
|
||||
build_completion(message, body, finish) if response_mode == "openai" else None
|
||||
)
|
||||
self._reject_empty_completion(content, source)
|
||||
prompt, completion, usage_source = _resolve_usage(body.get("usage") or {})
|
||||
reasoning_tokens = _coerce_reasoning_tokens(body.get("usage"))
|
||||
return TransportResult(
|
||||
@@ -744,6 +937,7 @@ class OpenAICompatTransport:
|
||||
ttft_ms=None,
|
||||
max_inter_token_ms=None,
|
||||
raw={"usage": body.get("usage")},
|
||||
completion=completion_result,
|
||||
cached_prompt_tokens=_coerce_cached_tokens(body.get("usage")),
|
||||
model_reported=_coerce_model_reported(body.get("model")),
|
||||
reasoning_tokens=reasoning_tokens,
|
||||
@@ -752,6 +946,7 @@ class OpenAICompatTransport:
|
||||
thinking_observation=observe_thinking(
|
||||
thinking=thinking, reasoning_tokens=reasoning_tokens
|
||||
),
|
||||
finish_reason=finish,
|
||||
)
|
||||
|
||||
async def aclose(self) -> None:
|
||||
|
||||
@@ -4,6 +4,7 @@
|
||||
fake,字段顺序即公共承诺;新增字段只增不删且必带默认值。
|
||||
"""
|
||||
|
||||
import copy
|
||||
import dataclasses
|
||||
import json
|
||||
import math
|
||||
@@ -422,6 +423,280 @@ class _CallContext:
|
||||
return True
|
||||
|
||||
|
||||
ResponseMode = Literal["text", "openai"]
|
||||
|
||||
StreamEnd = Literal["done", "eof_after_finish", "salvaged"]
|
||||
"""流式结束方式(1.3.10, #31): `done` = 收到 `[DONE]`;`eof_after_finish` = 未发
|
||||
`[DONE]` 但 finish_reason 与其后的实测 usage 齐全、连接干净关闭;`salvaged` = 文本
|
||||
模式按 `missing_done=salvage` 打捞的截断结果。非流式/缓存命中/失败行为 `None`。"""
|
||||
|
||||
FinishClass = Literal["natural", "truncated", "filtered", "upstream_error", "unknown", "absent"]
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class OpenAIChatCompletion:
|
||||
"""单 choice 协议结果，构造时快照隔离；嵌套 JSON 仍可变。"""
|
||||
|
||||
message: dict[str, Any]
|
||||
finish_reason: str | None
|
||||
response_id: str | None
|
||||
usage: dict[str, Any] | None
|
||||
|
||||
def __post_init__(self) -> None:
|
||||
"""校验协议快照；transport 翻译错误，缓存坏条目按 miss。"""
|
||||
message = self.message
|
||||
_check_completion_shape(message, self.finish_reason, self.response_id, self.usage)
|
||||
json.dumps({"message": message, "usage": self.usage}, allow_nan=False)
|
||||
object.__setattr__(self, "message", copy.deepcopy(message))
|
||||
object.__setattr__(self, "usage", copy.deepcopy(self.usage))
|
||||
|
||||
|
||||
def _check_completion_shape(message: Any, finish_reason: Any, response_id: Any, usage: Any) -> None:
|
||||
"""快照字段形态校验;违约抛 ValueError(由 transport/缓存各自翻译)。"""
|
||||
if not isinstance(message, dict) or message.get("role") != "assistant":
|
||||
raise ValueError("completion message 必须含 assistant role")
|
||||
if not all(_str_or_none(message.get(key)) for key in ("content", "reasoning_content")):
|
||||
raise ValueError("completion content/reasoning_content 必须为字符串或 null")
|
||||
if not (_str_or_none(finish_reason) and _str_or_none(response_id)):
|
||||
raise ValueError("completion 身份/结束原因必须为字符串或 null")
|
||||
if not isinstance(usage, dict | None):
|
||||
raise ValueError("completion usage 必须为对象或 null")
|
||||
if not isinstance(message.get("tool_calls", []), list | None):
|
||||
raise ValueError("completion tool_calls 必须为数组或 null")
|
||||
if not _tool_snapshot_ok(message):
|
||||
raise ValueError("completion tool 身份/函数字段缺失、冲突或非法")
|
||||
|
||||
|
||||
def _str_or_none(value: Any) -> bool:
|
||||
"""协议字符串字段的形态判据: 字符串或 null。"""
|
||||
return value is None or isinstance(value, str)
|
||||
|
||||
|
||||
def _tool_ok(tool: Any, seen: set[str]) -> bool:
|
||||
"""单个工具条目是否满足快照不变式;成立时登记其 id 供查重。"""
|
||||
if not isinstance(tool, dict):
|
||||
return False
|
||||
identity, fn = tool.get("id"), tool.get("function")
|
||||
ok = (
|
||||
isinstance(identity, str)
|
||||
and bool(identity)
|
||||
and identity not in seen
|
||||
and tool.get("type") == "function"
|
||||
and isinstance(fn, dict)
|
||||
and isinstance(fn.get("name"), str)
|
||||
and bool(fn["name"])
|
||||
and isinstance(fn.get("arguments"), str)
|
||||
)
|
||||
if ok:
|
||||
seen.add(identity)
|
||||
return ok
|
||||
|
||||
|
||||
def _tool_snapshot_ok(message: Mapping[str, Any]) -> bool:
|
||||
"""工具快照不变式(1.3.9 规则): 缺省/null 视无工具;null 元素跳过。
|
||||
|
||||
抽成纯判据而非留在快照构造里: 结局判定(#30)要在构造**之前**知道工具是否
|
||||
成立——截断的半截工具归 ResultInvalid,构造时抛 Transient 就到不了那一行。
|
||||
"""
|
||||
tools = message.get("tool_calls")
|
||||
if tools is None:
|
||||
return True
|
||||
if not isinstance(tools, list):
|
||||
return False
|
||||
seen: set[str] = set()
|
||||
return all(tool is None or _tool_ok(tool, seen) for tool in tools)
|
||||
|
||||
|
||||
_FINISH_CLASSES: Mapping[str, FinishClass] = MappingProxyType(
|
||||
{
|
||||
"stop": "natural",
|
||||
"tool_calls": "natural",
|
||||
"function_call": "natural",
|
||||
"length": "truncated",
|
||||
"content_filter": "filtered",
|
||||
"sensitive": "filtered", # GLM: 安全审核拦截
|
||||
"network_error": "upstream_error", # GLM: 模型推理异常
|
||||
"error": "upstream_error",
|
||||
}
|
||||
)
|
||||
|
||||
|
||||
def _classify_finish(value: str | None) -> FinishClass:
|
||||
"""finish_reason → 类别;大小写敏感(上游原值),未登记非空值为 unknown。"""
|
||||
if value is None:
|
||||
return "absent"
|
||||
return _FINISH_CLASSES.get(value, "unknown")
|
||||
|
||||
|
||||
def _stream_is_complete(
|
||||
*, done: bool, finish_reason: str | None, usage_after_finish: bool, usage_measured: bool
|
||||
) -> StreamEnd | None:
|
||||
"""流完整性(设计 §4.2): None = 截断。
|
||||
|
||||
缺 `[DONE]` 时只认"上游声明结束 + 其后到达的实测 usage": 前者证明生成结束,
|
||||
后者证明流走到了 include_usage 的自然末尾(finish 之前的累计 usage 不算)。
|
||||
"""
|
||||
if done:
|
||||
return "done"
|
||||
if finish_reason is not None and usage_after_finish and usage_measured:
|
||||
return "eof_after_finish"
|
||||
return None
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class _OutputSummary:
|
||||
"""一次结果的产物摘要(设计 §4.3 定义),判定的唯一输入形态。"""
|
||||
|
||||
any_output: bool
|
||||
body_output: bool
|
||||
tools_present: bool
|
||||
tools_ok: bool
|
||||
null_arguments: bool = False
|
||||
"""工具快照仅因 `function.arguments` 全程 null 而不成立(无参函数方言,审查 I2)。"""
|
||||
|
||||
|
||||
def _summarize_text(content: str, thinking: str) -> _OutputSummary:
|
||||
"""文本模式: 产物只看投影正文与思考;空白也算产物,正文须非空白。"""
|
||||
return _OutputSummary(
|
||||
any_output=content != "" or thinking != "",
|
||||
body_output=content.strip() != "",
|
||||
tools_present=False,
|
||||
tools_ok=True,
|
||||
)
|
||||
|
||||
|
||||
def _has_string(value: Any) -> bool:
|
||||
"""递归查找任一非空字符串片段。"""
|
||||
if isinstance(value, str):
|
||||
return value != ""
|
||||
if isinstance(value, dict):
|
||||
return any(_has_string(item) for item in value.values())
|
||||
if isinstance(value, list):
|
||||
return any(_has_string(item) for item in value)
|
||||
return False
|
||||
|
||||
|
||||
def _summarize_message(message: Mapping[str, Any], projected_content: str) -> _OutputSummary:
|
||||
"""保真模式: 任一非空字符串字段(role 除外)或工具条目即产物。"""
|
||||
tools = message.get("tool_calls")
|
||||
tools_present = isinstance(tools, list) and any(tool is not None for tool in tools)
|
||||
tools_ok = _tool_snapshot_ok(message)
|
||||
fields = {k: v for k, v in message.items() if k not in ("role", "tool_calls")}
|
||||
return _OutputSummary(
|
||||
any_output=tools_present or _has_string(fields),
|
||||
body_output=projected_content.strip() != "" or (tools_present and tools_ok),
|
||||
tools_present=tools_present,
|
||||
tools_ok=tools_ok,
|
||||
null_arguments=not tools_ok and _tool_snapshot_ok(_fill_null_arguments(message)),
|
||||
)
|
||||
|
||||
|
||||
def _fill_null_arguments(message: Mapping[str, Any]) -> dict[str, Any]:
|
||||
"""仅供判定: 把 null arguments 视作空串后再验快照,区分"只缺参数"与其他缺陷。
|
||||
|
||||
不改写交付值——保真结果原样;此函数的产物只用于分类。
|
||||
"""
|
||||
tools = message.get("tool_calls")
|
||||
if not isinstance(tools, list):
|
||||
return dict(message)
|
||||
filled = []
|
||||
for tool in tools:
|
||||
fn = tool.get("function") if isinstance(tool, dict) else None
|
||||
if isinstance(fn, dict) and "arguments" in fn and fn["arguments"] is None:
|
||||
tool = {**tool, "function": {**fn, "arguments": ""}}
|
||||
filled.append(tool)
|
||||
return {**message, "tool_calls": filled}
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class _Verdict:
|
||||
"""结局判定;`deliver` 为真时另两字段为 None。"""
|
||||
|
||||
deliver: bool
|
||||
error_kind: Literal["transient", "result_invalid"] | None
|
||||
code: str | None
|
||||
|
||||
|
||||
_DELIVER = _Verdict(True, None, None)
|
||||
_EMPTY = _Verdict(False, "transient", "empty_completion")
|
||||
_WITHOUT_CONTENT: Mapping[str, str] = MappingProxyType(
|
||||
{"truncated": "length_without_content", "filtered": "filtered_without_content"}
|
||||
)
|
||||
|
||||
|
||||
def _judge_broken(
|
||||
*, mode: ResponseMode, summary: _OutputSummary, finish: FinishClass
|
||||
) -> _Verdict | None:
|
||||
"""行 1-2: 上游自报失败、坏工具——先于产物判断,正文不得掩盖。"""
|
||||
if finish == "upstream_error":
|
||||
return _Verdict(False, "transient", "upstream_finish_error")
|
||||
if mode == "openai" and summary.tools_present and not summary.tools_ok:
|
||||
if finish == "truncated":
|
||||
return _Verdict(False, "result_invalid", "tool_truncated")
|
||||
if summary.null_arguments:
|
||||
# 无参函数只发 arguments:null 是确定性方言: 重拉同样结果,不重试也不改写
|
||||
return _Verdict(False, "result_invalid", "tool_arguments_null")
|
||||
return _Verdict(False, "transient", "tool_incomplete")
|
||||
return None
|
||||
|
||||
|
||||
def _judge_outcome(*, mode: ResponseMode, summary: _OutputSummary, finish: FinishClass) -> _Verdict:
|
||||
"""结局分类(设计 §4.3),自上而下首个匹配行生效。
|
||||
|
||||
确定性结局(length/过滤)在文本模式归 ResultInvalid 而非 Transient: 重抽只会
|
||||
再花一份钱,还会把健康源推向熔断;保真模式原样交回,由下游按 finish 决定。
|
||||
"""
|
||||
broken = _judge_broken(mode=mode, summary=summary, finish=finish)
|
||||
if broken is not None:
|
||||
return broken
|
||||
if summary.body_output:
|
||||
return _DELIVER
|
||||
if finish in _WITHOUT_CONTENT: # 行 3/6/7: 确定性结局
|
||||
if mode == "openai":
|
||||
return _DELIVER
|
||||
return _Verdict(False, "result_invalid", _WITHOUT_CONTENT[finish])
|
||||
# 行 4/8/9: 零产物恒为抖动;有产物无正文时,只有保真且上游明确声明结束才交回
|
||||
if summary.any_output and mode == "openai" and finish != "absent":
|
||||
return _DELIVER
|
||||
return _EMPTY
|
||||
|
||||
|
||||
def _effective_finish(finish_reason: Any, completion: OpenAIChatCompletion | None) -> str | None:
|
||||
"""缓存读写共用的 finish 口径: 顶层优先,缺省回退协议快照(1.3.9 条目无顶层)。"""
|
||||
if finish_reason is None and completion is not None:
|
||||
return completion.finish_reason
|
||||
return finish_reason
|
||||
|
||||
|
||||
def _is_cacheable(
|
||||
*,
|
||||
mode: ResponseMode,
|
||||
content: str,
|
||||
finish_reason: str | None,
|
||||
stream_end: str | None,
|
||||
completion: OpenAIChatCompletion | None,
|
||||
) -> bool:
|
||||
"""可缓存 ⊂ 可交付(设计 §6): 截断、空正文、非自然结束一律不进 TTL。
|
||||
|
||||
缓存回放的是"同一请求的确定答案";length/过滤/未知结束带随机性或不可证明
|
||||
是自然结束,固化进 TTL 会把一次偶然变成必然(无缓存毒化铁律)。
|
||||
"""
|
||||
if stream_end not in (None, "done", "eof_after_finish"):
|
||||
return False
|
||||
if _classify_finish(finish_reason) not in ("natural", "absent"):
|
||||
return False
|
||||
if mode == "openai":
|
||||
# 判原文而非投影: 协议原文为空时不信任缓存里的旧投影(1.3.9 同口径)
|
||||
if completion is None:
|
||||
return False
|
||||
raw = completion.message.get("content")
|
||||
summary = _summarize_message(completion.message, raw if isinstance(raw, str) else "")
|
||||
# 原文与投影都须有正文: 原文空不信任旧投影;投影空(think 标签剥净)不固化空回答
|
||||
has_tools = summary.tools_present and summary.tools_ok
|
||||
return summary.body_output and (content.strip() != "" or has_tools)
|
||||
return content.strip() != ""
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class LLMResponse:
|
||||
"""一次治理调用的统一响应(与三项目超集兼容,ARCH §5.1)。"""
|
||||
@@ -487,6 +762,15 @@ class LLMResponse:
|
||||
call_stats: CallStats | None = None
|
||||
"""本次**逻辑调用**的统计快照(1.3.5);`None` = 未知,不得读成 0。"""
|
||||
|
||||
completion: OpenAIChatCompletion | None = None
|
||||
|
||||
finish_reason: str | None = None
|
||||
"""上游结束原因原值(1.3.10, #30/#31),两模式同口径;`None` = 未上报或不可观测。"""
|
||||
|
||||
stream_end: StreamEnd | None = None
|
||||
"""流式结束方式(1.3.10, #31),见 `StreamEnd`。与 `usage_source` 分工: 那个答
|
||||
"账单可信吗",这个答"内容完整吗";`eof_after_finish` 必为 measured。"""
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class ChatRequest:
|
||||
@@ -543,6 +827,8 @@ class ChatRequest:
|
||||
洋葱各层经 `dataclasses.replace` 派生请求时保留**同一引用**(不是拷贝),
|
||||
重试/重问/分批才能共享同一个逻辑 ID 与计数。"""
|
||||
|
||||
response_mode: ResponseMode = "text"
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Usage:
|
||||
@@ -627,6 +913,15 @@ class TransportResult:
|
||||
"""超阈值相邻间隔个数(归因成对报告,Gregg 原则);值域与 `None` 语义同
|
||||
`stall_ms`。"""
|
||||
|
||||
completion: OpenAIChatCompletion | None = None
|
||||
|
||||
finish_reason: str | None = None
|
||||
"""上游结束原因原值(1.3.10, #30/#31),两模式同口径;`None` = 未上报或不可观测。"""
|
||||
|
||||
stream_end: StreamEnd | None = None
|
||||
"""流式结束方式(1.3.10, #31),见 `StreamEnd`。与 `usage_source` 分工: 那个答
|
||||
"账单可信吗",这个答"内容完整吗";`eof_after_finish` 必为 measured。"""
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class SourceConfig:
|
||||
|
||||
@@ -22,7 +22,13 @@ from polygateway.client import (
|
||||
)
|
||||
from polygateway.providers import get_provider
|
||||
from polygateway.transports.openai_compat import OpenAICompatTransport
|
||||
from polygateway.types import Effort, EmbeddingTransportResult, SourceConfig, TransportResult
|
||||
from polygateway.types import (
|
||||
Effort,
|
||||
EmbeddingTransportResult,
|
||||
ResponseMode,
|
||||
SourceConfig,
|
||||
TransportResult,
|
||||
)
|
||||
from tests.live_evidence import (
|
||||
AttemptEvidence,
|
||||
HttpEvidence,
|
||||
@@ -293,6 +299,7 @@ class ObservedTransport:
|
||||
reasoning_effort: Effort | None,
|
||||
first_token_event: asyncio.Event | None,
|
||||
content_event: asyncio.Event | None,
|
||||
response_mode: ResponseMode,
|
||||
) -> TransportResult:
|
||||
"""与生产端口逐参数同签名。"""
|
||||
with self._capture.attempt_context(call_id):
|
||||
@@ -306,6 +313,7 @@ class ObservedTransport:
|
||||
reasoning_effort=reasoning_effort,
|
||||
first_token_event=first_token_event,
|
||||
content_event=content_event,
|
||||
response_mode=response_mode,
|
||||
)
|
||||
|
||||
async def embed(
|
||||
|
||||
@@ -0,0 +1,114 @@
|
||||
"""真实网关工具双轮冒烟；复用安全 Markdown 报告，不运行工具副作用。"""
|
||||
|
||||
import dataclasses
|
||||
import json
|
||||
import os
|
||||
from pathlib import Path
|
||||
from uuid import uuid4
|
||||
|
||||
import pytest
|
||||
from dotenv import dotenv_values
|
||||
|
||||
from polygateway import GatewayClient, GatewaySettings
|
||||
from tests.live_evidence import write_live_round
|
||||
|
||||
_ENV = {k: v for k, v in {**dotenv_values(".env"), **os.environ}.items() if v is not None}
|
||||
pytestmark = [pytest.mark.slow, pytest.mark.requires_llm]
|
||||
|
||||
|
||||
@pytest.mark.parametrize("stream", [True, False])
|
||||
async def test_tools_two_rounds(stream):
|
||||
"""已配置源中选首源，只改变测试隔离与 raw-only 意图，不收紧生产超时。"""
|
||||
if not any(k.startswith("LLM__") and k.endswith("__API_KEY") for k in _ENV):
|
||||
pytest.skip("未配置真实源，未覆盖")
|
||||
settings = GatewaySettings.from_env("LLM", env=_ENV)
|
||||
source = dataclasses.replace(settings.sources[0], enable_thinking=None, reasoning_effort=None)
|
||||
settings = dataclasses.replace(
|
||||
settings,
|
||||
sources=(source,),
|
||||
cache_backend="none",
|
||||
cache_namespace=None,
|
||||
cache_ttl_s=None,
|
||||
telemetry_backend="none",
|
||||
telemetry_auto_migrate=False,
|
||||
limiter_backend="memory",
|
||||
breaker_backend="memory",
|
||||
hedge_after_s=None,
|
||||
hedge_stall_after_s=None,
|
||||
)
|
||||
tools = [
|
||||
{
|
||||
"type": "function",
|
||||
"function": {
|
||||
"name": "echo_value",
|
||||
"description": "Return the supplied value",
|
||||
"parameters": {
|
||||
"type": "object",
|
||||
"properties": {"value": {"type": "string"}},
|
||||
"required": ["value"],
|
||||
},
|
||||
},
|
||||
}
|
||||
]
|
||||
messages = [
|
||||
{
|
||||
"role": "user",
|
||||
"content": "Call echo_value with value hello. After receiving the tool result, reply with hello.",
|
||||
}
|
||||
]
|
||||
status, error_type, counts = "FAIL", None, {}
|
||||
try:
|
||||
async with GatewayClient.from_settings(settings) as client:
|
||||
first = await client.chat(
|
||||
messages,
|
||||
stream=stream,
|
||||
response_mode="openai",
|
||||
overlay={
|
||||
"tools": tools,
|
||||
"tool_choice": {"type": "function", "function": {"name": "echo_value"}},
|
||||
},
|
||||
)
|
||||
completion = first.completion
|
||||
assert completion is not None and completion.message["role"] == "assistant"
|
||||
assert completion.response_id and completion.finish_reason == "tool_calls"
|
||||
calls = completion.message["tool_calls"]
|
||||
counts["tools"] = len(calls)
|
||||
assert calls
|
||||
messages.append(completion.message)
|
||||
for call in calls:
|
||||
assert call["function"]["name"] == "echo_value"
|
||||
arguments = json.loads(call["function"]["arguments"])
|
||||
assert arguments["value"] == "hello"
|
||||
messages.append(
|
||||
{"role": "tool", "tool_call_id": call["id"], "content": arguments["value"]}
|
||||
)
|
||||
second = await client.chat(
|
||||
messages,
|
||||
stream=stream,
|
||||
response_mode="openai",
|
||||
overlay={"tools": tools, "tool_choice": "none"},
|
||||
)
|
||||
assert (
|
||||
second.completion is not None and second.completion.message["role"] == "assistant"
|
||||
)
|
||||
assert "hello" in (second.completion.message.get("content") or "").lower()
|
||||
counts["attempts"] = first.call_stats.attempts + second.call_stats.attempts
|
||||
status = "PASS"
|
||||
except Exception as exc:
|
||||
error_type = type(exc).__name__
|
||||
raise
|
||||
finally:
|
||||
write_live_round(
|
||||
Path("tests/outputs/issue29/live"),
|
||||
run_id=uuid4().hex,
|
||||
matrix_id="tools",
|
||||
round_index=1,
|
||||
safe_fields={
|
||||
"status": status,
|
||||
"stream": stream,
|
||||
"error_type": error_type,
|
||||
"counts": counts,
|
||||
"planned_rounds": 2,
|
||||
"completed_rounds": 2 if status == "PASS" else 0,
|
||||
},
|
||||
)
|
||||
@@ -72,6 +72,8 @@ _EXPECTED_COLUMNS = [
|
||||
# —— 1.3.8 沉默归因两列(issue #27)——
|
||||
"stall_ms",
|
||||
"stall_count",
|
||||
# —— 1.3.10 结束方式(#31)——
|
||||
"stream_end",
|
||||
]
|
||||
|
||||
# 1.3.5 之前那张表的 27 个物理列(26 个 INSERT 字段 + created_at)。写成固定切片
|
||||
@@ -173,6 +175,8 @@ def _minimal_fields(call_id: str | None = None, **overrides) -> dict[str, object
|
||||
# —— 1.3.8 两列: 沉默归因只属流式 chat 成功 attempt 行(issue #27),普通行 NULL ——
|
||||
"stall_ms": None,
|
||||
"stall_count": None,
|
||||
# —— 1.3.10: 结束方式只属流式成功 attempt 行,普通行 NULL ——
|
||||
"stream_end": None,
|
||||
}
|
||||
fields.update(overrides)
|
||||
return fields
|
||||
@@ -775,7 +779,7 @@ class TestCallerDimensionsAcceptance:
|
||||
"WHERE table_schema = $1 AND table_name = 'llm_calls' ORDER BY ordinal_position",
|
||||
schema,
|
||||
)
|
||||
# 22 → 38 个 recorder 字段(加 created_at 共 39 个物理列),且新列追加在末尾
|
||||
# 22 → 39 个 recorder 字段(加 created_at 共 40 个物理列),且新列追加在末尾
|
||||
assert [r["column_name"] for r in cols] == _EXPECTED_COLUMNS
|
||||
rows = await _fetch(
|
||||
schema_dsn,
|
||||
@@ -1106,7 +1110,7 @@ class TestCallObservabilityColumnsAcceptance:
|
||||
"""
|
||||
|
||||
async def test_pre_135_table_gains_the_ten_columns_and_old_rows_stay_null(self, pre_135_schema):
|
||||
"""27 列旧表 auto 补齐到 39 列(1.3.5 十列 + 1.3.8 两列),新行两类取值读得回,**历史行新增列一律 NULL**。
|
||||
"""27 列旧表 auto 补齐到 40 列(1.3.5 十列 + 1.3.8 两列 + 1.3.10 一列),新行两类取值读得回,**历史行新增列一律 NULL**。
|
||||
|
||||
旧行不回填是本版的明示决策(设计 §5): NULL 表达的是"补列之前根本没记过
|
||||
这件事",与任何哨兵值都不是一回事。若哪天有人给这十列加了 DEFAULT,历史行
|
||||
@@ -1148,7 +1152,7 @@ class TestCallObservabilityColumnsAcceptance:
|
||||
"WHERE table_schema = $1 AND table_name = 'llm_calls' ORDER BY ordinal_position",
|
||||
schema,
|
||||
)
|
||||
# 26 → 38 个 recorder 字段(加 created_at 共 39 个物理列),新列追加在末尾:
|
||||
# 26 → 39 个 recorder 字段(加 created_at 共 40 个物理列),新列追加在末尾:
|
||||
# 列序与新建库一致才不会让两条升级路径分叉
|
||||
assert [r["column_name"] for r in cols] == _EXPECTED_COLUMNS
|
||||
|
||||
@@ -1176,6 +1180,8 @@ class TestCallObservabilityColumnsAcceptance:
|
||||
# 1.3.8 两列: 普通成功 attempt 行无沉默观测 → NULL
|
||||
"stall_ms": None,
|
||||
"stall_count": None,
|
||||
# 1.3.10: 该行未传结束方式 → NULL
|
||||
"stream_end": None,
|
||||
}
|
||||
assert dict(by_id["term"]) == {
|
||||
"call_id": "term",
|
||||
@@ -1192,6 +1198,8 @@ class TestCallObservabilityColumnsAcceptance:
|
||||
# 1.3.8 两列: 终态行无 transport 观测 → NULL
|
||||
"stall_ms": None,
|
||||
"stall_count": None,
|
||||
# 1.3.10: 终态行无流可言 → NULL
|
||||
"stream_end": None,
|
||||
}
|
||||
# 历史行: 十列逐列 NULL(整体比对,漏掉任一列都红)
|
||||
assert dict(by_id["pre135"]) == {
|
||||
@@ -1349,7 +1357,7 @@ class TestPublishedSchemaScript:
|
||||
|
||||
await _execute_script(fresh_dsn, script)
|
||||
actual = [r["column_name"] for r in await _fetch(fresh_dsn, _PHYSICAL_COLUMNS_SQL, schema)]
|
||||
# 物理列 = 38 个 INSERT 字段 + 库从不显式写的 created_at;对着库常量比,不另抄一份
|
||||
# 物理列 = 39 个 INSERT 字段 + 库从不显式写的 created_at;对着库常量比,不另抄一份
|
||||
assert set(actual) == set(COLUMNS) | {"created_at"}
|
||||
# 列序也不许漂: 新列必须排在 created_at 之后,否则新建库与 ALTER 升级的列序分叉
|
||||
assert actual == _EXPECTED_COLUMNS
|
||||
|
||||
@@ -30,6 +30,13 @@ def _resp(content="cached"):
|
||||
return LLMResponse(content, "", "m", "p", 1, 2, 30, None, None, False, "orig")
|
||||
|
||||
|
||||
def _const(response):
|
||||
async def terminal(request):
|
||||
return response
|
||||
|
||||
return terminal
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
async def redis_cache():
|
||||
import redis.asyncio as aioredis
|
||||
@@ -82,6 +89,23 @@ class TestRealRedisRoundtrip:
|
||||
assert first.cache_hit is False and second.cache_hit is True
|
||||
assert calls["n"] == 1
|
||||
|
||||
async def test_completion_verdict_fields_roundtrip(self, redis_cache, namespace):
|
||||
"""1.3.10: finish_reason/stream_end 经真实 Redis 往返;不可缓存结果不落库。"""
|
||||
mw = CacheMW(
|
||||
backend=redis_cache, model_fingerprint="m", default_namespace=namespace, ttl_s=60
|
||||
)
|
||||
from dataclasses import replace
|
||||
|
||||
ok = replace(_resp(), finish_reason="stop", stream_end="eof_after_finish")
|
||||
first = await mw(ChatRequest(messages=_MSGS), _const(ok))
|
||||
second = await mw(ChatRequest(messages=_MSGS), _const(ok))
|
||||
assert first.cache_hit is False and second.cache_hit is True
|
||||
assert second.finish_reason == "stop" and second.stream_end is None
|
||||
truncated = replace(_resp(), stream_end="salvaged")
|
||||
other = [{"role": "user", "content": "integration-salvaged"}]
|
||||
await mw(ChatRequest(messages=other), _const(truncated))
|
||||
assert await redis_cache.get(build_cache_key("m", other, namespace, None)) is None
|
||||
|
||||
async def test_namespace_isolation_on_shared_instance(self, redis_cache, namespace):
|
||||
"""多项目共用同一 Redis 时,namespace 不同绝不互相命中(防毒化铁律)。"""
|
||||
other = f"pgw:test:{uuid.uuid4().hex}"
|
||||
@@ -172,3 +196,22 @@ class TestClientWithRealRedis:
|
||||
second = await client.chat(_MSGS)
|
||||
assert first.cache_hit is False and second.cache_hit is True
|
||||
assert second.content == "hello"
|
||||
|
||||
|
||||
async def test_real_completion_roundtrip(redis_cache, namespace):
|
||||
"""真实 Redis 保存完整嵌套协议对象，命中仍为值类型。"""
|
||||
from dataclasses import replace
|
||||
|
||||
from tests.unit.test_openai_completion import accumulate
|
||||
|
||||
completion = accumulate().finish()
|
||||
mw = CacheMW(backend=redis_cache, model_fingerprint="m", default_namespace=namespace, ttl_s=60)
|
||||
|
||||
async def terminal(_):
|
||||
return replace(_resp(), completion=completion)
|
||||
|
||||
request = ChatRequest(messages=_MSGS, response_mode="openai")
|
||||
first = await mw(request, terminal)
|
||||
second = await mw(request, terminal)
|
||||
assert second.cache_hit and second.completion == first.completion
|
||||
assert second.completion is not first.completion
|
||||
|
||||
@@ -86,6 +86,7 @@ class ScriptedTransport:
|
||||
reasoning_effort,
|
||||
first_token_event,
|
||||
content_event,
|
||||
response_mode,
|
||||
):
|
||||
self.calls.append(source.name)
|
||||
if self.hang:
|
||||
|
||||
@@ -221,6 +221,7 @@ class ClockAdvancingTransport:
|
||||
reasoning_effort,
|
||||
first_token_event,
|
||||
content_event,
|
||||
response_mode,
|
||||
):
|
||||
self.calls.append((source.name, call_id))
|
||||
advance, action = self.script.pop(0)
|
||||
|
||||
@@ -15,6 +15,7 @@ from polygateway.types import (
|
||||
ChatRequest,
|
||||
Effort,
|
||||
LLMResponse,
|
||||
OpenAIChatCompletion,
|
||||
SourceConfig,
|
||||
ThinkingObservation,
|
||||
)
|
||||
@@ -891,3 +892,238 @@ class TestCallStatsNotPoisoned:
|
||||
without = ChatRequest(messages=_MSGS)
|
||||
assert with_ctx.cache_namespace == without.cache_namespace
|
||||
assert digest_messages(with_ctx.messages) == digest_messages(without.messages)
|
||||
|
||||
|
||||
class TestOpenAICompletionCache:
|
||||
"""协议缓存不得混模式或把字典冒充公共值对象。"""
|
||||
|
||||
def test_mode_isolation_preserves_text_key(self):
|
||||
assert build_cache_key("m", _MSGS, "proj", None) == build_cache_key(
|
||||
"m", _MSGS, "proj", None, response_mode="text"
|
||||
)
|
||||
assert build_cache_key("m", _MSGS, "proj", None) != build_cache_key(
|
||||
"m", _MSGS, "proj", None, response_mode="openai"
|
||||
)
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
"completion",
|
||||
[
|
||||
None,
|
||||
{},
|
||||
{
|
||||
"message": {"content": "ok"},
|
||||
"finish_reason": "stop",
|
||||
"response_id": None,
|
||||
"usage": None,
|
||||
},
|
||||
],
|
||||
)
|
||||
async def test_missing_or_bad_completion_misses(self, completion):
|
||||
backend = InMemoryCache()
|
||||
mw = CacheMW(backend=backend, model_fingerprint="m", default_namespace="proj", ttl_s=60)
|
||||
raw = json.loads(mw._serialize(_resp()))
|
||||
raw["completion"] = completion
|
||||
assert (
|
||||
mw._rehydrate(json.dumps(raw), ChatRequest(messages=_MSGS, response_mode="openai"))
|
||||
is None
|
||||
)
|
||||
|
||||
async def test_serialization_failure_does_not_fail_call(self):
|
||||
mw = CacheMW(
|
||||
backend=InMemoryCache(), model_fingerprint="m", default_namespace="proj", ttl_s=60
|
||||
)
|
||||
response = _resp(cost=object())
|
||||
|
||||
async def terminal(_):
|
||||
return response
|
||||
|
||||
assert await mw(ChatRequest(messages=_MSGS), terminal) is response
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
"message",
|
||||
[
|
||||
{"role": "assistant"},
|
||||
{"role": "assistant", "content": None, "tool_calls": []},
|
||||
{"role": "assistant", "content": "", "tool_calls": []},
|
||||
{"role": "assistant", "content": " \n", "tool_calls": []},
|
||||
{"role": "assistant", "reasoning_content": "reason only"},
|
||||
],
|
||||
)
|
||||
@pytest.mark.parametrize("cached_content", ["", "stale projection"])
|
||||
async def test_openai_cache_without_output_misses_and_refills(message, cached_content):
|
||||
"""空协议产物不能靠旧投影正文伪装成功；miss 后回源并覆写。"""
|
||||
backend = InMemoryCache()
|
||||
mw = _mw(backend)
|
||||
request = ChatRequest(messages=_MSGS, response_mode="openai")
|
||||
key = build_cache_key("m", _MSGS, "proj", None, response_mode="openai")
|
||||
bad = _resp(
|
||||
content=cached_content,
|
||||
completion=OpenAIChatCompletion(message, "stop", "bad", None),
|
||||
)
|
||||
await backend.set(key, mw._serialize(bad), ttl_s=60)
|
||||
fresh = _resp(
|
||||
completion=OpenAIChatCompletion(
|
||||
{"role": "assistant", "content": "cached"}, "stop", "fresh", None
|
||||
)
|
||||
)
|
||||
terminal = _Terminal(fresh)
|
||||
result = await mw(request, terminal)
|
||||
assert terminal.calls == 1 and result is fresh and not result.cache_hit
|
||||
hit = await mw(request, terminal)
|
||||
assert terminal.calls == 1 and hit.cache_hit
|
||||
assert hit.completion.response_id == "fresh"
|
||||
|
||||
|
||||
async def test_openai_tool_only_cache_hits_without_origin():
|
||||
"""有效工具本身是产物，空文本投影不妨碍命中。"""
|
||||
backend = InMemoryCache()
|
||||
mw = _mw(backend)
|
||||
completion = OpenAIChatCompletion(
|
||||
{
|
||||
"role": "assistant",
|
||||
"content": None,
|
||||
"tool_calls": [
|
||||
{
|
||||
"id": "call-1",
|
||||
"type": "function",
|
||||
"function": {"name": "echo", "arguments": "{}"},
|
||||
}
|
||||
],
|
||||
},
|
||||
"tool_calls",
|
||||
"tool-response",
|
||||
None,
|
||||
)
|
||||
request = ChatRequest(messages=_MSGS, response_mode="openai")
|
||||
key = build_cache_key("m", _MSGS, "proj", None, response_mode="openai")
|
||||
await backend.set(key, mw._serialize(_resp(content="", completion=completion)), ttl_s=60)
|
||||
terminal = _Terminal(_resp())
|
||||
hit = await mw(request, terminal)
|
||||
assert hit.cache_hit and terminal.calls == 0
|
||||
assert hit.completion == completion
|
||||
|
||||
|
||||
# —— 1.3.10(#30/#31): 可缓存 ⊂ 可交付,读写共用同一判据(设计 §6)——
|
||||
|
||||
_OK_COMPLETION = OpenAIChatCompletion({"role": "assistant", "content": "ok"}, "stop", "up", None)
|
||||
_THINK_LENGTH = OpenAIChatCompletion(
|
||||
{"role": "assistant", "reasoning_content": "t"}, "length", "up", None
|
||||
)
|
||||
_THINK_STOP = OpenAIChatCompletion(
|
||||
{"role": "assistant", "reasoning_content": "t"}, "stop", "up", None
|
||||
)
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
("mode", "response"),
|
||||
[
|
||||
("text", _resp(stream_end="salvaged")),
|
||||
("text", _resp(finish_reason="length")),
|
||||
("text", _resp(finish_reason="content_filter")),
|
||||
("text", _resp(finish_reason="end_turn")),
|
||||
("openai", _resp(content="", finish_reason="length", completion=_THINK_LENGTH)),
|
||||
("openai", _resp(content="", finish_reason="stop", completion=_THINK_STOP)),
|
||||
],
|
||||
)
|
||||
async def test_uncacheable_results_are_delivered_but_not_written(mode, response):
|
||||
"""截断/空正文/非自然结束: 照常交回,但不写缓存,下次回源。"""
|
||||
backend = InMemoryCache()
|
||||
mw = _mw(backend)
|
||||
terminal = _Terminal(response)
|
||||
request = ChatRequest(messages=_MSGS, response_mode=mode)
|
||||
assert (await mw(request, terminal)) is response
|
||||
assert (await mw(request, terminal)).cache_hit is False
|
||||
assert terminal.calls == 2 and not backend._store
|
||||
|
||||
|
||||
def _stored(mode, **fields):
|
||||
"""直接注入一条缓存原文(模拟旧版本或别的进程写入)。"""
|
||||
backend = InMemoryCache()
|
||||
data = dataclasses.asdict(_resp(**fields))
|
||||
data.pop("structured_data", None)
|
||||
data.pop("call_stats", None)
|
||||
key = build_cache_key("m", _MSGS, "proj", None, response_mode=mode)
|
||||
backend._store[key] = (float("inf"), json.dumps(data))
|
||||
return backend, key
|
||||
|
||||
|
||||
async def _hit(backend, mode):
|
||||
terminal = _Terminal(_resp(content="fresh", completion=_OK_COMPLETION, finish_reason="stop"))
|
||||
response = await _mw(backend)(ChatRequest(messages=_MSGS, response_mode=mode), terminal)
|
||||
return response, terminal.calls
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
("mode", "fields"),
|
||||
[
|
||||
("text", {"stream_end": "salvaged"}),
|
||||
("text", {"stream_end": "bogus"}),
|
||||
("text", {"finish_reason": "length"}),
|
||||
("text", {"finish_reason": 5}),
|
||||
("openai", {"content": "", "completion": _THINK_LENGTH, "finish_reason": "length"}),
|
||||
],
|
||||
)
|
||||
async def test_injected_uncacheable_entries_read_as_miss(mode, fields):
|
||||
"""读路径对存储原值判定(覆盖之前): 不可缓存即 miss 回源。"""
|
||||
backend, _ = _stored(mode, **fields)
|
||||
response, calls = await _hit(backend, mode)
|
||||
assert response.cache_hit is False and calls == 1
|
||||
|
||||
|
||||
async def test_legacy_fidelity_length_entry_falls_back_to_completion_finish():
|
||||
"""1.3.9 保真条目无顶层 finish: 回退 completion.finish_reason 识别为不可缓存。"""
|
||||
completion = OpenAIChatCompletion({"role": "assistant", "content": "a"}, "length", None, None)
|
||||
backend, key = _stored("openai", completion=completion)
|
||||
data = json.loads(backend._store[key][1])
|
||||
for name in ("finish_reason", "stream_end"):
|
||||
data.pop(name)
|
||||
backend._store[key] = (float("inf"), json.dumps(data))
|
||||
response, calls = await _hit(backend, "openai")
|
||||
assert response.cache_hit is False and calls == 1
|
||||
|
||||
|
||||
async def test_legacy_text_entry_without_new_fields_still_hits():
|
||||
"""1.3.9 文本条目无新键: 仍命中;命中 stream_end=None。"""
|
||||
backend, key = _stored("text")
|
||||
data = json.loads(backend._store[key][1])
|
||||
for name in ("finish_reason", "stream_end"):
|
||||
data.pop(name)
|
||||
backend._store[key] = (float("inf"), json.dumps(data))
|
||||
response, calls = await _hit(backend, "text")
|
||||
assert response.cache_hit is True and calls == 0
|
||||
assert response.stream_end is None and response.finish_reason is None
|
||||
|
||||
|
||||
async def test_hit_resets_stream_end_and_keeps_effective_finish():
|
||||
"""命中: stream_end 置 None;finish_reason 取判定所用值(顶层缺省时回退)。"""
|
||||
backend, key = _stored("openai", completion=_OK_COMPLETION, stream_end="eof_after_finish")
|
||||
data = json.loads(backend._store[key][1])
|
||||
data.pop("finish_reason")
|
||||
backend._store[key] = (float("inf"), json.dumps(data))
|
||||
response, calls = await _hit(backend, "openai")
|
||||
assert response.cache_hit is True and calls == 0
|
||||
assert response.stream_end is None and response.finish_reason == "stop"
|
||||
|
||||
|
||||
async def test_new_fields_roundtrip_through_cache():
|
||||
"""两新字段随序列化往返;命中只重置 stream_end。"""
|
||||
backend = InMemoryCache()
|
||||
mw = _mw(backend)
|
||||
terminal = _Terminal(_resp(finish_reason="stop", stream_end="eof_after_finish"))
|
||||
await mw(ChatRequest(messages=_MSGS), terminal)
|
||||
stored = json.loads(next(iter(backend._store.values()))[1])
|
||||
assert stored["finish_reason"] == "stop" and stored["stream_end"] == "eof_after_finish"
|
||||
hit = await mw(ChatRequest(messages=_MSGS), terminal)
|
||||
assert hit.cache_hit is True and hit.finish_reason == "stop" and hit.stream_end is None
|
||||
|
||||
|
||||
async def test_fidelity_think_only_projection_not_cached():
|
||||
"""审查 I1: qwen think 标签剥离后投影为空的保真结果不写缓存。"""
|
||||
completion = OpenAIChatCompletion(
|
||||
{"role": "assistant", "content": "<think>x</think>"}, "stop", "up", None
|
||||
)
|
||||
response = _resp(content="", thinking="x", finish_reason="stop", completion=completion)
|
||||
backend = InMemoryCache()
|
||||
await _mw(backend)(ChatRequest(messages=_MSGS, response_mode="openai"), _Terminal(response))
|
||||
assert not backend._store
|
||||
|
||||
@@ -232,6 +232,7 @@ class _ScriptedGenClockTransport:
|
||||
reasoning_effort,
|
||||
first_token_event,
|
||||
content_event,
|
||||
response_mode,
|
||||
):
|
||||
self.calls.append(call_id)
|
||||
result = self._results.pop(0)
|
||||
@@ -1844,6 +1845,7 @@ class _ClockJumpTransport:
|
||||
reasoning_effort,
|
||||
first_token_event,
|
||||
content_event,
|
||||
response_mode,
|
||||
):
|
||||
self.calls.append(call_id)
|
||||
self._clock.advance(self._jump)
|
||||
|
||||
@@ -0,0 +1,453 @@
|
||||
"""统一完成判定在 transport 两条路径上的落点(#30/#31,设计 §4.2-§4.4、§5.4)。
|
||||
|
||||
假 SSE 按 magpie/glm 实测形态二次构造: 末块 finish_reason + usage 后干净关闭、
|
||||
不发 [DONE];以及只有思考的 length 截断、null/未知字段等方言。
|
||||
"""
|
||||
|
||||
import asyncio
|
||||
import json
|
||||
|
||||
import httpx
|
||||
import pytest
|
||||
from loguru import logger
|
||||
|
||||
from polygateway.errors import AllSourcesExhausted, ResultInvalidError, TransientError
|
||||
from polygateway.transports.openai_compat import OpenAICompatTransport
|
||||
from tests.unit.test_openai_compat import _complete, _source, _sse_stream, _transport_for
|
||||
|
||||
_USAGE = {"prompt_tokens": 11, "completion_tokens": 7}
|
||||
_TOOL = {
|
||||
"index": 0,
|
||||
"id": "call_1",
|
||||
"type": "function",
|
||||
"function": {"name": "lookup", "arguments": '{"q": 1}'},
|
||||
}
|
||||
|
||||
|
||||
def _f(delta=None, finish=None, usage=None, choices=True):
|
||||
"""单 choice 帧;`choices=False` 构造 usage-only 帧。"""
|
||||
body = {"id": "up-1"}
|
||||
if choices:
|
||||
choice = {"index": 0, "delta": delta or {}}
|
||||
if finish is not None:
|
||||
choice["finish_reason"] = finish
|
||||
body["choices"] = [choice]
|
||||
else:
|
||||
body["choices"] = []
|
||||
if usage is not None:
|
||||
body["usage"] = usage
|
||||
return f"data: {json.dumps(body)}\n\n"
|
||||
|
||||
|
||||
def _assistant(**delta):
|
||||
return _f({"role": "assistant", **delta})
|
||||
|
||||
|
||||
async def _run(frames, *, done, mode="text", **source_kw):
|
||||
transport = _transport_for(lambda _: _sse_stream(*frames, done=done))
|
||||
try:
|
||||
return await _complete(transport, _source(**source_kw), response_mode=mode)
|
||||
finally:
|
||||
await transport.aclose()
|
||||
|
||||
|
||||
async def _run_once(body, *, mode="text"):
|
||||
transport = _transport_for(lambda _: httpx.Response(200, json=body))
|
||||
try:
|
||||
return await _complete(transport, _source(), stream=False, response_mode=mode)
|
||||
finally:
|
||||
await transport.aclose()
|
||||
|
||||
|
||||
# —— #31: 缺 [DONE] 但 finish + 其后实测 usage 完整 ——
|
||||
|
||||
|
||||
@pytest.mark.parametrize("mode", ["text", "openai"])
|
||||
@pytest.mark.parametrize("finish", ["stop", "length"])
|
||||
async def test_eof_after_finish_with_usage_succeeds(mode, finish):
|
||||
"""验收 1: 末块 finish + usage 后干净关闭 → 成功、measured、eof_after_finish。"""
|
||||
frames = [_assistant(content="hel"), _f({"content": "lo"}, finish=finish, usage=_USAGE)]
|
||||
result = await _run(frames, done=False, mode=mode)
|
||||
assert result.content == "hello" and result.stream_end == "eof_after_finish"
|
||||
assert result.usage_source == "measured" and result.finish_reason == finish
|
||||
assert (result.prompt_tokens, result.completion_tokens) == (11, 7)
|
||||
if mode == "openai":
|
||||
assert result.completion.finish_reason == finish
|
||||
|
||||
|
||||
async def test_eof_after_finish_usage_only_frame_and_tools():
|
||||
"""验收 2: tool_calls 结束、usage 在其后的 usage-only 帧 → 工具完整交回。"""
|
||||
frames = [
|
||||
_assistant(content=None, tool_calls=[_TOOL]),
|
||||
_f({}, finish="tool_calls"),
|
||||
_f(choices=False, usage=_USAGE),
|
||||
]
|
||||
result = await _run(frames, done=False, mode="openai")
|
||||
tool = result.completion.message["tool_calls"][0]
|
||||
assert tool["function"] == {"name": "lookup", "arguments": '{"q": 1}'}
|
||||
assert result.stream_end == "eof_after_finish" and result.usage_source == "measured"
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
"frames",
|
||||
[
|
||||
[_assistant(content="partial"), _f(choices=False, usage=_USAGE)], # 验收 3: 无 finish
|
||||
[_assistant(content="partial"), _f({}, finish="stop")], # 验收 4: 无 usage
|
||||
[_assistant(content="a", **{}), _f({}, usage=_USAGE), _f({}, finish="stop")], # usage 早
|
||||
[_assistant(content="a"), _f({}, finish="stop", usage={})], # usage 不可用
|
||||
],
|
||||
)
|
||||
async def test_incomplete_eof_still_fails(frames):
|
||||
"""截断不放宽: 保真仍不打捞,文本 retry 档仍抛。"""
|
||||
with pytest.raises(TransientError, match="missing_done"):
|
||||
await _run(frames, done=False, mode="openai", missing_done="salvage")
|
||||
with pytest.raises(TransientError, match="missing_done"):
|
||||
await _run(frames, done=False)
|
||||
|
||||
|
||||
async def test_text_salvage_marks_stream_end():
|
||||
"""文本 salvage 打捞 → stream_end=salvaged,usage 降为 estimated。"""
|
||||
frames = [_assistant(content="partial"), _f(choices=False, usage=_USAGE)]
|
||||
result = await _run(frames, done=False, missing_done="salvage")
|
||||
assert result.stream_end == "salvaged" and result.usage_source == "estimated"
|
||||
|
||||
|
||||
async def test_read_error_mid_stream_fails():
|
||||
"""验收 5: 读取中途 RemoteProtocolError → 失败,不当干净 EOF。"""
|
||||
|
||||
class Broken(httpx.AsyncByteStream):
|
||||
async def __aiter__(self):
|
||||
yield _f({"role": "assistant", "content": "a"}, finish="stop", usage=_USAGE).encode()
|
||||
raise httpx.RemoteProtocolError("peer closed")
|
||||
|
||||
async def aclose(self):
|
||||
return None
|
||||
|
||||
transport = _transport_for(lambda _: httpx.Response(200, stream=Broken()))
|
||||
try:
|
||||
with pytest.raises(TransientError, match="网络错误"):
|
||||
await _complete(transport, _source(), response_mode="openai")
|
||||
finally:
|
||||
await transport.aclose()
|
||||
|
||||
|
||||
@pytest.mark.parametrize("mode", ["text", "openai"])
|
||||
async def test_done_stream_marks_done(mode):
|
||||
"""验收 6: 带 [DONE] 的正常流行为不变,stream_end=done。"""
|
||||
result = await _run([_assistant(content="ok"), _f({}, "stop", _USAGE)], done=True, mode=mode)
|
||||
assert result.stream_end == "done" and result.finish_reason == "stop"
|
||||
|
||||
|
||||
@pytest.mark.parametrize("done", [True, False])
|
||||
@pytest.mark.parametrize("mode", ["text", "openai"])
|
||||
async def test_upstream_error_finish_is_transient(done, mode):
|
||||
"""GLM network_error: 上游自报失败,有正文也不交付。"""
|
||||
frames = [_assistant(content="half"), _f({}, finish="network_error", usage=_USAGE)]
|
||||
with pytest.raises(TransientError, match="upstream_finish_error"):
|
||||
await _run(frames, done=done, mode=mode)
|
||||
|
||||
|
||||
# —— #30 与结局表(设计 §4.3)——
|
||||
|
||||
_THINK = [_assistant(reasoning_content="long thought")]
|
||||
|
||||
|
||||
@pytest.mark.parametrize("done", [True, False])
|
||||
async def test_openai_reasoning_only_length_delivered(done):
|
||||
"""#30 验收: 只有思考 + length → 交回,content 空,思考完整。"""
|
||||
result = await _run([*_THINK, _f({}, "length", _USAGE)], done=done, mode="openai")
|
||||
message = result.completion.message
|
||||
assert message.get("content") in (None, "") and message["reasoning_content"] == "long thought"
|
||||
assert result.finish_reason == "length" and result.thinking == "long thought"
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
("frames", "finish", "openai_ok", "text_error"),
|
||||
[
|
||||
(_THINK, "length", True, (ResultInvalidError, "length_without_content")),
|
||||
([_assistant()], "length", True, (ResultInvalidError, "length_without_content")),
|
||||
(_THINK, "content_filter", True, (ResultInvalidError, "filtered_without_content")),
|
||||
([_assistant()], "sensitive", True, (ResultInvalidError, "filtered_without_content")),
|
||||
(_THINK, "stop", True, (TransientError, "empty_completion")),
|
||||
([_assistant(refusal="no")], "stop", True, (TransientError, "empty_completion")),
|
||||
([_assistant()], "stop", False, (TransientError, "empty_completion")),
|
||||
],
|
||||
)
|
||||
async def test_outcome_rows_stream(frames, finish, openai_ok, text_error):
|
||||
"""行 3/4/6/7/8: 两模式的分叉。"""
|
||||
full = [*frames, _f({}, finish, _USAGE)]
|
||||
if openai_ok:
|
||||
assert (await _run(full, done=True, mode="openai")).finish_reason == finish
|
||||
else:
|
||||
with pytest.raises(TransientError, match="empty_completion"):
|
||||
await _run(full, done=True, mode="openai")
|
||||
error, code = text_error
|
||||
with pytest.raises(error, match=code) as caught:
|
||||
await _run(full, done=True)
|
||||
assert caught.type is error # ResultInvalid 不得被 Transient 子类掩盖
|
||||
|
||||
|
||||
@pytest.mark.parametrize("mode", ["text", "openai"])
|
||||
async def test_reasoning_only_without_finish_is_transient(mode):
|
||||
"""行 9: 只靠 DONE 收尾、无 finish → 无法区分抖动与结局,维持瞬时。"""
|
||||
with pytest.raises(TransientError, match="empty_completion"):
|
||||
await _run([*_THINK, _f(choices=False, usage=_USAGE)], done=True, mode=mode)
|
||||
|
||||
|
||||
async def test_openai_whitespace_content_stop_delivered():
|
||||
"""正文只有空白 + stop: 保真交回(#30 一-2)。"""
|
||||
result = await _run(
|
||||
[_assistant(content=" "), _f({}, "stop", _USAGE)], done=True, mode="openai"
|
||||
)
|
||||
assert result.completion.message["content"] == " "
|
||||
|
||||
|
||||
async def test_truncated_tool_is_result_invalid():
|
||||
"""行 2: length 截断的半截工具(缺 name)→ ResultInvalid tool_truncated。"""
|
||||
broken = {"index": 0, "id": "c", "type": "function", "function": {"arguments": '{"q'}}
|
||||
frames = [_assistant(tool_calls=[broken]), _f({}, "length", _USAGE)]
|
||||
with pytest.raises(ResultInvalidError, match="tool_truncated"):
|
||||
await _run(frames, done=True, mode="openai")
|
||||
|
||||
|
||||
async def test_content_cannot_mask_broken_tool():
|
||||
"""行 2: 正文非空 + 坏工具 + stop → Transient tool_incomplete。"""
|
||||
broken = {"index": 0, "id": "c", "type": "function", "function": {"arguments": "{}"}}
|
||||
frames = [_assistant(content="text", tool_calls=[broken]), _f({}, "stop", _USAGE)]
|
||||
with pytest.raises(TransientError, match="tool_incomplete"):
|
||||
await _run(frames, done=True, mode="openai")
|
||||
|
||||
|
||||
async def test_null_refusal_and_tool_calls_stream():
|
||||
"""#30 验收二: delta 带 refusal:null 与 tool_calls:null → 正常交回。"""
|
||||
frames = [_assistant(content="ok", refusal=None, tool_calls=None), _f({}, "stop", _USAGE)]
|
||||
result = await _run(frames, done=True, mode="openai")
|
||||
assert result.completion.message["content"] == "ok"
|
||||
|
||||
|
||||
# —— 非流式镜像 ——
|
||||
|
||||
|
||||
def _body(message, finish):
|
||||
choice = {"index": 0, "message": {"role": "assistant", **message}}
|
||||
if finish is not None:
|
||||
choice["finish_reason"] = finish
|
||||
return {"id": "up", "choices": [choice], "usage": _USAGE}
|
||||
|
||||
|
||||
async def test_nonstream_null_tool_calls_and_refusal():
|
||||
"""非流式 message 带 tool_calls:null + refusal:null → 成功。"""
|
||||
body = _body({"content": "hi", "tool_calls": None, "refusal": None}, "stop")
|
||||
result = await _run_once(body, mode="openai")
|
||||
assert result.completion.message["tool_calls"] is None and result.stream_end is None
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
("message", "finish", "openai_expect", "text_expect"),
|
||||
[
|
||||
(
|
||||
{"reasoning_content": "t"},
|
||||
"length",
|
||||
None,
|
||||
(ResultInvalidError, "length_without_content"),
|
||||
),
|
||||
({"content": ""}, "content_filter", None, (ResultInvalidError, "filtered_without_content")),
|
||||
({"reasoning_content": "t"}, "stop", None, (TransientError, "empty_completion")),
|
||||
({"reasoning_content": "t"}, None, (TransientError, "empty_completion"), None),
|
||||
({"content": "a"}, "network_error", (TransientError, "upstream_finish_error"), None),
|
||||
({"content": "a"}, "length", None, None),
|
||||
],
|
||||
)
|
||||
async def test_outcome_rows_nonstream(message, finish, openai_expect, text_expect):
|
||||
"""非流式跳过流完整性,直接以 body finish 走结局表。"""
|
||||
body = _body(message, finish)
|
||||
for mode, expect in (("openai", openai_expect), ("text", text_expect or openai_expect)):
|
||||
if expect is None:
|
||||
result = await _run_once(body, mode=mode)
|
||||
assert result.finish_reason == finish and result.stream_end is None
|
||||
else:
|
||||
with pytest.raises(expect[0], match=expect[1]) as caught:
|
||||
await _run_once(body, mode=mode)
|
||||
assert caught.type is expect[0]
|
||||
|
||||
|
||||
async def test_nonstream_truncated_tool_is_result_invalid():
|
||||
"""非流式先判定后构造快照: 缺 name + length → tool_truncated 而非构造期 Transient。"""
|
||||
tool = {"id": "c", "type": "function", "function": {"arguments": "{"}}
|
||||
with pytest.raises(ResultInvalidError, match="tool_truncated"):
|
||||
await _run_once(_body({"tool_calls": [tool]}, "length"), mode="openai")
|
||||
|
||||
|
||||
# —— reasoning 别名(设计 §4.4)——
|
||||
|
||||
|
||||
async def test_reasoning_alias_projects_thinking():
|
||||
"""只有 reasoning 字段: 文本 thinking 取别名;非空 reasoning_content 优先。"""
|
||||
alias = await _run(
|
||||
[_assistant(reasoning="r1"), _f({"content": "a"}, "stop", _USAGE)], done=True
|
||||
)
|
||||
assert alias.thinking == "r1"
|
||||
both = [
|
||||
_assistant(reasoning="r1", reasoning_content="rc"),
|
||||
_f({"content": "a"}, "stop", _USAGE),
|
||||
]
|
||||
assert (await _run(both, done=True)).thinking == "rc"
|
||||
empty_rc = [_assistant(reasoning="r1", reasoning_content=""), _f({"content": "a"}, "stop")]
|
||||
assert (await _run(empty_rc, done=True)).thinking == "r1"
|
||||
nonstream = await _run_once(_body({"content": "a", "reasoning": "nr"}, "stop"))
|
||||
assert nonstream.thinking == "nr"
|
||||
|
||||
|
||||
async def test_reasoning_alias_keeps_ttft_alive():
|
||||
"""只有 reasoning 的思考期刷新活性,不被 TTFT 看门狗误杀。"""
|
||||
|
||||
class Slow(httpx.AsyncByteStream):
|
||||
async def __aiter__(self):
|
||||
yield _assistant().encode()
|
||||
for _ in range(5): # 0.5s 只有 reasoning,远超 ttft,但每帧间隔 < inter_token
|
||||
yield _f({"reasoning": "t"}).encode()
|
||||
await asyncio.sleep(0.1)
|
||||
yield _f({"content": "answer"}, "stop", _USAGE).encode()
|
||||
yield b"data: [DONE]\n\n"
|
||||
|
||||
async def aclose(self):
|
||||
return None
|
||||
|
||||
transport = _transport_for(lambda _: httpx.Response(200, stream=Slow()))
|
||||
try:
|
||||
source = _source(ttft_timeout_s=0.3, inter_token_timeout_s=0.25)
|
||||
result = await _complete(transport, source)
|
||||
assert result.content == "answer" and result.thinking == "ttttt"
|
||||
finally:
|
||||
await transport.aclose()
|
||||
|
||||
|
||||
# —— 有界告警节流(设计 §5.4)——
|
||||
|
||||
|
||||
def _sink():
|
||||
records = []
|
||||
handle = logger.add(lambda m: records.append(m.record["message"]), level="WARNING")
|
||||
return records, handle
|
||||
|
||||
|
||||
async def test_conflict_and_unknown_finish_warn_once():
|
||||
"""同源同路径冲突、同一未知 finish 值各只告警一次,不回显字段值。"""
|
||||
frames = [
|
||||
_assistant(content="a", ext=1),
|
||||
_f({"ext": 2}),
|
||||
_f({}, "end_turn", _USAGE),
|
||||
]
|
||||
transport = _transport_for(lambda _: _sse_stream(*frames))
|
||||
records, handle = _sink()
|
||||
try:
|
||||
for _ in range(2):
|
||||
result = await _complete(transport, _source(), response_mode="openai")
|
||||
assert "ext" not in result.completion.message
|
||||
finally:
|
||||
logger.remove(handle)
|
||||
await transport.aclose()
|
||||
conflict = [r for r in records if "delta.ext" in r]
|
||||
unknown = [r for r in records if "end_turn" in r]
|
||||
assert len(conflict) == 1 and len(unknown) == 1 and "不缓存" in unknown[0]
|
||||
|
||||
|
||||
async def test_warning_set_is_bounded():
|
||||
"""节流集合饱和后只记一次饱和告警,不再增长。"""
|
||||
transport = OpenAICompatTransport()
|
||||
transport._warned_fields.update((f"s{i}", "k") for i in range(1024))
|
||||
records, handle = _sink()
|
||||
try:
|
||||
transport._warn_once("qwen_1", "field:x", "a")
|
||||
transport._warn_once("qwen_1", "field:y", "b")
|
||||
finally:
|
||||
logger.remove(handle)
|
||||
await transport.aclose()
|
||||
assert len(transport._warned_fields) == 1024
|
||||
assert sum("饱和" in r for r in records) == 1
|
||||
|
||||
|
||||
# —— 治理链: 确定性结局不重试、不计熔断 ——
|
||||
|
||||
|
||||
async def test_text_length_without_content_not_retried_nor_breaker_failure():
|
||||
"""文本 length 无正文 → ResultInvalid 直抛,attempts=1,熔断不记失败。"""
|
||||
from tests.unit.test_client import _client
|
||||
|
||||
calls = []
|
||||
|
||||
def handler(_):
|
||||
calls.append(1)
|
||||
return _sse_stream(*_THINK, _f({}, "length", _USAGE))
|
||||
|
||||
client = _client(handler=handler)
|
||||
failures = []
|
||||
original = client._breaker_backend.record_failure
|
||||
|
||||
async def spy(*args, **kwargs):
|
||||
failures.append(args)
|
||||
return await original(*args, **kwargs)
|
||||
|
||||
client._breaker_backend.record_failure = spy
|
||||
try:
|
||||
with pytest.raises(ResultInvalidError, match="length_without_content"):
|
||||
await client.chat([{"role": "user", "content": "hi"}])
|
||||
finally:
|
||||
await client._transport.aclose()
|
||||
assert len(calls) == 1 and failures == []
|
||||
|
||||
|
||||
async def test_openai_reasoning_length_single_attempt_via_client():
|
||||
"""#30 验收经治理链: attempts=1;#31 形态经治理链不再重试到耗尽。"""
|
||||
from tests.unit.test_client import _client
|
||||
|
||||
calls = []
|
||||
|
||||
def handler(_):
|
||||
calls.append(1)
|
||||
return _sse_stream(*_THINK, _f({}, "length", _USAGE), done=False)
|
||||
|
||||
client = _client(handler=handler)
|
||||
try:
|
||||
response = await client.chat([{"role": "user", "content": "hi"}], response_mode="openai")
|
||||
except AllSourcesExhausted: # pragma: no cover - 失败即回归
|
||||
pytest.fail("reasoning-only length 不应重试到耗尽")
|
||||
finally:
|
||||
await client._transport.aclose()
|
||||
assert len(calls) == 1 and response.call_stats.attempts == 1
|
||||
assert response.stream_end == "eof_after_finish" and response.finish_reason == "length"
|
||||
|
||||
|
||||
async def test_eof_after_finish_stop_single_attempt_via_client():
|
||||
"""#31 验收 1 经治理链: stop + usage 无 DONE,attempts=1、不重试到耗尽。"""
|
||||
from tests.unit.test_client import _client
|
||||
|
||||
calls = []
|
||||
|
||||
def handler(_):
|
||||
calls.append(1)
|
||||
return _sse_stream(_assistant(content="ok"), _f({}, "stop", _USAGE), done=False)
|
||||
|
||||
client = _client(handler=handler)
|
||||
try:
|
||||
response = await client.chat([{"role": "user", "content": "hi"}])
|
||||
finally:
|
||||
await client._transport.aclose()
|
||||
assert len(calls) == 1 and response.call_stats.attempts == 1
|
||||
assert response.stream_end == "eof_after_finish" and response.usage_source == "measured"
|
||||
|
||||
|
||||
async def test_text_salvage_with_length_partial_content_delivered():
|
||||
"""文本 salvage + length + 部分正文(finish 后无 usage): 交付、salvaged。"""
|
||||
frames = [_assistant(content="part"), _f({}, finish="length")]
|
||||
result = await _run(frames, done=False, missing_done="salvage")
|
||||
assert result.content == "part" and result.stream_end == "salvaged"
|
||||
assert result.finish_reason == "length"
|
||||
|
||||
|
||||
async def test_null_arguments_tool_is_result_invalid_stream():
|
||||
"""审查 I2: 无参函数 arguments 全程 null → ResultInvalid,不重试。"""
|
||||
tool = {"index": 0, "id": "c", "type": "function", "function": {"name": "f", "arguments": None}}
|
||||
frames = [_assistant(tool_calls=[tool]), _f({}, "tool_calls", _USAGE)]
|
||||
with pytest.raises(ResultInvalidError, match="tool_arguments_null"):
|
||||
await _run(frames, done=True, mode="openai")
|
||||
@@ -0,0 +1,265 @@
|
||||
"""统一完成判定(#30/#31): 内核纯函数真值表。"""
|
||||
|
||||
import pytest
|
||||
|
||||
from polygateway.types import (
|
||||
LLMResponse,
|
||||
OpenAIChatCompletion,
|
||||
TransportResult,
|
||||
_classify_finish,
|
||||
_effective_finish,
|
||||
_is_cacheable,
|
||||
_judge_outcome,
|
||||
_OutputSummary,
|
||||
_stream_is_complete,
|
||||
_summarize_message,
|
||||
_summarize_text,
|
||||
_tool_snapshot_ok,
|
||||
)
|
||||
|
||||
_TOOL = {"id": "t1", "type": "function", "function": {"name": "f", "arguments": "{}"}}
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
("value", "expected"),
|
||||
[
|
||||
("stop", "natural"),
|
||||
("tool_calls", "natural"),
|
||||
("function_call", "natural"),
|
||||
("length", "truncated"),
|
||||
("content_filter", "filtered"),
|
||||
("sensitive", "filtered"),
|
||||
("network_error", "upstream_error"),
|
||||
("error", "upstream_error"),
|
||||
("end_turn", "unknown"),
|
||||
("STOP", "unknown"),
|
||||
(None, "absent"),
|
||||
],
|
||||
)
|
||||
def test_classify_finish(value, expected):
|
||||
assert _classify_finish(value) == expected
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
("done", "finish", "after", "measured", "expected"),
|
||||
[
|
||||
(True, None, False, False, "done"),
|
||||
(True, "stop", True, True, "done"),
|
||||
(False, "stop", True, True, "eof_after_finish"),
|
||||
(False, "length", True, True, "eof_after_finish"),
|
||||
(False, None, True, True, None), # 无 finish 即截断
|
||||
(False, "stop", False, True, None), # usage 早于 finish(累计 usage)
|
||||
(False, "stop", True, False, None), # finish 后 usage 不可用
|
||||
],
|
||||
)
|
||||
def test_stream_is_complete(done, finish, after, measured, expected):
|
||||
got = _stream_is_complete(
|
||||
done=done, finish_reason=finish, usage_after_finish=after, usage_measured=measured
|
||||
)
|
||||
assert got == expected
|
||||
|
||||
|
||||
def test_tool_snapshot_ok():
|
||||
assert _tool_snapshot_ok({"role": "assistant"})
|
||||
assert _tool_snapshot_ok({"tool_calls": None})
|
||||
assert _tool_snapshot_ok({"tool_calls": [None, _TOOL]})
|
||||
assert not _tool_snapshot_ok({"tool_calls": {}})
|
||||
assert not _tool_snapshot_ok({"tool_calls": [{"id": "t1", "type": "function"}]})
|
||||
assert not _tool_snapshot_ok({"tool_calls": [_TOOL, _TOOL]}) # 重复 id
|
||||
|
||||
|
||||
def test_summarize_text():
|
||||
assert _summarize_text("", "") == _OutputSummary(False, False, False, True)
|
||||
assert _summarize_text(" ", "") == _OutputSummary(True, False, False, True)
|
||||
assert _summarize_text("", "think") == _OutputSummary(True, False, False, True)
|
||||
assert _summarize_text("hi", "") == _OutputSummary(True, True, False, True)
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
("message", "projected", "expected"),
|
||||
[
|
||||
({"role": "assistant"}, "", _OutputSummary(False, False, False, True)),
|
||||
({"role": "assistant", "content": None}, "", _OutputSummary(False, False, False, True)),
|
||||
({"role": "assistant", "refusal": "no"}, "", _OutputSummary(True, False, False, True)),
|
||||
(
|
||||
{"role": "assistant", "reasoning_content": "r"},
|
||||
"",
|
||||
_OutputSummary(True, False, False, True),
|
||||
),
|
||||
({"role": "assistant", "content": " "}, " ", _OutputSummary(True, False, False, True)),
|
||||
(
|
||||
{"role": "assistant", "x": {"y": ["", "z"]}},
|
||||
"",
|
||||
_OutputSummary(True, False, False, True),
|
||||
),
|
||||
(
|
||||
{"role": "assistant", "tool_calls": [None]},
|
||||
"",
|
||||
_OutputSummary(False, False, False, True),
|
||||
),
|
||||
(
|
||||
{"role": "assistant", "tool_calls": [_TOOL]},
|
||||
"",
|
||||
_OutputSummary(True, True, True, True),
|
||||
),
|
||||
(
|
||||
{"role": "assistant", "tool_calls": [{"id": "t"}]},
|
||||
"",
|
||||
_OutputSummary(True, False, True, False),
|
||||
),
|
||||
({"role": "assistant", "content": "a"}, "a", _OutputSummary(True, True, False, True)),
|
||||
],
|
||||
)
|
||||
def test_summarize_message(message, projected, expected):
|
||||
assert _summarize_message(message, projected) == expected
|
||||
|
||||
|
||||
_NONE = _OutputSummary(False, False, False, True)
|
||||
_THINK = _OutputSummary(True, False, False, True)
|
||||
_BODY = _OutputSummary(True, True, False, True)
|
||||
_BAD_TOOL = _OutputSummary(True, True, True, False)
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
("mode", "summary", "finish", "expected"),
|
||||
[
|
||||
# 行 1: upstream_error 优先于一切
|
||||
("openai", _BODY, "upstream_error", ("transient", "upstream_finish_error")),
|
||||
("text", _BODY, "upstream_error", ("transient", "upstream_finish_error")),
|
||||
# 行 2: 坏工具(仅保真),正文不得掩盖
|
||||
("openai", _BAD_TOOL, "truncated", ("result_invalid", "tool_truncated")),
|
||||
("openai", _BAD_TOOL, "natural", ("transient", "tool_incomplete")),
|
||||
("text", _BAD_TOOL, "natural", None),
|
||||
# 行 3: 无产物 + truncated/filtered
|
||||
("openai", _NONE, "truncated", None),
|
||||
("openai", _NONE, "filtered", None),
|
||||
("text", _NONE, "truncated", ("result_invalid", "length_without_content")),
|
||||
("text", _NONE, "filtered", ("result_invalid", "filtered_without_content")),
|
||||
# 行 4: 零增量抖动(2026-07-20 裁决)
|
||||
("openai", _NONE, "natural", ("transient", "empty_completion")),
|
||||
("openai", _NONE, "absent", ("transient", "empty_completion")),
|
||||
("openai", _NONE, "unknown", ("transient", "empty_completion")),
|
||||
("text", _NONE, "absent", ("transient", "empty_completion")),
|
||||
# 行 5: 有正文
|
||||
("openai", _BODY, "truncated", None),
|
||||
("text", _BODY, "filtered", None),
|
||||
("text", _BODY, "absent", None),
|
||||
# 行 6-9: 有产物无正文
|
||||
("openai", _THINK, "truncated", None),
|
||||
("text", _THINK, "truncated", ("result_invalid", "length_without_content")),
|
||||
("openai", _THINK, "filtered", None),
|
||||
("text", _THINK, "filtered", ("result_invalid", "filtered_without_content")),
|
||||
("openai", _THINK, "natural", None),
|
||||
("openai", _THINK, "unknown", None),
|
||||
("text", _THINK, "natural", ("transient", "empty_completion")),
|
||||
("openai", _THINK, "absent", ("transient", "empty_completion")),
|
||||
("text", _THINK, "absent", ("transient", "empty_completion")),
|
||||
],
|
||||
)
|
||||
def test_judge_outcome_rows(mode, summary, finish, expected):
|
||||
verdict = _judge_outcome(mode=mode, summary=summary, finish=finish)
|
||||
if expected is None:
|
||||
assert verdict.deliver and verdict.error_kind is None and verdict.code is None
|
||||
else:
|
||||
assert not verdict.deliver
|
||||
assert (verdict.error_kind, verdict.code) == expected
|
||||
|
||||
|
||||
def _completion(content="a", finish="stop", tools=None):
|
||||
message = {"role": "assistant", "content": content}
|
||||
if tools is not None:
|
||||
message["tool_calls"] = tools
|
||||
return OpenAIChatCompletion(message, finish, None, None)
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
("kwargs", "expected"),
|
||||
[
|
||||
({"mode": "text", "content": "a", "finish_reason": "stop", "stream_end": "done"}, True),
|
||||
({"mode": "text", "content": "a", "finish_reason": None, "stream_end": None}, True),
|
||||
(
|
||||
{
|
||||
"mode": "text",
|
||||
"content": "a",
|
||||
"finish_reason": "stop",
|
||||
"stream_end": "eof_after_finish",
|
||||
},
|
||||
True,
|
||||
),
|
||||
({"mode": "text", "content": "a", "finish_reason": None, "stream_end": "salvaged"}, False),
|
||||
({"mode": "text", "content": " ", "finish_reason": "stop", "stream_end": "done"}, False),
|
||||
({"mode": "text", "content": "a", "finish_reason": "length", "stream_end": None}, False),
|
||||
({"mode": "text", "content": "a", "finish_reason": "sensitive", "stream_end": None}, False),
|
||||
({"mode": "text", "content": "a", "finish_reason": "end_turn", "stream_end": None}, False),
|
||||
({"mode": "text", "content": "a", "finish_reason": "stop", "stream_end": "bogus"}, False),
|
||||
],
|
||||
)
|
||||
def test_is_cacheable_text(kwargs, expected):
|
||||
assert _is_cacheable(completion=None, **kwargs) is expected
|
||||
|
||||
|
||||
def test_is_cacheable_openai():
|
||||
ok = _completion()
|
||||
assert _is_cacheable(
|
||||
mode="openai", content="a", finish_reason="stop", stream_end="done", completion=ok
|
||||
)
|
||||
assert not _is_cacheable(
|
||||
mode="openai", content="a", finish_reason="stop", stream_end="done", completion=None
|
||||
)
|
||||
# 原文为空且无工具: 不信任旧投影
|
||||
assert not _is_cacheable(
|
||||
mode="openai",
|
||||
content="a",
|
||||
finish_reason="stop",
|
||||
stream_end="done",
|
||||
completion=_completion(content=""),
|
||||
)
|
||||
tool_only = _completion(content=None, finish="tool_calls", tools=[_TOOL])
|
||||
assert _is_cacheable(
|
||||
mode="openai", content="", finish_reason="tool_calls", stream_end=None, completion=tool_only
|
||||
)
|
||||
|
||||
|
||||
def test_effective_finish():
|
||||
assert _effective_finish("stop", _completion(finish="length")) == "stop"
|
||||
assert _effective_finish(None, _completion(finish="length")) == "length"
|
||||
assert _effective_finish(None, None) is None
|
||||
|
||||
|
||||
def test_completion_accepts_null_tool_calls():
|
||||
snap = OpenAIChatCompletion({"role": "assistant", "tool_calls": None}, "stop", None, None)
|
||||
assert "tool_calls" in snap.message and snap.message["tool_calls"] is None
|
||||
with pytest.raises(ValueError):
|
||||
OpenAIChatCompletion({"role": "assistant", "tool_calls": {}}, "stop", None, None)
|
||||
|
||||
|
||||
def test_response_fields_default_none():
|
||||
result = TransportResult("a", "", 0, 0, "unavailable", None, None, {})
|
||||
assert result.finish_reason is None and result.stream_end is None
|
||||
response = LLMResponse("a", "", "m", "p", 0, 0, 0, None, None, False, "c")
|
||||
assert response.finish_reason is None and response.stream_end is None
|
||||
|
||||
|
||||
def test_stream_end_exported():
|
||||
import polygateway
|
||||
|
||||
assert "StreamEnd" in polygateway.__all__
|
||||
|
||||
|
||||
def test_openai_cacheable_requires_projected_body():
|
||||
"""审查 I1: think 标签剥离后投影为空,即使原文非空也不可缓存。"""
|
||||
think_only = _completion(content="<think>x</think>")
|
||||
assert not _is_cacheable(
|
||||
mode="openai", content="", finish_reason="stop", stream_end="done", completion=think_only
|
||||
)
|
||||
|
||||
|
||||
def test_null_arguments_only_tool_is_result_invalid():
|
||||
"""审查 I2: 无参函数 arguments 全程 null(其余齐全)→ 确定性方言,ResultInvalid。"""
|
||||
tool = {"id": "t1", "type": "function", "function": {"name": "f", "arguments": None}}
|
||||
summary = _summarize_message({"role": "assistant", "tool_calls": [tool]}, "")
|
||||
assert summary.null_arguments and not summary.tools_ok
|
||||
verdict = _judge_outcome(mode="openai", summary=summary, finish="natural")
|
||||
assert (verdict.error_kind, verdict.code) == ("result_invalid", "tool_arguments_null")
|
||||
broken = {"id": "t1", "type": "function", "function": {"arguments": None}}
|
||||
assert not _summarize_message({"role": "assistant", "tool_calls": [broken]}, "").null_arguments
|
||||
@@ -1397,9 +1397,7 @@ class TestStallConfig:
|
||||
def test_stall_after_s_single_source_warns(self):
|
||||
"""单源 scope 设 stall 阈值: 装配期 warning 放行(1.3.7 §5 同款)。"""
|
||||
with _captured_warnings() as warnings:
|
||||
s = GatewaySettings.from_env(
|
||||
"LLM", env=_env(**{"LLM__HEDGE__STALL_AFTER_S": "8"})
|
||||
)
|
||||
s = GatewaySettings.from_env("LLM", env=_env(**{"LLM__HEDGE__STALL_AFTER_S": "8"}))
|
||||
assert s.hedge_stall_after_s == 8.0
|
||||
assert any("单源" in m for m in warnings)
|
||||
|
||||
@@ -1422,9 +1420,7 @@ class TestStallConfig:
|
||||
"EMBED__BATCH_SIZE": "64",
|
||||
}
|
||||
with _captured_warnings() as warnings:
|
||||
EmbeddingSettings.from_env(
|
||||
"EMBED", env={**embed_env, "EMBED__HEDGE__AFTER_S": "8"}
|
||||
)
|
||||
EmbeddingSettings.from_env("EMBED", env={**embed_env, "EMBED__HEDGE__AFTER_S": "8"})
|
||||
assert any("仅对 chat scope 生效" in m for m in warnings)
|
||||
with _captured_warnings() as warnings:
|
||||
EmbeddingSettings.from_env(
|
||||
|
||||
@@ -65,6 +65,7 @@ class HedgeTransport:
|
||||
reasoning_effort,
|
||||
first_token_event,
|
||||
content_event,
|
||||
response_mode,
|
||||
):
|
||||
self.calls.append(source.name)
|
||||
self.ft_events.append(first_token_event)
|
||||
|
||||
@@ -279,6 +279,7 @@ async def _complete(observed, *, call_id="a", stream=False):
|
||||
reasoning_effort=None,
|
||||
first_token_event=None,
|
||||
content_event=None,
|
||||
response_mode="text",
|
||||
)
|
||||
|
||||
|
||||
@@ -1270,6 +1271,7 @@ async def test_structured_first_attempt_requires_exact_initial_messages():
|
||||
reasoning_effort=None,
|
||||
first_token_event=None,
|
||||
content_event=None,
|
||||
response_mode="text",
|
||||
)
|
||||
event = capture.attempts(session_id="first", parent_call_id="parent")[0].http[0]
|
||||
assert not request_is_valid(event)
|
||||
|
||||
@@ -90,6 +90,7 @@ async def _complete(
|
||||
reasoning_effort=None,
|
||||
first_token_event=None,
|
||||
content_event=None,
|
||||
response_mode="text",
|
||||
):
|
||||
return await transport.complete(
|
||||
messages=[{"role": "user", "content": "hi"}],
|
||||
@@ -100,9 +101,19 @@ async def _complete(
|
||||
reasoning_effort=reasoning_effort,
|
||||
first_token_event=first_token_event,
|
||||
content_event=content_event,
|
||||
response_mode=response_mode,
|
||||
)
|
||||
|
||||
|
||||
async def test_complete_helper_forwards_response_mode():
|
||||
"""测试封装不得将显式保真模式静默退化成文本模式。"""
|
||||
from unittest.mock import AsyncMock
|
||||
|
||||
transport = AsyncMock()
|
||||
await _complete(transport, _source(), response_mode="openai")
|
||||
assert transport.complete.call_args.kwargs["response_mode"] == "openai"
|
||||
|
||||
|
||||
# 单价刻意取"输出贵于输入"的真实形态: est_tokens 兜底把整估值塞进 completion
|
||||
# 时,虚高才显形(设计 §1 的 26 倍算例即此单价)。
|
||||
_PRICING = PricingTable({"qwen-max": ModelPrice(input_per_1m=1.0, output_per_1m=8.0)})
|
||||
@@ -161,6 +172,8 @@ class TestSsePureFunctions:
|
||||
assert _sse_data_payload("data: [DONE]") == "[DONE]"
|
||||
|
||||
async def test_iter_deltas_yields_and_flags_done(self):
|
||||
from polygateway.transports._openai_completion import ChatCompletionAccumulator, ChatDelta
|
||||
|
||||
async def lines():
|
||||
for raw in [
|
||||
_chunk(content="he"),
|
||||
@@ -173,16 +186,28 @@ class TestSsePureFunctions:
|
||||
yield line
|
||||
|
||||
sink = {}
|
||||
out = [d async for d in _iter_sse_deltas(lines(), sink)]
|
||||
assert out == [(True, "he"), (False, "think")]
|
||||
out = [
|
||||
d
|
||||
async for d in _iter_sse_deltas(
|
||||
lines(), sink, ChatCompletionAccumulator(response_mode="text")
|
||||
)
|
||||
]
|
||||
assert out == [ChatDelta("he", "", True), ChatDelta("", "think", True)]
|
||||
assert sink["done"] is True and sink["usage"] == _USAGE
|
||||
|
||||
async def test_malformed_frame_raises_transient(self):
|
||||
from polygateway.transports._openai_completion import ChatCompletionAccumulator
|
||||
|
||||
async def lines():
|
||||
yield "data: {not-json"
|
||||
|
||||
with pytest.raises(TransientError, match="malformed"):
|
||||
_ = [d async for d in _iter_sse_deltas(lines(), {})]
|
||||
_ = [
|
||||
d
|
||||
async for d in _iter_sse_deltas(
|
||||
lines(), {}, ChatCompletionAccumulator(response_mode="text")
|
||||
)
|
||||
]
|
||||
|
||||
|
||||
class TestStreamHappyPath:
|
||||
|
||||
@@ -0,0 +1,468 @@
|
||||
"""协议聚合器的分片、防御与快照契约。"""
|
||||
|
||||
import copy
|
||||
import json
|
||||
|
||||
import pytest
|
||||
|
||||
from polygateway.errors import TransientError
|
||||
from polygateway.transports._openai_completion import (
|
||||
ChatCompletionAccumulator,
|
||||
parse_chat_completion,
|
||||
)
|
||||
|
||||
|
||||
def chunk(delta, **extra):
|
||||
"""构造单 choice 协议帧。"""
|
||||
return (
|
||||
"data: "
|
||||
+ json.dumps({"id": "upstream-1", "choices": [{"index": 0, "delta": delta, **extra}]})
|
||||
+ "\n\n"
|
||||
)
|
||||
|
||||
|
||||
def tool_frames():
|
||||
"""两个交错分片工具，保留空白及 Unicode。"""
|
||||
return [
|
||||
chunk({"role": "assistant", "content": None}),
|
||||
chunk(
|
||||
{
|
||||
"tool_calls": [
|
||||
{
|
||||
"index": 1,
|
||||
"id": "b",
|
||||
"type": "function",
|
||||
"function": {"name": "echo", "arguments": '{"v":'},
|
||||
},
|
||||
{
|
||||
"index": 0,
|
||||
"id": "a",
|
||||
"type": "function",
|
||||
"function": {"name": "echo", "arguments": "{"},
|
||||
},
|
||||
]
|
||||
}
|
||||
),
|
||||
chunk(
|
||||
{
|
||||
"tool_calls": [
|
||||
{"index": 0, "function": {"arguments": '"v": "中" }'}},
|
||||
{"index": 1, "function": {"arguments": "2}"}},
|
||||
]
|
||||
},
|
||||
finish_reason="tool_calls",
|
||||
),
|
||||
]
|
||||
|
||||
|
||||
def accumulate():
|
||||
"""复用双工具网关帧样本。"""
|
||||
state = ChatCompletionAccumulator(response_mode="openai")
|
||||
for frame in tool_frames():
|
||||
state.add_chunk(json.loads(frame.removeprefix("data: ")))
|
||||
return state
|
||||
|
||||
|
||||
@pytest.mark.parametrize("role", [None, "user", "tool"])
|
||||
def test_role_is_required_everywhere(role):
|
||||
"""缺角色不能被协议成功掩盖。"""
|
||||
state = accumulate()
|
||||
state.message.pop("role")
|
||||
if role:
|
||||
state.message["role"] = role
|
||||
with pytest.raises(TransientError, match="role"):
|
||||
state.finish()
|
||||
with pytest.raises(TransientError, match="role"):
|
||||
parse_chat_completion({"choices": [{"message": state.message}]})
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
"change",
|
||||
[
|
||||
lambda t: t.pop("id"),
|
||||
lambda t: t.update(type="custom"),
|
||||
lambda t: t["function"].pop("name"),
|
||||
lambda t: t["function"].pop("arguments"),
|
||||
lambda t: t["function"].update(arguments=12),
|
||||
],
|
||||
)
|
||||
def test_incomplete_tool_is_not_success(change):
|
||||
"""工具必需字段不能靠正文兜底。"""
|
||||
state = accumulate()
|
||||
state.message["content"] = "text"
|
||||
change(state.tools[0])
|
||||
with pytest.raises(TransientError):
|
||||
state.finish()
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
"delta",
|
||||
[
|
||||
[],
|
||||
{"tool_calls": {}},
|
||||
{"content": []},
|
||||
{"role": "user"},
|
||||
{"tool_calls": [{"index": True}]},
|
||||
{"tool_calls": [{"index": -1}]},
|
||||
{"tool_calls": [{"index": None}]},
|
||||
{"tool_calls": [{"index": 0, "function": {"arguments": 12}}]},
|
||||
],
|
||||
)
|
||||
def test_invalid_delta_is_domain_error(delta):
|
||||
"""畸形输入不泄漏裸类型错误。"""
|
||||
state = ChatCompletionAccumulator(response_mode="openai")
|
||||
with pytest.raises(TransientError):
|
||||
state.add_chunk({"choices": [{"index": 0, "delta": delta}]})
|
||||
|
||||
|
||||
def test_identity_repeat_does_not_refresh_progress():
|
||||
"""身份只初次生效算进展；同值重复不能续命。"""
|
||||
state = accumulate()
|
||||
repeated = {
|
||||
"choices": [
|
||||
{"index": 0, "delta": {"tool_calls": [{"index": 0, "id": "a", "type": "function"}]}}
|
||||
]
|
||||
}
|
||||
assert not state.add_chunk(repeated).progress
|
||||
repeated["choices"][0]["delta"]["tool_calls"][0]["id"] = "other"
|
||||
with pytest.raises(TransientError, match="冲突"):
|
||||
state.add_chunk(repeated)
|
||||
|
||||
|
||||
@pytest.mark.parametrize("delta", [{"role": "assistant"}, {}, {"content": ""}])
|
||||
def test_metadata_not_progress(delta):
|
||||
"""空帧和角色不算 token。"""
|
||||
state = ChatCompletionAccumulator(response_mode="openai")
|
||||
assert not state.add_chunk({"choices": [{"index": 0, "delta": delta}]}).progress
|
||||
|
||||
|
||||
def test_nonstream_snapshot_and_length_preserved():
|
||||
"""非流式扩展字段与参数原文独立保存，不修复 length 产物。"""
|
||||
message = accumulate().finish().message
|
||||
message["extension"] = {"nested": [1]}
|
||||
message["tool_calls"][0]["function"]["arguments"] = '{"unfinished":'
|
||||
original = copy.deepcopy(message)
|
||||
result = parse_chat_completion(
|
||||
{
|
||||
"id": "id",
|
||||
"choices": [{"message": message, "finish_reason": "length"}],
|
||||
"usage": {"extra": 3},
|
||||
}
|
||||
)
|
||||
message["extension"]["nested"].append(2)
|
||||
assert result.message == original
|
||||
assert result.finish_reason == "length" and result.usage == {"extra": 3}
|
||||
|
||||
|
||||
@pytest.mark.parametrize("choices", [[], [{"index": 1, "message": {}}], [{}, {}]])
|
||||
def test_nonstream_single_choice(choices):
|
||||
"""不会静默取第一个 choice。"""
|
||||
with pytest.raises(TransientError):
|
||||
parse_chat_completion({"choices": choices})
|
||||
|
||||
|
||||
def test_explicit_empty_tools_remains_present():
|
||||
"""显式空工具列表与缺省不同，不删除已接收字段。"""
|
||||
state = ChatCompletionAccumulator(response_mode="openai")
|
||||
state.add_chunk(
|
||||
{
|
||||
"choices": [
|
||||
{"index": 0, "delta": {"role": "assistant", "content": "ok", "tool_calls": []}}
|
||||
]
|
||||
}
|
||||
)
|
||||
assert state.finish().message["tool_calls"] == []
|
||||
|
||||
|
||||
def test_fragmented_name_and_arguments_with_usage():
|
||||
"""名称/参数分片逐字拼接，usage 扩展原样快照。"""
|
||||
state = ChatCompletionAccumulator(response_mode="openai")
|
||||
state.add_chunk(
|
||||
{
|
||||
"id": "response",
|
||||
"choices": [
|
||||
{
|
||||
"index": 0,
|
||||
"delta": {
|
||||
"role": "assistant",
|
||||
"tool_calls": [
|
||||
{
|
||||
"index": 3,
|
||||
"id": "call",
|
||||
"type": "function",
|
||||
"function": {"name": "ec", "arguments": " "},
|
||||
}
|
||||
],
|
||||
},
|
||||
}
|
||||
],
|
||||
}
|
||||
)
|
||||
progress = state.add_chunk(
|
||||
{
|
||||
"choices": [
|
||||
{
|
||||
"index": 0,
|
||||
"delta": {
|
||||
"content": "text",
|
||||
"reasoning_content": "reason",
|
||||
"tool_calls": [
|
||||
{"index": 3, "function": {"name": "ho", "arguments": "{} "}}
|
||||
],
|
||||
},
|
||||
"finish_reason": "length",
|
||||
}
|
||||
]
|
||||
}
|
||||
)
|
||||
assert (
|
||||
progress.content == "text" and progress.reasoning_content == "reason" and progress.progress
|
||||
)
|
||||
usage = {"prompt_tokens": 7, "completion_tokens": 2, "extra": {"nested": 9}}
|
||||
assert not state.add_chunk({"choices": [], "usage": usage}).progress
|
||||
result = state.finish()
|
||||
usage["extra"]["nested"] = 10
|
||||
assert result.message["tool_calls"][0]["function"] == {"name": "echo", "arguments": " {} "}
|
||||
assert result.usage["extra"]["nested"] == 9
|
||||
assert result.finish_reason == "length"
|
||||
|
||||
|
||||
# —— 1.3.10(#30): null 优先、未知字段无损合并、finish/usage 位置 ——
|
||||
|
||||
|
||||
def _feed(state, *chunks):
|
||||
"""依次喂入已解码帧,返回每帧的 ChatDelta。"""
|
||||
return [state.add_chunk(c) for c in chunks]
|
||||
|
||||
|
||||
def _frame(delta, finish=None, **top):
|
||||
"""单 choice 已解码帧。"""
|
||||
choice = {"index": 0, "delta": delta}
|
||||
if finish is not None:
|
||||
choice["finish_reason"] = finish
|
||||
return {"choices": [choice], **top}
|
||||
|
||||
|
||||
def test_null_known_and_unknown_fields_are_absent():
|
||||
"""refusal/tool_calls/role/arguments 为 null 不判失败,键按缺省保留。"""
|
||||
state = ChatCompletionAccumulator(response_mode="openai")
|
||||
_feed(
|
||||
state,
|
||||
_frame({"role": None, "refusal": None, "tool_calls": None, "content": None}),
|
||||
_frame({"role": "assistant", "content": "hi"}, finish="stop"),
|
||||
)
|
||||
message = state.finish().message
|
||||
assert message["refusal"] is None and message["content"] == "hi"
|
||||
assert message["role"] == "assistant"
|
||||
|
||||
|
||||
def test_role_only_null_fails_at_finish():
|
||||
"""全程只有 role:null 即缺 role,照旧失败。"""
|
||||
state = ChatCompletionAccumulator(response_mode="openai")
|
||||
_feed(state, _frame({"role": None, "content": "x"}, finish="stop"))
|
||||
with pytest.raises(TransientError, match="role"):
|
||||
state.finish()
|
||||
|
||||
|
||||
def test_null_arguments_and_null_tool_elements():
|
||||
"""arguments:null 视缺省;tool_calls 中 null 元素跳过。"""
|
||||
state = ChatCompletionAccumulator(response_mode="openai")
|
||||
tool = {"index": 0, "id": "a", "type": "function", "function": {"name": "f"}}
|
||||
_feed(
|
||||
state,
|
||||
_frame({"role": "assistant", "tool_calls": [None, tool]}),
|
||||
_frame({"tool_calls": [{"index": 0, "function": {"arguments": None}}]}),
|
||||
_frame({"tool_calls": [{"index": 0, "function": {"arguments": "{}"}}]}, "tool_calls"),
|
||||
)
|
||||
assert state.finish().message["tool_calls"][0]["function"] == {"name": "f", "arguments": "{}"}
|
||||
|
||||
|
||||
def test_null_choices_and_delta_are_absent():
|
||||
"""chunk 层 choices:null 与 choice 层 delta:null 视缺省。"""
|
||||
state = ChatCompletionAccumulator(response_mode="openai")
|
||||
assert not state.add_chunk({"choices": None}).progress
|
||||
assert not state.add_chunk({"choices": [{"index": 0, "delta": None}]}).progress
|
||||
|
||||
|
||||
def test_reasoning_alias_is_progress_and_preserved():
|
||||
"""只有 reasoning 字段: 计活性、交别名片段、保真原键保留。"""
|
||||
for mode in ("openai", "text"):
|
||||
state = ChatCompletionAccumulator(response_mode=mode)
|
||||
delta = state.add_chunk(_frame({"role": "assistant", "reasoning": "think"}))
|
||||
assert delta.progress and delta.reasoning == "think" and delta.reasoning_content == ""
|
||||
state.add_chunk(_frame({"reasoning": " more"}))
|
||||
openai = ChatCompletionAccumulator(response_mode="openai")
|
||||
_feed(openai, _frame({"role": "assistant", "reasoning": "a"}), _frame({"reasoning": "b"}))
|
||||
assert openai.raw_message()["reasoning"] == "ab"
|
||||
|
||||
|
||||
def _detail(text, **extra):
|
||||
return {"type": "reasoning.text", "index": 0, "format": "x-v1", "text": text, **extra}
|
||||
|
||||
|
||||
def test_reasoning_details_merge_by_index_without_label_concat():
|
||||
"""OpenRouter reasoning_details 分片: index 合并,format/id/type 不拼接。"""
|
||||
state = ChatCompletionAccumulator(response_mode="openai")
|
||||
_feed(
|
||||
state,
|
||||
_frame({"role": "assistant", "reasoning_details": [_detail("he", id="r1")]}),
|
||||
_frame({"reasoning_details": [_detail("llo", id="r1")]}),
|
||||
_frame({"content": "ok"}, finish="stop"),
|
||||
)
|
||||
details = state.finish().message["reasoning_details"]
|
||||
assert details == [
|
||||
{"type": "reasoning.text", "index": 0, "format": "x-v1", "text": "hello", "id": "r1"}
|
||||
]
|
||||
assert not state.conflicts
|
||||
|
||||
|
||||
def test_tool_level_nested_extension_preserved():
|
||||
"""工具层未知嵌套对象(如 thought signature)原样保留以便回传。"""
|
||||
state = ChatCompletionAccumulator(response_mode="openai")
|
||||
extra = {"google": {"thought_signature": "sig"}}
|
||||
tool = {"index": 0, "id": "a", "type": "function", "extra_content": extra}
|
||||
_feed(
|
||||
state,
|
||||
_frame({"role": "assistant", "tool_calls": [{**tool, "function": {"name": "f"}}]}),
|
||||
_frame({"tool_calls": [{"index": 0, "function": {"arguments": "{}", "strict": True}}]}),
|
||||
)
|
||||
snapshot = state.finish().message["tool_calls"][0]
|
||||
assert snapshot["extra_content"] == extra and snapshot["function"]["strict"] is True
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
("first", "second"),
|
||||
[(1, 2), (True, False), ("s", {"o": 1}), ([{"index": 0, "t": "a"}], ["plain"])],
|
||||
)
|
||||
def test_conflict_drops_key_and_bans_path(first, second):
|
||||
"""数值/布尔/形态冲突: 删键、登记路径、后续同路径丢弃、调用成功。"""
|
||||
state = ChatCompletionAccumulator(response_mode="openai")
|
||||
_feed(
|
||||
state,
|
||||
_frame({"role": "assistant", "content": "a", "ext": first}),
|
||||
_frame({"ext": second}),
|
||||
_frame({"ext": first}, finish="stop"),
|
||||
)
|
||||
assert "ext" not in state.finish().message
|
||||
assert state.conflicts == frozenset({"delta.ext"})
|
||||
|
||||
|
||||
def test_plain_arrays_append_and_same_scalar_idempotent():
|
||||
"""普通数组追加;同值标量幂等;追加数组中的字符串算活性。"""
|
||||
state = ChatCompletionAccumulator(response_mode="openai")
|
||||
deltas = _feed(
|
||||
state,
|
||||
_frame({"role": "assistant", "notes": ["a"], "n": 1}),
|
||||
_frame({"notes": ["b", None], "n": 1}),
|
||||
)
|
||||
message = state.raw_message()
|
||||
assert message["notes"] == ["a", "b"] and message["n"] == 1
|
||||
assert all(d.progress for d in deltas[1:])
|
||||
|
||||
|
||||
def test_one_progress_per_frame_with_many_fragments():
|
||||
"""同帧多个字段只产生一次进展事件(ChatDelta 单值)。"""
|
||||
state = ChatCompletionAccumulator(response_mode="text")
|
||||
delta = state.add_chunk(_frame({"content": "a", "reasoning_content": "b", "x": "c"}))
|
||||
assert delta.progress is True
|
||||
|
||||
|
||||
def test_label_only_unknown_is_not_progress():
|
||||
"""未知层仅标签键(type/format/id/index)不刷新活性。"""
|
||||
state = ChatCompletionAccumulator(response_mode="openai")
|
||||
assert not state.add_chunk(_frame({"meta": {"type": "x", "format": "y"}})).progress
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
("frames", "after"),
|
||||
[
|
||||
([_frame({"content": "a"}, usage={"x": 1}), _frame({}, finish="stop")], False),
|
||||
([_frame({"content": "a"}, finish="stop", usage={"x": 1})], True),
|
||||
([_frame({"content": "a"}, finish="stop"), {"choices": [], "usage": {"x": 1}}], True),
|
||||
([_frame({"content": "a"}, finish="stop")], False),
|
||||
],
|
||||
)
|
||||
def test_usage_after_finish_tracking(frames, after):
|
||||
"""usage 必须在 finish 同帧或之后到达才算流走到自然末尾。"""
|
||||
for mode in ("openai", "text"):
|
||||
state = ChatCompletionAccumulator(response_mode=mode)
|
||||
_feed(state, *frames)
|
||||
assert state.finish_seen and state.finish_reason == "stop"
|
||||
assert state.usage_after_finish is after
|
||||
|
||||
|
||||
def test_text_mode_ignores_other_choice_index():
|
||||
"""文本模式只取 index 缺省或为 0 的 choice,不混入 index=1。"""
|
||||
state = ChatCompletionAccumulator(response_mode="text")
|
||||
delta = state.add_chunk(
|
||||
{
|
||||
"choices": [
|
||||
{"index": 1, "delta": {"content": "B"}, "finish_reason": "length"},
|
||||
{"index": 0, "delta": {"content": "A"}},
|
||||
]
|
||||
}
|
||||
)
|
||||
assert delta.content == "A" and state.finish_reason is None
|
||||
|
||||
|
||||
def test_text_mode_finish_non_string_ignored():
|
||||
"""文本模式 finish 非字符串记 None,不判失败。"""
|
||||
state = ChatCompletionAccumulator(response_mode="text")
|
||||
state.add_chunk(_frame({"content": "a"}, finish=5))
|
||||
assert state.finish_reason is None and not state.finish_seen
|
||||
|
||||
|
||||
def test_nonstream_null_tool_elements_stripped():
|
||||
"""非流式 tool_calls 中 null 元素剔除(回传 [null] 会被上游拒),null 列表原样保留。"""
|
||||
tool = {"id": "a", "type": "function", "function": {"name": "f", "arguments": "{}"}}
|
||||
body = {
|
||||
"choices": [{"message": {"role": "assistant", "tool_calls": [None, tool], "refusal": None}}]
|
||||
}
|
||||
assert parse_chat_completion(body).message["tool_calls"] == [tool]
|
||||
body["choices"][0]["message"]["tool_calls"] = None
|
||||
assert parse_chat_completion(body).message["tool_calls"] is None
|
||||
|
||||
|
||||
@pytest.mark.parametrize(("index", "taken"), [(None, True), (0, True), (False, False), (1, False)])
|
||||
def test_text_mode_choice_index_null_is_zero(index, taken):
|
||||
"""审查 I3: 文本模式 index:null 视缺省(=0);bool 不冒充 0。"""
|
||||
state = ChatCompletionAccumulator(response_mode="text")
|
||||
delta = state.add_chunk(
|
||||
{"choices": [{"index": index, "delta": {"content": "hi"}, "finish_reason": "stop"}]}
|
||||
)
|
||||
assert (delta.content == "hi") is taken and (state.finish_reason == "stop") is taken
|
||||
|
||||
|
||||
def test_null_only_tool_elements_do_not_create_empty_list():
|
||||
"""审查 Minor1: tool_calls null 后 [null] 不得产出会被上游拒收的空数组。"""
|
||||
state = ChatCompletionAccumulator(response_mode="openai")
|
||||
_feed(
|
||||
state,
|
||||
_frame({"role": "assistant", "content": "a", "tool_calls": None}),
|
||||
_frame({"tool_calls": [None]}, finish="stop"),
|
||||
)
|
||||
assert state.finish().message["tool_calls"] is None
|
||||
body = {"choices": [{"message": {"role": "assistant", "content": "a", "tool_calls": [None]}}]}
|
||||
assert parse_chat_completion(body).message["tool_calls"] is None
|
||||
|
||||
|
||||
def test_tool_calls_null_then_list_merges():
|
||||
"""tool_calls 先 null 后列表: 正常聚合工具。"""
|
||||
state = ChatCompletionAccumulator(response_mode="openai")
|
||||
tool = {"index": 0, "id": "a", "type": "function", "function": {"name": "f", "arguments": "{}"}}
|
||||
_feed(
|
||||
state,
|
||||
_frame({"role": "assistant", "tool_calls": None}),
|
||||
_frame({"tool_calls": [tool]}, finish="tool_calls"),
|
||||
)
|
||||
assert state.finish().message["tool_calls"][0]["id"] == "a"
|
||||
|
||||
|
||||
def test_nonstream_role_checked_before_verdict():
|
||||
"""审查 Minor3: 非流式缺 role 是形态失败,先于结局判定。"""
|
||||
from polygateway.transports._openai_completion import check_completion_body
|
||||
|
||||
with pytest.raises(TransientError, match="role"):
|
||||
check_completion_body(
|
||||
{"choices": [{"message": {"content": "a"}, "finish_reason": "length"}]}
|
||||
)
|
||||
@@ -0,0 +1,376 @@
|
||||
"""OpenAI 消息保真回归：按网关 Chat Completions 形态构造。"""
|
||||
|
||||
import json
|
||||
|
||||
import httpx
|
||||
import pytest
|
||||
|
||||
from polygateway.errors import AllSourcesExhausted, TransientError
|
||||
from tests.unit.test_client import _client
|
||||
from tests.unit.test_openai_compat import _complete, _source, _sse_stream, _transport_for
|
||||
from tests.unit.test_openai_completion import accumulate, chunk, tool_frames
|
||||
|
||||
|
||||
async def test_error_before_done_is_failure():
|
||||
"""文本模式也不能接受 error 后的 DONE。"""
|
||||
transport = _transport_for(
|
||||
lambda _: _sse_stream(chunk({"content": "partial"}), 'data: {"error": null}\n\n')
|
||||
)
|
||||
try:
|
||||
with pytest.raises(TransientError):
|
||||
await _complete(transport, _source())
|
||||
finally:
|
||||
await transport.aclose()
|
||||
|
||||
|
||||
async def test_mixed_content_reasoning_survive():
|
||||
"""同一帧双文本不互斥。"""
|
||||
transport = _transport_for(
|
||||
lambda _: _sse_stream(chunk({"content": "answer", "reasoning_content": "reason"}))
|
||||
)
|
||||
try:
|
||||
result = await _complete(transport, _source())
|
||||
assert (result.content, result.thinking) == ("answer", "reason")
|
||||
finally:
|
||||
await transport.aclose()
|
||||
|
||||
|
||||
async def test_tools_roundtrip_and_retry():
|
||||
"""真实 transport 经过治理，失败重试不污染工具，消息可直接往返。"""
|
||||
requests = []
|
||||
|
||||
def handler(request):
|
||||
requests.append(json.loads(request.content))
|
||||
if len(requests) == 1:
|
||||
return _sse_stream(
|
||||
chunk({"content": "partial"}),
|
||||
'data: {"error": {"code": "upstream_stream_read_error"}}\n\n',
|
||||
)
|
||||
return _sse_stream(*tool_frames())
|
||||
|
||||
client = _client(handler=handler)
|
||||
try:
|
||||
response = await client.chat(
|
||||
[{"role": "user", "content": "hi"}],
|
||||
response_mode="openai",
|
||||
overlay={"reasoning_effort": "max"},
|
||||
)
|
||||
assert response.call_stats.attempts == 2
|
||||
message = response.completion.message
|
||||
assert message["role"] == "assistant" and message["content"] is None
|
||||
assert [t["id"] for t in message["tool_calls"]] == ["a", "b"]
|
||||
assert message["tool_calls"][0]["function"]["arguments"] == '{"v": "中" }'
|
||||
assert response.completion.response_id == "upstream-1"
|
||||
assert response.completion.finish_reason == "tool_calls"
|
||||
messages = [message, {"role": "tool", "tool_call_id": "a", "content": "ok"}]
|
||||
await client.chat(messages, response_mode="openai")
|
||||
assert requests[-1]["messages"] == messages
|
||||
assert requests[0]["reasoning_effort"] == "max"
|
||||
finally:
|
||||
await client._transport.aclose()
|
||||
|
||||
|
||||
@pytest.mark.parametrize("role", [None, "user"])
|
||||
async def test_final_role_required(role):
|
||||
"""非流式缺失或错误 role 必须协议失败。"""
|
||||
message = {"content": "ok"}
|
||||
if role:
|
||||
message["role"] = role
|
||||
client = _client(
|
||||
handler=lambda _: httpx.Response(200, json={"choices": [{"message": message}]})
|
||||
)
|
||||
try:
|
||||
with pytest.raises(AllSourcesExhausted):
|
||||
await client.chat(
|
||||
[{"role": "user", "content": "hi"}], stream=False, response_mode="openai"
|
||||
)
|
||||
finally:
|
||||
await client._transport.aclose()
|
||||
|
||||
|
||||
@pytest.mark.parametrize("stream", [True, False])
|
||||
async def test_completion_cache_roundtrip(stream):
|
||||
"""完整结果回放，修改返回对象不毒化缓存；模式隔离。"""
|
||||
from polygateway.backends.memory.cache import InMemoryCache
|
||||
|
||||
completion = accumulate().finish()
|
||||
|
||||
def handler(_):
|
||||
if stream:
|
||||
return _sse_stream(*tool_frames())
|
||||
return httpx.Response(
|
||||
200,
|
||||
json={
|
||||
"id": "upstream-1",
|
||||
"choices": [{"message": completion.message, "finish_reason": "tool_calls"}],
|
||||
},
|
||||
)
|
||||
|
||||
client = _client(
|
||||
handler=handler, cache=InMemoryCache(), cache_namespace="tools", cache_ttl_s=60
|
||||
)
|
||||
try:
|
||||
first = await client.chat([], stream=stream, response_mode="openai")
|
||||
second = await client.chat([], stream=stream, response_mode="openai")
|
||||
assert not first.cache_hit and second.cache_hit
|
||||
assert second.completion == first.completion
|
||||
assert second.call_id != first.call_id and second.call_stats.attempts == 0
|
||||
second.completion.message["tool_calls"].clear()
|
||||
third = await client.chat([], stream=stream, response_mode="openai")
|
||||
assert len(third.completion.message["tool_calls"]) == 2
|
||||
finally:
|
||||
await client._transport.aclose()
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
"kwargs",
|
||||
[
|
||||
{"response_mode": "bad"},
|
||||
{"response_mode": "openai", "structured": "json"},
|
||||
{"response_mode": "openai", "overlay": {"n": 2}},
|
||||
{"response_mode": "openai", "overlay": {"n": True}},
|
||||
],
|
||||
)
|
||||
async def test_invalid_mode_combinations_fail_before_http(kwargs):
|
||||
"""组合错误入口拒绝。"""
|
||||
|
||||
def unexpected(_):
|
||||
pytest.fail("不应发送 HTTP")
|
||||
|
||||
client = _client(handler=unexpected)
|
||||
try:
|
||||
with pytest.raises(ValueError):
|
||||
await client.chat([], **kwargs)
|
||||
finally:
|
||||
await client._transport.aclose()
|
||||
|
||||
|
||||
async def test_openai_never_salvages():
|
||||
"""无 finish 后 usage 的截断流即使收全工具也不打捞(1.3.10: 判据由 DONE 改为完成判定)。"""
|
||||
transport = _transport_for(lambda _: _sse_stream(*tool_frames(), done=False))
|
||||
try:
|
||||
with pytest.raises(TransientError, match="missing_done"):
|
||||
await transport.complete(
|
||||
messages=[],
|
||||
source=_source(missing_done="salvage"),
|
||||
stream=True,
|
||||
overlay={},
|
||||
call_id="c",
|
||||
reasoning_effort=None,
|
||||
first_token_event=None,
|
||||
content_event=None,
|
||||
response_mode="openai",
|
||||
)
|
||||
finally:
|
||||
await transport.aclose()
|
||||
|
||||
|
||||
async def test_openai_finish_with_trailing_usage_is_complete_without_done():
|
||||
"""对照: 同一工具流补上 finish 之后的 usage 帧,即使无 DONE 也完整交回(#31)。"""
|
||||
usage = 'data: {"choices": [], "usage": {"prompt_tokens": 3, "completion_tokens": 4}}\n\n'
|
||||
transport = _transport_for(lambda _: _sse_stream(*tool_frames(), usage, done=False))
|
||||
try:
|
||||
result = await transport.complete(
|
||||
messages=[],
|
||||
source=_source(),
|
||||
stream=True,
|
||||
overlay={},
|
||||
call_id="c",
|
||||
reasoning_effort=None,
|
||||
first_token_event=None,
|
||||
content_event=None,
|
||||
response_mode="openai",
|
||||
)
|
||||
finally:
|
||||
await transport.aclose()
|
||||
assert result.stream_end == "eof_after_finish"
|
||||
assert [t["id"] for t in result.completion.message["tool_calls"]] == ["a", "b"]
|
||||
|
||||
|
||||
async def test_tool_progress_sets_events():
|
||||
"""工具首进展驱动两个事件与时间观测。"""
|
||||
import asyncio
|
||||
|
||||
first, progress = asyncio.Event(), asyncio.Event()
|
||||
transport = _transport_for(lambda _: _sse_stream(*tool_frames()))
|
||||
try:
|
||||
result = await transport.complete(
|
||||
messages=[],
|
||||
source=_source(),
|
||||
stream=True,
|
||||
overlay={},
|
||||
call_id="c",
|
||||
reasoning_effort=None,
|
||||
first_token_event=first,
|
||||
content_event=progress,
|
||||
response_mode="openai",
|
||||
)
|
||||
assert first.is_set() and progress.is_set()
|
||||
assert result.ttft_ms is not None and result.stall_count == 0
|
||||
finally:
|
||||
await transport.aclose()
|
||||
|
||||
|
||||
async def test_real_transport_stall_hedge_cancels_loser():
|
||||
"""真实工具流沉默触发异源对冲，连接关闭且赢家不混入半成品。"""
|
||||
import asyncio
|
||||
import time
|
||||
|
||||
from polygateway.sources import RoundRobinSelector
|
||||
from polygateway.types import ChatRequest, _CallContext
|
||||
from tests.unit.test_retry import _src
|
||||
from tests.unit.test_stall_hedge import _harness
|
||||
|
||||
entered, closed = asyncio.Event(), asyncio.Event()
|
||||
|
||||
class Hanging(httpx.AsyncByteStream):
|
||||
"""工具首帧后阻塞，取消由真实 httpx 流处理。"""
|
||||
|
||||
async def __aiter__(self):
|
||||
yield tool_frames()[0].encode()
|
||||
yield tool_frames()[1].encode()
|
||||
entered.set()
|
||||
await asyncio.Event().wait()
|
||||
|
||||
async def aclose(self):
|
||||
closed.set()
|
||||
|
||||
count = 0
|
||||
|
||||
def handler(_):
|
||||
nonlocal count
|
||||
count += 1
|
||||
if count == 1:
|
||||
return httpx.Response(200, stream=Hanging())
|
||||
return _sse_stream(*tool_frames())
|
||||
|
||||
transport = _transport_for(handler)
|
||||
sources = [_src("s1"), _src("s2")]
|
||||
mw, limiter, *_ = _harness(
|
||||
sources, transport, stall_after_s=0.05, selector=RoundRobinSelector()
|
||||
)
|
||||
context = _CallContext(now=time.monotonic)
|
||||
try:
|
||||
response = await asyncio.wait_for(
|
||||
mw(ChatRequest(messages=[], response_mode="openai", call_context=context)), 3
|
||||
)
|
||||
assert entered.is_set() and closed.is_set()
|
||||
assert response.source_name == "s2" and len(response.completion.message["tool_calls"]) == 2
|
||||
assert context.snapshot().hedges == 1 and context.snapshot().attempts == 2
|
||||
finally:
|
||||
await transport.aclose()
|
||||
|
||||
|
||||
@pytest.mark.parametrize("stream", [True, False])
|
||||
async def test_bad_usage_is_domain_failure(stream):
|
||||
"""坏 usage 不能穿透成裸 AttributeError，包括默认文本模式。"""
|
||||
transport = _transport_for(
|
||||
lambda _: (
|
||||
_sse_stream(chunk({"content": "ok"}), 'data: {"choices": [], "usage": [1]}\n\n')
|
||||
if stream
|
||||
else httpx.Response(
|
||||
200, json={"choices": [{"message": {"content": "ok"}}], "usage": [1]}
|
||||
)
|
||||
)
|
||||
)
|
||||
try:
|
||||
with pytest.raises(TransientError):
|
||||
await _complete(transport, _source(), stream=stream)
|
||||
finally:
|
||||
await transport.aclose()
|
||||
|
||||
|
||||
async def test_nonstream_tool_result_has_no_liveness_events():
|
||||
"""非流式工具不制造流式观测。"""
|
||||
import asyncio
|
||||
|
||||
completion = accumulate().finish()
|
||||
first, progress = asyncio.Event(), asyncio.Event()
|
||||
transport = _transport_for(
|
||||
lambda _: httpx.Response(
|
||||
200, json={"choices": [{"message": completion.message, "finish_reason": "tool_calls"}]}
|
||||
)
|
||||
)
|
||||
try:
|
||||
result = await transport.complete(
|
||||
messages=[],
|
||||
source=_source(),
|
||||
stream=False,
|
||||
overlay={},
|
||||
call_id="c",
|
||||
reasoning_effort=None,
|
||||
first_token_event=first,
|
||||
content_event=progress,
|
||||
response_mode="openai",
|
||||
)
|
||||
assert result.completion.message == completion.message
|
||||
assert not first.is_set() and not progress.is_set()
|
||||
assert result.ttft_ms is None and result.stall_ms is None
|
||||
finally:
|
||||
await transport.aclose()
|
||||
|
||||
|
||||
async def test_openai_does_not_bypass_managed_conflict():
|
||||
"""保真模式不静默撤销源级受管意图。"""
|
||||
from polygateway.errors import RequestRejectedError
|
||||
|
||||
def unexpected(_):
|
||||
pytest.fail("冲突请求不应发送 HTTP")
|
||||
|
||||
transport = _transport_for(unexpected)
|
||||
try:
|
||||
with pytest.raises(RequestRejectedError):
|
||||
await transport.complete(
|
||||
messages=[],
|
||||
source=_source(enable_thinking=True),
|
||||
stream=True,
|
||||
overlay={"reasoning_effort": "max"},
|
||||
call_id="c",
|
||||
reasoning_effort=None,
|
||||
first_token_event=None,
|
||||
content_event=None,
|
||||
response_mode="openai",
|
||||
)
|
||||
finally:
|
||||
await transport.aclose()
|
||||
|
||||
|
||||
async def test_cancel_tool_stream_releases_resources():
|
||||
"""显式取消真实工具流，连接关闭且配额归还。"""
|
||||
import asyncio
|
||||
|
||||
from polygateway.backends.memory.limiter import InMemoryLimiter
|
||||
from polygateway.types import GlobalLimits
|
||||
|
||||
entered, closed = asyncio.Event(), asyncio.Event()
|
||||
|
||||
class Hanging(httpx.AsyncByteStream):
|
||||
"""可确定取消窗口的 HTTP 流。"""
|
||||
|
||||
async def __aiter__(self):
|
||||
for frame in tool_frames()[:2]:
|
||||
yield frame.encode()
|
||||
entered.set()
|
||||
await asyncio.Event().wait()
|
||||
|
||||
async def aclose(self):
|
||||
closed.set()
|
||||
|
||||
source = _source(max_concurrency=1)
|
||||
limiter = InMemoryLimiter(
|
||||
scope="llm", sources={source.name: source}, global_limits=GlobalLimits(1, 0, 0)
|
||||
)
|
||||
client = _client(
|
||||
sources=[source], limiter=limiter, handler=lambda _: httpx.Response(200, stream=Hanging())
|
||||
)
|
||||
task = asyncio.create_task(client.chat([], response_mode="openai"))
|
||||
try:
|
||||
await asyncio.wait_for(entered.wait(), 2)
|
||||
task.cancel()
|
||||
with pytest.raises(asyncio.CancelledError):
|
||||
await task
|
||||
assert closed.is_set()
|
||||
assert (await limiter.source_stats(source.name)).inflight == 0
|
||||
finally:
|
||||
task.cancel()
|
||||
await client._transport.aclose()
|
||||
@@ -88,3 +88,15 @@ def test_every_promised_export_is_actually_importable():
|
||||
"""
|
||||
missing = [name for name in polygateway.__all__ if not hasattr(polygateway, name)]
|
||||
assert not missing, f"__all__ 承诺了但没绑上的符号: {missing}"
|
||||
|
||||
|
||||
def test_apache_license_metadata():
|
||||
"""许可正文和包元数据同时存在，不以版本说明替代许可。"""
|
||||
import tomllib
|
||||
from pathlib import Path
|
||||
|
||||
root = Path(__file__).resolve().parents[2]
|
||||
assert "Apache License" in (root / "LICENSE").read_text()
|
||||
assert "Version 2.0" in (root / "LICENSE").read_text()
|
||||
project = tomllib.loads((root / "pyproject.toml").read_text())["project"]
|
||||
assert project["license"] == {"file": "LICENSE"}
|
||||
|
||||
@@ -83,6 +83,7 @@ class _DummyTransport:
|
||||
reasoning_effort,
|
||||
first_token_event,
|
||||
content_event,
|
||||
response_mode,
|
||||
):
|
||||
raise NotImplementedError
|
||||
|
||||
@@ -149,6 +150,7 @@ class _DummyRecorder:
|
||||
total_latency_ms,
|
||||
stall_ms,
|
||||
stall_count,
|
||||
stream_end,
|
||||
) -> None: ...
|
||||
|
||||
|
||||
@@ -321,7 +323,7 @@ class TestTelemetryRecorderSignature:
|
||||
"attempts",
|
||||
"total_latency_ms",
|
||||
} <= set(params)
|
||||
assert len(params) - 1 == 38 # 减掉 self
|
||||
assert len(params) - 1 == 39 # 减掉 self
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
"name",
|
||||
@@ -340,6 +342,7 @@ class TestTelemetryRecorderSignature:
|
||||
"error_body",
|
||||
"attempts",
|
||||
"total_latency_ms",
|
||||
"stream_end",
|
||||
],
|
||||
)
|
||||
def test_caller_dimensions_have_no_default(self, name):
|
||||
|
||||
@@ -90,6 +90,7 @@ class FakeTransport:
|
||||
reasoning_effort,
|
||||
first_token_event,
|
||||
content_event,
|
||||
response_mode,
|
||||
):
|
||||
self.calls.append((source.name, call_id))
|
||||
self.efforts.append(reasoning_effort)
|
||||
@@ -132,6 +133,7 @@ class _GenClockTransport:
|
||||
reasoning_effort,
|
||||
first_token_event,
|
||||
content_event,
|
||||
response_mode,
|
||||
):
|
||||
advance = self._advances.pop(0)
|
||||
stall = self._stalls.pop(0) if self._stalls is not None else None
|
||||
@@ -144,6 +146,7 @@ class _GenClockTransport:
|
||||
reasoning_effort=reasoning_effort,
|
||||
first_token_event=first_token_event,
|
||||
content_event=content_event,
|
||||
response_mode=response_mode,
|
||||
)
|
||||
if stall is not None:
|
||||
result = dataclasses.replace(result, stall_ms=stall[0], stall_count=stall[1])
|
||||
|
||||
@@ -78,6 +78,7 @@ class StallHedgeTransport:
|
||||
reasoning_effort,
|
||||
first_token_event,
|
||||
content_event,
|
||||
response_mode,
|
||||
):
|
||||
self.calls.append(source.name)
|
||||
self.ft_events.append(first_token_event)
|
||||
@@ -271,9 +272,7 @@ class TestStallHedgeTrigger:
|
||||
"""参数化四格(设计 §5.2 逐字): 两阈值独立生效,各格触发语义不串。"""
|
||||
# 格 1: 仅 AFTER_S + 流式 pre-TTFT 挂起 → AFTER_S 触发(1.3.7 语义不变)
|
||||
s1, s2 = _src("s1"), _src("s2")
|
||||
transport = StallHedgeTransport(
|
||||
{"s1": [("hang",), ("ok", "late")], "s2": [("ok", "fast")]}
|
||||
)
|
||||
transport = StallHedgeTransport({"s1": [("hang",), ("ok", "late")], "s2": [("ok", "fast")]})
|
||||
mw, _, _ = _harness([s1, s2], transport, hedge_after_s=_STALL_AFTER_S)
|
||||
ctx = _ctx()
|
||||
resp = await asyncio.wait_for(mw(_req(ctx=ctx)), timeout=5)
|
||||
@@ -312,9 +311,7 @@ class TestStallHedgeTrigger:
|
||||
|
||||
# 格 3b: 两者皆设 + pre-TTFT 挂起 → 阶段 1 AFTER_S 触发(两阶段各管一段)
|
||||
s1, s2 = _src("s1"), _src("s2")
|
||||
transport = StallHedgeTransport(
|
||||
{"s1": [("hang",), ("ok", "late")], "s2": [("ok", "fast")]}
|
||||
)
|
||||
transport = StallHedgeTransport({"s1": [("hang",), ("ok", "late")], "s2": [("ok", "fast")]})
|
||||
mw, _, _ = _harness(
|
||||
[s1, s2], transport, hedge_after_s=_STALL_AFTER_S, stall_after_s=_STALL_AFTER_S
|
||||
)
|
||||
@@ -340,9 +337,7 @@ class TestStallHedgeTrigger:
|
||||
async def test_stall_only_non_stream_degrades_to_single_leg(self):
|
||||
"""仅 stall 已设 + `stream=False` → 逐字单路(中段沉默无非流式概念,入口门)。"""
|
||||
s1, s2 = _src("s1"), _src("s2")
|
||||
transport = StallHedgeTransport(
|
||||
{"s1": [("hang",), ("ok", "x")], "s2": [("ok", "other")]}
|
||||
)
|
||||
transport = StallHedgeTransport({"s1": [("hang",), ("ok", "x")], "s2": [("ok", "other")]})
|
||||
mw, _, _ = _harness([s1, s2], transport, stall_after_s=_STALL_AFTER_S)
|
||||
ctx = _ctx()
|
||||
task = asyncio.ensure_future(mw(_req(stream=False, ctx=ctx)))
|
||||
|
||||
+109
-13
@@ -92,6 +92,8 @@ _EXPECTED_COLUMNS = [
|
||||
# —— 1.3.8 沉默归因两列(issue #27)——
|
||||
"stall_ms",
|
||||
"stall_count",
|
||||
# —— 1.3.10 结束方式(#31)——
|
||||
"stream_end",
|
||||
]
|
||||
|
||||
# 1.3.5 之前的 26 个 INSERT 字段(旧表形态),供冻结 INSERT 语句与旧表补列用例复用
|
||||
@@ -187,6 +189,8 @@ async def _record_minimal(recorder, call_id="c1", **overrides):
|
||||
# —— 1.3.8 沉默归因两列: 默认 None = 非流式/无沉默观测(合法事实)——
|
||||
"stall_ms": None,
|
||||
"stall_count": None,
|
||||
# —— 1.3.10 结束方式: 默认 None = 非流式/缓存命中/失败行 ——
|
||||
"stream_end": None,
|
||||
}
|
||||
fields.update(overrides)
|
||||
await recorder.record_llm_call(**fields)
|
||||
@@ -268,7 +272,7 @@ class TestSchemaModule:
|
||||
|
||||
# COLUMNS 是 INSERT 字段序,不含数据库自填的 created_at
|
||||
assert list(COLUMNS) == [c for c in _EXPECTED_COLUMNS if c != "created_at"]
|
||||
assert len(COLUMNS) == 38
|
||||
assert len(COLUMNS) == 39
|
||||
# 两端 DDL 的列出现顺序 == 物理列序(created_at 在第 19 位)
|
||||
for ddl in (SQLITE_DDL, PG_DDL):
|
||||
assert _first_occurrence_order(ddl, _EXPECTED_COLUMNS) == _EXPECTED_COLUMNS
|
||||
@@ -282,8 +286,8 @@ class TestSchemaModule:
|
||||
"ALTER TABLE llm_calls ADD COLUMN cached_prompt_tokens INTEGER",
|
||||
)
|
||||
assert PG_BACKFILL[-1] == (
|
||||
"stall_count",
|
||||
"ALTER TABLE llm_calls ADD COLUMN stall_count INTEGER",
|
||||
"stream_end",
|
||||
"ALTER TABLE llm_calls ADD COLUMN stream_end TEXT",
|
||||
)
|
||||
assert all("IF NOT EXISTS" not in stmt for _, stmt in PG_BACKFILL)
|
||||
|
||||
@@ -297,10 +301,10 @@ class TestSchemaModule:
|
||||
|
||||
assert insert_sql("sqlite", _PRE_135_COLUMNS) == _FROZEN_SQLITE_INSERT
|
||||
assert insert_sql("postgres", _PRE_135_COLUMNS) == _FROZEN_PG_INSERT
|
||||
# 全量 38 列: 占位符随列数增长,且不留空洞
|
||||
assert insert_sql("postgres", COLUMNS).count("$") == 38
|
||||
assert "$38)" in insert_sql("postgres", COLUMNS)
|
||||
assert insert_sql("sqlite", COLUMNS).count("?") == 38
|
||||
# 全量 39 列: 占位符随列数增长,且不留空洞
|
||||
assert insert_sql("postgres", COLUMNS).count("$") == 39
|
||||
assert "$39)" in insert_sql("postgres", COLUMNS)
|
||||
assert insert_sql("sqlite", COLUMNS).count("?") == 39
|
||||
# 裁剪列表按位置占位符重新编号,不留空洞
|
||||
assert insert_sql("postgres", ["call_id", "model"]) == (
|
||||
"INSERT INTO llm_calls (call_id, model) VALUES ($1, $2) ON CONFLICT DO NOTHING"
|
||||
@@ -377,13 +381,14 @@ class TestBackendColumnParity:
|
||||
"""新列只能追加在末尾: 旧表经 ALTER 补列必落末尾,插在中间会让两条路径分叉。"""
|
||||
from polygateway.telemetry.schema import COLUMNS
|
||||
|
||||
assert COLUMNS[-6:] == (
|
||||
assert COLUMNS[-7:] == (
|
||||
"cause_type",
|
||||
"error_body",
|
||||
"attempts",
|
||||
"total_latency_ms",
|
||||
"stall_ms",
|
||||
"stall_count",
|
||||
"stream_end",
|
||||
)
|
||||
|
||||
|
||||
@@ -776,7 +781,7 @@ class TestSQLiteCallerDimensionsAcceptance:
|
||||
|
||||
conn = sqlite3.connect(db)
|
||||
cols = [r[1] for r in conn.execute("PRAGMA table_info(llm_calls)")]
|
||||
assert cols == _EXPECTED_COLUMNS # 22 → 38 个 recorder 字段(+ created_at 共 39 物理列)
|
||||
assert cols == _EXPECTED_COLUMNS # 22 → 39 个 recorder 字段(+ created_at 共 40 物理列)
|
||||
rows = dict(conn.execute("SELECT call_id, tenant_id FROM llm_calls").fetchall())
|
||||
assert rows["new-row"] == "tenant-a"
|
||||
assert rows["old-row"] == "" # 不是 None: NULL 会被 RLS 静默吞掉
|
||||
@@ -826,7 +831,7 @@ class TestSQLiteSchemaMode:
|
||||
"""issue #13: `auto_migrate` 两档——auto 保持自动补列,manual 只裁剪写入不发 DDL。
|
||||
|
||||
列数断言一律按**物理列数**写: 旧表 22 个 INSERT 字段 + `created_at` = 23,
|
||||
补齐后 38 + `created_at` = 39。混用 INSERT 字段数与物理列数是本处最易错的地方。
|
||||
补齐后 39 + `created_at` = 40。混用 INSERT 字段数与物理列数是本处最易错的地方。
|
||||
"""
|
||||
|
||||
def _physical_columns(self, db: Path) -> list[str]:
|
||||
@@ -865,7 +870,7 @@ class TestSQLiteSchemaMode:
|
||||
assert "ALTER TABLE" in message # 给出可直接执行的补列 SQL
|
||||
|
||||
async def test_auto_mode_still_upgrades_the_legacy_table(self, tmp_path):
|
||||
"""auto + 同款旧表: 现状回归,补列后物理列数 23 → 39。"""
|
||||
"""auto + 同款旧表: 现状回归,补列后物理列数 23 → 40。"""
|
||||
db = tmp_path / "auto_legacy.db"
|
||||
_make_pre_tenant_db(db)
|
||||
|
||||
@@ -874,10 +879,10 @@ class TestSQLiteSchemaMode:
|
||||
recorder.close()
|
||||
|
||||
assert self._physical_columns(db) == _EXPECTED_COLUMNS
|
||||
assert len(self._physical_columns(db)) == 39
|
||||
assert len(self._physical_columns(db)) == 40
|
||||
|
||||
async def test_manual_mode_still_creates_a_fresh_table(self, tmp_path):
|
||||
"""manual 只管 ALTER,不管 CREATE: 全新库照建,39 个物理列齐全(设计 §4.2)。"""
|
||||
"""manual 只管 ALTER,不管 CREATE: 全新库照建,40 个物理列齐全(设计 §4.2)。"""
|
||||
db = tmp_path / "manual_fresh.db"
|
||||
recorder = SQLiteRecorder(db, auto_migrate=False)
|
||||
await _record_minimal(recorder, call_id="c-fresh", tenant_id="tenant-a")
|
||||
@@ -1117,6 +1122,8 @@ class TestPostgresBackfillDiscipline:
|
||||
# 1.3.8 两列: 稳态定义随补列前移,否则每进程首写都去抢锁
|
||||
"stall_ms",
|
||||
"stall_count",
|
||||
# 1.3.10 一列,理由同上
|
||||
"stream_end",
|
||||
]
|
||||
|
||||
def _recorder(self, conn):
|
||||
@@ -3586,3 +3593,92 @@ class TestTerminalRowSqlSemantics:
|
||||
).fetchone()[0]
|
||||
== 0
|
||||
)
|
||||
|
||||
|
||||
# 1.3.8 形态(1.3.10 补列前)的表: 38 个 INSERT 字段 + created_at = 39 物理列。
|
||||
# 冻结字面量(由 _PRE_138_DDL 末行补两列),不从常量切片派生,理由同 _PRE_138_DDL。
|
||||
_PRE_1310_DDL = _PRE_138_DDL.replace(
|
||||
" total_latency_ms INTEGER\n);",
|
||||
" total_latency_ms INTEGER,\n stall_ms INTEGER,\n"
|
||||
" stall_count INTEGER\n);",
|
||||
)
|
||||
|
||||
|
||||
class TestStreamEndColumn:
|
||||
"""1.3.10 结束方式列(#31): 落行、缺省 NULL、补列幂等、manual 告警、各入口取值。"""
|
||||
|
||||
async def test_value_round_trips_and_default_is_null(self, tmp_path):
|
||||
db = tmp_path / "stream_end.db"
|
||||
recorder = SQLiteRecorder(db, auto_migrate=True)
|
||||
await _record_minimal(recorder, call_id="c-eof", stream_end="eof_after_finish")
|
||||
await _record_minimal(recorder, call_id="c-none")
|
||||
recorder.close()
|
||||
conn = sqlite3.connect(db)
|
||||
rows = dict(conn.execute("SELECT call_id, stream_end FROM llm_calls").fetchall())
|
||||
conn.close()
|
||||
assert rows == {"c-eof": "eof_after_finish", "c-none": None}
|
||||
|
||||
async def test_auto_migrate_backfills_from_138_table(self, tmp_path):
|
||||
db = tmp_path / "pre1310.db"
|
||||
conn = sqlite3.connect(db)
|
||||
conn.execute(_PRE_1310_DDL)
|
||||
conn.commit()
|
||||
conn.close()
|
||||
for call_id in ("c1", "c2"): # 二次初始化幂等
|
||||
recorder = SQLiteRecorder(db, auto_migrate=True)
|
||||
await _record_minimal(recorder, call_id=call_id, stream_end="done")
|
||||
recorder.close()
|
||||
conn = sqlite3.connect(db)
|
||||
assert [r[1] for r in conn.execute("PRAGMA table_info(llm_calls)")] == _EXPECTED_COLUMNS
|
||||
conn.close()
|
||||
|
||||
async def test_manual_mode_names_the_new_alter(self, tmp_path, captured_warnings):
|
||||
db = tmp_path / "manual1310.db"
|
||||
conn = sqlite3.connect(db)
|
||||
conn.execute(_PRE_1310_DDL)
|
||||
conn.commit()
|
||||
conn.close()
|
||||
recorder = SQLiteRecorder(db, auto_migrate=False)
|
||||
await _record_minimal(recorder, call_id="c-manual", stream_end="done")
|
||||
recorder.close()
|
||||
conn = sqlite3.connect(db)
|
||||
assert len([r[1] for r in conn.execute("PRAGMA table_info(llm_calls)")]) == 39
|
||||
assert conn.execute("SELECT call_id FROM llm_calls").fetchone() == ("c-manual",)
|
||||
conn.close()
|
||||
assert "ALTER TABLE llm_calls ADD COLUMN stream_end TEXT" in captured_warnings[0]
|
||||
|
||||
async def test_attempt_takes_stream_end_from_response(self):
|
||||
rec = _MemoryRecorder()
|
||||
await TelemetryEmitter(rec, text_cap=None, scope="LLM").emit_attempt(
|
||||
request=_REQ,
|
||||
source=_source(),
|
||||
call_id="c",
|
||||
latency_ms=1,
|
||||
response=_resp(stream_end="eof_after_finish"),
|
||||
error=None,
|
||||
reasoning_applies=True,
|
||||
operation="chat",
|
||||
)
|
||||
assert rec.rows[0]["stream_end"] == "eof_after_finish"
|
||||
|
||||
async def test_failed_hit_and_terminal_rows_are_null(self):
|
||||
rec = _MemoryRecorder()
|
||||
emitter = TelemetryEmitter(rec, text_cap=None, scope="LLM")
|
||||
await emitter.emit_attempt(
|
||||
request=_REQ,
|
||||
source=_source(),
|
||||
call_id="c",
|
||||
latency_ms=1,
|
||||
response=None,
|
||||
error="boom",
|
||||
reasoning_applies=True,
|
||||
operation="chat",
|
||||
)
|
||||
# 命中行显式不信任 response 上的值(即使上游误带)
|
||||
await emitter.emit_cache_hit(
|
||||
request=_REQ, response=_resp(cache_hit=True, stream_end="done"), operation="chat"
|
||||
)
|
||||
await emitter.emit_terminal_failure(
|
||||
request=_REQ, call_id="c", error="dead", operation="chat", stats=_MIGRATED_STATS
|
||||
)
|
||||
assert [row["stream_end"] for row in rec.rows] == [None, None, None]
|
||||
|
||||
@@ -141,6 +141,7 @@ async def test_salvage_override_stays_in_domain(usage):
|
||||
reasoning_effort=None,
|
||||
first_token_event=None,
|
||||
content_event=None,
|
||||
response_mode="text",
|
||||
)
|
||||
assert result.usage_source in USAGE_SOURCES
|
||||
|
||||
|
||||
Reference in New Issue
Block a user