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 on-premises łą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, opcje awaryjne 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, …)
  bedrock:            # — punkt końcowy invoke AWS Bedrock
  vertex:             # — Google Vertex AI (Gemini)

  # Parametry informacji o modelu (opcjonalne)
  model_info:
    exposed: true                          # true: widoczny na liście /models; false: tylko wewnętrzny
    max_input_tokens: 128000               # rozmiar okna kontekstu
    max_output_tokens: 4096                # maksymalna liczba tokenów generowanych przez model
    input_cost_per_token: 0.0000025        # koszt w USD za token wejściowy (używany do pomiaru zużycia)
    output_cost_per_token: 0.000010        # koszt w USD za token wyjściowy
    cache_read_input_token_cost: 0.00      # koszt za tokeny wejściowe trafione z cache (cache promptów)
    cache_creation_input_token_cost: 0.00  # koszt zapisania nowego wpisu w cache
    supports_prompt_caching: true          # true jeśli model obsługuje buforowanie promptów
    supports_function_calling: true        # true jeśli model obsługuje wywołania narzędzi/funkcji
    supports_tool_choice: true             # true jeśli parametr tool_choice jest obsługiwany
    supports_reasoning: false              # true jeśli model obsługuje parametr reasoning_effort
    supports_vision: false                 # true jeśli model akceptuje obrazy w wiadomościach czatu
    mode: chat                             # chat | embedding | image_generation

  # Opcjonalna posortowana lista wartości model_name do wypróbowania, gdy ten model jest niedostępny
  fallbacks:
    - fallback_model

  # 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

Ostrzeżenie:

Ustawiaj supports_vision: true tylko na modelach, które akceptują obrazy. Jeśli supports_vision jest ustawione na true dla modelu, który nie obsługuje obrazów, wysłanie obrazu w czacie spowoduje błąd dostawcy. Następujące modele nie obsługują obrazów i muszą używać supports_vision: false lub pomijać tę flagę: Laguna S2.1 i Nvidia Nemotron 3.

Dostawcy

`openai_compatible`

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

openai_compatible:
  model: gpt-4o                          # ID modelu oczekiwane przez dostawcę
  base_url: https://base_url             # Bazowy URL wdrożenia modelu
  api_key: env.API_KEY                   # Klucz API do uwierzytelniania. env.<VAR> odczytuje ze środowiska kontenera
  extra_headers:                         # Dodatkowe nagłówki dołączane podczas wnioskowania
    example_header: env.HEADER_VALUE
  insecure_skip_verify: true             # Wyłącz weryfikację TLS (niezalecane w środowisku produkcyjnym)
  ca_cert_pem: env.CA_CERT               # Certyfikat CA do weryfikacji TLS

`bedrock`

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

bedrock:
  model: claude                                  # 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   # Tajny klucz dostępu Bedrock

`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.

vertex:
  model: gemini                              # ID modelu oczekiwane przez dostawcę
  project: my-gcp-project                    # ID projektu GCP
  location: global                           # Region Vertex AI / "global" dla Global API
  credentials: env.GEMINI_CREDENTIALS        # JSON konta usługi, zakodowany w base64

Kotwice YAML

Kotwice danych uwierzytelniających

Zdefiniuj dane uwierzytelniające raz i odwołuj się do nich za pomocą <<: *anchor-name w wielu wpisach modelu, aby uniknąć powtórzeń.

# Dane uwierzytelniające AWS Bedrock — odwoływane przez modele 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            # scalanie kotwicy danych uwierzytelniających zdefiniowanej powyżej
    model_info:
      exposed: true
      mode: chat

Kotwice modeli

Scalaj pełny blok modelu w kilku wpisach, aby uniknąć powtarzania konfiguracji dostawcy i 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

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

Główny pakiet CA zawiera standardowe publiczne certyfikaty CA dla dostawców chmurowych. Jednak 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 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.

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.

Konfiguracja bramy modelu:

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

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 obejmujący wszystkie typy dostawców. Zapisz konfigurację bramy modelu do pliku (na przykład /tmp/example/model-gateway.yaml) i odwołaj się do niego w czasie instalacji.

Konfiguracja bramy modelu (/tmp/example/model-gateway.yaml)

# ── Kotwice danych uwierzytelniających (współdzielone między wpisami modeli przez klucze scalania YAML) ──────
# Dane uwierzytelniające 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

# Dane uwierzytelniające Google Vertex AI
x-vertex-auth: &vertex-auth
  project: my-gcp-project
  location: global
  credentials: env.GEMINI_CREDENTIALS

# ── Kotwice wspólnych modeli (opcjonalne) ───────────────────────────────────────────
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

# ── Modele ────────────────────────────────────────────────────────────────────
models:
  # Model zgodny z OpenAI (np. Azure OpenAI) z kluczem API
  - 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

  # Model AWS Bedrock
  - model_name: my-bedrock-model
    bedrock:
      model: us.anthropic.claude-3-5-sonnet-20241022-v2:0
      <<: *aws-bedrock-auth
    fallbacks:                          # opcjonalne: posortowana lista nazw modeli awaryjnych
      - 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

  # Model Google Vertex AI (Gemini) używający wspólnej kotwicy modelu
  - model_name: my-gemini-model
    <<: *my-base-model

  # Model zgodny z OpenAI z niestandardowym certyfikatem CA
  - 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

  # Model zgodny z OpenAI z dodatkowymi nagłówkami
  - 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

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

Polecenie instalacji

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

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

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.BOB_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
      BOB_AZURE_API_KEY: "<your-azure-api-key>"

      # Uwierzytelnianie Google Cloud Vertex AI / Gemini
      BOB_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.

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