Jev AI 函数调用:把类型签名变成带置信度的 Dispatcher 调用
一句话结论: 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 官方这几页:
- Function calling cookbook——十函数交易助手、页面里打印的所有表格,以及 14 条命令的完整结果。可执行的例子同时也在公开示例库
github.com/typesafe-ai/typesafe-public-examples/tree/main/cookbooks/function_calling,notebook 就是从那里下载dispatch.py、trader.py、spec.json和bars.parquet的。 - Choice 原语页——选项数量上限、
probabilities和confidence的定义,以及置信度为什么是「从分布形状算出来的」。 - Noul 原语页——为什么「是/否」问题没有单独的
confidence,以及 0.7 / 0.3 这个起始阈值。 - Models 页——模型 ID
jev-1.14.0,以及 $42 / 十亿 token、$0.042 / 百万 token 的价格。
有一条官方在页面里自己声明的限制,这里必须重复,因为它直接影响你怎么看那些数字:例子里的股票代码是真的,但所有价格、收益率和图表都是用一个固定随机种子模拟出来的。置信度是模型真实输出,行情数据不是行情数据。
这一页到底在解决什么问题
一个交易助手暴露了十个普通函数。用户输入一句话。这句话里从来不出现函数名。
"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 工具读一遍签名,把这些参数归成三类:
| 形状 | 写法 | 变成什么 | 例子 |
|---|---|---|---|
| choice | Literal["a", "b"] | 一道 Choice,选项就是这些值 | symbol: Literal["SPY","NVDA","AMD","AAPL","MSFT","TSLA"] |
| set | list[Literal[...]] | 每个成员一道 Noul,问题文本里用 {} 占位 | compare_returns 里的 symbols |
| flag | bool | 一道开/关问题 | 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?" 里那个 {} 是成员占位符,展开就是每个股票代码一道问题。
官方明说的两条写作规则
两条都是关于「意思」而不是「措辞」的,也都特别容易写错:
- 问题要写「想法」,不要写「用户可能用的词」。 因为匹配是按语义走的,所以 “is amd tracking nvidia lately” 能落到
rolling_correlation上——尽管 tracking 和 lately 这两个词在spec.json里一次都没出现过。 - 别拿参数名当问题。 官方的反面例子是
"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 概率。
| 命令 | 调用 | confidence | tool |
|---|---|---|---|
| “show nvda 1h” | plot_price(symbol='NVDA', resolution='1h') | 0.59 | 0.99 |
| “plot rolling correlation between nvda and spy for the past month” | rolling_correlation(symbol='NVDA', benchmark='SPY', window='1mo') | 0.93 | 1.00 |
| “when during the day does nvda trade the most” | intraday_pattern(symbol='NVDA') | 0.53 | 1.00 |
| “what moved today” | top_movers(window='1d', direction='gainers') | 0.90 | 0.94 |
| “what tickers do you have” | list_symbols() | 1.00 | 1.00 |
| “how did the market do this week” | market_summary(window='1w') | 0.94 | 0.98 |
| “candles for tesla with a 20 period moving average” | plot_price(symbol='TSLA', style='candles', moving_average='20') | 0.88 | 1.00 |
| “compare nvda amd and msft over the past three months” | compare_returns(symbols=['NVDA','AMD','MSFT'], window='3mo') | 0.93 | 1.00 |
| “how volatile is tsla” | volatility(symbol='TSLA') | 0.97 | 1.00 |
| “biggest losers today” | top_movers(window='1d', direction='losers') | 0.94 | 1.00 |
| “worst drawdown for nvda this quarter, and chart it please” | drawdown(symbol='NVDA', window='3mo', plot=True) | 0.92 | 0.98 |
| “spy stats for the last month” | summary_stats(symbol='SPY', window='1mo') | 0.97 | 0.98 |
| “show me apple daily with volume” | plot_price(symbol='AAPL', resolution='1d', include_volume=True) | 0.69 | 0.98 |
| “is amd tracking nvidia lately” | rolling_correlation(symbol='AMD', benchmark='NVDA') | 0.69 | 0.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 个处理器之一、每个处理器带一小撮枚举设置」的流水线,都是同一个问题:
- 客服工单路由。 一道在 N 个队列之间选的
Choice,一道优先级Choice,每个标签一道Noul。dispatcher 该待的位置,可以先看客服路由场景。 - 发票审批。 一道「批准 / 驳回 / 升级」的
Choice,一道有界原因码的Choice,外加每条政策检查一道Noul。发票审批闸门案例里有对应的响应体形状。 - 表单或工单分诊。 一道部门
Choice,再按部门给一道子类Choice——这里是分层变体变得相关的地方,因为子类集合可以在第二次请求里依据部门答案来定。
这些能不能成立,前提都是先把枚举定义出来。那 14 条命令能成功,不是因为模型懂交易,而是因为 "1mo"、"3mo"、candles 早就在清单上,而且 spec 说清了每个是什么意思。如果你的处理器收的是自由字符串,那就没有东西可问。
接进去之前的最小清单
- 先做枚举。 任何没法写成
Literal(或小规模list[Literal])的参数都会静默保留默认值。逐个确认那个默认值你能不能接受。 - 每个可选的封闭集合参数都要有
stated问题。 没有它,Choice就只能硬猜。 - 选项描述要能把选项彼此分开。 选项名和描述都会发给模型,真正干活的是描述。
- 日志里记最弱参数,不只是记置信度。 数字告诉你这次调用有风险,名字告诉你要问什么。
- 用「什么都没说清」的命令去测试。 那 14 条全都过了;真正有意思的是 “what moved today” 和 “is amd tracking nvidia lately” 这两条。
- 准备好取最小值,并据此定下限。 官方那张表里 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 并删掉缓存文件——磁盘上已存在的缓存永远不会被覆盖。