Jev AI 层级分类:用 Choice 概率在分类树上做 beam search
一句话结论: Jev 的层级分类不是「把一大堆标签一次性丢给模型选」。它是往下走一棵树:每到一个节点,就这一层的直接子节点问一道
Choice,返回的概率就是树上的边权。每层只跟概率最高的那个子节点走,这就是 greedy search——便宜,但早一步错了就回不来。改成保留最好的K条路径,就是 beam search;而它并不比 greedy 多花延迟,因为同一层的 K 道问题是并行的。TypeSafe 官方 cookbook 在三套公开分类体系上把两者都跑了一遍,结论就一句:beam search 命中 3 条期望叶子,greedy 只命中 2 条。 本文就按这份 cookbook 拆:打分公式、代码骨架,以及这个套路什么时候不该用。
本文事实的来源
下面所有内容都在 2026-11-17 核对过 TypeSafe 官方页面与公开示例库:
- Hierarchical classification cookbook——三套层级、greedy 与 beam 的实现、打分公式,以及打印出来的结果表。可执行的 notebook 在
github.com/typesafe-ai/typesafe-public-examples的cookbooks/hierarchical_classification下,三套数据的许可写在同目录的DATA_LICENSE.md。 - Choice 原语页——Choice 返回选中项、每个选项的概率和 confidence 三项;单个 Choice 最多 255 个选项;这一页也直接把深层级/大分类体系指向本 cookbook。
- Models 页——模型 ID
jev-1.14.0,别名jev-latest与jev-preview当前都解析到它,价格 $42 / 十亿 token、$0.042 / 百万 token。
官方明说页里的数字来自 jev-1.14.0、测于 2026-11-03。这是一次带日期的实测,不是通用基准;样本是三个文档,每套层级各一个。它足够讲清机制,但不足以证明你的分类体系上也成立。
层级分类和普通分类不是同一个问题
cookbook 开头没给定义,给的是列举:「Many kinds of data are hierarchies: taxonomies, file systems, websites, codebases, org charts, biological ontologies, LLM skills and moderation policies.」
这个列举比定义有用,因为它把问题放到了「我标签很多」之外的另一个位置。一个三十个标签的平铺分类,就是一道三十选项的 Choice,Choice 页的建议可以直接用上:给全列表、别给候选短名单,因为每个选项也就几个 token,召回比省字更重要。层级不是这种问题。根节点上的候选很少,正确答案在往下第六层、第八层的某个叶子上,而那个叶子旁边的兄弟选项之间的区别,只有在你已经知道自己站在哪的时候才讲得清。
官方搭出来的套路是:从根开始,对根的子节点问一道 Choice,跟概率最高的那个子节点走,重复到叶子为止,那个叶子就是最终分类。这就是 greedy search。它是最顺手的做法——也正因为顺手,整页大部分篇幅都在讲它什么时候会坏。
另外还有一件事是「每个节点问一道问题」自然带出来的,官方把它当成收益列出来而不是副产品:
- 可观测:能看出错误分类最常发生在哪些节点上;能量出每个节点、每条边被遍历了多少次。
- 可测试:分类体系的更新可以做单元测试,也能量化它对分类表现的影响,而不是改完发布再祈祷。
这两个好处之所以成立,是因为树在你的代码里是显式的。如果你把文档直接对着摊平后的叶子列表分类,你只会拿到一个答案,没有任何节点级的证据可看。
greedy search 展开讲
方法就一句话:「choose the highest-probability child and discard every alternative. One early mistake cannot be recovered.」
代码上,greedy 是一个受 MAX_DEPTH 限制的循环,而且它把收到的每一个分布都记下来,好让遍历图能给每条边标上概率:
def greedy_search(hierarchy: Hierarchy) -> dict:
"""Follow only the locally highest-probability child."""
path, probability_product, decision_count, records = (), 1.0, 0, []
for _ in range(MAX_DEPTH):
labels = tuple(subtree(hierarchy.tree, path))
if not labels:
break
probabilities = choose(hierarchy.document, child_question(labels), model=TYPESAFE_MODEL)
records.append(choice_record(path, probabilities))
label = max(probabilities, key=probabilities.get)
if len(probabilities) > 1:
probability_product *= max(probabilities[label], EPSILON)
decision_count += 1
path += (label,)
score: float = (
probability_product ** (1 / decision_count) if decision_count else 1.0
)
return {"path": path, "score": score, "records": records}
这个循环里有两个细节,看着不起眼,实际分量很重。
只有一个子节点的节点不算一次决策。 choose 里的守卫是 if len(keys) == 1: return {label: 1.0 for label in keys.values()}——只有一个选项就直接短路返回确定值,连请求都不发。同样的意思在 extend_candidate 里写作 is_decision: bool = len(probabilities) > 1,decision_count 只在它为真时才加一。深层分类体系里到处是「某个概念只有一个子概念」的链;如果把这些也算成决策,一个深叶子就会被算成回答了更多问题,而它其实一个问题都没多答。
每个概率都被 EPSILON = 1e-9 兜底。 max(probabilities[label], EPSILON) 是为了防止连乘掉到零——一旦为零,几何平均也就是零,路径之间就没法比较了。这个下限不是对「这个选项有多不可能」的建模判断,只是让一个算术操作继续能用。
greedy 到底在哪坏掉
官方的失败样例值得整段抄下来,因为错在哪一层本身就是这一课。三条标注样例都过两种策略,零售那条是这样的:
「Furniture listing: a wall-mounted window shelf bed. This padded floating shelf uses suction cups and a washable cushion as a sunny perch for one cat.」
期望叶子是 Cat Window Beds & Perches。greedy 落在 Pet Chairs。
这段话里没有一个字是错的,链上也没有哪一步是瞎答的。listing 说了 furniture,说了 wall-mounted,说了 padded shelf,说了 perch。Chair 在树的某一层上确实是 bed 的合理兄弟,而一旦 greedy 做了选择,后面任何一次回答都不再有投票权。这就是官方那句「early mistake cannot be recovered」的全部含义:错误不在叶子上——在叶子上信息本来是够把问题解开的——而在叶子上方某一层,而那一层的信息更薄。
专利那条 greedy 没出错:一段描述「供家禽或宠物鸟使用的独立式木质栖架」的摘要,落在 A01K31/12 Perches for poultry or birds, e.g. roosts。生物医学那条也没错:一段写了透壁性回结肠炎症、跳跃性病变、英夫利昔单抗缓解的克罗恩病摘要,落在 C06.405.469.432.500 Crohn Disease。三条里贪心对两条,这就是结论——而且这是关于这三个样本的结论,不是一个比率。
beam search:保留 K 条,仍然每层一轮
修法一句话:「retain K plausible paths and classify every frontier in parallel. When an early choice is close, a clearer decision further down can put the right path back on top. The leaf of the path with the highest geometric-mean probability is the final classification.」
它之所以不贵,理由在 Choice 页也出现过、cookbook 又重复了一遍:System One 的问题本身可以并行,所以「the beam’s K questions at each level run in parallel, so beam search takes one round of calls per level, as greedy search does.」
这句话就是全部的成本论证,值得读准:beam search 增加的不是延迟轮次,而是一轮里的请求数,进而是 token。官方实现把并发写得很直白——一个 ThreadPoolExecutor(max_workers=BEAM_WIDTH) 把 choose 映射到当前前沿,一个候选一道 Choice:
for _ in range(MAX_DEPTH):
expandable = [
candidate
for candidate in beam
if subtree(hierarchy.tree, candidate["path"])
]
finished = [
candidate
for candidate in beam
if not subtree(hierarchy.tree, candidate["path"])
]
if not expandable:
break
with ThreadPoolExecutor(max_workers=BEAM_WIDTH) as executor:
distributions = list(
executor.map(
lambda candidate: choose(
hierarchy.document,
child_question(tuple(subtree(hierarchy.tree, candidate["path"]))),
model=TYPESAFE_MODEL,
),
expandable,
)
)
然后把每个可展开候选的所有子节点都变成新候选,再重排 beam:
beam = sorted(
finished + expanded,
key=lambda candidate: candidate["score"],
reverse=True,
)[:BEAM_WIDTH]
这里 finished 才是关键的一半。已经走到叶子的路径没有子节点了,所以它不再被提问,但它继续留在排序里。短路径能和长路径公平竞争,靠的就是这个——比较的标准不是「谁更深」,而是各自的几何平均。
打分公式:为什么是几何平均
官方把公式给了两遍,一遍散文一遍代码,要记的是散文那版:
path_score = product(edge_probabilities) ** (1 / decisions)
后面跟着一句提醒:「for hierarchies deeper than about 10 levels, compute it as exp(mean(log(probs))) to avoid floating-point precision loss」。代码里这句提醒以注释形式存在——「Use log space for very deep trees to avoid floating-point precision loss」——而 extend_candidate 本身是直接算幂的。如果你的分类树超过十层,那条注释就是该换算法的信号。
为什么不用直接连乘:「The geometric mean, unlike the raw product, doesn’t penalize a deep leaf just for taking more decisions.」八个概率连乘肯定小于四个概率连乘,哪怕这八个都很高。拿六层路径和三层的原始乘积比,比的是路径长度,不是路径质量。指数 1 / decisions 就是把这个影响消掉。
官方报告的第二个数字是 separation 比值:
separation = top_path_score / second_path_score
「reported only, not used for pruning. Near 1×, the top two paths are almost tied; the further above 1×, the clearer the winner.」compare_searches 里的写法是 top_score / max(second_score, EPSILON),打印时格式化成 f"{result['separation_ratio']:.2f}×"。
「只报告、不剪枝」是个设计选择,你在自己代码里可以改。这个数字回答的正是「这次 beam 的冠军果断吗」——1.01 倍意味着前两名基本是掷硬币,拿 separation 设阈值去触发人工复核或第二意见是很自然的用法。官方没做这件事,它只是把数字打出来让你自己决定。真要这么用,得记住这是两个「剪枝后活下来的路径」之间的比值,宽度为 1 的 beam 根本没有第二条路径,也就没有 separation。
跑出来的结果
结论只出现一次,然后才是表:
Beam search matched 3 of 3 expected leaves; greedy search matched 2 of 3. Keeping three paths recovered the expected classification for Shopify products.
| 层级 | 期望叶子 | greedy 叶子 | beam K=3 叶子 | greedy 正确 | beam 正确 |
|---|---|---|---|---|---|
| CPC patents | A01K31/12 Perches for poultry or birds, e.g. roosts | A01K31/12 Perches for poultry or birds, e.g. roosts | A01K31/12 Perches for poultry or birds, e.g. roosts | yes | yes |
| Shopify products | Cat Window Beds & Perches | Pet Chairs | Cat Window Beds & Perches | no | yes |
| MeSH biomedical subjects | C06.405.469.432.500 Crohn Disease | C06.405.469.432.500 Crohn Disease | C06.405.469.432.500 Crohn Disease | yes | yes |
这张表要按它本来的样子读。三个文档、三套层级、一处不一致。它能支持的结论是机制层面的——宽度 3 的 beam 能把 greedy 已经丢掉的路径留住;它不能支持任何看起来像准确率的东西。官方没有公布每套层级的节点数,也没有公布精确率、召回率之类的聚合指标,连它自己的表里都没有这两列。把 3/3 当示范看,别当基线。
cookbook 输出的后半部分是每套层级一张图:各一张静态 SVG,把两种策略查过的节点都画出来,只标注前几条边的概率(布局常量里 EDGE_TOP_K = 5),两条路径分别标出。CPC 和 MeSH 两种策略结论一致,图就是一条路线;Shopify 那张能看到被丢掉的分支——那本来是你只能从日志里重建的画面。
三套层级与 MeSH 那个坑
- CPC 2026.05——专利技术主题,「从宽的技术大类到窄的具体发明」,由欧洲专利局与美国专利商标局发布。加载器遍历 scheme XML 的
classification-item,每个分类号只保留第一次见到的父节点,根节点取level属性为 2 的那些分类号,节点标签拼成"{symbol} {title}"。 - Shopify 2026-02——零售商品类目,「从店铺部门到具体商品类型」,来自 Shopify Product Taxonomy(MIT)。读
categories.txt,先按" : "切出 id,再按" > "切出路径。 - MeSH 2026——生物医学主题,「从宽领域到具体疾病」。MeSH 是 DAG,一个 descriptor 可以出现在多个父节点下;官方给它每一个官方 tree number 各展开成一条独立路径。来源是美国国家医学图书馆,具体是 2026 年 1 月的构建,官方同时提醒这未必是最新的 MeSH 数据。
MeSH 这个例子最能迁移。大多数生物医学本体,以及相当多企业内部的知识树,都是「披着树皮的图」。官方的解法不是去写图搜索,而是把路径枚举出来,从构造上把 DAG 变成树:
for tree_number in sorted(names_by_tree_number):
parts: list[str] = tree_number.split(".")
prefixes: list[str] = [
".".join(parts[:index]) for index in range(1, len(parts) + 1)
]
category_code: str = tree_number[0]
category_path: tuple[str, ...] = (
f"{category_code} {MESH_CATEGORIES[category_code]}",
*(f"{prefix} {names_by_tree_number[prefix]}" for prefix in prefixes),
)
_insert(tree, category_path)
首层是分类字母,经一张十六项的映射表转成可读名字——A Anatomy、B Organisms、C Diseases,一直到 V Publication Characteristics、Z Geographicals。tree number 上每一级点分层级都变成一个中间节点。一个有三个 tree number 的 descriptor 因此在三个位置变成三片叶子,从任何一条路都能走到它。
因为 NLM 是原地更新当前 MeSH 文件的,cookbook 没有直接链 NLM,而是把一份钉死的副本放在示例库里,并注明这是 2026 年 1 月的构建、可能滞后。
环境、缓存语义,以及「复现这些数字要花什么」
文档要求很短:Python 3.10 或更高,以及
pip install typesafe-sdk ipython 'cooksafe>=0.3.0,<0.4.0'
代码回放已保存的答案,「so it runs as published without an API key」。要改动某个请求就设 TYPESAFE_API_KEY;在 Colab 里 notebook 会从 Secrets 面板把 key 复制进环境,外面套着 try: from google.colab import userdata,非 Colab 环境下退化成 userdata = None。客户端构造时是 api_key=os.environ.get("TYPESAFE_API_KEY", "cache-only"),重试策略 RetryPolicy(max_retries=5, backoff_initial=1.0, backoff_max=20.0)。
首次运行会把三套层级(约 28 MB)下载到 datasets/。下载走的是钉死的 URL,先写 .tmp 再替换,所以半截的下载不会变成缓存。
答案自己还有一层缓存,它的语义值得抄进你自己的管线:
CACHE = Path("hierarchical_classification_cache.json"),用cooksafe的@json_cache装饰。DOWNLOAD_CACHE = True会把已发布的答案填进缓存,「so the run makes no requests」。- 要真跑就「set it to
Falseand deleteCACHE; aCACHEalready on disk is never overwritten」。
最后半句最重要。它的意思是:跑到一半的成果不会被悄悄和新一轮重放混在一起——你要么删文件,要么不删,文件的存不存在直接决定你处在哪种模式。
常量全在一个块里,这本身就是回答「怎么调参」的实用答案:
TYPESAFE_MODEL = "jev-1.14.0" # the page's model; "jev-latest" runs the newest, live
BEAM_WIDTH, MAX_DEPTH, EPSILON = 3, 12, 1e-9
MAX_DEPTH = 12 是两种策略共用的循环上限,BEAM_WIDTH = 3 同时是 beam 宽度和线程池大小,EPSILON 就是前面那个概率下限。
token 成本:把账算清楚
延迟那句话官方给了:每层一轮调用,与 greedy 相同。token 的账官方没算,而钱恰恰花在这儿。
按 models 页,一次请求由 state 加若干问题组成,Jev「ingests the state once and evaluates every question against it in parallel」,单请求上下文上限管的是「state 加全部问题」。在这份 cookbook 里,每个 choose 调用都是把文档当 state、只带一道 Choice。所以宽度 K 的 beam 每层发 K 个请求,每个请求都把同一份文档当 state 重发一遍——相比 greedy,这是每层 K 倍的 state token,再加上多出来的那些问题。把这一层前沿的 K 道问题合成一个请求、一份 state、K 道问题,就能把这块砍掉(一次摄入、更多问题),但那样每个候选的缓存语义就变了——大概也是官方坚持一个候选一个调用的原因。
按价格感受一下量级:jev-1.14.0 为 $42 / 十亿 token、$0.042 / 百万 token,与 jev-1.13.0 相同。几千 token 的文档、宽度 3、走八层,单文档的 token 账是零点几分钱的下方,不是几美元。需要算它是因为它会漂:宽度和深度是相乘的,一张需要 BEAM_WIDTH = 8、走十二层的树,就是你已经觉得便宜的那次运行的 8 倍。
什么时候不该这么走
有三种情况,这套走法本身就不对形:
- 子节点集合小到可以一次问完。 一道
Choice最多 255 个选项,Choice 页的建议也是给全列表而不是短名单。如果你的整个分类体系不到 255 个叶子,摊平、一次问完:你拿到的是一道覆盖真实答案集合的分布,而不是一串局部判断,深度上限和 beam 宽度两件事一起消失了。 - 你已经有一个基于置信度的分流决策。 如果问题其实是「这条紧急吗、要不要转人工」,那是
Noul加阈值——见 置信度与兜底——不是树遍历。树是给分类体系用的,阈值是给分诊用的。 - 兄弟选项之间的差别离不开标签本身。 这套走法成立的前提是每个节点上的那道
Choice有一组好选项。如果你的节点标签是没人认得的内部编码——团队 id、SKU 前缀、不透明的工单分类——模型能拿到的信息就只有那串编码。Choice 页的建议在每一层都适用:选项名和选项描述才是做区分的东西。
还有第四种,语气软一点:当叶子是要被审计的。 每层都是一次独立判断,各带自己的分布,而路径分数是它们的连乘。如果这个分类要承担合规重量,需要辩护的面就太多了。greedy 留下的审计痕迹短,一次平铺的 Choice 最短。
它在整套工具里站在哪
这页靠的零件本站都写过。三个原语讲 Choice、Noul 与生成式回答各自负责什么;state 与问题讲一个请求怎么组织、state 为什么只摄入一次;请求模式讲扇出与路由这些形状,beam 只是其中一种特例;结构化抽取讲的是相反方向——把值取出来,而不是在选项里挑。
旁边还有两个场景:工单分流本质就是一个两层分类体系能解决的问题;RAG 重排是它的兄弟问题——给候选排序,而不是走树。工单情绪分流案例和商品 FAQ 打分案例展示的是单道 Choice 层面的请求与响应形状。
如果你要的是 cookbook 家族在同一个原语上搭出的另一种结构——把带类型函数的参数变成问题——那是 Jev AI 函数调用。而如果一次遍历的失败看起来像模型的问题而不是你的树的问题,失效模式那页列了官方记录过的坑,改 prompt 之前先去对一遍。
FAQ
这和「把所有叶子放进一道 Choice」是一回事吗?
不是,差别在信息从哪来。平铺的 Choice 要求模型一次把整套分类扛住;遍历则是在每个节点问一个小问题,用答案去选下一个问题。官方给出的遍历理由是复合的:每一步的候选集都保持很小,而且整条遍历是可观测的,节点级能看到错在哪。如果你的分类体系塞得进 255 个选项、叶子之间又足够好区分,平铺版本更简单,还直接给你一道覆盖真实答案的分布。
为什么留三条而不是两条、八条?
官方钉死 BEAM_WIDTH = 3,并报告宽度 3 救回了 Shopify 那一例——这是整页唯一的证据。它没有做宽度扫描,所以「K 该取多少」在官方页面里没有实测答案。从机制上推:更宽意味着正确分支更有机会活着,同时每层的 state token 线性增加,而宽到某个点之后,多出来的路径本来就是你永远不会选的。
为什么不用 confidence 当路径分数?
因为路径分数是把边概率连乘,而单道问题的 confidence 是从一个分布的形状算出来的——同一个 0-1 刻度上的两个不同量。官方的做法是用 probabilities,跨决策取几何平均,然后报告前两名路径的 separation。要看另一个视角,每个节点回答里的 confidence 就在同一个响应里,是记录可观测性时最自然的字段——官方对已录分布的用法正是这一种。
撞到深度上限会怎样?
MAX_DEPTH = 12 会同时停下两个循环。beam search 在没有任何候选可展开时提前 break(也就是 beam 里每个候选都是叶子),否则十二轮后停。比十二层更深的分类树会被截断,而代码对此没有任何报错;那句「超过十层改用 log 空间计算」的提醒,本身就是官方在暗示它预期的是浅树。
一定要用这三套层级吗?
不用。加载函数是给 CPC XML、Shopify 的 categories.txt 和 MeSH descriptor XML 写的,但遍历本身只要一个 Tree(嵌套的标签字典)、一段文档、一个期望叶子。任何能用嵌套字典表达的分类体系都能直接丢进 beam_search 和 greedy_search。MeSH 那一例唯一证明的要求是:图得先展开成路径。
它能替代重排或阈值吗? 不能。它做的是把文档定位到分类体系里的某个位置。重排是给候选排相关性序;阈值是把一个概率变成带下限的是/非。两者唯一的接触点就是 separation 比值,而官方在那个点上刻意停在了「只报告」。