예측 훅

훅을 사용하면 Laya를 포크하지 않고도 Laya가 내리는 모든 결정을 관찰하거나 조정할 수 있습니다.

훅은 모든 실제 배포에 필요한 것들을 위한 확장 지점입니다. 감사 로깅, 추론 전 PII 마스킹, 캐싱, 메트릭, 신뢰도 게이팅, 라우팅 재정의, 그리고 결정을 외부 서비스로 전달하는 일입니다. 훅은 옵트인입니다. 훅을 구성하지 않으면 Agent, Router, ONNXAgent의 동작은 그대로입니다.

훅은 직접 호출에만 쓰이는 것이 아닙니다. LangChain 및 LangGraph 러너블은 각각 동일한 다섯 개의 호출별 인자를 받으므로, 전체 에이전트가 아니라 그래프의 한 노드에 훅을 붙일 수 있습니다.

이 폴더는 전체 참고 자료입니다. 여기에서 시작한 뒤 필요한 페이지로 들어가십시오.

페이지	내용
API 참고	모든 클래스, 필드, 매개변수, 기본값
수명 주기	각 훅이 실행되는 정확한 시점, 순서도 포함
오류	`hooks_raise`, `on_error`, 예외 연결, 실패 행렬
패턴과 안티 패턴	해야 할 것, 피해야 할 것, 그리고 그 이유
예제	모든 사용 사례를 위한 복사-붙여넣기 레시피
트레이싱	`run_id`, 스팬 상관관계, OpenTelemetry

빠른 시작

import laya

def log(ctx):
    print(ctx.model, ctx.results[0]["answers"], ctx.elapsed_ms)

agent = laya.load("convaiinnovations/laya", on_predict_end=log)
agent.system_one("I was charged twice.", {"urgent": {"type": "noul", "instructions": "Urgent?"}})

객체는 수명 주기 이벤트 중 임의의 부분 집합을 구현할 수 있습니다.

class Audit:
    def on_predict_start(self, ctx):
        print("start", ctx.run_id)

    def on_predict_end(self, ctx):
        print("end", ctx.run_id, ctx.usage, ctx.elapsed_ms)

    def on_error(self, ctx):
        print("failed", ctx.run_id, ctx.error)

laya.load("convaiinnovations/laya", hooks=[Audit()])

훅은 나중에 추가하거나 블록 범위로 한정할 수도 있습니다.

agent.add_hook(tracer)               # attach at runtime
with agent.hooks_installed(debug):   # installed for the block, removed on exit
    agent.system_one(state, questions)

런타임 등록을 참고하십시오. 모든 호출에 훅을 일일이 넘기지 않고 어디에나 적용하고 싶다면 프로세스 전역 기본값으로 한 번만 등록하십시오.

from laya import hooks

hooks.set_default_hooks(hooks=[Tracer()])

멘털 모델

세 가지 아이디어가 있습니다.

훅은 호출 가능 객체이거나 객체입니다. 하나의 이벤트에는 일반 함수가 편리하고, 여러 이벤트에는 객체가 편리합니다. 둘 다 hooks= / on_predict_start= / on_predict_end=에 전달됩니다.
한 호출의 모든 훅은 하나의 가변 PredictContext를 공유합니다. 이 컨텍스트는 상태, 질문, 결과, 라우팅 결정, 모델 이름, 사용량, 타이밍, 그리고 오류를 담습니다. 한 호출은 여러 상태를 한꺼번에 담을 수 있으므로(predict_batch), 모든 결정을 대상으로 하려는 훅은 ctx.states와 ctx.results를 순회해야 합니다. ctx.usage와 ctx.elapsed_ms는 호출 전체의 합계입니다. 컨텍스트가 가변이므로 훅은 호출을 지켜보기만 하는 것이 아니라 조정할 수 있습니다. 상태를 마스킹하고, 질문을 다시 쓰고, 결과를 교체하거나, 캐시된 답변으로 추론을 건너뛸 수 있습니다.
범위는 두 가지입니다. Agent 훅은 순전파를 감쌉니다. Router 훅은 라우팅과 추론을 감싸며 모델 수명 주기(on_route, on_load, on_evict)까지 볼 수 있습니다. 이는 다른 에이전트 프레임워크의 “run hooks” 대 “agent hooks” 구분과 대응합니다.

                             Router.predict(state, questions)
   ┌──────────────────────────────────────────────────────────────────────────┐
   │  route()                                                                 │
   │    ├─ detect language / workflow                                         │
   │    └─ on_route          ctx.decision  (a hook may replace it)            │
   │                                                                          │
   │  load(decision.model)                                                    │
   │    ├─ build checkpoint on first use ──► on_load    ctx.model, ctx.agent  │
   │    └─ evict LRU checkpoint ───────────► on_evict   ctx.model             │
   │                                                                          │
   │  on_predict_start       ctx.states, ctx.questions, ctx.decision          │
   │    │                                                                     │
   │    ├── ctx.skip(results)? ──► skip the forward pass                      │
   │    │                                                                     │
   │    └── Agent.system_one(...)  ──►  Agent-level hooks run here            │
   │           on_predict_start  ─►  forward  ─►  on_predict_end              │
   │                                                                          │
   │  result["routing"] = decision                                            │
   │  on_predict_end         ctx.results, ctx.usage, ctx.elapsed_ms           │
   └──────────────────────────────────────────────────────────────────────────┘
                 any failure on the way ──► on_error, then on_predict_end

범위 한눈에 보기

	`Agent` / `ONNXAgent`	`Router`
`on_predict_start`	예	예
`on_predict_end`	예	예
`on_error`	예	예
`on_route`	아니요	예
`on_load`	아니요	예
`on_evict`	아니요	예

laya.serve와 MCP 서버는 Router.predict를 호출하므로 Router 훅은 자동으로 실행됩니다. Agent 훅은 Router가 연결된 에이전트나 내장 에이전트를 실행할 때마다 실행됩니다.

호환성

훅을 구성하지 않으면 동작 변화가 없습니다. 미설정 경로는 회귀 테스트로 검증됩니다.
모든 훅 매개변수는 기본값이 있는 키워드 인자이므로 기존 호출은 계속 작동합니다.
laya/hooks.py는 순수 Python입니다. 이 때문에 import laya가 torch를 끌어오지 않습니다.
훅은 기본적으로 동기입니다. async def 이벤트는 AsyncHook으로 감싸거나 일반 비동기 호출 가능 객체로 전달할 수 있으며, 완료될 때까지 실행됩니다.
hooks_timeout은 느린 훅의 실행 시간을 제한하여 서빙 중인 요청을 붙잡아 두지 못하게 합니다.
훅은 빠르고 비블로킹으로 유지하십시오. laya.serve에 미치는 영향은 오류와 패턴을 참고하십시오.

함께 보기

examples/hooks/: 실행 가능한 감사, 마스킹, 캐시, 메트릭 훅.
tests/test_hooks.py: 동작 명세.
tests/test_hooks_api.py: API 안정성 가드.
laya/hooks.py: 구현.