docs: correct the equivalence claim T2 disproved

2026-09-05 00:48:01 -04:00
parent 7fabc792b2
commit 3cb5331950
2 changed files with 11 additions and 2 deletions
@@ -156,7 +156,16 @@ request.reasoning_effort > source.reasoning_effort > source.enable_thinking(语
 | 旧写法 | 等价于 |
 |---|---|
 | `enable_thinking=False` | `reasoning_effort=Effort.NONE` |
-| `enable_thinking=True` | `reasoning_effort=Effort.AUTO`(注入 `on_base`,不附档位)——与旧行为逐字节等价,且不依赖能力表 |
+| `enable_thinking=True` | `reasoning_effort=Effort.AUTO`(注入 `on_base`,不附档位),不依赖能力表 |
+
+**`True` 的等价性分两种**(2026-09-04 实现时发现,更正初稿「与旧行为逐字节等价」的说法):
+
+| provider 类型 | 旧 `thinking_on` | 新 `AUTO` 注入 | 是否等价 |
+|---|---|---|---|
+| `on_base` 完整表达「开」(qwen/deepseek/zhipu/moonshot) | `{"enable_thinking": True}` 等 | 同左 | **逐字节等价** |
+| 靠档位表达「开」(minimax/openai/anthropic/google) | `{"reasoning_effort": "medium"}` | `{}`(不注入) | **行为变更** |
+
+后者是**有意的**: 旧版那个 `medium` 是库替下游做的档位判断(profile 注释自己承认「取 medium 是因为它是五档里语义最接近厂商正常强度的一档」),而 `medium` 在 GLM/kimi/deepseek 的档位表里根本不存在——正是本设计要消灭的东西。语义仍是「开」(这些模型默认即推理),只是不再强制一个档;要指定强度请显式配 `REASONING_EFFORT`。须进 CHANGELOG 的行为变更条目。
 | `enable_thinking=None` | 不表态 |

 **同源同时配 `enable_thinking` 与 `reasoning_effort` 且语义矛盾**(如 `True` + `none`)→ **构造期 `ValueError`**。不做「后者赢」的静默兜底: 两个字段表达同一件事时,矛盾是配置错误,不是优先级问题。