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

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

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

경고:

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

모델 사양

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

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

  # 모델 메타데이터
  model_info:
    exposed: true                         # true: /v1/model/info 목록에 표시; false: 내부 전용
    provider: openai                      # 모델 제공자 (예: openai, anthropic, google, nvidia, mistral)
    family: gpt                           # 제공자 내 모델 패밀리 (예: gpt, sonnet, gemini)
    version: "5.6-sol"                    # 모델 버전 문자열 (아래 표 참조)
    max_input_tokens: 270000              # 컨텍스트 윈도우 크기
    max_output_tokens: 20000              # 모델이 생성할 수 있는 최대 토큰 수
    supports_prompt_caching: true         # 모델이 프롬프트 캐싱을 지원하는 경우 true
    supports_vision: true                 # 모델이 이미지 입력을 지원하는 경우 true
    mode: chat                            # chat | embedding | image_generation

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

참고:

사용자가 채팅 인터페이스에서 이미지를 전송하려면 핵심 추론 모델의 model_info 블록에 supports_vision: true가 설정되어 있어야 합니다. 이 플래그가 없거나 false이면 이미지 입력을 사용할 수 없습니다.

경고:

이미지 입력을 실제로 지원하지 않는 모델에 supports_vision을 true로 설정하면 이미지 사용 시 제공자 오류가 발생합니다. 이미지 입력을 지원하는 모델에만 이 플래그를 활성화하세요. 다음 모델은 이미지 입력을 지원하지 않으므로 supports_vision: false를 사용해야 합니다: Laguna S2.1 및 Nvidia Nemotron 3.

지원되는 `provider` / `family` / `version` 값

Bob은 provider, family, version 필드를 함께 사용하여 모델별 프롬프트 튜닝 및 최적화를 선택합니다. 목록에 없는 모델의 경우 가장 가까운 값을 사용하세요.

`provider`	`family`	`version`	모델 ID 예시
`openai`	`gpt`	`5.6-sol`	`gpt-5.6-sol`
`openai`	`gpt-oss`	`20b`	`openai/gpt-oss-20b`
`anthropic`	`sonnet`	`5`	`us.anthropic.claude-sonnet-5`
`google`	`gemini`	`3.6-flash`	`gemini-3.6-flash`
`google`	`gemini`	`3.1-pro`	`gemini-3.1-pro`
`nvidia`	`nemotron`	`3-ultra`	`nvidia/nemotron-3-ultra-550b`
`mistral`	`medium`	`3.5`	`mistralai/mistral-medium-3-5-0`
`poolside`	`laguna`	`s2.1`	`poolside/laguna-s-2.1`

예약된 모델 이름 슬롯

다음 model_name 값은 models 목록에 반드시 있어야 합니다:

`model_name`	용도
`premium-ide`	대화형 채팅의 기본 모델
`security`	가드레일 / 보안 검사
`background`	백그라운드 및 자율 에이전트 작업

템플릿은 security와 background를 활성 모델의 YAML 병합 앨리어스로 정의하므로 모두 동일한 제공자 구성을 자동으로 따릅니다. security와 background의 경우 사용 가능한 경우 더 작고 효율적인 모델(예: openai/gpt-oss-20b)을 권장합니다.

제공자

`openai_compatible`

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

- model_name: premium-ide
  openai_compatible:
    model: gpt-5.6-sol                     # 제공자가 예상하는 모델 ID
    base_url: https://<resource>.cognitiveservices.azure.com/openai
    api_key: env.AZURE_API_KEY             # env.<VAR>는 모델 게이트웨이 시크릿에서 읽습니다
    extra_headers:                         # 추론 시 포함할 추가 헤더
      example_header: env.HEADER_VALUE
    ca_cert_pem: env.CA_CERT               # TLS 검증용 CA 인증서
  model_info:
    exposed: true
    provider: openai
    family: gpt
    version: "5.6-sol"
    max_input_tokens: 270000
    max_output_tokens: 20000
    supports_prompt_caching: true
    supports_vision: true
    mode: chat

`bedrock`

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

- model_name: premium-ide
  bedrock:
    model: us.anthropic.claude-sonnet-5    # 제공자가 예상하는 모델 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
  model_info:
    exposed: true
    provider: anthropic
    family: sonnet
    version: "5"
    max_input_tokens: 270000
    max_output_tokens: 20000
    supports_prompt_caching: true
    supports_vision: true
    mode: chat

`vertex`

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

- model_name: premium-ide
  vertex:
    model: gemini-3.6-flash                # 제공자가 예상하는 모델 ID
    project: <gcp-project-id>              # GCP 프로젝트 ID
    location: global                       # Vertex AI 리전 / Global API의 경우 "global"
    credentials: env.GEMINI_CREDENTIALS    # 서비스 계정 JSON (base64 인코딩)
  model_info:
    exposed: true
    provider: google
    family: gemini
    version: "3.6-flash"
    max_input_tokens: 270000
    max_output_tokens: 20000
    supports_prompt_caching: true
    supports_vision: true
    mode: chat

라우터

routers 섹션은 프론트엔드와 백엔드 간의 모델 해석을 구성합니다. 구성된 default_model은 채팅 상호 작용 중에 사용되는 기본 LLM입니다.

routers:
  - name: router
    strategy: static
    static:
      default_model: premium-ide   # models 목록의 model_name과 일치해야 합니다

필드	설명
`name`	라우터 이름 (항상 `router` 사용)
`strategy`	라우팅 전략. 현재는 `static`만 지원됩니다
`static.default_model`	기본 LLM으로 사용할 `model_name`. `models` 목록의 `model_name` 항목과 정확히 일치해야 합니다

참고:

premium-ide는 필수 모델 이름 슬롯입니다(예약된 모델 이름 슬롯 참조). 따라서 권장 방법은 default_model: premium-ide를 유지하고 models 목록에서 premium-ide 항목이 가리키는 제공자/모델을 변경하는 것입니다.

YAML 앵커

Model Gateway 구성은 표준 YAML 앵커(&name)와 병합 키(<<: *name)를 지원합니다. 템플릿은 이를 사용하여 재사용을 지원하고 반복을 방지합니다.

x-providers:
  gemini: &gemini
    vertex:
      model: gemini-3.6-flash
      project: <gcp-project-id>
      location: global
      credentials: env.GEMINI_CREDENTIALS
    model_info:
      exposed: true
      provider: google
      family: gemini
      version: "3.6-flash"
      max_input_tokens: 270000
      max_output_tokens: 20000
      supports_prompt_caching: true
      supports_vision: true
      mode: chat

models:
  - &chat_llm
    <<: *gemini
    model_name: premium-ide

  - <<: *chat_llm
    model_name: security               # 병합된 앵커의 premium-ide를 재정의합니다

  - <<: *chat_llm
    model_name: background

자격 증명 및 시크릿 관리

시크릿

모델 구성에서 참조되는 모든 시크릿(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 및 인증서 요구 사항

프라이빗 엔드포인트 또는 내부 모델 서버(예: 커스텀 또는 자체 서명된 엔터프라이즈 인증서가 있는 vLLM 또는 OpenShift AI)를 사용할 때는 추론 컨테이너가 TLS 신뢰를 설정할 수 있도록 내부 Root/Intermediate CA 인증서를 제공해야 합니다.

참고:

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

추론을 위한 CA를 추가하는 두 가지 방법이 있습니다:

옵션 1 — 추론 신뢰 번들 (권장)

Kubernetes Secret에 레이블을 지정하여 CA를 bob-inferencing-bundle-tls에 추가합니다. 오퍼레이터가 레이블을 감지하고 번들을 자동으로 재구성합니다 — Model Gateway 구성 변경이 필요하지 않으며 CA는 즉시 모든 추론 컨테이너에서 사용할 수 있습니다.

oc create secret generic my-model-endpoint-ca \
  --from-file=tls.crt=model-ca.crt \
  -n <instance-namespace>

oc label secret my-model-endpoint-ca \
  bob.ibm.com/inferencing-bundle-ca=true \
  -n <instance-namespace>

bob-inferencing-bundle-tls Secret은 추론 컨테이너에 신뢰 저장소로 마운트됩니다. bob-bundle-tls의 모든 항목과 추가로 레이블이 지정된 Secret을 항상 포함합니다. 파드 재시작이 필요하지 않습니다 — Secret은 실행 중인 컨테이너에 프로젝션됩니다.

전체 세부 정보 및 검증 단계는 TLS 인증서를 참조하세요.

옵션 2 — 모델별 `ca_cert_pem` (Model Gateway 구성)

다른 추론 컨테이너에 영향을 주지 않고 특정 모델 엔드포인트에 CA를 제공해야 할 때 사용합니다. 커스텀 TLS 인증서는 API 자격 증명과 동일한 2개 파일 분산 구성 패턴을 따릅니다:

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

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

1. Model Gateway 구성 (model-gateway.yaml):

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

2. 설치 구성 (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 핸드셰이크에 사용됩니다.

전체 예제

다음은 Bob Bundle의 config-model-gateway-template.yaml 구조를 그대로 반영한 전체 예제입니다. 파일(예: /tmp/example/model-gateway.yaml)에 저장하고 설치 시 참조하세요.

Model Gateway 구성

# ── 제공자 정의 ────────────────────────────────────────────────────────────────
# x-providers 키는 Model Gateway에서 무시됩니다 — 제공자 예시를 위한 YAML 스크래치패드입니다.
# 활성 제공자의 앵커만 아래에서 참조됩니다.
x-providers:

  # AWS Bedrock
  bedrock: &bedrock
    bedrock:
      model: us.anthropic.claude-sonnet-5
      region: us-east-1
      access_key_id: env.AWS_ACCESS_KEY
      secret_access_key: env.AWS_SECRET_ACCESS_KEY
    model_info:
      exposed: true
      provider: anthropic
      family: sonnet
      version: "5"
      max_input_tokens: 270000
      max_output_tokens: 20000
      supports_prompt_caching: true
      supports_vision: true
      mode: chat

  # Google Vertex AI (Gemini)
  gemini: &gemini
    vertex:
      model: gemini-3.6-flash
      project: <gcp-project-id>
      location: global
      credentials: env.GEMINI_CREDENTIALS
    model_info:
      exposed: true
      provider: google
      family: gemini
      version: "3.6-flash"
      max_input_tokens: 270000
      max_output_tokens: 20000
      supports_prompt_caching: true
      supports_vision: true
      mode: chat

  # Azure OpenAI
  azure: &azure
    openai_compatible:
      model: gpt-5.6-sol
      base_url: https://<resource>.cognitiveservices.azure.com/openai
      api_key: env.AZURE_API_KEY
    model_info:
      exposed: true
      provider: openai
      family: gpt
      version: "5.6-sol"
      max_input_tokens: 270000
      max_output_tokens: 20000
      supports_prompt_caching: true
      supports_vision: true
      mode: chat

  # 커스텀 추론 서비스 (RHOAI, vLLM 등)
  inference_service: &isvc
    openai_compatible:
      model: nvidia/nemotron-3-ultra-550b
      base_url: https://<llm-inference-server>
      api_key: env.INFERENCE_API_KEY
    model_info:
      exposed: true
      provider: nvidia
      family: nemotron
      version: "3-ultra"
      max_input_tokens: 262144
      supports_vision: false
      mode: chat

# ── 모델 ──────────────────────────────────────────────────────────────────────
models:

  # ── 활성 모델 ─────────────────────────────────────────────────────────────────
  # <<: *bedrock를 예: *azure, *gemini, 또는 *isvc로 변경하여 제공자를 전환합니다.
  - &chat_llm
    <<: *bedrock                       # ← 여기서 제공자를 변경합니다
    model_name: premium-ide
    model_info:
      exposed: true

  # ── 앨리어스 ───────────────────────────────────────────────────────────────────
  - <<: *chat_llm
    model_name: security               # 병합된 앵커의 premium-ide를 재정의합니다

  - <<: *chat_llm
    model_name: background

# ── 라우터 ────────────────────────────────────────────────────────────────────
routers:
  - name: router
    strategy: static
    static:
      default_model: premium-ide

시크릿 (`config.yaml`)

bob:
  modelGateway:
    secrets:
      AWS_ACCESS_KEY: "<your-aws-access-key-id>"
      AWS_SECRET_ACCESS_KEY: "<your-aws-secret-access-key>"
      GEMINI_CREDENTIALS: "<base64-encoded service-account JSON>"
      AZURE_API_KEY: "<your-azure-api-key>"
      INFERENCE_API_KEY: "<your-inference-api-key>"
      CA_CERT: <PEM encoded CA cert>

설치 명령

bobctl install --model-config /tmp/example/model-gateway.yaml --accept-license --registry-creds <username:password>

연결된 환경의 경우 icr.io에 대한 자격 증명 키를 지정하세요. 인증이 필요 없는 프라이빗 레지스트리를 사용하는 경우에만 --registry-creds를 생략할 수 있습니다.

구성 배포

초기 설치 중

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

bobctl install --model-config path/to/model-gateway-config.yaml --accept-license --registry-creds <username:password>

경고:

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

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

Model Gateway 구성 파일은 자격 증명을 환경 변수로 참조합니다(예: env.AWS_ACCESS_KEY, env.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 인증
      AZURE_API_KEY: "<your-azure-api-key>"

      # Google Cloud Vertex AI / Gemini 인증
      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을 실행했을 때 필요한 경로이며, 핵심 추론 모델 전환 시에도 동일한 명령을 사용합니다.

내부적으로 로컬 ibm-bob 차트의 model-config.yaml 및 model-secrets.yaml 템플릿에 대해 helm template을 실행한 후 렌더링된 매니페스트를 클러스터에 적용합니다. 적용되면 ibm-bob-operator가 새 모델 구성으로 bob-inference 배포를 조정합니다.

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

플래그	클러스터 리소스	소스
`--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 구성

이 페이지에서