Go Report Card

Go Reference

License

Join Slack

FOSSA Status

llm-d Router

[!IMPORTANT]
용어 변경: Inference Scheduler는 llm-d Router로 이름이 변경되었습니다. 자세한 내용은 Terminology를 참조하세요.

[!IMPORTANT]
API 및 코드 통합: Core Endpoint Picker (EPP) 코드는 그리고 InferenceObjective와 InferenceModelRewrite API가 Gateway API Inference Extension (GIE)에서 이 리포지토리로 병합되었습니다. GIE 리포지토리는 이제 InferencePool API—Kubernetes Gateway API의 확장 기능—만을 전용으로 호스팅하며, Endpoint Picker Protocol을 정의합니다.

llm-d Router는 추론 트래픽을 위한 지능형 진입점(entry point)이며, LLM 부하 및 접두사 캐시 인식 라우팅(prefix-cache aware routing), 요청 우선순위 지정(request prioritization), 그리고 복잡한 서비스 목표를 달성하기 위해 다양한 요청 형식을 통한 고급 흐름 제어(advanced flow control)를 제공합니다. 이 라우터는 유연한 배포 모델을 지원합니다: 자체 관리형 Envoy 프록시가 EPP와 함께 또는 별도의 서비스로 실행되는 Standalone Mode에서 작동하거나, Kubernetes Gateway API를 통해 자체 관리형 인스턴스(예: Istio, AgentGateway) 및 클라우드 관리형 서비스(예: Google Cloud의 Application Load Balancer)를 포함한 L7 로드 밸런서와 통합될 수 있습니다.

이 라우터는 **Endpoint Picker (EPP)**를 통해 지능성을 확보합니다. EPP는 ext-proc 프로토콜을 통해 프로덕션급 프록시(예: Envoy)와 통합되어, 데이터 플레인에 실시간 신호를 주입하여 요청 배치를 최적화합니다.

<p align="center"> <img src="https://raw.githubusercontent.com/llm-d/llm-d-router/HEAD/docs/images/llm-d-router.svg" width="800" alt="llm-d Router Architecture"> </p>

핵심 구성 요소 및 API

이 리포지토리는 다음의 핵심 구성 요소를 호스팅합니다:

• Endpoint Picker (EPP): 라우터의 '두뇌' 역할을 하는 지능형 라우팅 엔진입니다. 이 엔진은 KV-cache 지역성(locality), 현재 부하(load), 우선순위 등의 요소를 고려하여 들어오는 요청을 InferencePool의 현재 상태와 비교하고 최적의 배치 결정을 내립니다. ext-proc 프로토콜을 통해 L7 프록시와 통합됩니다.
• Request Management APIs: 이 리소스들은 EPP의 요청 처리 동작에 직접적인 영향을 미칩니다:
  • InferenceObjective: 특정 요청에 대한 EPP의 스케줄링 목표를 구성하며, 여기에는 우선순위 수준과 성능 목표가 포함됩니다.
  • InferenceModelRewrite: EPP에게 모델 이름 재작성(model name rewriting)을 수행하도록 지시하여 A/B 테스트 및 카나리 롤아웃을 위한 유연한 트래픽 관리를 가능하게 합니다.
• Disaggregation Sidecar: 모델 서버 옆에 배포되는 조정 구성 요소입니다 (일반적으로 디코드 워커의 사이드카로 작동). 이는 전문화된 인코더 및 프리필 워커와 통신하여 KV-cache 및 임베딩 전송을 관리함으로써, P/D (Prefill/Decode) 및 **E/P/D (Encode/Prefill/Decode)**와 같은 복잡한 다단계 추론 수명 주기를 조정합니다. 더 자세한 내용은 Disaggregation Documentation을 참조하십시오.

작동 모드 (Modes of Operation)

llm-d Router는 Kubernetes Gateway API Inference Extensions에 명시된 두 가지 주요 배포 모드를 지원합니다:

1. 독립형 모드 (Standalone Mode)

Gateway API 인프라가 필요하지 않은, 자체 관리형 Envoy 프록시를 사용하는 배포입니다. 독립형 Helm 차트는 두 가지 Envoy 프록시 토폴로지를 지원합니다:

• 사이드카 모드 (Sidecar mode) (기본값): 프록시가 EPP 파드 내에서 실행됩니다. 이 토폴로지는 기본적인 테스트 및 로컬 평가에 적합합니다.
• 서비스 모드 (Service mode): 프록시가 별도의 수평 확장 가능한 배포(Deployment)와 서비스(Service)로 실행되며, EPP 서비스를 통해 EPP에 접근합니다. router.proxy.mode=service를 설정하여 프록시를 EPP와 독립적으로 확장할 수 있습니다.

구성 예시는 Helm chart documentation을 참조하십시오.

2. Gateway Mode (추론 게이트웨이)

공식 Gateway API를 활용하는 프로덕션 환경에 권장되는 모드입니다. 이 모드에서 EPP는 공유된 Gateway의 HTTPRoute가 참조하는 InferencePool의 백엔드로 작동합니다. 이를 통해 고급 트래픽 관리, 다중 클러스터 로드 밸런싱, 그리고 추론 및 전통적인 워크로드를 위한 공유 인프라를 구현할 수 있습니다.

라우터 아키텍처, 라우팅 로직, 그리고 다양한 플러그인(필터 및 스코어러)에 대한 자세한 내용은 [아키텍처 문서]를 참조하십시오. 무거운 또는 긴 컨텍스트 워크로드에서의 리소스 프로비저닝 및 컨테이너 크기 지정 권장 사항은 [EPP 컨테이너 크기 지정 가이드]를 참조하십시오. [OpenTelemetry JSON stdout 로그] 문서는 EPP와 라우팅 사이드카가 사용하는 로그 레코드 형식을 설명합니다. [TLS 문서]는 EPP, 라우팅 사이드카 및 코디네이터의 서비스 및 메트릭 TLS 플래그를 다룹니다.

---

[!NOTE]
이 프로젝트는 자동 Envoy 설치 도구를 제공합니다. 하지만 직접 설치하거나 구성하는 경우, 지원되는 유일한 request_body_mode 및 response_body_mode는 FULL_DUPLEX_STREAMED임을 유의하십시오.

용어 정의 (Terminology)

프로젝트 전반에 걸쳐 명확성을 확보하기 위해 다음과 같은 표준 용어를 사용합니다:

• llm-d Router: Proxy (예: Envoy)와 **Endpoint Picker (EPP)**를 모두 포함하는 완전한 지능형 진입점입니다. 이 용어는 모든 맥락에서 'Inference Scheduler'를 대체합니다.
• llm-d Endpoint Picker (EPP): 라우팅 지능 및 스코어링 로직을 구현하는 특정 구성 요소입니다. 전체 요청 라우팅 시스템 자체보다는 EPP 자체에 특화된 기능이나 구성을 언급할 때 이 용어를 사용하십시오.
• Inference Gateway: Gateway Mode로 작동할 때 llm-d Router의 동의어입니다.
• Request Scheduler: EPP 내부에 있는 하위 구성 요소로, 요청의 큐잉 및 디스패칭을 담당합니다.

Contributing

프로젝트 전반의 가이드라인, 행동 강령 및 커뮤니티 리소스는 llm-d organization contributing guide에서 시작하고, 이 저장소에 특화된 내용(이슈를 할당하는 방법 포함)은 CONTRIBUTING.md를 참고하십시오.

저희 커뮤니티 미팅은 격주 수요일 오전 10시 PDT(Google Meet, Meeting Notes)에 열립니다.

현재 커뮤니케이션을 위해 llm-d Slack 워크스페이스의 #sig-router 채널을 사용하고 있습니다.

큰 변경 사항이 있을 경우, 먼저 [issue를 생성]하여 변경 내용을 설명해 주시면 유지보수 담당자들이 평가할 수 있고, 세부 사항에 대해 논의할 수 있습니다. 코드베이스 작업 방식에 대한 자세한 내용은 DEVELOPMENT.md를 참고하세요.

기여는 언제나 환영합니다!

보안 (Security)

취약점 보고는 SECURITY.md를 참고하세요. 게시된 컨테이너 이미지는 서명된 출처 증명(provenance attestation)과 SBOM(software bill of materials, 소프트웨어 구성 명세서)을 포함합니다. 이들을 확인하는 방법은 Verifying Published Artifacts를 참고하세요.

라이선스 (License)

FOSSA Status