Skip to content

Hermes 插件上报宿主 per-model 上下文窗口(修 #3261:自定义模型按默认 200K 计算) - #3262

Merged
ranxianglei merged 1 commit into
masterfrom
2026-10-15_hermes-context-window
Oct 15, 2026
Merged

ranxianglei merged 1 commit into
masterfrom
2026-10-15_hermes-context-window

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Closes #3261

是什么问题

Hermes 原生插件只上报 model/max-output,从不带 context window。自定义 provider 别名(如 group/sol)不在任何模型目录里,注册表兜底解析不到 → native=none → 会话按默认 200K 算预算;而 Hermes 宿主自己明确知道真实窗口(HERMES_HOME/context_length_cache.yaml 里就有 group/sol@http://…: 500000)。同一代理下 pi 正常,因为 pi 两条通道都盖了。

修法(纯 Python 插件侧,零 TS 变更)

proxy 侧两条链路本来都是通的(头通道 pluginReportedContextWindow + pluginHeadersMatchModel 门控;runtime-info 的 contextWindow 字段 handlePluginRuntimeInfo 已解析),缺的只是插件侧把宿主真值带上来:

  • 新增 context_window_for(model, base_url):best-effort 读 HERMES_HOME/context_length_cache.yaml(宿主自维护、键 <model>@<base_url>),复用既有双 YAML 后端模式(PyYAML/ruamel,[Bug] mitm_domains_from_config() bare 'import yaml' returns [] when PyYAML is absent -> silent blind tunnel (ruamel.yaml fallback suggested) #2838)。任何缺失/解析失败/无匹配一律 fail-open 回 None,proxy 走原有窗口链——最坏情况 = 现状。
  • base URL 解析:hook/request 现成字段优先,否则用 hook 的 provider 参数从 config.yaml providers 表解析(与 mitm_domains_from_config() 同源同键名)。匹配两级:归一化全 URL 精确匹配 → origin 粒度(缓存键带 /v1 后缀而配置常省略)。
  • 歧义不猜:同一模型在不同上游映射到不同窗口且无法定位当前上游时,宁缺毋报——报大导致 preflight 溢出、报小导致过度压缩,都比默认值更糟的方向要避免。
  • 双通道上报:on_llm_request 盖 x-bili-plugin-context-window 头(与 model 头同刻,天然满足 pluginHeadersMatchModel 门控);runtime-info body 加 contextWindow 字段,去重键从 (model, maxOutput) 扩为 (model, maxOutput, contextWindow),窗口变化会重新上报。

顺手修的同路径缺陷(独立标注)

on_pre_api_request 里 table 只在 max_tokens 存在的分支内绑定、却在分支外无条件读取——hermes 以无 max_tokens 触发该 hook 时抛 NameError 被外层 except 吞掉,整条 runtime-info 上报静默丢失(包括 maxOutput 本身)。已把绑定提升到分支外。行为变更:旧行为 = 无 max_tokens 的 hook 触发不上报任何 runtime-info;新行为 = 正常上报(maxOutput 缺席、contextWindow 若有则带上)。纯修复,无回归面。

行为变更披露

  • Hermes 会话的窗口来源链新增一个实际生效的高优先级输入:宿主 cache 命中时,nudge 分母从「注册表猜测/默认 200K」变为宿主真值(issue 场景:200K → 500K)。这是本 PR 的目的本身。
  • 口径说明:若宿主缓存值是「扣输出预留后的可用输入预算」口径(issue 备注提到 UI 如此显示),bili 还会再预留输出空间,等于略偏保守地提前压缩——方向安全,非回归。
  • 未命中/歧义/无 YAML 后端的宿主:行为与现状完全一致(fail-open 有测试钉住)。

测试

tests/hermes-native.test.ts(定向本地全绿 30/30,typecheck 干净;全量回归以 CI 为准):

  • 既有 attach 场景加一条断言钉住 fail-open:无 cache 文件 → 无窗口头(runtime-info deepEqual 本就钉死 body 形状)。
  • 新增 attach-window 场景:cache 含 group/sol@http://127.0.0.1:3425/v1: 500000 + config provider 指向同 origin(不带 /v1,覆盖 origin 粒度匹配腿)→ 断言头通道 "500000" + runtime-info {…, contextWindow: 500000};hook 调用刻意不带 provider kwarg(已知最小 hook 面),验证单条目无歧义回退腿。测试机无 YAML 后端时正腿跳过并 warn(负腿照跑)。
  • 新增 attach-window-ambiguous 场景:同模型两个上游两个窗口 → 断言两通道都不猜。

配置面 / kernel / 发布注意

  • 无新增配置项/env/CLI flag;无 kernel/ 或 pi-subagents/ 变更;不动 version。
  • 用户侧生效方式:发版后 bili plugin update hermes 刷新插件副本(安装器逐字节拷贝源文件,测试已钉住)。

…#3261)

The hermes native plugin stamped model/max-output but never the context
window, so custom-alias models (absent from every registry) sized sessions
at the 200K default even when the host knew the real window. Now the
plugin reads HERMES_HOME/context_length_cache.yaml (the host's own
per-model window cache, keyed <model>@<base_url>) best-effort and reports
it on both #955/#956 channels: x-bili-plugin-context-window header in the
llm_request middleware and contextWindow in the runtime-info body (dedup
key extended so a changed window re-reports). Base URL resolution:
hook/request-supplied fields first, then the provider entry in
config.yaml; matching is exact-URL then origin-granularity (cache keeps
/v1, configs often omit it); conflicting per-upstream windows are never
guessed (fail-open to the proxy's normal chain, like every other miss).

Adjacent fix in the same call path: on_pre_api_request read 'table'
unconditionally while binding it only inside the max_tokens-present
branch — a hook fire without max_tokens raised NameError into the
swallowing except and silently skipped the whole runtime-info report.
Hoisted the binding.
@github-actions

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-15_hermes-context-window (cd63f86)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.3762-pr.3262.9a44dc6

This exact version is immutable and reproducible. The rolling pr tag tracks the newest test build across all PRs.

Option B — Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr3262.tgz
npm install -g package

Install instructions are refreshed on each push.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

查重: 不重复。 检索了 open+closed issue 与 PR(按失败签名:hermes / context window / context_length_cache / runtime-info):无其他条目做同一件事;master 上最近的 hermes-plugin 提交(#2905 attach、#2838 YAML 双后端、#2455 非 ASCII model 头保护)都是不同机制;引用 #3261 的只有本 PR。

正在独立审核(不复读 issue 侧结论):已拉取分支核对代码、确认 proxy 侧两条链路(x-bili-plugin-context-window 头 + runtime-info contextWindow)确实零 TS 变更即可承接、docs 四件套 diff 已过。接下来本地跑定向测试 tests/hermes-native.test.ts(全量以 CI 为准),然后按结构化八问给出完整 review 结论。当前 CI:静态门禁全绿,test 分片仍在跑。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

PR #3262 独立审核结论(八问)

审核方式:不复读 issue 侧分析,自己拉分支重读 diff、对照 master 旧代码、核 proxy 侧链路、本地定向验证。CI 39/39 全绿(head cd63f863e);本地定向 tests/hermes-native.test.ts 30/30 通过、0 skip(本机有 PyYAML,正腿真实执行,非跳过)、typecheck/build/py_compile 干净。PR 落后 master 一个无关合并(#3253 incremental lane,零文件交集,已核 handle.ts 窗口级联区域未被触碰),mergeable=True,无需 rebase。

  1. 是什么问题:Hermes 原生插件从不把宿主已知的 per-model 上下文窗口报给 bili——自定义 provider 模型(如 group/sol)查不到注册表,会话按默认 200K 算压缩预算,而宿主自己的 HERMES_HOME/context_length_cache.yaml 里明明记着真实值 500K。
  2. 什么原因导致的:proxy 侧两条通道(x-bili-plugin-context-window 头 + runtime-info contextWindow 字段)本来就通,缺的只是 Python 插件侧没填。我逐行核实了 proxy 端:头门控 pluginReportedContextWindow/pluginHeadersMatchModel(src/plugin.ts:179-223,与 model 头同刻盖戳天然满足门控)、runtime-info 解析 num() 校验(src/plugin.ts:599-611)、pi 同款先例(src/agent/pi.ts:1133)——零 TS 变更成立。同路径还有一个潜伏缺陷:on_pre_api_request 的 table 只在 max_tokens 有效分支内绑定却在分支外无条件读,无 max_tokens 触发时 NameError 被吞 → 整条 runtime-info(含 maxOutput)静默丢失。对照 master 旧代码确认属实,提升绑定位置修法正确。
  3. 影响范围与严重程度:所有 hermes-native + 未入目录模型的用户;方向是「以为窗口比实际小」→ 提前/过度压缩,浪费 token、保留质量下降,但不会溢出,属效率退化而非不可用。NameError 面:无 max_tokens 触发的会话连 maxOutput 都丢,输出预算预留退化。
  4. 怎么修复的:纯插件侧。best-effort 读宿主 cache(键 <model>@<base_url>),上游 URL 三级定位(hook/request 现成字段 → config.yaml providers 表,键名与 MITM 发现同源同序),两级匹配(归一化全 URL → origin 粒度,覆盖缓存带 /v1 配置省略的差),歧义宁缺毋报,任何缺失/解析失败 fail-open 回 None(最坏 = 现状)。双通道上报 + 去重键扩为 (model, maxOutput, contextWindow)。
  5. 是否有回归问题:无。逐项清点过既有行为:① 既有四个头的盖章不变,无 cache 文件宿主行为字节级一致(新断言钉住);② runtime-info body 为纯增量字段,proxy 解析器是 pi/dsh/opencode 各 lane 共用的既有代码;③ 去重键加宽仅进程内存,单向启用「窗口变化重新上报」,无持久化格式影响;④ NameError 修复 = 静默丢弃 → 正常上报(已在 PR 披露);⑤ 窗口在级联中的位次与其他 lane 完全一致(注册表之上、operator 配置之下),未引入新语义;⑥ 安装器未动,逐字节拷贝测试通过;⑦ 零 TS diff,不碰 kernel/wire/persistence。
  6. 是否破坏缓存:不涉及。不改线上消息内容,只加内部协议头 + 回环 POST 元数据;前缀缓存、会话身份、持久化均不受影响。
  7. 是否改了设计方向:没有。是把 hermes lane 补到既有双通道协议的满配(与 pi/dsh/opencode 同一契约);「歧义不猜」与 fix: floor output-budget restore by best-known model output ceiling; warn once per model when none exists (#1840) #1842「不猜配额下限」纪律一致。
  8. 是否引入了新的配置:没有。无 env/config/CLI;读的是宿主自维护文件,不属于 bili 配置面。用户侧生效:发版后 bili plugin update hermes。

小观察(不拦):每次模型调用最多触发 2×(cache+config) 次小 YAML 解析(两个 hook 各一次)——文件极小且 best-effort 设计本就如此,不值得为此加缓存失效复杂度,不立项。

判定:可合。 证据链完整(CI 39/39 + 本地定向 30/30 + 回归清点),diff 每行都服务于本 PR 目的,docs 四件套 en/zh 同步且与代码事实相符。按仓库规则合并按钮在你手里:#3262

@ranxianglei
ranxianglei merged commit c2a73cc into master Oct 15, 2026
39 checks passed
@github-actions

Copy link
Copy Markdown
Contributor

📦 Merged Build Published

This merge to master was published as 0.0.445-master.c2a73cc (rolling master tag).

npm install -g billion-context@0.0.445-master.c2a73cc  # this exact build
npm install -g billion-context@master  # always the newest merged build

npm view billion-context@master prints the current version at any time.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Hermes 插件不上报 contextWindow:宿主已知窗口丢失,自定义模型按默认 200K 计算(pi 同代理正常)

1 participant