Agent
laya.Agent は 1 つのチェックポイントを読み込み、state についての型付きの質問に答えます。laya.load は Agent(...) のショートカットで、laya.RLAgent は Agent の別名です。ONNXAgent はエクスポート済みの ONNX モデルを CPU で実行し、laya.onnx_agent からインポートします。
名前・型・既定値・コードは英語のまま、それ以外は翻訳です(未翻訳の項目は英語原文のまま表示されます)。
Agent
Agent(
model_id_or_path: str = "convaiinnovations/laya",
device: Optional[str] = None,
token: Optional[str] = None,
subfolder: Optional[str] = None,
fast: bool = False,
compile: bool = False,
revision: Optional[str] = None,
expected_sha256: Optional[Dict[str, str]] = None,
lang_temperatures: Optional[Dict[str, Dict[str, Any]]] = None,
hooks=None,
on_predict_start=None,
on_predict_end=None,
hooks_raise: bool = True,
hooks_concurrent: bool = True,
hooks_timeout: Optional[float] = None,
calibration: Optional[str] = None,
backend: Optional[str] = None,
compile_warmup: bool = True,
compile_cache: bool = False,
compile_mode: str = "default",
)基底クラス: HookRegistry
System 1 意思決定モデルのランタイム。高速で、非自己回帰で、較正された意思決定を行います。
dtype は自動キャストの目標であって、すべての呼び出しの精度ではありません。MPS では行数が mps_amp_min_rows 以上のときだけ呼び出しが自動キャストするので、dtype が float16 でも、ある呼び出しは float32 で動きます。dtype_for(rows) は行数 rows の呼び出しの精度を返します。
Laya のチェックポイントを読み込みます。
backend は "eager"、"auto"、"compile"、"tilelang" から選びます。laya.backends を参照してください。fast と compile より優先されます。省略するとそれらの従来のフラグを保ちます。ONNX には代わりに load(backend="onnx") を使ってください。
revision は Hub からのダウンロードを明示的なコミット SHA/ブランチ/タグに固定します(任意)。省略した場合は huggingface_hub の通常の既定値と既存のオフラインキャッシュが使われます。expected_sha256({checkpoint ディレクトリからの相対パス: 16 進ダイジェスト})は、重みが解析または実行される前に成果物の完全性を検証します。オプトインで、ローカルディレクトリにも適用されます。成果物が見つからなければ FileNotFoundError、ダイジェストが一致しなければ ValueError を送出し、どちらの場合も読み込みを拒否します。
fast=True はエンコーダー/ヘッドのフォワードを TileLang の高速パスに差し替えます(CUDA のみ。pip install laya[fast] が必要)。Agent.accelerate を参照してください。
compile=True はモデルを torch.compile の下で動かし、ModernBERT エンコーダーの reference_compile を有効にします。torch.compile は入力形状ごとに特化しますが、Laya はほぼすべてのリクエストで新しい形状に出会うため、それらのグラフはたいてい元が取れません。トラフィックが反復的なときに使ってください。fast=True が優先されます。TileLang のパスは、コンパイルされるはずだったフォワードを置き換えるからです。
コンパイル済みの agent は返る前に warmup() を実行します。compile_warmup=False はその作業をリクエスト時または手動の warmup() 呼び出しへ先送りします。eager と fast の agent は変わりません。compile_cache=True は永続的な Laya Inductor ディレクトリ(プロセス全体)を有効にし、既存の TORCHINDUCTOR_CACHE_DIR を尊重します。コンパイルのエンジニアリングノートを参照してください。compile_mode="reduce-overhead" は CUDA graph を有効にします。より多くの GPU メモリを保持することがあり、新しい形状ごとに別々に記録します。CUDA の出力は次の再生の前にコピーされ、コンパイル済み CUDA graph のフォワードは直列化されます。既定のモードは "default" のままです。
subfolder は、複数を同梱するリポジトリから 1 つのチェックポイントを選びます(例:Agent("convaiinnovations/laya", subfolder="multilingual"))。そのサブフォルダだけがダウンロードされるので、同梱によってすべての利用者が一族全体のコストを払うことはありません。
calibration は temperature と temperature_by_options を含む任意の JSON パスです。チェックポイントの設定のあとに適用されるので、当てはめたマップが model.safetensors を書き換えずに同梱のスカラーを上書きできます。
hooks / on_predict_start / on_predict_end はすべての予測を観察または形成します。laya.hooks を参照してください。hooks_raise=False ではフックが失敗しても警告して続行し、hooks_concurrent=False は並列実行が安全でないフックを直列化し、hooks_timeout はフック呼び出し 1 回あたりを秒で制限します(None は無制限)。
引数
model_id_or_pathstr="convaiinnovations/laya"deviceOptional[str]=NonetokenOptional[str]=NonesubfolderOptional[str]=Nonefastbool=Falsecompilebool=FalserevisionOptional[str]=Noneexpected_sha256Optional[Dict[str, str]]=Nonelang_temperaturesOptional[Dict[str, Dict[str, Any]]]=Nonehooks=Noneon_predict_start=Noneon_predict_end=Nonehooks_raisebool=Truehooks_concurrentbool=Truehooks_timeoutOptional[float]=NonecalibrationOptional[str]=NonebackendOptional[str]=Nonecompile_warmupbool=Truecompile_cachebool=Falsecompile_modestr="default"
backend
backend: str現在有効な推論バックエンド。従来の compile と fast フラグを含みます。
backend_object
backend_objectインストールされた Backend オブジェクト。従来のランタイムでは None です。
set_backend
set_backend(name: str = "auto", strict: bool = False, options) -> strバックエンドを切り替えます。利用できないバックエンドは警告を出して eager を使いますが、strict=True の場合はそうしません。
オプションはバックエンドのコンストラクタに渡します。たとえば compile なら warmup=False、tilelang なら use_graphs=False です。切り替えは進行中の推論を待ちます。
引数
namestr="auto"strictbool=Falseoptions
accelerate
accelerate(use_graphs: bool = True, strict: bool = False)モデルのフォワードを TileLang の高速パスに差し替えます(融合された GEMM/GEGLU/LayerNorm/RoPE カーネル、スライディングウィンドウの flash attention、16 ビットの常駐重み、形状バケットごとの CUDA グラフ)。
高速パスは、呼び出し時点でのエージェントの自動キャスト dtype(bf16 または fp16)で動くので、置き換える元のフォワードと丸め誤差の範囲で一致します(benchmarks/parity_fast.py を参照)。agent.dtype を変更したあとは、deaccelerate() を呼んでから accelerate() を呼び、再構築してください。有効化できれば True を返します。strict=False のときは、どのような失敗(CUDA がない、tilelang がない)でも元のパスがそのまま残ります。
引数
use_graphsbool=Truestrictbool=False
warmup
warmup(shapes=None) -> float各形状の合成入力で今すぐフォワードを実行し、かかった秒数を返します。
compile=True は compile_warmup=False でない限り読み込み時にこれを呼びます。追加の形状は手動で温めることもできます。fast=True は初回使用時に形状バケットごとのカーネルと CUDA グラフを構築します。サービング前にこれを呼んでおくと、そのコストを最初のいくつかのリクエストから外へ移せます。元のフォワードでは、これは普通のフォワードパス数回分です。shapes は (rows, tokens, markers) のリストです。tokens はエージェントの max_len で上限が掛かります。呼び出し側に何かが返されたり記録されたりすることはなく、フックも走りません。
引数
shapes=None
deaccelerate
deaccelerate()元のフォワードに戻します。
dtype_for
dtype_for(rows: int) -> torch.dtyperows 個の質問行を持つフォワードパスが動く精度です。
dtype は読み込み時に 1 度だけ設定される自動キャストの目標です。フォワードが自動キャストするかどうかは呼び出しごとに決まります。MPS では行数が mps_amp_min_rows 以上のときだけです。行数 rows のフォワードが自動キャストするときは dtype を返し、そうでなければ torch.float32 を返します。predict 呼び出しは質問ごとに 1 行を実行します。
引数
rowsint
predict_batch
predict_batch(
states: List[Union[str, dict, list]],
questions: Dict[str, Dict[str, Any]],
batch_size: Optional[int] = None,
lang: Optional[str] = None,
hooks=None,
on_predict_start=None,
on_predict_end=None,
hooks_raise: Optional[bool] = None,
hooks_timeout: Optional[float] = None,
max_len: Optional[int] = None,
head_max_len: Optional[int] = None,
sort_by_length: bool = False,
min_confidence: Optional[float] = None,
) -> List[Dict[str, Any]]同じ質問を多数の状態に対して評価し、それらを共有のフォワードパスにまとめます。
これがスループットの経路です。system_one/predict は 1 回のフォワードパスで 1 つの状態を扱うので、GPU ではバッチ次元のほとんどが遊びます。predict_batch は複数の状態の質問行を 1 つのテンソルにまとめるため、N 回の逐次フォワードパスが要った呼び出しが 1 回(または ceil(len(states) / batch_size) 回)で済み、GPU では決定あたり数倍速くなります。
引数
statesList[Union[str, dict, list]]状態のリスト(各要素はテキスト文字列、JSON 辞書、または会話ターンのリスト)。同じ
questionsがすべての状態に対して評価されます。questionsDict[str, Dict[str, Any]]質問定義。
system_oneが受け付けるものとまったく同じです。batch_sizeOptional[int]=Noneフォワードパスあたりの状態数の任意の上限。
Noneはすべてを 1 回で送ります。多数または長い状態をまとめるときは、これを設定してピークメモリを抑えてください。langOptional[str]=NonehooksHookArg=None呼び出しごとのフック。Agent にインストール済みのフックの後ろに追加されます。
laya.hooksを参照してください。on_predict_startPredictHookArg=None呼び出しごとの開始フック。状態/質問を書き換えたり、
ctx.skip(...)を呼んで推論を短絡したりできます。on_predict_endPredictHookArg=None呼び出しごとの終了フック。結果を書き換えられます。
hooks_raiseOptional[bool]=Noneこの呼び出しにおける Agent の
hooks_raiseを上書きします。hooks_timeoutOptional[float]=Noneこの呼び出しにおける Agent の
hooks_timeoutを上書きします。max_lenOptional[int]=Noneこの呼び出しにおけるエージェント設定の
max_lenを上書きします。開始フックがctx.max_lenを設定してトークン予算を形作ることもできます。head_max_lenOptional[int]=Noneこの呼び出しにおけるエージェント設定の
head_max_lenを上書きします。開始フックがctx.head_max_lenを設定することもできます。sort_by_lengthbool=Falseエンコード後の長さが近い状態を 8 バッチ分の窓にまとめ、padding を減らします。1 より大きく、状態数より小さい
batch_sizeを明示する必要があります。そうでなければ効果はありません。結果は入力順を保ちます。これはトークン化済みの状態を 1 バッチ分ではなく最大 8 バッチ分バッファします。バッチの形状が変わると、浮動小数点の予測がわずかに変わることがあります。min_confidenceOptional[float]=None
戻り値
状態ごとの結果辞書のリスト。それぞれの形は system_one の出力と同一で、states と添字で対応します。
predict_long
predict_long(
state: Union[str, dict, list],
questions: Dict[str, Dict[str, Any]],
window: Optional[int] = None,
stride: Optional[int] = None,
aggregate: str = "auto",
batch_size: Optional[int] = None,
lang: Optional[str] = None,
hooks=None,
on_predict_start=None,
on_predict_end=None,
hooks_raise: Optional[bool] = None,
hooks_timeout: Optional[float] = None,
) -> Dict[str, Any]文脈長を超える状態に対して質問を評価します。重なり合うウィンドウで走査し、質問ごとに集約します。
system_one/predict は max_len を超える状態を 1 つのウィンドウ(最初、会話リストでは最後)に切り詰め、残りを黙って捨てます。predict_long は状態を 1 回だけトークン化し、重なり合うトークンウィンドウに分け、共有のフォワードパス(predict_batch 経由)で各ウィンドウを採点し、ウィンドウごとの答えを統合します。
- noul -> P(true) は各ウィンドウの最大値です(どのウィンドウかが支えればその言明は成り立ちます)
- choice-> 最も自信のある単一のウィンドウの答えです。局所的な信号が、長い文書の大半を占める多くの中性的なウィンドウに投票で負けないようにするためです (平均すると埋もれます —— 中性的な多数が支配します)
- score -> 同じく最も自信のあるウィンドウのレベルです
返される確率/信頼度は決定したウィンドウのもので、文書全体に対して較正された数値ではありません。信号がなくても noul の多ウィンドウ最大値はウィンドウ数とともに上がりますし、文書に決定的な内容が何もなければ choice が自信を持って中性的なウィンドウに着地することがあります。そこで各答えは answer["window"] を持ちます —— 決定したウィンドウの index、トークン化後の状態における token_start/token_end、そしてウィンドウの count です —— 呼び出し側は生の数値を信じるのではなく、答えがどの範囲から来たのかを調べられます。その範囲は、要求されただけの範囲ではなく、モデルが実際に読んだ範囲です。ウィンドウは質問が残す余地で上限が掛かるので、predict_batch に渡されるものは再び切り詰められません。
質問が余地を残す状態は system_one にそのまま渡されます(出力は同一)—— system_one はそれを丸ごと読むからです。明示的な window がある場合は、そのウィンドウに収まる状態が渡されます。
フックが包むのは、その状態に答える推論です。複数のウィンドウを要する文書では、それがウィンドウ全体にわたる 1 回の共有 predict_batch になります。on_predict_start は 1 回だけ発火し、ctx.states には走査順にデコード済みのウィンドウテキストが入ります —— 呼び出し側の state ではありません。あれはこれらを作るためにトークン化されたものです。この連鎖が何を残すかによって 3 つの結果があります。
ctx.skip([result])が文書に答えます:ペイロードはウィンドウの帰属情報なしで返り、usage["windows"]は 0 です。何も採点されていないからです- このメソッドが組んだままの走査:すべてのウィンドウが採点され、各答えが
answer["window"]を持ち、usage["windows"]はウィンドウ数です - 書き換えられた走査(
ctx.statesが何らかの形で差し替えられた):答えは採点された状態の上で集約されますが、どの答えもanswer["window"]を持ちません —— 上記のオフセットはこのメソッドのウィンドウを記述したもので、モデルが読んだテキストではありません
引数
stateUnion[str, dict, list]questionsDict[str, Dict[str, Any]]windowOptional[int]=Noneウィンドウあたりの状態トークン数。既定はチェックポイントの状態予算
max(64, max_len - head_max_len - 8)です —— 64 は下限なので、head_max_lenを広げても予算がそこに達すると既定が縮まなくなります —— どちらの場合も、質問がmax_len内で状態に残す余地(そのうち最小の余地)が上限になります。1 つのウィンドウのリストがすべての質問に対して採点されるからです。広いウィンドウはモデルへ向かう途中で再び切り詰められるため、代わりにクランプされ、呼び出し側がそれを要求した場合にはRuntimeWarningが出ます。余地を小さくするのは選択肢です。英語のチェックポイントでは、2 択の質問は状態に 483 トークンを残し、100 択の質問は 100 を残します。ウィンドウを小さくすると局所的な信号をよく分離できます(短い決定的範囲はウィンドウに占める割合が大きくなるので、そのウィンドウは明瞭に分類できます)が、ウィンドウ数が増えます。既定の大きいウィンドウは文脈とスループットを優先します。noulはこれに強く、決定的な範囲が長くほぼ中性的な文書のごく一部である場合、choice/scoreは小さいウィンドウのほうが有利です。strideOptional[int]=Noneウィンドウ間のトークン刻み。既定は実効ウィンドウの半分(50% の重なり)なので、境界の近くにある範囲もどこかのウィンドウに丸ごと収まります。実効ウィンドウを超えるストライドは、クランプではなく拒否されます。各ウィンドウの対の間のトークンがどのウィンドウからも読まれなくなるからであり、それがこのメソッドが防ぐために存在する失敗です。
aggregatestr="auto""auto"(上記の型ごとの規則)が現時点で唯一のモードです。
batch_sizeOptional[int]=Noneフォワードパスあたりのウィンドウ数の上限。非常に長い状態でメモリを抑えるためです。
langOptional[str]=None言語ごとの温度選択。
system_oneと同じです。hooksHookArg=None呼び出しごとのフック。Agent にインストール済みのフックの後ろに追加されます。
laya.hooksを参照してください。on_predict_startPredictHookArg=None呼び出しごとの開始フック。
system_oneと同じです。on_predict_endPredictHookArg=None呼び出しごとの終了フック。
system_oneと同じです。hooks_raiseOptional[bool]=Noneこの呼び出しにおける Agent の
hooks_raiseを上書きします。hooks_timeoutOptional[float]=Noneこの呼び出しにおける Agent の
hooks_timeoutを上書きします。
例外
ValueError:aggregate が "auto" 以外である場合、質問の選択肢が系列全体を埋めて状態の余地を残さない場合、または stride が実効ウィンドウを超える場合です。後者では 2 つのウィンドウの間のトークンが何からも読まれません。
単一の結果辞書を返します。形は system_one と同じで、usage["windows"] が加わります。このキーは常に存在し、モデルが答えを出すために採点したウィンドウ数を数えます。1 つのウィンドウに収まる状態では 1、N 個の重なり合うウィンドウで走査した文書では N(開始フックが書き換えた場合はその N)、開始フックが文書に答えたり、どのウィンドウも読まれる前に採点する状態を残さなかった場合は 0 です —— どちらの経路でも同じなので、キャッシュされた答えがモデルの読んだウィンドウとして読まれることはありません。
複数のウィンドウにまたがる場合、切り詰めに関するキーは他の usage フィールドと同じように統合されます。truncated、state_tokens、state_tokens_dropped は合計され(したがって truncated は切り詰められたウィンドウ数で、トークン数には重なりが含まれます)、truncated_questions は最後のウィンドウのリストです。両者は食い違うことがあります。先のウィンドウだけが切り詰められた場合、truncated は 0 より大きく、truncated_questions は空です。ウィンドウが、ある質問のヘッドが残す余地より大きいときに切り詰められます。ここでは is True ではなく usage["truncated"] > 0 を判定してください。
system_one
system_one(
state: Union[str, dict, list],
questions: Dict[str, Dict[str, Any]],
lang: Optional[str] = None,
hooks=None,
on_predict_start=None,
on_predict_end=None,
hooks_raise: Optional[bool] = None,
hooks_timeout: Optional[float] = None,
max_len: Optional[int] = None,
head_max_len: Optional[int] = None,
min_confidence: Optional[float] = None,
) -> Dict[str, Any]1 回の並列フォワードパスで、状態に対して型付きの質問を評価します。
引数
stateUnion[str, dict, list]テキスト文字列、JSON 辞書、または会話ターンのリスト。
questionsDict[str, Dict[str, Any]]question_id を質問定義に写す辞書。
- choice: {"type": "choice", "instructions": "...", "criteria": {"optA": "...", ...}}
- score: {"type": "score", "instructions": "...", "criteria": ["lvl0", "lvl1", ...]}
- noul: {"type": "noul", "instructions": "...", "criteria": {"false": "...", "true": "..."}, "labels": {"false": "B", "true": "A"}}
Noul の criteria と labels は任意です。labels はモデルに見せるテキストだけを制御し、そのキーは false/true の意味を保ち、返される
noulの値は常に P(true) です。互換性のため、labels の既定値は false/true です。langOptional[str]=Nonehooks=Noneon_predict_start=Noneon_predict_end=Nonehooks_raiseOptional[bool]=Nonehooks_timeoutOptional[float]=Nonemax_lenOptional[int]=Nonehead_max_lenOptional[int]=Nonemin_confidenceOptional[float]=None
戻り値
答え、確率、較正された信頼度、トークン使用量を含む辞書。質問が空のときは、トークン化もモデルのフォワードパスも行わず、空の答えとゼロのトークン使用量を返します。
ヘッドの予算によっていくつかの選択肢が同じトークン範囲に収まるとき、usage はそうなった各質問について options エントリを運びます —— total、distinct、tokens_per_option です。58 の区別できる範囲のうち 42 個から選ぶ答えの天井は、モデルではなく予算によるものだからです。選択肢がすべて残った質問は含まれないので、何も潰れなかったリクエストは変わりません。
usage は状態が収まったかどうかも報告します。truncated、state_tokens、state_tokens_dropped、そして truncated_questions(ヘッドが残した余地が小さすぎた質問)です。答えが状態全体を見たかどうかを気にする呼び出し側は、送った内容の長さから推測するのではなく usage["truncated"] を読むべきです。
多数の状態をまとめて採点するには predict_batch を参照してください。状態をまたいでフォワードパスを共有します。
decide
decide(
state: Union[str, dict, list],
schema: Any = None,
questions: Optional[Dict[str, Any]] = None,
return_details: bool = False,
min_confidence: Optional[float] = None,
predict_kwargs,
) -> Anystate をスキーマ(JSON schema または pydantic モデル)に照らして答え、型付きの値を返します。
laya.structured を参照してください。schema か questions のどちらか一方だけを渡します。追加のキーワード引数は predict / system_one に転送されます。
引数
stateUnion[str, dict, list]schemaAny=NonequestionsOptional[Dict[str, Any]]=Nonereturn_detailsbool=Falsemin_confidenceOptional[float]=Nonepredict_kwargs
decide_batch
decide_batch(
states: List[Union[str, dict, list]],
schema: Any = None,
questions: Optional[Dict[str, Any]] = None,
return_details: bool = False,
min_confidence: Optional[float] = None,
predict_kwargs,
) -> List[Any]複数の状態を 1 つのスキーマ(JSON schema または pydantic モデル)に照らして、1 回のバッチ呼び出しで答えます。
:meth:decide のスループット版です。スキーマは 1 回だけ計画され、その質問が :meth:predict_batch を通じてすべての状態に対して実行され(共有のフォワードパス、結果は入力順)、そのうえで各状態の答えが decide と同じように射影されます。追加のキーワード引数(batch_size=、lang=、hooks= など)は predict_batch に転送されます。laya.structured を参照してください。
引数
statesList[Union[str, dict, list]]schemaAny=NonequestionsOptional[Dict[str, Any]]=Nonereturn_detailsbool=Falsemin_confidenceOptional[float]=Nonepredict_kwargs
fit_temperatures
fit_temperatures(records, compute_ece: bool = False, seed: int = 0) -> Dict[str, Any]CPU 上の記録からバケットごとの温度を当てはめ、このエージェントに保存します。
records は (qtype, logits, target, k) です。ラベル付きのフォワードがある場合は laya.calibrate.records_from_labeled で組み立ててください。このメソッドは重みをダウンロードせず、model.safetensors も書きません。seed は compute_ece が真のときのホールドアウト ECE 分割にだけ影響します。チェックポイントの cfg は読み込んだままにされます。
引数
recordscompute_ecebool=Falseseedint=0
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
save_calibration
save_calibration(path: str) -> Nonetemperature、temperature_by_options、エージェントが持っていれば binning_map、そしてそれらがどのチェックポイント向けに当てはめられたかを書き出します。重みは書きません。
引数
pathstr
load_calibration
load_calibration(path: str) -> Nonesave_calibration が書き出した JSON マップを、このエージェントに読み込みます。
ファイルは 3 つのフィールドを持ち、3 つすべてがインストールされます:temperature、temperature_by_options、binning_map です。binning_map キーのないファイルは None をインストールするので、それを読み込むとこのエージェントの fit_binning が当てはめたマップが消えます —— ファイルは較正状態の全体であり、現在のものへのパッチではありません。
version のないファイルはバージョン 1 とみなされ、そのまま読み込まれます。記録されたチェックポイントがこのエージェントと一致しない、より新しいファイルは警告を出しつつ読み込まれます。数値でない温度、または [TEMP_MIN, TEMP_MAX] の外にある温度は、チェックポイントの読み込みと同じように clamp_temperature で丸められます。binning の値は丸められず、フィールドを名指しする ValueError で拒否されます。範囲外の binning 値は、フォールバックするものがないまま信頼度を動かしてしまうからです。
引数
pathstr
load
load(
model_id_or_path: str = "convaiinnovations/laya",
device: Optional[str] = None,
token: Optional[str] = None,
subfolder: Optional[str] = None,
fast: bool = False,
compile: bool = False,
revision: Optional[str] = None,
expected_sha256: Optional[Dict[str, str]] = None,
lang_temperatures: Optional[Dict[str, Dict[str, Any]]] = None,
hooks=None,
on_predict_start=None,
on_predict_end=None,
hooks_raise: bool = True,
hooks_concurrent: bool = True,
hooks_timeout: Optional[float] = None,
calibration: Optional[str] = None,
backend: Optional[str] = None,
onnx_path: Optional[str] = None,
compile_warmup: bool = True,
compile_cache: bool = False,
compile_mode: str = "default",
) -> AgentLaya のエージェントを読み込みます。
subfolder は、複数を同梱するリポジトリから 1 つのチェックポイントを選びます。
laya.load("convaiinnovations/laya") # English (repo root)
laya.load("convaiinnovations/laya", subfolder="multilingual")
laya.load("convaiinnovations/laya", fast=True) # TileLang GPU fast path
laya.load("convaiinnovations/laya", compile=True) # torch.compile the model
model_id_or_path はチェックポイント名や別名も受け付けます —— Router が解決するのと同じもので、両方の入口が 1 つの表を読みます:
laya.load("typed-decisions")
laya.load("ml") # multilingual
それ以外(Hub のリポジトリ id、ローカルディレクトリ)はそのまま Agent に渡されます。
backend は "auto"、"eager"、"compile"、"tilelang"、"onnx" から選びます。ONNX は既存の ONNXAgent を返し、onnx_path(既定 "laya.onnx")を伴います。他のバックエンドは Agent を使います。明示的な backend は従来のフラグより優先されます。
revision/expected_sha256 はダウンロードした成果物を固定して検証します。Agent を参照してください。hooks / on_predict_start / on_predict_end はすべての予測を観察または形成します。laya.hooks を参照してください。calibration は Agent が受け付けるのと同じ任意の JSON パスです。
引数
model_id_or_pathstr="convaiinnovations/laya"deviceOptional[str]=NonetokenOptional[str]=NonesubfolderOptional[str]=Nonefastbool=Falsecompilebool=FalserevisionOptional[str]=Noneexpected_sha256Optional[Dict[str, str]]=Nonelang_temperaturesOptional[Dict[str, Dict[str, Any]]]=Nonehooks=Noneon_predict_start=Noneon_predict_end=Nonehooks_raisebool=Truehooks_concurrentbool=Truehooks_timeoutOptional[float]=NonecalibrationOptional[str]=NonebackendOptional[str]=Noneonnx_pathOptional[str]=Nonecompile_warmupbool=Truecompile_cachebool=Falsecompile_modestr="default"
ONNXAgent
ONNXAgent(
model_id_or_path: str,
onnx_path: str = "laya.onnx",
token: Optional[str] = None,
subfolder: Optional[str] = None,
revision: Optional[str] = None,
expected_sha256: Optional[Dict[str, str]] = None,
hooks=None,
on_predict_start=None,
on_predict_end=None,
hooks_raise: bool = True,
hooks_concurrent: bool = True,
hooks_timeout: Optional[float] = None,
lang_temperatures: Optional[Dict[str, Dict[str, Any]]] = None,
calibration: Optional[str] = None,
)基底クラス: HookRegistry
ONNX 経由の System 1 意思決定モデルのランタイム。CPU 向けに最適化された高速な意思決定を行います。
ONNX Runtime をバックエンドとする Laya エージェントを読み込みます。
引数
model_id_or_pathstrHuggingFace Hub の ID、または元の PyTorch チェックポイントへのローカルパス(トークナイザーと設定の読み込みに使います)。
onnx_pathstr="laya.onnx"エクスポートした .onnx ファイルへのパス。
tokenOptional[str]=Noneプライベートまたはゲート付きチェックポイント用の任意の HuggingFace トークン。省略時は
Agentとまったく同じく$HF_TOKENにフォールバックします。取得するのはトークナイザーと設定だけです —— グラフ自体はローカルのonnx_pathです。subfolderOptional[str]=None同梱リポジトリからダウンロードする場合の任意のサブフォルダ。
revisionOptional[str]=None任意の Hub リビジョン(コミット SHA/ブランチ/タグ)。省略した場合は huggingface_hub の通常の既定値と既存のオフラインキャッシュが使われます。
expected_sha256Optional[Dict[str, str]]=None任意の {checkpoint ディレクトリからの相対パス: 16 進ダイジェスト}。チェックポイントのファイルが解析される前に検証します。オプトインで、ローカルディレクトリにも適用されます。成果物が見つからなければ
FileNotFoundError、ダイジェストが一致しなければValueErrorを送出し、どちらの場合も読み込みを拒否します。hooksHookArg=Noneオプトインの予測フック。
laya.hooksを参照してください。on_predict_startPredictHookArg=Noneオプトインの開始フック。推論の前に実行されます。
on_predict_endPredictHookArg=Noneオプトインの終了フック。推論のあとに実行されます。
hooks_raisebool=TrueFalse のとき、フックが失敗しても警告して推論は続行します。
hooks_concurrentbool=TrueFalse のとき、フックはロックで直列化されます。
hooks_timeoutOptional[float]=Noneフック呼び出し 1 回あたりを秒で制限します。None は無制限です。
lang_temperaturesOptional[Dict[str, Dict[str, Any]]]=None言語コードをキーにした、任意の言語ごとの温度上書き。各項目は
{"temperature": [3 floats], "temperature_by_options": {}}です。system_one/predictにlang=が渡されたときに適用され、PyTorch のAgentに対応します。そうでなければバックエンドをまたぐ差し替えで較正が失われます。calibrationOptional[str]=None
load_calibration
load_calibration(path: str) -> Nonesave_calibration が書き出した JSON マップを、このエージェントに読み込みます。
引数
pathstr
system_one
system_one(
state: Union[str, dict, list],
questions: Dict[str, Dict[str, Any]],
lang: Optional[str] = None,
hooks=None,
on_predict_start=None,
on_predict_end=None,
hooks_raise: Optional[bool] = None,
hooks_timeout: Optional[float] = None,
max_len: Optional[int] = None,
head_max_len: Optional[int] = None,
min_confidence: Optional[float] = None,
) -> Dict[str, Any]1 回の ONNX Runtime セッション実行で、状態に対して型付きの質問を評価します。
lang は言語ごとの温度上書きを選びます(lang_temperatures を参照)。PyTorch の Agent.system_one とシグネチャが一致するので、どちらのバックエンドも他方の drop-in になります。
PyTorch の Agent.system_one とまったく同じく predict_batch を基礎として定義されているので、単一状態の経路とバッチの経路がずれることはありません。
引数
stateUnion[str, dict, list]テキスト文字列、JSON 辞書、または会話ターンのリスト。
questionsDict[str, Dict[str, Any]]質問定義。
Agent.system_oneが受け付けるのと同じ形です。langOptional[str]=None言語ごとの温度上書き(
lang_temperaturesを参照)。hooksHookArg=None呼び出しごとのフック。エージェントにインストール済みのフックの後ろに追加されます。
on_predict_startPredictHookArg=None呼び出しごとの開始フック。状態/質問を書き換えたり、
ctx.skip(...)を呼んで推論を短絡したりできます。on_predict_endPredictHookArg=None呼び出しごとの終了フック。結果を書き換えられます。
hooks_raiseOptional[bool]=Noneこの呼び出しにおけるエージェントの
hooks_raiseを上書きします。hooks_timeoutOptional[float]=Noneこの呼び出しにおけるエージェントの
hooks_timeoutを上書きします。max_lenOptional[int]=Noneこの呼び出しにおける設定の
max_lenを上書きします。head_max_lenOptional[int]=Noneこの呼び出しにおける設定の
head_max_lenを上書きします。min_confidenceOptional[float]=Noneanswer_confidenceに対するオプトインの棄権しきい値(#361)。これを下回る答えはlow_confidence: Trueの印を付けて返されます。
戻り値
答え、確率、較正された信頼度、トークン使用量を含む辞書。
多数の状態をまとめて採点するには predict_batch を参照してください。状態をまたいでセッション実行を共有します。
predict_batch
predict_batch(
states: List[Union[str, dict, list]],
questions: Dict[str, Dict[str, Any]],
batch_size: Optional[int] = None,
lang: Optional[str] = None,
hooks=None,
on_predict_start=None,
on_predict_end=None,
hooks_raise: Optional[bool] = None,
hooks_timeout: Optional[float] = None,
max_len: Optional[int] = None,
head_max_len: Optional[int] = None,
sort_by_length: bool = False,
min_confidence: Optional[float] = None,
) -> List[Dict[str, Any]]同じ質問を多数の状態に対して評価し、ONNX Runtime のセッション実行を共有します。
laya.agent.Agent.predict_batch に対応するスループットの経路です。system_one はセッション実行 1 回につき 1 つの状態の質問行しかまとめないので、N 個の状態には N 回の実行がかかります。predict_batch は複数の状態の行を 1 回の実行に —— あるいは ceil(len(states) / batch_size) 回に —— まとめます。ONNX Runtime 自身の並列性が CPU で効いてくるのはここです。
引数
statesList[Union[str, dict, list]]状態のリスト(各要素はテキスト文字列、JSON 辞書、または会話ターンのリスト)。同じ
questionsがすべての状態に対して評価されます。questionsDict[str, Dict[str, Any]]質問定義。
system_oneが受け付けるものとまったく同じです。batch_sizeOptional[int]=Noneセッション実行あたりの状態数の任意の上限。
Noneはすべてを 1 回で送ります。多数または長い状態をまとめるときは、これを設定してピークメモリを抑えてください。langOptional[str]=Noneすべての状態に適用される言語ごとの温度上書き。
lang_temperaturesを参照してください。hooksHookArg=None呼び出しごとのフック。エージェントにインストール済みのフックの後ろに追加されます。
on_predict_startPredictHookArg=None呼び出しごとの開始フック。状態/質問を書き換えたり、
ctx.skip(...)を呼んで推論を短絡したりできます。on_predict_endPredictHookArg=None呼び出しごとの終了フック。結果を書き換えられます。
hooks_raiseOptional[bool]=Noneこの呼び出しにおけるエージェントの
hooks_raiseを上書きします。hooks_timeoutOptional[float]=Noneこの呼び出しにおけるエージェントの
hooks_timeoutを上書きします。max_lenOptional[int]=Noneこの呼び出しにおける設定の
max_lenを上書きします。head_max_lenOptional[int]=Noneこの呼び出しにおける設定の
head_max_lenを上書きします。sort_by_lengthbool=Falseエンコード後の長さが近い状態を 8 バッチ分の窓にまとめ、padding を減らします。
Agent.predict_batchとまったく同じです。1 より大きく、状態数より小さいbatch_sizeを明示する必要があります。そうでなければ効果はありません。結果は入力順を保ちます。バッチの形状が変わると、決定しきい値の近くで浮動小数点の予測がわずかに変わることがあります。min_confidenceOptional[float]=Noneanswer_confidenceに対するオプトインの棄権しきい値(#361)。これを下回る答えはlow_confidence: Trueの印を付けて返されます。
戻り値
状態ごとの結果辞書のリスト。それぞれの形は system_one の出力と同一で、states と添字で対応します。
predict_long
predict_long(
state: Union[str, dict, list],
questions: Dict[str, Dict[str, Any]],
window: Optional[int] = None,
stride: Optional[int] = None,
aggregate: str = "auto",
batch_size: Optional[int] = None,
lang: Optional[str] = None,
hooks=None,
on_predict_start=None,
on_predict_end=None,
hooks_raise: Optional[bool] = None,
hooks_timeout: Optional[float] = None,
) -> Dict[str, Any]文脈長を超える状態に対して質問を評価します。重なり合うウィンドウで走査し、質問ごとに集約します。
laya.agent.Agent.predict_long の ONNX 版で、集約の規則も同じです。system_one は max_len を超える状態を 1 つのウィンドウに切り詰め、残りを黙って捨てます。predict_long は状態を 1 回だけトークン化し、重なり合うトークンウィンドウに分け、predict_batch を通じて各ウィンドウを採点し(これにより、ウィンドウは 1 つずつコストを払うのではなく ONNX Runtime のセッション実行を共有します)、ウィンドウごとの答えを統合します。
- noul -> P(true) は各ウィンドウの最大値です(どのウィンドウかが支えればその言明は成り立ちます)
- choice-> 最も自信のある単一のウィンドウの答えです。局所的な信号が、長い文書の大半を占める多くの中性的なウィンドウに投票で負けないようにするためです
- score -> 同じく最も自信のあるウィンドウのレベルです
返される確率/信頼度は決定したウィンドウのもので、文書全体に対して較正された数値ではありません。理由は PyTorch 側の説明と同じです。各答えは answer["window"] を持ちます —— 決定したウィンドウの index、トークン化後の状態における token_start/token_end、そしてウィンドウの count です。
質問が余地を残す状態は system_one にそのまま渡されます(出力は同一)—— system_one はそれを丸ごと読むからです。明示的な window がある場合は、そのウィンドウに収まる状態が渡されます。
引数
stateUnion[str, dict, list]テキスト文字列、JSON 辞書、または会話ターンのリスト。
questionsDict[str, Dict[str, Any]]質問定義。
system_oneが受け付けるものとまったく同じです。windowOptional[int]=Noneウィンドウあたりの状態トークン数。既定は質問ごとの状態予算(
max(64, max_len - head_max_len - 8)、64 は下限)です。Agent.predict_longと同じく、ウィンドウを小さくすると局所的な信号をよく分離できますが、ウィンドウ数が増えます。strideOptional[int]=Noneウィンドウ間のトークン刻み。既定は
window // 2(50% の重なり)です。aggregatestr="auto""auto"(上記の型ごとの規則)が現時点で唯一のモードです。
batch_sizeOptional[int]=Noneセッション実行あたりのウィンドウ数の上限。非常に長い状態でメモリを抑えるためです。
langOptional[str]=None言語ごとの温度選択。
system_oneと同じです。hooksHookArg=None呼び出しごとのフック。エージェントにインストール済みのフックの後ろに追加されます。
Agent.predict_longの契約に従います。状態に答える推論を包み、ctx.skip(...)で答える開始フックはusage["windows"] == 0とウィンドウ帰属情報なしを受け取り、書き換えられた走査はanswer["window"]なしで集約されます。on_predict_startPredictHookArg=None呼び出しごとの開始フック。
system_oneと同じです。on_predict_endPredictHookArg=None呼び出しごとの終了フック。
system_oneと同じです。hooks_raiseOptional[bool]=Noneこの呼び出しにおけるエージェントの
hooks_raiseを上書きします。hooks_timeoutOptional[float]=Noneこの呼び出しにおけるエージェントの
hooks_timeoutを上書きします。
単一の結果辞書を返します。形は system_one と同じで、usage["windows"] が加わります。複数のウィンドウにまたがる場合、切り詰めに関するキーは Agent.predict_long と同じように統合されます。truncated はウィンドウ数で、truncated_questions は最後のウィンドウのリストなので、truncated が 0 より大きいのにリストが空、ということが起こりえます。
decide
decide(
state: Union[str, dict, list],
schema: Any = None,
questions: Optional[Dict[str, Dict[str, Any]]] = None,
return_details: bool = False,
min_confidence: Optional[float] = None,
predict_kwargs,
) -> Anystate をスキーマ(JSON schema または pydantic モデル)に照らして答え、型付きの値を返します。
laya.structured を参照してください。schema か questions のどちらか一方だけを渡します。追加のキーワード引数は predict / system_one に転送されます。
引数
stateUnion[str, dict, list]schemaAny=NonequestionsOptional[Dict[str, Dict[str, Any]]]=Nonereturn_detailsbool=Falsemin_confidenceOptional[float]=Nonepredict_kwargs
decide_batch
decide_batch(
states: List[Union[str, dict, list]],
schema: Any = None,
questions: Optional[Dict[str, Dict[str, Any]]] = None,
return_details: bool = False,
min_confidence: Optional[float] = None,
predict_kwargs,
) -> List[Any]predict_batch を通じて、複数の状態を 1 つのスキーマに照らして答えます。laya.structured を参照してください。
引数
statesList[Union[str, dict, list]]schemaAny=NonequestionsOptional[Dict[str, Dict[str, Any]]]=Nonereturn_detailsbool=Falsemin_confidenceOptional[float]=Nonepredict_kwargs
量子化エクスポート
scripts/export_onnx.py --quantize は、fp32 エクスポートの隣に INT8 の重みのみ量子化したコピーを書き出します(laya.onnx は laya.int8.onnx も生成します)。動的量子化は MatMul の重みを int8 に変換し、活性値のスケールは実行時に入力ごとに計算するので、キャリブレーション用データセットは不要です。ONNXAgent は onnx_path をそこに向けるだけで結果を読み込みます。CPU では eager モデルより約 2 倍速く、fp32 ONNX グラフより約 1.8 倍速く、チェックポイントによって 1.4〜2.8 倍小さくなります。
INT8 は実際の精度を犠牲にするので、サイズとレイテンシのための選択肢であり、無料ではありません。キャリブレーションされた確率や信頼度が重要な場面では使わないでください。スケールは既定でテンソル単位です。--per-channel でチャネル単位の重みを選べますが、動的パスの場合、これで意思決定モデルが崩壊します(eager モデルとの一致率は英語チェックポイントで約 32%、多言語チェックポイントで約 40% まで下がり、テンソル単位ではそれぞれ約 67% / 83% でした。issue #790 を参照)。テンソル単位でも、より大きなチェックポイントではドリフトが目立ちます。精度を保つ int8 には QAT か SmoothQuant 方式の外れ値処理が必要です。int8 のグラフは CPU 専用です。ONNX Runtime には CUDAExecutionProvider 上の INT8 MatMul カーネルがなく、GPU プロバイダはノード単位で黙ってフォールバックします。
python scripts/export_onnx.py --model convaiinnovations/laya --output laya.onnx --quantize
プロセス内での動的量子化
上の量子化エクスポートは、ONNXAgent が読み込む int8 の経路です。生きた Agent に対する
torch.ao.quantization.quantize_dynamic は別の操作です。
Issue #1065 は、SSE4.2 はあるが AVX2 の
ない CPU で、既定の fbgemm エンジンが SIGILL(不正命令)でクラッシュすると報告しています
(laya 0.3.22、torch 2.14)。まず CPU を確認してください。AVX2 が使えないとき
torch.backends.cpu.get_cpu_capability() は "NO AVX" を返し、使えるときは "AVX2" または
"AVX512" を返します。Linux では grep -m1 flags /proc/cpuinfo が生のフラグを出力します
(報告では avx2 がありません)。そこで動いた設定は qnnpack で、エンコーダにだけ適用されました:
import torch
import torch.nn as nn
torch.backends.quantized.engine = "qnnpack"
torch.ao.quantization.quantize_dynamic(
agent.model.encoder, {nn.Linear}, dtype=torch.qint8, inplace=True)
エンコーダだけの量子化は、CPU が実行できるどちらのエンジンでも動きます。当てにできる高速化
ではなく、スコアを変えます。#1065 のマシンでは、qnnpack は 20 states で fp32 の 3.0 秒に対して
3.7 秒かかり、ある候補の noul が 0.15 から 0.04 になりました。torch 2.14.1(capability
AVX512、4 スレッド、短い state)での多言語チェックポイントの抜き取り確認でも同種の動きが
見られました。qnnpack は 0.57 秒に対して 2.1 秒かかり、ある noul が 0.90 から 0.13 に
なりました。fbgemm はその CPU では速く(0.39 秒)、それでもスコアを 0.15 へ動かしました。
レイテンシと確率は自分のデータで検証してください。
agent.model 全体を量子化しないでください。それは意思決定ヘッドの nn.Linear 層を動的量子化
された linear に置き換え、その weight はテンソルではなくメソッドになります。ヘッドは
nn.TransformerEncoderLayer で、その高速パスはそれらの重みの .device を読むので、predict
は AttributeError: 'function' object has no attribute 'device' を送出します。ヘッドは fp32 の
ままにしてください。