ドキュメント

ヘルパー

言語検出

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) -> str

text の主要な文字体系です。'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 も参照してください。

引数

bodystr
max_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 フィールドを残しません。

引数

subjectstr
bodystr
senderOptional[str]= None
cleanbool= True
max_charsint= 3000
extra

質問プリセット

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) -> int

q が max_len 内に残す状態トークン数で、build_sequence が保つものです。

ヘッドは質問自身のもので —— その instructions に加えて、選択肢ごとに 1 つの [MASK] プレフィックス付きスパン —— 、選択肢の多い質問は 2 択の質問より状態に残す余地が少なく、同じリクエスト内の 2 つの質問が同じ量を残さなければならないわけでもありません。戻り値を超えるものは切り落とされます(先頭が保たれるか、会話ターンのリストでは末尾が保たれます)。

引数

tok
qDict
max_lenint= 512
head_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) を返します。

引数

tok
questions
max_lenint= 512
head_max_lenint= 192
windowOptional[int]= None
strideOptional[int]= None

collapsed_options

collapsed_options(qids, items) -> Dict[str, Dict[str, Optional[int]]]

アイテムごとの統計から、選択肢がもはやそれぞれトークン幅を持たない質問です。

total はその質問が定義する選択肢数で、系列に届いたマーカーの数ではありません。マーカーから数えたレポートは、28 の選択肢が入力にまったく入らなかったリクエストについて「43/58」と言ってしまいます。

引数

qids
items

候補の絞り込み

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) の配列に写します。呼び出しは 1 回だけで、まずクエリ文字列、続いて criteria の順に各選択肢の文字列が渡されます。選択肢の文字列は choice 質問の render_options と一致します。

k がラベル数以上のときは、すべてのラベルが元の順序で返り、embed_fn は呼ばれません。

同点のときは先のラベルが残ります。順位付けは相似度の下限ではなく符号付きコサインです。スコア 0 のラベル —— 信号がまったくないか、非有限のベクトルがそう扱われたもの —— は、負のスコアだった先のラベルを追い越します。そして k は負のラベルから先に落とします。

return_scores=True のときの戻り値は (labels, scores) のペアで、scores は順位順に残った各ラベルの符号付きコサインを保持します —— predict_shortlist がその shortlist メタデータで報告するのと同じ値です。何も捨てられなかったとき scores は None で、そのメタデータとまったく同じです。

引数

stateAny
criteriaAny
embed_fnCallable[[Sequence[str]], Any]
kint= DEFAULT_SHORTLIST_K
DEFAULT_SHORTLIST_K
instructionsOptional[str]= None
return_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=)。

引数

agentAny
stateAny
questionsDict[str, Dict[str, Any]]
embed_fnCallable[[Sequence[str]], Any]
kint= DEFAULT_SHORTLIST_K
DEFAULT_SHORTLIST_K
predict_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=)。

引数

agentAny
stateAny
questionsDict[str, Dict[str, Any]]
group_sizeint= DEFAULT_TOURNAMENT_GROUP
DEFAULT_TOURNAMENT_GROUP
predict_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 を使います。

引数

agentAny
max_lengthint= 512
batch_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.ndarray
kint

confidence_from_probs

confidence_from_probs(p: np.ndarray, k: int) -> float

正規化シャノンエントロピー信頼度:1 - H(p) / log(k)。

分布全体がどれだけ集中しているかを表します。有用ですが較正されてはいません。温度スケーリングが当てはめるのはこれではなく、報告される ECE が測るのもこれではありません。answer_confidence を参照してください。

引数

pnp.ndarray
kint

ece_score

ece_score(conf: np.ndarray, correct: np.ndarray, bins: int = 15) -> float

信頼度のビンごとに計算した期待較正誤差(ECE)です。

引数

confnp.ndarray
correctnp.ndarray
binsint= 15

fit_temperatures

fit_temperatures = fit_temperature_map

fit_one_temperature

fit_one_temperature(pairs: Sequence, min_n: Optional[int] = None) -> float

log 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 のままにはならずスカラーが得られます。

引数

pairsSequence
min_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 は常に完全な入力を数えます。当てはめ自体が部分集合を使った場合も同じです。

引数

recordsIterable
compute_ecebool= False
seedint= 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% の答えを受理します。

引数

recordsIterable
temperatureSequence[float]
temperature_by_optionsDict[str, float]
binning_mapOptional[Dict[str, Dict[str, Any]]]= None
target_errorfloat= 0.10
min_bucket_nint= MIN_ABSTAIN_BUCKET_N
MIN_ABSTAIN_BUCKET_N
conservativebool= 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 に再較正されることはありません。

引数

recordsIterable
temperatureSequence[float]
temperature_by_optionsDict[str, float]
binsint= 15
min_bucket_nint= MIN_BINNING_BUCKET_N
MIN_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)に合わせて再較正します。

マップにそのバケットのエントリがないときは信頼度を変えずに返すので、マップが当てはめていないバケットは、誤った値に押し込まれることなくそのまま通ります。

引数

confidencefloat
bucketstr
binning_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 として書き出されます。

引数

records
min_bucket_nint= MIN_BINNING_BUCKET_N
MIN_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.Tensor
targettorch.Tensor
qtypetorch.Tensor
masktorch.Tensor
w_sphfloat= 0.5
w_rpsfloat= 1.0
log_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.Tensor
batchDict
lamfloat= 1.0

QTYPES

QTYPES = {"choice": 0, "score": 1, "noul": 2}

QTYPE_NAMES

QTYPE_NAMES = {v: k for k, v in QTYPES.items()}