TypeLLM 是一个为大模型提供类型安全生成（type-safe generation）的开源框架：模型仍保留原生推理与自由生成能力，最终输出却严格符合 JSON Schema。它的思考模式（thinking mode）更进一步，让你为每个字段单独设置 thinking 预算，或用"thinking": "auto"让模型按每次请求的难度自动选择推理强度——简单字段直接作答，复杂字段才"深想"。

30 秒看懂：为什么需要"按字段思考"

TypeLLM 的思考默认是关闭的。开启后，只有声明了思考的字段会先推理、再给出受约束的正式答案，而且多个需要思考的字段会并行推理，互不等待。

上图是 examples/receipt/ 中的收据解析演示：一次generate()调用里，多个字段按依赖关系分层执行。把思考加进来后，你可以只让"金额计算""是否符合报销政策"这类字段思考，而"商户名""发票号"等字段依旧即时回答——思考成本只花在真正需要它的地方。

第一步：用 thinking 与 thinking_budget 设置每个字段的推理预算

在字段定义里加两个键即可（来自 README.md）：

"policy_ok": { "type": "boolean", "instructions": "Does it meet the travel policy?", "thinking": True, # 开启该字段的思考 "thinking_budget": 1024, # 推理 token 上限 }

三个关键行为：

• 预算是上限：thinking_budget封顶该字段的推理 token 数；不设置时，字段可能一直推理到模型上下文用满；
• 到点强制收尾：当推理触及预算，TypeLLM 会强制关闭思考块，直接进入类型受约束的正式答案阶段（强制收尾逻辑见 typellm/sglang.py，协议标记定义在 typellm/protocol.py）；
• 可观测：response.thinking记录每个思考过字段的推理文本，response.usage.thinking_tokens统计本次调用消耗的推理 token。

第二步：用 thinking_effort 按档位设置思考预算

手动拍一个 token 数总觉得随意？TypeLLM 提供四档思考强度，在 typellm/schema.py 中定义：

用法是把thinking换成档位声明：

"total": {"type": "number", "thinking_effort": "medium"}

档位的官方校验逻辑（typellm/schema.py）会确保："none"严格不产生推理，其余档位思考 token 数不超过档位上限。仓库中的 GPU 回归测试 evals/thinking_effort_gpu/results/summary.json 显示 17 组调用全部符合"该想的想、不该想的不想"（think_ok: 17/17）。

第三步：用 "thinking": "auto" 实现智能推理

不想给每个字段估难度？直接把字段写成：

"policy_ok": { "type": "boolean", "instructions": "Does it meet the travel policy?", "thinking": "auto", }

"auto"的工作方式（编译逻辑见 typellm/schema.py）：

1. 在字段自己的依赖结果就绪后，TypeLLM 先插入一个隐藏的难度评估问题，让模型在不思考的前提下判断该字段需要none / low / medium / high哪一档；
2. 然后按选中的档位回答该字段，字段自身的 prompt 保持不变；
3. response.thinking_effort会报告每个"auto"字段实际拿到的档位。

真实 GPU 测试（evals/thinking_effort_gpu/run.py，Qwen3.8-27B）中四个字段的选择非常符合直觉：

也就是说，提取题一分推理都不花，计算题给足 medium，难题直接拉满 high。

配置禁忌：哪些参数不能混用

Schema 校验（typellm/schema.py）会抛SchemaError拦截错误组合，记住三条即可：

• "thinking": "auto"不能与thinking_effort或thinking_budget同时出现——auto 会自己选档位；
• thinking_effort与thinking_budget二选一，都指定预算会报错；
• thinking: false与thinking_effort: "high"这类自相矛盾的写法也会被拒绝。

另外，数组项（array items）的属性不支持thinking、depends_on等高级选项；思考能力作用于字段级。

实测效果：开启思考后准确率提升多少

在 evals/jevbench/ 的 231 道公开 JevBench 任务上（Qwen3.8-27B，同一检查点、不做微调），思考模式把准确率从84.42%（195/231）提升到 98.70%（228/231）：

代价是延迟：P50 请求耗时从约 1.3 秒升到约 6.7 秒（明细见 evals/jevbench/README.md）。所以预算档位本质上是**"准确率 × 延迟"的旋钮**。

上手建议：什么时候开、开多大

• ✅ 字段答案直接写在上下文里 → 不思考或"none"，省 token 省延迟；
• ✅ 需要计算、核对政策、综合多字段结论 →thinking_effort: "medium"起步；
• ✅ 不确定难度、批量字段混合难度 → 用"thinking": "auto"交给模型自评；
• ⚠️ 不设thinking_budget也不设档位时，推理可能直到上下文用满，生产环境建议始终给预算或档位兜底；
• ⚠️ 强制收尾保证"总能给出类型合法的最终答案"，但它不保证答案语义正确——复杂题请配合return_probabilities与confidence审查低置信结果。

想亲手体验，可以从 examples/receipt/receipt.py 入手：加一个--thinking参数即可对比同一张收据在有/无思考下的提取结果（输出分别为 result.json 与 result_thinking.json）。