Router

Router(
    models: Optional[Dict[str, str]] = None,
    device: Optional[str] = None,
    token: Optional[str] = None,
    revision: Optional[str] = None,
    revisions: Optional[Dict[str, Optional[str]]] = None,
    max_loaded: int = 2,
    default: str = "english",
    auto_task_detection: bool = False,
    standalone_repos: bool = False,
    preload: bool = False,
    lang_guess: Optional[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,
    agent_kwargs: Optional[Dict[str, Any]] = None,
    sha256_digests: Optional[Dict[str, Optional[Dict[str, str]]]] = None,
)

Laya 체크포인트를 지연 로드하고 각 요청을 맞는 것에 보냅니다.

from laya import Router

r = Router()
r.predict({"message": "Mein Konto wurde zweimal belastet"}, questions)   # -> multilingual
r.predict({"message": "I was charged twice"}, questions)                 # -> english
r.predict(state, questions, model="typed-decisions")                     # explicit

모델은 처음 사용할 때 다운로드되고 빌드됩니다. max_loaded는 상주하는 개수를 제한하며(가장 최근에 사용되지 않은 것이 축출됩니다), 셋을 합치면 약 11.6억 파라미터이기 때문입니다.

기본값은 2입니다. 자동 라우팅은 english와 multilingual 사이에서만 고르기 때문입니다. 상한을 1로 두면 스크립트를 바꿀 때마다 방금 축출한 체크포인트를 다시 빌드하는데, 이는 Router가 존재하는 바로 그 트래픽에서 요청마다 수 초가 걸립니다. 한 언어만 보는 트래픽은 두 번째 체크포인트를 결코 빌드하지 않으므로 기본값은 그것에 아무 비용도 지우지 않습니다. 메모리가 제한된 호스트에서는 1로 낮추고, auto_task_detection, 명시적 model= 또는 명시적 task=가 typed-decisions에도 닿을 수 있을 때는 3으로(또는 프리로드로) 올리십시오.

서버나 데모에서는 대신 프리로드하십시오. 차가운 로드는 수 초가 걸리는 반면 탐지는 마이크로초가 걸리므로, 기본값이라도 언어가 처음 나타날 때 여전히 로드 비용을 치릅니다.

r = Router(preload=True)                    # all three resident, routing is free
r = Router(preload=True, device="cuda")
r.preload(["english", "multilingual"])      # or just the two you serve

Hub 리비전은 선택적입니다. revision은 모든 모델에 하나의 commit을 적용하고, revisions={"english": "...", "multilingual": "..."}는 모델별로 그것을 덮어씁니다. 이는 독립 저장소들이 서로 다른 commit에서 검토되었을 때 유용합니다. 둘 다 없으면 huggingface_hub의 일반 기본값과 기존 오프라인 캐시를 사용합니다.

revisions 항목이 None이거나 비어 있으면 "이 모델에 대한 재정의 없음"이므로, 그 모델은 revision을 상속합니다 -- 변수가 설정되지 않았을 때 {"english": os.environ.get("EN_SHA")}가 쓰는 형태이며, 이것이 호출자가 실제로 요청한 고정을 잃게 해서는 안 됩니다. revisions의 어떤 것도 revision이 나머지를 고정하는 동안 한 모델을 풀 수 없습니다. 고정할 모델을 지정하고 revision은 설정하지 않은 채 두십시오.

빈 revision도 같은 방식으로 읽습니다. 이는 Router가 전달하는 내용의 의도적인 변경입니다. Router(revision=" ")는 예전에는 resolve_revision에 도달했고, 거기서 참이지만 빈 문자열이 LAYA_REVISION 폴백을 억제하고 huggingface_hub의 기본값을 남겨 두었습니다. 이제는 거기 도달하기 전에 버려지므로, 공백으로 설정된 Router는 아무것도 설정하지 않은 것처럼 동작하고 $LAYA_REVISION이 적용됩니다. revision과 revisions 항목을 같은 방식으로 읽으려면 이것이 "이 설정 줄은 한 번도 채워지지 않았다"의 의미여야 합니다.

이는 더 약한 출처가 명시적 인수보다 앞서게 되는 두 곳 중 하나입니다. 다른 하나는 LAYA_SHA256_DIGESTS의 체크포인트별 다이제스트 항목으로, agent_kwargs를 통해 전달된 expected_sha256을 이깁니다. 클래스 docstring을 참고하십시오.

laya.Agent가 받는 다른 모든 것은 Router가 빌드하는 모든 체크포인트에 병합되는 agent_kwargs를 통해 전달할 수 있습니다:

Router(agent_kwargs={"lang_temperatures": {"de": {"temperature": [1.0, 1.4, 2.0]}}})
Router(agent_kwargs={"expected_sha256": {"model.safetensors": "a3f1..."}})
Router(agent_kwargs={"fast": True})

거기의 expected_sha256는 모든 체크포인트에서 같은 파일을 고정합니다. 단일 상주 체크포인트나 공유 tokenizer.json이 원하는 것이 바로 이것입니다. 체크포인트 자체의 다이제스트가 통째로 버리는 일은 없습니다. 어떤 체크포인트에도 항목이 있으면(sha256_digests 또는 체크포인트별 LAYA_SHA256_DIGESTS에서), 두 맵은 파일 단위로 병합되므로, 둘 중 하나만 지정한 파일도 여전히 검증됩니다.

두 가지 예외가 있으며, 둘 다 의도적이고 테스트되어 있습니다. "파일 단위로 병합"이 이야기의 전부가 아니고 그 차이가 공급망 통제이기 때문입니다:

• 평평한 LAYA_SHA256_DIGESTS -- {artifact: digest} 형태이고 {model: {...}}가 아님 -- 는 여기서 계층이 전혀 아닙니다. verify_digests가 스스로 적용하지만, 다른 무엇도 고정하지 않을 때(if expected is None)만 적용하므로, 여기서든 체크포인트 항목에서든 Agent에 도달하는 어떤 expected_sha256이든 그 로드에서 평평한 변수가 참조되지 않는다는 뜻입니다. 실제 파일에서 검증했습니다. model.safetensors를 고정하는 평평한 변수와 tokenizer.json을 고정하는 agent_kwargs 맵이 있으면 변조된 model.safetensors를 로드합니다. 둘 다 필요하면 체크포인트별 형태를 쓰거나, 신경 쓰는 모든 파일을 하나의 맵에 넣으십시오. 이것은 main에서 변하지 않았습니다.
• 명시적인 {} 또는 None 항목은 그렇지 않으면 적용될 것을 마스킹합니다 -- 그것이 "이것은 검증하지 않고 로드한다"의 의미여야 하며, test_an_explicit_none_entry_masks_a_flat_environment_map이 그것을 고정합니다.

그리고 우선순위는 각각 어디서 왔든 체크포인트별이 공유보다 위입니다. 따라서 LAYA_SHA256_DIGESTS에서 합성된 체크포인트별 항목은 여기 코드에서 전달된 expected_sha256을 이깁니다. 환경 변수가 명시적 인수를 이긴다는 점은 이런 통제에서는 분명히 말해 둘 가치가 있습니다. test_an_environment_pin_overrides_the_shared_one_per_checkpoint가 그것을 고정합니다.

양쪽이 모두 지정한 파일에 대해서는 체크포인트별 항목이 이깁니다. 둘은 똑같이 구체적이지 않습니다. agent_kwargs 맵은 Router가 빌드하는 모든 체크포인트에 도달하고, model.safetensors는 모든 체크포인트가 서로 다른 파일에 사용하는 하나의 이름이므로, 그것에 대한 공유 항목은 모든 체크포인트에 대해 동시에 올바른 주장일 수 없습니다. 그 겹침에 대해 아무것도 예외를 던지지 않습니다 -- 거부하면 공유 고정 더하기 체크포인트별 재정의라는, 이것이 존재하기 전에도 올바르게 로드되던 일반적인 형태를 거부하게 됩니다. 어떤 체크포인트가 어떤 다이제스트로 검증되었는지 알고 싶으면 다시 읽어 보십시오. 각 Agent에 전달되는 맵이 위에서 설명한 병합 결과입니다.

agent_kwargs와 sha256_digests는 둘 다 공개적이고 가변이며, 체크포인트의 항목은 생성 시점이 아니라 로드 시점에 읽히므로, 나중에 할당된 고정 -- 또는 기존 항목에 제자리에서 추가된 것 -- 도 인정됩니다.

Router가 스스로 설정하는 이름 -- model_id_or_path, device, token, subfolder, revision 및 hook 인수들 -- 은 여기서 조용히 덮이는 대신 거부되며, 나머지 이름은 생성 시 Agent.__init__과 대조되어 검사되므로, 잘못 쓴 옵션은 첫 요청이 아니라 Router(...) 줄에서 실패합니다.

산출물 다이제스트는 선택적이며 항상 모델별입니다. sha256_digests={"english": {...}}는 그 {path relative to the checkpoint dir: hexdigest} 맵을 그것을 로드하는 Agent에 전달하므로, 변조되거나 바뀐 가중치 파일은 파싱되기 전에 거부됩니다. revision의 Router 전역 등가물은 없습니다. 다이제스트는 commit SHA와 달리 공유할 수 없기 때문입니다. 번들 저장소는 english, multilingual, typed-decisions 각각에 별도의 model.safetensors를 제공하므로, 하나의 평평한 맵은 그중 하나에만 맞을 수 있습니다. None 또는 {}로 나열된 모델은 자기 파일을 전혀 추가하지 않으므로, agent_kwargs["expected_sha256"]이 고정하지 않는 한 검증 없이 로드됩니다. 그래도 평평한 LAYA_SHA256_DIGESTS를 마스킹하며, 그렇게 나열하는 이유가 바로 그것입니다.

같은 분리는 환경으로만 구성된 프로세스에도 제공됩니다. LAYA_SHA256_DIGESTS가 모델 키 맵({"english": {...}, "multilingual": {...}})을 담고 있으면 이를 체크포인트별로 심어 주므로, 여러 개를 상주시키는 서버가 두 번째에서 시작을 거부하는 대신 각각을 자기 다이제스트로 고정할 수 있습니다. 평평한 LAYA_SHA256_DIGESTS는 기존 의미를 유지하며 laya.revisions에 의해 프로세스가 로드하는 모든 체크포인트에 적용되는데, 이는 단일 체크포인트 프로세스에 맞습니다. 인수 항목은 그것이 지명한 모델에 대해 환경보다 우선합니다. 일부 체크포인트만 지명하고 나머지는 지명하지 않는 중첩 변수는 나머지에 대해 아무 말도 하지 않습니다. 나머지는 agent_kwargs["expected_sha256"]이 고정하는 것을 유지합니다. 환경에서 체크포인트 하나를 고정하는 것이 나머지 검증을 중단하라는 요청은 아니기 때문입니다.

Hook은 선택적이며 Router 수준에서 실행됩니다. on_route는 라우팅 결정을 보고, on_load / on_evict는 모델 수명 주기를 보며, on_predict_start / on_predict_end는 전체 route+infer 호출을 감쌉니다. laya.hooks를 참고하십시오.

load(name: str)

name에 해당하는 Agent를 반환하며, 처음 사용할 때 다운로드하고 빌드합니다.

동시 호출자들은 중복으로 빌드하지 않고 하나의 Agent를 공유합니다.

attach(name: str, agent: Any)

이미 빌드된 Agent를 두 번째 사본을 로드하는 대신 name 아래에 등록합니다.

프로세스가 다른 이유로 체크포인트를 이미 로드한 경우 유용합니다. 이미 convaiinnovations/laya를 빌드한 데모는 중복된 421M 파라미터에 대한 비용을 치르고 메모리에 붙들어 두는 대신 그것을 router에 넘길 수 있습니다.

preload(names: Optional[List[str]] = None)

미리 체크포인트를 다운로드하고 빌드해 어떤 요청도 모델 로드 비용을 치르지 않게 합니다.

차가운 로드는 수 초가 걸리고 언어 감지는 마이크로초가 걸립니다. 모든 체크포인트가 상주하면 라우팅은 사실상 무료이며, 이는 서버나 데모에서 원하는 바로 그것입니다. max_loaded는 요청된 체크포인트와 이미 상주하는 모든 agent를 모두 수용하도록 올라가므로, 증분 프리로딩이 어느 쪽도 축출하지 않습니다.

unload(name: Optional[str] = None)

모델 하나를, 또는 전부를 해제합니다.

loaded_revisions: Dict[str, Optional[str]]

각 상주 agent가 로드된 commit SHA(로컬 경로는 None)입니다.

route(
    state: Union[str, dict, list, None],
    questions: Optional[Dict[str, Any]] = None,
    model: Optional[str] = None,
    task: Optional[str] = None,
    lang: Optional[str] = None,
    lang_guess: Optional[Any] = None,
    hooks=None,
    hooks_raise: Optional[bool] = None,
    hooks_timeout: Optional[float] = None,
) -> RouteDecision

어떤 체크포인트를 쓸지 결정한 다음, on_route 훅이 그것을 관찰하거나 대체하게 합니다.

ctx.decision은 RouteDecision입니다. 훅이 그것을 대체할 수 있으며(예: 체크포인트를 고정하기 위해), 대체된 것이 반환되어 사용됩니다. hooks는 호출별 훅이며, Router에 설치된 훅 뒤에 덧붙습니다.

predict(
    state: Union[str, dict, list],
    questions: Dict[str, Any],
    model: Optional[str] = None,
    task: Optional[str] = None,
    lang: Optional[str] = None,
    lang_guess: Optional[Any] = 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 패스로 모든 질문에 답합니다.

결과는 일반적인 system_one 페이로드에 결정을 기록하는 routing 키를 더한 것입니다. Router 수준 on_predict_start / on_predict_end 훅은 전체 route+infer 호출을 감싸고 ctx.decision을 봅니다. laya.hooks를 참고하십시오. max_len / head_max_len은 이 호출에 대해 agent 토큰 예산을 재정의합니다(시작 훅이 ctx.max_len / ctx.head_max_len을 설정할 수 있습니다).

predict_long(
    state: Union[str, dict, list],
    questions: Dict[str, Any],
    model: Optional[str] = None,
    task: Optional[str] = None,
    lang: Optional[str] = None,
    lang_guess: Optional[Any] = None,
    window: Optional[int] = None,
    stride: Optional[int] = None,
    aggregate: str = "auto",
    batch_size: Optional[int] = None,
    hooks=None,
    on_predict_start=None,
    on_predict_end=None,
    hooks_raise: Optional[bool] = None,
    hooks_timeout: Optional[float] = None,
) -> Dict[str, Any]

라우팅한 다음, 상태의 첫 윈도만이 아니라 모든 윈도를 스캔합니다.

predict는 상태를 단일 윈도에서 채점합니다. max_len을 넘는 부분은 잘려나가고(첫 윈도, 대화 리스트의 경우 마지막 윈도) 모델에 결코 닿지 않습니다. 이 메서드는 predict와 정확히 같은 방식으로 라우팅하며 -- 같은 model/task/lang 힌트, 같은 router 수준 훅, 같은 routing 키와 usage -- 라우팅된 상태를 그 agent의 predict_long으로 채점합니다. 후자는 상태를 겹치는 윈도로 나누고 질문별로 집계합니다. 집계 규칙은 laya.agent.Agent.predict_long의 것입니다. noul은 가장 강한 윈도를, choice/score는 가장 확신하는 윈도를 취합니다.

호출별 훅(hooks, on_predict_start, on_predict_end, hooks_raise, hooks_timeout)은 predict를 감싸는 것과 정확히 같은 방식으로 전체 route+scan을 감쌉니다. 스캔이 마지막에 실행되므로 답하는(ctx.skip(...)) 시작 훅이나 상태를 재작성하는 시작 훅이 이깁니다. 여기서는 max_len / head_max_len을 받지 않습니다. 윈도 크기는 window 또는 체크포인트 예산으로 정해지며, 단일 윈도 잘림을 재정의하는 것이 바로 predict_long의 용도입니다.

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 schema 또는 pydantic 모델)에 대조해 답하고 타입화된 값을 반환합니다.

laya.structured를 참고하십시오. schema 또는 questions 중 정확히 하나만 전달하십시오. 추가 키워드 인수(예: model=, task=, hooks=)는 predict로 전달됩니다.

decide_batch(
    states: Sequence[Any],
    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=, model=, hooks=, ...)는 predict_batch로 전달됩니다. laya.structured를 참고하십시오.

route_batch(
    requests: Sequence[Dict[str, Any]],
    hooks_timeout: Optional[float] = None,
    hooks=None,
    hooks_raise: Optional[bool] = None,
) -> List[RouteDecision]

어떤 체크포인트도 로드하지 않고 이기종 요청 배치를 라우팅합니다.

각 요청은 state와 questions에 더해 :meth:route가 받는 것과 같은 선택적 라우팅 재정의인 model, task, lang, lang_guess를 가진 매핑입니다. 반환된 결정은 입력 순서를 보존합니다.

이는 추론과 의도적으로 분리되어 있어, 호출자가 모델 로드 비용을 치르기 전에 라우팅 결정을 검사하거나 집계할 수 있습니다.

predict_batch(
    requests: Sequence[Dict[str, Any]],
    batch_size: Optional[int] = None,
    hooks_timeout: Optional[float] = None,
    min_confidence: Optional[float] = None,
    sort_by_length: bool = False,
    hooks=None,
    on_predict_start=None,
    on_predict_end=None,
    hooks_raise: Optional[bool] = None,
) -> List[Dict[str, Any]]

최소한의 모델 전환으로 이기종 요청 배치를 라우팅하고 실행합니다.

요청은 먼저 라우팅되고 체크포인트별로 그룹화됩니다. 각 체크포인트 안에서, 같은 질문 스키마를 공유하는 요청들이 Agent.predict_batch로 전달되어 상태들이 forward 패스를 공유할 수 있습니다. 그런 다음 결과가 원래 요청 순서로 복원됩니다.

요청은 각각 model, task, lang, lang_guess, max_len, head_max_len을 독립적으로 지정할 수 있고 서로 다른 질문 스키마를 쓸 수도 있습니다. max_len / head_max_len은 predict가 호출 인수로 받는 토큰 예산 재정의의 요청별 형태입니다. 그것들은 그 하나의 요청에 대해 체크포인트의 상태 예산과 질문 헤드 예산을 설정하므로, 배치의 다른 요청들을 같은 윈도로 줄이지 않고도 넓은 질문을 할 수 있습니다. 다른 예산을 요구하는 요청들은 별도의 forward 패스로 나뉩니다. 하나의 Agent.predict_batch 호출은 모든 상태에 대해 하나의 예산을 나르기 때문입니다. 시작 훅은 여전히 ctx에서 두 값 중 하나를 대체할 수 있습니다.

Router 수준 예측 훅은 predict가 실행하는 것과 같이 요청마다 실행됩니다. 각 요청은 자기 PredictContext를 가지므로 on_predict_start가 그 요청의 상태, 질문 또는 토큰 예산을 대체하거나 ctx.skip(...)으로 건너뛸 수 있고, on_predict_end는 그 결과를 보고 대체할 수 있습니다. 요청은 각자의 시작 훅이 실행된 뒤에 forward 패스용으로 그룹화되며, 한 체크포인트 그룹의 요청들은 시작한 순서의 역순으로 끝납니다. 체크포인트 그룹이 실패하면, 시작 훅이 실행된 그룹의 모든 요청이 예외와 함께 실패합니다 -- 캐시 적중도 포함해서입니다. 각 요청은 예외가 전파되기 전에 on_error를, 그다음 on_predict_end를 받습니다.

RouteDecision()

라우팅 결과: 어떤 모델을, 왜, 무엇이 감지되었는지입니다.

딕셔너리처럼 동작하므로 API 응답으로 곧바로 직렬화됩니다.

DEFAULT_MODELS = {
    "english": (BUNDLE_REPO, None),
    "multilingual": (BUNDLE_REPO, "multilingual"),
    "typed-decisions": (BUNDLE_REPO, "typed-decisions"),
}