Dowiedz się, jak tworzyć plik konfiguracyjny bramy modelu i nim zarządzać, w tym ustawienia dostawców, definicje modeli, zarządzanie danymi uwierzytelniającymi, konfigurację TLS i przykłady wdrożeń dla obsługiwanych dostawców modeli.

Brama modelu umożliwia IBM Bob samodzielnie wdrożonemu łączenie się i kierowanie żądań do obsługiwanych modeli AI u różnych dostawców, w tym punktów końcowych zgodnych z OpenAI, AWS Bedrock i Google Vertex AI. Konfiguracja bramy modelu definiuje punkty końcowe modeli, ustawienia uwierzytelniania, zachowanie routingu i możliwości modeli, podczas gdy poufne dane uwierzytelniające i certyfikaty są bezpiecznie zarządzane przez config.yaml.

Konfiguracja bramy modelu to plik YAML, który definiuje, z jakimi modelami brama się łączy i jak uwierzytelniać się u każdego dostawcy.

Ostrzeżenie:

Konfiguruj tylko jeden główny model wnioskowania w bramie modelu naraz. Konfigurowanie wielu głównych modeli jednocześnie nie jest obsługiwane i prowadzi do niezdefiniowanego zachowania.

Specyfikacja modelu

Każdy wpis na liście models musi mieć unikalną wartość model_name. Pełna specyfikacja modelu to:

- model_name: example_model
  # Typy dostawców (wybierz jeden dla każdego modelu):
  openai_compatible:  # — dowolny punkt końcowy REST zgodny z OpenAI (Azure, vLLM, …)
  bedrock:            # — punkt końcowy invoke AWS Bedrock
  vertex:             # — Google Vertex AI (Gemini)

  # Metadane modelu
  model_info:
    exposed: true                         # true: widoczny na liście /v1/model/info; false: tylko wewnętrzny
    provider: openai                      # dostawca modelu (np. openai, anthropic, google, nvidia, mistral)
    family: gpt                           # rodzina modeli u dostawcy (np. gpt, sonnet, gemini)
    version: "5.6-sol"                    # ciąg wersji modelu (patrz tabela poniżej)
    max_input_tokens: 270000              # rozmiar okna kontekstu
    max_output_tokens: 20000              # maksymalna liczba tokenów generowanych przez model
    supports_prompt_caching: true         # true jeśli model obsługuje buforowanie promptów
    supports_vision: true                 # true jeśli model obsługuje obrazy
    mode: chat                            # chat | embedding | image_generation

  # Opcjonalne dowolne parametry żądania dołączane do każdego żądania wysyłanego do
  # dostawcy, w tym standardowe parametry (np. temperature, top_p,
  # max_tokens) i rozszerzenia specyficzne dla dostawcy (np. top_k,
  # repetition_penalty, anthropic_beta).
  chat_inference_params:
    temperature: 0.7
    top_p: 0.9

Uwaga:

Aby użytkownicy mogli wysyłać obrazy w interfejsie czatu, główny model wnioskowania musi mieć ustawione supports_vision: true w bloku model_info. Jeśli ta flaga jest nieobecna lub ma wartość false, wprowadzanie obrazów nie będzie dostępne.

Ostrzeżenie:

Jeśli supports_vision jest ustawione na true dla modelu, który faktycznie nie obsługuje obrazów, użycie obrazów zakończy się błędem dostawcy. Upewnij się, że ta flaga jest włączona tylko dla modeli obsługujących obrazy. Następujące modele nie obsługują obrazów i powinny mieć supports_vision: false: Laguna S2.1 i Nvidia Nemotron 3.

Obsługiwane wartości `provider` / `family` / `version`

Bob używa pól provider, family i version łącznie do wyboru dostrojenia promptów i optymalizacji specyficznych dla modelu. Dla niewymienionych modeli użyj najbliżej pasujących wartości.

`provider`	`family`	`version`	Przykładowe ID modelu
`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`

Zarezerwowane sloty nazw modeli

Następujące wartości model_name muszą być obecne na liście models:

`model_name`	Używane do
`premium-ide`	Domyślny model do interaktywnego czatu
`security`	Kontrole guardrail / bezpieczeństwa
`background`	Zadania w tle i autonomicznego agenta

Szablon definiuje security i background jako aliasy scalania YAML aktywnego modelu, dzięki czemu wszystkie automatycznie stosują tę samą konfigurację dostawcy. Dla security i background zalecany jest mniejszy i bardziej wydajny model, jeśli jest dostępny (na przykład openai/gpt-oss-20b).

Dostawcy

`openai_compatible`

Łączy się z dowolnym zewnętrznie hostowanym modelem z REST API zgodnym z OpenAI (na przykład Azure OpenAI, vLLM, niestandardowe punkty końcowe).

- model_name: premium-ide
  openai_compatible:
    model: gpt-5.6-sol                     # ID modelu oczekiwane przez dostawcę
    base_url: https://<resource>.cognitiveservices.azure.com/openai
    api_key: env.AZURE_API_KEY             # env.<VAR> odczytuje z sekretów bramy modelu
    extra_headers:                         # Dodatkowe nagłówki dołączane podczas wnioskowania
      example_header: env.HEADER_VALUE
    ca_cert_pem: env.CA_CERT               # Certyfikat CA do weryfikacji TLS
  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`

Łączy się z modelem serwowanym przez AWS Bedrock.

- model_name: premium-ide
  bedrock:
    model: us.anthropic.claude-sonnet-5    # ID modelu oczekiwane przez dostawcę
    region: us-east-1                      # Region AWS, w którym znajduje się punkt końcowy Bedrock
    access_key_id: env.AWS_ACCESS_KEY      # ID klucza dostępu Bedrock
    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`

Łączy się z modelem serwowanym przez Google Vertex AI (Gemini). Dane uwierzytelniające muszą być podane jako ciąg JSON konta usługi zakodowany w base64.

- model_name: premium-ide
  vertex:
    model: gemini-3.6-flash                # ID modelu oczekiwane przez dostawcę
    project: <gcp-project-id>              # ID projektu GCP
    location: global                       # Region Vertex AI / "global" dla Global API
    credentials: env.GEMINI_CREDENTIALS    # JSON konta usługi, zakodowany w 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

Routery

Sekcja routers konfiguruje rozwiązywanie modeli między frontendem a backendem. Skonfigurowany default_model będzie głównym LLM używanym podczas interakcji w czacie.

routers:
  - name: router
    strategy: static
    static:
      default_model: premium-ide   # musi odpowiadać model_name na liście modeli

Pole	Opis
`name`	Nazwa routera (zawsze używaj `router`)
`strategy`	Strategia routingu. Obecnie obsługiwana jest tylko `static`
`static.default_model`	Wartość `model_name` używana jako główny LLM. Musi dokładnie odpowiadać wpisowi `model_name` na liście `models`

Uwaga:

premium-ide to wymagany slot nazwy modelu (patrz Zarezerwowane sloty nazw modeli), dlatego zalecana praktyka polega na pozostawieniu default_model: premium-ide i zmienianiu tego, na jaki dostawca/model wskazuje wpis premium-ide na liście models.

Kotwice YAML

Konfiguracja bramy modelu obsługuje standardowe kotwice YAML (&name) i klucze scalania (<<: *name). Szablon używa tego mechanizmu do obsługi ponownego użycia i unikania powtórzeń.

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               # nadpisuje premium-ide ze scalonej kotwicy

  - <<: *chat_llm
    model_name: background

Zarządzanie danymi uwierzytelniającymi i sekretami

Sekrety

Dla sekretów odwoływanych w konfiguracji modelu (klucze API, hasła, certyfikaty) skonfiguruj je w pliku instalacyjnym config.yaml w sekcji bob.modelGateway.secrets. Sekrety są montowane do kontenera usługi wnioskowania w czasie uruchamiania.

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

Odwołuj się do sekretu w konfiguracji modelu przy użyciu składni env.<VAR_NAME>:

api_key: env.VAR_BAR_1

Wymagania TLS i certyfikaty

W przypadku korzystania z prywatnych punktów końcowych lub wewnętrznych serwerów modeli (na przykład vLLM lub OpenShift AI z niestandardowymi lub samopodpisanymi certyfikatami przedsiębiorstwa) musisz dostarczyć wewnętrzny certyfikat Root/Intermediate CA, aby kontenery wnioskowania mogły ustanowić zaufanie TLS.

Uwaga:

Ta konfiguracja TLS punktu końcowego modelu jest oddzielna od certyfikatu wymaganego przez Bob IDE i Bob Shell do połączenia z backendem Bob. Kroki dotyczące certyfikatu punktu końcowego backendu i zaufania po stronie klienta można znaleźć w artykule Certyfikaty TLS.

Istnieją dwa sposoby dodania CA dla wnioskowania:

Opcja 1 — Pakiet zaufania dla wnioskowania (zalecane)

Dodaj CA do bob-inferencing-bundle-tls, etykietując sekret Kubernetes. Operator wykrywa etykietę i automatycznie przebudowuje pakiet — nie są wymagane żadne zmiany konfiguracji bramy modelu, a CA jest natychmiast dostępne dla wszystkich kontenerów wnioskowania.

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>

Sekret bob-inferencing-bundle-tls jest montowany do kontenerów wnioskowania jako ich magazyn zaufania. Zawsze zawiera wszystko z bob-bundle-tls oraz wszelkie dodatkowo etykietowane sekrety. Restart podów nie jest potrzebny — sekrety są projektowane do działającego kontenera.

Pełne szczegóły i kroki weryfikacji można znaleźć w artykule Certyfikaty TLS.

Opcja 2 — `ca_cert_pem` dla poszczególnych modeli (konfiguracja bramy modelu)

Użyj tej opcji, gdy musisz dostarczyć CA dla jednego konkretnego punktu końcowego modelu bez wpływu na inne kontenery wnioskowania. Niestandardowe certyfikaty TLS stosują ten sam wzorzec konfiguracji rozdzielonej na dwa pliki, co dane uwierzytelniające API:

W model-gateway.yaml: Ustaw ca_cert_pem na nazwę zmiennej środowiskowej (na przykład env.CA_CERT).

W config.yaml: Dodaj pasującą nazwę zmiennej w sekcji bob.modelGateway.secrets i wklej pełny ciąg certyfikatu zakodowany w formacie PEM.

1. Konfiguracja bramy modelu (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           # Wskazuje na nazwę zmiennej zdefiniowaną w config.yaml
    model_info:
      exposed: true
      mode: chat

2. Konfiguracja instalacji (config.yaml):

bob:
  modelGateway:
    secrets:
      MODEL_API_KEY: "<your-api-key>"
      # Rzeczywista zawartość certyfikatu PEM odpowiadająca env.CA_CERT powyżej:
      CA_CERT: |
        -----BEGIN CERTIFICATE-----
        MIIFazCCA1OgAwIBAgIRAIIQjJaDSmJT3g4qg05...
        ... [pełne dane certyfikatu CA zakodowane w PEM] ...
        -----END CERTIFICATE-----

Podczas wdrożenia bobctl wstrzykuje CA_CERT do sekretu Kubernetes bob-inference-model-secrets. Jest on następnie montowany do kontenera usługi bramy wnioskowania i używany do uzgadniania TLS z prywatnym serwerem modelu.

Pełny przykład

Poniżej znajduje się pełny przykład odzwierciedlający strukturę config-model-gateway-template.yaml z pakietu Bob Bundle. Zapisz go do pliku (na przykład /tmp/example/model-gateway.yaml) i odwołaj się do niego w czasie instalacji.

Konfiguracja bramy modelu

# ── Definicje dostawców ───────────────────────────────────────────────────────
# Klucz x-providers jest ignorowany przez bramę modelu — jest to skratchpad YAML
# z przykładami dostawców. Poniżej odwoływana jest tylko kotwica aktywnego dostawcy.
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

  # Niestandardowa usługa wnioskowania (RHOAI, vLLM itp.)
  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

# ── Modele ────────────────────────────────────────────────────────────────────
models:

  # ── AKTYWNY MODEL ─────────────────────────────────────────────────────────────
  # Zmień <<: *bedrock na np. *azure, *gemini lub *isvc, aby przełączyć dostawcę.
  - &chat_llm
    <<: *bedrock                       # ← zmień dostawcę tutaj
    model_name: premium-ide
    model_info:
      exposed: true

  # ── Aliasy ───────────────────────────────────────────────────────────────────
  - <<: *chat_llm
    model_name: security               # nadpisuje premium-ide ze scalonej kotwicy

  - <<: *chat_llm
    model_name: background

# ── Router ────────────────────────────────────────────────────────────────────
routers:
  - name: router
    strategy: static
    static:
      default_model: premium-ide

Sekrety (`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>

Polecenie instalacji

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

W środowisku z dostępem do internetu podaj klucz uprawnień dla icr.io. --registry-creds można pominąć tylko wtedy, gdy masz prywatny rejestr niewymagający uwierzytelnienia podczas pobierania.

Wdrażanie konfiguracji

Podczas wstępnej instalacji

Podaj ścieżkę do pliku konfiguracyjnego bramy modelu przy użyciu flagi --model-config w czasie instalacji:

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

Ostrzeżenie:

Jeśli bobctl install zostanie uruchomiony bez --model-config, Bob jest instalowany z pustą konfiguracją bramy modelu. Usługa wnioskowania działa, ale nie ma połączenia z żadnym modelem. Użyj bobctl update-model-config po instalacji, aby przesłać konfigurację modelu do klastra.

Jak dane uwierzytelniające są wdrażane do klastra

Plik konfiguracyjny bramy modelu odwołuje się do danych uwierzytelniających jako zmiennych środowiskowych (na przykład env.AWS_ACCESS_KEY, env.AZURE_API_KEY). Różni dostawcy modeli wymagają różnych sekretów — klucze IAM AWS dla Bedrock, klucze API dla Azure OpenAI lub JSON konta usługi dla Google Gemini.

Podczas instalacji te dane uwierzytelniające są podawane w config.yaml w sekcji bob.modelGateway.secrets. CLI bobctl automatycznie przetwarza tę sekcję i tworzy sekret Kubernetes o nazwie bob-inference-model-secrets w klastrze, montując klucze jako zmienne środowiskowe bezpośrednio wewnątrz kontenera usługi bramy wnioskowania.

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

      # Uwierzytelnianie Azure OpenAI
      AZURE_API_KEY: "<your-azure-api-key>"

      # Uwierzytelnianie Google Cloud Vertex AI / Gemini
      GEMINI_CREDENTIALS: "<your-gemini-credentials-json>"

      # Niestandardowe klucze API punktów końcowych / tokeny lub wewnętrzne uwierzytelnianie proxy
      # RITS_APIKEY: "<your-api-key>"

      # Niestandardowy certyfikat CA w formacie PEM dla prywatnych punktów końcowych z podpisem własnym
      # CA_CERT: |
      #   -----BEGIN CERTIFICATE-----
      #   ...
      #   -----END CERTIFICATE-----

Aktualizacja konfiguracji po instalacji (`bobctl update-model-config`)

Użyj bobctl update-model-config, aby przesłać konfigurację bramy modelu i/lub sekrety do działającego klastra bez ponownej instalacji. Jest to wymagana ścieżka, gdy bobctl install został uruchomiony bez --model-config, i to samo polecenie używane podczas przełączania głównego modelu wnioskowania.

Wewnętrznie uruchamia helm template na szablonach model-config.yaml i model-secrets.yaml w lokalnym chartcie ibm-bob, a następnie stosuje wyrenderowane manifesty do klastra. Po zastosowaniu operator ibm-bob uzgadnia wdrożenie bob-inference z nową konfiguracją modelu.

Polecenie zarządza dwoma oddzielnymi zasobami klastra:

Flaga	Zasób klastra	Źródło
`--model-config <file>`	`ConfigMap` `bob-inference-model-config`	Plik podany jako argument
`--update-secrets`	`Secret` `bob-inference-model-secrets`	`bob.modelGateway.secrets` w `config.yaml`

Co najmniej jeden z dwóch musi zostać podany — niepodanie żadnego jest błędem.

Wymagania wstępne:

Musisz być zalogowany do klastra (oc login)

config.yaml musi istnieć obok bobctl (skopiuj z config-template.yaml)

helm ≥ 3.14.0 musi być dostępny w PATH

Typowe użycie:

# Aktualizuj tylko plik konfiguracyjny modelu
bobctl update-model-config --model-config ./my-model-config.yaml

# Aktualizuj tylko sekrety (klucze pochodzą z config.yaml)
bobctl update-model-config --update-secrets

# Aktualizuj oba jednocześnie
bobctl update-model-config --model-config ./my-model-config.yaml --update-secrets

# Podgląd tego, co zostałoby zastosowane, bez dotykania klastra
bobctl update-model-config --model-config ./my-model-config.yaml --update-secrets --dry-run

Wszystkie flagi:

Flaga	Domyślna	Opis
`--model-config <file>`		Ścieżka do pliku konfiguracyjnego modelu do przesłania do ConfigMap
`--update-secrets`		Przesyła `bob.modelGateway.secrets` z `config.yaml` do sekretu
`--output-config <file>`	`model-gateway-config.yaml`	Gdzie zapisać wyrenderowany manifest ConfigMap
`--output-secret <file>`	`model-gateway-secret.yaml`	Gdzie zapisać wyrenderowany manifest sekretu
`--cleanup`	false	Usuwa wyrenderowane pliki manifestów po ich zastosowaniu
`--dry-run`	false	Wyświetla to, co zostałoby uruchomione, bez wykonywania żadnych poleceń `oc`

Konfiguracja bramy modelu

Na tej stronie