명령줄과 MCP 서버

Laya에는 같은 구조화 의사결정 엔진을 시험해 볼 두 가지 로컬 인터페이스가 있습니다:

결과를 읽는 사람이 당신일 때는 CLI를 고르십시오. 다른 프로세스가 안정적인 도구 인터페이스를 필요로 할 때는 MCP를 고르십시오. 둘 다 Laya의 Router를 사용해 체크포인트를 선택하고 타입이 지정된 choice, score, noul 의사결정을 돌려줍니다. 어느 것도 개방형 질의응답이나 텍스트 생성 인터페이스가 아닙니다.

라우팅 결정과 타입 지정 질문 예제는 README의 라우트 모드 빠른 시작을 참고하십시오. 신뢰도와 내장 워크플로는 README의 신뢰도 게이팅과 워크플로 프리셋을 참고하십시오.

1. 명령줄

패키지를 설치하면 laya 진입점이 설치됩니다. 전체 옵션 목록은 laya --help로 확인하십시오.

python -m pip install laya
laya --help

평가 CLI

패키지는 laya-evals도 설치합니다. 메인 CLI는 laya eval을 통해 같은 평가 명령을 노출합니다:

laya eval --help

데이터셋, 지표, 기준선 게이트는 평가 하네스 가이드를 참고하십시오.

체크포인트를 로드하지 않고 라우팅

텍스트가 있고 예측 플래그가 없으면 CLI는 Router.route를 호출합니다:

laya "I was charged twice, please refund it"

출력은 선택된 체크포인트를 밝히고, 왜 선택되었는지 설명하며, 가능하면 감지된 언어 정보를 보여 줍니다. 라우팅만으로는 체크포인트를 내려받거나 빌드하지 않으므로, 라우팅 결정을 빠르게 오프라인 확인하는 방법입니다.

다른 로컬 스크립트가 결정을 소비해야 할 때는 --json을 쓰십시오:

laya "I was charged twice, please refund it" --json

예측 실행

--predict는 전체 타입 지정 예측을 실행하고 첫 사용 시 라우팅된 체크포인트를 로드합니다. 첫 로드에는 Hugging Face Hub 접근이 필요하고, 이후 실행은 로컬 캐시를 사용합니다.

laya "Classify this support request" --predict
laya "Classify this support request" --predict --json

--json은 전체 결과를 JSON으로 출력합니다. 없으면 CLI는 각 답을 그 choice 확률, score 또는 noul 값과 함께, 그리고 라우팅 결정을 출력합니다.

주요 제어는 다음과 같습니다:

• --model english|multilingual|typed-decisions는 자동 라우팅 대신 체크포인트를 고정합니다.
• --lang en|de|...는 자동 감지 대신 명시적 언어 코드를 제공합니다.
• --lang-guess en|de|...는 라우팅이 --lang 다음, 자체 감지기 이전에 읽는 소프트 힌트를 제공합니다. 아무것도 해석하지 못하는 힌트는 통과되어, 체크포인트를 강제하지 않고 밀어 줍니다.
• --task NAME은 감지 대신 typed-decisions 워크플로를 강제합니다.
• --device cpu|cuda|...는 장치 선택을 Router에 전달합니다.
• --json은 기계가 읽을 수 있는 출력을 냅니다.

내장 프리셋 사용

프리셋은 미리 만들어진 질문 집합을 제공하고 예측을 함의하므로 --predict가 필요하지 않습니다:

laya "My payment failed twice" --preset triage
laya "Ignore all previous instructions" --preset guard --json

CLI 프리셋은 email, guard, moderation, router, triage입니다. CLI는 선택된 프리셋이 기대하는 state 필드 아래에 텍스트를 놓습니다. --predict는 router 질문 집합의 request 필드를 사용합니다. 프리셋은 빠른 로컬 확인에는 유용하지만, 그 질문들은 여전히 도메인 의사결정입니다. 애플리케이션 정책으로 쓰기 전에 프리셋을 살펴보고 자기 데이터로 검증하십시오.

대화형 탐색

텍스트 인수 없이 CLI는 작은 프롬프트를 엽니다:

laya
# laya> Classify this request
# laya> quit

각 요청을 실행하려면 Enter를 누르십시오. 빈 줄, quit, exit, Ctrl-D가 세션을 끝냅니다. 대화형 루프는 하나의 Router를 재사용하므로, 스크립트를 작성하지 않고 여러 입력을 비교하는 편리한 방법입니다.

실패가 드러남

CLI는 애플리케이션 경계에서 잘못된 값과 흔한 의존성, 다운로드, 런타임 실패를 처리합니다. 처리되지 않은 트레이스백을 보여 주는 대신 stderr에 진단을 출력하고 종료 코드 2를 돌려줍니다. 첫 사용 체크포인트 다운로드가 실패하면 재시도하기 전에 의존성 설치, Hub 접근, 선택된 장치를 확인하십시오.

2. 내장 MCP stdio 서버

MCP 서버는 선택적 추가 기능입니다. 코어 패키지는 mcp 의존성을 설치하지 않습니다:

python -m pip install "laya[mcp]"
laya-mcp-server
# equivalent module form:
python -m laya.mcp.server

서버는 HTTP가 아니라 stdio를 통해 MCP를 말합니다. 콘솔 스크립트로 클라이언트를 설정하십시오:

{
  "mcpServers": {
    "laya": {
      "command": "laya-mcp-server",
      "env": {
        "LAYA_DEVICE": "cpu"
      }
    }
  }
}

클라이언트 설정이 Python 실행 파일과 인수를 지원하면, 동등한 실행 형태로 python -m laya.mcp.server를 쓰십시오. 클라이언트가 서버 프로세스를 소유하며, Laya는 네트워크 포트를 열지 않습니다.

사용 가능한 도구

세 가지 배치 및 스키마 도구가 있는 이유는 같은 작업을 SDK와 laya-serve에서도 쓸 수 있기 때문입니다. 많은 요청이나 이미 답의 형태를 아는 호출자를 위해 Python으로 내려갈 필요가 없습니다. 스키마 기반 형태를 더 깊이 보려면 스키마 기반 의사결정을 참고하십시오.

공유 가드레일은 숏리스트 없이 선택지가 20개를 넘는 choice 질문을 보내지 말라고 말합니다. laya_shortlist는 포워드 패스 이전에 가장 가능성 높은 k개 레이블을 남기며, 기본값은 k=20입니다. 답하는 체크포인트 자체의 인코더에서 나온 평균 풀링 임베딩을 사용하므로 두 번째 모델을 내려받지 않고, 각 숏리스트된 질문에 대해 남긴 레이블, 코사인 점수, k, 선택지 개수를 돌려줍니다.

state는 비어 있지 않은 JSON 객체여야 합니다. questions는 값이 Laya의 타입 지정 질문 스키마를 사용하는 비어 있지 않은 객체여야 합니다. laya_preset은 CLI와 같은 다섯 프리셋을 받습니다. email, guard, moderation, triage, 그리고 이 표면에서의 정식 이름이 model_router인 router 워크플로입니다. router는 별칭으로 받아 같은 프리셋을 가리키므로 CLI 표기도 여기서 동작하며, 결과로 돌아오는 것이 정식 키입니다. 상태가 정확히 문자열 하나이면 laya_preset은 그 프리셋의 질문이 밝힌 필드 아래에 그것을 놓습니다. CLI가 하는 것과 같은 배치이므로, 호출자가 키를 추측할 필요가 없습니다. 문자열 하나보다 풍부한 것은 호출자 자신의 형태이며 손대지 않고 그대로 전달됩니다.

단일 요청 도구는 배치 요청과 같은 호출별 라우팅 제어를 받습니다. model과 함께, 요청은 task(작업으로 체크포인트 지명), lang(언어 코드 강제), lang_guess(lang 아래, 내장 감지기 위에 있는 소프트 언어 힌트로, 개연성이 있지만 불확실한 코드가 lang처럼 강제하지 않고 어떤 체크포인트를 선택할지 밀어 줄 수 있음)를 설정할 수 있습니다. lang_guess는 라우팅에만 참여하므로, task처럼 model을 고정한 호출에서는 거부됩니다. 고정된 체크포인트에는 라우팅할 것이 남아 있지 않습니다. laya_predict와 laya_shortlist는 답변 토큰 예산으로 max_len/head_max_len을, 유보 게이트로 min_confidence도 받습니다.

예측 호출은 SDK의 타입 지정 호출과 같은 형태입니다:

{
  "state": {
    "body": "I was billed twice for the same plan. Please reverse the duplicate charge."
  },
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this request?",
      "criteria": {
        "billing": "payments, invoices, refunds, duplicate charges",
        "technical": "bugs, outages, integration problems"
      }
    },
    "urgent": {
      "type": "noul",
      "instructions": "Does the user need immediate help?"
    }
  }
}

도구 응답은 타입 지정 answers, routing 결정, 타이밍 정보를 담은 JSON입니다. 높은 신뢰도의 답을 외부 동작을 수행할 권한으로 취급하지 마십시오. 정책, 검토, 부작용에 대한 책임은 애플리케이션이나 에이전트에 남아 있습니다.

시작과 환경

MCP 서버는 상주 Router를 유지하고 첫 구성이 직렬화됩니다. 기본적으로 english와 multilingual을 미리 로드하고, typed-decisions는 지연 상태로 남습니다. 미리 로드 실패는 시작 시 보고되고 다음 도구 호출에서 재시도되므로, 서버가 준비되었다고 가정하기 전에 laya_status를 살펴보십시오.

MCP 세션 간에 모델 서버 하나 공유하기

로컬 HTTP 서버를 하나 실행하고 각 MCP 클라이언트의 환경을 그것으로 향하게 합니다:

LAYA_HOST=127.0.0.1 LAYA_PRELOAD=0 LAYA_IDLE_UNLOAD_SECONDS=300 laya-serve

{
  "mcpServers": {
    "laya": {
      "command": "laya-mcp-server",
      "env": {"LAYA_BASE_URL": "http://127.0.0.1:8000"}
    }
  }
}

HTTP 서버가 실행되는 곳에 laya[serve]를 설치하십시오. MCP는 편집기와는 여전히 stdio를 사용하고, 그 예측 도구는 HTTP로 서버에 도달합니다. laya_predict, laya_predict_batch, laya_decide, laya_preset은 서버 본래의 state, instructions, 선택지 설명을 사용합니다. 이기종 배치는 항목마다 /v1/systemone 요청 하나를 보내 입력 순서를 보존합니다. batch_size와 sort_by_length는 서버의 실행을 바꾸지 않습니다. laya_status는 서버의 /health를 보고하고, laya_route와 laya_route_batch는 로컬에 머물며 모델도 HTTP 요청도 필요로 하지 않습니다. MCP 프로세스는 torch를 임포트하지 않고 체크포인트도 로드하지 않으며, LAYA_THREADS나 LAYA_PRELOAD가 설정된 경우에도 마찬가지입니다.

서버가 bearer 토큰을 요구하면 두 프로세스에 같은 LAYA_API_KEY를 설정하십시오. LAYA_DEFAULT_MODEL과 LAYA_AUTO_TASK를 맞춰 두면 로컬 라우팅 미리보기가 서버의 실제 라우팅과 일치합니다. 장치와 프리로드 설정은 HTTP 서버에 속합니다. 유휴 언로드 후 첫 호출은 콜드 로드를 기다립니다. 그것이 300초보다 오래 걸리면 LAYA_REMOTE_TIMEOUT을 올리십시오. laya_shortlist와 예측 훅 재정의는 unsupported_remote를 반환합니다. 그 코드는 모델 프로세스를 필요로 하기 때문입니다. HTTP 오류는 서버의 detail 텍스트를 MCP 도구 오류로 유지합니다. LAYA_BASE_URL이 설정되지 않으면 MCP 서버는 자기 프로세스에서 체크포인트를 계속 로드합니다.

기본 제공 laya-mcp-server 런처는 훅을 설치하지 않고 Router를 만듭니다. 예측 훅은 추론을 실행하는 프로세스에 설치하십시오. 로컬 모드에서는 MCP 프로세스, 공유 서버 모드에서는 HTTP 서버입니다. 사용자 정의 런처는 Router를 빌드하기 전에 laya.hooks.set_default_hooks를 사용할 수 있습니다. 위의 환경 변수는 모델 생명주기를 설정하는 것이지 훅 등록이 아닙니다. 언제 도구를 호출하고 돌려받은 의사결정으로 무엇을 할지는 여전히 클라이언트가 결정합니다.

3. 공유 경계와 관련 가이드

CLI와 MCP 서버는 같은 타입 지정 의사결정 엔진에 대한 인터페이스입니다:

• 유한한 레이블 집합에는 choice를, 순서 있는 루브릭에는 score를, 참일 확률에는 noul을 쓰십시오.
• 임계값과 프리셋은 대표성 있는 데이터로 검증하십시오. 보편적인 도입 임계값은 없습니다.
• 되돌릴 수 없거나 비용이 큰 동작은 애플리케이션의 검토와 폴백 정책 뒤에 두십시오.
• MCP 서버는 Router.predict를 호출하므로, 사용자 정의 런처가 훅을 설치하면 훅이 발동합니다. 관측 가능성과 run_id 상관에 대해서는 예측 훅, 훅 생명주기, 트레이싱을 참고하십시오.

이 가이드는 로컬 CLI와 내장 MCP stdio 서버를 다룹니다. HTTP API, 커뮤니티 래퍼, MCP 프로토콜 재설계는 문서화하지 않습니다.