라우팅

Router는 요청마다 체크포인트를 고르고, 예측이 필요로 할 때 그 Agent를 로드합니다. 기본 라우터는 영어 텍스트를 영어 체크포인트로, 나머지 지원 언어를 다국어 체크포인트로 보냅니다. 이 선택을 덮어쓰거나, 직접 언어 힌트를 제공하거나, typed-decisions 체크포인트를 명시적으로 선택할 수 있습니다.

이 가이드는 모델 선택과 수명 주기를 다룹니다. 예측이 받아들이는 질문 유형은 스키마 기반 의사결정을, 수명 주기 콜백은 예측 훅을 참고하십시오.

빠른 시작

from laya import Router

router = Router()

questions = {
    "department": {
        "type": "choice",
        "instructions": "Which department should handle this request?",
        "criteria": {
            "billing": "invoices, payments, refunds",
            "technical": "bugs, outages, system errors",
            "other": "everything else",
        },
    }
}

result = router.predict("We were billed twice. Please refund the duplicate charge.", questions)
print(result["answers"]["department"]["choice"])
print(result["routing"]["model"])

Router() 생성은 기본적으로 체크포인트를 다운로드하지 않습니다. predict()는 요청을 라우팅한 다음, 처음 사용할 때 선택된 체크포인트를 로드합니다. 따라서 첫 예측은 파일을 다운로드하고 모델을 초기화하는 동안 더 오래 걸릴 수 있습니다. 이후 예측은 로드된 에이전트를 재사용합니다.

체크포인트가 선택되는 방식

Router.route(state, questions, ...)는 체크포인트를 로드하거나 추론을 실행하지 않고 RouteDecision을 반환합니다. 이 결정에는 선택된 모델, 사람이 읽을 수 있는 이유, 그리고 내장 감지를 사용한 경우의 언어 감지 세부 정보가 담깁니다.

라우팅은 다음 순서로 입력을 확인합니다.

model=은 체크포인트를 직접 선택합니다.
task=는 지정된 작업의 체크포인트를 선택합니다.
auto_task_detection=True이면, 알려진 typed-decisions 질문 ID 집합 중 하나와 정확히 일치할 때 typed-decisions를 선택합니다.
인식된 lang= 값은 영어 또는 다국어를 선택합니다.
호출별 lang_guess= 또는 라우터에 설정된 lang_guess가 참조됩니다.
내장 문자 체계 및 언어 분석이 체크포인트를 선택합니다. 신뢰할 만한 언어 신호가 없으면 라우터는 설정된 default(기본값은 영어)를 사용합니다.

처음 일치하는 규칙이 이깁니다. 예를 들어 model="multilingual"은 lang="en"을 덮어씁니다. 잘못된 모델 이름은 감지로 넘어가지 않고 ValueError를 발생시킵니다.

decision = router.route(
    "La aplicación se cierra cada vez que abro la configuración.",
    questions,
)
print(decision.model)   # multilingual
print(decision.reason)  # why that checkpoint was selected

RouteDecision은 dict 호환이므로, 그 필드는 decision["model"]과 decision["reason"] 같은 키로도 사용할 수 있습니다. Router.predict()는 같은 결정을 결과의 "routing" 키 아래에 포함시킵니다.

언어 라우팅 덮어쓰기

애플리케이션이 이미 요청 언어를 알고 있다면 lang=을 사용하십시오. "en", "en-US", "en_US.UTF-8" 같은 언어 태그를 받습니다. 영어는 english로, 다른 인식된 언어 코드는 multilingual로 라우팅됩니다.

result = router.predict(state, questions, lang="de")
assert result["routing"]["model"] == "multilingual"

애플리케이션에 자체 언어 감지기가 있다면, 그 결과를 언어 코드로 lang_guess=에 전달하십시오. 호출 가능 객체는 상태를 받아 코드를 반환하거나, 기권을 나타내는 None을 반환할 수 있습니다:

def detect_request_language(state):
    # Replace this with the application's detector.
    return "en" if "invoice" in str(state).lower() else None

router = Router(lang_guess=detect_request_language)

기권하는 힌트는 체크포인트를 강제하지 않습니다. 라우팅은 다음 규칙으로 넘어갑니다. 여기에는 None, 빈 문자열, 그리고 어떤 언어도 지명하지 않는 코드(C, POSIX, C.UTF-8, und, zxx, mul)가 포함됩니다. 이들은 감지기가 할 말이 없을 때 반환하는 값이므로, 기권이 요청을 잘못된 모델에 조용히 고정시키는 일은 없습니다.

인식되지 않는 힌트는 기권이 아닙니다. "xx", False, 0을 포함한 다른 모든 값은 “영어 아님”으로 읽혀 다국어 체크포인트로 라우팅됩니다. 따라서 None 대신 잘못된 코드를 반환하는 감지기는 실제로 체크포인트를 선택하며, 그것이 중요하다면 전달하기 전에 그 알 수 없는 경우를 None으로 매핑하십시오.

내장 감지는 가벼운 문자 체계 및 언어 휴리스틱이고, 범용 언어 식별 모델이 아닙니다. text, dict, list 상태의 문자열 값을 분석합니다. 사전 키는 흔히 영어 필드 이름이므로 무시됩니다. 짧거나 모호한 텍스트는 기본 체크포인트를 사용할 수 있습니다. 알려진 워크로드에서는 명시적 언어나 애플리케이션이 제공한 힌트가 더 예측 가능합니다.

typed-decisions 선택

typed-decisions 체크포인트는 기본적으로 자동 선택되지 않습니다. 명시적으로 선택하십시오:

result = router.predict(state, questions, model="typed-decisions")
# `task="typed_decisions"` is also accepted.

또는 auto_task_detection=True를 설정하십시오. 그러면 라우터는 질문 ID가 알려진 typed-decision 워크플로 중 하나와 정확히 일치하는지 확인합니다. 질문 문구로부터 작업을 추론하지 않으며, 관련 없는 질문 ID를 추가하면 정확한 일치가 성립하지 않습니다.

router = Router(auto_task_detection=True)

모델을 로드하지 않고 라우팅 검사

단일 결정을 검사하려면 route()를, 일련의 결정을 검사하려면 route_batch()를 사용하십시오. 두 메서드 모두 체크포인트를 로드하지 않으므로, 추론을 실행하기 전에 라우팅 규칙을 디버깅하는 데 유용합니다.

requests = [
    {"state": "Please refund the duplicate charge.", "questions": questions},
    {"state": "Necesito ayuda con mi factura.", "questions": questions},
]

decisions = router.route_batch(requests)
for decision in decisions:
    print(decision.model, decision.reason)

route_batch()의 각 항목에는 state와 questions가 필요합니다. 선택적 라우팅 덮어쓰기(model, task, lang, lang_guess)는 항목별로 지정합니다. 결정은 입력 순서를 유지합니다.

로딩과 메모리

기본적으로 라우터는 처음 필요할 때 체크포인트를 로드하고, 최대 두 개의 에이전트를 상주시킵니다. 자동 언어 라우팅은 보통 영어와 다국어 체크포인트만 필요로 합니다. 요청이 typed-decisions도 선택할 수 있다면, 작은 max_loaded가 다른 에이전트를 밀어내어 다음에 필요할 때 다시 로드하게 만들 수 있습니다.

# Load only the checkpoints this process serves, before accepting requests.
router = Router()
router.preload(["english", "multilingual"])

print(router.loaded)  # currently resident checkpoint names
router.unload("multilingual")

Router(preload=True)는 설정된 모든 체크포인트를 미리 로드합니다. 미리 로딩은 요청된 집합에 맞도록 상주 모델 한도를 높입니다. 미리 로드하지 않고 세 개의 체크포인트로 이루어진 워크로드를 제어하려면 max_loaded=3을 설정하십시오. 에이전트 하나를 해제하려면 unload()를, 전부 해제하려면 router.unload()를 사용하십시오. 컨텍스트 관리자로 사용되는 라우터는 블록을 빠져나갈 때 에이전트를 해제합니다:

with Router(preload=True) as router:
    result = router.predict(state, questions)

라우터를 생성할 때 device="cpu", device="cuda" 또는 다른 지원되는 PyTorch 장치를 전달할 수도 있습니다. 어떤 장치가 주어진 모델을 실행할 수 있는지는 가용성과 메모리가 결정합니다.

혼합 배치

predict_batch()는 상태, 모델, 언어, 질문 스키마가 서로 다른 요청을 받습니다. 라우터는 먼저 요청마다 결정을 내리고, 체크포인트와 호환되는 질문 스키마로 작업을 묶은 다음, 결과를 원래 입력 순서로 되돌립니다.

requests = [
    {"state": "Please refund the duplicate charge.", "questions": questions},
    {"state": "Mi cuenta fue cobrada dos veces.", "questions": questions},
    {"state": "A third request", "questions": questions, "model": "typed-decisions"},
]

results = router.predict_batch(requests, batch_size=8)

각 요청에는 state와 questions가 필요합니다. model, task, lang, lang_guess도 포함할 수 있습니다. 체크포인트와 질문 스키마를 공유하는 요청은 하나의 Agent 배치 순전파를 공유할 수 있습니다. 서로 다른 스키마나 체크포인트는 별도 그룹에서 처리됩니다. batch_size는 한꺼번에 Agent에 전달하는 상태 수를 제한합니다. 결과는 여전히 요청 순서에 대응합니다.

진입점 선택

모델을 로드하지 않고 결정을 검사해야 할 때는 route() 또는 route_batch()를 사용하십시오.
단일 요청에는 predict()를, 여러 개의, 이질적일 수 있는 요청에는 predict_batch()를 사용하십시오.
애플리케이션이 이미 체크포인트 하나를 골라 로드했고 자동 라우팅이 필요 없다면 Agent를 직접 사용하십시오.

생성자와 메서드의 세부 정보는 Router API 참조를 참고하십시오.