Jev AI 函数调用:把类型签名变成带置信度的 Dispatcher 调用

更新于 适用版本 Jev 1.14

一句话结论: Jev 的函数调用跟 LLM 那套不是一回事。LLM 那套是模型「生成」一段 JSON 参数、你再去校验;TypeSafe 这套是从你函数上已有的类型标注里读出「封闭集合」,把每个枚举参数变成一道 Choice、每个可选参数变成一道 Noul、把每个函数变成一道 Choice 的选项,然后一次性发出去、只读被选中那支的答案。官方 cookbook 把结果也量出来了:10 个函数、28 个可填参数、每个命令 54 道问题,14 条测试命令的置信度从 1.00 一直到 0.53。整个过程中函数本身一个字都没改。本文就按 notebook 打印出来的那些表格逐项拆。

如果你之前看到「工具调用不过就是给个 schema」这种说法,那这里最有意思的地方恰恰是:它没有 schema。没有 JSON Schema,没有 tool_choice,也没有语法约束解码。有的只是签名里那些 Literal,加上一份用英文白话写清每个参数含义的 spec.json,加上一个把所有问题一次问完的 dispatcher。

本文事实的来源

下面所有内容都在 2026-11-14 核对过 TypeSafe 官方这几页:

有一条官方在页面里自己声明的限制,这里必须重复,因为它直接影响你怎么看那些数字:例子里的股票代码是真的,但所有价格、收益率和图表都是用一个固定随机种子模拟出来的。置信度是模型真实输出,行情数据不是行情数据。

这一页到底在解决什么问题

一个交易助手暴露了十个普通函数。用户输入一句话。这句话里从来不出现函数名。

"plot rolling correlation between nvda and spy for the past month"
    rolling_correlation(symbol='NVDA', benchmark='SPY', window='1mo')   confidence 0.93

"compare nvda amd and msft over the past three months"
    compare_returns(symbols=['NVDA', 'AMD', 'MSFT'], window='3mo')      confidence 0.93

"show me apple daily with volume"
    plot_price(symbol='AAPL', resolution='1d', include_volume=True)     confidence 0.69

"what tickers do you have"
    list_symbols()                                                     confidence 1.00

官方用的比喻是咖啡店:你点「大杯冰燕麦拿铁、不加糖」,店员不会把你的整句话抄下来,而是在杯子上勾四个选项。这里的对应关系就是——一句话进去,函数名和一组已求值的参数出来,而每个参数都是从一份固定清单里勾出来的。

之所以这套东西适合判断模型、而不适合生成模型,原因在于每一个决策都是封闭问题。哪个函数?十选一。哪个标的?六选一。要蜡烛图还是折线?是/否,问两次。整条流水线里没有任何一个环节需要模型「生产」一个不在清单上的值。

签名里其实藏着三种形状

类型标注已经声明了哪些参数来自固定列表。官方的 closed_sets 工具读一遍签名,把这些参数归成三类:

形状写法变成什么例子
choiceLiteral["a", "b"]一道 Choice,选项就是这些值symbol: Literal["SPY","NVDA","AMD","AAPL","MSFT","TSLA"]
setlist[Literal[...]]每个成员一道 Noul,问题文本里用 {} 占位compare_returns 里的 symbols
flagbool一道开/关问题include_volume、log_scale

官方把那句签名当「草图」印了出来,值得完整看一遍——因为从里面能看出类型标注本身已经替你干了多少活:

def plot_price(
    symbol: Literal["SPY", "NVDA", "AMD", "AAPL", "MSFT", "TSLA"],
    style: Literal["line", "candles"] = "line",
    resolution: Literal["1m", "5m", "15m", "1h", "1d"] = "15m",
    window: Literal["1d", "1w", "1mo", "3mo"] = "1w",
    include_volume: bool = False,
    moving_average: Literal["9", "20", "50"] | None = None,
    log_scale: bool = False,
): ...

七个参数,notebook 的实测输出把七个全归好类了:symbol:choice, style:choice, resolution:choice, window:choice, include_volume:flag, moving_average:choice, log_scale:flag。

实测清单

下面这张表是 notebook 打印出来的,不是我重构的。十个函数,每个后面跟可填参数的数量:

  list_symbols        0
  market_summary      1  window:choice
  plot_price          7  symbol:choice, style:choice, resolution:choice, window:choice, include_volume:flag, moving_average:choice, log_scale:flag
  intraday_pattern    3  symbol:choice, window:choice, metric:choice
  compare_returns     3  symbols:set, window:choice, normalize:flag
  rolling_correlation 4  symbol:choice, benchmark:choice, window:choice, resolution:choice
  summary_stats       2  symbol:choice, window:choice
  volatility          3  symbol:choice, window:choice, annualized:flag
  top_movers          2  window:choice, direction:choice
  drawdown            3  symbol:choice, window:choice, plot:flag

28 fillable arguments in total

表里有两个细节,比「28」这个总数有用得多。

list_symbols 是 0。 它那行数字后面直接是空白,因为没有东西可填。一个完全没有封闭集合参数的函数,一道参数问题都不需要——它照样能被选中,只是不再贡献别的问题。

top_movers 演示了「什么会被跳过」。 它有三个参数,只有两个是封闭集合。第三个 limit 是 int,所以永远不会有问题,一直保持默认值 3。这就是所有未枚举参数的通用规则:自由文本、数字、日期都不问,函数自己的默认值生效。也正因为这条规则,这套玩法没法用来从一句话里抽出客户姓名或者发票金额——那些恰好就是会掉下去的参数。

spec 才是白话待的地方

Literal 只给了你 "1mo" 和 "3mo" 这两个字符串。它没法告诉你:用户说「这个季度」的时候,指的是第二个。这件事得由 spec 来说明,而 spec 也是整套东西里唯一需要人写的部分。它包含:每个参数一道问题、每个选项一段描述、每个函数一段描述,再加一道在函数之间做选择的问题。

官方真正的 spec.json 里的两条,notebook 直接打印出来的:

{
  "style": {
    "question": "Does the user want a plain line or candles?",
    "stated": "Does the user say how the chart should be drawn, such as a line, candles, or OHLC bars?",
    "options": {
      "line": "a simple line through the closing prices",
      "candles": "a candlestick or OHLC chart, showing each bar's open, high, low and close"
    }
  }
}
{
  "moving_average": {
    "question": "How many bars should the moving average cover - nine, twenty, or fifty?",
    "stated": "Does the user ask for a moving average or a smoothed line over the candles?",
    "options": {
      "9": "a nine-bar moving average, a fast one",
      "20": "a twenty-bar moving average",
      "50": "a fifty-bar moving average, a slow one"
    }
  }
}

就这么几行,藏了三个机制。

选项的 key 就是函数自己的字符串。 是 "9",不是 "nine"。这样后面就不需要任何「把标签映射回参数」的代码,也就顺手消掉了一整类差一错误。

stated 才是让参数变可选的那个东西。 它是一道额外的「是/否」问题——一个 Noul——问的是「这句话到底有没有提到这个参数」。答否,调用就省掉这个参数,函数的默认值接手。没有它,Choice 就被迫在用户什么窗口都没说的情况下,硬指定一个窗口。

set 类型是每个成员问一次。 "Does the user want {} in the comparison?" 里那个 {} 是成员占位符,展开就是每个股票代码一道问题。

官方明说的两条写作规则

两条都是关于「意思」而不是「措辞」的,也都特别容易写错:

  1. 问题要写「想法」,不要写「用户可能用的词」。 因为匹配是按语义走的,所以 “is amd tracking nvidia lately” 能落到 rolling_correlation 上——尽管 tracking 和 lately 这两个词在 spec.json 里一次都没出现过。
  2. 别拿参数名当问题。 官方的反面例子是 "Which resolution?"——它让命令没有任何东西可以匹配。

54 道问题,一次请求

Dispatcher 只从 spec 构建一次问题集。之后每条用户命令就是一次请求,里面同时装着「选哪个函数」和所有函数的参数,而 dispatcher 只读那个胜出函数名下的答案。

54 questions per command, among them:
  __tool__                      choice  What is the user asking the trading assistant to do?
  plot_price.style              choice  Does the user want a plain line or candles?
  plot_price.style?             noul    Does the user say how the chart should be drawn, such as a line,
  compare_returns.symbols.NVDA  noul    Does the user want NVDA in the comparison?

注意这个命名约定:plot_price.style 是那道 Choice,而 plot_price.style?——同一路径加一个问号——才是 stated 那个 Noul。__tool__ 则是在十个函数描述之间做路由的那道 Choice。

每条命令都把十个函数的参数全发出去,看起来浪费,某种意义上确实浪费:官方文档说得很直白,多出来的问题仍然要花 token。换来的是延迟——问题之间并行评估,加问题几乎不增加响应时间,代码直接忽略不需要的答案就行。这跟 Choice 原语页上给的通用建议是同一句话:把你可能需要的所有问题一次性问完,而不是一个问题一次请求。

十四条命令的实测结果

官方跑了 14 条命令,每条打印出调用本身和两个数字:整次调用的 confidence,以及路由到那个函数的 tool 概率。

命令调用confidencetool
“show nvda 1h”plot_price(symbol='NVDA', resolution='1h')0.590.99
“plot rolling correlation between nvda and spy for the past month”rolling_correlation(symbol='NVDA', benchmark='SPY', window='1mo')0.931.00
“when during the day does nvda trade the most”intraday_pattern(symbol='NVDA')0.531.00
“what moved today”top_movers(window='1d', direction='gainers')0.900.94
“what tickers do you have”list_symbols()1.001.00
“how did the market do this week”market_summary(window='1w')0.940.98
“candles for tesla with a 20 period moving average”plot_price(symbol='TSLA', style='candles', moving_average='20')0.881.00
“compare nvda amd and msft over the past three months”compare_returns(symbols=['NVDA','AMD','MSFT'], window='3mo')0.931.00
“how volatile is tsla”volatility(symbol='TSLA')0.971.00
“biggest losers today”top_movers(window='1d', direction='losers')0.941.00
“worst drawdown for nvda this quarter, and chart it please”drawdown(symbol='NVDA', window='3mo', plot=True)0.920.98
“spy stats for the last month”summary_stats(symbol='SPY', window='1mo')0.970.98
“show me apple daily with volume”plot_price(symbol='AAPL', resolution='1d', include_volume=True)0.690.98
“is amd tracking nvidia lately”rolling_correlation(symbol='AMD', benchmark='NVDA')0.690.85

路由几乎从来不是问题所在。 十四分之十一的命令 tool 落在 0.98–1.00,全表最低的两个值——0.94 和 0.85——选的函数也都是对的。不确定性长在参数上,不在选函数上。如果你正在决定「兜底逻辑该放哪儿」,这是这张表里最有用的一句话。

有两条命令值得单独看。

“compare nvda amd and msft over the past three months” 把三个标的塞进了 symbols 这个 set,另外三个正确排除——一个六选多的集合一次就解对了。官方的解释是问题里写清了角色:在相关性那条命令里,symbol 和 benchmark 都从同样六个标的里取,最终每个标的都落到了正确的参数上,因为问题把「第一个被测量的」和「第二个作为基准的」区分开了。同一份封闭集合,两种含义,没有串线。

“is amd tracking nvidia lately” 则是拿来检验 spec 的那条。它产出 rolling_correlation(symbol='AMD', benchmark='NVDA'),置信度 0.69,tool 0.85——全表最低的路由概率——而 tracking 和 lately 这两个词在 spec.json 里根本不存在。

为什么只有一个参数不稳,整次调用就报 0.69

官方把那次调用按参数拆开了,也是整页最该消化的一段:

"is amd tracking nvidia lately"  ->  rolling_correlation(symbol='AMD', benchmark='NVDA')   confidence 0.69
  symbol      'AMD'                     p 0.93   AMD 0.93  NVDA 0.07  AAPL 0.00
  benchmark   'NVDA'                    p 0.69   NVDA 1.00  AAPL 0.00  AMD 0.00
  window      omitted, default stands   p 0.88
  resolution  omitted, default stands   p 0.95
  weakest argument: benchmark

两个参数填得很稳,一个参数被省略且 stated 概率很高,还有一个 benchmark 掉到 0.69——而整次调用的置信度就是 0.69,因为置信度取的是最不确定的那个判断,不是乘积。

理由官方写得很清楚:一个参数错了,结果就废了。而乘积回答的是另一个问题——「是不是每一部分都对」——它会随着参数变多而下降,不管每个判断稳不稳,这等于在惩罚 plot_price 因为参数多(七个),而无视它其实每个都很稳。取最小值意味着:你拿去跟阈值比的这个数字,就是真正该拦下这次调用的那个数字。

这跟单独用 Choice 原语的语义是一致的:那边的 confidence 也是从概率分布的形状算出来的——单个尖峰=高置信,摊在好几个选项上=低置信。这里只是把它应用到每个参数上,最后用 min 归约。

stated 的概率不是「确定性」

有个反常的地方值得点出来,因为它特别容易让人误读。window 和 resolution 明明被省略了,却还各带一个概率,0.88 和 0.95。那个数字属于「是/否」的 stated 问题——用户有没有提到这个参数的概率。高值意味着模型对「用户提了吗?」这个问题的回答很确定,而那个回答是没有。对否定答案高度确信,仍然是一个确信的答案,所以它不会把最小值拉低。

两个参数都被省略的原因就是「lately」这个词:它没说往前看多久,也没说用什么周期的 K 线,于是 rolling_correlation 按自己的默认值(一个月、小时线)执行。这正是 stated 存在的意义——它防止 dispatcher 凭空造出一个用户根本没给的参数。

给调度结果加阈值

置信度这个数字只有在「有东西读它」的时候才有用。按官方给的指导,有两个地方可以分叉:

按整次调用的置信度三分。 低于下限就不执行,改成向用户提一个澄清问题、并点名最弱的那个参数;高于上限就执行;中间那段交给人工或一个确认界面。这就是 confidence 页对 Choice 和 Score 答案描述的那套三分法,只不过这里是应用在整次调用上,而不是单个字段上。

按单个参数的概率分叉。 call.weakest() 会返回设定了最小值的那个参数。在澄清提示里点名它,才是把 0.69 变成一句好问题的关键——「你说的基准是 NVDA 吗?」是可回答的;用户都打完一整句话了,再问「哪个基准?」就不是。

至于「是/否」类的参数,官方给的起始点是「是 0.7、否 0.3」,同时附了一条限定:具体放哪儿取决于「判断错的代价」。判断错「是」很贵的时候(比如把人叫起来、或者直接退款),就调高;判断错「否」很贵的时候(比如漏报一个安全问题),就调低。0.3 到 0.7 之间的值可以交给人工,而不是硬塞进任何一条代码路径。别拿一小撮测试用例去贴合阈值。

而 14 条命令那张表对「拍脑袋定 0.9」意味着什么:14 条里有 5 条会被踢给人工,包括看起来完全合理的 "show nvda 1h"(0.59)和 "show me apple daily with volume"(0.69)。这两条的结果看着都对。在这个场景里高下限很贵,原因也很实在——残缺的句子里本来就存在真实的歧义:“show nvda 1h” 从头到尾没说画什么。

这套东西买到了什么,买不到什么

买到了 LLM 那套给不了的保证。 进到函数里的值,一定是函数能接受的值——因为选项 key 就是参数自己的字符串。dispatcher 和调用之间不需要校验层,也就不需要写「参数格式不对」那条分支。

买到了一个校准过的、按参数粒度的数字。 置信度不是一个感觉,它是从你提供的那些选项上的概率分布算出来的,而且它会告诉你整次调用里最弱的是哪儿。

代价是为用不上的参数付 token。 每条命令都发十个函数的问题出去。官方自己的规矩——一次问全,忽略不需要的——就是拿 token 换往返次数;在延迟比边际成本更重要的时候,这笔交易是划算的。

买不到「你没枚举的值」。 Choice 的 255 选项上限,加上「自由文本/数字/日期一律不问」这条规则,指向同一个结论:候选生成应该放在代码里或者生成式模型里,Jev 的职责是在候选之间挑。如果你的函数需要一个自由文本的 query 参数,那个参数只会拿到默认值,得靠别的路填。

也替代不了函数本身。 官方那句「你不用动函数」值得记住。dispatcher 是增量式的,这正是它能在「选择器早就存在」的现有代码库里落地的原因。

把这套搬到非交易场景

把股票代码剥掉,形状是完全通用的。任何「把一条消息路由到 N 个处理器之一、每个处理器带一小撮枚举设置」的流水线,都是同一个问题:

这些能不能成立,前提都是先把枚举定义出来。那 14 条命令能成功,不是因为模型懂交易,而是因为 "1mo"、"3mo"、candles 早就在清单上,而且 spec 说清了每个是什么意思。如果你的处理器收的是自由字符串,那就没有东西可问。

接进去之前的最小清单

  1. 先做枚举。 任何没法写成 Literal(或小规模 list[Literal])的参数都会静默保留默认值。逐个确认那个默认值你能不能接受。
  2. 每个可选的封闭集合参数都要有 stated 问题。 没有它,Choice 就只能硬猜。
  3. 选项描述要能把选项彼此分开。 选项名和描述都会发给模型,真正干活的是描述。
  4. 日志里记最弱参数,不只是记置信度。 数字告诉你这次调用有风险,名字告诉你要问什么。
  5. 用「什么都没说清」的命令去测试。 那 14 条全都过了;真正有意思的是 “what moved today” 和 “is amd tracking nvidia lately” 这两条。
  6. 准备好取最小值,并据此定下限。 官方那张表里 14 条有 5 条低于 0.9,而这 5 条看起来都是对的。

常见问题

这跟 OpenAI 那种 function calling 是一回事吗? 不是,差别在架构层面,不是措辞层面。LLM 那套是模型生成参数、你的代码去校验;这里根本没有生成环节——每个参数都是从你给的列表里挑出来的,答案是这些选项上的分布加一个概率。代价是表达力,换来的是「参数一定合法」。

能调度到十个以上的函数吗? cookbook 用了十个;文档里 Choice 的实际上限是 255 个选项,所以「选函数」那道问题的余量跟其他任何 Choice 一样。真正随函数数量增长的是每条命令的问题总数——dispatcher 每次都把全部函数的参数发出去——所以处理器规模很大时,这首先是个 token 成本决策,而不是上限决策。

是不是每个函数都要单独一次请求? 不是。官方明确说每条命令就是一次请求,里面同时装着选哪个函数和所有函数的参数,dispatcher 只读被选中那个函数的答案。54 道问题能用一个往返的价格问完,就是这个原因。

示例用的哪个模型? notebook 里钉的是 jev-1.14.0,并注明 jev-latest 会跑最新的线上模型。Models 页的价格是 $42 / 十亿 token、$0.042 / 百万 token。

把 DOWNLOAD_CACHE 设成 True,还会真的调 API 吗? 不会。那个模式下 notebook 用官方发布的答案填充缓存,整个运行不发任何请求。要跑真实调用就设成 false 并删掉缓存文件——磁盘上已存在的缓存永远不会被覆盖。

常见问题

+ Jev AI 的「函数调用」到底指什么?

指一套很具体的做法:拿一个普通的、参数取值来自固定列表的强类型函数,为每个参数生成一道 System One 问题,再加一道用来「选函数」的问题。返回的结果是函数名加上已经填好的参数,每个参数都带概率,整次调用再带一个置信度——这个置信度等于最不确定的那个参数的分数。TypeSafe 官方把它写在 docs.typesafe.ai/cookbooks/function_calling 这页 cookbook 里。

+ 用这套做法需要改函数本身的代码吗?

不需要,官方原话就是「你不用动函数,你要加的是那份用大白话说明每个参数含义的 spec」。封闭集合是从现有的类型标注里读出来的,所以只要签名里已经用 Literal 标好了取值范围,就够生成问题了。

+ 一条命令会生成多少道问题?

在 cookbook 那个交易助手的例子里是每个命令 54 道。这个数字是 notebook 自己打印出来的,构成是:一道在十个函数描述之间做选择的 Choice,加上十个函数全部参数的问题——因为 dispatcher 会把所有函数的参数一次性发出去,然后只读被选中那个函数的答案。问题之间是并行评估的,所以加问题几乎不增加响应时间,但多出来的问题确实要花 token。

+ 一次调度返回的置信度是怎么算的?

取所有参数里最不确定的那个,也就是最小值,而不是所有参数概率相乘。官方给的理由很直接:一个参数错了,整个调用的结果就废了;而乘积回答的是另一个问题——「是不是每一部分都对」,它会随着函数参数变多而下降,哪怕每一个判断都很稳。示例里某次调用报 0.69,就是因为 benchmark 这一个参数是 0.69,其他都更高。

+ 不是固定列表、也不是布尔值的参数会怎样?

完全不会有问题,函数自己的默认值直接生效。官方用 top_movers 演示:它有三个参数,其中两个是封闭集合,第三个 limit 是 int,所以从来不会生成问题,一直保持默认值 3。自由文本、数字、日期都遵循同一条规则——不问,用默认值。

+ 那 Jev 能不能直接抽出姓名、金额这类自由文本的值?

不能靠「直接问值」的方式。官方给的抽取建议是:先用正则或生成式模型把候选选项捞出来,再让 Jev 从候选里挑正确的那个;而且单个 Choice 的选项上限是 255 个。所以函数调用这套玩法的定位是「从封闭集合里填参数」,没被枚举的值要交给调用它的那段普通代码去处理。

+ spec 里那个 stated 字段是干什么的?

它让参数变成可选的。它是一道额外的「是/否」问题,问的是「用户这句话到底有没有提到这个参数」。如果答否,这次调用就直接省掉这个参数,由函数自己的默认值接手。官方的例子是结尾带 lately 的那条命令——它没说往前看多久,于是 window 和 resolution 两个参数都被省略,函数按自己的默认值(一个月、小时线)执行。

继续阅读