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 文字で止まりますが、これが巨大なフィールドを安く保っています。走査が届かなかった値は、そのあと単独で読み直されます。

detect_script(text: str) -> str

text の主要な文字体系です。'latin'、'han'、'devanagari' など。文字がなければ 'unknown' です。

is_english(state: Union[str, bytes, Mapping, list, None]) -> bool

英語チェックポイントがこの状態を読めると期待できるときに True です。

clean_email_body(body: str, max_chars: int = 3000) -> str

引用されたメールの履歴、署名、免責事項を取り除き、入力を焦点の合ったものにします。

max_chars は結果を切り詰める長さで、変更しない限り 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 のときは無視され、本文はまるごと渡されます。

その他のキーワードは状態のフィールドになり、モデルに読まれます。ここでの打ち間違いはエラーではなく、入力の書き換えです。

triage_questions() -> Dict

カスタマーサポートチケットのトリアージ用のプリセット質問です。

email_questions(categories: Optional[Dict[str, str]] = None) -> Dict

受信メールのトリアージと脅威フィルタリング用のプリセット質問です。

guard_questions() -> Dict

リアルタイムの LLM 入力ガードレール用のプリセット質問です。

moderation_questions() -> Dict

コンテンツの安全性とモデレーション用のプリセット質問です。

router_questions() -> Dict

インテリジェントなモデルルーティング用のプリセット質問です。

shortlist_choice(
    state: Any,
    criteria: Any,
    embed_fn: Callable[[Sequence[str]], Any],
    k: int = DEFAULT_SHORTLIST_K,
    DEFAULT_SHORTLIST_K,
    instructions: Optional[str] = None,
) -> List[Any]

state の上位 k 件の choice ラベルを返します。

embed_fn は文字列のリストを形状 (len(texts), dim) の配列に写します。呼び出しは 1 回だけで、まずクエリ文字列、続いて criteria の順に各選択肢の文字列が渡されます。選択肢の文字列は choice 質問の render_options と一致します。

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

同点のときは先のラベルが残ります。ゼロベクトルは 0 点で、それより前にあるラベルを追い越すことはありません。

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 辞書は変更されません。

返る辞書はモデルの結果に shortlist の項目を足したものです。絞り込んだ choice の確率は、残ったラベルの上だけで正規化されます。shortlist[qid] には labels（順位順）、scores（コサイン値。何も捨てなかったときは None）、k、n、passthrough が入ります。

追加のキーワード引数は predict / system_one に渡されます（たとえば Router の model=）。

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 を使います。

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 の背後にあるモデルや重みが変わったら、キャッシュを消してください。

check_min_confidence(v: Any) -> float

オプトインの棄権しきい値 min_confidence を検証します（#361）。

[0.0, 1.0] の実数でなければなりません。真偽値は拒否されます（isinstance(True, int) は成り立ちますが）。

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 が加わります。

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

報告された答えに載っている確率の質量：max(p)。

温度スケーリングが当てはめるのはこの量で、このリポジトリの較正に関する数値はすべてこの量の上で計算されています —— 2 つのベンチマークハーネスはどちらも ece_score を呼ぶ前に conf = max(probs) を取ります。README のゲートの節が依拠しているのは、それに付随する性質です。信頼度 c で返された答えのうち、およそ c の割合が正しい、という性質です。この性質は条件付きで、既定ではその条件は満たされていません。このチェックポイントとこの選択肢数について温度を当てはめ、ホールドアウトデータで検証してはじめて成り立ちます。配布されているチェックポイントは自信過剰です。choice:11+ は約 10 倍のシャープナーで、1.0 に点質量を返すため、これらにしきい値を適用するとモデルの精度を下回るものが選ばれます（issue #394）。

下の confidence_from_probs は別の量を別の尺度で報告するもので、そのような保証はありません。したがって両者を同じしきい値で比べてはいけません。

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

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

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

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

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

fit_temperatures = fit_temperature_map

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

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

render_options(q: Dict) -> List[str]

選択肢のテキストをラベルの添字順に描画します。Noul の意味上の順序は常に [false, true] です。

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 またはソフトな目標分布）

td_lambda_targets(p_true: torch.Tensor, batch: Dict, lam: float = 1.0) -> torch.Tensor

マルチターン会話の軌跡に対する TD(lambda) ターゲットです。

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

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