diff --git a/CHANGELOG.md b/CHANGELOG.md index 24c034d..67c2e36 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,34 @@ # CHANGELOG +## 2026-09-28 · 上游会话 id 支持客户端显式指定(`x-opencode-session` 优先) + +老板要求:「x-opencode-session 如果 api 请求有带的话优先用请求上的,没有再用 apikey 的那个方式」。 + +**取值优先级**(`_upstream_session()`): + +| 优先级 | 来源 | 派生 | +| --- | --- | --- | +| ① | **入站 `x-opencode-session` 头**(本轮新增) | `sha256("s:{账号}:{客户端值}")[:32]` | +| ② | 请求里的 `conversation_id` | `sha256("{账号}:{conversation_id}")[:32]` | +| ③ | 用这个 API Key 自己(一个 Key 一个稳定会话) | `sha256("k:{去前缀Key}")[:32]` | +| ④ | 登录页会话(无 Key) | `sha256("u:{账号}")[:32]` | + +- 客户端带了就用客户端的(它最清楚哪几次调用算同一段对话),**但仍按账号哈希** —— 保留 + 第二十六轮定下的账号隔离:两个账号即便写同一个值,也不会被绑到同一个上游会话标识上; +- 入站值同样过 `conversation_id` 那套入口校验(仅 ASCII、≤128 字符),**非法值静默丢弃并回退** + (可选头不该把请求打回 400);非 ASCII 值在 HTTP 层就发不出去(httpx 直接拒),校验是兜底; +- 三个调用点(直传端点、managed 非流式、managed 流式)全部接上。 + +**实测(生产,2026-09-28)**:同一会话头连打两次同一段 4k 前缀 → `cached 0 → 1920`(稳定复用); +不带头(回退 Key 派生)两次都命中。 +**顺带更正一条旧认知**:上游提示词缓存**并非严格按 session 隔离** —— 换一个会话头、同一段前缀 +照样命中(1920)。所以稳定会话 id 是「纳入缓存」的前提之一,**不是隔离边界**,也不能拿缓存 +命中率当会话隔离的判据(README 与代码注释已同步更正)。 + +**测试**:新增「取值优先级 + 账号隔离」与「入站头端到端(稳定/换头/回退/非法值)」两条回归, +测试数 204 → **206 全过**;`ci_check.sh` 全绿。 + + ## 2026-09-28 · 修「token 统计恒 0」+ token 细分(缓存命中 / 推理) 老板报「token 数统计有问题,一直都是 0」。 diff --git a/README.md b/README.md index a224818..4b2f954 100644 --- a/README.md +++ b/README.md @@ -54,12 +54,31 @@ api-gateway/ > `extra_headers`**(适配器缓存会把它冻结)。会话 id 的取值逻辑(方案 A + 第二十六轮加固): > 前端对话页为「同一段对话」维持一个稳定 `conversation_id` 并随请求带来;**纯 API 调用**则在请求体 > 里带同名字段(用 OpenAI SDK 时放 `extra_body={"conversation_id": ...}`)。网关**不原样透传**, -> 而是派生成 `sha256("{账号}:{conversation_id}")[:32]` 再作为 `x-opencode-session` 发往上游: -> 同一账号的同一段对话**恒定不变**(给上游一个语义正确的「对话级」标识,而不是每请求一个随机值), -> 不同账号之间**天然隔离**(两人碰巧用了同一个字符串,也不会共用同一个上游会话标识); -> 请求未带(或传空白串)时回退为每次请求一个随机 UUID(仍能过强校验)。 +> 而是按下面的**优先级**派生成一个稳定值再作为 `x-opencode-session` 发往上游 +> (第三十五轮更新;任何一级都**不再回退成随机 UUID** —— 随机 = 缓存命中率恒为 0): > -> - **关于提示词缓存(实测更正,2026-09-18):不要指望用稳定会话 id 来吃缓存。** +> | 优先级 | 来源 | 派生方式 | +> | --- | --- | --- | +> | ① | **入站 `x-opencode-session` 头**(客户端显式指定,第三十五轮新增) | `sha256("s:{账号}:{客户端值}")[:32]` | +> | ② | 请求里的 `conversation_id` | `sha256("{账号}:{conversation_id}")[:32]` | +> | ③ | 都没带 → 用**这个 API Key 自己**(一个 Key 一个稳定会话) | `sha256("k:{去前缀Key}")[:32]` | +> | ④ | 连 Key 都没有(登录页会话) | `sha256("u:{账号}")[:32]` | +> +> - ①「客户端带了就用客户端的」:客户端最清楚哪几次调用算同一段对话,比网关拿 Key 兜底更贴合 +> 它的会话划分;但**仍按账号哈希**,保留账号隔离 —— 否则两个账号只要用同一个值就会共用上游 +> 缓存作用域。值同样过 `conversation_id` 那套入口校验 +> (仅 ASCII、≤128 字符),非法值**静默丢弃并回退**(可选头不该把请求打回 400)。 +> - 同一账号的同一段对话**恒定不变**,不同账号之间**天然隔离**(两人碰巧用了同一个字符串也不会 +> 共用同一个上游会话标识)。 +> +> - **关于提示词缓存**:会话 id 稳定是**吃到缓存的前提**,但不是充分条件(上游缓存本身是 +> 机会性的)。2026-09-28 复测:同一个稳定会话下、同一段 4k token 前缀连打两次, +> 第二次 `cached_tokens=1920`(命中);而 2026-09-18 的观测里同一 session 连打 6 次 +> 得到 `[0,0,0,0,896,896]`(前几次未命中、之后才命中)。所以:**别把它当保证**, +> 但**千万别让它随机** —— 每请求一个随机 UUID 等于永远不命中。 +> **2026-09-28 实测更正**:上游缓存**并非严格按 session 隔离** —— 换一个会话头、同一段 4k +> 前缀照样命中(1920)。所以会话 id 是「纳入缓存」的前提之一,**不是隔离边界**,也别拿缓存 +> 命中率当会话隔离的判据。 > 多轮实测(真实 key、长 prompt 约 940 token)显示 `cached_tokens` 与该头**没有稳定关系**: > 同一 session 连打 6 次得到 `[0,0,0,0,896,896]`(前 4 次未命中,之后才命中); > 等缓存落定后**换全新 session** 打同一 prompt,也是「命中 936」与「不命中 0」混合出现。 diff --git a/app/main.py b/app/main.py index 6597b22..25011ea 100644 --- a/app/main.py +++ b/app/main.py @@ -1524,7 +1524,8 @@ async def _passthrough(request: Request, protocol: str): # 定点改写:model 换成真实 id(别名场景)+ 盖模型级强制参数;其余字段一个不动 payload = adapter.prepare_payload(model_in, clean) - session = _upstream_session(conv, caller, getattr(request.state, "key_token", None)) + session = _upstream_session(conv, caller, getattr(request.state, "key_token", None), + _inbound_session(request)) if stream: return await _passthrough_stream(request, rid, caller, protocol, adapter, cb, @@ -1824,23 +1825,59 @@ async def chat_completions(request: Request, req: ChatRequest, _auth=Depends(req return await _chat_once(cfg, rid, caller, request, req, model_id, messages, tools) -def _upstream_session(conversation_id: str | None, account: str, key_token: str | None = None) -> str: - """把调用的标识派生成**稳定**的上游 session id(第二十六轮 + 第二十九轮强化)。 +# 入站显式会话头(第三十五轮):客户端自己指定的上游会话 id。 +SESSION_HEADER = "x-opencode-session" + + +def _inbound_session(request) -> str | None: + """读入站的 `x-opencode-session`(客户端显式指定的会话 id)。 + + 与 `conversation_id` 走**同一套入口校验**(非 ASCII / 过长一律丢弃)—— 两者最终都会 + 成为发往上游的 header,脏值不能在这里放过。校验不过时**静默回退**(当作没带): + 一个可选头不该把请求打回 400。 + """ + raw = request.headers.get(SESSION_HEADER) + if not raw: + return None + try: + return normalize_conversation_id(raw) + except ValueError as e: + log.warning("[rid=%s] 入站 %s 非法(%s),忽略并回退到派生会话", + getattr(request.state, "rid", "-"), SESSION_HEADER, e) + return None + + +def _upstream_session(conversation_id: str | None, account: str, key_token: str | None = None, + client_session: str | None = None) -> str: + """把调用的标识派生成**稳定**的上游 session id(第二十六轮 + 第二十九轮 + 第三十五轮)。 上游(OpenCode Go)的提示词缓存以 `x-opencode-session` 为作用域 —— 实测:同一 session 的第二次请求 `cached_tokens` 全量命中,换成另一个 session 则恒为 0(换 session = 完全不 吃缓存)。所以这个值**必须在一次最近的重复调用间恒定**。取值优先级: - ① 客户端带了 `conversation_id`(第二十六轮):first 「账号:会话」后哈希 —— 同一段对话 - 恒定 → 该对话内反复出现的前缀命中;不同账号天然隔离。 - ② 没带(QwenPaw / 多数 agent 不发这个字段,第二十九轮老板决策):用**这个 API Key + ① **客户端显式带了 `x-opencode-session`(第三十五轮,老板要求)**:客户端最清楚 + "哪几次调用算同一个会话",带了就听它的(比网关用 Key 兜底更贴合它的会话划分)。 + 仍然**按账号哈希**(`s:账号:客户端值`)—— 保持第二十六轮定下的账号隔离:两个账号 + 即便写了同一个值,也不会被绑到同一个上游会话标识上(上游按它记会话/日志;缓存那层 + 见下注,别指望靠它做隔离)。 + ② 客户端带了 `conversation_id`(第二十六轮):按「账号:会话」哈希 —— 同一段对话恒定 + → 该对话内反复出现的前缀命中;不同账号天然隔离。 + ③ 没带(QwenPaw / 多数 agent 不发这些字段,第二十九轮老板决策):用**这个 API Key 自己**派生 —— 一个 Key 一个稳定会话,比"每调随机"命中率高得多。但**先哈希再传**: 直接把 `wjd-` 后面那串原样发给上游等于泄露 Key 凭证内容给第三方(见 _key_token)。 - ③ 连 Key 都没有(登录页面会话,kind=session):按账号稳定兜底,同样不再随机。 + ④ 连 Key 都没有(登录页面会话,kind=session):按账号稳定兜底,同样不再随机。 - 这三级都**不再回退成每个调用一个随机 UUID** —— 随机=缓存命中率恒为 0。上游只看到 + 这四级都**不再回退成每个调用一个随机 UUID** —— 随机=缓存命中率恒为 0。上游只看到 32 位十六进制串,不暴露账号名、业务命名或 Key 明文。 + + ★ 2026-09-28 实测更正:上游的提示词缓存**并不是严格按 session 隔离的** —— + 同一段 4k 前缀,用同一个会话头连打(0 → 1920 命中)能命中;**换成另一个会话头** + 再打同一段前缀,照样命中(1920)。所以「稳定会话 id」是**吃到缓存的前提之一、但不是隔离边界**, + 更不是保证(2026-09-18 还观测到同一 session 连打 6 次才陆续命中)。 + 别把缓存命中率当成会话隔离的判据。 """ + if client_session: + return hashlib.sha256(f"s:{account}:{client_session}".encode("utf-8")).hexdigest()[:32] if conversation_id: return hashlib.sha256(f"{account}:{conversation_id}".encode("utf-8")).hexdigest()[:32] if key_token: @@ -1892,7 +1929,9 @@ async def _chat_once(cfg, rid, caller, request, req, model_id, messages, tools): max_tokens=req.max_tokens, stop=req.stop, tools=tools, tool_choice=tool_choice, extra=req.upstream_extra() or None, - session_id=_upstream_session(req.conversation_id, caller, getattr(request.state, "key_token", None)), + session_id=_upstream_session(req.conversation_id, caller, + getattr(request.state, "key_token", None), + _inbound_session(request)), ) ok = True break @@ -1997,7 +2036,9 @@ def _stream_response(request, req, model_id, messages, tools): max_tokens=req.max_tokens, stop=req.stop, tools=tools, tool_choice=req.tool_choice, extra=req.upstream_extra() or None, - session_id=_upstream_session(req.conversation_id, caller, getattr(request.state, "key_token", None)), + session_id=_upstream_session(req.conversation_id, caller, + getattr(request.state, "key_token", None), + _inbound_session(request)), ) async for chunk in stream_gen: if chunk.get("done"): diff --git a/tests/test_gateway.py b/tests/test_gateway.py index a615146..c28d06a 100644 --- a/tests/test_gateway.py +++ b/tests/test_gateway.py @@ -5473,6 +5473,92 @@ def test_metrics_record_tokens_breakdown_accumulates(): assert t["cached"] <= t["prompt"] and t["reasoning"] <= t["completion"] +def test_upstream_session_priority_and_account_isolation(): + """第三十五轮:上游会话 id 的取值优先级 + 账号隔离。 + + ① 入站 `x-opencode-session` 优先(客户端最清楚哪几次算同一个会话); + ② 没带才依次回退 conversation_id → API Key → 账号; + ③ 带了客户端会话时仍**按账号哈希** —— 否则两个账号用同一个值就会共用上游缓存作用域 + (第二十六轮定下的账号隔离被绕过)。 + """ + import hashlib + import app.main as m + + h = lambda x: hashlib.sha256(x.encode("utf-8")).hexdigest()[:32] # noqa: E731 + + # ① 客户端显式会话优先,且不受 conversation_id 影响 + a = m._upstream_session(None, "acct", "tok", "conv-abc") + b = m._upstream_session("conv-xyz", "acct", "tok", "conv-abc") + assert a == b, "带了入站会话头时不该再被 conversation_id 改写" + assert a == h("s:acct:conv-abc"), a + # ③ 同值不同账号必须隔离 + assert a != m._upstream_session(None, "other", "tok", "conv-abc"), "账号隔离不能绕过" + # ② 没带则按原优先级回退 + assert m._upstream_session("c1", "acct", "tok") == h("acct:c1") + assert m._upstream_session(None, "acct", "tok") == h("k:tok") + assert m._upstream_session(None, "acct", None) == h("u:acct") + # 都稳定(缓存要靠它),且都是 32 位十六进制 + for v in (a, m._upstream_session("c1", "acct", "tok"), m._upstream_session(None, "acct", None)): + assert len(v) == 32 and all(c in "0123456789abcdef" for c in v), v + + +def test_inbound_opencode_session_header_reaches_upstream(): + """第三十五轮端到端:入站的 `x-opencode-session` 真的决定了发给上游的会话 id。 + + - 同一个头 → 稳定(缓存前提); + - 换头 → 换会话; + - 不带头 → 回退到 Key 派生(结果与带头不同); + - 非法头(非 ASCII / 过长)→ 丢弃并回退,绝不把脏值带去上游。 + """ + from fastapi.testclient import TestClient + import app.main as m + + seen: list[str | None] = [] + + class FakeAdapter: + async def chat_stream(self, model=None, messages=None, session_id=None, **kw): + seen.append(session_id) + yield {"id": "c1", "choices": [{"index": 0, "delta": {"content": "hi"}}]} + yield {"done": True} + + orig = m._get_adapter + m._get_adapter = lambda model_id, timeout=None, cfg=None: ( + FakeAdapter(), "agnes", m._cfg().providers["agnes"]) + body = {"model": "agnes-3.0-flash", "messages": [{"role": "user", "content": "hi"}], + "stream": True} + try: + client = TestClient(m.app) + + def run(headers): + with client.stream("POST", "/v1/chat/completions", headers=headers, json=body) as r: + assert r.status_code == 200, r.read() + "".join(r.iter_text()) + + run({"x-opencode-session": "conv-A"}) + run({"x-opencode-session": "conv-A"}) + run({"x-opencode-session": "conv-B"}) + run({}) + run({"x-opencode-session": "x" * 500}) # 过长(ASCII)→ 丢弃并回退 + assert len(seen) == 5, seen + assert seen[0] == seen[1], "同一个入站会话头必须映射到稳定的上游会话" + assert seen[0] != seen[2], "换会话头应换上游会话" + assert seen[0] != seen[3], "带了会话头就不该再用 Key 派生" + assert seen[4] == seen[3], "过长会话头应等同没带(回退到派生)" + assert all(isinstance(x, str) and len(x) == 32 for x in seen), seen + + # 非 ASCII 值在 HTTP 层就发不出去(httpx 直接拒),所以用桩验门口的校验: + class _S: + rid = "t" + + class _Req: + headers = {"x-opencode-session": "中文会话"} + state = _S() + + assert m._inbound_session(_Req()) is None, "非 ASCII 会话头必须被丢弃(不能带进上游 header)" + finally: + m._get_adapter = orig + + # 直接运行(非 pytest)—— 必须留在文件末尾,见上方 `test_image_request_goes_to_requested_model` # 之前的旁注:运行器只会收集执行到这一行时已经存在的 globals。 if __name__ == "__main__":