Практичні нотатки: Розкриття таємниць агентської мережі: масштабування AI-агентів та LLM на

У цьому посібнику детально описано шлях від сировини до функціональної системи для проекту «Розкриття таємниць агентських мереж: масштабування AI-агентів та LLM на Kubernetes». Основна увага приділяється конкретним крокам виконання, чітким перевіркам та коду, який можна просто додати до репозиторію, не намагаючись здогадатися про його призначення. На етапі огляду необхідно визначити вхідні дані, відповідальну особу за крок та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись зрозуміти прихований стан системи. Необхідно одночасно задокументувати шлях успішного виконання та шлях відновлення після проблем. Повторні спроби, людський контроль та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої оптимізації.

Основні ускладнення у виробничих AI-агентах

Під час роботи над етапом «Ключові вузькі місця» спочатку запишіть контракт: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Такий перелік допомагає зберігати чесність пізніших змін у коді. Віддавайте перевагу невеликим, тестованим одиницям перед об’ємними скриптами. Коли якийсь крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану послідовність операцій. Зберігайте у кеші стабільні інструкції системи та схеми інструментів. Повторна передача ідентичних даних є поширеною причиною витрат ресурсів.

Познайомтеся зі стеком: план проектування агентного мережевого середовища

Під час роботи над етапом «Meet the Stack The stage» спочатку запишіть умови контракту: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Цей перелік допомагає зберігати чесність пізніших змін у коді. Розглядайте цей етап як контракт між вхідними даними та перевіреними результатами. Дайте назви кожним елементам, визначте критерії успіху та не допускайте безповідомного часткового виконання. Зберігайте у кеші стабільні інструкції системи та схеми інструментів. Повторна передача ідентичних даних є поширеною причиною витрат ресурсів.

1. kagent: Час виконання агента

Під час роботи над етапом 1 kagent The Agent спочатку запишіть умови взаємодії: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Цей перелік допомагає зберігати чесність пізніших змін у коді. Запишіть час виконання та витрати на токени чи запити поруч із функціональними результатами. Відображення витрат заздалегідь запобігає несподіваним рахункам, коли процес переходить від демо-середовища до спільних. Зберігайте у кеші стабільні інструкції системи та схеми інструментів. Повторна передача ідентичних даних є поширеною причиною зайвих витрат. Під час роботи над етапом 1 kagent The Agent спочатку запишіть умови взаємодії: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Цей перелік допомагає зберігати чесність пізніших змін у коді. Одночасно задокументуйте оптимальний та резервний сценарії роботи. Повторні спроби, людський контроль та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої оптимізації.

2. agentgateway: Поліцейський трафіку

Етап Traffic у 2 agentgateway працює найкраще, якщо його розглядати як вимірювану поверхню. Збережіть один ідеальний запис, один випадок збою та примітку про скасування перед розширенням обсягу роботи. Віддавайте перевагу малим, тестовим одиницям перед величезними скриптами. Коли якийсь крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану послідовність дій. Встановіть ліміти на кількість токенів за хід та за сеанс. Інструменти типу agentic агресивно розширюють контекст; жорсткі обмеження запобігають тому, що демонстрації перетворюються на несподівані рахунки.

3. llm-d: Розділювач навантаження

Етап роботи з 3 llm-d найкраще функціонує, якщо його розглядати як вимірювану поверхню. Збережіть один ідеальний запис результату, один випадок невдачі та примітку про скасування змін перед розширенням обсягу роботи. Розглядайте цей етап як контракт між вхідними даними та перевіреними результатами. Позначте всі елементи, визначте критерії успіху та не допускайте мовчазного часткового виконання завдань. Встановіть ліміт токенів на кожен крок та на кожну сесію. Інструменти типу агентів активно розширюють контекст; жорсткі обмеження запобігають тому, щоб демонстрації перетворювалися на несподівані рахунки.

4. vLLM: Сила GPU

У рівні 4 vLLM GPU найкраще функціонує, якщо його розглядати як вимірювану поверхню. Збережіть один ідеальний запис, один випадок збою та примітку про скасування змін перед розширенням обсягу роботи. Записуйте час виконання та витрати на токени чи запити поруч із функціональними результатами. Візуалізація витрат заздалегідь запобігає несподіваним рахункам під час переходу від демо-версії до спільних середовищ. Визначте бюджет на токени за кожен хід та сеанс. Інструменти типу агентів активно розширюють контекст; жорсткі ліміти запобігають тому, що демо-версії перетворюються на несподівані рахунки. У рівні 4 vLLM GPU найкраще функціонує, якщо його розглядати як вимірювану поверхню. Збережіть один ідеальний запис, один випадок збою та примітку про скасування змін перед розширенням обсягу роботи. Документуйте як успішний, так і відновлювальний шляхи роботи. Повторні спроби, людський контроль та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої оптимізації.

1. Архітектура системи

На етапі 1 «Архітектура системи» необхідно визначити вхідні дані, відповідальну особу за крок та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись визначити прихований стан. Краще використовувати невеликі, перевірювані одиниці коду замість об’ємних скриптів. Коли крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану структуру обробки. Коли наступним кроком є код або виклик інструменту, краще використовувати структуровані результати з перевіркою схеми, ніж вільний текст.

Як це працює: обробка запиту в мережі

На етапі обробки «під капотом» необхідно визначити вхідні дані, відповідальну особу за крок та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан. Розглядайте цей етап як контракт між вхідними даними та перевіреними результатами. Позначте всі елементи, визначте критерії успіху та не допускайте мовчазного часткового завершення. У разі, коли наступним кроком є код або виклик інструменту, віддавайте перевагу структурованим результатам із перевіркою схеми перед вільним текстовим форматом.

2. Встановлення контролерів та CRDs

На етапі 2 Install Controllers CRDs необхідно визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори мають мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан. Записуйте час виконання та витрати на токени чи запити поруч із функціональними результатами. Візуалізація витрат заздалегідь запобігає несподіваним рахункам під час переходу з демо-середовища у спільні. У разі, коли наступним кроком є написання коду чи виклик інструменту, краще використовувати структуровані результати з перевіркою схеми, ніж вільний текст. На етапі 2 Install Controllers CRDs необхідно визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори мають мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан. Документуйте як оптимальний, так і альтернативний шлях виконання. Повторні спроби, людський контроль та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої оптимізації.

# 1. Install Kubernetes Gateway API & Inference Extension CRDs
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.0/standard-install.yaml
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api-inference-extension/releases/download/v0.1.0/manifests.yaml

# 2. Add Helm Registries
helm repo add agentgateway oci://cr.agentgateway.dev/charts
helm repo add kagent https://charts.kagent.dev
helm repo update

# 3. Install agentgateway (Control & Data Plane)
helm upgrade -i agentgateway-crds agentgateway/agentgateway-crds -n agentgateway-system --create-namespace
helm upgrade -i agentgateway agentgateway/agentgateway -n agentgateway-system

# 4. Install kagent (Agent Runtime)
helm upgrade -i kagent kagent/kagent -n kagent-system --create-namespace

3. Розгортання інфраструктури інтерпретації GPU (vLLM та llm-d)

Під час виконання 3-го етапу розгортання інфраструктури інтерпретації GPU спочатку запишіть контракт: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Такий перелік допомагає зберігати чесність пізніших змін у коді. Віддавайте перевагу невеликим, тестованим одиницям коду перед об’ємними скриптами. Якщо якийсь крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану послідовність операцій. Зберігайте у кеші стабільні інструкції системи та схеми інструментів. Повторна передача ідентичних даних є поширеною причиною витрат ресурсів.

Заповнення попередніми даними та декодування конфігурації розгортання (vllm-infrastructure.yaml)

Під час виконання етапу Prefill Decode Deployment vllm-infrastructure спочатку запишіть умови договору: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Такий перелік допомагає зберігати чесність пізніших змін у коді. Розглядайте цей етап як договір між вхідними даними та перевіреними результатами. Позначте всі елементи, визначте критерії успіху та не допускайте безпроблемного часткового завершення роботи. Зберігайте у кеші стабільні інструкції системи та схеми інструментів. Повторна передача ідентичних даних є поширеною причиною непотрібних витрат.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: vllm-prefill
  namespace: llm-serving
  labels:
    app: vllm-prefill
spec:
  replicas: 1
  selector:
    matchLabels:
      app: vllm-prefill
  template:
    metadata:
      labels:
        app: vllm-prefill
    spec:
      containers:
      - name: vllm
        image: vllm/vllm-openai:latest
        args:
        - "--model"
        - "meta-llama/Meta-Llama-3-8B-Instruct"
        - "--experimental-prefill-only" # Optimization: Dedicated Prefill role
        - "--gpu-memory-utilization"
        - "0.90"
        - "--port"
        - "8000"
        ports:
        - containerPort: 8000
          name: http
        resources:
          limits:
            nvidia.com/gpu: "1" # Schedule on premium compute node
            cpu: "4"
            memory: 16Gi
        volumeMounts:
        - mountPath: /root/.cache/huggingface
          name: model-cache
        - mountPath: /dev/shm
          name: dshm
      volumes:
      - name: model-cache
        persistentVolumeClaim:
          claimName: vllm-model-cache-pvc
      - name: dshm
        emptyDir:
          medium: Memory
          sizeLimit: 4Gi
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: vllm-decode
  namespace: llm-serving
  labels:
    app: vllm-decode
spec:
  replicas: 3 # Scale out dynamically based on load
  selector:
    matchLabels:
      app: vllm-decode
  template:
    metadata:
      labels:
        app: vllm-decode
    spec:
      containers:
      - name: vllm
        image: vllm/vllm-openai:latest
        args:
        - "--model"
        - "meta-llama/Meta-Llama-3-8B-Instruct"
        - "--experimental-decode-only" # Optimization: Dedicated token generator role
        - "--gpu-memory-utilization"
        - "0.90"
        - "--port"
        - "8000"
        ports:
        - containerPort: 8000
          name: http
        resources:
          limits:
            nvidia.com/gpu: "1" # Schedule on low-cost L4/A10G nodes
            cpu: "4"
            memory: 16Gi
        volumeMounts:
        - mountPath: /root/.cache/huggingface
          name: model-cache
        - mountPath: /dev/shm
          name: dshm
      volumes:
      - name: model-cache
        persistentVolumeClaim:
          claimName: vllm-model-cache-pvc
      - name: dshm
        emptyDir:
          medium: Memory
          sizeLimit: 4Gi

Конфігурація llm-d (llmd-routing.yaml)

Під час роботи над етапом llmd-routing yaml у конфігурації llm-d спочатку запишіть умови використання: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Такий перелік допомагає зберігати чесність пізніших змін у коді. Запишіть час виконання та витрати на токени або запити поруч із функціональними результатами. Чітке бачення витрат заздалегідь запобігає несподіваним рахункам, коли процес переходить від демо-режиму до спільних середовищ. Зберігайте у кеші стабільні інструкції системи та схеми інструментів. Повторна передача ідентичних даних є поширеною причиною надмірних витрат. Під час роботи над етапом llmd-routing yaml у конфігурації llm-d спочатку запишіть умови використання: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Такий перелік допомагає зберігати чесність пізніших змін у коді. Одночасно задокументуйте оптимальний та резервний сценарії роботи. Повторні спроби, людський контроль та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої оптимізації.

apiVersion: inference.networking.x-k8s.io/v1alpha1
kind: InferencePool
metadata:
  name: llama3-decode-pool
  namespace: llm-serving
spec:
  selector:
    matchLabels:
      app: vllm-decode
  targetPort: 8000
---
apiVersion: inference.networking.x-k8s.io/v1alpha1
kind: InferenceObjective
metadata:
  name: llama3-serving-objective
  namespace: llm-serving
spec:
  modelName: "meta-llama/Meta-Llama-3-8B-Instruct"
  prefillService:
    name: vllm-prefill
    port: 8000
  decodePool:
    name: llama3-decode-pool

4. Налаштування agentgateway

Етап 4 «Налаштування agentgateway» найкраще функціонує, якщо його розглядати як вимірювану одиницю. Збережіть один ідеальний зразок виконання, один випадок збою та примітки щодо скасування змін перед розширенням обсягу роботи. Віддавайте перевагу невеликим, тестованим одиницям перед складними скриптами. Якщо якийсь крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану послідовність дій. Встановіть ліміти на кількість токенів за кожен крок та сесію. Інструменти типу агентів активно розширюють контекст; жорсткі обмеження запобігають тому, що демонстрації перетворюються на несподівані рахунки.

Визначення гейтвею (agent-gateway.yaml)

Етап yaml агента-шлюзу у моделі Gateway Definition працює найкраще, якщо його розглядати як вимірювану поверхню. Збережіть один ідеальний запис, один випадок збою та примітку про скасування змін перед розширенням обсягу роботи. Розглядайте цей етап як контракт між вхідними даними та перевіреними результатами. Позначте всі елементи, визначте критерії успіху та не допускайте мовчазного часткового виконання завдань. Встановіть ліміти на кількість токенів за кожен хід та сесію. Інструменти агентів активно розширюють контекст; жорсткі обмеження запобігають тому, що демонстрації перетворюються на несподівані рахунки.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: agent-gateway
  namespace: agentgateway-system
spec:
  gatewayClassName: agentgateway
  listeners:
  - name: http
    protocol: HTTP
    port: 8080
    allowedRoutes:
      namespaces:
        from: All
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: llm-inference-route
  namespace: llm-serving
spec:
  parentRefs:
  - name: agent-gateway
    namespace: agentgateway-system
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /v1/chat/completions
    backendRefs:
    - name: llama3-serving-objective
      kind: InferenceObjective
      group: inference.networking.x-k8s.io
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: mcp-tools-route
  namespace: agent-tools
spec:
  parentRefs:
  - name: agent-gateway
    namespace: agentgateway-system
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /mcp/tools
    backendRefs:
    - name: mcp-tool-server-service
      port: 50051

5. Розгортання кластера AI-агента kagent

Етап 5 «Розгортання kagent AI» працює найкраще, якщо його розглядати як вимірювану поверхню. Збережіть один ідеальний запис, один випадок збою та примітку про скасування змін перед розширенням обсягу роботи. Записуйте час виконання та витрати на токени чи запити поруч із функціональними результатами. Чітке бачення витрат заздалегідь запобігає несподіваним рахункам під час переходу від демонстрації до спільних середовищ.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: kagent-orchestrator
  namespace: kagent-system
spec:
  replicas: 2
  selector:
    matchLabels:
      app: kagent-orchestrator
  template:
    metadata:
      labels:
        app: kagent-orchestrator
    spec:
      containers:
      - name: agent-runtime
        image: kagent/runtime:latest
        env:
        # Route all model and tool API calls through agentgateway
        - name: OPENAI_API_BASE
          value: "http://agent-gateway.agentgateway-system.svc.cluster.local:8080/v1"
        - name: MCP_SERVER_URL
          value: "http://agent-gateway.agentgateway-system.svc.cluster.local:8080/mcp/tools"
        resources:
          limits:
            cpu: "2"
            memory: 4Gi
          requests:
            cpu: "1"
            memory: 2Gi

6. Чек-лист оптимізації та налаштувань

Чек-лист експлуатації