Agent
laya.Agent는 체크포인트 하나를 로드하고 상태에 대한 타입이 지정된 질문에 답합니다.
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 다운로드를 명시적인 commit SHA/브랜치/tag에 고정합니다. 생략하면 huggingface_hub의 일반 기본값과 기존 오프라인 캐시를 사용합니다. expected_sha256({체크포인트 디렉터리에 상대적인 경로: hexdigest})은 어떤 가중치도 파싱되거나 실행되기 전에 산출물 무결성을 검증합니다. 선택 사항이며 로컬 디렉터리에도 적용됩니다. 산출물이 없으면 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를 대체하기 때문입니다.
컴파일된 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 forward는 직렬화됩니다. 기본 모드는 "default"로 남습니다.
subfolder는 여러 체크포인트를 묶어 둔 저장소에서 하나를 고릅니다. 예: 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은 각 훅 호출을 초 단위로 제한합니다(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)모델 forward를 TileLang 빠른 경로(융합 GEMM/GEGLU/LayerNorm/RoPE 커널, 슬라이딩 윈도 flash attention, 16비트 상주 가중치, 형상 버킷별 CUDA graph)로 바꿉니다.
빠른 경로는 호출 시점의 agent 자동 캐스트 dtype(bf16 또는 fp16)으로 실행되므로, 대체하는 원래 forward와 반올림 오차 내에서 일치합니다(benchmarks/parity_fast.py 참고). agent.dtype을 바꾼 뒤에는 deaccelerate()를 호출한 다음 accelerate()를 호출해 다시 만드십시오. 활성화되면 True를 반환합니다. strict=False이면 어떤 실패(CUDA 없음, tilelang 누락)든 원래 경로를 그대로 둡니다.
매개변수
use_graphsbool=Truestrictbool=False
warmup
warmup(shapes=None) -> float지금 각 형상의 합성 입력으로 forward를 실행하고 걸린 시간(초)을 반환합니다.
compile=True는 compile_warmup=False가 아닌 한 로드 시점에 이를 호출합니다. 추가 형상은 수동으로 데울 수 있습니다. fast=True는 처음 사용할 때 형상 버킷별로 커널과 CUDA graph를 만듭니다. 서빙 전에 이를 호출하면 그 비용을 처음 몇 요청 밖으로 옮길 수 있습니다. 원래 forward에서는 평범한 forward 패스 몇 번에 불과합니다. shapes는 (rows, tokens, markers)의 리스트이고, tokens는 agent의 max_len으로 제한됩니다. 어떤 호출자에게도 반환되거나 기록되는 것이 없으며, 훅도 실행되지 않습니다.
매개변수
shapes=None
deaccelerate
deaccelerate()원래 forward를 복원합니다.
dtype_for
dtype_for(rows: int) -> torch.dtype행 수가 rows인 질문 행으로 하는 forward 패스가 실행되는 정밀도입니다.
dtype은 로드 시점에 한 번 설정되는 자동 캐스트 대상입니다. forward가 자동 캐스트하는지는 호출마다 결정됩니다. MPS에서는 행 수가 mps_amp_min_rows 이상일 때만 그렇습니다. 행 수가 rows인 forward가 자동 캐스트하면 dtype을, 그렇지 않으면 torch.float32를 반환합니다. predict 호출은 질문마다 한 행을 실행합니다.
매개변수
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]]여러 상태에 대해 같은 질문을 평가하고, 이들을 공유 forward 패스로 묶습니다.
이것이 처리량 경로입니다. system_one/predict는 forward 패스마다 상태 하나를 처리하므로, GPU에서는 배치 차원의 대부분이 놀게 됩니다. predict_batch는 여러 상태의 질문 행을 하나의 텐서로 모으므로, N번의 순차 forward 패스를 필요로 하던 호출이 한 번(또는 ceil(len(states) / batch_size)번)이 되고, GPU에서 결정마다 몇 배 더 빠릅니다.
매개변수
statesList[Union[str, dict, list]]상태의 리스트입니다(각각은 텍스트 문자열, JSON 딕셔너리 또는 대화 턴 리스트). 같은
questions가 모든 상태에 대해 평가됩니다.questionsDict[str, Dict[str, Any]]system_one이 받는 것과 정확히 같은 질문 정의입니다.batch_sizeOptional[int]=Noneforward 패스당 상태 수의 선택적 상한입니다.
None은 전부 한 번에 보냅니다. 많거나 긴 상태를 배치 처리할 때 최대 메모리를 제한하려면 설정하십시오.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이 호출에 대해 agent 설정의
max_len을 재정의합니다. 시작 훅이ctx.max_len을 설정해 토큰 예산을 형성할 수도 있습니다.head_max_lenOptional[int]=None이 호출에 대해 agent 설정의
head_max_len을 재정의합니다. 시작 훅이ctx.head_max_len을 설정할 수도 있습니다.sort_by_lengthbool=False비슷한 크기로 인코딩된 상태를 여덟 배치 단위의 윈도로 묶어 패딩을 줄입니다. 1보다 크고 상태 수보다 작은
batch_size를 명시적으로 요구하며, 그렇지 않으면 아무 효과가 없습니다. 결과는 입력 순서를 유지합니다. 한 배치가 아니라 최대 여덟 배치의 토큰화된 상태를 버퍼링합니다. 배치 형상을 바꾸면 부동소수점 예측이 약간 달라질 수 있습니다.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을 초과하는 상태를 하나의 윈도(첫 번째, 대화 리스트의 경우 마지막)로 잘라내고 나머지는 조용히 버립니다. predict_long은 상태를 한 번 토큰화하고, 겹치는 토큰 윈도로 나누고, 공유 forward 패스에서 모든 윈도를 채점하며(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가 아니라, 그 state는 이 윈도들을 만들기 위해 토큰화된 것입니다. 이 체인이 남기는 것에 따라 세 가지 결과가 나옵니다:
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_len - head_max_len - 8)이며, 어느 쪽이든 질문이max_len안에서 상태를 위해 남기는 공간이 상한이 됩니다 -- 그중 가장 작은 공간입니다. 윈도 리스트 하나가 모든 질문에 대해 채점되기 때문입니다. 더 넓은 윈도는 모델로 가는 도중에 다시 잘리므로, 대신 클램프되며 호출자가 직접 요청한 경우RuntimeWarning이 나옵니다. 공간을 작게 만드는 것은 옵션입니다. 영어 체크포인트에서 2지선다 질문은 상태를 위해 483개 토큰을 남기고, 100지선다 질문은 100개를 남깁니다. 윈도가 작을수록 국소 신호를 더 잘 분리합니다(짧은 결정 구간이 윈도에서 차지하는 비중이 커져 그 윈도가 그것을 분명하게 분류합니다), 대신 윈도 수가 늘어납니다. 기본값인 큰 윈도는 컨텍스트와 처리량을 선호합니다.noul은 이에 강건하고, 결정 구간이 길고 그 외에는 중립인 문서의 작은 부분일 때choice/score는 작은 윈도의 이점을 봅니다.strideOptional[int]=None윈도 사이의 토큰 스텝입니다. 기본값은 실효 윈도의 절반(50% 겹침)이므로, 경계 근처의 구간도 어떤 윈도 안에 온전히 들어갑니다. 실효 윈도를 넘어서는 스트라이드는 클램프되지 않고 거부됩니다. 그러면 각 윈도 쌍 사이의 토큰을 어떤 윈도도 읽지 않게 되는데, 이것이 바로 이 메서드가 막으려는 실패입니다.
aggregatestr="auto""auto"(위의 타입별 규칙)가 현재 유일한 모드입니다.
batch_sizeOptional[int]=Noneforward 패스당 윈도 수의 상한으로, 매우 긴 상태에서 메모리를 제한합니다.
langOptional[str]=Nonesystem_one에서처럼 언어별 temperature 선택입니다.hooksHookArg=None호출별 훅이며, Agent에 이미 설치된 훅 뒤에 덧붙습니다.
laya.hooks를 참고하십시오.on_predict_startPredictHookArg=Nonesystem_one에서처럼 호출별 시작 훅입니다.on_predict_endPredictHookArg=Nonesystem_one에서처럼 호출별 종료 훅입니다.hooks_raiseOptional[bool]=None이 호출에 대해 Agent의
hooks_raise를 재정의합니다.hooks_timeoutOptional[float]=None이 호출에 대해 Agent의
hooks_timeout을 재정의합니다.
예외
ValueError: aggregate가 "auto"가 아닌 경우, 질문의 선택지가 시퀀스 전체를 채워 상태를 위한 공간을 남기지 않는 경우, 또는 stride가 실효 윈도를 넘어서는 경우입니다. 마지막 경우에는 두 윈도 사이의 토큰을 아무것도 읽지 않게 됩니다.
usage["windows"]가 추가된, system_one과 같은 형상의 단일 결과 딕셔너리를 반환합니다. 이 키는 항상 존재하며 모델이 답을 내기 위해 채점한 윈도 수를 셉니다. 하나의 윈도에 들어간 상태는 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]단일 병렬 forward 패스에서 상태 전반에 걸쳐 타입화된 질문을 평가합니다.
매개변수
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
반환값
답, 확률, 캘리브레이션된 신뢰도, 토큰 사용량을 담은 딕셔너리입니다. 질문이 비어 있으면 토큰화나 모델 forward 패스 없이 빈 답과 0 토큰 사용량을 반환합니다.
헤드 예산이 두 옵션을 같은 토큰 구간에 남길 때, usage는 그렇게 된 각 질문에 대해 options 항목 -- total, distinct, tokens_per_option -- 을 담습니다. 58개의 구분 가능한 구간 중 42개에서 고른 답은 모델이 아니라 예산이 정한 상한을 갖기 때문입니다. 옵션이 모두 살아남은 질문은 나타나지 않으므로, 아무것도 압축되지 않은 요청은 변하지 않습니다.
usage는 상태가 들어맞았는지도 보고합니다. truncated, state_tokens, state_tokens_dropped, 그리고 truncated_questions(헤드가 공간을 너무 적게 남긴 질문들)입니다. 답이 전체 상태를 보았는지가 중요한 호출자는 보낸 내용의 길이로 추정하지 말고 usage["truncated"]를 읽어야 합니다.
여러 상태를 한 번에 채점하려면, 상태들 간에 forward 패스를 공유하는 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]여러 상태를 하나의 스키마(JSON schema 또는 pydantic 모델)에 대해 한 번의 배치 호출로 답합니다.
:meth:decide의 처리량 형태입니다. 스키마는 한 번 계획되고 그 질문들은 :meth:predict_batch를 통해 모든 상태에 대해 실행되며(공유 forward 패스, 입력 순서대로 결과), 그런 다음 각 상태의 답이 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 기록에서 버킷별 temperature를 피팅해 이 agent에 저장합니다.
records는 (qtype, logits, target, k)입니다. 라벨이 있는 forward가 있으면 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]이 agent가 피팅한 temperature 위에 히스토그램 구간화 맵을 피팅해 저장합니다.
records는 fit_temperatures가 소비한 것과 같은 (qtype, logits, target[, k]) 튜플입니다. 맵의 키는 temperature_by_options와 정확히 같고, 현재 temperature 위에 겹쳐 적용되며, save_calibration이 binning_map으로 씁니다.
매개변수
recordsmin_bucket_nint=MIN_BINNING_BUCKET_NMIN_BINNING_BUCKET_N
save_calibration
save_calibration(path: str) -> Nonetemperature와 그것들이 어느 체크포인트를 위해 피팅되었는지를 씁니다. 가중치는 쓰지 않습니다.
매개변수
pathstr
load_calibration
load_calibration(path: str) -> Nonesave_calibration이 쓴 JSON 맵을 이 agent로 읽어들입니다.
version이 없는 파일은 버전 1로 취급되며 여전히 로드됩니다. 기록된 체크포인트가 이 agent와 맞지 않는 더 새로운 파일은 경고하고 여전히 로드됩니다. 숫자가 아니거나 [TEMP_MIN, TEMP_MAX] 밖에 있는 값은 체크포인트 로드와 같은 방식으로 clamp_temperature로 클램프됩니다.
매개변수
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 agent를 로드합니다.
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
그 밖의 것(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 agent를 로드합니다.
매개변수
model_id_or_pathstr원본 PyTorch 체크포인트의 HuggingFace Hub ID 또는 로컬 경로입니다(토크나이저와 설정을 로드하는 데 사용됩니다).
onnx_pathstr="laya.onnx"내보낸 .onnx 파일의 경로입니다.
tokenOptional[str]=None비공개 또는 게이트된 체크포인트용 선택적 HuggingFace token입니다.
Agent와 정확히 같이$HF_TOKEN으로 폴백합니다. 토크나이저와 설정만 가져옵니다 -- 그래프 자체는 로컬onnx_path입니다.subfolderOptional[str]=None저장소 번들에서 다운로드하는 경우의 선택적 하위 폴더입니다.
revisionOptional[str]=None선택적 Hub 리비전(commit SHA/브랜치/tag)입니다. 생략하면 huggingface_hub의 일반 기본값과 기존 오프라인 캐시를 사용합니다.
expected_sha256Optional[Dict[str, str]]=None선택적 {체크포인트 디렉터리에 상대적인 경로: hexdigest}이며, 어떤 체크포인트 파일도 파싱되기 전에 검증됩니다. 선택 사항이고 로컬 디렉터리에도 적용됩니다. 산출물이 없으면
FileNotFoundError를, 다이제스트가 맞지 않으면ValueError를 발생시킵니다. 어느 오류든 이번 로드를 거부합니다.hooksHookArg=None선택적 예측 훅입니다.
laya.hooks를 참고하십시오.on_predict_startPredictHookArg=None추론 전에 실행되는 선택적 시작 훅입니다.
on_predict_endPredictHookArg=None추론 후에 실행되는 선택적 종료 훅입니다.
hooks_raisebool=TrueFalse이면 훅이 실패해도 경고하고 추론은 계속됩니다.
hooks_concurrentbool=TrueFalse이면 훅이 잠금으로 직렬화됩니다.
hooks_timeoutOptional[float]=None각 훅 호출을 초 단위로 제한합니다. None은 제한 없음입니다.
lang_temperaturesOptional[Dict[str, Dict[str, Any]]]=None언어 코드로 키가 지정된 선택적 언어별 temperature 재정의이며, 각각
{"temperature": [3 floats], "temperature_by_options": {}}입니다.system_one/predict에lang=이 전달될 때 적용되어 PyTorchAgent를 그대로 반영합니다. 그렇지 않으면 백엔드를 바꿀 때 캘리브레이션을 잃습니다.calibrationOptional[str]=None
load_calibration
load_calibration(path: str) -> Nonesave_calibration이 쓴 JSON 맵을 이 agent로 읽어들입니다.
매개변수
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]하나의 ONNX Runtime 세션 실행에서 상태 전반에 걸쳐 타입화된 질문을 평가합니다.
lang은 언어별 temperature 재정의를 선택하며(lang_temperatures 참고), PyTorch Agent.system_one 시그니처와 맞으므로 어느 백엔드든 다른 쪽을 그대로 대체할 수 있습니다.
PyTorch Agent.system_one과 정확히 마찬가지로 predict_batch로 정의되므로, 단일 상태 경로와 배치 경로가 서로 어긋날 수 없습니다.
매개변수
stateUnion[str, dict, list]텍스트 문자열, JSON 딕셔너리 또는 대화 턴 리스트입니다.
questionsDict[str, Dict[str, Any]]Agent.system_one이 받는 형상을 가진 질문 정의입니다.langOptional[str]=None언어별 temperature 재정의입니다(
lang_temperatures참고).hooksHookArg=None호출별 훅이며, agent에 이미 설치된 훅 뒤에 덧붙습니다.
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을 재정의합니다.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은 세션 실행마다 상태 하나의 질문 행을 모으므로 N개 상태에 N번의 실행이 듭니다. predict_batch는 여러 상태의 행을 한 번의 실행으로 -- 또는 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은 전부 한 번의 실행으로 보냅니다. 많거나 긴 상태를 배치 처리할 때 최대 메모리를 제한하려면 설정하십시오.langOptional[str]=None모든 상태에 적용되는 언어별 temperature 재정의입니다.
lang_temperatures를 참고하십시오.hooksHookArg=None호출별 훅이며, agent에 이미 설치된 훅 뒤에 덧붙습니다.
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을 재정의합니다.head_max_lenOptional[int]=None이 호출에 대해 설정의
head_max_len을 재정의합니다.sort_by_lengthbool=False비슷한 크기로 인코딩된 상태를 여덟 배치 단위의 윈도로 묶어 패딩을 줄이며,
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을 초과하는 상태를 하나의 윈도로 잘라내고 나머지는 조용히 버립니다. predict_long은 상태를 한 번 토큰화하고, 겹치는 토큰 윈도로 나누고, predict_batch를 통해 모든 윈도를 채점하며(그래서 윈도들이 각각 비용을 치르는 대신 ONNX Runtime 세션 실행을 공유합니다), 윈도별 답을 결합합니다:
- noul -> P(true)는 윈도들에 대한 최댓값입니다(어느 윈도 하나라도 뒷받침하면 그 진술은 성립합니다)
- choice-> 가장 확신하는 단일 윈도의 답입니다. 그래야 국소 신호가 긴 문서 대부분을 차지하는 다수의 중립 윈도에 투표로 밀리지 않습니다
- score -> 마찬가지로 가장 확신하는 윈도의 레벨입니다
반환되는 확률/신뢰도는 결정을 내린 윈도의 것이며, 문서 전체에 대해 캘리브레이션된 숫자가 아닙니다. 이유는 PyTorch 문서 문자열에 나온 것과 같습니다. 각 답은 answer["window"]를 함께 가집니다 -- 결정 윈도의 index, 토큰화된 상태에서의 token_start/token_end, 그리고 윈도 수 count입니다.
이미 하나의 윈도에 들어가는 상태는 system_one으로 곧장 전달됩니다(출력이 동일합니다).
매개변수
stateUnion[str, dict, list]텍스트 문자열, JSON 딕셔너리 또는 대화 턴 리스트입니다.
questionsDict[str, Dict[str, Any]]system_one이 받는 것과 정확히 같은 질문 정의입니다.windowOptional[int]=None윈도당 상태 토큰 수입니다. 기본값은 질문별 상태 예산(
max_len - head_max_len - 8)입니다.Agent.predict_long에서처럼 윈도가 작을수록 국소 신호를 더 잘 분리하며 대신 윈도 수가 늘어납니다.strideOptional[int]=None윈도 사이의 토큰 스텝입니다. 기본값은
window // 2(50% 겹침)입니다.aggregatestr="auto""auto"(위의 타입별 규칙)가 현재 유일한 모드입니다.
batch_sizeOptional[int]=None세션 실행당 윈도 수의 상한으로, 매우 긴 상태에서 최대 메모리를 제한합니다.
langOptional[str]=Nonesystem_one에서처럼 언어별 temperature 선택입니다.hooksHookArg=None호출별 훅이며, agent에 이미 설치된 훅 뒤에 덧붙습니다. 이들은
Agent.predict_long의 계약을 따릅니다. 즉 상태에 답하는 추론을 감싸고,ctx.skip(...)으로 답하는 시작 훅은usage["windows"] == 0과 윈도 귀속 없음을 받으며, 재작성된 스캔은answer["window"]없이 집계됩니다.on_predict_startPredictHookArg=Nonesystem_one에서처럼 호출별 시작 훅입니다.on_predict_endPredictHookArg=Nonesystem_one에서처럼 호출별 종료 훅입니다.hooks_raiseOptional[bool]=None이 호출에 대해 agent의
hooks_raise를 재정의합니다.hooks_timeoutOptional[float]=None이 호출에 대해 agent의
hooks_timeout을 재정의합니다.
usage["windows"]가 추가된, system_one과 같은 형상의 단일 결과 딕셔너리를 반환합니다. 여러 윈도에 걸치면 잘림 관련 키가 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를 통해 답합니다. 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