지원되는 모델 제공자를 위한 제공자 설정, 모델 정의, 자격 증명 관리, TLS 구성 및 배포 예제를 포함하여 Model Gateway 구성 파일을 생성하고 관리하는 방법을 알아봅니다.

Model Gateway를 통해 Bob 온프레미스는 OpenAI 호환 엔드포인트, AWS Bedrock, Google Vertex AI를 포함한 다양한 제공자의 지원되는 AI 모델에 연결하고 요청을 라우팅할 수 있습니다. Model Gateway 구성은 모델 엔드포인트, 인증 설정, 라우팅 동작, 대체(fallback) 옵션 및 모델 기능을 정의하며, 민감한 자격 증명과 인증서는 config.yaml을 통해 안전하게 관리됩니다.

Model Gateway 구성은 게이트웨이가 연결할 모델과 각 제공자에 인증하는 방법을 정의하는 YAML 파일입니다.

경고:

Model Gateway에는 한 번에 하나의 핵심 추론 모델만 구성하세요. 여러 핵심 모델을 동시에 구성하는 것은 지원되지 않으며 정의되지 않은 동작이 발생합니다.

모델 사양

models 목록의 각 항목에는 고유한 model_name이 있어야 합니다. 전체 모델 사양은 다음과 같습니다:

- model_name: example_model
  # 제공자 유형 (모델당 하나 선택):
  openai_compatible:  # — OpenAI 호환 REST 엔드포인트 (Azure 등)
  bedrock:            # — AWS Bedrock invoke 엔드포인트
  vertex:             # — Google Vertex AI (Gemini)

  # 모델 정보 매개변수 (선택 사항)
  model_info:
    exposed: true                          # true: /models 목록에 표시; false: 내부 전용
    max_input_tokens: 128000               # 컨텍스트 윈도우 크기
    max_output_tokens: 4096                # 모델이 생성할 수 있는 최대 토큰 수
    input_cost_per_token: 0.0000025        # 입력 토큰당 USD 비용 (사용량 측정에 사용)
    output_cost_per_token: 0.000010        # 출력 토큰당 USD 비용
    cache_read_input_token_cost: 0.00      # 캐시 히트 입력 토큰 비용 (프롬프트 캐싱)
    cache_creation_input_token_cost: 0.00  # 새 캐시 항목 작성 비용
    supports_prompt_caching: true          # 모델이 프롬프트 캐싱을 지원하는 경우 true
    supports_function_calling: true        # 모델이 도구/함수 호출을 지원하는 경우 true
    supports_tool_choice: true             # tool_choice 매개변수가 준수되는 경우 true
    supports_reasoning: false              # 모델이 reasoning_effort 매개변수를 지원하는 경우 true
    supports_vision: false                 # 모델이 채팅 메시지에서 이미지 입력을 수락하는 경우 true
    mode: chat                             # chat | embedding | image_generation

  # 이 모델을 사용할 수 없을 때 시도할 model_name 값의 선택적 순서 목록
  fallbacks:
    - fallback_model

  # 표준 매개변수(예: temperature, top_p, max_tokens) 및
  # 제공자별 확장(예: top_k, repetition_penalty, anthropic_beta)을 포함하여
  # 제공자에게 전송되는 모든 요청에 추가되는 선택적 자유 형식 요청 매개변수입니다.
  chat_inference_params:
    temperature: 0.7
    top_p: 0.9

경고:

이미지 입력을 허용하는 모델에만 supports_vision: true를 설정하세요. 이미지 입력을 지원하지 않는 모델에 supports_vision을 true로 설정하면 채팅에서 이미지를 전송할 때 제공자 오류가 발생합니다. 다음 모델은 이미지 입력을 지원하지 않으므로 supports_vision: false를 사용하거나 플래그를 생략해야 합니다: Laguna S2.1 및 Nvidia Nemotron 3.

제공자

`openai_compatible`

OpenAI 호환 REST API를 사용하는 외부 호스팅 모델(예: Azure OpenAI, 커스텀 엔드포인트)에 연결합니다.

openai_compatible:
  model: gpt-4o                          # 제공자가 예상하는 모델 ID
  base_url: https://base_url             # 모델 배포의 기본 URL
  api_key: env.API_KEY                   # 인증용 API 키. env.<VAR>는 컨테이너 환경에서 읽습니다
  extra_headers:                         # 추론 시 포함할 추가 헤더
    example_header: env.HEADER_VALUE
  insecure_skip_verify: true             # TLS 검증 비활성화 (프로덕션 환경에는 권장하지 않음)
  ca_cert_pem: env.CA_CERT               # TLS 검증용 CA 인증서

`bedrock`

AWS Bedrock을 통해 제공되는 모델에 연결합니다.

bedrock:
  model: claude                                  # 제공자가 예상하는 모델 ID
  region: us-east-1                              # Bedrock 엔드포인트가 있는 AWS 리전
  access_key_id: env.AWS_ACCESS_KEY              # Bedrock Access Key ID
  secret_access_key: env.AWS_SECRET_ACCESS_KEY   # Bedrock Secret Access Key

`vertex`

Google Vertex AI(Gemini)를 통해 제공되는 모델에 연결합니다. 자격 증명은 base64로 인코딩된 서비스 계정 JSON 문자열로 제공되어야 합니다.

vertex:
  model: gemini                              # 제공자가 예상하는 모델 ID
  project: my-gcp-project                    # GCP 프로젝트 ID
  location: global                           # Vertex AI 리전 / Global API의 경우 "global"
  credentials: env.GEMINI_CREDENTIALS        # 서비스 계정 JSON (base64 인코딩)

YAML 앵커

자격 증명 앵커

자격 증명을 한 번 정의하고 여러 모델 항목에서 <<: *anchor-name으로 참조하여 중복을 피합니다.

# AWS Bedrock 자격 증명 — bedrock 모델에서 참조됨.
x-aws-bedrock-auth: &aws-bedrock-auth
  region: us-east-1
  access_key_id: env.AWS_ACCESS_KEY
  secret_access_key: env.AWS_SECRET_ACCESS_KEY

models:
  - model_name: my-bedrock-model
    bedrock:
      model: claude
      <<: *aws-bedrock-auth            # 위에서 정의한 자격 증명 앵커 병합
    model_info:
      exposed: true
      mode: chat

모델 앵커

여러 항목에 걸쳐 전체 모델 블록을 병합하여 제공자 구성 및 model_info의 반복을 방지합니다.

x-my-base-model: &my-base-model
  vertex:
    model: gemini-2.5-pro
    project: my-gcp-project
    location: global
    credentials: env.GEMINI_CREDENTIALS
  model_info:
    exposed: false
    supports_reasoning: true
    mode: chat

models:
  - model_name: my-gemini-model
    <<: *my-base-model

  - model_name: my-second-gemini-model
    <<: *my-base-model

자격 증명 및 시크릿 관리

시크릿

모델 구성에서 참조되는 모든 시크릿(API 키, 비밀번호, 인증서)은 설치 config.yaml의 bob.modelGateway.secrets 아래에 구성합니다. 시크릿은 런타임 시 Inference Service 컨테이너에 마운트됩니다.

bob:
  modelGateway:
    secrets:
      VAR_BAR_1: FOO_1
      VAR_BAR_2: FOO_2
      VAR_BAR_N: FOO_N

env.<VAR_NAME> 구문을 사용하여 모델 구성에서 시크릿을 참조합니다:

api_key: env.VAR_BAR_1

TLS 및 인증서 요구 사항

루트 CA 번들에는 클라우드 제공자를 위한 표준 공개 CA 인증서가 포함되어 있습니다. 그러나 프라이빗 엔드포인트 또는 내부 모델 서버(예: 커스텀 또는 자체 서명된 엔터프라이즈 인증서가 있는 vLLM 또는 OpenShift AI)를 사용할 때는 TLS 신뢰를 설정하기 위해 내부 Root/Intermediate CA 인증서를 제공해야 합니다.

참고:

이 모델 엔드포인트 TLS 구성은 Bob IDE 및 Bob Shell이 Bob 백엔드에 연결하는 데 필요한 인증서와 별개입니다. 백엔드 엔드포인트 인증서 및 클라이언트 신뢰 단계는 TLS 인증서를 참조하세요.

커스텀 TLS 인증서는 API 자격 증명과 동일한 2개 파일 분산 구성 패턴을 따릅니다:

model-gateway.yaml에서: ca_cert_pem을 환경 변수 이름(예: env.CA_CERT)으로 설정합니다.

config.yaml에서: bob.modelGateway.secrets 아래에 일치하는 변수 이름을 추가하고 전체 PEM 인코딩 인증서 문자열을 붙여넣습니다.

Model Gateway 구성:

models:
  - model_name: example-model
    openai_compatible:
      model: mistral-3.5
      base_url: https://vllm.internal.corp:8000/v1
      api_key: env.MODEL_API_KEY
      ca_cert_pem: env.CA_CERT           # config.yaml에 정의된 변수 이름을 가리킵니다
    model_info:
      exposed: true
      mode: chat

설치 구성 (config.yaml):

bob:
  modelGateway:
    secrets:
      MODEL_API_KEY: "<your-api-key>"
      # 위의 env.CA_CERT와 일치하는 실제 PEM 인증서 내용:
      CA_CERT: |
        -----BEGIN CERTIFICATE-----
        MIIFazCCA1OgAwIBAgIRAIIQjJaDSmJT3g4qg05...
        ... [full PEM-encoded CA certificate data] ...
        -----END CERTIFICATE-----

배포 중에 bobctl은 CA_CERT를 bob-inference-model-secrets Kubernetes Secret에 주입합니다. 그런 다음 이는 추론 게이트웨이 서비스에 마운트되어 프라이빗 모델 서버에 대한 TLS 핸드셰이크에 사용됩니다.

전체 예제

다음은 모든 제공자 유형을 다루는 전체 예제입니다. Model Gateway 구성을 파일(예: /tmp/example/model-gateway.yaml)에 저장하고 설치 시 참조하세요.

Model Gateway 구성 (/tmp/example/model-gateway.yaml)

# ── 자격 증명 앵커 (YAML 병합 키를 통해 모델 항목 간에 공유됨) ──────────────
# AWS Bedrock 자격 증명
x-aws-bedrock-auth: &aws-bedrock-auth
  region: us-east-1
  access_key_id: env.AWS_ACCESS_KEY
  secret_access_key: env.AWS_SECRET_ACCESS_KEY

# Google Vertex AI 자격 증명
x-vertex-auth: &vertex-auth
  project: my-gcp-project
  location: global
  credentials: env.GEMINI_CREDENTIALS

# ── 공유 모델 앵커 (선택 사항) ────────────────────────────────────────────────
x-my-base-model: &my-base-model
  vertex:
    model: gemini-2.5-pro
    <<: *vertex-auth
  model_info:
    exposed: true
    max_input_tokens: 200000
    max_output_tokens: 12000
    input_cost_per_token: 0.00000125
    output_cost_per_token: 0.00001
    cache_read_input_token_cost: 0.000000125
    supports_reasoning: true
    mode: chat

# ── 모델 ──────────────────────────────────────────────────────────────────────
models:
  # API 키를 사용하는 OpenAI 호환 모델 (예: Azure OpenAI)
  - model_name: my-gpt-model
    openai_compatible:
      model: gpt-4o
      base_url: https://<resource>.cognitiveservices.azure.com/openai
      api_key: env.BOB_AZURE_API_KEY
    model_info:
      exposed: true
      max_input_tokens: 128000
      max_output_tokens: 4096
      input_cost_per_token: 0.0000025
      output_cost_per_token: 0.000010
      supports_function_calling: true
      supports_tool_choice: true
      mode: chat
    chat_inference_params:
      temperature: 0.7
      top_p: 0.9

  # AWS Bedrock 모델
  - model_name: my-bedrock-model
    bedrock:
      model: us.anthropic.claude-3-5-sonnet-20241022-v2:0
      <<: *aws-bedrock-auth
    fallbacks:                          # 선택 사항: 대체 모델 이름의 순서 목록
      - my-fallback-model
    model_info:
      exposed: false
      max_input_tokens: 200000
      max_output_tokens: 8192
      input_cost_per_token: 0.000003
      output_cost_per_token: 0.000015
      cache_creation_input_token_cost: 0.00000375
      cache_read_input_token_cost: 0.0000003
      supports_prompt_caching: true
      supports_function_calling: true
      supports_tool_choice: true
      mode: chat
    chat_inference_params:
      temperature: 0.7
      top_k: 50

  # 공유 모델 앵커를 사용하는 Google Vertex AI (Gemini) 모델
  - model_name: my-gemini-model
    <<: *my-base-model

  # 커스텀 CA 인증서를 사용하는 OpenAI 호환 모델
  - model_name: example-model-mini
    openai_compatible:
      model: gpt-4o-mini
      base_url: https://llm-mock-server.ca-tor.containers.appdomain.cloud
      ca_cert_pem: env.CA_CERT
    model_info:
      exposed: true
      max_input_tokens: 131072
      input_cost_per_token: 0.00000015
      output_cost_per_token: 0.0000006
      supports_function_calling: true
      supports_tool_choice: true
      mode: chat

  # 추가 헤더를 사용하는 OpenAI 호환 모델
  - model_name: another-example-model-mini
    openai_compatible:
      model: gpt-4o-mini
      base_url: https://llm-mock-server.ca-tor.containers.appdomain.cloud
      extra_headers:
        model_key: env.MODEL_KEY
    model_info:
      exposed: true
      max_input_tokens: 131072
      input_cost_per_token: 0.00000015
      output_cost_per_token: 0.0000006
      supports_function_calling: true
      supports_tool_choice: true
      mode: chat

시크릿 (config.yaml)

bob:
  modelGateway:
    secrets:
      BOB_AZURE_API_KEY: someapikeyvalue
      AWS_ACCESS_KEY: someapikeyvalue
      AWS_SECRET_ACCESS_KEY: someapikeyvalue
      GEMINI_CREDENTIALS: <base64_vertex_credentials>
      CA_CERT: <PEM encoded CA cert>
      MODEL_KEY: apikeyvalue

설치 명령

bobctl install --model-config /tmp/example/model-gateway.yaml

구성 배포

초기 설치 중

설치 시 --model-config 플래그를 사용하여 Model Gateway 구성 파일의 경로를 전달합니다:

bobctl install --model-config path/to/model-gateway-config.yaml --accept-license

경고:

--model-config 없이 bobctl install을 실행하면 Bob이 빈 Model Gateway 구성으로 설치됩니다. Inference Service는 실행되지만 추론을 위한 모델 연결이 없습니다. 설치 후 bobctl update-model-config를 사용하여 클러스터에 모델 구성을 푸시하세요.

자격 증명이 클러스터에 배포되는 방식

Model Gateway 구성 파일은 자격 증명을 환경 변수로 참조합니다(예: env.AWS_ACCESS_KEY, env.BOB_AZURE_API_KEY). 모델 제공자마다 필요한 시크릿이 다릅니다 — Bedrock의 경우 AWS IAM 키, Azure OpenAI의 경우 API 키, Google Gemini의 경우 서비스 계정 JSON이 필요합니다.

설치 중에 이러한 자격 증명은 config.yaml의 bob.modelGateway.secrets 아래에 제공됩니다. bobctl CLI는 이 섹션을 자동으로 처리하여 클러스터에 bob-inference-model-secrets라는 Kubernetes Secret을 생성하고, 키를 추론 게이트웨이 서비스 컨테이너 내부에 직접 환경 변수로 마운트합니다.

bob:
  modelGateway:
    secrets:
      # AWS Bedrock 인증
      AWS_ACCESS_KEY: "<your-aws-access-key-id>"
      AWS_SECRET_ACCESS_KEY: "<your-aws-secret-access-key>"

      # Azure OpenAI 인증
      BOB_AZURE_API_KEY: "<your-azure-api-key>"

      # Google Cloud Vertex AI / Gemini 인증
      BOB_GEMINI_CREDENTIALS: "<your-gemini-credentials-json>"

      # 커스텀 엔드포인트 API 키/토큰 또는 내부 프록시 인증
      # RITS_APIKEY: "<your-api-key>"

      # 자체 서명된 내부 엔드포인트를 위한 PEM 형식의 커스텀 CA 인증서
      # CA_CERT: |
      #   -----BEGIN CERTIFICATE-----
      #   ...
      #   -----END CERTIFICATE-----

설치 후 구성 업데이트 (`bobctl update-model-config`)

재설치 없이 실행 중인 클러스터에 Model Gateway 구성 및/또는 시크릿을 푸시하려면 bobctl update-model-config를 사용합니다. 이는 --model-config 없이 bobctl install을 실행했을 때 필요한 경로이며, 핵심 추론 모델 전환 시에도 동일한 명령을 사용합니다.

이 명령은 두 개의 개별 클러스터 리소스를 관리합니다:

플래그	클러스터 리소스	소스
`--model-config <file>`	`ConfigMap` `bob-inference-model-config`	전달하는 파일
`--update-secrets`	`Secret` `bob-inference-model-secrets`	`config.yaml`의 `bob.modelGateway.secrets`

둘 중 하나 이상을 제공해야 합니다 — 둘 다 전달하지 않으면 오류가 발생합니다.

전제 조건:

클러스터에 로그인되어 있어야 합니다 (oc login)

config.yaml이 bobctl 옆에 존재해야 합니다 (config-template.yaml에서 복사)

helm ≥ 3.14.0이 PATH에 있어야 합니다

일반적인 사용법:

# 모델 구성 파일만 업데이트
bobctl update-model-config --model-config ./my-model-config.yaml

# 시크릿만 업데이트 (키는 config.yaml에서 가져옴)
bobctl update-model-config --update-secrets

# 둘 다 한 번에 업데이트
bobctl update-model-config --model-config ./my-model-config.yaml --update-secrets

# 클러스터를 수정하지 않고 적용될 내용 미리보기
bobctl update-model-config --model-config ./my-model-config.yaml --update-secrets --dry-run

모든 플래그:

플래그	기본값	설명
`--model-config <file>`		ConfigMap으로 푸시할 모델 구성 파일의 경로
`--update-secrets`		`config.yaml`의 `bob.modelGateway.secrets`를 Secret으로 푸시
`--output-config <file>`	`model-gateway-config.yaml`	렌더링된 ConfigMap 매니페스트를 작성할 위치
`--output-secret <file>`	`model-gateway-secret.yaml`	렌더링된 Secret 매니페스트를 작성할 위치
`--cleanup`	false	적용 후 렌더링된 매니페스트 파일 삭제
`--dry-run`	false	`oc` 명령을 실행하지 않고 실행될 내용 출력

Model Gateway 구성

이 페이지에서