OmniRoute Auto-Combo Engine (한국어)

2. cost / eco — 가장 저렴하고 정상 상태인 공급자

후보 풀을 costPer1MTokens 기준으로 오름차순 정렬하고 가장 저렴한 후보를 선택합니다. 먼저 OPEN 상태인 후보를 필터링합니다.

class CostStrategyImpl implements RouterStrategy {
  readonly name = "cost";
  readonly description = "Always selects cheapest available provider";

  select(pool, context) {
    const healthy = pool.filter((c) => c.circuitBreakerState !== "OPEN");
    const sorted = [...healthy].sort((a, b) => a.costPer1MTokens - b.costPer1MTokens);
    return { provider: sorted[0].provider /* ... */ };
  }
}

사용 시점: 비용에 민감한 워크로드, 배치 처리 또는 백그라운드 작업에 사용합니다.

별칭: cost, eco

---

3. latency / fast — 신뢰성 페널티를 반영한 가장 낮은 p95 지연 시간

p95LatencyMs + (errorRate * 1000)을 기준으로 정렬합니다. 오류율 페널티를 적용하여 명목상 지연 시간이 짧더라도 신뢰할 수 없는 제공자는 더 낮은 순위에 배치됩니다.

class LatencyStrategyImpl implements RouterStrategy {
  readonly name = "latency";
  readonly description = "Prioritizes lowest p95 latency with reliability weighting";

  select(pool, context) {
    const healthy = pool.filter((c) => c.circuitBreakerState !== "OPEN");
    const sorted = [...healthy].sort(
      (a, b) => a.p95LatencyMs + a.errorRate * 1000 - (b.p95LatencyMs + b.errorRate * 1000)
    );
    return { provider: sorted[0].provider /* ... */ };
  }
}

사용 시점: 실시간 채팅, 자동 완성 또는 대화형 코딩 어시스턴트와 같이 지연 시간에 민감한 워크로드.

별칭: latency, fast

---

4. sla-aware / sla — 지연 시간/오류/비용 SLO 준수

구성된 SLO 정책을 각 후보가 얼마나 잘 충족하는지에 따라 점수를 산정합니다.

요소	가중치	공식
지연 시간 점수	35%	threshold / max(value, ε)
오류 점수	35%	threshold / max(value, ε)
상태 점수	15%	1.0 (CLOSED) / 0.5 (HALF_OPEN) / 0.0 (OPEN)
비용 점수	10%	threshold / max(value, ε) 또는 역정규화
안정성 점수	5%	지연 시간 표준 편차의 역정규화

hardConstraints: true인 경우 후보는 먼저 위반 점수 (SLO를 초과한 정도)를 기준으로 정렬된 다음, 종합 점수를 기준으로 정렬됩니다. 그렇지 않으면 종합 점수만 사용합니다.

class SLAStrategyImpl implements RouterStrategy {
  readonly name = "sla-aware";
  readonly description =
    "Selects the provider most likely to satisfy latency, error-rate, and cost SLOs";

  select(pool, context) {
    // 정책에 따라 각 후보의 점수를 산정합니다: { targetP95Ms, maxErrorRate, maxCostPer1MTokens, hardConstraints }
  }
}

SLA 필드(콤보 구성에 설정):

{
  "strategy": "auto",
  "config": {
    "routerStrategy": "sla-aware",
    "slaTargetP95Ms": 1500,
    "slaMaxErrorRate": 0.05,
    "slaMaxCostPer1MTokens": 5,
    "slaHardConstraints": true
  }
}

사용 시점: 지연 시간, 오류율 또는 비용 예산이 엄격한 프로덕션 워크로드.

별칭: sla-aware, sla

---

5. lkgp — 마지막으로 정상 동작한 제공자를 우선 사용

설정되어 있는 경우 마지막으로 정상 동작한 제공자를 먼저 시도한 다음, rules 전략으로 폴백합니다. 세션 고정성에 유용하며, 대화의 후속 요청을 동일한 제공자가 처리하도록 합니다.

class LKGPStrategyImpl implements RouterStrategy {
  readonly name = "lkgp";
  readonly description = "Tries last known good provider first, then falls back to rules";

  select(pool, context) {
    if (context.lkgpEnabled === false) {
      return getStrategy("rules").select(pool, context);
    }

    if (context.lastKnownGoodProvider) {
      const candidates = pool.filter(
        (c) => c.provider === context.lastKnownGoodProvider && c.circuitBreakerState !== "OPEN"
      );
      if (candidates.length > 0) {
        return { provider: candidates[0].provider /* ... */ };
      }
    }

    // rules 전략으로 폴백
    return getStrategy("rules").select(pool, context);
  }
}

사용 시점: 동일한 제공자가 후속 요청을 처리하도록 하려는 멀티턴 대화(예: 캐싱, 컨텍스트 연속성 또는 가격 일관성을 위해).

별칭: lkgp(별도의 별칭 없음)

---

사용자 지정 라우터 전략

공개 API를 통해 자체 RouterStrategy 구현을 등록할 수 있습니다.

import {
  registerStrategy,
  type RouterStrategy,
} from "@omniroute/open-sse/services/autoCombo/routerStrategy";

class MyCustomStrategy implements RouterStrategy {
  readonly name = "my-custom";
  readonly description = "My custom routing strategy";

  select(pool, context) {
    // 여기에 라우팅 로직을 작성합니다
    return {
      provider: pool[0].provider,
      model: pool[0].model,
      strategy: this.name,
      reason: "MyCustomStrategy: ...",
      candidatesConsidered: pool.length,
      finalScore: 1.0,
    };
  }
}

registerStrategy("my-custom", new MyCustomStrategy());

그런 다음 다음과 같이 사용합니다.

{
  "strategy": "auto",
  "config": {
    "routerStrategy": "my-custom"
  }
}

---

라우터 전략 선택 가이드

사용 사례	전략	이유
균형 잡힌 워크로드	rules	기본값 — 모든 요소를 고려
비용 최소화	cost	항상 가장 저렴한 옵션 선택
지연 시간 최소화	latency	가장 빠르고 신뢰할 수 있는 제공자 선택
엄격한 SLO	sla-aware	p95/오류/비용 임계값으로 필터링
멀티턴 채팅	lkgp	세션 고정성

SLA 인식 필드:

{
  "strategy": "auto",
  "config": {
    "routerStrategy": "sla-aware",
    "slaTargetP95Ms": 1500,
    "slaMaxErrorRate": 0.05,
    "slaMaxCostPer1MTokens": 5,
    "slaHardConstraints": true
  }
}

작업 적합도

6가지 작업 유형(coding, review, planning, analysis, debugging, documentation)에 걸쳐 30개 이상의 모델에 점수가 부여됩니다. 와일드카드 패턴도 지원합니다(예: *-coder → 높은 코딩 점수).

자동 변형 요약

기본 auto와 autoPrefix.ts에 선언된 6개의 AutoVariant 값을 포함하면, 호출 가능한 모델 ID는 7개입니다.

auto, auto/coding, auto/fast, auto/cheap, auto/offline, auto/smart, auto/lkgp

(AutoVariant 자체는 6개의 값을 열거합니다. 7번째 옵션은 “변형 없음”을 의미하는 기본 auto이며, parseAutoPrefix()에서 variant: undefined로 처리됩니다.)

티어가 Auto-Combo에 적용되는 방식

16개 요소로 구성된 점수 산정 함수(open-sse/services/autoCombo/scoring.ts)는 티어 소속 여부를 tierPriority(0.0476)와 tierAffinity(0.0476)라는 두 가지 신호로 처리합니다. 전체 DEFAULT_WEIGHTS 세트는 위의 표준 점수 산정 요소 표를 참조하세요. 팩별 재정의(ship-fast/cost-saver/quality-first/ offline-friendly)는 “팩별 가중치 프로필” 표에 나와 있습니다.

티어만으로는 Tier 1이 먼저 선택되도록 강제되지 않습니다. Tier 1의 지연 시간이 길거나 비용 대비 품질이 최적이 아닌 경우 Tier 2가 선택됩니다. 티어 순서를 강제하려면 콤보 전략 priority를 사용하고 공급자를 티어 순서에 따라 배치하세요.

Tier 1(구독)을 강하게 선호하려면 tierPriority 가중치를 높이세요.

{
  "strategy": "auto",
  "config": { "auto": { "weights": { "tierPriority": 0.3, "costInv": 0.05 } } }
}

티어 정의와 공급자 분류는 docs/marketing/TIERS.md를 참조하세요.

테스트 및 커버리지

결정론적 라우팅 결정 매트릭스(npm run test:combo:matrix)

tests/integration/combo-matrix/*.test.ts는 모의 업스트림을 사용하는 실제 콤보 파이프라인을 통해 19개의 모든 공개 전략에 대한 라우팅 결정을 엔드투엔드로 검증합니다. 커버리지에는 다음이 포함됩니다.

• 19개의 모든 ROUTING_STRATEGY_VALUES 전략(ordered, weighted, cost, context, fusion, …).
• quota-share(내부) 엔드투엔드: 실제 selectQuotaShareTarget 연결 지점(registerQuotaFetcher / setLKGP / __setHeadroomSaturationFetcherForTests)을 통한 DRR 공정성 및 포화 상태 우선순위 하향 조정.
• 모든 대상 수에 대한 context-relay 범용 핸드오프 커버리지.

이 테스트 모음은 결정론적 동작을 보장하고 실제 자격 증명이 필요하지 않도록 --test-concurrency=1 및 --test-force-exit 옵션과 함께 CI(test:integration 작업)에서 실행됩니다.

조건부 실제 스모크 테스트(CI에서는 실행하지 않음 — 실제 공급자)

명령어	수행 내용
npm run test:combo:live	RUN_COMBO_LIVE=1을 사용하는 프로세스 내 실제 라우팅. 실제 OmniRoute DB의 스냅샷을 생성
npm run test:combo:live:vps	실제 OmniRoute 서버에 HTTP 요청 전송(COMBO_LIVE_BASE_URL 설정)
npm run test:combo:live:vps:failover	의도적인 장애 조치 시나리오를 포함해 동일하게 수행

이러한 스모크 테스트는 실제 통신 경로(콤보 → 공급자 → 완성)를 검증합니다. 실제 자격 증명과 VPS 액세스가 필요하므로 의도적으로 CI에서 제외됩니다.

---

파일

파일	용도
open-sse/services/autoCombo/scoring.ts	16개 요소 점수 계산 함수, DEFAULT_WEIGHTS, 풀 정규화
open-sse/services/autoCombo/taskFitness.ts	모델 × 작업 적합도 조회
open-sse/services/autoCombo/engine.ts	선택 로직, 밴딧, 예산 상한
open-sse/services/autoCombo/selfHealing.ts	제외, 프로브, 인시던트 모드
open-sse/services/autoCombo/modePacks.ts	6개 가중치 프로필(ship-fast, cost-saver, quality-first, offline-friendly, reliability-first, chaos-mode)
open-sse/services/autoCombo/autoPrefix.ts	auto/ 접두사 파서 + 6개 변형
open-sse/services/autoCombo/virtualFactory.ts	활성 연결에서 인메모리 AutoComboConfig 구성
open-sse/services/autoCombo/providerRegistryAccessor.ts	제공자 레지스트리를 모킹하기 위한 테스트 훅
src/shared/constants/routingStrategies.ts	ROUTING_STRATEGY_VALUES(19개 전략)
src/sse/handlers/chat.ts	통합: auto-prefix 단락 평가

---

OmniRoute 소스 코드 (a58000c7685f)