콘텐츠로 이동
AggregaAggrega
언어 선택: 한국어
이 페이지는 기계 번역되었습니다. 영어 원문 읽기.

에이전트, 라우터, 그리고 두 개의 업스트림 모델

하나의 클러스터 내 라우터를 통해 두 개의 업스트림 provider 모델에 접근하는 에이전트 애플리케이션으로, Kubernetes 매니페스트로 컴파일됩니다.

에이전트는 하나의 이름으로 모델을 요청합니다. 그 이름 뒤에는 별칭 맵을 가진 라우터가 있고, 그 맵 뒤에는 두 개의 provider가 있습니다. 에이전트는 어느 provider가 응답했는지 알지 못하고, provider 자격 증명을 보유하지 않으며, 맵이 다른 대상을 가리키도록 바뀌어도 변경되지 않습니다. 이것이 바로 그 자리에 라우터를 두는 이유입니다.

이 워크스페이스는 자체 카탈로그 엔티티를 하나도 작성하지 않습니다. 여기서 이름을 붙이는 모든 Component, Feature, Recipe는 표준 라이브러리 카탈로그에 포함되어 제공되며, 여기 있는 세 개의 엔티티 파일, 즉 Aggregate, Manifest, Release가 누구든 작성하는 것의 전부입니다.

구성되는 내용

agent ───────────────────┐ ┌────► openai/gpt-4o
│ │ │
▼ ├────► router ──────┤
checkpointer │ (the alias map) └────► anthropic/claude-sonnet-4
(run state) │
│
an Ingress at ───────────┘
assistant.example.internal

라우터로 요청이 들어오는 길은 두 가지이고 — 에이전트는 model 엣지를 통해, 외부의 모든 것은 Ingress를 통해 라우터에 도달합니다 — 나가는 길은 맵 항목마다 하나씩 있습니다. 세 번째 포트는 클러스터 내부의 스크레이퍼에 메트릭을 제공합니다.

세 개의 컴포넌트가 각각 다른 일을 합니다:

인스턴스카탈로그 Component여기서의 역할
routercore/gateway/litellm라우팅 컴포넌트: 하나의 엔드포인트, 별칭 맵, 두 개의 업스트림 제공자. 자신의 주소와 에이전트가 요청하는 별칭을 게시합니다
agentcore/ai-agent/langgraph자체 그래프 이미지를 실행하는 애플리케이션
checkpointercore/datastore/valkey에이전트가 실행 상태를 보관하는 곳으로, 데이터스토어 범주로 선택됩니다

두 개의 uses 엣지가 있으며, 둘 다 에이전트의 Component가 선언하는 소켓으로 연결됩니다: model (필수이며, 모델 컴포넌트 또는 모델 API를 제공하는 게이트웨이를 허용합니다 — 라우터는 후자입니다)과 checkpointer_db(필수이며, 데이터스토어 범주로 선택합니다). 네 가지 Feature 종류에 걸친 여섯 개의 Feature 연결이 있으며 — 다섯 개는 라우터에, 하나는 에이전트의 model 연결에 있습니다 — 각각이 렌더링된 출력에 무언가를 추가합니다. 각각이 무엇을 생성하는지는 아래 섹션에서 보여 줍니다.

예제 생성하기

아래 명령으로 이 예제를 빌드하거나, AI 어시스턴트에게 대신 빌드하게 할 수 있습니다.

예제 이름을 딴 새 폴더에 예제를 씁니다:

Terminal window
aggrega scaffold --example ai-agent-and-model-router

그런 다음 이어서 실행할 명령을 출력합니다. 첫 번째 명령은 새 폴더로 이동합니다:

Terminal window
cd ai-agent-and-model-router

빌드

Terminal window
aggrega build --release release.yaml --auto-pull

릴리스는 빌드하기 전에 lockfile이 필요하며, lockfile은 함께 배포되지 않고 생성되므로 새로 클론한 저장소에는 lockfile이 없습니다. aggrega build는 기본적으로 읽기 전용입니다. lockfile이 없으면 중단하고 진행할 수 있는 두 가지 방법을 알려 줍니다. 먼저 lockfile을 해석하거나, 빌드가 lockfile을 채우도록 합니다.

Terminal window
aggrega pull --release release.yaml # resolve once, then build with no flag
aggrega build --release release.yaml --auto-pull # or resolve during the build

이 작업 공간은 .aggrega-config.yaml이 지정하는 기본 레지스트리에서 엔티티를 해석하므로 --catalog 플래그가 필요하지 않습니다.

라우터의 selection 첨부를 실현할 때는 컴파일러에도 카탈로그에도 포함되지 않은 플러그인 하나, 즉 게이트웨이 구성 단계 pipeline-step/litellm-gateway-config를 실행하며, 해석 과정에서 이를 default_registry가 지정하는 레지스트리 hub.aggrega.ai에서 가져옵니다.

아래의 여러 절에서는 한 줄을 변경하고 다시 빌드하도록 안내합니다. lockfile은 이 디렉터리의 Aggregate와 Manifest를 포함하여 릴리스가 해석한 모든 엔티티의 다이제스트를 고정하고, Release 자체는 그 내용의 다이제스트로 기록합니다. 따라서 이 세 파일 중 하나라도 편집하면 lockfile이 최신 상태가 아니게 되며, 다음 빌드는 오래된 고정값에 대해 렌더링하지 않고 중단합니다. 메시지는 무엇이 변경되었는지(Release는 파일로, Aggregate나 Manifest는 이름으로) 지목하고, 기록된 다이제스트를 발견된 다이제스트와 나란히 출력합니다. pull은 다른 모든 고정값을 유지하면서 변경 사항을 기록합니다:

Terminal window
aggrega pull --release release.yaml

이를 실행한 뒤 다시 빌드하거나, 같은 pull을 먼저 실행하는 --auto-pull로 빌드합니다. 어느 쪽이든 중단은 장애물이 아니라 의도된 동작입니다. 빌드는 오래되었음을 알 수 있는 고정값에 대해 렌더링하지 않습니다.

빌드는 다음을 출력하며, <workspace>는 이 예제의 폴더를 나타냅니다.

verify: plugin pipeline-step/litellm-gateway-config:1.0.0 host functions match the published .wasm
[… omitted: three warnings, one per credential attachment, that the declared-sensitive origin reaches the target with no per-key sensitivity marking, because the realization maps it through a valuesMapping]
Pull complete: release.lock (entities=24, source_artifacts=0, external_inputs=0)
[… omitted: a notice that core/referenced-secret declares origin in both of its pillars, and a total build time, which differs per run]
Build completed: 12 files written to <workspace>/dist

엔티티는 lockfile을 해석할 때 한 번, 릴리스를 빌드할 때 한 번 카탈로그의 관례에 대해 검사되며, 이 검사에서 발생한 각 권고는 lint: 줄로 출력됩니다. 이 릴리스에서는 아무것도 발생하지 않습니다. 같은 검사를 단독으로 실행하고, 각 권고를 그것이 나온 엔티티 파일 및 관례에 맞추는 방법과 함께 전체 내용으로 읽으려면 다음을 실행합니다.

Terminal window
aggrega lint --release release.yaml

여기서는 conventions checked: 19 entities, 0 advisory finding(s)를 보고합니다.

AI 어시스턴트 사용

Aggrega 도구로 설정한 AI 어시스턴트도 같은 작업을 할 수 있습니다. 다음 프롬프트를 붙여 넣으십시오.

Aggrega 도구만 사용하고 폴더를 직접 만들지 마십시오. 워크스페이스 폴더에 아직 `ai-agent-and-model-router` 폴더가 없으면 `example`에 `ai-agent-and-model-router`를 지정하고 `dir` 없이 `scaffold` 도구를 한 번 호출하십시오. 그러면 예제가 새 `ai-agent-and-model-router` 폴더에 쓰입니다. 그런 다음 `workspace_root`에 `ai-agent-and-model-router`, `release`에 `release.yaml`, `auto_pull`에 true, `write`에 true를 지정하여 `build` 도구를 호출하십시오. 빌드가 어떤 파일을 썼는지 알려 주십시오. 파일은 `ai-agent-and-model-router/dist/` 아래에 있습니다.

렌더링된 트리

dist/helm/
├── agent--router-zumodel-zdcredential--agent-secret-agent-router-model-credential.yaml
├── agent-deployment.yaml
├── checkpointer-default-service.yaml
├── checkpointer-deployment.yaml
├── router--api-zukey--router-secret-router-api-key.yaml
├── router--metrics--router-servicemonitor-router-scrape.yaml
├── router--provider-zukey--router-secret-router-provider-key.yaml
├── router--published--router-ingress-router-ingress.yaml
├── router-default-service.yaml
├── router-deployment.yaml
└── router/
├── litellm-gateway-config/
│ └── configmap.yaml
└── request-guard/
└── request-guard.yaml

router/ 아래에는 라우터의 Recipe가 직접 내보내는 파일이 있습니다. 두 파일 모두 Recipe가 직접 작성하지 않고 가져오는 번들에서 오므로, 각각 가져올 때 사용된 키인 litellm-gateway-config와 request-guard 아래에 놓입니다.

어태치먼트가 가져온 모든 것은 컴포넌트 자체의 매니페스트와 같은 디렉터리에 놓이며, 파일 이름에 두 가지 좌표를 담습니다. 하나는 어태치먼트가 붙은 컴포넌트이고, 다른 하나는 어태치먼트에 부여된 이름입니다. router--metrics--는 router에 붙은 metrics 어태치먼트입니다. 무엇이 어디에서 왔는지는 여전히 트리에서 읽어 낼 수 있으며, 모든 파일은 한 디렉터리를 읽는 도구가 찾을 수 있는 위치에 있습니다. 따로 지정하지 않는 한 이 타깃의 소비자가 하는 일이 바로 이것입니다.

두 좌표는 파일 자체의 이름과 하나의 문자열을 공유하므로, 입력한 그대로 쓰이지 않고 인코딩됩니다. 파일 이름에 안전하게 담을 수 없는 문자는 -z와 문자 하나로 바뀝니다. api_key는 api-zukey가 되고, router_model.credential(에이전트의 router_model 연결에 붙은 어태치먼트가 갖는 이름으로, 연결의 별칭, 점, 슬롯으로 이루어짐)은 router-zumodel-zdcredential이 되며, feature.aggrega.ai/monitoring(Feature 자체의 어노테이션이 만들어 내는 어태치먼트 이름)은 feature-zdaggrega-zdai-zsmonitoring이 됩니다. 파일 자체의 이름은 포함된 점을 그대로 유지하므로 .yaml 접미사는 여전히 접미사로 읽힙니다.

여기의 페이지에서 빌드가 생성한 내용을 보여 주는 경우, 해당 블록은 실제 실행에서 복사한 것입니다. 이 관례와 생략된 줄에 사용하는 표시는 이 페이지의 출력 읽기를 참조하십시오.

라우팅 테이블

라우터가 존재하는 이유는 그 맵이며, 맵은 작성된 파일에 머무르지 않고 렌더링된 출력에 도달합니다. 다음은 dist/helm/router/litellm-gateway-config/configmap.yaml의 data 블록 전체입니다:

data:
config.yaml: |
model_list:
- model_name: assistant
litellm_params:
model: openai/gpt-4o
api_key: os.environ/LITELLM_PROVIDER_API_KEY
- model_name: assistant
litellm_params:
model: anthropic/claude-sonnet-4
api_key: os.environ/LITELLM_PROVIDER_API_KEY
litellm_settings:
callbacks:
- /etc/litellm-request-guard/request_field_filter.filter
- prometheus
router_settings:
routing_strategy: latency-based-routing

그리고 두 번째 ConfigMap인 dist/helm/router/request-guard/request-guard.yaml의 data 블록이며, 담고 있는 파일의 텍스트는 생략했습니다:

data:
request_field_filter.py: |
[… omitted: the text of the router's request guard, a Python module described below]
path-allowlist.conf: |
[… omitted: the configuration of the router's path allowlist, described below]

여기서 읽어 낼 만한 것이 다섯 가지 있습니다.

두 항목은 같은 별칭을 게시합니다. 이것이 라우터가 요청마다 선택을 하게 만드는 이유이며, 본문 끝의 router_settings가 그 선택 방법을 알려 줍니다. 바로 latency-based-routing으로, 아래 해당 attachment 절에서 보듯이 라우터 자체의 Recipe가 아니라 라우터의 selection attachment가 그곳에 기록한 것입니다. 별칭이 모두 서로 다른 맵은 이름만으로 라우팅하며, 전략은 이에 대해 아무것도 바꾸지 않습니다. 하나의 별칭을 공유한다는 점은 또한 두 항목이 라우터의 models 소켓에 연결된 모델 component에서 제공되지 않고 values.models에 직접 입력된 이유이기도 합니다. 연결된 모델은 자기 연결의 별칭으로 제공되며, 그 별칭은 다른 어떤 항목도 게시할 수 없으므로 연결된 두 모델이 하나의 별칭을 공유하는 일은 없습니다. 두 번째 이유는 Anthropic에 있습니다. 라우터는 연결된 모델의 항목을 OpenAI API로만 기록하는데 Anthropic의 모델은 자체 API로 응답하므로, core/ai-model/anthropic를 연결하면 빌드가 중단되며 그 업스트림을 대신 맵에 직접 입력하라고 알려 줍니다.

대상은 컴파일러가 해석하지 않는 문자열입니다. openai/gpt-4o는 결정적인 포인터로, 실행 중인 프록시가 요청을 처리할 때 이를 해석합니다. 컴파일러는 빌드 시점에 provider에 접속하지 않으므로, 대상이 존재하는지, 철자가 올바른지, 계정이 그 대상에 접근할 수 있는지 알려 줄 수 없습니다. openai/gpt-4o를 openai/not-a-real-model로 바꾸어도 빌드는 여전히 성공하며, 실패는 요청 시점에 provider로부터 발생합니다.

이 파일에는 자격 증명 값이 없습니다. 각 항목은 대신 프록시 자체의 간접 참조를 통해 환경 변수의 이름을 지정합니다. 값은 아래에서 보듯이 완전히 다른 경로로 컨테이너에 도달합니다.

모든 요청은 먼저 가드를 거칩니다. 첫 번째 callbacks 항목은 request_field_filter 모듈을 그 파일의 전체 경로로 등록합니다. 두 번째 ConfigMap은 라우터 컨테이너의 /etc/litellm-request-guard에 마운트되는데, 이는 첫 번째 ConfigMap이 마운트되고 프록시가 구성을 읽는 /etc/litellm 옆의 별도 디렉터리입니다. 이 두 번째 ConfigMap은 이 프록시를 실행하는 모든 Recipe가 가져오는 번들인 LiteLLMGuard#/artifacts/RequestGuard에서 오므로, 가드와 아래의 허용 목록은 프록시가 실행되는 어디서나 같은 텍스트를 가집니다. 라우터가 provider 자격 증명을 보유하므로 라우터의 Recipe는 모든 Release에서 이 가드를 제공합니다. 가드는 호출자로부터 요청이 거친 경로에 대해 프록시가 선언한 요청 필드와 Release가 라우터의 infra.admitted_request_fields에 지정한 필드만 전달하고, 그 밖의 필드에는 그 필드를 명시한 오류로 응답하며 아무것도 전달하지 않습니다. 따라서 호출자는 요청 본문의 모델 목록을 통해 라우터가 자신의 주소를 가리키게 하거나, 라우터의 키 대신 자신의 provider 키를 보낼 수 없습니다. 또한 호출자는 라우터가 모든 요청에 직접 기록하는 신원, 즉 검증한 키의 해시, 그 키의 팀과 조직, 최종 사용자를 설정할 수도 없습니다. 라우터가 호출자의 metadata를 자신의 것과 분리해 두는 responses 또는 messages 요청에서는 호출자가 그곳에 기록한 팀, 조직, 최종 사용자 필드를 제거하고 가드는 그곳에 키 metadata.user_api_key를 지정한 요청을 거부하며, 그 밖의 모든 경로에서는 라우터의 값이 호출자가 보낸 값을 대체합니다. 이 Release는 그 이상 아무것도 허용하지 않습니다. 두 번째 항목인 prometheus는 프록시 자체의 메트릭 콜백으로, 라우터의 metrics_enabled 값이 이를 켭니다. 아래의 metrics attachment가 이 콜백이 기록한 것을 수집합니다.

라우터 자체의 경로에만 도달할 수 있습니다. 가드는 자신에게 요청을 넘기는 경로만 보므로, 두 번째 ConfigMap의 다른 파일이 파드의 두 번째 컨테이너를 구성합니다. 이 컨테이너는 그 ConfigMap만 마운트하고 공식 nginx 이미지를 경로 허용 목록으로 실행합니다. 라우터 자체는 파드 외부에서는 아무것도 도달할 수 없는 파드의 루프백 주소에서 수신하며, 허용 목록은 아래 Service가 대상으로 하는 포트인 4000번 포트에서 수신합니다. 허용 목록은 요청의 메서드와 경로가 라우터가 제공하는 경로 중 하나일 때만 요청을 전달합니다. 그 경로는 가드가 검사하는 모델 요청 경로(별칭과 관계없이 라우터가 제공하는 표기로, /v1/chat/completions와 /v1/messages 포함), 모델 목록, 상태 확인, 그리고 관리 경로 중 키 관리입니다. 그 밖의 모든 경로에는 403으로 응답하며 아무것도 전달하지 않습니다. 따라서 프록시의 토큰 수 경로, provider 자체 API로의 패스스루 경로, 그 밖의 관리 경로와 관리 콘솔에는 라우터를 통해 도달할 수 없으며, Azure의 클라이언트가 보내는 경로처럼 경로에 모델 이름이 들어 있는 모델 경로도 마찬가지입니다. 그런 경로에서는 프록시가 요청 기록 방식을 결정하기 위해 별칭을 포함한 경로의 단어를 읽으며, 라우터는 그 경로에서 이 맵 자체의 assistant에 대한 요청도 거부합니다. 프록시의 메트릭도 이 경로에 포함되지 않으므로 4000번 포트는 /metrics에 403으로 응답합니다. Aggregate가 설정한 대로 라우터의 metrics_enabled가 true이면 허용 목록은 9090번 포트에서도 수신하며, 그곳에서는 /metrics에 대한 GET만 프록시가 루프백 주소에 메트릭용으로 유지하는 리스너로 전달하고 그 밖의 모든 요청에는 403으로 응답합니다. 이 포트는 호출자를 검사하지 않으며, 메트릭에는 라우터가 비용을 귀속시키는 해시된 키, 키 별칭, 사용자 이메일이 기록됩니다.

라우터가 게시하는 것

라우터의 Recipe는 모든 모델 컴포넌트가 게시하는 두 키를 게시합니다. 하나는 클라이언트 라이브러리에 전달되는 기본 URL인 endpoint이고, 다른 하나는 요청이 지정하는 이름인 model입니다. 이 덕분에 에이전트의 model 소켓이 모델 대신 라우터를 받을 수 있습니다. 소켓의 셀렉터는 component.aggrega.ai/category in (ai-model, gateway), model.aggrega.ai/api입니다. 이 셀렉터는 모델 또는 게이트웨이 카테고리에 속하면서 model.aggrega.ai/api를 가진 컴포넌트를 허용합니다. 이 레이블은 컴포넌트가 게시하는 주소에서 어떤 모델 API가 응답하는지를 나타냅니다. 라우터는 model.aggrega.ai/api: openai를 가집니다. 모델 API를 제공하지 않는 게이트웨이에는 이런 레이블이 없으며, 에이전트에서 그런 게이트웨이로 향하는 엣지는 빌드를 중단시키고, 해당 소켓과 대상이 충족하지 못한 셀렉터를 알려 줍니다.

주소는 라우터 자신의 Recipe가 내보내는 Service입니다. 다음은 dist/helm/router-default-service.yaml의 spec 전체입니다.

spec:
type: ClusterIP
selector:
app: router
ports:
- name: http
port: 4000
targetPort: http
- name: metrics
port: 9090
targetPort: metrics

Recipe는 게시하는 엔드포인트 http://router-default:4000/v1을 Service의 이름과 포트를 정하는 데 쓰인 것과 같은 두 가지 사실, 즉 컴포넌트 자신의 이름과 infra.port로 구성합니다. Service가 대상으로 하는 포트 http는 라우터의 경로 허용 목록이 수신하는 포트입니다. 두 번째 포트인 metrics는 라우터의 메트릭이 켜져 있기 때문에 존재하며, 메트릭만 전달합니다. 세 파일 어디에도 router-default가 직접 적혀 있지 않습니다. router 컴포넌트의 이름, 즉 Aggregate와 Release에서의 키와 이를 가리키는 에이전트의 엣지를 바꾸면, 에이전트가 받는 주소도 따라 바뀝니다. gateway로 바꾸면 에이전트의 OPENAI_BASE_URL은 http://gateway-default:4000/v1이 됩니다.

이름은 라우터가 자신의 모델로 게시하는 별칭입니다. 이 맵은 두 항목 모두에서 하나의 별칭 assistant를 게시하므로, 라우터는 그 별칭을 게시하고 values.model은 생략됩니다. 두 번째 항목에 고유한 별칭, 예컨대 summarizer를 주면 아무것도 렌더링되기 전에 빌드가 중단됩니다. 라우터는 하나만 게시할 수 있기 때문입니다. 이 중단은 라우터 Component의 어서션 실패인 E0033이며, 메시지는 규칙 자체의 문장으로 끝납니다. values.model is not set, but values.models publishes 2 aliases (assistant, summarizer), so the gateway cannot tell which one a component wired to it asks for; set values.model to one of them (values.model이 설정되지 않았지만 values.models가 2개의 별칭(assistant, summarizer)을 게시하므로, 게이트웨이는 연결된 컴포넌트가 어느 것을 요청하는지 알 수 없습니다. values.model을 그중 하나로 설정하십시오). models 옆에 model: assistant를 설정하면 해결되며, 에이전트는 다시 assistant를 받습니다. summarizer를 원하는 호출자는 같은 엔드포인트에 이름으로 요청합니다.

에이전트가 받는 것

에이전트의 Recipe는 자신의 두 엣지를 모두 읽고 에이전트 자체의 값도 읽어, 이를 컨테이너 환경으로 바꿉니다. 다음은 dist/helm/agent-deployment.yaml의 env 블록 전체입니다.

env:
- name: OPENAI_API_KEY
valueFrom:
secretKeyRef:
name: agent-router-model.credential
key: api-key
- name: LANGGRAPH_DEFAULT_RECURSION_LIMIT
value: "25"
- name: OPENAI_BASE_URL
value: http://router-default:4000/v1
- name: OPENAI_MODEL
value: assistant
- name: LANGGRAPH_CHECKPOINTER_HOST
value: checkpointer-default
- name: LANGGRAPH_CHECKPOINTER_PORT
value: "6379"
- name: LANGGRAPH_GRAPH_ENTRYPOINT
value: app.graph:graph

첫 번째 항목은 model 엣지가 지닌 첨부에서 왔으며, helm 프로바이더는 Secret에서 읽는 이런 항목을 일반 항목보다 앞에 씁니다. 재귀 한도는 에이전트 자체의 recursion_limit이며, LangGraph가 스스로 읽는 변수로 전달됩니다. 그다음 두 항목은 model 엣지에서, 그 뒤의 두 항목은 checkpointer_db 엣지에서 왔고, 마지막 항목은 에이전트 자체의 graph_entrypoint로, 애플리케이션 코드가 읽는 기본 이름으로 전달되며 컴포넌트 자체의 inject 블록은 그 이름을 대체합니다. Aggregate가 말할 필요가 없었던 것에 주목하십시오. 어느 엣지도 inject 블록을 지니지 않는데, 소비하는 Recipe가 각 연결을 기본 이름으로 전달하며 엣지의 inject 블록은 그 이름을 대체하기 때문입니다. 개발자는 에이전트가 모델을 사용한다고 선언합니다. 그 엔드포인트가 도착하는 변수는 클라이언트 라이브러리가 읽는 변수이며, 엣지가 지정하는 대로 유지됩니다.

LANGGRAPH_CHECKPOINTER_PORT: "6379"에도 주목하십시오. Release는 checkpointer: {}를 선언하고 아무것도 구성하지 않으므로, 이 포트는 캐시 Component 자신의 스키마 기본값이 구체화되어 엣지를 통해 전달된 것입니다.

에이전트는 프로바이더와 직접 대화할 때 쓰는 것과 정확히 같은 방식, 즉 기본 URL, 모델 이름, 키로 라우터와 대화합니다. 그래서 애플리케이션을 바꾸지 않고도 라우터를 삽입하거나 옮기거나 다른 곳을 가리키게 할 수 있습니다.

여섯 가지 첨부와 각각이 렌더링하는 것

출력에서 아무것도 바꾸지 않는 첨부는 아무것도 가르쳐 주지 않습니다. 이 여섯 가지는 각각 출력에 무언가를 넣습니다.

라우터의 api_key — 호출자에게 요구하는 키

core/referenced-secret로, 라우터의 Component가 선언하는 슬롯을 채웁니다. 이것이 담는 키는 LiteLLM이 마스터 키라고 부르는 키입니다. 자체 Secret을 렌더링하고, 라우터의 컨테이너가 이를 참조합니다. dist/helm/router--api-zukey--router-secret-router-api-key.yaml에서:

stringData:
master-key: "dev-router-admin-key-change-me"

그리고 라우터 컨테이너의 env에서, dist/helm/router-deployment.yaml로부터:

- name: LITELLM_MASTER_KEY
valueFrom:
secretKeyRef:
name: router-api-key
key: master-key

컨테이너는 값이 아니라 참조를 담습니다. Secret의 이름은 첨부가 게시하고 소비자가 읽으므로, 어느 쪽도 이를 다시 도출하지 않습니다.

라우터의 provider_key — 업스트림에 제시하는 키

같은 Feature가 다른 슬롯에 있으며, 두 슬롯의 차이가 곧 라우터의 핵심입니다. 이것은 values.models에 입력된 항목들, 여기서는 두 항목 모두의 유일한 자격 증명입니다. 라우터의 models 소켓에 연결된 모델은 이 키가 아니라 자체 연결이 담는 키를 제시합니다. dist/helm/router--provider-zukey--router-secret-router-provider-key.yaml에서:

stringData:
provider-key: "upstream-provider-key-change-me"

그리고 같은 컨테이너의 env에서:

- name: LITELLM_PROVIDER_API_KEY
valueFrom:
secretKeyRef:
name: router-provider-key
key: provider-key

이 첨부는 라우팅 테이블도 바꿉니다. 위의 라우팅 테이블 data 블록을 다시 보면, 모든 맵 항목이 api_key: os.environ/LITELLM_PROVIDER_API_KEY를 담아 바로 이 변수를 지칭합니다. Aggregate에서 provider_key 첨부를 제거하고 다시 빌드해 보십시오. 빌드는 12개가 아니라 11개의 파일을 보고하고(Secret이 사라짐), 라우팅 테이블의 ConfigMap은 정확히 그 두 api_key 줄만 다르고 나머지는 같습니다. 가드의 ConfigMap은 변하지 않습니다. 맵의 나머지 부분은 작성된 순서와 서식을 유지하고, 라우터는 여전히 요청을 처리하고 라우팅하지만, 라우팅된 요청은 이제 제시할 자격 증명이 없으므로 공급자 측에서 실패합니다.

변수 이름은 라우터의 Recipe에 한 번 작성되고, 라우팅 테이블과 컨테이너 환경 모두가 그곳에서 읽으므로, 테이블이 아무것도 설정하지 않는 변수를 지칭하게 될 수 없습니다.

두 자격 증명은 분리된 채로 유지되며, 그 분리가 라우터가 주는 이점입니다. 업스트림 키는 라우터 안에 머물고, 호출하는 애플리케이션은 라우터에 대한 키 외에는 아무것도 갖지 않습니다.

에이전트의 model 연결의 credential — 라우터에 제시하는 키

다시 core/referenced-secret이며, 같은 대화의 반대편에 있습니다. 에이전트의 model 소켓이 credential 슬롯을 선언하므로, 키는 그것이 제시되는 연결에, 즉 Aggregate의 엣지 아래에 첨부됩니다:

uses:
model:
router_model:
target: router
features:
credential:
type: core/referenced-secret
values:
key: api-key
origin: "{{ .parameters.router_admin_key }}"

dist/helm/agent--router-zumodel-zdcredential--agent-secret-agent-router-model-credential.yaml에서:

stringData:
api-key: "dev-router-admin-key-change-me"

이는 위의 라우터 master-key와 같은 값이며, 두 번 작성되지 않습니다. 두 첨부 모두 끌어올린 하나의 매개변수를 읽습니다:

origin: "{{ .parameters.router_admin_key }}"

Aggregate가 매개변수를 선언하고 Release가 이를 채우므로, 키가 작성되는 곳은 하나이고 두 Secret이 따로 편집될 수 없습니다. Release에서 한 번 바꾸면 렌더링된 두 Secret이 함께 바뀝니다.

각 첨부는 여전히 자체 Secret을 렌더링하며, 그 이름은 이를 소비하는 컴포넌트와, 에이전트의 경우 첨부된 연결에서 따옵니다: agent-router-model.credential. 공유 매개변수가 공유하는 것은 리소스가 아니라 값입니다.

라우터의 published — 클러스터 외부의 주소

core/public-ingress로, 어떤 슬롯도 채우지 않습니다. 이것은 라우터가 지닌 자체 셀렉터 component.aggrega.ai/type=server에 의해 허용됩니다. 라우터의 Recipe가 전혀 모르는 리소스를 가져옵니다. dist/helm/router--published--router-ingress-router-ingress.yaml의 spec 전체:

spec:
rules:
- host: assistant.example.internal
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: router-default
port:
name: http

개발자는 Aggregate에서 path와 함께 이를 첨부합니다. 애플리케이션이 어떤 요청을 처리하는지는 애플리케이션이 무엇인지의 일부이기 때문입니다. 운영자는 같은 첨부에 대한 Release 항목에 host와 포트 이름을 작성합니다. 호스트는 환경에서 라우터를 부르는 이름이므로, 운영자가 환경마다 각 환경의 Release에서 이름을 붙입니다. 백엔드 Service는 어느 쪽도 제공하지 않았습니다. service_name은 설정되지 않은 채로 남고, 첨부의 실현은 라우터 자체 Recipe가 내보내는 Service로 대체됩니다. 출력에 ingressClassName 필드가 없는 것은 아무것도 이를 설정하지 않았고 실현이 주어지지 않은 것은 생략하기 때문이며, 그 결과 클러스터의 기본 클래스가 리소스를 차지하게 됩니다.

라우터의 metrics — 스크레이프 대상

core/prometheus-exporter로, 같은 셀렉터에 의해 허용되며 자체 리소스를 하나 더 가져옵니다. 이것이 받는 모든 입력은 애플리케이션의 의도가 아니라 운영자의 크기 설정입니다. 플랫폼이 얼마나 자주 스크레이프하는지, 어느 포트와 경로를 읽는지는 플랫폼의 속성이기 때문입니다. 따라서 운영자가 Release에서 라우터의 항목에, infra 옆에 유형을 적어 이를 첨부합니다. Aggregate는 이를 언급하지 않습니다:

components:
router:
features:
metrics:
type: core/prometheus-exporter
infra:
interval: 30s
port: metrics
path: /metrics

dist/helm/router--metrics--router-servicemonitor-router-scrape.yaml의 spec 전체:

spec:
selector:
matchLabels:
app.kubernetes.io/name: router
endpoints:
- port: metrics
interval: 30s
path: /metrics

port는 숫자가 아니라 Service 포트 이름을 지정합니다. metrics로, Aggregate가 라우터의 metrics_enabled 값을 설정하므로 라우터의 Recipe가 내보내며, 메트릭을 제공합니다. 이는 Feature의 기본 포트 이름이기도 하며, 여기서는 나머지 두 설정과 함께 명시적으로 작성되었습니다. 위의 Ingress가 라우팅하는 http 포트는 /metrics에 403으로 응답하므로, 그곳을 가리키는 스크레이프는 아무것도 수집하지 못합니다. 메트릭을 제공할지 여부는 Aggregate에서 내리는 개발자의 선택이고, 플랫폼이 얼마나 자주, 어느 포트와 경로에서 스크레이프할지는 여기서 내리는 운영자의 선택입니다.

라우터의 selection — 대상 사이에서 선택하는 방법

core/target-selection으로, 라우터처럼 gateway.aggrega.ai/intelligence: semantic을 지닌 게이트웨이에 첨부됩니다. 라우터가 어떤 방식으로 선택하는지는 애플리케이션이 라우터에 요구하는 것의 일부이므로, 개발자가 Aggregate에서 strategy를 값으로 지정해 이를 첨부합니다:

components:
router:
features:
selection:
type: core/target-selection
values:
strategy: latency

그리고 Manifest가 이를 이 라우터의 실현에 바인딩합니다:

core/target-selection:1.0.0: helm/target-selection-litellm:1.0.0

이것은 자체 파일을 렌더링하지 않습니다. 그 실현은 라우터의 Recipe가 렌더링하는 라우팅 테이블에 설정 하나를 씁니다. 위 data 블록의 마지막 두 줄입니다:

router_settings:
routing_strategy: latency-based-routing

이 설정이 있으면 프록시는 assistant에 대한 각 요청을, 최근 열 번의 응답이 평균적으로 가장 짧은 시간이 걸린 항목으로 보냅니다. 응답이 토큰 수를 보고하는 경우 출력 토큰당 시간으로 계산하며, 아직 시도되지 않은 항목은 가장 빠른 것으로 간주되므로 평균이 결정하기 전에 각 항목이 한 번씩 시도됩니다. Aggregate에서 첨부를 제거하고 다시 빌드하면, 빌드는 여전히 12개의 파일을 보고하고 라우팅 테이블의 ConfigMap은 정확히 그 두 줄만 다릅니다. 라우터의 Recipe는 자체 전략을 쓰지 않으며, 전략이 없으면 프록시는 두 항목 중 무작위로 선택합니다.

대신 strategy: cost를 요청하면 빌드가 아무것도 쓰지 않고 중단됩니다. 이 중단은 실현의 어설션 실패인 E0033이며, 그 메시지는 규칙 자체의 문장으로 끝납니다: core/target-selection attachment “selection” on “router” asks for strategy cost, but core/gateway/litellm cannot choose between the entries of its model map by cost: the proxy looks each entry’s target up, exactly as written, in its own price table, which names OpenAI’s and Anthropic’s models without the provider prefix a target carries (gpt-4o, not openai/gpt-4o) and which the proxy may fetch afresh when it starts, and it prices an entry it does not find, and that carries no price of its own, at a fixed fallback, so the entries sharing an alias are priced alike and the choice falls to their order. Ask for strategy latency, or remove the attachment (core/target-selection 첨부 “selection”(“router”)이 strategy cost를 요청하지만, core/gateway/litellm은 모델 맵의 항목 사이에서 비용으로 선택할 수 없습니다. 프록시는 각 항목의 대상을 작성된 그대로 자체 가격표에서 찾는데, 이 가격표는 OpenAI와 Anthropic의 모델을 대상이 지닌 공급자 접두사 없이 명명하며(openai/gpt-4o가 아니라 gpt-4o) 프록시가 시작할 때 새로 가져올 수 있습니다. 또한 찾지 못하고 자체 가격도 없는 항목은 고정된 대체 가격으로 매기므로, 별칭을 공유하는 항목들은 같은 가격이 매겨지고 선택은 순서에 따르게 됩니다. strategy latency를 요청하거나 첨부를 제거하십시오). 여기의 두 대상은 모두 그렇게 작성되어 있으므로, Aggregate가 비용을 요청했는데도 프록시는 모든 요청을 그중 첫 번째로 보내게 됩니다.

컴파일러가 해석하지 않는 부분

에이전트의 주소와 모델 이름은 라우터가 게시하는 내용에서 읽어 오므로, 세 파일 안의 어떤 이름 쌍도 직접 맞춰 둘 필요가 없습니다. 빌드가 실제로 검사하는 것은 라우터가 게시하는 별칭이 그 맵이 게시하는 별칭 중 하나여야 한다는 라우터 자체의 규칙입니다. 이 규칙은 엔티티가 지니는 다른 모든 어서션과 마찬가지로 해당 Component가 선언하고 빌드가 평가합니다.

나머지는 한 곳에서 다른 곳으로 전달되는 문자열입니다. 컴파일러는 주소와 별칭을 읽지 않고 전달합니다. 컴파일러는 하나가 호스트 이름이고 다른 하나가 모델 이름이라는 것을 알지 못하며, router-default:4000에서 무언가가 응답하는지 확인할 실행 중인 클러스터에 접근할 수도 없습니다. 라우터를 받아들인 model.aggrega.ai/api 레이블도 같은 종류의 문자열입니다. 소켓의 셀렉터가 이를 매칭할 뿐, 그곳에서 실제로 어떤 API가 응답하는지는 아무것도 검사하지 않습니다. 그리고 맵의 모든 target은 실행 중인 프록시가 해석하는 포인터입니다. openai/gpt-4o를 openai/not-a-real-model로 바꾸어도 빌드는 여전히 성공하며, 실패는 요청 시점에 나타납니다.

이 예제의 나머지 부분을 작동하게 하는 것도 같은 속성입니다. 컴파일러가 전달하는 내용을 해석하지 않기 때문에, 라우터가 다른 공급자를 가리키도록 바꿀 수 있고, 에이전트를 다른 라우터에 연결할 수 있으며, 자격 증명 구현을 저장소 기반 구현으로 교체할 수 있습니다. 이 모든 것이 컴파일러가 그 어느 것도 이해할 필요 없이, 그리고 에이전트를 바꾸지 않고 이루어집니다.

응용하기

  • provider 대상 바꾸기. 라우터 맵의 target을 수정합니다. 그 밖에는 아무것도 바뀌지 않습니다. 모델도, 에이전트도, 렌더링된 Secret도 바뀌지 않습니다.

  • 세 번째 provider 추가하기. 맵 항목을 하나 추가합니다. 그 항목이 기존 별칭을 게시하면 전략은 세 대상 중에서 선택하기 시작합니다. 새 별칭을 게시하면 맵은 두 개의 별칭을 게시하고, 라우터의 values.model은 에이전트에 전달되는 별칭을 지정합니다. 다른 별칭을 원하는 호출자는 이름으로 요청합니다. 카탈로그가 모델링하는 모델 중 API가 OpenAI API인 모델은 대신 라우터의 models 소켓에 연결할 수 있으며, 이때 자체 별칭을 사용하고 해당 연결이 지닌 키를 제시합니다. 그러면 values.model은 에이전트에 전달되는 별칭을 지정합니다.

  • 자격 증명을 저장소에서 가져오기. core/referenced-secret을 바인딩하는 Manifest의 한 줄을 helm/k8s-external-secret으로 바꾸고 다시 빌드합니다. 렌더링된 각 Secret은 클러스터 시크릿 저장소의 항목을 지정하는 ExternalSecret이 되어 저장소 오퍼레이터가 조정하게 됩니다. 그리고 모든 소비자의 렌더링된 참조는 바이트 단위로 동일하게 유지됩니다. 로케이터는 양쪽이 합의하는 것이 아니라 생산하는 쪽이 게시하기 때문입니다. 빌드가 성공하기 위해 세 파일에서 그 밖에 바꿔야 할 것은 없습니다.

    다만 이 교체가 의미를 가지려면 먼저 다시 작성해야 할 것이 하나 있습니다. origin의 의미가 두 구현 사이에서 달라집니다. 이 워크스페이스의 구현은 이를 저장할 값으로 읽고, 다른 구현은 가져올 키로 읽습니다. origin 값을 다시 살펴보지 않고 그 줄만 바꾸면 렌더링된 remoteRef.key는 값 자리에 들어 있던 플레이스홀더가 됩니다. 여기서는 dev-router-admin-key-change-me입니다. 그러면 출력 트리의 어디에도 그 문자열을 자격 증명 자료로 보관하지는 않지만, 존재하지 않는 항목을 지정하는 저장소 키로서 여전히 남아 있습니다.

  • 라우터 제거하기. 에이전트의 model 엣지가 대신 provider별 모델 component를 가리키게 합니다. 그러면 에이전트가 provider 자격 증명을 직접 보유하게 되며, 이는 라우터가 없애기 위해 존재하는 바로 그 절충입니다.

  • 카탈로그가 모델링하지 않는 라우터에 연결하기. 에이전트의 model 엣지가 core/ai-model/openai-compatible component를 가리키게 하고, Release에서 그 라우터의 주소를 해당 component의 infra.endpoint에 작성합니다. 그 component 뒤에서는 클러스터 안에서 아무것도 실행되지 않으므로, 주소를 작성하고 그 주소가 가리키는 서비스와 일치하도록 유지하는 일은 운영자의 몫입니다.

여러 소비자의 연결에서 하나의 자격 증명을 공유하는 방법은 model-api-key-sharing을 참조하십시오. 어떤 카탈로그 엔티티도 선언하지 않는 소켓은 adhoc-uses-socket을 참조하십시오.