تكوين بوابة النماذج

تعرّف على كيفية إنشاء وإدارة ملف تكوين بوابة النماذج (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 معًا لاختيار ضبط النموذج والتحسينات المحددة له. استخدم أقرب قيمة مطابقة للنماذج غير المدرجة.

providerfamilyversionمثال على معرف النموذج
openaigpt5.6-solgpt-5.6-sol
openaigpt-oss20bopenai/gpt-oss-20b
anthropicsonnet5us.anthropic.claude-sonnet-5
googlegemini3.6-flashgemini-3.6-flash
googlegemini3.1-progemini-3.1-pro
nvidianemotron3-ultranvidia/nemotron-3-ultra-550b
mistralmedium3.5mistralai/mistral-medium-3-5-0
poolsidelagunas2.1poolside/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: chat

bedrock

يتصل بنموذج يتم توفيره عبر 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: chat

vertex

يتصل بنموذج يتم توفيره عبر 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_modelmodel_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:

  1. في model-gateway.yaml: اضبط ca_cert_pem على اسم متغير بيئة (على سبيل المثال، env.CA_CERT).
  2. في 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: chat

2. تكوين التثبيت (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-secretsSecret bob-inference-model-secretsbob.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 المُولَّد
--cleanupfalseحذف ملفات البيانات المُولَّدة بعد تطبيقها
--dry-runfalseطباعة ما سيتم تشغيله دون تنفيذ أي أوامر oc
ما رأيك في هذا الموضوع؟