Helpers
语言检测
laya.detect_language 就是 laya.lang.analyse。
名称、类型、默认值与代码保持英文;其余为译文(尚未翻译的条目暂显示英文原文)。
analyse
analyse(state: Union[str, bytes, Mapping, list, None]) -> Dict[str, object]对一个状态做完整检测的结果。
返回 script、script_profile、language(尽力而为,可能是 None)、is_english、non_latin_fraction 与 mixed_segment(让一个以英语为主的状态被判成非英语的那一行或那个字段,没有就是 None)。
真正被读取的是字符串值。一个状态里有多个字符串值时,只要有一个非英语就够了:把所有值拼进同一段窗口,会让一段很长的英语备注占满 4000 字符,或者把一条很短的德语消息压过去,于是那条消息被送去了英语 checkpoint(#384)。段落扫描仍然在 4000 字符处停下,正是这一点让超大字段不至于变贵;没扫到的值之后会单独读一遍。
参数
stateUnion[str, bytes, Mapping, list, None]
detect_script
detect_script(text: str) -> strtext 的主导文字系统:'latin'、'han'、'devanagari' …… 没有字母时是 'unknown'。
参数
textstr
is_english
is_english(state: Union[str, bytes, Mapping, list, None]) -> bool当英语 checkpoint 有望读懂这个状态时为 True。
参数
stateUnion[str, bytes, Mapping, list, None]
邮件
clean_email_body
clean_email_body(body: str, max_chars: int = 3000) -> str去掉邮件里被引用的往来历史、签名与免责声明,让输入保持聚焦。
max_chars 是结果被截到的长度,默认 3000 字符 —— 见 email_state,它接受同一个预算并透传下来。
参数
bodystrmax_charsint=3000
email_state
email_state(
subject: str,
body: str,
sender: Optional[str] = None,
clean: bool = True,
max_chars: int = 3000,
extra,
) -> Dict为邮件分类构造一个干净的状态字典。
max_chars 是 clean_email_body 截断正文的预算,消息较长时值得调大:默认值下正文在 3000 字符处就停了,于是写在最后几段里的诉求永远到不了模型 —— 走 predict_long 也一样,它把状态切成窗口扫描,本来就是为了能读到超过一个窗口的内容。clean=False 时忽略此项,正文整段透传。
其它任何关键字都会成为状态的一个字段,因此会被模型读到;这里拼错字不是报错,而是改了输入。例外是取值恰好为 None 的关键字:它会被丢掉而不是加入,所以 email_state(..., thread_id=None) 得到的状态与完全不带这个关键字相同。该键是缺席,而不是 null —— 这个区别会到达模型,因为被分词之前,laya.common.serialize_state 会把状态转成 JSON,所以一个保留下来的 None 会在提示词里写下 "thread_id": null。sender 在同一次调用里按另一条规则被丢掉 —— 是假值而非 None —— 所以 sender="" 也不留下任何 from 字段。
参数
subjectstrbodystrsenderOptional[str]=Nonecleanbool=Truemax_charsint=3000extra
问题预设
triage_questions
triage_questions() -> Dict客服工单分流用的预设问题。
email_questions
email_questions(categories: Optional[Dict[str, str]] = None) -> Dict来信分流与威胁过滤用的预设问题。
参数
categoriesOptional[Dict[str, str]]=None
guard_questions
guard_questions() -> Dict实时 LLM 输入防护栏用的预设问题。
moderation_questions
moderation_questions() -> Dict内容安全与审核用的预设问题。
router_questions
router_questions() -> Dict智能模型路由用的预设问题。
运行前的请求规模估算
一次请求在任何前向传播之前能装下什么。这些是 predict_long 自己读取的辅助函数,所以不持有
Agent 也能测量一个问题:build_head 是序列中问题的那一半,state_room 是它之后留给 state 的
空间,而 build_sequence 报告 head 预算对选项和对 state 做了什么。
from transformers import AutoTokenizer
from laya.common import build_sequence, collapsed_options, state_room, window_budget
tok = AutoTokenizer.from_pretrained("convaiinnovations/laya", subfolder="tokenizer")
max_len, head_max_len = 512, 192 # from the checkpoint's rl_agent_config.json
question = {"type": "choice", "instructions": "What does the customer want?",
"criteria": {"refund": "money back", "cancel": "stop the service"}}
# The short-key internal shape the sizing helpers read; inline the mapping as
# questions-and-answers.md shows rather than reaching into Agent._to_internal.
q = {"t": question["type"], "ins": question["instructions"], "crit": question["criteria"]}
state = "I was charged twice for the same invoice."
state_room(tok, q, max_len, head_max_len) # state tokens this question leaves room for
seq, markers, stats, trunc = build_sequence(
tok, state, q, max_len, head_max_len, return_stats=True, return_truncation_stats=True)
stats # how many options the head budget kept distinct, and the cap it applied
trunc # state tokens, used, dropped, and whether the state was truncated
collapsed_options(["q"], [{"options": stats}]) # {} until an option loses its own span
window_budget(tok, [q], max_len, head_max_len) # (window, stride, room) a scan may use
同样的数字会在一次调用之后出现在 usage 里:state_tokens、state_tokens_dropped、
truncated、truncated_questions,以及当某个选项失去自己的跨度时的 options。那个块记录一次
运行做了什么;上面的辅助函数则是如何在为一次运行付出代价之前就查清楚。当 state 的 token 装得下
它那些问题所留出的空间时,predict_long 直接把它交给一次传播,而扫描窗口以那个空间为上限、步长
为窗口的 50% —— 一个大到会让传播次数成倍增加的窗口会在扫描运行之前先发出警告。
这些都不挑选策略:predict_tournament 之后,锦标赛轮次会以 tournament[qid]["rounds"] 返回,
而候选排序的质量取决于提供它的那个 embedder。
state_room
state_room(tok, q: Dict, max_len: int = 512, head_max_len: int = 192) -> int问题 q 在 max_len 里给状态留下多少 token,也就是 build_sequence 会保留的部分。
决策头是问题自己的 —— 它的指令,加上每个选项一个以 [MASK] 为前缀的 span —— 所以选项多的问题给状态留下的空间比两个选项的问题少,同一个请求里的两个问题也不必留下一样多。超出返回值的部分会被截掉(保留开头;对话轮次列表则保留结尾)。
参数
tokqDictmax_lenint=512head_max_lenint=192
window_budget
window_budget(
tok,
questions,
max_len: int = 512,
head_max_len: int = 192,
window: Optional[int] = None,
stride: Optional[int] = None,
)扫描一个比单个序列还长的状态时所用的窗口大小与步长。
predict_long 会把每个 token 窗口解码回文本、当作普通状态打分,所以一个比问题留出的空间更宽的窗口,在送入时会被 build_sequence 再次截断:每个窗口的尾部到不了模型,而报告的 span 却说它到了。因此窗口被限制在 state_room 内,且取 questions 中最小的那个空间,因为这些窗口是一份状态列表,要为每个问题在共享的前向传播里统一打分 —— 一个按最宽裕问题定尺寸的窗口,对最紧的问题会被截短,而它答案上报告的偏移对每个问题含义都不同。没有问题就没有要适配的东西,所以调用方的窗口(或 checkpoint 的默认值)保持不变。那个默认值是 max(64, max_len - head_max_len - 8):配置留下的状态预算,下面垫着一个 64 token 的下限,所以调大 head_max_len 到那里就不再缩小它。
questions 是内部问题字典,即 Agent._to_internal 返回的那种。
显式给出、比该空间更宽的 window 会被夹到该空间,并给出 RuntimeWarning,因为按请求的尺寸扫描读不到它声称读到的内容。越过有效窗口的 stride 会被拒绝:那样两个窗口之间的 token 谁都不会读到,而这正是 predict_long 存在所要防止的失败。默认步长保留它对有效窗口 50% 的重叠,所以靠近边界的片段仍能完整落进某个窗口;显式给出的、等于窗口的步长仍然读到每一个 token,只是没有重叠去接住横跨边界的片段。
返回 (window, stride, room)。
参数
tokquestionsmax_lenint=512head_max_lenint=192windowOptional[int]=NonestrideOptional[int]=None
collapsed_options
collapsed_options(qids, items) -> Dict[str, Dict[str, Optional[int]]]从逐项统计里找出那些选项已不再各自拥有一个 token span 的问题。
total 是问题定义的选项数,而不是到达序列的 marker 数:按 marker 数来统计,会把一个 28 个选项根本没进入输入的请求报成 "43/58"。
参数
qidsitems
候选筛选
shortlist_choice
shortlist_choice(
state: Any,
criteria: Any,
embed_fn: Callable[[Sequence[str]], Any],
k: int = DEFAULT_SHORTLIST_K,
DEFAULT_SHORTLIST_K,
instructions: Optional[str] = None,
return_scores: bool = False,
) -> Any返回 state 的前 k 个 choice 标签。
embed_fn 把一个字符串列表映射成形状为 (len(texts), dim) 的数组。它只被调用一次:先是查询文本,然后按 criteria 顺序每个选项一个字符串。选项字符串与 choice 问题的 render_options 一致。
当 k 不小于标签数时,所有标签按原顺序返回,且不调用 embed_fn。
并列时保留靠前的标签。排序用的是有符号余弦,而不是相似度下限:得分为 0 的标签 —— 完全没有信号,或者一个非有限向量被当作 0 处理 —— 确实会压过更靠前但得分为负的标签,而 k 会先丢掉负分标签。
return_scores=True 时返回的是 (labels, scores) 对,其中 scores 按排名顺序保存每个保留标签的有符号余弦 —— 就是 predict_shortlist 在其 shortlist 元数据里报告的那些值。当没有丢弃任何标签时,scores 是 None,与该元数据中完全一致。
参数
stateAnycriteriaAnyembed_fnCallable[[Sequence[str]], Any]kint=DEFAULT_SHORTLIST_KDEFAULT_SHORTLIST_KinstructionsOptional[str]=Nonereturn_scoresbool=False
predict_shortlist
predict_shortlist(
agent: Any,
state: Any,
questions: Dict[str, Dict[str, Any]],
embed_fn: Callable[[Sequence[str]], Any],
k: int = DEFAULT_SHORTLIST_K,
DEFAULT_SHORTLIST_K,
predict_kwargs: Any,
) -> Dict[str, Any]先对每个 choice 问题做候选筛选,再调用一次 predict 或 system_one。
非 choice 的问题原样透传。标签数 <= k 的 choice 问题也原样透传,且不调用 embed_fn。调用方传入的 questions 字典不会被修改。
一个被收窄、且原本带 option_order 的 choice 问题,它的顺序会被丢掉,并给出一条点名该问题的 RuntimeWarning:顺序为每个选项留一个槽位,所以一个原先适配调用方标签集合的顺序,不再适配保留下来的标签,agent 会拒绝这个问题。把顺序重新映射到保留下来的标签上,会静默地在槽位之间挪动选项,所以这里选择丢掉它。透传的 choice 问题与非 choice 问题则保留自己的顺序。
返回的字典是模型结果加一个 shortlist 条目。经过筛选的 choice 问题,其概率只在保留下来的标签上归一。shortlist[qid] 里是 labels、scores、k、n 与 passthrough。labels 是筛选产生的排序顺序;当 passthrough 置位、没有做排序时,就是 criteria 本身的顺序。scores 是按该顺序每个保留标签的有符号余弦 —— 包含负值,绝不夹到 0 —— 或者当没有丢弃任何标签时为 None。
额外的关键字参数会透传给 predict / system_one(例如 Router 上的 model=)。
参数
agentAnystateAnyquestionsDict[str, Dict[str, Any]]embed_fnCallable[[Sequence[str]], Any]kint=DEFAULT_SHORTLIST_KDEFAULT_SHORTLIST_Kpredict_kwargsAny
predict_tournament
predict_tournament(
agent: Any,
state: Any,
questions: Dict[str, Dict[str, Any]],
group_size: int = DEFAULT_TOURNAMENT_GROUP,
DEFAULT_TOURNAMENT_GROUP,
predict_kwargs: Any,
) -> Dict[str, Any]用淘汰的方式收窄每个较大的 choice 问题,然后再调用一次 predict。
标签数超过 group_size 的 choice 问题,会按 criteria 顺序切成若干个大小接近、至多 group_size 个的分组。一次 predict 调用为每个这样的问题的所有分组作答 —— 各分组作为独立的问题送入,因此共享一次前向传播 —— 每个分组的答案进入下一轮。如此重复,直到没有 choice 还剩超过 group_size 个标签;默认值 16 时,最多 256 个标签一轮就能收完。与 predict_shortlist 不同,这不需要嵌入器,而且每个标签是按一个 group_size 个标签的问题的选项预算来读的,而不是整个标签集合的预算。
最后一次调用为请求里的每个问题作答,其中经过一轮的每个 choice 都被收窄到它的入围者。非 choice 问题,以及标签数至多 group_size 的 choice,原样进入它,所以当没有任何东西需要一轮时,它就是唯一的一次调用。调用方传入的 questions 字典不会被修改。
经过一轮的 choice 会丢掉它原本带的 option_order,并给出一条点名该问题的 RuntimeWarning:分组与入围者问题保有的标签比调用方的少,顺序不再适配保留下来的标签。把它重新映射过去会静默地在槽位之间挪动选项,所以这里选择丢掉它。不需要一轮的 choice 则保留自己的顺序。
返回的字典是最后一次调用的结果加一个 tournament 条目。每个 choice 问题的 tournament[qid] 里有 labels(入围者,按 criteria 顺序)、n(标签数)与 rounds。概率、置信度与 usage 都来自最后一次调用,所以经过锦标赛的 choice,其概率只在它的入围者上归一。
额外的关键字参数会透传给每一次调用(例如 Router 上的 model=)。
参数
agentAnystateAnyquestionsDict[str, Dict[str, Any]]group_sizeint=DEFAULT_TOURNAMENT_GROUPDEFAULT_TOURNAMENT_GROUPpredict_kwargsAny
embed_fn_from_agent
embed_fn_from_agent(
agent: Any,
max_length: int = 512,
batch_size: int = 32,
) -> Callable[[Sequence[str]], np.ndarray]对 agent 上已经加载好的 checkpoint 编码器做平均池化。
返回的可调用对象用 agent.tok 与 agent.model.encoder 嵌入一个字符串列表。它不跑决策头,也不下载权重。传入一个专门的 bi-encoder 作为 embed_fn 通常能筛得更准;这个辅助函数是给手上只有 Laya checkpoint 的调用方用的。
平均时排除 padding 位置。编码器的 train/eval 标志保持调用方设置的样子(加载好的 Agent 本来就在 eval)。每次调用都用当前的 agent.device,回退到 CPU 之后也一样。
参数
agentAnymax_lengthint=512batch_sizeint=32
cached_embed_fn
cached_embed_fn(
embed_fn: Callable[[Sequence[str]], Any],
maxsize: int = 4096,
) -> Callable[[Sequence[str]], np.ndarray]按输入字符串缓存 embed_fn 的输出,用一个 LRU 上界限制。
predict_shortlist 每次调用都要嵌入查询文本以及每个选项的文本。当每个请求筛选的都是同一组选项 —— 比如固定的意图或标签列表,README 里的 BANKING77 例子就是这样 —— 选项那些行在调用之间并没有变化,却每次都被重新嵌入一遍。把嵌入器包一层:
embed_fn = cached_embed_fn(embed_fn_from_agent(agent))
第一次调用不变,之后每次重复调用都只剩下嵌入新的查询文本。
查表按字符串精确匹配。缓存里没有的文本会先去重,再放在一次 embed_fn 调用里嵌入,所以冷缓存与不包一层时花费的批量调用次数相同。行以 float32 存储;缓存最多保留 maxsize 个字符串,超出后淘汰最久未用的那一项,内存上界约为 maxsize * dim * 4 字节。embed_fn 抛错或返回的形状不对时,什么都不缓存。
这个包装器可以安全地在多个线程间共用:锁只覆盖缓存的读写,从不覆盖嵌入调用本身。返回的可调用对象带有 cache_info() —— 一个含 size、maxsize、hits 与 misses 的字典 —— 以及 cache_clear()。如果 embed_fn 背后的模型或权重换了,请清空缓存。
参数
embed_fnCallable[[Sequence[str]], Any]maxsizeint=4096
弃权
check_min_confidence
check_min_confidence(v: Any)校验可选的弃权阈值 min_confidence(#361、#394)。
要么是 [0.0, 1.0] 区间内的实数(所有答案共用一个阈值;布尔值会被拒绝,尽管 isinstance(True, int) 成立),要么是按桶映射(见 :func:check_min_confidence_map),让阈值可以随选项个数而不同。返回的是校验后的值 —— 标量情形是 float,映射情形是 dict[str, float] —— 下面两个门控函数都接受这种形式。
参数
vAny
check_min_confidence_map
check_min_confidence_map(m: Dict[Any, Any]) -> Dict[str, float]校验一张按桶的弃权阈值映射(#394)。
键是 common.temp_bucket 拼法下的选项数桶 —— :func:bucket_keys 的每一个成员("choice:2"、"choice:3-5"、"score:6-10"、"noul:2" 等等)—— 外加一个可选的 "default",用于映射没有点名的任何桶。除此之外的任何键都会报错:一个没有任何答案能产生的键并不是一个闲置条目,而是一个调用方以为已被门控、实际上却没有的桶,因为 :func:resolve_min_confidence 会越过它回退到 "default",再回退到 0.0 —— 不门控任何东西。值是 [0.0, 1.0] 内的浮点数。一个置信度阈值无法跨选项个数迁移(#394);这让调用方可以按每个桶的校准实际能达到的水平来门控它。用 :func:laya.calibrate.fit_abstention_thresholds 拟合一张,它的键按构造就是这个词表。
参数
mDict[Any, Any]
resolve_min_confidence
resolve_min_confidence(
answer: Dict[str, Any],
thresholds: Dict[str, float],
default: float = 0.0,
) -> float在按桶映射下,这个答案的选项数桶所被门控的阈值。
对于映射没有点名的桶,依次回退到映射的 "default" 条目,再回退到 default(0.0 —— 不门控任何东西),所以未配置的桶永远不会出其不意地弃权。一张经过 :func:check_min_confidence_map 的映射,在这里只可能因为漏掉某个桶而落空:一个拼错到没有任何答案会产生的键,会在校验时就被拒绝,否则它就会走到这层回退,让那个桶不门控任何东西,而它的调用方却以为它已被门控。
参数
answerDict[str, Any]thresholdsDict[str, float]defaultfloat=0.0
flag_low_confidence
flag_low_confidence(results: List[Dict[str, Any]], min_confidence: float) -> None可选的弃权标记(#361):把置信度低于 min_confidence 的答案标出来。
读取 answer_confidence(即 max(p),校准指标所描述、且不随选项个数漂移的那个量),answer_confidence 缺失时退回 confidence。原始答案与置信度保持不变:当答案低于阈值时加上 low_confidence: True,而先前被标记过的答案如果重新达标,就把它去掉(例如结果字典被复用时,或者用不同阈值重新评估时)。
min_confidence 要么是浮点数(所有答案共用一个阈值),要么是按桶映射(#394);后者下,每个答案按它自己选项数所在桶的阈值,经由 :func:resolve_min_confidence 做门控。
参数
resultsList[Dict[str, Any]]min_confidencefloat
apply_confidence_gate
apply_confidence_gate(
results: List[Dict[str, Any]],
min_confidence: Optional[float] = None,
) -> None在真正施加过门控的那些答案上,报告置信度门控的状态。
门控是一种策略,而一个连施加与否都无法观察的策略根本算不上策略。设置 min_confidence 后,这会把 abstention(:data:GATE_STATES 之一)写到每个答案上,同时写上 abstention_threshold,于是调用方能回答三个原本回答不了的问题:
- 有多大比例的决策弃权了,而不是靠
low_confidence是否恰好被设置去反推; - 有多少答案门控无法决定,这是布尔值根本无法表达的;
- 是什么阈值产生了这些结果 ——
flag_low_confidence会把阈值消费掉,所以没有它,一次带逐类阈值的批量运行就无法重新拆分。
GATE_UNEVALUATED 是布尔值无法表达的情形:门控跑了,而答案没有带可用的置信度,于是门控无法决定。把它报告成通过,和报告成一个标记是同一个谎言。
未设置 min_confidence 时,这什么都不写。 没有 abstention,没有 abstention_threshold,也没有标记。这就是全部的约定:一次未门控的调用返回的载荷与之前完全相同,而调用方是靠字段是否出现(而不是从字段里读出的第四个值)判断门控跑过没有。要在每次调用时无条件地调用它,取代 if min_confidence is not None: 这种守卫:正是那种守卫留下了一条什么都不报告的通路,而这正是本函数要区分出来的状态。
标记本身仍归 :func:flag_low_confidence 所有 —— 这里是委托,而不是重新实现那条规则,所以布尔值与所报告的状态不会漂移开。
恰好为 0.0 的 min_confidence 确实被设置了,所以状态会被报告,而 :func:flag_low_confidence 把 0.0 当作空操作,因为没有东西能掉到它下面。于是每个带可用置信度的答案都读作 passed,而阈值回显正是把它与在真实阈值下一次真正的通过区分开的东西。
参数
resultsList[Dict[str, Any]]min_confidenceOptional[float]=None
GATE_STATES
GATE_STATES = (GATE_PASSED, GATE_ABSTAINED, GATE_UNEVALUATED)校准与训练
answer_confidence
answer_confidence(p: np.ndarray, k: int) -> float落在所报告答案上的概率质量:max(p)。
温度缩放拟合的就是这个量,本仓库里每一个校准数字也都是在这个量上算的 —— 两个基准测试框架在调用 ece_score 之前都取 conf = max(probs)。README 的门控一节依赖的是随之而来的性质:在置信度为 c 时返回的答案里,大约有 c 的比例是对的。这个性质是有条件的,而默认情况下条件并不成立 —— 只有在针对这个 checkpoint、这个选项个数,把温度拟合出来并在留出数据上验证过之后才成立。已发布的 checkpoint 是过度自信的:choice:11+ 拟合出的温度是 0.1006,一个约 10 倍的锐化器,会把一个真实的 0.24 最高概率公布成 0.9999。clamp_temperature 拒绝它,改用 TEMP_MIN(0.5),后者仍然锐化 2 倍,把同一个 0.24 公布成 0.4993 —— 所以对这些数字施加阈值仍然会让选中率低于模型准确率(issue #394)。夹紧只是限制了损害,并没有校准任何东西。
下面的 confidence_from_probs 报告的是另一个量、另一个尺度,没有这个保证,所以两者不能拿同一个阈值去比。
参数
pnp.ndarraykint
confidence_from_probs
confidence_from_probs(p: np.ndarray, k: int) -> float归一化香农熵置信度:1 - H(p) / log(k)。
它刻画的是整个分布有多集中。有用,但没有校准:温度缩放拟合的不是它,报告的 ECE 量的也不是它。见 answer_confidence。
参数
pnp.ndarraykint
ece_score
ece_score(conf: np.ndarray, correct: np.ndarray, bins: int = 15) -> float按置信度分箱计算的期望校准误差(ECE)。
参数
confnp.ndarraycorrectnp.ndarraybinsint=15
fit_temperatures
fit_temperatures = fit_temperature_mapfit_one_temperature
fit_one_temperature(pairs: Sequence, min_n: Optional[int] = None) -> float用 NLL + LBFGS 在 log T 上拟合单个标量 T。
结果是优化出的尺度经过 clamp_temperature 之后的值,因此落在 [TEMP_MIN, TEMP_MAX] 内(值不是数时取中性的 1.0)。给出的样本对少于 min_n 时返回 1.0。min_n 默认是 MIN_BUCKET_N(每个桶的下限)。类型级拟合传的是更低的 MIN_TYPE_N,因此一个填不满任何桶的数据集仍然能得到一个标量,而不是停在 1.0。
参数
pairsSequencemin_nOptional[int]=None
fit_temperature_map
fit_temperature_map(
records: Iterable,
compute_ece: bool = False,
seed: int = 0,
) -> Dict[str, Any]拟合类型级标量与逐桶温度。
MIN_BUCKET_N 是每个桶的下限:更小的桶不进入 temperature_by_options,由类型级标量覆盖它们。MIN_TYPE_N 是只作用于那个标量的、单独且更低的下限。
compute_ece=False(默认值,也是 Agent.fit_temperatures 存下来的那条路径)在全部记录上拟合,且不返回 report 键。这条路径上 seed 被忽略。
compute_ece=True 会按 temp_bucket 分层,从每个桶里留出 ECE_HOLDOUT_FRAC 的比例,用 seed 保证同一批记录总是以同样的方式切分。温度只在剩下的部分上拟合,ECE 也只在留出的记录上评分。report["n"] 是传入的记录数;report["n_eval"] 是 ECE 所依据的留出条数。某个桶如果留出之后会低于 MIN_BUCKET_N,就在它的全部记录上拟合、不进入评估集,并写进 report["buckets_excluded_from_eval"],而不是被丢掉。n_by_bucket 始终按完整输入计数,包括拟合本身只用了子集的情况。
参数
recordsIterablecompute_ecebool=Falseseedint=0
fit_abstention_thresholds
fit_abstention_thresholds(
records: Iterable,
temperature: Sequence[float],
temperature_by_options: Dict[str, float],
binning_map: Optional[Dict[str, Dict[str, Any]]] = None,
target_error: float = 0.10,
min_bucket_n: int = MIN_ABSTAIN_BUCKET_N,
MIN_ABSTAIN_BUCKET_N,
conservative: bool = True,
) -> Dict[str, float]拟合一个逐 temp_bucket 的弃权阈值,让门控在每个桶里都守住目标误差。
单个 min_confidence 无法跨选项个数迁移(#394):2 选项与 12 选项答案的校准置信度处在不同的尺度上,所以同一刀切会随问题不同而过度弃权或弃权不足。这个函数改为每个桶拟合一刀,键与 temperature_by_options 完全一致(common.temp_bucket,例如 "choice:3-5"),结果是一张 min_confidence 映射,:func:laya.confidence.check_min_confidence / :func:laya.confidence.apply_confidence_gate 直接接受它。
records 与 fit_temperature_map 消费的是同一批 (qtype, logits, target[, k]) 元组(由 records_from_labeled 构造)。置信度是校准后的 max(p) —— logits 先被拟合出的 temperature / temperature_by_options 缩放,所以阈值与运行时报告的数字处在同一尺度上。target_error 是已接受答案中可容忍的误差;min_bucket_n 会略过太小的桶不拟合,conservative 则加上一样本量的余量。这些阈值是校准集上的经验切点,不是形式化的覆盖率保证 —— 生产门控要在留出数据上验证(fit_temperature_map(..., compute_ece=True) 会给出一个留出切分)。
当将要提供这些阈值的 agent 装了一张 binning_map 时,要把它传进来 —— 无论这张映射是 Agent.fit_binning 装的,还是由带 binning_map 的校准载荷装的 —— 因为运行时会在任何东西读取 answer_confidence 之前,先经由那张映射重新校准它,所以没有它拟合出的切点,落在的是一个门控根本看不到的尺度上。这样阈值就落在分箱后的尺度上,两者拟合的先后顺序也不再重要。在 1,200 条合成的 12 选项记录上、target_error=0.10 时的实测结果:没有映射拟合出的切点,在未分箱置信度上以 50% 覆盖率守住 9.8% 的误差;而一旦把同一个数字与分箱后的置信度相比,它在 25.6% 的误差下就放行了 94.5% 的答案。
参数
recordsIterabletemperatureSequence[float]temperature_by_optionsDict[str, float]binning_mapOptional[Dict[str, Dict[str, Any]]]=Nonetarget_errorfloat=0.10min_bucket_nint=MIN_ABSTAIN_BUCKET_NMIN_ABSTAIN_BUCKET_Nconservativebool=True
fit_binning_map
fit_binning_map(
records: Iterable,
temperature: Sequence[float],
temperature_by_options: Dict[str, float],
bins: int = 15,
min_bucket_n: int = MIN_BINNING_BUCKET_N,
MIN_BINNING_BUCKET_N,
) -> Dict[str, Dict[str, Any]]为 answer_confidence 拟合一张逐 temp_bucket 的直方图分箱重校准映射。
温度缩放对每个桶只施加一个标量;它修不好一条可靠性曲线不是简单锐化/钝化的桶(随英文包发布的 choice:11+ 就是这样一个病态桶)。直方图分箱是非参数替代方案:把一个桶里校准后的置信度分到 [0, 1] 上 bins 个等宽箱里,再把落进某个箱的每个置信度映射到那个箱的经验准确率。它不需要单调性假设,也不需要额外的依赖(只用 NumPy;等渗回归会引入 scikit-learn)。
records 与 fit_temperature_map 消费的是同一批 (qtype, logits, target[, k]) 元组;置信度是校准后的 max(p)(logits 先被拟合出的 temperature / temperature_by_options 缩放),所以分箱映射是叠加在温度映射之上,而不是取代它。返回 {bucket: {"bins": N, "values": [recalibrated confidence per bin]}};低于 min_bucket_n 的桶会被略去。用 :func:apply_binning_map 施加它。空箱(校准集从未产生过的置信度区间)映射到它自己的中点,也就是让那个区域保持不变,所以没见过的值永远不会被重校准成一个凭空捏造的 0。
参数
recordsIterabletemperatureSequence[float]temperature_by_optionsDict[str, float]binsint=15min_bucket_nint=MIN_BINNING_BUCKET_NMIN_BINNING_BUCKET_N
apply_binning_map
apply_binning_map(
confidence: float,
bucket: str,
binning_map: Dict[str, Dict[str, Any]],
) -> float按选项数 bucket(common.temp_bucket)重校准一个 answer_confidence。
当映射里没有该桶的条目时,返回原样的置信度,所以映射没有为它拟合的桶会直接通过,而不是被强行赋一个错误的值。
参数
confidencefloatbucketstrbinning_mapDict[str, Dict[str, Any]]
fit_binning
fit_binning(
records,
min_bucket_n: int = MIN_BINNING_BUCKET_N,
MIN_BINNING_BUCKET_N,
) -> Dict[str, Any]在这个 agent 已拟合的温度之上拟合一张直方图分箱映射,并存下来。
records 与 fit_temperatures 消费的是同一批 (qtype, logits, target[, k]) 元组。这张映射的键与 temperature_by_options 完全一致,叠加在当前温度之上,由 save_calibration 写成 binning_map。
参数
recordsmin_bucket_nint=MIN_BINNING_BUCKET_NMIN_BINNING_BUCKET_N
render_options
render_options(q: Dict) -> List[str]按标签下标顺序渲染选项文本。Noul 的语义顺序永远是 [false, true]。
参数
qDict
proper_reward
proper_reward(
q: torch.Tensor,
target: torch.Tensor,
qtype: torch.Tensor,
mask: torch.Tensor,
w_sph: float = 0.5,
w_rps: float = 1.0,
log_floor: float = -9.21,
) -> torch.Tensor严格 proper 评分规则的奖励:log score + spherical score + ranked probability score。
q: [..., N, K] 报告的分布 target: [N, K](one-hot 或软目标分布)
参数
qtorch.Tensortargettorch.Tensorqtypetorch.Tensormasktorch.Tensorw_sphfloat=0.5w_rpsfloat=1.0log_floorfloat=-9.21
td_lambda_targets
td_lambda_targets(p_true: torch.Tensor, batch: Dict, lam: float = 1.0) -> torch.Tensor多轮对话轨迹的 TD(lambda) 目标。
参数
p_truetorch.TensorbatchDictlamfloat=1.0
QTYPES
QTYPES = {"choice": 0, "score": 1, "noul": 2}QTYPE_NAMES
QTYPE_NAMES = {v: k for k, v in QTYPES.items()}