Maslul: LLM 요청을 최적의 모델로 라우팅하는 파이썬 라이브러리

섹션별 상세

라우팅 및 정규화: 요청마다 모델을 하드코딩하는 대신, Maslul은 요청을 난이도 티어(Simple, Medium, Hard)로 분류하여 적절한 모델로 자동 라우팅한다. 또한 Anthropic, Gemini, Grok, OpenAI 등 다양한 공급자의 SDK를 단일 Request/Response 형태로 정규화하여 일관된 개발 경험을 제공한다.

python

import asyncio
from maslul import Router, Request, Message

router = Router.from_toml("maslul.toml")

async def main() -> None:
    resp = await router.complete(Request(messages=[Message(role="user", content="Hello!")]))
    print(resp.text, "·", resp.level_used, "·", resp.usage.output_tokens, "tokens")

asyncio.run(main())

Maslul 라우터를 초기화하고 요청을 처리하는 기본 예시 코드

근거

요청 난이도에 따라 모델을 동적으로 라우팅하여 비용과 성능을 최적화할 수 있다. — Routing Difficulty 섹션

임베딩 라이브러리 구조: 별도의 서버나 프록시를 실행하는 게이트웨이 방식과 달리, 애플리케이션 내부에 직접 임베딩되는 라이브러리 형태로 동작한다. 이를 통해 인프라 복잡도를 낮추고, 도구 사용(Tool use)이나 구조화된 출력(Structured output) 등 복잡한 기능을 공급자 구분 없이 동일한 코드로 실행한다.

python

async def get_weather(call: ToolCall) -> str:
    return f"18°C in {call.input['city']}"

req = Request(
    messages=[Message(role="user", content="Weather in Paris?")],
    tools=[ToolDef(name="get_weather", description="Current weather for a city.", input_schema={"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]})],
    tool_executor=get_weather,
)

Maslul을 사용하여 도구(Tool)를 정의하고 실행하는 예시 코드

근거

Maslul은 서버나 프록시 없이 애플리케이션에 직접 임베딩되는 라이브러리이다. — How it compares 섹션

유연한 라우팅 전략: route_default, classify, classify_and_answer, verify_cascade 등 다양한 전략을 지원하여 비용과 성능 사이의 균형을 맞춘다. 특히 classify_and_answer 전략은 분류 모델이 직접 답변하거나 에스컬레이션 신호를 보내는 방식을 통해 호출 횟수를 최적화한다.

장애 복구 및 캐싱: 일시적인 오류 발생 시 지수 백오프(Exponential backoff)를 포함한 재시도 로직을 수행하며, 지속적인 실패 시 더 높은 티어의 모델로 에스컬레이션하는 교차 공급자 장애 복구 기능을 지원한다. 또한, 동일하거나 유사한 요청에 대해 캐시된 응답을 반환하여 API 비용을 절감한다.

용어 해설

LLM 라우터(LLM Router): — LLM 요청의 특성을 분석하여 가장 적합한 모델로 전달하는 시스템이다. 비용 절감과 성능 최적화를 위해 요청의 난이도에 따라 모델을 동적으로 선택하는 역할을 수행한다.
구조화된 출력(Structured Output): — LLM이 자연어 대신 JSON 등 정해진 스키마 형식으로 응답하도록 강제하는 기능이다. 데이터 파싱과 후처리를 자동화하는 데 필수적이다.
도구 사용(Tool Use): — LLM이 외부 API나 함수를 호출하여 정보를 검색하거나 작업을 수행하는 능력이다. 에이전트 시스템의 핵심 요소로, 모델의 기능을 확장한다.
지수 백오프(Exponential Backoff): — 네트워크 오류나 API 제한 발생 시 재시도 간격을 지수적으로 늘려 서버 부하를 방지하는 알고리즘이다. 안정적인 API 연동을 위해 필수적이다.

기술

Python
Anthropic
Gemini
Grok
OpenAI
TOML

활용 사례

LLM 비용 최적화
교차 공급자 장애 복구
통합 LLM 인터페이스 구축

언급된 리소스

GitHubMaslul GitHub Repository