모델 라우팅

모델 라우팅 (Model Routing)

사용자 메시지의 내용에 따라 요청을 다른 모델로 라우팅해요.

출처: 문서

본문

개요 (Overview)

모델 라우팅을 사용하면 사용자의 메시지에 따라 최적의 기본 모델을 자동으로 선택하는 "라우터" 모델을 정의할 수 있어요. 이것은 비용 최적화, 특화 처리, 모델 간 부하 분산에 유용해요.

Note 동작 원리 (How It Works) Docker Agent는 NLP 기반 텍스트 유사도(Bleve 전문 검색을 통해)를 사용해 사용자 메시지를 당신이 정의한 예제 문구와 일치시켜요. 예제와 가장 잘 일치하는 라우트가 이기고, 그 모델이 요청을 처리해요.

구성 (Configuration)

어떤 모델 정의에든 라우팅 규칙을 추가해요. 모델의 provider / model 필드가 어떤 라우트도 일치하지 않을 때의 폴백이 돼요:

models:
  smart_router:
    # Fallback model when no routing rule matches
    provider: openai
    model: gpt-5-mini

    # Routing rules
    routing:
      - model: anthropic/claude-sonnet-4-5
        examples:
          - "Write a detailed technical document"
          - "Help me architect this system"
          - "Review this code for security issues"
          - "Explain this complex algorithm"

      - model: openai/gpt-5
        examples:
          - "Generate some creative ideas"
          - "Write a story about"
          - "Help me brainstorm"
          - "Come up with names for"

      - model: openai/gpt-5-mini
        examples:
          - "What time is it"
          - "Convert this to JSON"
          - "Simple math calculation"
          - "Translate this word"

agents:
  root:
    model: smart_router
    description: Assistant with intelligent model routing
    instruction: You are a helpful assistant.

라우팅 규칙 (Routing Rules)

각 라우팅 규칙은 다음을 가져요:

Field Type Required Description
model string ✓ 대상 모델 (인라인 형식 또는 models 섹션 참조)
examples array ✓ 이 모델로 라우팅해야 하는 예제 문구

일치 동작 (Matching Behavior)

라우터는:

  • 대화에서 마지막 사용자 메시지 추출
  • 전문 검색을 사용해 모든 예제 검색
  • 라우트별로 일치 점수 집계 (라우트당 최고 점수 승리)
  • 전체 점수가 가장 높은 라우트 선택
  • 좋은 일치가 없으면 기본 모델로 폴백

Tip 좋은 예제 작성 (Writing Good Examples) 의도를 포착하는 다양한 문구 사용 사용자가 실제로 쓰는 키워드 포함 최상의 결과를 위해 라우트당 5-10개 예제 추가 예제는 정확한 일치일 필요 없어요 — 라우터는 의미적 유사도를 사용해요

사용 사례 (Use Cases)

비용 최적화 (Cost Optimization)

간단한 질의를 더 저렴한 모델로 라우팅:

models:
  cost_optimizer:
    provider: openai
    model: gpt-5-mini # Cheap fallback
    routing:
      - model: anthropic/claude-sonnet-4-5
        examples:
          - "Complex analysis"
          - "Detailed research"
          - "Multi-step reasoning"

특화 모델 (Specialized Models)

코딩 작업을 코드 특화 모델로 라우팅:

models:
  task_router:
    provider: openai
    model: gpt-5-mini # General fallback
    routing:
      - model: anthropic/claude-sonnet-4-5
        examples:
          - "Write code"
          - "Debug this function"
          - "Review my implementation"
          - "Fix this bug"
      - model: openai/gpt-5
        examples:
          - "Write a blog post"
          - "Help me with writing"
          - "Summarize this document"

부하 분산 (Load Balancing)

서로 다른 제공자의 동등한 모델 간에 부하 분산:

models:
  load_balancer:
    provider: openai
    model: gpt-5-mini
    routing:
      - model: anthropic/claude-sonnet-4-5
        examples:
          - "First request pattern"
          - "Another request type"
      - model: google/gemini-2.5-flash
        examples:
          - "Different request pattern"
          - "Alternative query style"

디버깅 (Debugging)

라우팅 결정을 보려면 디버그 로깅을 활성화해요:

$ docker agent run config.yaml --debug

다음 같은 로그 항목을 찾아보세요:

"Rule-based router selected model" router=smart_router selected_model=anthropic/claude-sonnet-4-5
"Route matched" model=anthropic/claude-sonnet-4-5 score=2.45

Warning 한계 (Limitations)

  • 라우팅은 마지막 사용자 메시지만 고려하며 전체 대화 컨텍스트는 고려하지 않아요
  • 매우 짧은 메시지는 잘 일치하지 않을 수 있어요 — 폴백을 신중히 고려하세요
  • 각 라우팅된 모델은 별도의 제공자 연결을 만듭니다

더 알아보기 (Learn more)