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",
)

Среда выполнения модели принятия решений System One: быстрые, неавторегрессионные, калиброванные решения.

dtype — это цель autocast, а не точность каждого вызова. На MPS вызов делает autocast только начиная с 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 к явному commit SHA/ветке/тегу; если он опущен, используются обычное значение по умолчанию huggingface_hub и существующий офлайн-кэш. expected_sha256 ({path relative to the checkpoint dir: hexdigest}) проверяет целостность артефактов до того, как будет разобран или выполнен любой вес; это opt-in и применяется также к локальным каталогам. Отсутствующий артефакт вызывает FileNotFoundError, а несовпадение дайджеста — ValueError; любая из этих ошибок отклоняет загрузку.

fast=True заменяет forward энкодера/головы на быстрый путь TileLang (только CUDA, требует pip install laya[fast]); см. Agent.accelerate.

compile=True запускает модель под torch.compile и включает у энкодера ModernBERT reference_compile. torch.compile специализируется по форме входа, и Laya видит новую почти на каждом запросе, так что такие графы обычно стоят дороже, чем дают; используйте его, когда трафик повторяющийся. fast=True имеет приоритет, потому что путь TileLang заменяет forward, который был бы скомпилирован. Скомпилированные агенты выполняют warmup() перед возвратом; compile_warmup=False откладывает эту работу на запросы или ручной вызов warmup(). Агенты eager и fast не меняются. compile_cache=True включает постоянный каталог Laya Inductor (в масштабе процесса), уважая любой существующий TORCHINDUCTOR_CACHE_DIR; см. инженерные заметки о компиляции. compile_mode="reduce-overhead" включает графы CUDA. Он может удерживать больше памяти GPU и записывает каждую новую форму отдельно. Выходные данные CUDA копируются перед следующим воспроизведением; скомпилированные прямые проходы с графами CUDA сериализуются. Режим по умолчанию остаётся "default".

subfolder выбирает один чекпойнт из репозитория, в котором их несколько, например Agent("convaiinnovations/laya", subfolder="multilingual"). Загружается только этот подкаталог, так что объединение в один репозиторий не стоит каждому пользователю всей семьи.

calibration — необязательный путь JSON с temperature и temperature_by_options. Он применяется после конфигурации чекпойнта, так что подобранная карта переопределяет поставляемые скаляры без перезаписи model.safetensors.

hooks / on_predict_start / on_predict_end наблюдают за каждым предсказанием или формируют его; см. laya.hooks. hooks_raise=False предупреждает и продолжает, когда хук падает, hooks_concurrent=False сериализует хуки, которые небезопасно запускать параллельно, а hooks_timeout ограничивает каждый вызов хука в секундах (None означает отсутствие ограничения).

backend: str

Активный бэкенд инференса, включая устаревшие флаги compile и fast.

backend_object

Установленный объект Backend, или None для устаревшей среды выполнения.

set_backend(name: str = "auto", strict: bool = False, options) -> str

Переключает бэкенды; недоступные бэкенды предупреждают и используют eager, если только не strict=True.

Опции передаются в конструктор бэкенда, например warmup=False для compile или use_graphs=False для tilelang. Переключение ждёт выполняющийся инференс.

accelerate(use_graphs: bool = True, strict: bool = False)

Заменяет forward модели на быстрый путь TileLang (слитые ядра GEMM/GEGLU/LayerNorm/RoPE, flash attention со скользящим окном, резидентные веса 16 бит, графы CUDA на каждый бакет формы).

Быстрый путь выполняется в dtype autocast агента на момент вызова (bf16 или fp16), поэтому он совпадает с заменяемым стандартным forward в пределах округления (см. benchmarks/parity_fast.py). После смены agent.dtype вызовите deaccelerate(), затем accelerate(), чтобы перестроить его. Возвращает True, если он включён. При strict=False любой сбой (нет CUDA, отсутствует tilelang) оставляет стандартный путь на месте.

warmup(shapes=None) -> float

Запускает forward на синтетическом входе каждой формы сейчас и возвращает затраченные секунды.

compile=True вызывает это при загрузке, если только не compile_warmup=False. Дополнительные формы по-прежнему можно прогревать вручную. fast=True строит свои ядра и графы CUDA на каждый бакет формы при первом использовании; вызов этого до обслуживания выносит эту стоимость из первых запросов. Со стандартным forward это несколько обычных проходов вперёд. shapes — список из (rows, tokens, markers); токены ограничены значением max_len агента. Ничего не возвращается и не записывается ни для какого вызывающего, и хуки не запускаются.

deaccelerate()

Восстанавливает стандартный forward.

dtype_for(rows: int) -> torch.dtype

Точность, в которой выполняется проход вперёд с rows строками вопросов.

dtype — цель autocast, задаваемая один раз при загрузке. Делает ли проход autocast, решается для каждого вызова: на MPS только начиная с mps_amp_min_rows строк. Этот метод возвращает dtype, когда проход с rows строками делает autocast, и torch.float32, когда нет. Вызов predict выполняет одну строку на вопрос.

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 обрабатывают одно состояние за проход вперёд; на GPU это оставляет большую часть размерности батча простаивающей. predict_batch собирает строки вопросов нескольких состояний в один тензор, так что вызов, который занял бы N последовательных проходов вперёд, занимает один (или ceil(len(states) / batch_size)), что в несколько раз быстрее на решение на GPU.

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, до одного окна (первого, а для списка разговора — последнего), молча отбрасывая остаток. predict_long токенизирует состояние один раз, разбивает его на перекрывающиеся окна токенов, оценивает каждое окно в общих проходах вперёд (через predict_batch) и объединяет ответы по окнам:

• noul -> P(true) — максимум по окнам (утверждение выполняется, если его поддерживает любое окно)
• choice-> ответ из единственного наиболее уверенного окна, чтобы локализованный сигнал не был перевесован множеством нейтральных окон, из которых в основном состоит длинный документ (усреднение его топит -- нейтральное большинство доминирует)
• score -> уровень из наиболее уверенного окна, аналогично

Возвращаемая вероятность/уверенность принадлежит решающему окну, а не калиброванному числу для всего документа: максимум noul по многим окнам дрейфует вверх с числом окон даже без сигнала, а choice может попасть на уверенно-нейтральное окно, когда ничто в документе не является решающим. Поэтому каждый ответ несёт answer["window"] — index решающего окна, token_start/token_end в токенизированном состоянии и count окон — так что вызывающий может исследовать фрагмент, из которого пришёл ответ, вместо того чтобы доверять сырому числу. Этот фрагмент — тот, который прочитала модель, а не просто запрошенный: окно ограничено местом, которое оставляют вопросы, так что то, что передаётся в predict_batch, больше не обрезается.

Состояние, которое уже помещается в одно окно, передаётся прямо в system_one (идентичный вывод).

Хуки оборачивают инференс, отвечающий на состояние, которым для документа, требующего нескольких окон, является один общий predict_batch по ним: on_predict_start срабатывает один раз, и ctx.states содержит декодированные тексты окон в порядке сканирования -- не state вызывающего, который был токенизирован, чтобы их получить. Из того, что оставляет цепочка, следуют три исхода:

• ctx.skip([result]) отвечает на документ: результат возвращается без атрибуции окна и с usage["windows"] равным 0, потому что ничего не было оценено
• сканирование, оставленное таким, каким его построил этот метод: оценивается каждое окно, каждый ответ несёт answer["window"], а usage["windows"] — это число окон
• переписанное сканирование (ctx.states заменён, любым способом): ответы агрегируются по состояниям, которые были оценены, но ни один ответ не несёт answer["window"] -- смещения выше описывают окна этого метода, а не текст, который прочитала модель

Возвращает единственный словарь результата, той же формы, что и system_one, с добавленным usage["windows"]. Ключ всегда присутствует и считает окна, которые модель оценила, чтобы получить ответ: 1 для состояния, вместившегося в одно окно, N для документа, просканированного в N перекрывающихся окнах (или N, к которому их переписал хук начала), и 0, когда хук начала ответил на документ или не оставил состояний для оценки, прежде чем было прочитано какое-либо окно -- в любом из этих путей, так что кэшированный ответ никогда не читается как окно, которое прочитала модель.

По нескольким окнам ключи усечения комбинируются, как любое другое поле usage: truncated, state_tokens и state_tokens_dropped суммируются (так что truncated — это число окон, которые были обрезаны, а счётчики токенов включают перекрытие), и truncated_questions — список последнего окна. Они могут расходиться: когда обрезано только более раннее окно, truncated больше 0, а truncated_questions пуст. Окно обрезается, когда оно больше места, которое оставляет голова вопроса. Проверяйте здесь usage["truncated"] > 0, а не is True.

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]

Оценивает типизированные вопросы по состоянию за один параллельный проход вперёд.

Чтобы оценить много состояний сразу, см. predict_batch, который разделяет проходы вперёд между ними.

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,
) -> Any

Отвечает на state относительно схемы (JSON-схемы или модели pydantic) и возвращает типизированные значения.

См. laya.structured. Передайте ровно одно из schema или questions; дополнительные именованные аргументы передаются в predict / system_one.

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]

Отвечает на многие состояния относительно одной схемы (JSON-схемы или модели pydantic) за один пакетный вызов.

Пропускная форма :meth:decide: схема планируется один раз, и её вопросы выполняются по каждому состоянию через :meth:predict_batch (общие проходы вперёд, результаты в порядке входа), затем ответы каждого состояния проецируются так же, как это делает decide. Дополнительные именованные аргументы (batch_size=, lang=, hooks=, ...) передаются в predict_batch. См. laya.structured.

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 влияет только на отложенную выборку ECE, когда compute_ece истинно. cfg чекпойнта остаётся таким, каким был загружен.

fit_binning(
    records,
    min_bucket_n: int = MIN_BINNING_BUCKET_N,
    MIN_BINNING_BUCKET_N,
) -> Dict[str, Any]

Подбирает карту гистограммной бинаризации поверх подобранных температур этого агента и сохраняет её.

records — это те же кортежи (qtype, logits, target[, k]), что потребляет fit_temperatures. Ключи карты в точности как у temperature_by_options, она компонуется поверх текущих температур и записывается save_calibration как binning_map.

save_calibration(path: str) -> None

Записывает температуры и чекпойнт, для которого они подбирались. Не записывает веса.

load_calibration(path: str) -> None

Читает JSON-карту, записанную save_calibration, на этот агент.

Файл без version трактуется как версия 1 и всё равно загружается. Более новый файл, записанный чекпойнт которого не совпадает с этим агентом, предупреждает и всё равно загружается. Значения, которые не являются числами или лежат вне [TEMP_MIN, TEMP_MAX], ограничиваются с помощью clamp_temperature так же, как при загрузке чекпойнта.

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",
) -> Agent

Загружает агента Laya.

subfolder выбирает один чекпойнт из репозитория, в котором их несколько:

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, так что обе точки входа читают одну таблицу:

laya.load("typed-decisions")
laya.load("ml")                                               # multilingual

Всё остальное (id репозитория Hub, локальный каталог) передаётся в 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 — тот же необязательный путь JSON, который принимает Agent.

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

Среда выполнения модели принятия решений System One через ONNX: быстрые решения, оптимизированные для CPU.

Загружает агента Laya на базе ONNX Runtime.

load_calibration(path: str) -> None

Читает JSON-карту, записанную save_calibration, на этот агент.

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]

Оценивает типизированные вопросы по состоянию за один запуск сессии ONNX Runtime.

lang выбирает переопределение температуры по языку (см. lang_temperatures), совпадая с сигнатурой PyTorch Agent.system_one, так что любой из бэкендов заменяет другой без изменений.

Определён в терминах predict_batch, точно как PyTorch Agent.system_one, чтобы пути для одного состояния и пакетный не могли разойтись.

Чтобы оценить много состояний сразу, см. 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 собирает строки вопросов одного состояния за запуск сессии, так что N состояний стоят N запусков. predict_batch собирает строки нескольких состояний в один запуск -- или ceil(len(states) / batch_size) из них -- именно здесь собственный параллелизм ONNX Runtime окупается на CPU.

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]

Оценивает вопросы по состоянию, которое длиннее контекстного окна, сканируя его в перекрывающихся окнах и агрегируя по каждому вопросу.

ONNX-порт laya.agent.Agent.predict_long с теми же правилами агрегации: system_one усекает состояние, превышающее max_len, до одного окна, молча отбрасывая остаток. predict_long токенизирует состояние один раз, разбивает его на перекрывающиеся окна токенов, оценивает каждое окно через predict_batch -- так окна разделяют запуски сессии ONNX Runtime, а не стоят по одному каждое -- и объединяет ответы по окнам:

• noul -> P(true) — максимум по окнам (утверждение выполняется, если его поддерживает любое окно)
• choice-> ответ из единственного наиболее уверенного окна, чтобы локализованный сигнал не был перевесован множеством нейтральных окон, из которых в основном состоит длинный документ
• score -> уровень из наиболее уверенного окна, аналогично

Возвращаемая вероятность/уверенность принадлежит решающему окну, а не калиброванному числу для всего документа, по тем же причинам, которые приводит docstring PyTorch. Каждый ответ несёт answer["window"] -- index решающего окна, token_start/token_end в токенизированном состоянии и count окон.

Состояние, которое уже помещается в одно окно, передаётся прямо в system_one (идентичный вывод).

Возвращает единственный словарь результата, той же формы, что и system_one, с добавленным usage["windows"]. По нескольким окнам ключи усечения суммируются или переносятся так же, как в Agent.predict_long: truncated — это число окон, а truncated_questions — список последнего окна, так что truncated может быть больше 0, пока список пуст.

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,
) -> Any

Отвечает на state относительно схемы (JSON-схемы или модели pydantic) и возвращает типизированные значения.

См. laya.structured. Передайте ровно одно из schema или questions; дополнительные именованные аргументы передаются в predict / system_one.

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; см. laya.structured.

python scripts/export_onnx.py --model convaiinnovations/laya --output laya.onnx --quantize