조건부 라우팅 (Conditional Routing)

조건부 라우팅 (Conditional Routing)

모든 요청을 같은 모델로 보낸다면, 비싼 모델이 가벼운 질문까지 처리하는 낭비가 생겨요. Portkey 게이트웨이는 우리가 정의한 조건에 따라 서로 다른 프로바이더·모델로 요청을 나눠 보내 줘요. 예를 들어 temperature 파라미터가 0.7을 넘으면 더 창의적인 모델로 보내는 식이에요. 이렇게 하면 앱 코드는 건드리지 않고 라우팅 정책만 바꿔 비용과 품질을 조절할 수 있어요.

출처: Portkey Conditional Routing 공식 문서

컨피그 만들기

조건부 라우팅은 게이트웨이 컨피그의 한 전략이에요(다른 전략으로는 fallback, loadbalance가 있어요). 사용 흐름은 이렇게 돼요.

  1. Portkey UI에서 conditional 컨피그를 만든다.
  2. 저장해서 Config ID를 얻는다.
  3. 요청에 config 파라미터로 그 ID를 전달한다.

기본 구조는 strategy(모드와 조건 배열, default 대상), 그리고 여러 targets로 이뤄져요. 각 대상은 고유한 name과 프로바이더 정보를 갖고, 이 이름을 조건 객체에서 참조해요.

{
  "strategy": {
    "mode": "conditional",
    "conditions": [],
    "default": "target_1"
  },
  "targets": [
    { "name": "target_1", "provider": "@xx" },
    { "name": "target_2", "provider": "@yy" }
  ]
}

조건 쿼리 작성 규칙

  • 쿼리 경로: metadata.<key>, params.<key>, url.pathname을 지원해요. 두 세그먼트 키만 지원되니 metadata.user_plan, params.model 같은 형태만 되고, metadata.features.x처럼 중첩된 경로는 안 돼요.
  • 논리 연산자: $and, $or로 중첩 쿼리를 쓸 수 있어요.
  • 조건이 false 또는 잘못된 형태면 다음 조건으로 넘어가요.
  • 모든 조건이 통과하지 못하면 default 대상으로 가요.
  • 조건은 순서대로 평가되므로 순서가 중요해요.
  • 참조한 키가 없으면 에러를 내지 않고 조건을 false로 처리해요.

파라미터 기반 라우팅

model, temperature, max_tokens처럼 요청의 어느 파라미터로든 라우팅할 수 있어요. 파라미터 값으로 모델 별칭을 써서 특정 모델 이름을 직접 적지 않게 하는 것도 가능해요.

{
  "strategy": {
    "mode": "conditional",
    "conditions": [
      { "query": { "params.model": { "$eq": "fastest" } }, "then": "fastest-model-target" }
    ],
    "default": "smartest-model-target"
  },
  "targets": [
    { "name": "smartest-model-target", "provider": "@anthropic-prod", "override_params": { "model": "claude-3.5-sonnet" } },
    { "name": "fastest-model-target", "provider": "@oai-vk", "override_params": { "model": "gpt-4o-mini" } }
  ]
}

이 컨피그를 쓰면 model="smartest" 요청은 claude-3.5-sonnet으로, model="fastest" 요청은 gpt-4o-mini로 자동 라우팅돼요.

메타데이터 기반 라우팅

요청에 커스텀 메타데이터를 보내면 그 값으로도 라우팅할 수 있어요. $and/$or로 여러 조건을 묶으면 더 정밀해져요.

{
  "strategy": {
    "mode": "conditional",
    "conditions": [
      {
        "query": {
          "$and": [
            { "metadata.user_type": { "$eq": "pro" } },
            { "metadata.user_tier": { "$eq": "tier-1" } }
          ]
        },
        "then": "gpt4_v2_target"
      }
    ],
    "default": "default_target"
  }
}

조건 조합하기

메타데이터와 요청 파라미터를 함께 조건으로 쓰는 것도 가능해요.

{
  "strategy": {
    "mode": "conditional",
    "conditions": [
      {
        "query": {
          "$and": [
            { "metadata.user_tier": { "$eq": "enterprise" } },
            { "params.temperature": { "$gte": 0.7 } }
          ]
        },
        "then": "premium-creative-target"
      }
    ],
    "default": "default-target"
  }
}

더 알아보기 (Learn more)