引言

过去一个月，我连续写了两篇决策模型的文章：Jev vs Laya 对比了闭源的 Jev 和开源的 Laya，Microsoft-Decision-1 详解 又加入了微软。写完之后，被问得最多的问题是：能不能自己训练一个？

答案是可以，而且门槛比想象中低。看看第三方榜单 JevBench 就知道：截至 10 月中旬，开源权重榜上已经有 160 多个参与排名的系统，绝大多数出自社区和中小团队之手。排在前面的也不神秘：综合分第一的 H2O-Lightning-4B 是在阿里开源的 Qwen3.5-4B 上微调出来的，能力分第一的 Quyet-1.0-Large 则是 Gemma-4-31B 加一个适配器；微软的 Microsoft-Decision-1，底座同样是开源的 Qwen3.5-9B。

这说明一件事：决策模型的核心竞争力不在模型结构，而在数据、训练目标和评测体系。 这三样东西，普通团队完全可以自己掌握。

本文按一个真实项目的顺序，把训练一个“自己的 Jev”的全过程走一遍：

1. 原理：决策模型到底在学什么，为什么训练目标必须是“严格适当评分规则”
2. 数据：去哪里找，怎么统一格式、清洗、增强和切分
3. 算力：需要多少显存、多少 GPU 小时、多少钱
4. 底座：怎么选基础模型
5. 训练：从零写一套可以直接运行的 LoRA 训练脚本
6. 评测：用哪些指标打分，怎么和 JevBench 上的模型同场比较
7. 调优：分数不理想时，按什么思路改进

文中的脚本我都在 Qwen3.5-0.8B 上实际跑通过（CPU 冒烟测试，只用来验证代码正确性），文中引用的榜单和模型数据均来自公开资料，链接列在文末。

一、先想清楚：决策模型到底在学什么

1. 本质是一个“条件概率”

先回顾一下决策模型的接口：调用方给出一段状态（state）和一个问题，问题的候选答案由调用方提前定义好，模型返回每个候选答案的概率。三种问题原语都可以统一成同一件事：

所以，训练一个决策模型，就是让模型学会估计 P(选项 | 状态, 问题)。和普通的文本分类模型相比，它有两个关键区别：

• 类别不是固定的：每次请求的问题和选项都不一样，模型必须读懂选项的含义，而不是记住一组固定的标签。这就是它需要“零样本泛化”能力的原因。
• 概率本身就是产品：下游程序会直接拿概率做 if 判断，所以概率必须“诚实”，也就是校准过的。这决定了训练目标的选择，后面会专门讲。

2. 三条技术路线

目前社区的做法大致分成三类：

JevBench 的数据给出了很清楚的信号：

• 几个编码器路线的系统，零样本智能分都只有个位数（Laya 1.8、modernbert-jev v2 2.6、open-jev-deberta-v3-large 2.8），和随机猜测差不多；
• 完全不做决策微调、直接读取 Qwen3-4B-Instruct-2507 的 logits，智能分就有 34.0；
• 在 Qwen3.5-4B 上做过决策微调的 H2O-Lightning-4B 达到 60.0，接近 Jev 1.13.0 的 63.6；
• 更大的 Gemma-4-31B 底座（Quyet-1.0-Large）达到 73.4。

结论很明确：如果目标是 Jev 那样的“零样本通才”，应该走解码器路线，大模型预训练时学到的知识是零样本能力的来源，决策微调则把这些知识“对齐”到选项概率上；如果只服务一两个固定任务，对延迟要求极高，而且有足够的标注数据，Laya 这样的编码器路线依然是性价比最高的选择。

本文的主线是第二条路线：解码器 + 选项字母。它的推理过程是这样的：

1. 把状态、问题和带字母编号的选项拼成一段对话提示词，以助手回复的开头结束；
2. 模型做一次前向计算（只有预填充，没有逐 token 生成）；
3. 在最后一个位置（答案位）取出 A、B、C……这几个字母 token 的 logits，只在这 K 个 logits 上做 softmax，得到每个选项的概率。

H2O-Lightning-4B 的模型卡把这概括为“一次前向，一个输出 token”（one forward pass and one output token）。因为不生成文本，成本几乎只有输入 token；又因为输出空间被限定在 K 个字母上，模型不可能答出选项以外的东西。这条路线还有一个先天优势：大模型在选择题格式下给出的字母概率，本身就有不错的校准性（Kadavath 等人，2022），决策微调是在一个好的起点上继续打磨。

3. 训练目标：为什么必须是“严格适当评分规则”

决策模型输出的概率要直接进入程序的分支判断，所以我们要的不只是“答对”，还要校准：在所有给出 80% 把握的回答里，应该恰好有大约 80% 是对的。

第一个坑：只奖励“答对”会毁掉校准。 假设一道题的真实分布是 p（比如 70% 选 A、30% 选 B），模型报告的分布是 q。如果把模型当成策略，按 q 抽一个答案，答对得 1 分，期望奖励就是 Σ p_k · q_k，它对 q 是线性的，最优解是把全部概率押在最可能的选项上，也就是让 A 的概率等于 1。模型被训练成“永远 100% 确定”，准确率没变，概率却失去了意义。

解决办法是用严格适当评分规则（strictly proper scoring rule）做目标。 它的定义是：只有当模型报告的分布 q 等于真实分布 p 时，期望得分才能达到最大值，说真话是唯一的最优策略（经典论述见 Gneiting 和 Raftery 2007 年的论文）。常用的有四种：

记 q = (q_1, …, q_K) 为模型给出的分布，y 为标签（one-hot 或软标签）

对数评分（越大越好）     S_log(q, y) = Σ y_k · log q_k            就是负的交叉熵
Brier 分数（越小越好）   B(q, y)     = Σ (q_k − y_k)²
球面评分（越大越好）     S_sph(q, y) = Σ y_k · q_k / ‖q‖          取值 0～1，梯度比对数评分温和
排序概率分（越小越好）   RPS(q, y)   = Σ (Q_i − Y_i)² / (K − 1)   Q、Y 是累积分布，用于有序的 score

这里有一个经常被忽略的事实：交叉熵本身就是严格适当的（它就是对数评分）。那为什么用交叉熵训练出来的神经网络普遍过度自信？原因不在损失函数，而在于有限的训练数据：模型会把训练样本“背”下来，把它们的概率推向 1，到了没见过的数据上，自信程度就高于实际准确率（Guo 等人 2017 年的论文对此有系统的分析）。所以有两点要做到：

1. 训练时：用严格适当评分规则做目标；标签本身有不确定性时（标注员意见不一、多个教师模型投票不一致），用软标签代替 one-hot，让模型学会“诚实地不确定”；不要训练过多 epoch。
2. 训练后：在留出的开发集上做温度缩放（temperature scaling），即 p = softmax(z / T)，按问题类型拟合一个温度 T。它不改变排序，所以不影响准确率，只修正自信程度。

温度缩放的效果往往非常明显。Laya 的出厂检查点按“问题类型 × 选项数”重新拟合温度后，平均 ECE（期望校准误差）从 0.466 降到了 0.081。而 H2O-Lightning-4B 随模型发布的温度是 choice 0.75、noul 0.8、score 0.65，都小于 1，说明它的原始输出反而偏保守，需要“锐化”。方向因模型而异，只能实测，不能拍脑袋。

4. RLCD：Laya 公开的强化学习做法

Jev 把自己的训练方法称为 RLCD（Reinforcement Learning for Calibrated Decisions，面向校准决策的强化学习），但没有公开细节。Laya 沿用了这个名字，并公开了一个具体实现：

• 奖励：三种严格适当评分的组合，Reward = S_log + 0.5 × S_sph − RPS，其中 RPS 只对有序的 score 题生效；
• 探索：每道题对 logits 加 8 组高斯噪声（噪声在选项维度上减去均值，因为给所有 logits 加同一个常数不会改变 softmax），噪声的标准差从 1.0 逐步衰减到 0.3；
• 优势：8 个样本的奖励减去组内均值、除以组内标准差，和 GRPO 的组内基线是同一个思路（GRPO 的原理可以参考我之前写的 PPO vs GRPO）；
• 更新：用高斯分布的对数密度做 REINFORCE 式的策略梯度，完全不使用交叉熵损失。

我的理解是：当模型直接输出完整的概率分布时，评分规则本身就是可微的，直接对它求梯度（也就是把评分规则当损失函数）和用强化学习去估计这个梯度，在期望上指向同一个方向，前者方差更小、更省事。 强化学习的形式真正不可替代的场景，是奖励无法对输出直接求导的时候，比如奖励来自多步 Agent 任务最终是否成功、用户的真实反馈，或者 Laya 处理的多轮销售对话：奖励是对话最终是否成交，需要用 TD(λ) 把这个结果分摊到每一轮。

为了验证这个判断，我用后文训练脚本里的 reward() 函数做了两个小实验：一是把目标分布设为 [0.7, 0.2, 0.1]，直接对组合评分做梯度上升，模型输出的分布最终收敛到 [0.7, 0.2, 0.1]，说明这个组合评分确实“只奖励说真话”；二是对同一组 logits，用 RLCD 的方式（2 万组扰动，σ = 0.05）估计梯度，它和直接求导得到的梯度方向几乎完全一致（余弦相似度 0.999）。

所以本文的训练脚本两种都支持：默认直接优化评分规则（--objective proper），也可以切换成 Laya 式的 RLCD（--objective rlcd），自己对比。

5. 从概率到动作：阈值由代价决定

概率校准好之后，“什么时候自动执行、什么时候转人工”就不必拍脑袋了。Laya 给它的 Act / Escalate 头设计了一个代价矩阵：判对 +1，判错 −3，转人工 −0.5。自动执行的期望收益是 p × 1 + (1 − p) × (−3)，它大于 −0.5 的条件是 p > 0.625。一般地：

自动执行的阈值 = (转人工的收益 − 判错的收益) / (判对的收益 − 判错的收益)
              = (−0.5 − (−3)) / (1 − (−3)) = 0.625

只要概率是校准的，这个阈值可以直接从业务代价算出来，单独训练一个“该不该执行”的头反而不是必需的（Laya 的 README 也坦承它的 Act 头目前几乎没有信号，建议直接用置信度做门控）。H2O-Lightning-4B 在 3474 道留出题上给出了阈值的实际效果：

这张表就是你训练完之后要为自己的模型画出来的东西。

6. 全流程一览

把上面的原理落到工程上，一个完整的训练项目大致是这样的循环：

① 定义题目和验收标准：指标、阈值、上线门槛，先写下来再看结果
        │
② 找数据 → 统一格式 → 去重、去污染 → 按任务切分
        │
③ 零样本基线：直接读底座模型的选项字母概率，先知道起点在哪里
        │
④ LoRA 微调：选项随机乱序 + 严格适当评分规则（或 RLCD）
        │
⑤ 在开发集上拟合温度，在留出任务、公开集和私有封存集上打分
        │
⑥ 按切片做误差分析 → 补数据 → 回到 ④
        │
⑦ 合并权重，接入 /v1/systemone 接口，灰度上线，持续监控

接下来按这个顺序逐一展开。

二、数据：从哪里找，怎么准备

数据决定了决策模型的上限。H2O-Lightning-4B 在模型卡里总结的几条经验，几乎都和数据有关：留一份从不参与训练的封存评测集、上线标准先写下来再看结果、训练数据和所有评测集做精确和近似去重、按主题和题型找短板再补数据、标签只来自人工标注或多个独立强模型的一致意见。

1. 数据从哪里来

几个经验值得参考：

• Laya 坚持“零合成”：训练数据全部来自人工标注的公开数据集（客服意图、自然语言推理、内容安全、越狱与注入、评分细则打分、多轮对话结果等），理由是用模型生成的标签训练校准模型，只会把模型校准到“老师”的错误上。
• H2O-Lightning-4B 的数据配比：按场景分，文档、政策与规则 37%，数字、日期与概率 22%，游戏与模拟 12%，日常语言与知识 10%，客服与运营 10%，安全与护栏 7%，代码与工具调用 2%；按题型分，choice 54%、noul 29%、score 16%；超过 99% 是英文。训练分三个阶段：先广泛覆盖，再集中强化长文档和数字推理，最后把所有类型重新混合。
• 任务的多样性比单个任务的样本量更重要：FLAN 系列研究发现，指令微调时覆盖的任务种类越多，模型在没见过的任务上表现越好，这一点对决策模型同样成立。在总量相同的情况下，覆盖更多不同的任务，通常比在少数几个任务上堆样本更有利于零样本泛化。

如果只是做某个垂直领域的专用模型，几千到几万条高质量标注就能有明显提升：Laya 的 typed-decisions 检查点用约 3 万道题微调，准确率从 0.362 提升到 0.766；社区有人用单张 16 GB 显卡把 Laya 微调成浏览器 Agent 的操作决策器，约 45 个候选元素中选对目标的比例从 0.10 提升到 0.66。

2. 统一的数据格式

建议直接沿用 Jev 的请求格式，每行一道决策题：

{"task": "ticket_routing", "state": "Checkout returns HTTP 500 for every customer since 09:10.",
 "question": {"type": "choice", "instructions": "Which team should handle this ticket?",
              "criteria": {"billing": "Charges, invoices and refunds",
                           "engineering": "Bugs, errors and outages",
                           "support": "How-to and account questions"}},
 "answer": "engineering"}
{"task": "refund_check", "state": {"subject": "Charged twice", "body": "Please refund the duplicate."},
 "question": {"type": "noul", "instructions": "Does the customer ask for a refund?",
              "criteria": {"true": "yes, a refund is requested", "false": "no refund is requested"}},
 "answer": true}
{"task": "urgency", "state": "Payroll export fails and payroll runs today.",
 "question": {"type": "score", "instructions": "How urgent is this request?",
              "criteria": ["not urgent", "soon", "today", "blocking right now"]},
 "answer": 2}
{"task": "intent_soft", "state": "I was billed twice and the app keeps crashing.",
 "question": {"type": "choice", "instructions": "What is the main topic?",
              "criteria": {"billing": "payments", "technical": "bugs"}},
 "target": {"billing": 0.6, "technical": 0.4}}

几点约定：

• 为了便于阅读，上面的示例做了换行，实际文件中每条记录占一行（JSONL）；
• answer 对 choice 是选项名，对 noul 是布尔值，对 score 是等级下标；有不确定性的样本用 target 给出软标签；
• task 字段记录样本来自哪个任务，后面切分和按切片分析都要用到；
• 这个格式和 JevBench 公开题集的格式几乎一致（它用 expected 字段存答案），后面的评测脚本可以直接读取 JevBench 的公开题。

3. 清洗与增强

清洗要做三件事：

1. 去重：先做规范化后的精确去重，再用 MinHash 之类的方法做近似去重，避免同一条数据换个标点就出现好几遍；
2. 去污染：把所有评测集（自己的封存集、JevBench 公开题等）都和训练集做比对，有重叠的从训练集里删掉。JevBench 要求在公开题上训练过的模型必须主动声明，而且公开题成绩明显高于封存题的模型还会被扣分，“刷”公开题没有意义；
3. 配平：给每个任务设上限，防止某个大数据集主导训练；同时控制题型、语言、选项数的分布。

增强的目标是让模型学会“看内容，而不是看形式”：

要注意顺序：先切分，再增强，而且增强只作用于训练集，否则同一道题的不同变体会同时出现在训练集和评测集里，评测分数就虚高了。

4. 切分：一定要按“任务”留出

决策模型最重要的能力是泛化到没见过的问题，所以评测集要分层次：

真实项目里，每种题型下面都应该有多个任务，留出整个任务之后，训练集里仍然有同题型的其他任务。

下面是一个最小的数据准备脚本，把 Banking77（意图，choice）、BoolQ（是否题，noul）、SST-5（情感，score）和 OCNLI（中文推理，choice）四个公开数据集改写成决策题，完成去重、去污染和按任务切分：

# prepare_data.py
"""Turn a few public datasets into decision records, remove duplicates and eval overlap, split by task."""
import hashlib
import json
import random
from pathlib import Path

from datasets import load_dataset

random.seed(13)
SST5_LEVELS = ["very negative", "negative", "neutral", "positive", "very positive"]
OCNLI = {"entailment": "前提为真时，假设一定为真",
         "neutral": "前提为真时，假设可能为真也可能为假",
         "contradiction": "前提为真时，假设一定为假"}


def banking77():
    ds = load_dataset("mteb/banking77", split="train")
    intents = sorted(set(ds["label_text"]))
    for row in ds:
        # 77 intents do not fit 26 letters: show the gold intent among 9 random distractors
        shown = random.sample([i for i in intents if i != row["label_text"]], 9) + [row["label_text"]]
        random.shuffle(shown)
        yield {"task": "banking77", "state": row["text"],
               "question": {"type": "choice",
                            "instructions": "Which banking intent does the customer's message express?",
                            "criteria": {i: i.replace("_", " ") for i in shown}},
               "answer": row["label_text"]}


def boolq():
    for row in load_dataset("google/boolq", split="train"):
        yield {"task": "boolq", "state": row["passage"],
               "question": {"type": "noul", "instructions": row["question"].capitalize() + "?",
                            "criteria": {"true": "yes, according to the passage",
                                         "false": "no, according to the passage"}},
               "answer": row["answer"]}


def sst5():
    for row in load_dataset("SetFit/sst5", split="train"):
        yield {"task": "sst5", "state": row["text"],
               "question": {"type": "score", "instructions": "How positive is this movie review?",
                            "criteria": SST5_LEVELS},
               "answer": row["label"]}


def ocnli():
    ds = load_dataset("clue/clue", "ocnli", split="train")
    names = ds.features["label"].names
    for row in ds:
        if row["label"] >= 0:  # -1 marks unlabeled rows
            yield {"task": "ocnli", "state": {"前提": row["sentence1"], "假设": row["sentence2"]},
                   "question": {"type": "choice", "instructions": "假设和前提是什么关系？", "criteria": OCNLI},
                   "answer": names[row["label"]]}


def key(record):
    text = json.dumps([record["state"], record["question"]["instructions"]], ensure_ascii=False)
    return hashlib.sha1(" ".join(text.lower().split()).encode()).hexdigest()


def write(path, rows):
    with open(path, "w", encoding="utf-8") as f:
        f.writelines(json.dumps(r, ensure_ascii=False) + "\n" for r in rows)


def main():
    held_out_tasks = {"banking77"}  # whole tasks never trained on (choice is still covered by ocnli)
    banned = {key(json.loads(line)) for p in Path("eval").glob("*.jsonl")
              for line in open(p, encoding="utf-8")}  # JevBench public files, your lockbox, ...
    seen, train, dev, held_out = set(), [], [], []
    for source in (banking77, boolq, sst5, ocnli):
        rows = list(source())
        random.shuffle(rows)
        for r in rows[:20000]:  # cap every task so no single dataset dominates the mix
            k = key(r)
            if k in seen or k in banned:
                continue
            seen.add(k)
            if r["task"] in held_out_tasks:
                held_out.append(r)
            elif random.random() < 0.05:
                dev.append(r)
            else:
                train.append(r)
    random.shuffle(train)
    Path("data").mkdir(exist_ok=True)
    write("data/train.jsonl", train)
    write("data/dev.jsonl", dev)
    write("data/heldout_tasks.jsonl", held_out)
    print(f"train {len(train)}  dev {len(dev)}  held-out tasks {len(held_out)}")


if __name__ == "__main__":
    main()

把 JevBench 的公开题文件和自己的封存集放进 eval/ 目录后运行，就会得到 data/ 下的三个文件。我实际运行的结果是：训练集 36,044 条，开发集 1,917 条，留出任务（Banking77）9,993 条。这只是一个演示，真正的项目需要几十到几百个任务，但流程完全一样：每加一个数据源，就是再写一个这样的转换函数。

三、GPU 资源：到底需要多少卡

1. 显存怎么估

训练时的显存主要由三部分组成：模型权重、梯度和优化器状态、激活值。前两部分可以按“每个参数占多少字节”来估：

按这个规则，不含激活值的显存大约是：

激活值和 batch 大小、序列长度成正比。开启梯度检查点后，主要剩下每一层边界的隐状态：以 Qwen3.5-4B（32 层，隐藏维度 2560）为例，一条 4K token 的样本约 32 × 4096 × 2560 × 2 字节 ≈ 0.7 GB，batch 为 4 时约 3 GB，再加上单层重算的峰值和 CUDA 自身的开销。所以 4B 模型做 LoRA，单张 24 GB 的卡通常就能跑（序列在 4K 以内、batch 不大的情况下），80 GB 的卡则可以放开 batch 和序列长度。

这里有一个决策模型特有的大坑：语言模型头的 logits。Qwen3.5 的词表有 248,320 个 token，如果像普通 SFT 那样对每个位置都算 logits，一条 4K token 的样本光 fp32 的 logits 就要 4096 × 248320 × 4 字节 ≈ 4 GB，反向传播时还要再来一份。而决策模型只需要最后一个位置的 logits，前向时传入 logits_to_keep=1，这部分就只剩 1 MB 左右。后面的训练脚本就是这么做的。

2. 时间怎么估

训练的计算量可以用一个经验公式估算：每个训练 token 约 6 × 参数量 次浮点运算（LoRA 加梯度检查点：前向 2N、重算 2N、反向 2N；全参微调加梯度检查点约为 8N）。举个例子，用 Qwen3.5-4B 做 LoRA，20 万道题、平均每题 600 token、训练 2 个 epoch：

训练 token 数  ≈ 200,000 × 600 × 2 = 2.4e8
训练计算量    ≈ 6 × 4e9 × 2.4e8 ≈ 5.8e18 FLOPs
H100 实际吞吐 ≈ 989 TFLOPS（bf16 稠密峰值）× 35% 利用率 ≈ 350 TFLOPS
训练时间      ≈ 5.8e18 / 3.5e14 ≈ 16,500 秒 ≈ 4.6 小时

同样的任务在 A100 上大约要 3 倍时间。实际利用率和序列长度、padding 比例、算子实现都有关系，要以自己的 profiler 数据为准。Qwen3.5 是“Gated DeltaNet 线性注意力 + 门控全注意力”的混合架构，训练前一定要装上 flash-linear-attention 和 causal-conv1d，否则会退回到纯 PyTorch 实现，慢很多（加载模型时会打印提示）。

3. 推荐配置

成本方面，按 H100 按需价格每小时 2～3 美元估算（JevBench 的 GPU 成本计算器默认按 H100 PCIe 每小时 2.89 美元），一次 4B 的 LoRA 训练大约 15 美元。真正花钱的是迭代：一个项目通常要跑几十轮“改数据、重训、评测”，GPU 总花费在几百美元量级。算力不是最贵的，数据和评测才是。

部署的成本更低：H2O-Lightning-4B 的 bf16 权重约 9.1 GB，在一张 32 GB 的 RTX PRO 4500 上用 vLLM 服务，标准题单次判断的 p50 约 30 ms；按 JevBench 计算器的估算，在 RTX 5090 上自托管，每千次决策约 0.008 美元，大约是 Jev 在 JevBench 上实测成本（每千次 0.032 美元）的四分之一。

四、基础模型怎么选

1. 选择标准

1. 零样本底子：优先选指令版（经过对齐的对话模型），它们本来就会做选择题，起点高；Base 版需要更多数据才能追上。JevBench 专门放了几个“底座对照组”（不做任何决策微调，直接读 logits），能直接看出不同底座的起点。
2. 语言：中文场景优先考虑 Qwen；注意 H2O-Lightning-4B 的训练数据 99% 以上是英文，直接拿来处理中文要先自测。
3. 尺寸与延迟：决策模型的定位是几十毫秒级的快速判断，4B 左右是目前延迟、成本和能力的甜点。
4. 上下文长度：JevBench 里有 23 道 7.7 万～8.1 万 token 的超长题，Jev 和不少模型因为超出上下文而拒答，按答错计分。Qwen3.5 原生支持 262K，但序列越长，训练的显存和时间成本上涨得越快。
5. 许可证：Qwen3.5 全系列、Gemma 4、ModernBERT 都是 Apache 2.0，mmBERT 是 MIT，商用比较省心。
6. 生态：训练要有 Transformers 和 PEFT 支持，部署要有 vLLM、SGLang、llama.cpp 支持；另外，选项字母必须各自是一个独立的 token（训练脚本里有断言检查）。

2. 候选清单

3. 我的建议

• 起步用 Qwen3.5-4B（指令版）+ LoRA：中文能力好，社区已经证明它能做到接近 Jev 的水平，单卡就能训练和部署；
• 先在 0.8B / 2B 上把流程跑通：数据格式、评测脚本、阈值策略都在小模型上验证完，再换大底座，可以省掉大量试错成本；
• 想冲击更高的能力分，再上 9B 到 31B：收益是真实的（Quyet-1.0-Large 的智能分比 H2O-Lightning-4B 高 13 分以上），但训练和推理成本也会成倍增加；
• 使用 Qwen3.5 时关闭思考模式：它默认会先输出思考过程，构造提示词时要传 enable_thinking=False，让助手回复的第一个 token 就是答案字母。

五、训练脚本：一步步写出来

这一节给出一套完整、可以直接运行的代码。它刻意保持精简，没有依赖任何专门的训练框架，方便读懂每一步在做什么。

1. 准备环境

pip install torch transformers peft accelerate datasets fastapi uvicorn
# GPU 机器上再装 Qwen3.5 线性注意力层的加速算子
pip install flash-linear-attention causal-conv1d

项目结构如下：

my-jev/
├── prepare_data.py      # 数据准备（上一节）
├── decision_format.py   # 提示词渲染与一次前向打分，训练、评测、服务共用
├── train.py             # LoRA 训练
├── evaluate.py          # 打分测试与温度拟合
├── serve.py             # /v1/systemone 服务
├── eval/                # JevBench 公开题、自己的封存集
└── data/                # prepare_data.py 的输出

2. 共用模块：把一道题变成一次前向

训练、评测和线上服务必须用完全相同的提示词格式，否则训练出来的概率到了线上就不再准确。所以先把这部分抽成一个共用模块：

# decision_format.py
"""Shared by training, evaluation and serving: render a decision as a prompt and read option probabilities."""
import json
import string

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer

LETTERS = string.ascii_uppercase  # up to 26 options per question
SYSTEM = ("You are a decision model. Read the state and the question, "
          "then answer with the letter of exactly one option.")


def load(base, dtype=torch.bfloat16):
    tok = AutoTokenizer.from_pretrained(base)
    tok.padding_side = "left"  # every row then ends at its answer slot
    model = AutoModelForCausalLM.from_pretrained(base, dtype=dtype)  # Qwen3.5 loads text-only here
    ids = [tok.encode(c, add_special_tokens=False) for c in LETTERS]
    assert all(len(i) == 1 for i in ids), "every option letter must be a single token"
    return tok, model, torch.tensor([i[0] for i in ids])


def options(question):
    """[(key, description)] in the caller's order; noul is shown as yes / no."""
    kind, crit = question["type"], question.get("criteria")
    if kind == "noul":
        crit = crit or {}
        return [("yes", crit.get("true", "")), ("no", crit.get("false", ""))]
    if kind == "score":
        return [(str(i), desc) for i, desc in enumerate(crit)]
    return list(crit.items()) if isinstance(crit, dict) else [(c, "") for c in crit]


def target(record, opts):
    """Target distribution over opts: a soft label if the record has one, else one-hot."""
    keys = [k for k, _ in opts]
    if "target" in record:  # e.g. {"billing": 0.7, "technical": 0.3}
        dist = [float(record["target"].get(k, 0.0)) for k in keys]
    else:
        ans = record.get("answer", record.get("expected"))
        if record["question"]["type"] == "noul":
            ans = "yes" if ans in (True, "yes", "true") else "no"
        dist = [1.0 if k == str(ans) else 0.0 for k in keys]
    if sum(dist) <= 0:
        raise ValueError(f"answer is not one of the options: {record.get('id', record['question'])}")
    return [d / sum(dist) for d in dist]


def prompt(tok, record, order, max_state_tokens=6000):
    """Chat prompt whose next token is the answer letter; slot s shows option order[s]."""
    q, opts, state = record["question"], options(record["question"]), record["state"]
    if not isinstance(state, str):
        state = json.dumps(state, ensure_ascii=False, indent=1)
    ids = tok.encode(state, add_special_tokens=False)
    if len(ids) > max_state_tokens:  # cut the state, never the options or the answer slot
        state = tok.decode(ids[:max_state_tokens]) + "\n[truncated]"
    lines = [f"{LETTERS[s]}. {opts[i][0]}" + (f": {opts[i][1]}" if opts[i][1] else "")
             for s, i in enumerate(order)]
    user = (f"<state>\n{state}\n</state>\n\nQuestion ({q['type']}): {q['instructions']}\n"
            "Options:\n" + "\n".join(lines) + "\n\nAnswer with the letter of one option.")
    messages = [{"role": "system", "content": SYSTEM}, {"role": "user", "content": user}]
    return tok.apply_chat_template(messages, tokenize=False, add_generation_prompt=True,
                                   enable_thinking=False)


def option_logits(model, tok, letter_ids, prompts, ks, device):
    """One forward pass for a batch: logits of the shown option letters at the answer slot."""
    enc = tok(prompts, return_tensors="pt", padding=True, add_special_tokens=False).to(device)
    out = model(input_ids=enc.input_ids, attention_mask=enc.attention_mask, logits_to_keep=1)
    z = out.logits[:, -1, letter_ids[: max(ks)].to(device)].float()
    mask = torch.arange(z.shape[1], device=device)[None, :] < torch.tensor(ks, device=device)[:, None]
    return z.masked_fill(~mask, -1e4), mask

几个关键点：

• 左侧 padding：一个 batch 里的提示词长短不一，左侧补齐之后，每一行的最后一个位置都是答案位，配合 logits_to_keep=1，语言模型头只需要算一个位置。Qwen3.5 有线性注意力层，我专门验证过：同一道题单独计算和放进左侧补齐的 batch 里计算，logits 的最大差异只有 6×10⁻⁵；
• 只加载文本部分：Qwen3.5 是原生多模态模型，但用 AutoModelForCausalLM 加载时得到的是纯文本的 Qwen3_5ForCausalLM，不会带上视觉编码器，省显存，LoRA 也不会挂到视觉层上；
• 只在 K 个字母上做 softmax：取出 A、B、C……对应的 logits，多余的槽位填一个很小的值，模型的输出永远落在合法选项里；
• state 过长时只截断 state：问题、选项和答案位必须完整保留；
• noul 统一渲染成“yes / no”两个选项，返回的 P(yes) 就是 noul 的答案；score 的各个等级按顺序排列，便于计算 RPS；
• 断言每个字母都是单独的 token：换其他底座时，这一行能第一时间发现问题。在 Qwen3.5 的分词器上，A 到 Z 都是单个 token，而且在答案位后面追加一个字母，恰好多出一个 token。

3. 训练主脚本

# train.py
"""LoRA fine-tuning of a decision model with strictly proper scoring rules, or Laya-style RLCD."""
import argparse
import json
import math
import random

import torch
from accelerate import Accelerator
from peft import LoraConfig, get_peft_model
from torch.utils.data import DataLoader
from transformers import get_cosine_schedule_with_warmup

from decision_format import load, option_logits, options, prompt, target


def reward(z, mask, y, ordinal):
    """Laya's composite of strictly proper scores: log + 0.5 * spherical - RPS (RPS for score only)."""
    logq = z.log_softmax(-1)
    q = logq.exp()
    s_log = (y * logq).sum(-1)                      # log score = minus cross-entropy
    s_sph = (y * q).sum(-1) / q.norm(dim=-1)        # spherical score, bounded in [0, 1]
    k = mask.sum(-1).clamp(min=2)
    rps = ((q.cumsum(-1) - y.cumsum(-1)) ** 2).sum(-1) / (k - 1)  # ranked probability score
    return s_log + 0.5 * s_sph - ordinal * rps


def rlcd_loss(z, mask, y, ordinal, sigma, group=8):
    """Policy gradient over Gaussian-perturbed logits with a group-mean baseline, as Laya describes RLCD."""
    m = mask.float()
    eps = torch.randn(group, *z.shape, device=z.device) * m
    eps = (eps - eps.sum(-1, keepdim=True) / m.sum(-1, keepdim=True)) * m  # softmax ignores a common shift
    sample = z.detach() + eps
    with torch.no_grad():
        r = reward(sample, mask, y, ordinal)            # [group, batch]
        adv = (r - r.mean(0)) / (r.std(0) + 1e-6)
    logp = -(((sample - z) ** 2) * m).sum(-1) / (2 * sigma**2)  # Gaussian log-density up to a constant
    return -(adv * logp).mean()


class Collate:
    def __init__(self, tok, max_state_tokens):
        self.tok, self.max_state_tokens = tok, max_state_tokens

    def __call__(self, records):
        prompts, ks, ys, ordinal = [], [], [], []
        for r in records:
            opts = options(r["question"])
            order = list(range(len(opts)))
            if r["question"]["type"] != "score":  # score levels keep their order, RPS relies on it
                random.shuffle(order)
            y = target(r, opts)
            prompts.append(prompt(self.tok, r, order, self.max_state_tokens))
            ys.append([y[i] for i in order])
            ks.append(len(opts))
            ordinal.append(float(r["question"]["type"] == "score"))
        y = torch.zeros(len(records), max(ks))
        for row, t in enumerate(ys):
            y[row, : len(t)] = torch.tensor(t)
        return {"prompts": prompts, "ks": ks, "y": y, "ordinal": torch.tensor(ordinal)}


def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("--base", default="Qwen/Qwen3.5-4B")
    ap.add_argument("--train", default="data/train.jsonl")
    ap.add_argument("--out", default="out/my-jev")
    ap.add_argument("--objective", choices=["proper", "rlcd"], default="proper")
    ap.add_argument("--epochs", type=int, default=2)
    ap.add_argument("--lr", type=float, default=1e-4)
    ap.add_argument("--batch-size", type=int, default=4)
    ap.add_argument("--grad-accum", type=int, default=8)
    ap.add_argument("--lora-r", type=int, default=32)
    ap.add_argument("--max-state-tokens", type=int, default=3000)
    ap.add_argument("--mixed-precision", default="bf16")
    args = ap.parse_args()

    acc = Accelerator(mixed_precision=args.mixed_precision, gradient_accumulation_steps=args.grad_accum)
    tok, model, letter_ids = load(args.base)
    model.gradient_checkpointing_enable(gradient_checkpointing_kwargs={"use_reentrant": False})
    model = get_peft_model(model, LoraConfig(
        r=args.lora_r, lora_alpha=2 * args.lora_r, lora_dropout=0.05, target_modules="all-linear"))
    if acc.is_main_process:
        model.print_trainable_parameters()

    records = [json.loads(line) for line in open(args.train, encoding="utf-8")]
    loader = DataLoader(records, batch_size=args.batch_size, shuffle=True,
                        collate_fn=Collate(tok, args.max_state_tokens))
    opt = torch.optim.AdamW([p for p in model.parameters() if p.requires_grad], lr=args.lr, weight_decay=0.0)
    total = args.epochs * math.ceil(len(loader) / args.grad_accum)
    sched = get_cosine_schedule_with_warmup(opt, max(1, int(0.03 * total)), total)
    model, opt, loader, sched = acc.prepare(model, opt, loader, sched)

    step, n_batches = 0, args.epochs * len(loader)
    for epoch in range(args.epochs):
        model.train()
        for batch in loader:
            with acc.accumulate(model):
                z, mask = option_logits(model, tok, letter_ids, batch["prompts"], batch["ks"], acc.device)
                if args.objective == "rlcd":
                    sigma = 1.0 - 0.7 * step / n_batches  # exploration decays from 1.0 to 0.3
                    loss = rlcd_loss(z, mask, batch["y"], batch["ordinal"], sigma)
                else:
                    loss = -reward(z, mask, batch["y"], batch["ordinal"]).mean()
                acc.backward(loss)
                if acc.sync_gradients:
                    acc.clip_grad_norm_(model.parameters(), 1.0)
                opt.step()
                sched.step()
                opt.zero_grad()
            step += 1
            if step % 20 == 0:
                acc.print(f"epoch {epoch + 1} step {step}/{n_batches} loss {loss.item():.4f}")
        acc.wait_for_everyone()
        if acc.is_main_process:
            acc.unwrap_model(model).save_pretrained(f"{args.out}/epoch{epoch + 1}")
    acc.end_training()


if __name__ == "__main__":
    main()

这段代码做了这几件事：

1. 训练目标：reward() 就是前面介绍的 Laya 组合评分（对数评分 + 0.5 × 球面评分 − RPS），默认的 --objective proper 直接把它的相反数当损失；--objective rlcd 则按 Laya 的方式，用 8 组高斯扰动和组内基线做策略梯度，探索噪声从 1.0 衰减到 0.3。因为加了球面评分，choice 和 noul 题的损失下限是 −0.5（完全确定且答对），日志里出现负数是正常的；RLCD 的损失则是策略梯度的代理目标，数值本身没有意义，两种目标都要以评测指标为准；
2. 选项乱序：Collate 每次取 batch 都重新打乱 choice 和 noul 的选项顺序，标签跟着一起换位，这是对抗位置偏差最简单有效的办法；score 题保持等级顺序；
3. LoRA：target_modules="all-linear" 会覆盖注意力、Gated DeltaNet 和 MLP 中的所有线性层。在 Qwen3.5-0.8B 上，r=8 时可训练参数约 541 万，只占 0.71%；
4. 省显存：开启梯度检查点，只计算答案位的 logits；
5. 单卡、多卡同一份代码：Accelerate 负责设备、混合精度和梯度累积，多卡时自动切换成数据并行。

4. 启动训练

# 单卡：有效 batch = 4 × 8 = 32 道题
python train.py --base Qwen/Qwen3.5-4B --train data/train.jsonl --out out/my-jev

# 8 卡数据并行：有效 batch = 4 × 2 × 8 = 64 道题
accelerate launch --num_processes 8 train.py --base Qwen/Qwen3.5-4B \
  --train data/train.jsonl --out out/my-jev --grad-accum 2

# 对比实验：换成 Laya 式的 RLCD
python train.py --base Qwen/Qwen3.5-4B --train data/train.jsonl --out out/my-jev-rlcd --objective rlcd

每个 epoch 结束会保存一份 LoRA 适配器（out/my-jev/epoch1、epoch2……），挑哪一份由下一节的评测决定。超参数可以从这里起步：

我在 Qwen3.5-0.8B 上用 CPU 跑过这份脚本的冒烟测试（几十道题、两种训练目标各跑一遍），确认能正常训练和保存。真正的训练请在 GPU 上进行。

六、打分测试：怎么知道模型好不好

1. 看哪些指标

只看准确率是远远不够的。一个合格的决策模型评测，至少要包含下面这些指标：

位置偏差绝不是小问题。学术界早有研究表明，大模型做选择题时会偏好特定的选项位置和选项字母（Zheng 等人，2023）。JevBench 也记录过一个例子：open-alternative-jev 在“判断回答是否合格”这类题上，按作者给的选项顺序（A. yes, B. no）准确率是 72%，把两个选项倒过来就只剩 21%。除了脚本里的倒序翻转率，上线前最好再补几项一致性检查：同一问题换种问法答案是否一致、问题和它的否定形式概率之和是否接近 1、state 里插入注入文本后答案是否被带偏。

2. 评测脚本

# evaluate.py
"""Evaluate a decision model: accuracy, chance-corrected accuracy, calibration, order robustness, latency."""
import argparse
import json
import statistics
import time

import torch
from peft import PeftModel

from decision_format import load, option_logits, options, prompt, target


@torch.no_grad()
def predict(model, tok, letter_ids, records, batch_size=8, reverse=False):
    """Logits over each record's options, in the caller's order."""
    result = []
    for i in range(0, len(records), batch_size):
        chunk, orders = records[i : i + batch_size], []
        for r in chunk:
            order = list(range(len(options(r["question"]))))
            if reverse and r["question"]["type"] != "score":
                order.reverse()
            orders.append(order)
        prompts = [prompt(tok, r, o) for r, o in zip(chunk, orders)]
        z, _ = option_logits(model, tok, letter_ids, prompts, [len(o) for o in orders], model.device)
        for row, order in enumerate(orders):
            logits = torch.empty(len(order))
            logits[order] = z[row, : len(order)].cpu()  # slot s showed option order[s]
            result.append(logits)
    return result


def ece(conf, correct, bins=10):
    groups = {}
    for c, ok in zip(conf, correct):
        groups.setdefault(min(int(c * bins), bins - 1), []).append((c, ok))
    return sum(len(g) / len(conf) * abs(statistics.mean(o for _, o in g) - statistics.mean(c for c, _ in g))
               for g in groups.values())


def summary(rows):
    conf = [p.max().item() for _, p, _ in rows]
    correct = [float(p.argmax() == y.argmax()) for _, p, y in rows]
    acc = statistics.mean(correct)
    chance = statistics.mean(1 / len(p) for _, p, _ in rows)
    out = {"n": len(rows), "accuracy": acc, "chance_corrected": (acc - chance) / (1 - chance),
           "log_loss": statistics.mean(-(y * p.clamp_min(1e-12).log()).sum().item() for _, p, y in rows),
           "brier": statistics.mean(((p - y) ** 2).sum().item() for _, p, y in rows),
           "ece": ece(conf, correct)}
    ordinal = [(p, y) for kind, p, y in rows if kind == "score"]
    if ordinal:
        out["rps"] = statistics.mean((((p.cumsum(0) - y.cumsum(0)) ** 2).sum() / (len(p) - 1)).item()
                                     for p, y in ordinal)
    return out


def metrics(records, logits, temps):
    rows = []
    for r, z in zip(records, logits):
        kind = r["question"]["type"]
        p = (z / temps.get(kind, 1.0)).softmax(-1)
        rows.append((kind, p, torch.tensor(target(r, options(r["question"])))))
    report = {"all": summary(rows)}
    for kind in ("choice", "noul", "score"):
        if any(row[0] == kind for row in rows):
            report[kind] = summary([row for row in rows if row[0] == kind])
    return report


def fit_temperatures(records, logits):
    """One temperature per question type, chosen to minimise log loss (fit on dev data only)."""
    grid, temps = [round(0.3 + 0.05 * i, 2) for i in range(55)], {}
    for kind in ("choice", "noul", "score"):
        pairs = [(z, torch.tensor(target(r, options(r["question"]))))
                 for r, z in zip(records, logits) if r["question"]["type"] == kind]
        if pairs:
            temps[kind] = min(grid, key=lambda t: sum(-(y * (z / t).log_softmax(-1)).sum().item()
                                                      for z, y in pairs))
    return temps


@torch.no_grad()
def latency_ms(model, tok, letter_ids, records, n=50):
    times = []
    for r in records[:n]:
        k = len(options(r["question"]))
        text = prompt(tok, r, list(range(k)))
        if torch.cuda.is_available():
            torch.cuda.synchronize()
        start = time.perf_counter()
        option_logits(model, tok, letter_ids, [text], [k], model.device)
        if torch.cuda.is_available():
            torch.cuda.synchronize()
        times.append((time.perf_counter() - start) * 1000)
    times.sort()
    return {"p50": times[len(times) // 2], "p95": times[min(len(times) - 1, int(0.95 * len(times)))]}


def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("--base", default="Qwen/Qwen3.5-4B")
    ap.add_argument("--adapter", help="LoRA directory; omit it to score the raw base model")
    ap.add_argument("--data", nargs="+", required=True)
    ap.add_argument("--fit-temperature", help="fit temperatures on --data (dev only) and save them here")
    ap.add_argument("--temperatures", help="temperatures fitted earlier")
    ap.add_argument("--batch-size", type=int, default=8)
    args = ap.parse_args()

    tok, model, letter_ids = load(args.base)
    if args.adapter:
        model = PeftModel.from_pretrained(model, args.adapter).merge_and_unload()
    model.to("cuda" if torch.cuda.is_available() else "cpu").eval()
    records = [json.loads(line) for path in args.data for line in open(path, encoding="utf-8")]

    logits = predict(model, tok, letter_ids, records, args.batch_size)
    temps = json.load(open(args.temperatures)) if args.temperatures else {}
    if args.fit_temperature:
        temps = fit_temperatures(records, logits)
        json.dump(temps, open(args.fit_temperature, "w"), indent=2)
    flipped = predict(model, tok, letter_ids, records, args.batch_size, reverse=True)
    flips = [bool(a.argmax() != b.argmax())
             for r, a, b in zip(records, logits, flipped) if r["question"]["type"] != "score"]

    report = metrics(records, logits, temps)
    report["flip_rate_reversed_options"] = sum(flips) / max(1, len(flips))
    report["temperatures"] = temps
    report["latency_ms"] = latency_ms(model, tok, letter_ids, records)
    print(json.dumps(report, indent=2))


if __name__ == "__main__":
    main()

典型的用法分三步：

# 1) 零样本基线：不加适配器，直接读底座模型的字母概率，先知道起点
python evaluate.py --base Qwen/Qwen3.5-4B --data data/dev.jsonl data/heldout_tasks.jsonl

# 2) 在开发集上评测训练好的模型，并按题型拟合温度
python evaluate.py --base Qwen/Qwen3.5-4B --adapter out/my-jev/epoch2 \
  --data data/dev.jsonl --fit-temperature out/my-jev/temperatures.json

# 3) 带上温度，在留出任务和 JevBench 公开题上打分（温度只能在开发集上拟合）
python evaluate.py --base Qwen/Qwen3.5-4B --adapter out/my-jev/epoch2 \
  --temperatures out/my-jev/temperatures.json --data data/heldout_tasks.jsonl
python evaluate.py --base Qwen/Qwen3.5-4B --adapter out/my-jev/epoch2 \
  --temperatures out/my-jev/temperatures.json --data eval/easy.jsonl eval/original.jsonl eval/hard.jsonl

作为示例，下面是 Qwen3.5-0.8B 原始模型（不加适配器）在 JevBench 公开的 easy 和 original 两组、共 120 道题上的结果（节选，保留三位小数）。这是在我的 Mac 上用 CPU 跑的，延迟没有参考意义，就不列出来了：

{
  "all":    {"n": 120, "accuracy": 0.642, "chance_corrected": 0.488, "log_loss": 1.326, "brier": 0.523, "ece": 0.108},
  "choice": {"n": 72,  "accuracy": 0.694, "chance_corrected": 0.614, "ece": 0.117},
  "noul":   {"n": 36,  "accuracy": 0.583, "chance_corrected": 0.167, "ece": 0.220},
  "score":  {"n": 12,  "accuracy": 0.500, "chance_corrected": 0.333, "rps": 0.151},
  "flip_rate_reversed_options": 0.620
}

几个值得注意的地方：

• noul 题的准确率只有 58.3%，去掉随机猜中的部分只剩 16.7%，基本是在猜；
• 选项倒序翻转率高达 62%：只是把选项顺序倒过来，六成以上题目的答案就变了。我还单独试了一道题：state 是“结账页面对所有客户返回 HTTP 500”，问题是“是否有生产系统宕机”，选项按 yes、no 排列时 P(yes) 是 0.18，换成 no、yes 排列就变成了 0.45。小模型的位置偏差比想象中严重得多，这正是训练时要不断打乱选项、评测时一定要报告这个指标的原因；
• 作为对照，H2O-Lightning-4B 在同样这 120 道题上答对了 119 道。两者规模不同，差距不能全部归功于微调，但足以说明决策微调要补的课有多少。

3. 和 JevBench 上的模型同场比较

JevBench 的 GitHub 仓库公开了 231 道题（datasets/public/ 下的 easy 48 道、original 72 道、hard 111 道），格式和本文的数据格式一致，evaluate.py 可以直接读取。作为参照，H2O-Lightning-4B 在这 231 道题上答对 205 道（88.7%）：easy 48/48，original 71/72，hard 86/111。

不过要注意三点：

1. 公开题只是参考：榜单分数基于每期 1500 道题（1200 道不公开的封存题加 300 道公开题，智能分里两部分各占一半），还做了去随机、分难度加权和公开 / 封存差距惩罚，公开题上的准确率不能直接换算成榜单分数；
2. 绝不能拿公开题训练：JevBench 要求在公开题上训练过的模型必须主动声明，prepare_data.py 里的去污染就是为此准备的；
3. 想上榜就提交：在 JevBench 网站提交模型后，会由维护者在他们自己的 GPU 上跑完整的封存题。

如果想完全按 JevBench 官方的方式测，可以先把模型包装成和 Jev 一样的 HTTP 接口，再用官方的评测工具去调用它。

4. 服务化：兼容 Jev 的 /v1/systemone

# serve.py
"""A minimal /v1/systemone server (Jev wire format) in front of the fine-tuned model."""
import json
import os

import torch
from fastapi import FastAPI, HTTPException
from peft import PeftModel

from decision_format import LETTERS, load, option_logits, options, prompt

BASE = os.environ.get("BASE_MODEL", "Qwen/Qwen3.5-4B")
ADAPTER = os.environ.get("ADAPTER", "out/my-jev/epoch2")
TEMPS = json.load(open(os.environ["TEMPERATURES"])) if os.environ.get("TEMPERATURES") else {}

tok, model, letter_ids = load(BASE)
model = PeftModel.from_pretrained(model, ADAPTER).merge_and_unload()
model.to("cuda" if torch.cuda.is_available() else "cpu").eval()
app = FastAPI()


@app.post("/v1/systemone")
@torch.no_grad()
def systemone(body: dict):
    questions = body.get("questions")
    if not isinstance(questions, dict) or not 0 < len(questions) <= 32:
        raise HTTPException(422, "questions must be an object with 1 to 32 entries")
    names, prompts, ks = list(questions), [], []
    for name in names:
        q = questions[name]
        try:
            k = len(options(q))
            ok = q["type"] in ("choice", "noul", "score") and isinstance(q["instructions"], str)
        except (KeyError, TypeError, AttributeError):
            ok = False
        if not ok or not 2 <= k <= len(LETTERS):
            raise HTTPException(422, f"{name}: malformed question or unsupported option count")
        prompts.append(prompt(tok, {"state": body.get("state", ""), "question": q}, list(range(k))))
        ks.append(k)

    z, _ = option_logits(model, tok, letter_ids, prompts, ks, model.device)
    answers = {}
    for row, name in enumerate(names):
        q, k = questions[name], ks[row]
        p = (z[row, :k] / TEMPS.get(q["type"], 1.0)).softmax(-1).tolist()
        if q["type"] == "noul":
            answers[name] = {"type": "noul", "noul": p[0]}  # P(yes)
        elif q["type"] == "score":
            answers[name] = {"type": "score", "score": sum(i * x for i, x in enumerate(p)),
                             "probabilities": {str(i): x for i, x in enumerate(p)}}
        else:
            probs = {key: x for (key, _), x in zip(options(q), p)}
            best = max(probs, key=probs.get)
            answers[name] = {"type": "choice", "choice": best, "probabilities": probs,
                             "confidence": (k * probs[best] - 1) / (k - 1)}
    used = sum(len(ids) for ids in tok(prompts, add_special_tokens=False).input_ids)
    return {"answers": answers, "usage": {"input_tokens": used, "output_tokens": 0}}

启动服务，然后用 curl 验证一下：

ADAPTER=out/my-jev/epoch2 TEMPERATURES=out/my-jev/temperatures.json \
  uvicorn serve:app --host 127.0.0.1 --port 8741

curl -s http://127.0.0.1:8741/v1/systemone -H 'Content-Type: application/json' -d '{
  "state": "Checkout returns HTTP 500 for every customer since 09:10.",
  "questions": {
    "team": {"type": "choice", "instructions": "Which team should handle this?",
             "criteria": {"billing": "charges and refunds", "engineering": "bugs and outages"}},
    "outage": {"type": "noul", "instructions": "Is a production system down?"}
  }
}'

返回结构沿用 Jev 的格式：每个答案都带 type，choice 返回 choice、probabilities 和按 Jev 公式 (K·p_max − 1)/(K − 1) 计算的 confidence，score 返回期望等级和以等级下标为键的概率，noul 直接返回 P(yes)，usage 里只有输入 token。这正是 JevBench 官方评测工具（typesafe 适配器）解析的字段，所以可以直接拿它来测，已有的 Jev 客户端通常也只需要改一下 baseUrl：

git clone https://github.com/fstandhartinger/jevbench && cd jevbench
python -m jevbench.cli run \
  --tasks datasets/public/easy.jsonl,datasets/public/original.jsonl,datasets/public/hard.jsonl \
  --adapter typesafe --endpoint http://127.0.0.1:8741 --key-env '' --model my-jev \
  --cost-basis self_hosted_gpu --reserve-usd 0 --delay-s 0 \
  --results RUN/results.jsonl --raw-dir RUN/raw --ledger RUN/ledger.jsonl --manifest RUN/manifest.json

# 汇总成绩
python -m jevbench.cli summarize \
  --tasks datasets/public/easy.jsonl,datasets/public/original.jsonl,datasets/public/hard.jsonl \
  --results RUN/results.jsonl --public-export RUN/summary.json

这个服务只是为了评测和演示：它一次处理一个请求，没有认证。正式上线时，推荐像 H2O-Lightning-4B 那样把合并后的模型交给 vLLM（连续批处理、前缀缓存），前面放一个很薄的协议转换层，并加上认证、限流和请求大小限制，不要直接暴露在公网上。

七、调整思路：分数不理想怎么办

1. 先有基线，再按切片找问题

动手调参之前，先确认两件事：一是零样本基线（不微调、直接读底座的字母概率）是多少，二是“永远猜最常见答案”能拿多少分。训练后的模型必须和这两个数字比，否则很容易被虚高的准确率骗到。

然后按切片拆开看：题型、任务、语言、选项数、state 长度、置信度区间。总分掩盖的问题，往往在切片里一目了然。H2O 把这叫作“找短板”（gap hunting）：按主题和题型和其他系统对比，跑对抗性题集，然后针对性地补充经过验证的新数据。

2. 症状与对策

3. 让迭代形成闭环

最后是几条流程上的建议，它们比任何一个超参数都重要：

1. 上线标准先写下来：比如“封存集上的去随机准确率不低于上一版，温度缩放后 ECE 不高于 0.05，选项倒序翻转率不高于 5%，p95 延迟不超过 100 ms”。先定标准再看结果，才能避免“看着结果改标准”。
2. 封存集只在发版时用一次：日常调参只看开发集和留出任务，封存集一旦被反复使用，它就变成了另一个开发集。
3. 每次只改一个变量：数据、超参数、底座同时改，就无法判断哪一个起了作用。
4. 固定版本，持续监控：底座或数据变化之后，温度和阈值都要重新标定；上线后持续记录概率分布并抽样复核，一旦分布漂移就回到飞轮的起点。

总结

把全文浓缩成几句话：

1. 路线：想要 Jev 那样的零样本通才，走“解码器 + 选项字母”，从 Qwen3.5-4B + LoRA 起步；只服务固定任务、追求极致速度，编码器路线依然划算。
2. 目标：用严格适当评分规则训练，再用温度缩放校准。RLCD 是其中一种实现方式，而不是魔法。
3. 数据：任务的多样性、标签的质量、严格的去污染和按任务切分，比模型结构重要得多。
4. 算力：4B 模型的一次 LoRA 训练，单张 H100 几个小时、十几美元，钱主要花在一轮又一轮的迭代上。
5. 评测：准确率之外还要看校准、位置偏差、阈值曲线和延迟；用 JevBench 公开题对标，用自己的封存集验收。

Jev 定义了“决策模型”这个品类，而短短一个月里，开源社区已经复刻出了上百个替代品，其中最好的一批在榜单上已经和 Jev 不相上下。训练一个自己的决策模型，已经从“能不能做到”变成了“值不值得做”。如果你有自己的数据、有合规要求，或者对延迟和成本格外敏感，答案多半是值得的。

参考资料

• JevBench：开源权重决策模型榜单
• JevBench：评测方法说明
• JevBench：评测工具与公开题集（GitHub）
• H2O-Lightning-4B 模型卡
• Laya GitHub 仓库
• Nandakishor M：I Built Non-Autoregressive Decision Models a Year Ago. Then a Frontier Lab Called It a “Breakthrough”.
• Qwen3.5-4B 模型卡
• Gneiting & Raftery：Strictly Proper Scoring Rules, Prediction, and Estimation（2007）
• Guo et al.：On Calibration of Modern Neural Networks（2017）
• Kadavath et al.：Language Models (Mostly) Know What They Know（2022）
• Zheng et al.：Large Language Models Are Not Robust Multiple Choice Selectors（2023）
• Wei et al.：Finetuned Language Models Are Zero-Shot Learners（2021）
• Hu et al.：LoRA: Low-Rank Adaptation of Large Language Models（2021）
• Jev vs Laya：闭源与开源 System One 决策模型的对比与选型
• Microsoft-Decision-1 详解：微软入局决策模型，与 Jev、Laya 的三方对比
• 玩转大语言模型：大语言模型（LLM）微调主流方式和使用场景全面解析对比
• PPO vs GRPO：两种主流 LLM 强化学习范式的对比与选择

引言

上个月我写了一篇 Jev vs Laya，对比了 TypeSafe AI 的闭源决策模型 Jev 和社区开源的 Laya。那时“决策模型”还是一个刚刚诞生的新品类：9 月 15 日 Jev 发布，三天后 Laya 开源。

仅仅三周之后，这个赛道就挤满了玩家：10 月 6 日，OpenAI 开放了基于 GPT-6 Luna 的 Decisions API；Liquid AI、Inception 等公司也陆续推出了自己的决策 API；第三方榜单 JevBench 上参与排名的开源权重系统已经超过 140 个。10 月 9 日，微软也正式入局，发布了 Microsoft-Decision-1。

和其他入局者相比，Microsoft-Decision-1 有几个特别值得关注的地方：

• 出自大厂，底座却是开源模型：它基于阿里开源的 Qwen3.5-9B 后训练而来，微软还表示后续会迁移到自家的 MAI 系列和 OpenAI 的模型上；
• 价格与 Jev 完全一致：输入每百万 token 0.042 美元，输出免费；
• 接口几乎与 Jev 兼容：同样是 state + questions，同样是 noul / choice / score 三种问题类型；
• 官方数据很亮眼：在 36 项基准、近 15 万道题的对比中平均准确率最高，中位延迟比 GPT-6 Sol 快约 35 倍。

但官方数据只是故事的一半。微软发布的第二天，第三方榜单 JevBench 就完成了独立实测，结论并不完全一致。本文将从以下几个方面展开：

1. Microsoft-Decision-1 是什么，又是怎么做出来的
2. 它与 Jev、Laya 的技术路线和接口有什么不同
3. 官方基准与第三方实测应该怎么看
4. Microsoft-Decision-1 的优势与劣势
5. 适用场景、选型建议与代码示例

一分钟回顾：什么是决策模型

决策模型（System One Model）不聊天，也不写文章，它只做一件事：接收一段状态（state）和一组预先定义好的问题（questions），直接返回带概率的类型化决策。三家都支持同样的三种问题原语：

由于答案空间被提前限定，模型不会返回格式错误或凭空编造的选项；校准过的概率则可以直接写进程序的 if 语句：高置信度自动执行，中置信度交给更强的模型复核，低置信度转人工。在一个 AI 系统里，比较合理的分工是：代码负责骨架，决策模型负责快速判断，大模型负责深度思考。

更详细的概念介绍和置信度分流的思路，可以参考上一篇，这里不再展开。

Microsoft-Decision-1 是什么

1. 基本信息

2026 年 10 月 9 日，微软首席技术官办公室（Office of the CTO）软件工程副总裁 Achint Srivastava 在微软的技术博客 Command Line 上发布了 Microsoft-Decision-1。文章开头是这样定义决策模型的：

Unlike LLMs, which are designed to generate text or reason through complex problems, decision models are purpose-built to deliver structured outputs that software can immediately act on.

与生成文本、推理复杂问题的大模型不同，决策模型专门用来输出软件可以立即据此行动的结构化结果。

微软给它的定位是一个“快速决策打分”（fast decision-scoring）模型，面向路由、分类、优先级排序、结果校验和工作流控制。主要信息如下：

按这个价格，如果每次判断平均消耗 1000 个输入 token，100 万次判断的费用约为 42 美元，和 Jev 完全相同。

2. 它是怎么做出来的

微软公开的技术细节不多，但有几个关键点：

• 在开源底座上后训练：微软在 Qwen3.5-9B 上做了后训练（post-training），让它学会“单次前向完成决策打分”（fast, single-pass decision scoring）。给定一组固定的候选答案，模型直接为每个选项输出一个校准过的概率，而不是逐 token 生成文字。
• 底座可以替换：微软明确表示，很快会把它迁移（rebase）到其他底座上，包括微软自研的 MAI 系列和 OpenAI 的模型。
• 没有公开的部分：训练数据、后训练方法和打分机制的具体实现都没有公开，权重也没有开放，只能以托管 API 的形式使用。

微软在博客里把打造一个可靠决策模型的难点归纳为五个方面，并给出了相应的自测结果：

3. 微软内部的四个试点

微软还公开了几个内部试用的案例（均为微软自测）：

其中 Xbox 的三个数据集，微软给出了更详细的对比数据：

按 100 万条文本折算，GPT-6 Sol 约需 2434 美元，Microsoft-Decision-1 约需 11 美元（微软注明成本为估算值）。两者读取的是同一份任务说明，输入 token 数相同，差距来自单价，以及 GPT-6 Sol 还需要为输出付费。

4. 适合哪些场景

微软在博客里列出了 16 个推荐场景，大致可以归为四类：

其中最值得关注的是 Agent 控制。今天的 Agent 每走一步都要做大量“小判断”：上一步成功了吗？要不要重试？这个工具调用会不会动到生产数据？如果这些判断都交给大模型，延迟和成本会随着步数线性累积。用一个百毫秒级的决策模型给 Agent 加一道“闸门”，是这类模型最有想象空间的用法。微软还演示了一个电脑操作（computer use）的例子：在完成“买一个背包”的任务时，由 Microsoft-Decision-1 选择下一步界面操作，完成速度明显快于 GPT-6 Sol。

另一个值得一提的场景是模型路由：根据请求的质量、成本和延迟要求，选择最合适的模型来处理。我之前写过一篇 让模型自己选模型：Embedding 驱动的 LLM 智能路由机制，决策模型提供了另一种思路：不再依赖向量相似度，而是直接把“该交给哪个模型”当成一道 choice 题来回答。

三条技术路线

把三个模型放在一起，会发现它们代表了三条截然不同的技术路线：

有几点值得展开说说：

1. 规模相差一个数量级以上。Laya 用 4 亿参数的编码器换取极致的速度和本地部署能力；Microsoft-Decision-1 用 90 亿参数的解码器换取更强的零样本泛化能力，代价是对算力的要求高得多，而且目前只能以云端托管的方式使用。
2. 底座正在变成可替换的零件。从 JevBench 榜单看，排名靠前的开源决策模型大多也是在 Qwen 或 Gemma 上后训练出来的，比如基于 Qwen3.5-4B 的 H2O-Lightning-4B、基于 Gemma-4-31B 的 Quyet-1.0-Large。微软直接选用阿里的开源模型做底座，又公开表示后续会换成 MAI 或 OpenAI 的模型，说明这类模型的竞争力主要来自后训练数据、评测体系和校准方法，而不是底座本身。
3. “单次前向”已经是共识。无论是 Laya 的编码器还是 Microsoft-Decision-1 的解码器，核心思路都一样：不生成文本，一次前向计算就给出所有候选项的概率。这也是决策模型能比通用大模型快一到两个数量级的根本原因。

同一套接口，三种后端

对开发者来说，一个非常实用的变化是：三者的请求格式几乎一致。

• Jev 的官方 API 是 POST https://api.typesafe.ai/v1/systemone；
• Microsoft-Decision-1 的端点是 Foundry 资源下的 /providers/microsoft/v1/systemone，微软文档也直接说明，它的请求模式与 System One API 类似；
• Laya 也提供了 laya-serve，在本地以同样的 POST /v1/systemone 协议对外服务，返回结构与 Jev 一致，已有的 Jev 客户端只需要修改 baseUrl。

三者在细节上的差异如下：

这意味着 state + questions 风格的接口正在成为决策模型的事实标准，就像当年 OpenAI 的 Chat Completions 接口之于大模型。微软把价格定得和 Jev 一模一样、接口也几乎一致，很难不让人认为这是在刻意降低 Jev 用户的迁移门槛。对用户来说，切换成本越来越低；对厂商来说，护城河只能来自效果、延迟、单次成本、合规能力和生态。

核心差异一览

基准数据怎么看

1. 微软公布的对比数据

微软把 Microsoft-Decision-1 和 JevBench 榜单上的几个头部模型、Jev 以及 GPT-6 Sol 放在一起，在 36 个公开和私有基准、共 147,137 道题上做了对比（准确率和校准分越高越好，延迟越低越好）：

注：Microsoft-Decision-1 的延迟是在 Foundry 同区域测得的，其余模型的延迟引用自 JevBench v1.6.1 的调整后中位延迟（10 月 7 日数据）。另外，AWS 的 Strands-Decider 2B 只能回答 36 个基准中的 23 个，平均准确率为 54.8%，未列入上表。微软的文章在发布后还专门更新了一次，补充了 Jev 的准确率和校准数据。

按这组数据，Microsoft-Decision-1 的平均准确率第一，速度最快：比第二快的 H2O-Lightning-4B v1.1 快 2.5 倍，比 Jev 快约 2.8 倍，比 GPT-6 Sol 快约 35 倍；校准分排第三。

需要注意的是，微软说的是 36 项基准的平均准确率最高，而不是每一项都排第一，一些报道中“36 项基准全部第一”的说法并不准确。

2. 第三方 JevBench 的实测

JevBench 是一个独立于 TypeSafe 的社区榜单（个人维护的开源项目 Benchmark Heaven），用 1500 道决策题（1200 道封存题加 300 道公开题），从智能（Intelligence）、校准（Calibration）、速度和成本四个维度评测决策模型。Microsoft-Decision-1 发布的第二天（10 月 10 日），JevBench 就通过 Azure Foundry 的原生接口完成了完整测试。下面是 API 榜单上的部分结果：

把 Jev 和 Microsoft-Decision-1 单独拿出来比较：

JevBench 的智能分是扣除随机猜测之后的得分（0 表示和随机猜测相当，100 表示全部答对），能力分是智能分和校准分的平均值，综合分则把智能、校准、速度和成本四个维度放在一起计算。它们和微软表格里的“平均准确率”不是同一个指标，不能直接换算。

3. 解读数据时必须注意的五点

第一，自测与第三方的结论并不一致。 在微软的 36 项基准上，Microsoft-Decision-1 的平均准确率比 Jev 高 1.2 个百分点；但在 JevBench 上，Jev 的智能分（63.6 对 57.2）和能力分（77.1 对 70.8）都明显领先。两边的题目、评分方法和统计口径完全不同，谁也不能代表“绝对真相”。比较稳妥的理解是：Microsoft-Decision-1 已经进入第一梯队，但还谈不上全面超越 Jev。这也再次说明，最可靠的基准永远是你自己的数据。

第二，校准仍是 Jev 的强项。 即使在微软自己的数据里，Microsoft-Decision-1 的校准分（92.2）也落后于 Jev（93.7）和 Quyet-1.0-Large（93.1）；在 JevBench 上差距更大（84.4 对 90.6）。对于依赖置信度阈值做分流的系统来说，校准质量往往比准确率高出一两个点更重要。

第三，延迟主要取决于部署位置。 微软的 85 ms 是在 Foundry 同区域测得的，而表中其他模型的延迟来自 JevBench 自己的测试环境。JevBench 原生调用 Microsoft-Decision-1 测得的中位延迟是 459 ms，在同一个榜单上，Jev 是 240 ms。两组数字都没有错，只是测量条件不同。决策模型的计算本身只需要几十毫秒，真正决定体验的是网络距离：把 Foundry 资源建在离应用最近的区域，对数据驻留有要求时选择 DataZoneStandard，并且一定要用真实流量实测。

第四，同样的单价，不同的单次成本。 两者的标价都是每百万输入 token 0.042 美元，但 JevBench 在同一批题目上实测的每千次决策成本，Microsoft-Decision-1 约为 0.019 美元，Jev 约为 0.032 美元，前者便宜约 40%。差异来自两者对同样的输入计出的 token 数不同。调用量很大时，这个差距值得算进总成本。

第五，Laya 不在同一条赛道上。 微软的对比中没有 Laya。JevBench 对 Laya 的三个检查点做了零样本测试，智能分只有 0.3～5.5，几乎等同于随机猜测。这和 Laya 作者自己的定位是一致的：它是一个需要在自有数据上微调的快速底座，而不是零样本决策引擎。再加上默认只有 512 / 1024 token 的上下文，Laya 在 JevBench 这种包含长文本、覆盖开放领域的考卷上吃亏是必然的。它的价值在于本地部署，以及特化之后的速度和成本，这一点在上一篇中已经详细讨论过。

此外，JevBench 中有 23 道约 7.7 万～8.1 万 token 的超长题。Microsoft-Decision-1 有 21 道因为超出上下文限制而失败，Jev 也拒绝了这 23 道超出其输入范围的题目，它们都按答错计分。

4. 小结

比较公允的结论是：Microsoft-Decision-1 进入了决策模型的第一梯队，优势在于同区域延迟、单次成本和微软生态；Jev 在校准和长上下文上仍然领先；Laya 则是另一条赛道上的选手，适合有数据、需要本地化的团队。

Microsoft-Decision-1 的优势与劣势

优势

1. 企业级集成：作为 Azure 直接销售的 Foundry 模型，它通过 Azure 订阅计费，受 Azure SLA 保障并由微软提供支持；支持 Entra ID 认证和 RBAC 权限控制，可以和现有的 Azure 网络、监控、合规体系一起管理。对已经在用 Azure 的企业来说，几乎不需要引入新的供应商。
2. 同区域延迟低：微软在同区域测得的 p50 约为 85 ms、p95 约为 125 ms，加上决策只需要一次前向计算，适合放进 Agent 的多步循环里。
3. 零样本能力进入第一梯队：不需要任何训练数据就能使用；在微软的 36 项基准上平均准确率最高，在 JevBench 的 27 个 API 产品中综合排名第 6。
4. 鲁棒性好：对同一请求做 8 种等价扰动，平均翻转率只有 1.3%，选项改写或重排时不翻转。在提示词和选项不断演进的生产环境中，这一点很重要。
5. 单次成本更低：标价与 Jev 相同，按 JevBench 的实测，每千次决策的成本还要低约 40%。
6. 接口兼容，迁移成本低：请求格式与 Jev 的 System One 风格接口几乎一致，已有的问题设计和分流逻辑可以直接复用（阈值需要重新标定）。
7. 有具体的落地参考：Xbox、Copilot、事故响应、Microsoft Discovery 等内部试点给出了可以借鉴的用法，虽然这些同样是自测数据。

劣势

1. 以自测数据为主，第三方结果不如官方亮眼：在 JevBench 上，它的智能分和校准分都低于 Jev，在 API 榜单上综合排名第 6。
2. 校准不是最强：无论官方数据还是第三方数据，它的校准都落后于 Jev，上线前一定要用自己的数据标定阈值。
3. 上下文只有 32K：比 Jev 的 64K 短，长邮件串、长合同或 Agent 的长执行轨迹需要先截断、摘要或分块。
4. 权重不开放，也不能微调：虽然底座是开源的 Qwen3.5-9B，但模型本身只能以托管 API 的形式使用，无法本地或离线部署；目前文档只介绍了通过 state、instructions 和选项来调优，没有提供基于自有数据的微调。
5. 版本和底座都可能变化：目前只有版本 1，而微软已经表示会把它迁移到 MAI 或 OpenAI 的底座上。底座一换，概率分布很可能随之变化，调好的阈值需要重新标定。
6. 没有解释，且对措辞敏感：模型只返回数字，不给理由。官方文档也提醒：问题和选项的措辞、顺序会影响分数；校准在熟悉的任务类型上最可靠；模型的知识可能已经过时；作为安全过滤器时，它可能漏掉隐蔽的有害内容，也可能误拦正常内容。
7. 跨境与数据驻留：中国大陆的团队目前需要通过 Azure 全球版的 Foundry 调用它，要同时考虑跨境网络延迟和数据出境的合规要求；GlobalStandard 部署可能在任意区域处理推理请求，对数据驻留敏感的场景应选择 DataZoneStandard。

与 Jev、Laya 相比，怎么选

1. 场景对照表

2. 选型时要回答的几个问题

可以按下面的顺序依次回答：

1. 数据能否离开自己的环境（以及境内）？
   └─ 不能 → Laya（硬约束，其他因素都要让路）
2. 是否已经在用 Azure，需要统一账单、Entra ID、RBAC 和数据区域部署？
   └─ 是 → 优先评估 Microsoft-Decision-1
3. 是否高度依赖置信度阈值，或者单次输入经常超过 32K token？
   └─ 是 → 优先评估 Jev
4. 是否有标注数据，并且需要每秒几十次以上的决策？
   └─ 是 → 微调 Laya，本地部署
5. 以上都不是硬约束？
   └─ 用同一组题目同时测试 Microsoft-Decision-1 和 Jev，
      按准确率、校准、延迟和单次成本综合选择

3. 组合使用：不必三选一

由于三者的接口几乎一致，组合使用的成本很低：

1. 多供应商容灾：把 Microsoft-Decision-1 和 Jev 配置成互为备份的两个云端后端，一方限流或故障时自动切换。两者的概率分布不同，阈值需要分别标定。
2. 影子测试：生产流量走一个后端，同时把请求异步发给另一个后端，积累两者结论不一致的样本，再交给人工或大模型裁决，为后续的选型和阈值调整提供依据。
3. 分层级联：本地的 Laya 先处理高频、短文本、高置信度的请求；低置信度或长文本请求升级给 Microsoft-Decision-1 或 Jev；仍然拿不准的，再交给推理型大模型或人工处理。
4. 按数据敏感度路由：涉及敏感数据的请求只走本地的 Laya，其余请求走云端。

代码示例：同一组问题，三种后端

1. 部署 Microsoft-Decision-1

可以在 Foundry 门户的模型目录中搜索 Microsoft-Decision-1 并一键部署，也可以使用 Azure CLI：

az cognitiveservices account deployment create \
  --name <ACCOUNT_NAME> \
  --resource-group <RESOURCE_GROUP> \
  --deployment-name decision-1 \
  --model-name "Microsoft-Decision-1" \
  --model-format Microsoft \
  --model-version "1" \
  --sku-name GlobalStandard \
  --sku-capacity 1

如果需要把推理限制在某个数据区域内，可以把 --sku-name 换成 DataZoneStandard（需要所在区域支持）。

2. 启动本地的 Laya 服务

pip install "laya[serve]"
# 只监听本机；如需对外提供服务，请设置 LAYA_API_KEY 并放在网关后面
LAYA_HOST=127.0.0.1 LAYA_DEVICE=cuda LAYA_PRELOAD=1 laya-serve

3. 用同一组问题调用三个后端

下面的示例使用 requests 和 azure-identity（pip install requests azure-identity）。注意 team 问题里加了一个 cannot_tell 选项，这是微软文档推荐的做法：当模型不应该被迫做出选择时，给它一个“无法判断”的出口。

import os

import requests
from azure.identity import DefaultAzureCredential

payload = {
    "state": {
        "message": "Checkout is down again. This is my third request.",
        "customer_contact_count": 3,
    },
    "questions": {
        "team": {
            "type": "choice",
            "instructions": "Which team should handle this request?",
            "criteria": {
                "billing": "Charges, invoices, and refunds",
                "engineering": "Bugs, errors, and outages",
                "support": "How-to and account questions",
                "cannot_tell": "The message does not say enough to decide",
            },
        },
        "severity": {
            "type": "score",
            "instructions": "How severe is this issue?",
            "criteria": ["Cosmetic", "Minor", "Major", "Critical"],
        },
        "repeat_contact": {
            "type": "noul",
            "instructions": "Has the customer contacted support before?",
        },
    },
}


def decide(url: str, headers: dict, model: str | None = None) -> dict:
    body = {**payload, "model": model} if model else payload
    resp = requests.post(url, headers=headers, json=body, timeout=10)
    resp.raise_for_status()
    return resp.json()["answers"]


# 1) Microsoft-Decision-1（Foundry）：model 填部署名称，推荐使用 Entra ID 认证
token = DefaultAzureCredential().get_token("https://cognitiveservices.azure.com/.default").token
answers = decide(
    f"{os.environ['AZURE_ENDPOINT'].rstrip('/')}/providers/microsoft/v1/systemone",
    {"Authorization": f"Bearer {token}"},
    os.environ["DEPLOYMENT_NAME"],
)
print("decision-1:", answers["team"]["choice"])

# 2) Jev（TypeSafe）：固定版本号，避免别名升级后调好的阈值失效
answers = decide(
    "https://api.typesafe.ai/v1/systemone",
    {"Authorization": f"Bearer {os.environ['TYPESAFE_API_KEY']}"},
    "jev-1.13.0",
)
print("jev:", answers["team"]["choice"])

# 3) Laya（本地 laya-serve）：省略 model，由 Router 按语言自动选择检查点
answers = decide("http://127.0.0.1:8000/v1/systemone", {})
print("laya:", answers["team"]["choice"])

如果使用 API Key 调用 Microsoft-Decision-1，把请求头换成 {"api-key": os.environ["AZURE_API_KEY"]} 即可。

三个后端返回的 answers 都以问题名为键，但有几个细节需要留意：

• Jev 和 Laya 的 choice 结果都包含 choice、probabilities 和 confidence，不过 Laya 的 confidence 计算方式和 Jev 不同，所以它额外提供了一个按 Jev 公式计算的 x_jev_confidence，方便沿用 Jev 上调好的阈值；
• Microsoft-Decision-1 的文档说明会返回选中项和每个选项的概率，接入时建议先打印一次完整的响应，确认字段名之后再编写阈值逻辑；
• Microsoft-Decision-1 的 score 返回的是各等级下标的概率加权平均值（四级量表的取值范围是 0～3，可能落在两个等级之间），文档建议把它用于相对排序和阈值判断，而不是当作绝对的校准评分。

落地注意事项

Microsoft-Decision-1 的官方文档给出了不少实用的建议，它们同样适用于 Jev 和 Laya：

1. 先用代表性数据验证：用自己的标注样本测试准确率和延迟，再决定是否上线。
2. 按误判代价设置阈值：根据误报和漏报的代价分别设置置信度阈值；不应该强行选择时，加一个“无法判断”的选项。
3. 使用中性措辞，随机化选项顺序：测试改变选项顺序是否会影响结果。
4. 用 Coding Agent 迭代问题设计：让 Coding Agent 生成多组候选的 state、instructions 和选项，在标注集上评估、对比，人工审核之后再上线。
5. 涉及个人的重大决策必须有人参与：在信贷、招聘、住房、医疗、法律等场景中，只能把模型作为决策辅助，并告知受影响的用户有 AI 参与了决策；不要使用不必要的敏感属性，并持续监控不同群体之间的结果差异。
6. 阈值不能跨后端照搬：三个模型的概率分布不同，置信度的计算方式也可能不同，切换或混用后端时要分别标定。
7. 固定版本，持续监控：固定部署的模型版本，升级（包括底座迁移）之后重新标定阈值，并持续监控概率分布和校准漂移。

总结

用一句话概括三者：

Microsoft-Decision-1 是“Azure 里的企业级决策组件”，Jev 是“开箱即用的云端通才”，Laya 是“可以特化的本地专才”。

• 如果你已经在用 Azure，需要统一的计费、身份认证和合规体系，或者想给 Agent 加一道低延迟的“决策闸门”，Microsoft-Decision-1 是最省事的选择；
• 如果你最看重置信度校准和长上下文，Jev 目前仍然更稳；
• 如果数据不能离开本地，或者需要毫秒级、海量的决策，并且有能力准备标注数据，Laya 依然不可替代。

从更大的视角看，Microsoft-Decision-1 的意义不只是“又多了一个决策模型”。微软带着开源底座、与 Jev 相同的价格和几乎一致的接口入局，说明了两件事：一是 state + questions 风格的决策接口正在成为事实标准，用户的迁移成本越来越低；二是底座正在变成可替换的零件，竞争的焦点转向了后训练数据、评测体系、校准质量和分发渠道。对开发者来说这是好消息：把决策从大模型里拆出来，已经从创业公司和开源社区的尝试，变成了大厂也认可的工程实践。

参考资料

• Microsoft Command Line：Introducing Microsoft-Decision-1, our model for fast decision-making
• Microsoft Learn：Deploy and use Microsoft-Decision-1 in Microsoft Foundry
• Microsoft Learn：Foundry Models sold by Azure
• Microsoft Foundry 模型目录：Microsoft-Decision-1
• JevBench：Hosted decision API benchmark
• JevBench：Open-weights decision model leaderboard
• TypeSafe 文档：Models
• Laya GitHub 仓库
• Jev vs Laya：闭源与开源 System One 决策模型的对比与选型

在上一篇文章中，我把 OpenWebUI 的数据库迁移到了 Azure 托管 PostgreSQL。在日常使用 OpenWebUI 的过程中，我经常遇到两个问题：

1. 问不到最新的信息：模型有知识截止时间，问到最近的版本发布、新闻或价格，要么答不上来，要么答错。
2. 贴进去的链接不会被打开：把文章、文档或 GitHub 页面的 URL 贴进对话框，想让模型总结、翻译或对比，模型却不会去读这个链接，有时甚至会根据 URL 猜出一段“看起来很像”的内容。

这两个问题都可以靠 OpenWebUI 的联网能力解决。本文使用微软新推出的 Microsoft Web IQ 作为联网搜索引擎，并让模型自动识别消息中的 URL、读取网页后再回答。整个过程只需要在 Azure 门户中创建一个 Web IQ 资源，再到 OpenWebUI 的管理界面中完成配置，不需要写代码，也不需要部署额外的服务。

本文基于 Open WebUI v0.11.4（2026 年 9 月发布），界面名称以英文界面为准。文中的 API Key 均为占位符。

最终效果

配置完成后：

• 提问涉及最新信息时，模型会自己调用 search_web，由 Web IQ 返回搜索结果，回答附带参考链接；
• 消息中出现 http:// 或 https:// 链接时，模型会自己调用 fetch_url，通过 Web IQ 读取页面正文后再回答，读取过的页面会出现在引用来源中；
• 两者可以在同一次回答中组合使用，例如先读取你给出的文档，再搜索最新的变更说明做对比。

为什么选择 Microsoft Web IQ

打开 OpenWebUI 的 Settings → Admin → Web Search，在 Web Search Engine 中可以找到 bing。选中后需要填写 Bing Search V7 Endpoint 和 Bing Search V7 Subscription Key，看起来只要填上 Azure 上 Bing 资源的密钥就能用，但这条路已经走不通了：

• Bing Search v7 API（包括 Bing Custom Search）已于 2025 年 8 月 11 日退役，已有实例全部下线，也无法再创建新资源；
• 现在 Azure 上能创建的 Bing 资源是 Grounding with Bing Search，它只能作为 Microsoft Foundry 智能体的工具使用，不能拿密钥直接调用搜索接口。想接入 OpenWebUI，就得自己开发一个桥接服务。

Microsoft Web IQ 是微软在 2026 年 6 月发布的一组面向 AI 应用的 API，用来为模型提供实时的网络信息（grounding），可以理解为“给 AI 智能体用的搜索引擎”：

• 基于 Bing 的全球索引构建，并针对智能体的多轮检索重新设计；
• 返回的不只是链接列表，而是带来源的相关段落，可以直接放进模型上下文，用更少的 token 得到更好的回答；
• 覆盖网页、新闻、图片、视频等内容，支持 100 多种语言和市场。

更重要的是，OpenWebUI 已经内置了 microsoft_web_iq 引擎。它既可以作为搜索引擎，也可以作为读取网页的网页加载引擎，只需要一个 API Key。

工作原理

用户消息
  │
  ▼
OpenWebUI（模型以原生工具调用方式工作）
  │
  ├── search_web：联网搜索
  │     └── Web IQ /search/web：返回标题、链接和相关段落
  │
  └── fetch_url：读取消息中的链接
        └── Web IQ /browse：读取网页，返回 Markdown 格式的正文

几点说明：

• search_web 和 fetch_url 是 OpenWebUI 的两个内置工具，同属 Web Search 类别，由模型自己决定何时调用；
• 这两个工具依赖原生工具调用（Native Function Calling），这是 v0.10.0 起的默认模式；
• 网页加载引擎也设为 Web IQ 之后，网页由 Web IQ 读取，需要 JavaScript 渲染的页面也能读到内容。PDF 等文件仍然由 OpenWebUI 下载后自行解析。

第一步：创建 Web IQ 资源并获取 API Key

Web IQ 以 Azure 资源的形式提供。在 Azure 门户中搜索 Microsoft Web IQ，进入 Microsoft Web IQ resources，点击 Create，在 Basics 页填写：

• Subscription 和 Resource group：选择用于管理和计费的订阅与资源组；
• Name：资源名称；
• Region：固定为 Global，这是一个可以跨 Azure 区域使用的全局资源。

点击 Review + create 完成创建，然后在资源页面中复制 API Key，下一步会用到。

Web IQ 目前仍处于有限访问（limited access）阶段。如果在 Azure 门户中找不到或者无法创建这个资源，可以先到 Microsoft Web IQ 官网 点击 Join the waitlist 申请。

第二步：配置 Web IQ 搜索和网页读取

以管理员身份登录 OpenWebUI，点击左下角的头像，进入 Settings → Admin → Web Search。

1. Search 部分

几点说明：

• Microsoft Web IQ API Base URL：OpenWebUI 已经预先填好，一般不需要修改；如果 Web IQ 资源页面显示了其他终结点，以资源页面为准；
• Language：技术类内容用 en 通常效果更好；如果主要查询中文资讯，可以改为 zh（以 Web IQ 支持的语言代码为准）；
• Fetch URL Content Length Limit：默认不截断，遇到很长的页面会占用大量上下文，建议设置上限；
• Web Search Confirmation：可选。开启后，用户在对话中使用联网搜索前会先看到确认提示，例如默认的 “Your query will be sent to the configured web search provider.”，提醒用户查询内容会发送到外部服务。

2. Loader 部分

点击 Save 保存，配置立即生效，不需要重启容器。

Web Loader Engine 也可以保持 Default，由 OpenWebUI 服务器自己抓取网页。但默认加载器读不到需要 JavaScript 渲染的内容，它的 User-Agent 也容易被部分网站拦截，交给 Web IQ 读取会省心很多。

第三步：让模型自动识别并读取消息中的 URL

1. 模型设置

进入 Settings → Admin → Models，编辑对话使用的模型：

其中 Default Features 很关键：原生模式下，只有模型启用了 Web Search 能力，并且当前对话打开了联网开关，search_web 和 fetch_url 才会提供给模型。不勾选的话，用户每次都要在输入框的 + 菜单中手动打开联网搜索，否则贴进来的链接不会被读取。

原生模式要求模型具备可靠的工具调用能力，建议使用较新的模型，太小或太旧的模型可能不会正确调用工具。

2. 系统提示词

是否调用 fetch_url 由模型自己决定。为了让行为更稳定，在同一个页面的 System Prompt 中加入以下规则：

你可以使用 search_web 和 fetch_url 两个工具：
1. 用户消息中出现以 http:// 或 https:// 开头的链接时，先调用 fetch_url 读取链接内容，再根据读取结果回答；有多个链接时逐个读取。
2. 问题涉及最新动态、版本、价格等时效性信息，或者你不确定答案时，调用 search_web 搜索；搜索结果中的摘要不够时，再用 fetch_url 打开最相关的结果。
3. 链接无法访问或内容为空时，如实告诉用户，不要根据链接地址推测页面内容。
4. 在回答末尾列出参考链接。

第 3 条用来防止模型在读取失败后“编”一段内容；第 4 条则是因为原生模式下，search_web 的结果不会出现在引用来源中，只有 fetch_url 读取过的页面才会，所以需要模型在回答中写出来。

3. 手动附加网页

如果希望某个链接一定被读取，也可以手动附加：

• 在输入框中输入 # 后粘贴链接，然后选择该网页；
• 或者通过输入框的 + → Attach Webpage 添加链接。

这两种方式由 OpenWebUI 直接读取页面（同样使用上面配置的网页加载引擎），不依赖模型的判断。

效果验证

1. 读取链接

新建一个对话，输入：

帮我总结这篇文档的要点：https://docs.openwebui.com/features/chat-conversations/web-search/providers/microsoft-web-iq

预期：

• 回答过程中显示模型调用了 fetch_url；
• 回答下方的引用来源中出现这篇文档；
• 回答内容与文档一致，而不是泛泛而谈。

2. 联网搜索

Open WebUI 最新发布的版本是多少？有哪些主要更新？

预期：

• 模型调用 search_web，结果来自 Web IQ；
• 如果摘要不够，模型会继续调用 fetch_url 打开发布说明页面；
• 回答末尾列出参考链接。

3. 组合使用

先读取 https://github.com/open-webui/open-webui/releases 的内容，再搜索一下社区对最新版本的反馈，最后给我一个是否升级的建议。

预期模型会先读取给出的链接，再根据需要多次搜索，最后综合两部分信息给出建议。

4. 排查问题

如果没有达到预期效果，可以先查看 OpenWebUI 的日志：

docker logs --since 10m open-webui 2>&1 |
grep -Ei 'web iq|microsoft browse|fetch_url|blocked'

常见的日志：

• Error searching with Microsoft Web IQ API：搜索请求失败，通常是 API Key 不正确或者尚未开通；
• Error browsing ... with Microsoft Web IQ：Web IQ 读取网页失败；
• Blocked ...：链接指向内网地址或者在过滤列表中，被 OpenWebUI 拦截。

也可以直接用 curl 验证 API Key，下面的请求格式与 OpenWebUI 实际发送的一致：

curl -sS https://api.microsoft.ai/v3/search/web \
  -H "x-apikey: $WEB_IQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "Open WebUI", "maxResults": 3, "language": "en", "contentFormat": "passage"}'

正常情况下会返回包含 webResults 的 JSON，每条结果都有 url、title 和 content。

注意事项

• 数据会发送到 Web IQ：搜索词和需要读取的链接会发送到 Web IQ API（api.microsoft.ai），数据如何处理以 Web IQ 的服务条款为准。敏感对话可以关闭联网开关，或者开启 Web Search Confirmation 提醒用户。
• 请求中会附带用户信息：从 v0.11.4 的源码看，调用 Web IQ 搜索时，OpenWebUI 会在请求头中附带当前用户的名称、ID、邮箱和角色（X-OpenWebUI-User-*），目前无法通过配置关闭。如果组织对此有要求，上线前需要评估。
• 内网链接无法读取：读取链接之前，OpenWebUI 会先校验 URL，默认禁止访问内网地址和云元数据地址。这些防护默认开启，无需额外配置，Web IQ 本身也访问不到内网页面。
• 调用次数与成本：每次 search_web 和 fetch_url 都是一次 Web IQ 调用，原生模式下模型还可能为一个问题连续调用多次。建议 Search Result Count 保持在 3～5，只在需要联网的模型上把 Web Search 设为默认功能。Web IQ 的费用计入创建资源时选择的 Azure 订阅，可以为资源组设置预算告警。

常见问题

总结

Bing Search API 退役之后，OpenWebUI 内置的 bing 引擎已经无法使用。借助 OpenWebUI 内置的 microsoft_web_iq 引擎，只需要在 Azure 上创建一个 Web IQ 资源并拿到 API Key，就可以在管理界面中完成联网搜索的接入：

• 搜索和网页读取都交给 Web IQ，返回的是适合直接放进模型上下文的段落和正文；
• 在原生工具调用模式下，search_web 负责搜索，fetch_url 负责读取消息中的链接；
• 通过模型的 Default Features 和系统提示词，让模型自动识别 URL、先读后答，并在回答中给出参考链接。

整个过程不需要写一行代码。无论是询问最新的信息，还是直接丢一个链接让模型总结，现在都可以在 OpenWebUI 中完成。

参考资料

• Announcing Microsoft Web IQ
• Microsoft Web IQ
• Open WebUI: Microsoft Web IQ
• Open WebUI: Agentic Web Search & URL Fetching
• Open WebUI: Bing
• Open WebUI: Hardening

引言

2026 年 9 月，AI 圈突然流行起一类“不会说话”的模型。

9 月 15 日，由前 OpenAI 研究员 Diogo Almeida 创办的 TypeSafe AI 发布了 Jev：它不聊天、不写文章、也不生成代码，只接收一段状态（state）和一组预先定义好的问题，然后直接返回带有校准概率的结构化决策。

仅仅三天后，9 月 18 日，独立研究者 Nandakishor M（Convai Innovations）开源了 Laya。它同样是一个非自回归的 System 1 决策模型，采用 Apache 2.0 协议，权重可以直接从 Hugging Face 下载，三天内 GitHub 星标就超过了 6000，被社区称为“开源版 Jev”。

一边是背靠 4000 万美元种子轮、开箱即用的闭源 API，一边是 4.2 亿参数、一张 T4 甚至一台 MacBook 就能跑起来的开源模型。社交媒体上“Laya 反超 Jev”“Jev 的护城河只维持了两天”之类的说法很多，但如果把双方公开的资料仔细读一遍，就会发现结论远没有这么简单。

本文将从以下几个方面展开：

1. 什么是决策模型，它要解决什么问题
2. Jev 与 Laya 各自的技术路线
3. 核心差异与基准数据解读
4. 两者各自的优势与劣势
5. 适用场景与选型建议

什么是决策模型（System One Model）

1. 名字的由来

“System One”来自丹尼尔·卡尼曼的《思考，快与慢》：System 1 是快速、直觉式的判断，System 2 是缓慢、审慎的推理。在这个比喻下，生成式大模型（尤其是推理模型）更像 System 2，而决策模型负责的是毫秒级的“直觉反应”。

顺带一提，Jev 这个名字来自经济学家威廉·斯坦利·杰文斯（William Stanley Jevons）。TypeSafe 认为机器智能会重演“杰文斯悖论”：就像蒸汽机效率提升反而带动了煤炭需求一样，智能的单价每下降一个数量级，都会解锁更多数量级的新用例。

2. 用大模型做“选择题”的痛点

在真实的 AI 工程里，大量决策其实都是“小事”：

• 这张工单应该分给哪个团队？
• 这封邮件是不是钓鱼邮件？
• 这段提示词有没有注入攻击？
• Agent 下一步该调用哪个工具？上一步执行成功了吗？

今天常见的做法，是把这些问题交给一个擅长写作的大模型，再从它生成的文本里把答案“抠”出来。这会带来一系列问题：

3. 决策模型的思路

决策模型干脆把“生成”这一步删掉了。TypeSafe 用一句话概括它：

Unstructured state in, typed probabilistic decisions out.

非结构化的状态输入，带概率的类型化决策输出。

调用方只需要提交两部分内容：

• state：需要判断的当前状态，可以是字符串、JSON 对象或文本数组
• questions：一组类型化问题，每个问题的候选答案都由调用方提前定义

模型并行地回答所有问题，只返回数字和概率。Jev 与 Laya 采用了完全相同的三种问题原语：

由于输出空间被提前限定，模型不可能返回类型错误或凭空编造的选项。但需要注意：类型安全不等于判断正确，它仍然可能在合法的选项里选错，这一点后文会反复提到。

4. 它在系统中的位置

决策模型并不是用来取代大模型的，而是把大模型从一些“本不该由它来做”的位置上挪开。一个比较合理的分工是：

代码（确定性逻辑）
  └─ 流程编排、权限控制、数学与日期计算、执行动作
        │  遇到需要语义理解的“模糊 if 语句”
        ▼
决策模型（System 1：Jev / Laya）
  └─ 分类、路由、打分、校验、护栏，返回类型化答案 + 概率
        │  置信度不足，或需要生成文本 / 复杂推理
        ▼
大模型（System 2：GPT / Claude / DeepSeek 等）
  └─ 长上下文理解、规划、写作、代码生成

有了校准过的置信度，程序的控制流就不再只有“是 / 否”两种状态，而可以分成三档：高置信度自动执行，中置信度交给更强的模型复核或请求用户确认，低置信度转人工。这也是决策模型真正的价值所在：速度只是表象，可以被写进 if 语句的置信度才是关键。

两位主角

Jev：TypeSafe AI 的闭源云端服务

基本信息

• 发布时间：2026 年 9 月 15 日，以 early access 形式开放
• 团队背景：TypeSafe AI 是一家旧金山公司，创始人 Diogo Almeida 曾在 Google Brain 和 OpenAI 从事研究，是 InstructGPT 论文和 GPT-4 技术报告的作者之一。发布当天，公司同时宣布了由 DCVC 领投的 4000 万美元种子轮融资
• 产品形态：闭源，只提供 API（POST https://api.typesafe.ai/v1/systemone）以及 Python / JavaScript SDK
• 当前版本：Jev 1.13（jev-1.13.0），别名 jev-latest

技术路线

TypeSafe 声称为自动化场景重建了一整套技术栈：全新的模型架构、追求极致效率的并行采样器，以及一种名为 RLCD（Reinforcement Learning for Calibrated Decisions，面向校准决策的强化学习） 的训练方法。与 RLHF 优化“人类偏好”、RLVR 优化“可验证奖励”不同，RLCD 的目标是让模型在给出答案的同时，给出认知上诚实的概率。

不过，TypeSafe 目前并没有公开模型架构、参数规模和训练数据。社区有不少人认为它更接近 BERT 这类 encoder 模型，但这只是猜测。

关键规格

按这个定价计算，如果每次判断平均消耗 1000 个输入 token，100 万次判断的费用只有约 42 美元。

生态

Jev 发布后迅速走红：LangChain 很快发布了集成指南，Vercel 把它接入了 AI Gateway，社区也涌现出不少实验项目，比如用 Jev 给 Claude Code 的工具调用输出做相关性打分、进而压缩上下文的 fast-jev-compaction。

Laya：Convai Innovations 的开源本地模型

基本信息

• 发布时间：2026 年 9 月 18 日
• 作者：独立研究者 Nandakishor M（Convai Innovations）
• 开源协议：Apache 2.0，代码、权重、训练方法和微调 Notebook 全部公开
• 获取方式：pip install laya（要求 Python 3.10+），权重托管在 Hugging Face 的 convaiinnovations/laya

Laya 的诞生还有一段插曲。作者在 2025 年就先后发表过两篇相关论文（arXiv:2503.23303、arXiv:2510.01237），研究用强化学习训练非自回归的决策模型，最早用于预测销售对话的转化率。看到 Jev 以“突破”之名发布后，他把旧方案的架构缺陷全部修了一遍，做出了这个通用的开源版本。

模型架构

Laya 采用“双向编码器 + 决策头”的结构，总参数量 421M：

State（文本或 JSON）+ 类型化问题与选项
        │ 拼接为：[CLS] 问题 [SEP] [MASK] 选项1 [MASK] 选项2 ... [SEP] state [SEP]
        ▼
ModernBERT-large 编码器（395M，28 层双向注意力）
        ▼
决策头 Transformer（约 25M，2 层）
        ├─ 选项打分器：取每个 [MASK] 位置的隐状态 → logit → 温度缩放 → softmax
        └─ Act / Escalate 头：基于 [CLS] 与分布统计量，判断“自动执行”还是“升级处理”

每个选项前面放一个 [MASK] 标记，经过双向编码器之后，从这些标记的位置取出隐状态进行打分。同一个 state 上的多个问题会组成一个 batch，在一次前向传播中完成计算。

三个检查点 + 路由器

Laya 内置了一个纯 Python 实现的 Router，会在前向计算之前用不到 1 毫秒的时间检测文本的书写系统和语言，然后自动选择合适的检查点。之所以需要它，是因为英文检查点在非拉丁文字上会“自信地犯错”：在高棉语测试中，它的准确率为 0，置信度却高达 0.952。这种情况下，靠置信度阈值是拦不住的。

开放的 RLCD 实现

Laya 沿用了 RLCD 这个名字，并公开了具体做法：用严格适当评分规则（strictly proper scoring rules，由对数评分、球面评分和排序概率评分组合而成）作为奖励，采用 GRPO 风格的组内基线策略梯度进行训练，完全不使用监督交叉熵损失。严格适当评分规则的特点是：只有当模型报告真实的概率时，才能拿到最高的期望奖励，从而“逼”模型说实话。

Act / Escalate 头则用一个代价矩阵来训练：判对奖励 +1，判错惩罚 -3，升级人工惩罚 -0.5。由此可以推导出，只有当正确率超过 62.5% 时，自动执行才比升级人工更划算，模型也就学会了“没把握就上交”。

此外，Laya 还提供了开箱即用的工作流预设（模型路由、提示词护栏、内容审核、工单分诊），以及一个可以在 Kaggle 免费 2×T4 GPU 上运行的微调 Notebook：在约 3 万个问题上训练 4 个 epoch，耗时 4～5 小时。

核心差异一览

基准数据怎么看

1. Laya 公布的对比数据

Laya 的 README 中给出了一张与 Jev 1.13.0 的对比表（Laya 一侧为经过 Router 路由后的实测结果）：

乍一看，Laya 几乎全面领先。但如果只看这张表就下结论，很容易踩坑。

2. 解读数据时必须注意的五点

第一，Jev 的数据并非同场实测。 Laya 作者明确说明，自己没有 TypeSafe 的 API 权限，表中 Jev 的数字全部引用自第三方公开的结果，样本量和提示词都不相同。

第二，Laya 的高分来自针对性微调。 typed-decisions 上的 0.766 是 laya-typed-decisions 在该基准自己的训练集上微调后取得的成绩。未经微调的两个基础检查点只有 0.34～0.36，接近随机猜测（0.318），甚至低于“每题都猜最常见类别”的基线（0.461），而 Jev 不做任何训练就能拿到 0.727。作者自己也说得很直白：Laya 是一个适合特化的快速底座，而不是零样本决策引擎。 换句话说，这张表比的其实是“特化后的专才”和“零样本的通才”。

第三，校准优势需要额外的温度拟合。 表中 0.081 的 ECE 是用领域留出数据重新拟合温度之后的结果，出厂时为 0.466。而在同一个 typed-decisions 基准上，Laya 微调检查点的 ECE 为 0.213，反而高于 Jev 的 0.144；在衡量概率分布与参考分布吻合程度的“软准确率”上，Jev 也以 0.580 领先 Laya 的 0.471。当然 Jev 也并非完美：Laya 作者引用的数据显示，在 DAIR Emotion 上，Jev 对 16% 的样本给真实标签分配了 0 概率，这对依赖置信度做分流的系统来说是个硬伤。

第四，延迟对比的本质是部署方式的差异。 Jev 的延迟包含从客户端到 TypeSafe 云端的网络往返（TypeSafe 的评测大多从美国西海岸发起），而 Laya 的 32.8 ms 是在本地 T4 GPU 上的推理耗时。对于国内或其他地区的用户，Jev 的实际延迟还要叠加跨境网络的开销；反过来，如果把 Laya 部署成远程服务，同样要算上网络开销。

第五，Jev 自己的宣传数据同样需要打折。 TypeSafe 官网上“快 193.6 倍、便宜 444.6 倍”的数字来自其团队设计的 4 套工作流评测，参考答案取自 GPT-6 Astra 和 Fable 5.1 两个前沿模型的平均结果，官方也坦言这些数字处于真实收益的上限。自动化服务公司 AY Automate 发布的第三方测试则显示：Jev 比几款对照模型快约 2～3.6 倍；成本方面，相比便宜的小模型约节省 4.7～7.5 倍，相比昂贵的前沿模型才能达到 40～49 倍。

3. 社区实测

发布后短短几天，社区就做了不少对比测试，大多集中在高频交互场景：

• 贪吃蛇：在同一套决策逻辑下，本地运行的 421M Laya 在 30 秒内平均每秒决策 86.5 次，P50 延迟约 9 ms；云端 Jev 每秒只能决策 3.2 次，API 往返约 317 ms
• M5 Pro 测试：两者的中位耗时分别为 15.3 ms 和 298.1 ms，差距接近 20 倍
• Apple Silicon 移植：社区项目 laya-mlx 把模型移植到 MLX，运行时最高约占 1GB 内存，在 M3 Max 上运行贪吃蛇可以达到每秒 60 次决策

这些测试体现的主要是“本地推理”与“云端往返”的差异。对于每秒需要几十次决策的实时场景，这个差距是决定性的；但对于一次工单分流来说，30 ms 和 300 ms 的区别，用户几乎感知不到。

4. 小结

比较公允的结论是：在开箱即用、长上下文、选项复杂的场景下，Jev 更强；在有标注数据的垂直任务上，经过微调的 Laya 可以做到更快、更准、更便宜。

Jev 的优势与劣势

优势

1. 开箱即用，零样本能力强：不需要任何训练数据，写好 state 和问题就能直接使用。TypeSafe 称 Jev 在 System One 类任务上达到了与现有前沿 LLM 相近的智能水平；Karpathy 也评价说，它处在 LLM 帕累托曲线上一个长期被低估的位置：不需要复杂思考，只需要在低延迟下给出足够可靠的判断。
2. 长上下文与高基数选项：64k 的上下文可以直接放入长邮件串、合同条款或 Agent 执行轨迹；choice 最多支持 255 个选项，在 Banking77 这类细粒度意图分类上仍有 0.870 的准确率。
3. 出厂即校准：不需要自己拟合温度，返回的概率可以直接用于阈值分流；官方文档还给出了按风险等级设置不同阈值的最佳实践。
4. 免运维，生态成熟：托管服务加官方 SDK，已经接入 LangChain、Vercel AI Gateway 等生态，团队不需要操心 GPU、扩缩容和模型升级。
5. 单价极低：按每次 1000 个输入 token 估算，100 万次判断约 42 美元，对大多数业务来说，模型费用已经不是瓶颈。

劣势

1. 闭源黑盒：架构、参数量和训练数据都没有公开。决策模型本身也不输出解释，正如 Simon Willison 所提醒的，Jev 最终留给开发者的可能只有一个数字，判断出错时很难追问原因。
2. 数据必须出域：所有 state 都要发送到 TypeSafe 的云端，零数据保留（ZDR）仅面向企业客户，这对金融、医疗、政企等场景是硬伤。另据媒体报道，Jev 目前尚未面向中国大陆开放。
3. 网络延迟无法消除：几百毫秒的往返对于业务工作流已经足够快，但对于游戏 AI、实时风控这类每秒几十次决策的场景仍然太慢。
4. 无法微调：所有客户共用同一套权重，只能通过 state、instructions 和 criteria 来“调教”，在高度垂直的领域可能达不到专用模型的效果。
5. 英语优先：官方明确英语是主要训练语言，中文场景一定要先用自己的数据验证。
6. 早期产品的不确定性：速率限制仍在动态调整；官方预计价格只降不升，但也坦言暂时无法证明当前价格没有补贴；jev-latest 别名会随新版本移动，调好的阈值可能需要重新标定；此外还有厂商锁定的风险。
7. 已知的能力“锯齿”：官方文档专门列出了 Jev 1.13 的多种失效模式，包括过于字面地理解问题、不擅长计数和数学运算、日期比较不可靠、多跳的间接推理效果差、state 中无关内容过多会降低准确率、容易被 state 中的对抗内容（如提示词注入）带偏等。甚至一些“常识性”的一致性也无法保证：对同一个问题和它的否定分别提问，两个 noul 的概率之和可能是 1.19，而不是 1。

Laya 的优势与劣势

优势

1. 完全开源：Apache 2.0 协议，架构、训练方法、评测脚本和微调 Notebook 全部公开，可审计、可复现、可二次开发，没有厂商锁定。
2. 数据不出域：可以部署在本地、私有云甚至离线环境中，天然满足数据驻留和隐私合规的要求。
3. 极低延迟、高吞吐：T4 上单个问题约 33～40 ms，多语言检查点批量推理时每题约 7 ms，单卡吞吐约 100～330 题/秒，在实时交互类应用中优势明显。
4. 边际成本接近零：按单张 T4 每秒 100～300 题估算，100 万次判断只需要 1～3 个 GPU 小时。
5. 可微调、可特化：在自有数据上微调后可以超越 Jev（typed-decisions 上 0.766 对 0.727），而且整个流程在 Kaggle 的免费 GPU 上就能完成。
6. 多语言与自动路由：laya-multilingual 覆盖 100 多种语言，Router 会在推理前自动选择检查点，对中文等非英语场景更友好（但仍需自测）。
7. 面向生产的设计：Act / Escalate 头可以直接给出“自动执行还是升级人工”的建议；内置了护栏、审核、分诊等预设；文档还坦诚地列出了自身的各项短板。

劣势

1. 零样本能力弱：基础检查点在 typed-decisions 上接近随机水平，想要好的效果，就必须准备标注数据并进行微调。没有数据的团队拿到手的，基本上只是一个“待训练的底座”。
2. 上下文短：英文检查点默认只有 512 token（留给 state 的约 320 token），多语言和 typed-decisions 检查点为 1024 token（留给 state 的约 768 token）。长文档、长对话需要先做截断、摘要或分块。编码器最高支持 8192 token，但调大之后延迟会上升，效果也需要自行验证。
3. 高基数选项吃力：所有选项共享一个固定的 token 预算，77 个选项时每个选项只能分到 3～4 个 token，Banking77 的准确率随之跌到 0.425。需要调大 head_max_len、先用 embedding 做候选筛选（predict_shortlist），或者拆成“粗分类 + 细分类”两级问题。
4. 校准需要额外工作：出厂的检查点偏向“过度自信”，需要用领域内的留出数据拟合温度（ECE 可以从 0.466 降到 0.081）；多语言检查点出厂时则完全没有拟合温度。
5. score 是最弱的原语：有序打分任务的表现最差，例如 SST-5 五级情感分类的准确率只有 0.372。
6. 语言陷阱：英文检查点在非拉丁文字上会高置信度地犯错，必须使用 Router 或手动选对检查点。另外，默认的懒加载模式下切换语言会触发 7～10 秒的模型重载，生产环境需要开启预加载。
7. 运维与项目成熟度：需要自己负责 GPU 资源、扩缩容、监控和模型版本管理；项目刚刚发布，主要由独立研究者维护，长期演进存在不确定性。

适用场景与选型建议

1. 场景对照表

关于最后一点再多说一句：Laya 在未参与训练的提示词注入测试集上的准确率约为 0.698，Jev 的官方文档也承认 state 中的对抗内容可能带偏判断。决策模型可以作为一道低成本的前置过滤，但不能作为唯一的安全防线。

2. 选型时要回答的几个问题

可以按下面的顺序依次回答：

1. 数据能否发送到第三方云（以及境外）？
   └─ 不能 → Laya（硬约束，其他因素都要让路）
2. 是否有标注数据，并且愿意投入微调？
   └─ 没有 → Jev
3. 是否需要每秒几十次以上的实时决策，或者要在端侧运行？
   └─ 是 → Laya
4. state 是否很长（超过 1k token），或者选项是否很多（超过 20 个）？
   └─ 是 → Jev（或 Laya + 分块 / 候选筛选）
5. 月调用量是否达到数千万级？
   └─ 是 → 倾向 Laya；否则 Jev 的总拥有成本通常更低

关于成本，可以简单算一笔账：假设每次判断消耗 1000 个输入 token，Jev 每 100 万次判断约 42 美元；一台 T4 实例全天候运行，按每小时约 0.5 美元估算，每月约 360 美元，相当于 Jev 约 850 万次判断的费用，这还没算高可用冗余和运维人力。所以单纯从成本角度看，只有当调用量足够大时，自托管 Laya 才有明显优势。更多时候，选择 Laya 的理由应该是延迟、合规和可定制性，而不仅仅是省钱。

3. 组合使用：不必二选一

在实际项目中，两者完全可以组合使用：

1. 阶段式迁移：先用 Jev 快速上线，验证问题拆解、选项设计和置信度阈值是否合理，同时沉淀真实数据和人工复核的标签；当调用量上来或合规要求收紧时，再用这些人工标签微调 Laya，迁移到自托管。由于两者的请求格式（state + questions，以及 choice / score / noul 的 instructions、criteria 结构）几乎一致，迁移成本很低。需要注意的是，如果打算直接把 Jev 的输出当作训练标签，请先确认 TypeSafe 的服务条款；Laya 作者也提醒过，用模型生成的标签来训练，只会把新模型校准到“老师”的错误上。
2. 分层级联：本地 Laya 处理高频、简单、短文本的判断；低置信度或长上下文的请求升级给 Jev；Jev 仍然拿不准的，再交给推理型大模型或人工处理。
3. 按数据敏感度路由：涉及个人隐私或敏感业务数据的请求走本地 Laya，其余请求走 Jev。

4. 其他选择

除了这两者，社区还出现了一条“零训练复刻”的路线：直接读取现成开源 LLM 在候选项上的 token 概率来模拟 Jev 的输出。例如 SemIf 用一个现成的 4B 开源模型直接读取概率，据称与 Jev 的结论一致率在 85% 左右；Kev 则基于 Qwen 3.5 制作了 0.8B、4B 和 9B 三个 Jev-like 模型。这类方案在门槛和效果上介于两者之间，适合想先低成本尝鲜的团队。

代码示例：同一组问题，两种调用方式

由于 Jev 和 Laya 的问题格式几乎一致，同一组 state 和 questions 可以同时用于两者：

state = {
    "message": "I was charged twice for order A-104. Please refund the duplicate.",
    "order": {"charges": [49, 49]},
}

questions = {
    "department": {
        "type": "choice",
        "instructions": "Which team should handle this request?",
        "criteria": {
            "billing": "Payments, invoices, and refunds",
            "technical": "Bugs and integrations",
            "account": "Account access and profile issues",
        },
    },
    "urgency": {
        "type": "score",
        "instructions": "How urgent is this request?",
        "criteria": ["Not urgent", "Soon", "Critical or blocking"],
    },
    "refund_requested": {
        "type": "noul",
        "instructions": "Does the message request a refund?",
    },
}

调用云端的 Jev（固定版本号，避免别名升级后调好的阈值失效）：

import os
import requests

resp = requests.post(
    "https://api.typesafe.ai/v1/systemone",
    headers={"Authorization": f"Bearer {os.environ['TYPESAFE_API_KEY']}"},
    json={"model": "jev-1.13.0", "state": state, "questions": questions},
    timeout=5,
)
resp.raise_for_status()
answers = resp.json()["answers"]

在本地运行 Laya：

from laya import Router

# 生产环境建议预加载，避免切换语言时重新加载模型
router = Router(preload=True)
answers = router.predict(state, questions)["answers"]

两者返回的结构基本相同：choice 包含 choice、probabilities 和 confidence，score 包含期望分数、等级概率分布和 confidence，noul 则直接返回“是”的概率。后续的置信度分流逻辑可以完全复用：

dept = answers["department"]

if dept["confidence"] >= 0.9:
    route_to_team(dept["choice"])     # 高置信度：自动执行
elif dept["confidence"] >= 0.6:
    review_with_llm(state, dept)      # 中置信度：交给更强的模型复核
else:
    send_to_human(state)              # 低置信度：转人工

这里的 0.9 和 0.6 只是示意，真实的阈值一定要用自己的数据来标定。

落地时的共同注意事项

无论选择哪一个，以下几点都同样适用：

1. 类型安全 ≠ 判断正确：校准描述的是一组预测的统计性质，并不保证单个答案正确，阈值必须用自己的数据标定。
2. 把问题拆小：不要问“这张工单该怎么处理”，而是拆成“是否申请退款”“紧急程度如何”“属于哪条业务线”等原子问题，再在代码里组合。
3. 计算交给代码：计数、数学运算、日期比较等确定性逻辑不要交给模型。
4. 精简 state：只放与问题相关的字段，无关内容会降低准确率；Laya 的上下文更短，这一点尤为关键。
5. 不可逆操作要兜底：付款、删除数据、医疗或合规审批等操作，不能仅凭一个概率就自动执行。
6. 防范注入：state 虽然是数据，但其中的恶意内容仍可能影响判断，不要把决策模型当作唯一的安全防线。
7. 固定版本，持续监控：固定模型版本（如 jev-1.13.0 或指定的 Laya 检查点），升级后重新标定阈值；上线后持续记录概率分布、抽样复核，并监控校准漂移。

总结

用一句话概括：

Jev 是“开箱即用的云端通才”，Laya 是“可以特化的本地专才”。

• 如果你追求快速上线、手上没有标注数据，或者面对长上下文和复杂的选项空间，Jev 是更省心的选择；
• 如果你有数据、有合规要求、需要毫秒级的实时决策或海量调用，并且有能力运维一个小模型，Laya 更值得投入。

两者并不是替代关系，而是同一条“决策光谱”上的不同档位。更值得关注的是这场对决背后的趋势：AI 系统正在从“一个大模型包打天下”走向分工协作，代码负责骨架，决策模型负责快速判断，大模型负责深度思考。Jev 定义了这个品类，Laya 则在三天之内证明了开源社区可以迅速跟上。对开发者来说，这意味着工具箱里又多了一种更快、更便宜、也更可控的构建模块。

参考资料

• TypeSafe AI：Introducing System One Models & Jev
• TypeSafe 文档：Models
• TypeSafe 文档：Jev 1.13 jaggedness
• TypeSafe 文档：Confidence
• TypeSafe Workflow Evals
• Laya GitHub 仓库
• Laya Hugging Face 模型页
• Nandakishor M：I Built Non-Autoregressive Decision Models a Year Ago. Then a Frontier Lab Called It a “Breakthrough”.
• 虎嗅：号称快200倍的Jev模型，拿不下LLM的大结果

在普通 HTTP API 中，我们通常只需要限制“每分钟请求数”。但对于大模型接口，仅限制请求数量远远不够：一次请求可能只消耗几十个 Token，也可能消耗数万个 Token。

因此，一个实用的 AI 网关通常需要同时支持：

• RPM（Requests Per Minute）：每分钟请求数。
• TPM（Tokens Per Minute）：每分钟 Token 数。
• 按租户、API Key、模型或套餐分别计费。
• 多个 Envoy 实例共享同一份额度。
• 在高并发条件下避免各实例独立计数造成额度放大。
• 返回统一的 429 Too Many Requests 和剩余额度信息。

本文介绍如何使用 envoyproxy/ratelimit、Redis 和 Envoy 构建一套分布式 AI 限流系统。

为什么不能只使用 Envoy Local Rate Limit

Envoy 提供了 Local Rate Limit Filter，但它的计数器默认位于当前 Envoy 进程中。

假设我们有 4 个 Envoy 实例，并为某个租户配置：

RPM = 100

如果每个 Envoy 都独立维护 100 RPM，那么整个集群实际上可能放行：

4 × 100 = 400 RPM

这显然不是我们想要的结果。

Envoy 的 Global Rate Limit Filter 可以把限流请求发送给外部 Rate Limit Service。envoyproxy/ratelimit 正是 Envoy 官方生态中常用的全局限流服务实现，它将计数器存放在 Redis 中。

整体架构如下：

这里增加了一个很薄的 AI Quota Adapter，主要用于解决两个问题：

1. 从请求体中解析模型、租户和 Token 数量。
2. 分别使用不同的 hits_addend 检查 RPM 和 TPM。

为什么 AI TPM 需要额外的适配层

Envoy 的普通限流规则通常把一次 HTTP 请求视为一次命中：

hits_addend = 1

这适合 RPM，但不适合 TPM。

例如下面两个请求：

请求 A：消耗 200 Token
请求 B：消耗 20,000 Token

如果两者都只增加一次计数，TPM 就没有意义。TPM 必须让一次请求按照 Token 数增加计数器：

hits_addend = token_cost

例如：

RPM 请求：hits_addend = 1
TPM 请求：hits_addend = 3200

Rate Limit Service 的 hits_addend 通常作用于整个 RateLimitRequest，因此 RPM 和 TPM 需要使用两次限流调用，或者由自定义适配服务组合处理。

推荐的处理顺序是：

1. 检查并增加 RPM，hits_addend=1。
2. RPM 允许后，再检查并增加 TPM，hits_addend=token_cost。
3. 任意一个返回 OVER_LIMIT，适配层向 Envoy 返回 429。

这种模式下，每个维度都由 Redis 原子计数，多个 Envoy 实例不会各自放大额度。

需要注意：两次调用并不是跨计数器事务。RPM 已增加后，TPM 可能拒绝请求。因此要提前明确计数语义：

• RPM 统计所有进入限流流程的请求尝试；或者
• 自行扩展服务，使用一段 Redis Lua 脚本同时检查 RPM 和 TPM。

多数系统接受第一种语义，因为它更简单，也能避免恶意用户通过大量超大请求免费消耗网关资源。

设计限流 Descriptor

限流维度通常包括：

• tenant：租户、组织或 API Key。
• model：模型名称。
• metric：rpm 或 tpm。

最终生成的 Descriptor 可以表示为：

tenant = tenant-a
model  = gpt-4.1
metric = rpm

以及：

tenant = tenant-a
model  = gpt-4.1
metric = tpm

这样可以实现：

tenant-a + gpt-4.1 -> 60 RPM
tenant-a + gpt-4.1 -> 100,000 TPM

如果不希望按模型拆分额度，也可以只保留：

tenant + metric

例如所有模型共享同一份租户额度。

配置 envoyproxy/ratelimit

创建 config/config.yaml：

domain: ai-gateway

descriptors:
  - key: tenant
    descriptors:
      - key: model
        descriptors:
          - key: metric
            value: rpm
            rate_limit:
              unit: minute
              requests_per_unit: 60

          - key: metric
            value: tpm
            rate_limit:
              unit: minute
              requests_per_unit: 100000

这里 tenant 和 model 没有指定固定值，可用于根据请求中的 Descriptor 值进行分桶。实际部署前，应使用所选 ratelimit 版本提供的配置校验工具检查配置。

适配层发送 RPM Descriptor：

[
  {"key": "tenant", "value": "tenant-a"},
  {"key": "model", "value": "gpt-4.1"},
  {"key": "metric", "value": "rpm"}
]

发送 TPM Descriptor：

[
  {"key": "tenant", "value": "tenant-a"},
  {"key": "model", "value": "gpt-4.1"},
  {"key": "metric", "value": "tpm"}
]

Descriptor 的顺序必须与配置中的嵌套路径一致。

不同套餐额度

如果不同租户拥有不同额度，可以增加套餐维度：

tenant -> plan -> model -> metric

例如：

domain: ai-gateway

descriptors:
  - key: tenant
    descriptors:
      - key: plan
        value: standard
        descriptors:
          - key: model
            descriptors:
              - key: metric
                value: rpm
                rate_limit:
                  unit: minute
                  requests_per_unit: 60

              - key: metric
                value: tpm
                rate_limit:
                  unit: minute
                  requests_per_unit: 100000

      - key: plan
        value: enterprise
        descriptors:
          - key: model
            descriptors:
              - key: metric
                value: rpm
                rate_limit:
                  unit: minute
                  requests_per_unit: 1000

              - key: metric
                value: tpm
                rate_limit:
                  unit: minute
                  requests_per_unit: 2000000

请求中的 tenant 用于隔离计数器，plan 用于选择额度。

不要只使用 plan 作为计数维度，否则所有 Standard 用户可能共享同一个计数器。

五、使用 Docker Compose 部署

下面是一个简化示例：

services:
  redis:
    image: redis:7-alpine
    command:
      - redis-server
      - --appendonly
      - "yes"
    volumes:
      - redis-data:/data
    ports:
      - "6379:6379"

  ratelimit:
    image: envoyproxy/ratelimit:<固定版本号>
    command: /bin/ratelimit
    environment:
      LOG_LEVEL: info

      REDIS_SOCKET_TYPE: tcp
      REDIS_URL: redis:6379

      RUNTIME_ROOT: /data
      RUNTIME_SUBDIRECTORY: ratelimit
      RUNTIME_WATCH_ROOT: "false"

      USE_STATSD: "false"
    volumes:
      - ./config:/data/ratelimit
    ports:
      - "8081:8081"
      - "6070:6070"
    depends_on:
      - redis

volumes:
  redis-data:

生产环境不要直接使用 master 或浮动标签，应固定到经过验证的 release 版本。

不同版本的镜像端口和环境变量可能存在差异，因此部署时应以对应版本仓库中的示例配置为准。

启动：

docker compose up -d

查看日志：

docker compose logs -f ratelimit

生产环境可以运行多个 ratelimit 副本：

ratelimit-1 ─┐
ratelimit-2 ─┼── Redis
ratelimit-3 ─┘

ratelimit 服务本身可以保持无状态，只要所有副本：

• 使用相同的配置。
• 指向同一个 Redis 逻辑集群。
• 使用一致的 Redis Key 前缀或命名空间。

AI Quota Adapter 的核心逻辑

适配层可以实现为 Envoy ext_authz 服务。它接收 Envoy 转发过来的请求信息，完成身份识别、Token 计算和额度检查。

下面是简化后的 Go 伪代码：

func CheckAIQuota(
    ctx context.Context,
    tenant string,
    model string,
    tokenCost uint32,
) error {
    // 第一次调用：RPM
    rpmResp, err := rateLimitClient.ShouldRateLimit(
        ctx,
        &ratelimitv3.RateLimitRequest{
            Domain: "ai-gateway",
            Descriptors: []*ratelimitv3.RateLimitDescriptor{
                {
                    Entries: []*ratelimitv3.RateLimitDescriptor_Entry{
                        {Key: "tenant", Value: tenant},
                        {Key: "model", Value: model},
                        {Key: "metric", Value: "rpm"},
                    },
                },
            },
            HitsAddend: 1,
        },
    )
    if err != nil {
        return err
    }

    if rpmResp.OverallCode ==
        ratelimitv3.RateLimitResponse_OVER_LIMIT {
        return ErrRPMExceeded
    }

    // 第二次调用：TPM
    tpmResp, err := rateLimitClient.ShouldRateLimit(
        ctx,
        &ratelimitv3.RateLimitRequest{
            Domain: "ai-gateway",
            Descriptors: []*ratelimitv3.RateLimitDescriptor{
                {
                    Entries: []*ratelimitv3.RateLimitDescriptor_Entry{
                        {Key: "tenant", Value: tenant},
                        {Key: "model", Value: model},
                        {Key: "metric", Value: "tpm"},
                    },
                },
            },
            HitsAddend: tokenCost,
        },
    )
    if err != nil {
        return err
    }

    if tpmResp.OverallCode ==
        ratelimitv3.RateLimitResponse_OVER_LIMIT {
        return ErrTPMExceeded
    }

    return nil
}

实际代码中的 protobuf 包名和字段类型应以项目锁定的 Envoy API 版本为准。

适配层的完整处理流程如下：

1. 从 Authorization/API Key 中识别 tenant
2. 从 JSON 请求体中读取 model
3. 使用模型对应的 tokenizer 计算 input_tokens
4. 根据策略计算 token_cost
5. 调用 RLS 检查 RPM
6. 调用 RLS 检查 TPM
7. 都允许：返回 OK
8. 任意超限：返回 429

在 Envoy 中接入适配层

如果适配层实现 Envoy 的 ext_authz gRPC 协议，可以在 Envoy 中配置：

http_filters:
  - name: envoy.filters.http.ext_authz
    typed_config:
      "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthz

      transport_api_version: V3

      grpc_service:
        envoy_grpc:
          cluster_name: ai_quota_adapter
        timeout: 0.5s

      with_request_body:
        max_request_bytes: 1048576
        allow_partial_message: false
        pack_as_bytes: true

      failure_mode_allow: false

  - name: envoy.filters.http.router
    typed_config:
      "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router

对应的 Cluster：

clusters:
  - name: ai_quota_adapter
    type: STRICT_DNS
    connect_timeout: 0.25s

    http2_protocol_options: {}

    load_assignment:
      cluster_name: ai_quota_adapter
      endpoints:
        - lb_endpoints:
            - endpoint:
                address:
                  socket_address:
                    address: ai-quota-adapter
                    port_value: 9000

因为 Token 计算需要读取 JSON 请求体，所以需要配置 with_request_body。

注意限制最大请求体，避免攻击者提交超大 Prompt 导致 Envoy 或适配层内存压力。

TPM 应该如何计算

RPM 的定义比较简单，一次请求增加 1。

TPM 更复杂，因为请求发出时通常只知道输入 Token，尚不知道模型最终会产生多少输出 Token。

方案一：只计算输入 Token

token_cost = input_tokens

优点：

• 请求开始前就能精确计算。
• 实现最简单。
• 非流式和流式接口都适用。

缺点：

• 无法限制输出 Token。
• 用户可能通过很短的 Prompt 请求大量输出。

适合将 TPM 定义为“输入 Token 配额”的系统。

方案二：预留最大输出 Token

token_cost = input_tokens + requested_max_output_tokens

例如：

input_tokens = 1200
max_tokens   = 4096
token_cost   = 5296

优点：

• 在调用模型前就能做严格准入控制。
• 不会因为输出 Token 未知而突破额度。
• 适合流式响应。

缺点：

• 实际只输出 300 Token 时仍预留了 4096 Token。
• 如果不实现退款，额度利用率会偏低。

这是最容易实现“严格不超额”的方案。

网关必须对 max_tokens 设置服务端上限，不能完全信任客户端：

effective_max_tokens = min(client_max_tokens, server_model_limit)

否则客户端可以提交异常大的 max_tokens，让自己或整个租户迅速耗尽配额。

方案三：先预留，再按实际用量结算

完整思路是：

1. 请求开始时预留：

input_tokens + max_output_tokens

2. 响应结束后得到实际输出 Token。
3. 退还未使用部分：

refund = max_output_tokens - actual_output_tokens

但 envoyproxy/ratelimit 的标准限流调用主要面向正向增加计数，并不天然提供完整的“预留—提交—退款”事务模型。

如果业务必须支持精确退款，通常需要：

• 在适配层实现额外的 Redis Lua 脚本。
• 使用独立的预留记录和过期时间。
• 请求结束后进行 commit/refund。
• 使用请求 ID 保证幂等。

此时 envoyproxy/ratelimit 仍可负责 RPM 或基础 TPM，但结算逻辑已经属于定制配额服务。

方案四：流式增量扣费

对于流式输出，可以：

1. 请求开始时扣除输入 Token。
2. 每生成一批输出 Token，再增加一次 TPM 计数。
3. 一旦超过额度，终止上游流。

例如每 32 或 128 个 Token 扣一次。

这种方式需要能观察响应流，因此仅靠请求阶段的 ext_authz 不够，需要：

• Envoy ext_proc；
• Wasm Filter；
• 自定义 HTTP Filter；
• 或由 AI Gateway 自身代理并读取流式响应。

增量批次越小，控制越精确，但 gRPC 和 Redis 调用次数也越多。

多 Envoy 实例如何保证共享额度

假设一个租户拥有：

RPM = 100
TPM = 200,000

请求可能随机落到不同 Envoy：

Request 1 -> Envoy A
Request 2 -> Envoy B
Request 3 -> Envoy C

但所有限流请求最终都会访问同一套 Redis 计数器：

ai-gateway / tenant-a / gpt-4.1 / rpm
ai-gateway / tenant-a / gpt-4.1 / tpm

因此额度是整个集群共享的，而不是每个 Envoy 各有一份。

可以横向扩展的部分包括：

• Envoy。
• AI Quota Adapter。
• envoyproxy/ratelimit。

不能随意拆分的是同一个配额 Key 的计数状态。如果使用多个完全独立的 Redis，则必须确保相同租户、模型和指标始终路由到同一个分片，否则额度又会被放大。

返回标准限流响应

发生超限时，适配层应向 Envoy 返回 429：

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 12

响应体可以采用 OpenAI 风格：

{
  "error": {
    "message": "Rate limit exceeded for tenant tenant-a",
    "type": "rate_limit_error",
    "code": "tpm_limit_exceeded"
  }
}

建议分别暴露 RPM 和 TPM 信息：

X-RateLimit-Limit-Requests: 60
X-RateLimit-Remaining-Requests: 12
X-RateLimit-Reset-Requests: 18

X-RateLimit-Limit-Tokens: 100000
X-RateLimit-Remaining-Tokens: 24580
X-RateLimit-Reset-Tokens: 18

为了避免客户端形成同步重试风暴，SDK 应使用带随机抖动的指数退避：

sleep = random(0, min(cap, base × 2^retry_count))

“精准限流”需要明确的边界

使用 Redis 共享计数器可以解决多实例额度放大的问题，但“精准”仍然需要明确具体含义。

1. 它通常是固定时间窗

配置：

unit: minute

通常表示分钟级固定时间窗，不等同于严格的滑动窗口。

用户可能在一个窗口结束前发送 100 次请求，并在新窗口开始后立刻再发送 100 次。从任意连续 60 秒观察，流量可能接近配置值的两倍。

因此，该方案能够保证：

所有 Envoy 实例共享同一个固定时间窗计数器。

但它不自动等于：

任意连续 60 秒都绝不超过限制。

如果业务要求严格滑动窗口，需要使用 Redis Sorted Set、滑动窗口计数器或专门的配额算法。

2. 输出 Token 在请求开始时未知

如果 TPM 包含输出 Token，则无法在生成之前知道最终消耗量。

所谓严格控制通常意味着：

• 使用 max_tokens 预留；或者
• 在流式生成过程中增量扣费。

单纯在响应结束后上报实际 Token，只能用于计费和统计，不能阻止当前请求突破 TPM。

3. RPM 和 TPM 不是一个原子事务

标准 RLS 请求中的 hits_addend 是统一的，而 RPM 和 TPM 需要不同增量，因此通常需要两次调用。

如果必须保证“RPM 和 TPM 同时检查、同时增加、任意失败都不修改”，需要定制服务并使用单个 Redis Lua 脚本完成事务。

生产环境中的关键问题

1. 请求重试和重复扣费

Rate Limit Service 的计数调用通常不是业务级幂等操作。

如果适配层因为超时重试同一个请求：

第一次调用已经写入 Redis，但响应丢失
第二次调用再次增加计数

就会产生重复扣费。

建议：

• 限流调用不要盲目自动重试。
• 使用 Envoy 的 x-request-id 或业务请求 ID。
• 对严格计费场景，在适配层中实现请求幂等记录。
• 幂等记录过期时间至少覆盖限流窗口和最大请求时长。

2. 故障时 Fail Open 还是 Fail Closed

当 Redis 或 ratelimit 服务不可用时，可以选择：

Fail Open：

限流系统不可用时继续放行

优点是可用性高，缺点是可能导致成本失控。

Fail Closed：

限流系统不可用时拒绝请求

优点是保护成本，缺点是限流组件故障会影响业务。

AI 推理通常成本较高，面向外部用户的付费 API 更适合 Fail Closed。内部低风险环境可以考虑短时间 Fail Open，并配合熔断和告警。

3. Tokenizer 必须与模型匹配

不同模型的 Tokenizer 可能不同。不能使用简单的字符数除以固定比例来实现严格 TPM。

应该维护：

model -> tokenizer

例如：

gpt-family       -> cl100k/o200k 类 tokenizer
llama-family     -> 对应 SentencePiece/BPE tokenizer
自定义模型        -> 模型实际 tokenizer.json

如果 tokenizer 不可用，可以做保守估算，但必须预留误差：

estimated_tokens = ceil(raw_estimate × safety_factor)

4. 规范化模型名称

客户端可能使用：

gpt-4.1
gpt-4.1-2025-04-14
my-gpt-alias

限流前应将它们映射到统一的配额名称：

my-gpt-alias -> gpt-4.1

否则用户可能通过切换别名绕过同一模型的额度。

5. 不要信任客户端提供的 Token 数

不能让客户端直接提交：

X-Token-Cost: 1

然后按该值扣费。

Token 数必须由可信组件计算，或者由上游模型返回后进行校验。客户端声明只能作为参考，不能作为计费依据。

6. 配置发布必须一致

如果多个 ratelimit 副本加载了不同配置，可能出现：

副本 A：RPM 100
副本 B：RPM 200

即使 Redis 相同，结果也会变得不可预测。

生产环境应：

• 使用固定版本配置。
• 进行启动前校验。
• 滚动发布时保持向后兼容。
• 为配置添加版本号和监控指标。

监控指标

至少应监控：

Envoy

• ext_authz 调用次数。
• ext_authz 超时和失败次数。
• HTTP 429 数量。
• 上游请求数和并发数。
• 请求体缓冲失败次数。

AI Quota Adapter

• RPM 允许和拒绝次数。
• TPM 允许和拒绝次数。
• Token 计算耗时。
• RLS gRPC 延迟。
• Tokenizer 加载失败次数。
• 按模型和租户聚合的 Token 消耗。
• 重复请求或幂等命中次数。

Ratelimit

• OK、OVER_LIMIT、错误数量。
• Redis 请求延迟。
• Redis 连接池使用率。
• 配置加载状态。
• 各限流规则命中次数。

Redis

• CPU 和内存。
• 命令延迟。
• 连接数。
• Key 数量。
• Key 过期速率。
• 主从复制延迟。
• Failover 次数。

高基数租户 ID 不适合直接作为 Prometheus Label。否则租户数量较多时会产生严重的指标基数问题。按租户的详细用量更适合写入日志、ClickHouse 或专门的计量系统。

推荐的最终实现

对于大多数 AI API 网关，可以采用下面的组合：

Envoy
  └── ext_authz
        └── AI Quota Adapter
              ├── 解析租户和模型
              ├── 使用可信 tokenizer 计算 input_tokens
              ├── 规范化并限制 max_tokens
              ├── RPM：RLS hits_addend = 1
              └── TPM：RLS hits_addend =
                       input_tokens + max_output_tokens
                        └── envoyproxy/ratelimit
                              └── Redis

这一方案具备以下特征：

• 多 Envoy 实例共享统一额度。
• RPM 和 TPM 分别计数。
• 支持按租户、模型、套餐隔离。
• 在请求进入模型服务之前完成准入控制。
• 通过预留最大输出 Token，保证不会因为流式输出突破 TPM。
• Envoy、适配层和 ratelimit 服务都可以横向扩展。

如果还需要按照实际输出 Token 精确结算，则在此基础上增加：

预留记录 + 响应用量采集 + commit/refund + 请求幂等

此时系统已经从“限流服务”演进为一套完整的“分布式 AI 配额与计量服务”。

总结

envoyproxy/ratelimit 非常适合解决多 Envoy 实例之间的全局共享限流问题。它通过 Redis 集中维护计数器，避免每个网关实例独立计算额度。

对于 AI 场景，需要在标准 HTTP 限流之上增加 Token 感知能力：

• RPM 使用 hits_addend=1。
• TPM 使用 hits_addend=token_cost。
• 使用租户、模型和指标构建 Descriptor。
• 请求阶段通过输入 Token或最大输出 Token预留完成准入。
• 多 Envoy、多个适配层和多个 RLS 副本共享同一个 Redis 计数空间。

需要特别注意的是，分布式共享计数、固定时间窗、RPM/TPM 组合事务以及实际输出 Token 结算是四个不同问题。理解这些边界，才能构建一套既能保护模型成本、又能在高并发环境中稳定运行的 AI 限流系统。

随着 OpenWebUI 中的用户、对话、文件和知识库数据不断增长，原先部署在 Azure VM 上的自建 PostgreSQL 带来了越来越多的运维工作，包括数据库补丁、备份、故障恢复、存储监控和安全维护。

为了降低维护成本并提高数据库可靠性，我将 OpenWebUI 的业务数据库从 VM 本地 PostgreSQL 迁移到了 Azure Database for PostgreSQL Flexible Server。

这次迁移采用了：

在线全量迁移 + 数据一致性验证 + 活跃对话增量同步 + 快速切换

全量数据库导出和恢复期间，OpenWebUI 始终保持在线。最终切换仅涉及一次很短的 Docker 容器重建，用户侧基本无感。

本文中的服务器地址、数据库名称、用户名、密码和资源标识均已隐藏或替换为占位符。

迁移背景

OpenWebUI 以 Docker 容器形式运行在 Azure VM 中，最初使用安装在同一台 VM 上的 PostgreSQL。

迁移前的架构如下：

用户
  │
  ▼
Azure VM
  ├── OpenWebUI Docker 容器
  │      └── 连接 VM 宿主机 PostgreSQL
  │
  └── PostgreSQL
         └── 数据保存在 VM 本地磁盘

这种部署方式比较简单，但随着应用逐渐稳定运行，数据库维护也成为了新的负担。

需要自行处理的工作包括：

• PostgreSQL 安全更新和补丁
• 数据库备份及备份轮换
• 数据恢复和恢复演练
• 磁盘容量监控
• 数据库服务监控
• PostgreSQL 版本升级
• 故障处理
• 网络和访问权限管理

对于 OpenWebUI 这样的应用来说，数据库是重要的状态组件，但并不是应用的核心运维目标。因此，将 PostgreSQL 迁移到 Azure 托管服务是一个更合理的选择。

迁移后的架构

迁移后的架构如下：

用户
  │
  ▼
Azure VM
  └── OpenWebUI Docker 容器
          │
          ├── Private Endpoint
          │       └── Azure Database for PostgreSQL
          │
          └── 宿主机持久化目录
                  ├── uploads
                  ├── vector_db
                  └── cache

最终实现了：

• OpenWebUI 使用 Azure 托管 PostgreSQL
• 数据库通过 Private Endpoint 私网访问
• 数据库连接启用 TLS
• PostgreSQL 不再占用 VM 本地端口和磁盘
• OpenWebUI 上传文件和向量数据实现持久化挂载
• Azure 自动执行数据库备份
• VM 上只保留 PostgreSQL 客户端，用于日常管理 Azure 数据库

为什么选择 Azure Database for PostgreSQL

1. 降低数据库运维成本

Azure Database for PostgreSQL Flexible Server 是一项托管数据库服务。

与 VM 自建 PostgreSQL 相比，Azure 可以帮助处理大量底层工作，例如：

• 数据库基础设施维护
• 自动备份
• 事务日志备份
• 时间点恢复
• 监控指标采集
• 存储管理
• 计划性维护
• 可选高可用
• 可选只读副本

迁移完成后，VM 只需要负责运行 OpenWebUI，数据库生命周期则交给 Azure 管理。

2. 自动备份和时间点恢复

Azure PostgreSQL 提供内置自动备份，并持续备份事务日志，支持时间点恢复（Point-in-Time Restore，PITR）。

当前环境配置了自动备份保留策略。发生误操作时，可以在保留期内创建一台恢复到指定时间点的新服务器。

与自行编写 pg_dump 和 Cron 脚本相比，Azure 托管备份具有以下优势：

• 不需要维护备份脚本
• 不需要手动轮换备份文件
• 不会占用 VM 本地磁盘
• 可以恢复到保留期内的特定时间
• 备份操作由平台统一管理

需要注意的是，Azure 内置备份主要用于平台恢复，不等同于可随意下载的逻辑备份文件。

如果有以下需求，仍建议额外定期执行 pg_dump：

• 长期离线归档
• 跨平台恢复
• 数据审计
• 跨订阅或跨云迁移
• 保留期超过平台备份策略

3. 使用 Private Endpoint 私网访问

本次迁移没有将 PostgreSQL 直接暴露到公网，而是为 Azure PostgreSQL 配置了 Private Endpoint。

OpenWebUI 访问数据库时，数据库域名通过 Private DNS 解析到 VNet 中的私有 IP：

Azure PostgreSQL FQDN
        ↓
Private DNS
        ↓
Private Endpoint 私有 IP

从 OpenWebUI 容器内部进行了两层验证：

1. DNS 是否解析到私有地址
2. TCP 5432 是否可以通过私网访问

示例：

docker exec -i open-webui python3 - <<'PY'
import socket

host = "<AZURE_POSTGRESQL_PRIVATE_FQDN>"
port = 5432

addresses = sorted({
    item[4][0]
    for item in socket.getaddrinfo(
        host,
        port,
        type=socket.SOCK_STREAM
    )
})

print("Resolved addresses:", addresses)

with socket.create_connection((host, port), timeout=5) as sock:
    print("TCP connection: OK")
    print("Connected peer:", sock.getpeername())
PY

数据库安全性并不只是来自 Private Endpoint，而是来自以下措施的组合：

• Private Endpoint
• Private DNS
• VNet 隔离
• NSG 和路由控制
• 禁用或限制公网访问
• PostgreSQL 身份认证
• TLS 链路加密
• 最小权限数据库账号

4. 数据库连接启用 TLS

OpenWebUI 的数据库连接串启用了：

sslmode=require

脱敏后的连接串格式如下：

postgresql://<APP_USER>:<PASSWORD>@<AZURE_POSTGRESQL_FQDN>:5432/<APP_DATABASE>?sslmode=require

迁移前还通过 OpenWebUI 使用的 Python 和 SQLAlchemy 环境实际验证了 TLS：

import os
from sqlalchemy import create_engine, text

engine = create_engine(os.environ["DATABASE_URL"])

with engine.connect() as conn:
    ssl_enabled = conn.execute(text("""
        SELECT ssl
        FROM pg_stat_ssl
        WHERE pid = pg_backend_pid()
    """)).scalar_one()

print("TLS enabled:", ssl_enabled)

如果安全要求更高，可以进一步使用：

sslmode=verify-full

这种模式不仅加密连接，还会验证证书和服务器主机名，但需要正确配置 CA 证书，并使用与证书匹配的服务器 FQDN。

5. 更容易扩展可靠性能力

迁移到 Azure PostgreSQL 后，可以根据 OpenWebUI 的使用规模继续配置：

• 计算规格扩缩容
• 存储扩容
• 可用区高可用
• 只读副本
• 慢查询分析
• 数据库连接监控
• CPU、内存和存储告警
• 更长的备份保留期
• 异地恢复策略

这使 OpenWebUI 的数据库层从“单 VM 上的本地服务”升级为独立、可管理的托管数据服务。

迁移目标：让 OpenWebUI 尽量保持在线

传统迁移通常采用以下流程：

停止应用
  ↓
导出数据库
  ↓
恢复目标数据库
  ↓
修改连接配置
  ↓
重新启动应用

这种方式虽然简单，但数据库越大，停机时间越长。

本次迁移采用了不同策略：

在线全量备份
  ↓
在线恢复到 Azure PostgreSQL
  ↓
验证结构、权限和数据
  ↓
同步迁移期间新增的活跃对话
  ↓
快速重建 OpenWebUI 容器

在以下阶段，OpenWebUI 都保持在线：

• 全量 pg_dump
• Azure PostgreSQL 数据恢复
• 表结构验证
• 数据量对比
• Private Endpoint 验证
• TLS 验证
• 增量数据同步

最终只有更换 DATABASE_URL 并重建容器时发生了短暂连接中断。

因此，更准确地说，这是一种：

近零停机、用户侧近乎无感知的 OpenWebUI 数据库迁移方案。

迁移前检查 OpenWebUI

1. 确认 OpenWebUI 使用的数据库类型

首先检查 OpenWebUI 容器环境变量：

docker inspect open-webui \
  --format '{{range .Config.Env}}{{println .}}{{end}}' |
grep -E 'DATABASE_URL|DATA_DIR|WEBUI_SECRET_KEY'

确认 OpenWebUI 已经使用 PostgreSQL，而不是默认 SQLite：

DATABASE_URL=postgresql://<LOCAL_USER>:***@<LOCAL_HOST>:5432/<LOCAL_DATABASE>

由于源端和目标端都是 PostgreSQL，因此可以直接使用：

pg_dump → pg_restore

不需要使用 SQLite 到 PostgreSQL 的转换工具。

2. 检查源数据库

检查 PostgreSQL 版本和数据库大小：

sudo -u postgres psql \
  -d <LOCAL_DATABASE> \
  -c "
SELECT
  current_database(),
  current_setting('server_version'),
  pg_size_pretty(
    pg_database_size(current_database())
  );
"

同时检查源数据库使用了哪些扩展：

sudo -u postgres psql \
  -d <LOCAL_DATABASE> \
  -c "
SELECT extname, extversion
FROM pg_extension
ORDER BY extname;
"

本次源数据库没有使用额外的第三方扩展，因此降低了跨环境迁移的兼容性风险。

3. 检查 OpenWebUI 的本地文件

数据库并不是 OpenWebUI 的全部数据。

检查容器挂载后发现，原容器没有配置持久化 volume，而 /app/backend/data 中已经存在大量数据：

/app/backend/data
├── cache
├── uploads
└── vector_db

这些内容包括：

• 用户上传文件
• 向量数据库
• 缓存
• 其他应用本地状态

它们不会进入 PostgreSQL 的 pg_dump，因此必须单独处理。

这也是本次迁移中一个非常重要的发现：

迁移 OpenWebUI 的 PostgreSQL，并不等于迁移了 OpenWebUI 的全部数据。

准备 Azure PostgreSQL

1. 创建独立应用账号

不建议让 OpenWebUI 长期使用 Azure PostgreSQL 管理员账号。

在目标服务器中创建专用角色：

CREATE ROLE <APP_USER> LOGIN;

通过 psql 交互方式设置密码，可以避免密码出现在 Shell 历史记录中：

\password <APP_USER>

然后创建目标数据库：

CREATE DATABASE <APP_DATABASE>
OWNER <APP_USER>;

2. 验证应用账号

psql \
  "host=<AZURE_POSTGRESQL_FQDN> \
   port=5432 \
   dbname=<APP_DATABASE> \
   user=<APP_USER> \
   sslmode=require" \
  -W \
  -c "SELECT current_user, current_database();"

同时确认目标数据库为空：

SELECT count(*)
FROM information_schema.tables
WHERE table_schema = 'public'
  AND table_type = 'BASE TABLE';

3. 处理 public schema 权限

第一次测试恢复时遇到了：

ERROR: permission denied for schema public

原因是应用账号虽然可以连接数据库，但没有在 public schema 中创建对象的权限。

使用管理员账号连接目标数据库后执行：

ALTER SCHEMA public OWNER TO <APP_USER>;

GRANT USAGE, CREATE
ON SCHEMA public
TO <APP_USER>;

这个问题说明，仅验证账号“能否登录”还不够，还需要确认该账号能否：

• 创建表
• 创建索引
• 创建序列
• 创建约束
• 执行 OpenWebUI 的 Alembic 数据库迁移

在线执行全量数据库迁移

1. 在线导出 OpenWebUI 数据库

PostgreSQL 的 pg_dump 会基于一致性事务快照导出数据，因此可以在 OpenWebUI 继续运行时执行。

sudo -u postgres pg_dump \
  --dbname=<LOCAL_DATABASE> \
  --format=custom \
  --no-owner \
  --no-acl \
  --file=/tmp/openwebui-pre-migration.dump

参数含义：

• --format=custom：使用 PostgreSQL 自定义归档格式
• --no-owner：不恢复源端对象 owner
• --no-acl：不恢复源端权限
• --file：指定备份文件

检查归档是否有效：

pg_restore \
  --list \
  /tmp/openwebui-pre-migration.dump |
head -30

自定义格式会保留：

• 表结构
• 表数据
• 主键
• 唯一约束
• 索引
• 外键
• 序列
• Alembic 迁移版本

2. 恢复到 Azure PostgreSQL

pg_restore \
  --host=<AZURE_POSTGRESQL_FQDN> \
  --port=5432 \
  --username=<APP_USER> \
  --dbname=<APP_DATABASE> \
  --no-owner \
  --no-acl \
  --exit-on-error \
  --verbose \
  /tmp/openwebui-pre-migration.dump

使用：

--exit-on-error

可以确保遇到恢复错误时立即停止，避免忽略关键问题。

恢复成功后更新统计信息：

psql \
  "host=<AZURE_POSTGRESQL_FQDN> \
   port=5432 \
   dbname=<APP_DATABASE> \
   user=<APP_USER> \
   sslmode=require" \
  -W \
  -c "ANALYZE;"

对比源端与目标端数据

恢复完成后，需要对 OpenWebUI 的核心表进行对比。

示例查询：

SELECT
  (SELECT count(*) FROM "user") AS users,
  (SELECT count(*) FROM chat) AS chats,
  (SELECT count(*) FROM chat_message) AS chat_messages,
  (SELECT count(*) FROM file) AS files,
  (SELECT count(*) FROM knowledge) AS knowledge,
  (
    SELECT count(*)
    FROM information_schema.tables
    WHERE table_schema = 'public'
      AND table_type = 'BASE TABLE'
  ) AS tables;

重点检查：

• 用户数量
• 对话数量
• 消息数量
• 文件记录数量
• 知识库数量
• 业务表数量
• Alembic 版本
• 表 owner
• 序列状态