Jegue API使用教程:ask接口详解与choice、noul两种题型实战(附完整示例)

原创2026-11-14 15:35:271,022 阅读
文章标签:人工智能大模型微调本地部署模型推理服务模型评测机器学习

Jegue API使用教程:ask接口详解与choice、noul两种题型实战(附完整示例)

Jegue 是一个 9B 规模的类型化决策模型(typed-decision model),核心就是它的 ask 接口:给它一段上下文 state 和若干 choice(多选一)或 noul(是/否)题型,它能一次性返回每个选项的校准概率,且大部分问题只需一次前向传播。本文将带你从零跑通 Jegue API 的完整调用流程,掌握 ask 接口的入参结构、两种题型的写法,以及如何读取返回的概率结果。

一、Jegue 是什么:返回概率的选择题模型

Jegue 0.2 基于 Qwen/Qwen3.5-9B,通过 LoRA 适配器 + 答案槽读出头(answer-slot head)+ 路由头,把通用大模型改造成"概率决策器"。它和聊天模型最大的区别是:

特性 说明
🎯 输出 不是自由文本,而是每个选项的校准概率(0~1),可直接作为阈值触发下游动作
📝 题型 choice(多选一)和 noul(yes/no),一次请求可混合提问
⚡️ 速度 大多数问题单次前向传播即可作答;官方在单张 RTX 5090 上实测路由模式平均 293ms、中位数 89ms
🖥️ 部署 单张消费级 GPU 即可运行(Hugging Face 类约 20GB 显存,vLLM 类 24GB+),权重自包含在本仓库,无需额外下载

仓库结构很简单,基座模型文件在根目录,权重在 weights/(LoRA 适配器、head.pt、router-direct-brief.npz),全部 API 代码集中在 code/ 目录。更多背景见 README.md。

二、环境准备:安装依赖

只需要一块 CUDA GPU,Python 环境安装:

torch、transformers(5.x)、peft、safetensors、numpy、tqdm

如果使用 vLLM 快速路径,再额外安装 vllm(官方以 0.32 测试)。无需 Decision Index 评测套件即可调用 API。

三、ask 接口的两个类:Jegue 与 JegueVLLM

Jegue API 提供两个类,调用签名完全相同:response = model.ask(state, questions),区别只在底层引擎与可选模式(见 code/jegue.py):

类 底层引擎 可选 mode 显存 定位
Jegue Hugging Face / PyTorch direct / routed 约 20GB 精确对照、开发调试
JegueVLLM vLLM(CUDA graphs + 前缀缓存) routed / direct / brief 24GB+ 低延迟生产路径(默认 routed)

三种模式对应三条回答路径:

  • direct:单次前向传播,不生成任何文本,最快;
  • routed:先走 direct,由学习出来的 router 判断哪些 choice 问题值得升级,为它们补写一段至多 64 token 的简短推理(rationale)再重读答案。官方基准中约 15.2% 的问题走了升级路径;
  • brief:所有问题都先生成简短推理再作答(vLLM 类可用)。

⚠️ 两点注意:noul 题型与超过 26 个选项的 choice 题永远走 direct 路径(不参与路由);vLLM 类需要运行在独立的 Python 进程中(它内部设置 VLLM_ENABLE_V1_MULTIPROCESSING=0 以读取隐状态)。

四、choice 题型:多选项问题怎么写

questions 是一个字典,每个键是问题 ID。choice 题型需要三个字段:

"intent": {
    "type": "choice",
    "instructions": "What does the customer mainly want?",
    "criteria": {
        "refund": "A refund",
        "status": "An update on the delivery",
        "other": "Something else",
    },
}
  • instructions:用一句话描述问题(会被渲染进提示词);
  • criteria:选项表,键是返回时用的选项 ID,值是给人/模型看的描述,选项顺序无关紧要。

返回结果中,choice 字段给出概率最高的选项 ID,probabilities 给出全部选项的概率分布,总和为 1。

五、noul 题型:是/否判断与 P(yes)

noul 就是 yes/no 题型(取自已/否两个答案 token),不需要 criteria,只需一句可判是的问句:

"urgent": {
    "type": "noul",
    "instructions": "Should this email be escalated to a human agent today?",
}

返回一个 0~1 的浮点数 noul,即 P(yes)。概率经过训练校准,因此可以直接当置信度用:例如 P(yes)=0.78 意味着模型认为"应该升级人工"的概率约 78%,你可以按业务成本自设阈值(0.7、0.9 等)。

六、完整示例:一封客户邮件的双重提问

官方示例脚本 examples/ask_hf.py(Hugging Face 类)与 examples/ask_vllm.py(vLLM 类)输入完全相同,核心代码:

from jegue import Jegue

model = Jegue(mode="direct")   # vLLM 类则用 JegueVLLM(mode="routed")

state = "Email from a customer: 'My parcel was due on Monday and it is " \
        "Friday. Tracking has not changed since Tuesday. I want my money back.'"
questions = {
    "intent": {
        "type": "choice",
        "instructions": "What does the customer mainly want?",
        "criteria": {"refund": "A refund", "status": "An update on the delivery",
                     "complaint": "To complain about the service", "other": "Something else"},
    },
    "urgent": {
        "type": "noul",
        "instructions": "Should this email be escalated to a human agent today?",
    },
}

response = model.ask(state, questions)

一次 ask 调用同时回答了一个多选问题(客户意图)和一个是否问题(是否需当日升级),输出如下:

intent: refund  refund=1.00  status=0.00  complaint=0.00  other=0.00
urgent: P(yes)=0.78

七、读懂返回结果:response 的结构

ask 返回的 JSON 结构固定为三部分:

{
  "model": "Qwen/Qwen3.5-9B",
  "answers": {
    "intent": {
      "type": "choice",
      "choice": "refund",
      "probabilities": {"refund": 1.0, "status": 0.0, "complaint": 0.0, "other": 0.0}
    },
    "urgent": {"type": "noul", "noul": 0.78}
  },
  "usage": {"input_tokens": 128}
}
  • answers.<id>.type:choice 带 choice(最优选项)+ probabilities(全分布);noul 只有 noul 字段(P(yes));
  • usage.input_tokens:本次请求消耗的提示词 token 数,便于做成本核算;
  • 引擎还会返回 raw 调试信息(如每问走了 direct 还是 brief、路由打分),ask 会将其省略,用 model(state, questions) 双返回值调用可拿到。

八、direct 还是 routed:如何选模式

场景 推荐配置 理由
高吞吐在线服务 JegueVLLM(mode="routed") 官方延迟基准路径:平均 293ms / 中位数 89ms / p95 1166ms(RTX 5090)
极致低延迟 JegueVLLM(mode="direct") 跳过推理生成,单次前向传播
开发调试、核对结果 Jegue(mode="direct") 或 "routed" Hugging Face 路径行为直观,routed 模式用于精度对照

路由器(router)是一个小型回归头,作用在 direct 路径的隐状态上,阈值 tau=0.055;升级判断只对"单槽 choice 题"生效,细节可看 code/decision_engine_vr.py 与 code/decision_engine_v6r.py。

九、常见问题 FAQ

1. 提示词太长会怎样? 超过 32,768 token 的请求会被直接拒绝(抛 Unsupported),Jegue 不做截断,需要你在业务侧控制上下文长度。

2. 显存不够 20GB 怎么办? 官方未提供量化版本;建议升级到 24GB+ 显卡并使用 vLLM 类,或缩小并发规模(单请求串行即可满足基准)。

3. 概率为什么不是温度缩放的? 答案槽读取的是选项 token 的 logits + 训练残差,概率未做温度缩放,因此数值可直接比较,也适合作为门控阈值。

4. 一次可以问多少个问题? questions 字典可任意混合多个 choice / noul,共享同一份 state,长上下文只编码一次,天然适合"一份材料多个判断"的场景(如上面邮件意图 + 紧急度)。

十、小结

Jegue 的 ask 接口把"让大模型做选择题"变成了三件事:写好 state 上下文、用 choice / noul 描述问题、读取 answers 里的校准概率。它输出的是概率而非文字,天生适合意图分类、风险判断、内容分级等需要置信度与低延迟的工程场景。建议从 examples/ask_hf.py 起步跑通 direct 模式,再切到 examples/ask_vllm.py 的 routed 模式上生产。

登录后查看全文
jegue