تكوين بوابة النماذج
تعرّف على كيفية إنشاء وإدارة ملف تكوين بوابة النماذج (Model Gateway)، بما في ذلك إعدادات الموفرين، وتعريفات النماذج، وإدارة بيانات الاعتماد، وتكوين TLS، وأمثلة النشر لموفري النماذج المدعومين.
تتيح بوابة النماذج (Model Gateway) لـ Bob ذاتي الاستضافة الاتصال بالنماذج المدعومة وتوجيه الطلبات إليها عبر مختلف موفري الذكاء الاصطناعي، بما في ذلك نقاط النهاية المتوافقة مع OpenAI، وAWS Bedrock، وGoogle Vertex AI. يحدد تكوين بوابة النماذج نقاط نهاية النماذج، وإعدادات المصادقة، وسلوك التوجيه، وإمكانيات النماذج، بينما تُدار بيانات الاعتماد والشهادات الحساسة بأمان من خلال config.yaml.
تكوين بوابة النماذج هو ملف YAML يحدد النماذج التي تتصل بها البوابة وكيفية المصادقة مع كل موفر.
هيّئ نموذج استدلال أساسي واحد فقط في بوابة النماذج في المرة الواحدة. تكوين عدة نماذج أساسية في الوقت نفسه غير مدعوم ويؤدي إلى سلوك غير محدد.
مواصفات النموذج
يجب أن يحتوي كل إدخال في قائمة models على model_name فريد. المواصفات الكاملة للنموذج هي:
- model_name: example_model
# Provider types (pick one per model):
openai_compatible: # — any OpenAI-compatible REST endpoint (Azure, vLLM, …)
bedrock: # — AWS Bedrock invoke endpoint
vertex: # — Google Vertex AI (Gemini)
# Model metadata
model_info:
exposed: true # true: visible in /v1/model/info list; false: internal-only
provider: openai # model provider (e.g. openai, anthropic, google, nvidia, mistral)
family: gpt # model family within the provider (e.g. gpt, sonnet, gemini)
version: "5.6-sol" # model version string (see table below)
max_input_tokens: 270000 # context window size
max_output_tokens: 20000 # maximum tokens the model may generate
supports_prompt_caching: true # true if the model supports prompt caching
supports_vision: true # true if the model supports image inputs
mode: chat # chat | embedding | image_generation
# Optional free-form request parameters appended to every request sent to
# the provider, including standard parameters (e.g. temperature, top_p,
# max_tokens) and provider-specific extensions (e.g. top_k,
# repetition_penalty, anthropic_beta).
chat_inference_params:
temperature: 0.7
top_p: 0.9لكي يتمكن المستخدمون من إرسال مدخلات الصور في واجهة الدردشة، يجب أن يحتوي نموذج الاستدلال الأساسي على supports_vision: true في كتلة model_info الخاصة به. إذا كان هذا الخيار غائبًا أو false، فلن تكون مدخلات الصور متاحة.
إذا تم ضبط supports_vision على true لنموذج لا يدعم مدخلات الصور فعليًا، فإن استخدام الصور سيفشل بخطأ من الموفر. تأكد من تفعيل هذا الخيار فقط على النماذج التي تدعم مدخلات الصور. لاحظ أن النماذج التالية لا تدعم مدخلات الصور ويجب استخدام supports_vision: false معها: Laguna S2.1 و Nvidia Nemotron 3.
قيم provider / family / version المدعومة
يستخدم Bob حقلَي provider وfamily وversion معًا لاختيار ضبط النموذج والتحسينات المحددة له. استخدم أقرب قيمة مطابقة للنماذج غير المدرجة.
provider | family | version | مثال على معرف النموذج |
|---|---|---|---|
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).
موفرو الخدمات (Providers)
openai_compatible
يتصل بأي نموذج مستضاف خارجيًا عبر واجهة برمجة تطبيقات REST متوافقة مع OpenAI (على سبيل المثال، Azure OpenAI، وvLLM، ونقاط النهاية المخصصة).
- model_name: premium-ide
openai_compatible:
model: gpt-5.6-sol # Model ID as expected by the provider
base_url: https://<resource>.cognitiveservices.azure.com/openai
api_key: env.AZURE_API_KEY # env.<VAR> reads from the model gateway secrets
extra_headers: # Extra headers to include when inferencing
example_header: env.HEADER_VALUE
ca_cert_pem: env.CA_CERT # CA certificate for TLS verification
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: chatbedrock
يتصل بنموذج يتم توفيره عبر AWS Bedrock.
- model_name: premium-ide
bedrock:
model: us.anthropic.claude-sonnet-5 # Model ID as expected by the provider
region: us-east-1 # AWS region where your Bedrock endpoint lives
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: chatvertex
يتصل بنموذج يتم توفيره عبر Google Vertex AI (Gemini). يجب توفير بيانات الاعتماد كسلسلة JSON لحساب الخدمة مشفرة بـ base64.
- model_name: premium-ide
vertex:
model: gemini-3.6-flash # Model ID as expected by the provider
project: <gcp-project-id> # GCP project ID
location: global # Vertex AI region / "global" for Global API
credentials: env.GEMINI_CREDENTIALS # Service-account JSON, base64-encoded
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)
يُكوّن قسم routers تحليل النماذج بين الواجهة الأمامية والخلفية. يكون default_model المُكوَّن هو النموذج اللغوي الرئيسي المستخدم أثناء تفاعلات الدردشة.
routers:
- name: router
strategy: static
static:
default_model: premium-ide # must match a model_name in the models list| الحقل | الوصف |
|---|---|
name | اسم الموجّه (استخدم دائمًا router) |
strategy | استراتيجية التوجيه. حاليًا يُدعم فقط static |
static.default_model | model_name المراد استخدامه كنموذج لغوي رئيسي. يجب أن يطابق تمامًا إدخال model_name في قائمة models |
premium-ide هو فتحة اسم نموذج مطلوبة (راجع فتحات أسماء النماذج المحجوزة)، لذا فإن الممارسة الموصى بها هي الإبقاء على default_model: premium-ide وتغيير الموفر/النموذج الذي يشير إليه إدخال premium-ide في قائمة models.
روابط YAML (YAML anchors)
يدعم تكوين بوابة النماذج روابط 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 # overrides premium-ide from the merged anchor
- <<: *chat_llm
model_name: backgroundإدارة بيانات الاعتماد والأسرار
الأسرار
بالنسبة لأي أسرار مشار إليها في تكوين النموذج (مفاتيح API، وكلمات المرور، والشهادات)، قم بتكوينها في ملف التثبيت config.yaml تحت bob.modelGateway.secrets. يتم تركيب الأسرار داخل حاوية خدمة الاستدلال في وقت التشغيل.
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 مع شهادات مؤسسية مخصصة أو موقعة ذاتيًا)، يجب عليك توفير شهادة Root/Intermediate CA الداخلية الخاصة بك حتى تتمكن حاويات الاستدلال من إنشاء ثقة TLS.
تكوين TLS لنقاط نهاية النماذج هذا منفصل عن الشهادة المطلوبة لاتصال Bob IDE وBob Shell بالواجهة الخلفية لـ Bob. للاطلاع على خطوات شهادة نقطة نهاية الواجهة الخلفية وثقة العميل، راجع شهادات TLS.
هناك طريقتان لإضافة CA للاستدلال:
الخيار 1 — حزمة ثقة الاستدلال (موصى به)
أضف CA إلى bob-inferencing-bundle-tls عن طريق وضع تسمية على سر Kubernetes. يكتشف المُشغِّل التسمية ويُعيد بناء الحزمة تلقائيًا — لا توجد تغييرات مطلوبة في تكوين بوابة النماذج ويكون 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 في حاويات الاستدلال كمخزن الثقة الخاص بها. يحتوي دائمًا على كل ما في bob-bundle-tls بالإضافة إلى أي أسرار مُعلَّمة إضافية. لا حاجة لإعادة تشغيل الـ pod — يتم إسقاط الأسرار في الحاوية الجارية.
للاطلاع على التفاصيل الكاملة وخطوات التحقق، راجع شهادات TLS.
الخيار 2 — ca_cert_pem لكل نموذج (تكوين بوابة النماذج)
استخدم هذا عندما تحتاج إلى توفير CA لنقطة نهاية نموذج محددة دون التأثير على حاويات الاستدلال الأخرى. تتبع شهادات TLS المخصصة نفس نمط التكوين الموزع المكون من ملفين مثل بيانات اعتماد API:
- في
model-gateway.yaml: اضبطca_cert_pemعلى اسم متغير بيئة (على سبيل المثال،env.CA_CERT). - في
config.yaml: أضف اسم المتغير المطابق تحتbob.modelGateway.secretsوالصق نص الشهادة الكامل المشفر بصيغة PEM.
1. تكوين بوابة النماذج (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 # Points to the variable name defined in config.yaml
model_info:
exposed: true
mode: chat2. تكوين التثبيت (config.yaml):
bob:
modelGateway:
secrets:
MODEL_API_KEY: "<your-api-key>"
# The actual PEM certificate content matching env.CA_CERT above:
CA_CERT: |
-----BEGIN CERTIFICATE-----
MIIFazCCA1OgAwIBAgIRAIIQjJaDSmJT3g4qg05...
... [full PEM-encoded CA certificate data] ...
-----END CERTIFICATE-----أثناء النشر، يحقن bobctl المتغير CA_CERT في سر Kubernetes المسمى bob-inference-model-secrets. يتم بعد ذلك تركيب هذا السر في خدمة بوابة الاستدلال واستخدامه لمصافحة TLS مقابل خادم النموذج الخاص بك.
مثال كامل
فيما يلي مثال كامل يعكس هيكل config-model-gateway-template.yaml من حزمة Bob Bundle. احفظه في ملف (على سبيل المثال، /tmp/example/model-gateway.yaml) وأشر إليه في وقت التثبيت.
تكوين بوابة النماذج
# ── Provider definitions ───────────────────────────────────────────────────────
# The x-providers key is ignored by the model gateway — it is a YAML scratchpad
# for provider examples. Only the active provider's anchor is referenced below.
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
# Custom inference service (RHOAI, vLLM, etc.)
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 ────────────────────────────────────────────────────────────────────
models:
# ── ACTIVE MODEL ─────────────────────────────────────────────────────────────
# Change <<: *bedrock to e.g. *azure, *gemini, or *isvc to switch providers.
- &chat_llm
<<: *bedrock # ← change provider here
model_name: premium-ide
model_info:
exposed: true
# ── Aliases ───────────────────────────────────────────────────────────────────
- <<: *chat_llm
model_name: security # overrides premium-ide from the merged anchor
- <<: *chat_llm
model_name: background
# ── Router ────────────────────────────────────────────────────────────────────
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 في وقت التثبيت:
bobctl install --model-config path/to/model-gateway-config.yaml --accept-license --registry-creds <username:password>إذا تم تشغيل bobctl install بدون --model-config، فسيتم تثبيت Bob بتكوين فارغ لبوابة النماذج. تعمل خدمة الاستدلال (Inference Service) ولكن ليس لديها اتصال بأي نموذج للاستدلال. استخدم bobctl update-model-config بعد التثبيت لدفع تكوين النموذج إلى المجموعة.
كيفية نشر بيانات الاعتماد على المجموعة
يشير ملف تكوين بوابة النماذج إلى بيانات الاعتماد كمتغيرات بيئة (على سبيل المثال، env.AWS_ACCESS_KEY وenv.AZURE_API_KEY). يتطلب موفرو النماذج المختلفون أسرارًا مختلفة — مفاتيح AWS IAM لـ Bedrock، أو مفاتيح API لـ Azure OpenAI، أو ملف JSON لحساب الخدمة لـ Google Gemini.
أثناء التثبيت، يتم توفير بيانات الاعتماد هذه في ملف config.yaml الخاص بك تحت bob.modelGateway.secrets. تعالج واجهة سطر الأوامر bobctl هذا القسم تلقائيًا وتنشئ سر Kubernetes باسم bob-inference-model-secrets في المجموعة، مع تركيب المفاتيح كمتغيرات بيئة مباشرةً داخل حاوية خدمة بوابة الاستدلال.
bob:
modelGateway:
secrets:
# AWS Bedrock authentication
AWS_ACCESS_KEY: "<your-aws-access-key-id>"
AWS_SECRET_ACCESS_KEY: "<your-aws-secret-access-key>"
# Azure OpenAI authentication
AZURE_API_KEY: "<your-azure-api-key>"
# Google Cloud Vertex AI / Gemini authentication
GEMINI_CREDENTIALS: "<your-gemini-credentials-json>"
# Custom endpoint API keys / tokens or internal proxy auth
# RITS_APIKEY: "<your-api-key>"
# Custom CA certificate in PEM format for self-signed internal endpoints
# CA_CERT: |
# -----BEGIN CERTIFICATE-----
# ...
# -----END CERTIFICATE-----تحديث التكوين بعد التثبيت (bobctl update-model-config)
استخدم bobctl update-model-config لدفع تكوين بوابة النماذج و/أو الأسرار إلى مجموعة قيد التشغيل دون إعادة التثبيت. هذا هو المسار المطلوب عندما تم تشغيل bobctl install بدون --model-config، وهو نفس الأمر المستخدم عند تبديل نموذج الاستدلال الأساسي.
داخليًا، يُشغّل helm template مقابل قوالب model-config.yaml وmodel-secrets.yaml في مخطط ibm-bob المحلي، ثم يُطبّق البيانات المُولَّدة على المجموعة. بعد التطبيق، يُسوّي ibm-bob-operator نشر bob-inference مع تكوين النموذج الجديد.
يدير الأمر موردين منفصلين للمجموعة:
| الراية | مورد المجموعة | المصدر |
|---|---|---|
--model-config <file> | ConfigMap bob-inference-model-config | الملف الذي تم تمريره |
--update-secrets | Secret bob-inference-model-secrets | bob.modelGateway.secrets في config.yaml |
يجب توفير واحد منهما على الأقل — عدم تمرير أي منهما يعد خطأً.
المتطلبات الأساسية:
- يجب أن تكون مسجلاً للدخول إلى المجموعة (
oc login) - يجب أن يكون
config.yamlموجودًا بجوارbobctl(انسخه منconfig-template.yaml) - يجب أن يكون
helm≥ 3.14.0 متوفرًا في مسار PATH لديك
الاستخدام الشائع:
# Update only the model config file
bobctl update-model-config --model-config ./my-model-config.yaml
# Update only the secrets (keys come from config.yaml)
bobctl update-model-config --update-secrets
# Update both at once
bobctl update-model-config --model-config ./my-model-config.yaml --update-secrets
# Preview what would be applied without touching the cluster
bobctl update-model-config --model-config ./my-model-config.yaml --update-secrets --dry-runجميع الرايات:
| الراية | القيمة الافتراضية | الوصف |
|---|---|---|
--model-config <file> | المسار إلى ملف تكوين النموذج لدفعه إلى ConfigMap | |
--update-secrets | دفع bob.modelGateway.secrets من config.yaml إلى Secret | |
--output-config <file> | model-gateway-config.yaml | مكان كتابة بيان ConfigMap المُولَّد |
--output-secret <file> | model-gateway-secret.yaml | مكان كتابة بيان Secret المُولَّد |
--cleanup | false | حذف ملفات البيانات المُولَّدة بعد تطبيقها |
--dry-run | false | طباعة ما سيتم تشغيله دون تنفيذ أي أوامر oc |