> For the complete documentation index, see [llms.txt](https://genos-docs.gitbook.io/default/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://genos-docs.gitbook.io/default/v1.9.2/advanced-tutorials/guides/serving/service-router.md).
# 서비스 라우터
서비스 라우터는 여러 서빙 리비전(모델 서빙·코드 서빙)을 하나의 고정된 외부 엔드포인트 뒤에 묶어, 트래픽을 나눠 보내거나 교체할 수 있게 해주는 기능입니다. 리비전을 직접 지정하는 대신 라우터의 엔드포인트 하나만 호출하면, 뒤쪽 리비전을 무중단으로 바꾸거나(가중치·카나리), 새 리비전을 병행 검증하거나(Shadow), 장애가 난 리비전을 자동으로 격리할 수 있습니다.
좌측 메뉴의 **서비스 라우터**에서 접근합니다. 외부 애플리케이션이나 스크립트에서는 리비전 ID가 아니라 라우터 엔드포인트를 호출합니다.
## 주요 개념
| 개념 | 설명 |
| ---------------- | ----------------------------------------------------------------------------------------------------- |
| 서비스 라우터 | 여러 서빙 리비전을 하나의 엔드포인트 뒤에 묶어 트래픽을 분배·전환하는 단위입니다. |
| 엔드포인트 | 라우터를 외부에서 호출할 때 쓰는 고유 식별자입니다. 영문 소문자·숫자·하이픈·언더스코어만 사용하며 최대 30자입니다(시작은 영문 또는 숫자). 예: `qwen3-router` |
| 유형 | 라우터가 어떤 서빙을 묶는지 나타냅니다. 서빙 - LLM/VLM/Rerank/Embedding, 코드 서빙 중 하나이며, 유형에 따라 외부 호출 경로가 달라집니다. |
| 타깃(대표 리비전) | 라우터가 트래픽을 보내는 실제 서빙 리비전입니다. 라우터와 동일한 유형의 리비전만 묶을 수 있습니다. |
| Primary / Shadow | Primary는 실제 사용자에게 응답하는 리비전이며 여러 개를 지정할 수 있습니다. Shadow는 응답을 사용자에게 주지 않고 병행 호출만 하는 검증용 리비전으로 하나만 지정합니다. |
| 라우팅 전략 | 트래픽을 나누는 방식입니다. 가중치가 기본이며 카나리 점진 전환을 지원합니다. |
| 서킷 브레이커 | 실패가 임계치를 넘은 리비전을 자동으로 트래픽에서 제외하는 안전장치입니다. 상태는 정상·격리·probe 허용으로 구분됩니다. |
| 인증키 | 라우터를 외부에서 호출할 때 쓰는 토큰입니다. 허용 IP·만료일·호출 한도를 함께 관리합니다. |
| 이용 로그 | 해당 라우터로 들어온 호출을 추적한 기록입니다. |
### 유형과 외부 호출 경로
라우터 생성 시 유형을 고르면 외부 호출 경로의 뒷부분이 유형에 맞춰 자동으로 결정됩니다. 유형은 생성 후 타깃과 충돌할 수 있으므로 변경 시 주의가 필요합니다.
| 유형 | 호출 경로 뒷부분 | 규약 |
| -------------- | ---------------------- | ------------------------- |
| 서빙 - LLM | `/v1/chat/completions` | OpenAI 호환 챗 |
| 서빙 - VLM | `/v1/chat/completions` | OpenAI 호환 챗(비전) |
| 서빙 - Rerank | `/v1/rerank` | 리랭킹 |
| 서빙 - Embedding | `/v1/embeddings` | 임베딩 |
| 코드 서빙 | 없음 | 코드 서빙이 정의한 경로를 그대로 사용합니다. |
## 서비스 라우터 목록
목록 화면에서는 등록된 라우터를 확인하고 검색·생성할 수 있습니다. 목록 컬럼은 ID·이름·엔드포인트·유형·설명·제작자·관리 그룹·등록일시이며, 이름·ID·엔드포인트·설명·제작자로 검색할 수 있습니다. 행을 더블 클릭하면 상세 화면으로 이동합니다.
서비스 라우터 목록
챗 모델 노드처럼 특정 유형만 필요한 화면에서는 해당 유형의 라우터만 표시됩니다.
## 서비스 라우터 생성
목록의 **생성** 버튼으로 다이얼로그를 엽니다. 생성 권한이 있어야 버튼이 표시됩니다.
서비스 라우터 생성 다이얼로그
| 입력 | 필수 | 설명 |
| ----- | :-: | ----------------------------------------------- |
| 이름 | ● | 라우터 표시 이름입니다. |
| 상세 설명 | | 용도를 메모합니다. |
| 관리 그룹 | ● | 라우터가 속할 리소스 관리 그룹입니다. |
| 유형 | ● | 서빙 - LLM/VLM/Rerank/Embedding, 코드 서빙 중에서 선택합니다. |
| 엔드포인트 | ● | 외부 호출용 식별자입니다. 영문 소문자·숫자·하이픈·언더스코어만, 최대 30자입니다. |
엔드포인트를 입력하면 다이얼로그 하단에 실제 외부 호출 경로 예시가 유형에 맞춰 안내됩니다. 생성하면 곧바로 상세 화면으로 이동해 타깃과 정책을 설정합니다. 타깃은 생성 시 비워 두고 상세에서 지정해도 됩니다.
## 상세 — 기본 정보
상세 화면의 탭은 **기본 정보 · 라우터 정책 · 인증 키 · 이용 로그**입니다. 인증 키 탭은 수정 권한이 있을 때만 표시됩니다.
기본 정보 탭은 왼쪽에 메타 정보(제작자·관리 그룹·등록일시·엔드포인트·활성 토글), 오른쪽에 편집 폼(이름·상세 설명·유형)이 놓입니다.
상세 — 기본 정보 탭
* **엔드포인트**: 엔드포인트 이름이 표시되고, 그 아래에 외부 호출 경로 전체와 복사 버튼이 있습니다.
* **활성 토글**: 켜면 외부 호출이 가능하고, 끄면 외부에서 호출할 수 없습니다.
* **수정**: 하단의 **수정** 버튼은 해당 라우터에 수정 권한이 있을 때만 나타납니다. 이름·상세 설명·활성 여부를 편집할 수 있으며 유형은 읽기 전용으로 표시됩니다.
## 라우터 정책
라우터 정책 탭은 트래픽을 어떻게 나눌지 결정하는 핵심 화면입니다. 타깃 선택과 여러 정책을 한 탭에서 편집하고 하단의 **저장** 버튼으로 한 번에 반영합니다.
라우터 정책 탭 — 타깃 선택과 추가 정책
### 타깃(대표 리비전)
라우터가 트래픽을 보낼 서빙 리비전을 지정합니다. **Primary**는 여러 개를 고를 수 있고 **Shadow**는 하나만 고릅니다. 온라인 상태(배포 완료 또는 내리기 대기 중)인 리비전만 선택 대상이며, 배포가 중지된 리비전은 목록에 표시되지 않습니다. 타깃은 라우터와 동일한 유형이어야 합니다.
**분배 비율** 컬럼은 각 Primary 리비전이 실제로 받는 트래픽 비율을 보여줍니다. 다음 리비전은 0%로 계산됩니다.
* 트래픽에서 수동으로 격리한 리비전
* Shadow 리비전(사용자 응답에 반영되지 않음)
* 서킷 브레이커가 격리한 리비전
### 라우팅 전략
* **가중치**: 기본 전략입니다. Primary 리비전들에 가중치를 배분해 그 비율대로 트래픽을 나눕니다. 무중단 리비전 교체나 A/B 분배에 사용합니다.
* **카나리**: 새 리비전으로 트래픽을 점진적으로 늘려가며 전환합니다. 진행 중에는 정책 탭에 진행률과 남은 시간이 표시되고, **카나리 중지** 버튼으로 즉시 되돌릴 수 있습니다. 중지하면 전략이 가중치로 돌아가고 진행 패널이 사라집니다.
> 카나리와 Shadow는 동시에 사용할 수 없습니다.
### 추가 정책
정책 탭 좌측의 세로 탭에서 다음 정책을 켜고 설정합니다.
| 정책 | 설명 |
| --------- | ------------------------------------------------------------------------------------------------ |
| 서킷 브레이커 | 실패가 임계치를 넘은 리비전을 자동으로 격리합니다. 일정 시간 뒤 probe로 회복을 확인하고 정상이면 다시 트래픽을 받습니다. 수동 격리 해제와 복구도 지원합니다. |
| 규칙 기반 라우팅 | 특정 사용자나 관리 그룹 등 조건에 맞는 요청을 지정한 리비전으로 보냅니다. |
| 세션 고정 | 같은 세션의 요청을 같은 리비전으로 계속 보냅니다. 설정한 시간 동안 유지됩니다. |
| Shadow 모드 | Primary 응답을 사용자에게 주면서 동일한 요청을 Shadow 리비전에도 복제 호출해 결과를 비교합니다. 응답 유사도와 지연 차이를 확인하고 선호를 기록할 수 있습니다. |
| 가드레일 | 요청과 응답에 가드레일을 적용합니다. |
### 저장과 미저장 변경 안내
정책은 하단의 저장 버튼으로 한 번에 저장됩니다. 저장하지 않은 변경이 있는 상태에서 다른 탭으로 이동하거나 페이지를 벗어나거나 새로고침하면 저장하지 않고 나갈 것인지 확인하는 경고가 표시됩니다.
## 인증 키
인증 키 탭에서 라우터를 외부에서 호출하기 위한 토큰을 발급하고 관리합니다. 수정 권한이 필요합니다. 목록 컬럼은 ID·토큰·승인 상태·허용 IP·만료일·호출 한도·사용자·요청 수·프롬프트 및 컴플리션 토큰·메모입니다. 행을 더블 클릭하면 인증키 상세로 이동합니다.
인증 키 탭
외부 호출 시 이 토큰을 인증 헤더로 전달합니다. 허용 IP를 지정하면 해당 IP에서만 호출이 허용됩니다.
## 이용 로그
이용 로그 탭은 이 라우터로 들어온 호출을 추적한 기록입니다. 한 라우터의 트래픽은 여러 리비전과 Shadow로 분산되므로 서빙 단위가 아니라 라우터 단위로 묶어서 보여줍니다. 조회 권한이 필요합니다.
이용 로그 탭
* 컬럼은 추적 ID·pod·IP·세션 ID·시각·소요 시간·성공 여부이며, 실패한 호출은 툴팁으로 오류 내용을 확인할 수 있습니다.
* 날짜 범위로 필터링하며 최대 2주까지 조회할 수 있습니다.
* **다운로드** 버튼으로 CSV 파일을 내려받을 수 있습니다.
> 라우터 단위 추적이 시작되기 이전에 발생한 트래픽은 이용 로그에 나타나지 않습니다.
## 임베딩 서빙 연결 방식 선택
임베딩 서빙을 선택하는 화면에서 연결 방식을 **Direct Serving**과 **Service Router** 중에서 고를 수 있습니다. 다음 화면에서 지원합니다.
* 벡터 DB 문서 추가
* AI 드라이브 문서 색인
* 자동 적재(파일·RDBMS 원천)
* 리포트
* 워크플로우 InstantRAG
**Direct Serving**은 기존 방식으로 임베딩 서빙 리비전을 직접 지정합니다. **Service Router**를 고르면 활성화된 임베딩 유형 라우터를 선택합니다. 활성 라우터가 없으면 안내가 표시됩니다. 이 경우 임베딩 호출이 라우터를 경유하므로 라우터에서 설정한 리비전 교체·다중 리비전 분배·Shadow 검증이 임베딩에도 그대로 적용됩니다.
연결 방식을 비워 두면 기존 Direct Serving 동작을 유지합니다.
## 오류와 예외 상황
| 상황 | 동작 |
| --------------------------- | -------------------------------------- |
| 라우터 활성 토글을 끈 경우 | 외부에서 호출할 수 없습니다. |
| 엔드포인트 형식을 위반한 경우 | 생성·수정 시 허용 문자를 안내하는 오류가 입력칸 아래에 표시됩니다. |
| 유형과 타깃이 일치하지 않는 경우 | 저장이 거부됩니다. |
| 서킷 브레이커 복구를 시도했으나 이미 복구된 경우 | 이미 복구되었다는 안내가 표시됩니다. |
| 상세·정책 조회 권한이 없는 경우 | 권한 없음 화면이 표시됩니다. |
| 인증키·정책 편집 권한이 없는 경우 | 편집 버튼이 비활성화되거나 표시되지 않습니다. |
## 사용자 시나리오
### 무중단 모델 교체
새 모델 리비전을 Primary에 추가하고 가중치를 점차 올려 기존 리비전의 비중을 낮춥니다. 외부 호출 측은 라우터 엔드포인트만 호출하므로 리비전 교체를 인지하지 못하며, 문제가 생기면 가중치를 되돌려 즉시 롤백할 수 있습니다.
### 카나리 배포
새 리비전을 카나리로 두고 소량 트래픽부터 점진적으로 전환합니다. 진행 중 패널에서 진행률과 남은 시간을 확인하고, 이상 징후가 보이면 **카나리 중지**로 전략을 가중치로 되돌립니다.
### Shadow 검증
교체 후보 리비전을 Shadow로 지정하면 사용자 응답에는 영향을 주지 않으면서 동일한 요청이 복제 호출됩니다. Primary와 Shadow의 응답 유사도·지연 차이를 비교하고 선호를 기록해 실제 승격 여부를 판단합니다.
### 임베딩 색인 파이프라인 전환
벡터 DB 문서 추가·AI 드라이브·자동 적재·리포트에서 임베딩 연결 방식을 **Service Router**로 두면, 임베딩 서빙 리비전의 교체나 분배를 라우터에서 일괄 관리할 수 있습니다.
## 함께 보기
* [서빙 로그 확인](/default/v1.9.2/advanced-tutorials/guides/serving/api-log.md)
* [멀티터넌트 서빙](/default/v1.9.2/advanced-tutorials/guides/serving/multitenancy.md)
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://genos-docs.gitbook.io/default/v1.9.2/advanced-tutorials/guides/serving/service-router.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.