ヘルパー
言語検出
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)を返します。
実際に読まれるのは文字列の値です。1 つの状態に複数の文字列があるときは、非英語の値が 1 つあれば十分です。すべての値を 1 つのウィンドウに連結すると、長い英語のメモが 4000 文字を埋め尽くしたり、短いドイツ語のメッセージを押しのけたりして、そのメッセージが英語チェックポイントへ送られてしまいました(#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英語チェックポイントがこの状態を読めると期待できるときに 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 を通しても同じです。あれは 1 つのウィンドウ分を超えて読むために、まさに状態をウィンドウに切っているのですから。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、そして選択肢が自分の span を失ったときの options です。
そのブロックは実行が何をしたかの記録で、上のヘルパーは 1 回払う前に知る方法です。predict_long
は、state のトークンがその質問の残す余地に収まるとき、そのまま 1 回のパスへ渡します。スキャン
窓はその余地で上限され、ストライドは窓の 50% です —— パスを倍増させるほど大きい上限は、
スキャンが走る前に警告します。
これらはいずれも戦略を選びません。トーナメントのラウンドは predict_tournament の後に
tournament[qid]["rounds"] として返り、ショートリストのランキング品質はそれに供給する
埋め込み器に委ねられます。
state_room
state_room(tok, q: Dict, max_len: int = 512, head_max_len: int = 192) -> intq が max_len 内に残す状態トークン数で、build_sequence が保つものです。
ヘッドは質問自身のもので —— その instructions に加えて、選択肢ごとに 1 つの [MASK] プレフィックス付きスパン —— 、選択肢の多い質問は 2 択の質問より状態に残す余地が少なく、同じリクエスト内の 2 つの質問が同じ量を残さなければならないわけでもありません。戻り値を超えるものは切り落とされます(先頭が保たれるか、会話ターンのリストでは末尾が保たれます)。
引数
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,
)1 つの系列より長い状態を走査するためのウィンドウサイズとストライド。
predict_long は各トークンウィンドウをテキストへデコードし、普通の状態として採点するので、質問が残す余地より広いウィンドウは入る途中で build_sequence に再び切り詰められます。すると各ウィンドウの末尾はどのモデルにも届かないのに、報告される範囲は届いたと言います。したがってウィンドウは state_room で、かつ questions の最小の余地で上限が掛かります。ウィンドウは、共有のフォワードパスで質問ごとに採点される 1 つの状態リストだからです —— 最も余裕のある質問に合わせたウィンドウは、最も厳しい質問では切り詰められ、その答えに報告されるオフセットは質問ごとに違う意味になってしまいます。質問がなければ収めるものが何もないので、呼び出し側のウィンドウ(またはチェックポイントの既定値)がそのまま使われます。その既定値は max(64, max_len - head_max_len - 8) です。config が残す状態予算に、64 トークンの下限を敷いたもので、head_max_len を広げてもそこで縮まなくなります。
questions は、Agent._to_internal が返すような内部の質問 dict です。
余地より広い明示的な window は、RuntimeWarning とともにそれへクランプされます。要求したサイズでの走査は、主張するものを読めないからです。実効ウィンドウを超える stride は拒否されます。2 つのウィンドウの間のトークンがどちらからも読まれなくなるからであり、それが predict_long が防ぐために存在する失敗です。既定のストライドは実効ウィンドウの 50% の重なりを保つので、境界の近くの範囲もどこかのウィンドウに丸ごと収まります。ウィンドウと等しい明示的なストライドでもすべてのトークンは読まれますが、境界をまたぐ範囲を捉える重なりはありません。
(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]]]アイテムごとの統計から、選択肢がもはやそれぞれトークン幅を持たない質問です。
total はその質問が定義する選択肢数で、系列に届いたマーカーの数ではありません。マーカーから数えたレポートは、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,
) -> Anystate の上位 k 件の choice ラベルを返します。
embed_fn は文字列のリストを形状 (len(texts), dim) の配列に写します。呼び出しは 1 回だけで、まずクエリ文字列、続いて criteria の順に各選択肢の文字列が渡されます。選択肢の文字列は choice 質問の render_options と一致します。
k がラベル数以上のときは、すべてのラベルが元の順序で返り、embed_fn は呼ばれません。
同点のときは先のラベルが残ります。順位付けは相似度の下限ではなく符号付きコサインです。スコア 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 を 1 回呼びます。
choice 以外の質問はそのまま渡されます。ラベル数が <= k の choice はそのまま渡され、embed_fn を呼びません。呼び出し側の questions 辞書は変更されません。
option_order を運んでいた絞り込み済みの choice は、それを落とされます。質問を名指しする RuntimeWarning が 1 つ出ます。順序は選択肢ごとに 1 つのスロットを持つので、呼び出し側のラベル集合に合っていた順序は、残ったラベルにもはや合わず、エージェントはその質問を拒否します。順序を残ったラベルへ対応し直すとスロット間で選択肢が黙って移ってしまうので、代わりに落とされます。素通りした 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 をもう 1 回呼びます。
group_size を超えるラベルを持つ choice は、criteria 順に、ほぼ等しい大きさで最大 group_size のグループへ切り分けられます。1 回の predict 呼び出しが、そのようなすべての質問のすべてのグループに答えます —— グループは別々の質問として入るので、1 回のフォワードパスを共有します —— そして各グループの答えが次のラウンドへ進みます。どの choice も残りのラベルが group_size を超えなくなるまでラウンドを繰り返します。既定の 16 では、256 ラベルまで 1 ラウンドで済みます。predict_shortlist と違い、埋め込み器を必要とせず、各ラベルはラベル集合全体の予算ではなく group_size ラベルの質問の選択肢予算で読まれます。
最後の呼び出しがリクエストのすべての質問に答えます。ラウンドを通った各 choice はファイナリストへ切り詰められます。choice 以外の質問と、group_size 以下のラベルの choice はそのままそこへ行くので、ラウンドが必要なければそれが唯一の呼び出しです。呼び出し側の questions 辞書は変更されません。
ラウンドを通った choice は、運んでいた option_order を失います。質問を名指しする RuntimeWarning が 1 つ出ます。グループとファイナリストの質問は呼び出し側より少ないラベルしか持たず、順序はもはや残ったラベルに合いません。それを対応し直すとスロット間で選択肢が黙って移ってしまうので、代わりに落とされます。ラウンドを必要としなかった choice は自分の順序を保ちます。
返る辞書は最後の呼び出しの結果に tournament の項目を足したものです。tournament[qid] は各 choice 質問について 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 にすでに読み込まれているチェックポイントのエンコーダーを平均プーリングします。
返る呼び出し可能オブジェクトは agent.tok と agent.model.encoder で文字列のリストを埋め込みます。決定ヘッドは走らせず、重みのダウンロードも行いません。embed_fn として専用の bi-encoder を渡したほうがたいてい精度よく絞り込めます。このヘルパーは、手元に Laya のチェックポイントしかない呼び出し側のためのものです。
平均からは padding の位置を除きます。エンコーダーの train/eval フラグは呼び出し側が設定したままにします(読み込み済みの Agent はすでに eval です)。各呼び出しは、CPU フォールバックのあとでも、そのときの agent.device を使います。
引数
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))
最初の呼び出しは変わらず、2 回目以降は新しいクエリだけを埋め込めば済みます。
照合は文字列の完全一致です。キャッシュにないテキストは重複を除いたうえで 1 回の 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] の実数(すべての答えで 1 つのしきい値。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] の浮動小数点数です。1 つの信頼度しきい値は選択肢数をまたいで移せません(#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 は浮動小数点数(すべての答えで 1 つのしきい値)か、バケットごとのマッピング(#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 の 1 つ)をすべての答えに書き込み、さらに abstention_threshold も書き込むので、呼び出し側はそうでなければ答えられない 3 つの問いに答えられます:
- 意思決定のうちどれだけの割合が棄権したか ——
low_confidenceがたまたま設定されたかどうかから推測するのではなく。 - ゲートが決定できなかった答えがいくつあるか。これは真偽値ではまったく表現できません。
- どのしきい値がこの結果を生んだか ——
flag_low_confidenceはしきい値を消費して捨ててしまうので、これがなければクラスごとのしきい値を持つバッチ実行を分割し直せません。
GATE_UNEVALUATED は真偽値が表現できない場合です。ゲートは走ったものの、答えが使える信頼度を持っていなかったため、ゲートは決定できませんでした。それを通過として報告するのは、フラグとして報告するのと同じ嘘です。
min_confidence を設定しない場合、これは何も書き込みません。 abstention も abstention_threshold もフラグもありません。それが契約のすべてです。ゲートされていない呼び出しは以前とまったく同じペイロードを返し、フィールドの有無(そこから読み取られる 4 つ目の値ではなく)が、ゲートが走ったことを呼び出し側に伝えます。if min_confidence is not None: のガードの代わりに、呼び出しごとに 1 回、無条件に呼び出してください。そのガードこそ、何も報告しない経路を残すものであり、この関数が区別するために存在する状態です。
フラグ自体は :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)。
温度スケーリングが当てはめるのはこの量で、このリポジトリの較正に関する数値はすべてこの量の上で計算されています —— 2 つのベンチマークハーネスはどちらも ece_score を呼ぶ前に conf = max(probs) を取ります。README のゲートの節が依拠しているのは、それに付随する性質です。信頼度 c で返された答えのうち、およそ c の割合が正しい、という性質です。この性質は条件付きで、既定ではその条件は満たされていません。このチェックポイントとこの選択肢数について温度を当てはめ、ホールドアウトデータで検証してはじめて成り立ちます。配布されているチェックポイントは自信過剰です。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) -> floatlog T 上で NLL + LBFGS により 1 つのスカラー 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 選択肢の答えの較正済み信頼度は異なる尺度にあり、同じ 1 つのカットでは質問によって棄権しすぎたり足りなかったりします。これは代わりにバケットごとに 1 つのカットを当てはめ、キーは temperature_by_options とまったく同じにします(common.temp_bucket、例えば "choice:3-5")。結果は :func:laya.confidence.check_min_confidence / :func:laya.confidence.apply_confidence_gate が直接受け付ける min_confidence マップです。
records は fit_temperature_map が消費するものと同じ (qtype, logits, target[, k]) タプルです(records_from_labeled が組み立てます)。信頼度は較正済みの max(p) です —— logits はまず当てはめた temperature / temperature_by_options でスケーリングされるので、しきい値とランタイムが報告する数値は同じ尺度上にあります。target_error は受け入れた答えのうち許容する誤差です。min_bucket_n は小さすぎて当てはめられないバケットを省き、conservative は 1 サンプル分の余裕を加えます。しきい値は較正集合上の経験的なカットであり、形式的なカバレッジの保証ではありません —— 本番のゲートではホールドアウトデータで検証してください(fit_temperature_map(..., compute_ece=True) がホールドアウト分割を与えます)。
これらのしきい値を提供する agent に binning_map がインストールされている場合は、それを渡してください —— Agent.fit_binning によってでも、binning_map を運ぶ較正ペイロードによってでも —— ランタイムは何かが読む前に answer_confidence をそのマップを通して再較正するので、それなしで当てはめたカットは、ゲートが決して見ない尺度上のカットになります。そのときしきい値はビニング後の尺度上にあり、2 つを当てはめた順序は問題にならなくなります。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 ごとのヒストグラムビニング再較正マップを当てはめます。
温度スケーリングはバケットごとに 1 つのスカラーを適用します。信頼性曲線が単純な鋭化/鈍化でないバケットは直せません(配布されている英語チェックポイントが持つ病的な choice:11+ がその 1 つです)。ヒストグラムビニングはノンパラメトリックな代替策です。バケットの較正済み信頼度を [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ある answer_confidence を、その選択肢数の bucket(common.temp_bucket)に合わせて再較正します。
マップにそのバケットのエントリがないときは信頼度を変えずに返すので、マップが当てはめていないバケットは、誤った値に押し込まれることなくそのまま通ります。
引数
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]このエージェントが当てはめた温度の上に、ヒストグラムビニングのマップを当てはめて保存します。
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()}