F5 AI Gateway 헤더 기반 라우팅 구성 가이드

F5 AI Gateway 는 요청의 헤더 값에 따라 지정한 서비스(모델)로 요청을 라우팅하도록 구성할 수 있습니다. 이를 통해, 사용자의 요청 특성(예: 모델 명시, 사용자 그룹, 기능 요구 등)에 맞는 백엔드 LLM을 선택적으로 사용할 수 있어 효율적인 AI 서비스 운영이 가능합니다.

이 가이드는 Ollama를 백엔드 LLM 서비스로 사용하는 구조를 기반으로 합니다.
Ollama의 설치 및 배포 방법은 Ollama 설치 및 생성형 AI 배포 포스트를 참고하세요.

목차

1. 환경 및 버전 정보
2. F5 AI Gateway 헤더 기반 라우팅 이해
3. Operands를 사용한 조건 분기 설정
4. F5 AI Gateway 헤더 기반 라우팅 설정 및 동작 확인
5. 결론

1. 환경 및 버전 정보

  • Kubernetes: v1.32.2
  • NGINX Plus Ingress Controller: 5.0.0
  • F5 AI Gateway: v1.0.2
  • F5 AI Gateway Helm chart: aigw-0.1.1
  • Ollama: 0.6.5

2. F5 AI Gateway 헤더 기반 라우팅 이해

F5 AI Gateway는 policies 섹션에 selector를 사용하여 HTTP 요청 헤더의 값에 따라 서로 다른 profile로 요청을 라우팅할 수 있습니다. 예시 구성은 아래와 같습니다.

policies:
  - name: chat-policy
    profiles:
      - name: hermes-profile
        selector:
          type: header
          key: Model-Name  # 클라이언트 요청의 헤더 이름
          values:
            - hermes
      - name: tinyllama-profile
        selector:
          type: header
          key: Model-Name
          values:
            - tinyllama

profiles:
  - name: hermes-profile
    services:
      - name: ollama/hermes
  - name: tinyllama-profile
    services:
      - name: ollama/tinyllama

services:
  - name: ollama/hermes
    type: hermes3:8b
    executor: ollama
    config:
      endpoint: "http://192.168.200.129:11434/api/chat"
  - name: ollama/tinyllama
    type: tinyllama:1.1b
    executor: ollama
    config:
      endpoint: "http://192.168.200.129:11434/api/chat"
  • selector: 헤더 값을 사용해 profile을 매칭하기 위해 구성합니다.
  • type: 헤더 기반 매칭을 사용하기 위해 header로 설정합니다.
  • key: 헤더의 키값(이름)을 지정합니다. Role과 같은 커스텀 헤더와 Accept-Language와 같은 표준 헤더를 모두 지원합니다. 대소문자를 구분하지 않고, key: role과 같이 구성 시 Role 헤더에서 값을 얻습니다.
  • values: 헤더의 값을 지정합니다.

policies, profile, service에 대한 설명은 F5 AI Gateway 설정 기초 가이드 포스트를 참고하세요.

3. Operands를 사용한 조건 분기 설정

F5 AI Gateway에서는 operand 값을 사용하여 여러 조건(tag 또는 header 값 등)을 조합해 프로필 또는 서비스 선택 조건을 정교하게 설정할 수 있습니다. 지원되는 operand는 다음과 같습니다:

Operand의미조건 만족 기준
or 또는 anyOR 조건조건 중 하나라도 일치하면 선택됨
and 또는 allAND 조건모든 조건이 일치해야 선택됨
not 또는 noneNOT 조건조건이 일치하지 않아야 선택됨

기본값: operand가 명시되지 않으면 or가 기본으로 적용됩니다.

예시 구성:

policies:
  - name: chat-policy
    profiles:
      - name: llama-de-ja
        selector:
          type: header
          operand: or
          key: Accept-Language
          values:
            - ja
            - de

위 구성은 Accept-Language 헤더에 ja 혹은 de 값이 있으면 llama-de-ja profile로 요청을 라우팅합니다.

policies:
  - name: chat-policy
    profiles:
      - name: llama-de-ja
        selector:
          type: header
          operand: and
          key: Accept-Language
          values:
            - ja
            - de

type: header와 operand: and를 사용할 경우 다음과 같이 요청을 전송해야 조건을 만족합니다.

Accept-Language: ja  
Accept-Language: de

실제 HTTP 클라이언트는 동일 키의 헤더를 다중 라인으로 보내는 기능을 제한할 수 있으므로, and 조건 사용 시 주의가 필요합니다.

다음과 같이 한 줄에 쉼표로 구분되거나 개행으로 구분된 경우, and 조건을 만족하지 못합니다.

Accept-Language: ja, de


Accept-Language: ja\nde
selector의 동작 순서

selector는 정의된 순서대로 평가되며, 첫 번째로 조건에 일치하는 selector를 가진 항목 또는 selector가 없는 항목이 선택됩니다.

services:
  - name: en-llm            # 1순위
    selector:
      operand: not
      tags:
        - language:ja
        - language:de
  - name: multilingual-ll   # 2순위
  • 위 예제에서 language:ja 또는 language:de가 없으면, en-llm이 사용됩니다.
  • 반면, language:ja 또는 language:de가 있으면, 다음 순서인 multilingual-llm이 사용됩니다.
services:
  - name: multilingual-llm  # 1순위 (무조건 매칭)
  - name: en-llm            # 2순위 (매칭되지 않음)
    selector:
      operand: not
      tags:
        - language:ja
        - language:de
  • 위 구성의 경우 multilingual-llm은 selector가 없기 때문에 항상 조건과 상관없이 우선 선택됩니다.
  • en-llm의 selector는 절대 평가되지 않습니다.

따라서 다음과 같은 설정 순서를 따르는 것이 권장됩니다.

  1. selector가 있는 설정을 먼저 배치
  2. 구체적인 조건(selector에 and와 같은 다중 조건)을 앞에 배치
  3. 기본(default) 서비스는 selector 없이 마지막에 배치

이러한 조건 분기 방식과 순서 평가 로직은 header 타입의 selector에도 동일하게 적용되며, 이를 통해 AI Gateway는 복잡한 정책 라우팅 요구를 유연하게 만족시킬 수 있습니다.

4. F5 AI Gateway 헤더 기반 라우팅 설정 및 동작 확인

F5 AI Gateway에 간단한 헤더 기반 라우팅 설정을 적용하고, Postman으로 요청을 전송하여 응답을 확인하겠습니다.

version: 1

server:
  address: :4141

logging:
  level: debug

routes:
  - path: /v1/chat/completions
    policy: chat-policy
    schema: v1/chat_completions  
    timeoutSeconds: 240
  - path: /v1/models
    policy: chat-policy
    schema: v1/models

policies:
  - name: chat-policy
    profiles:
      - name: hermes-profile
        selector:
          type: header
          key: Model-Name  # 클라이언트 요청의 헤더 이름
          values:
            - hermes
      - name: tinyllama-profile
        selector:
          type: header
          key: Model-Name
          values:
            - tinyllama

profiles:
  - name: hermes-profile
    services:
      - name: ollama/hermes
  - name: tinyllama-profile
    services:
      - name: ollama/tinyllama

services:
  - name: ollama/hermes
    type: hermes3:8b
    executor: ollama
    config:
      endpoint: "http://192.168.200.129:11434/api/chat"
  - name: ollama/tinyllama
    type: tinyllama:1.1b
    executor: ollama
    config:
      endpoint: "http://192.168.200.129:11434/api/chat"

Model-Name 헤더를 통해 각 hermes, tinyllama 모델과 연결된 profile로 요청을 라우팅하도록 구성했습니다.

Model-Name 헤더의 값을 hermes로 설정하고 요청을 전송합니다.

F5 AI Gateway 헤더 : hermes 요청
F5 AI Gateway 헤더 : hermes 응답

응답에 사용된 모델을 확인할 수 있습니다.

F5 AI Gateway Pod의 로그에서 응답의 id 값과 매칭되는 로그를 확인하면 profile 선택 로그를 확인할 수 있습니다.

Model-Name 헤더의 값을 tinyllama로 설정하고 요청을 전송합니다.

F5 AI Gateway 헤더 : tinyllama 요청
F5 AI Gateway 헤더 : tinyllama 응답

tinyllama 모델을 사용해 응답한 것을 확인할 수 있습니다.

F5 AI Gateway Pod의 로그에서도 확인할 수 있습니다.

5. 결론

F5 AI Gateway의 헤더 기반 라우팅 기능을 활용하면 다양한 LLM 백엔드를 목적에 맞게 효율적으로 분기할 수 있습니다. selector, operand, profile 구성을 통해 다양한 조건부 라우팅 정책을 정의할 수 있으며, 이를 통해 유연한 서비스 운영이 가능합니다.

운영 중인 AI 서비스에 강력한 보안, 헤더 기반 라우팅과 같은 기능이 필요하신가요? NGINX STORE를 통해 문의하여 F5 AI Gateway with NGINX Integration 서비스를 통해 AI 서비스를 보호하세요.

NGINX STORE를 통한 솔루션 도입 및 기술지원 무료 상담 신청

* indicates required