在 Docker Compose 應用程式中定義 AI 模型

目錄
要求： Docker Compose 2.38.0 及更高版本

Compose 允許您將 AI 模型定義為應用程式的核心元件，因此您可以與服務一起宣告模型依賴項，並在任何支援 Compose 規範的平台上執行應用程式。

先決條件

  • Docker Compose v2.38 或更新版本
  • 支援 Compose 模型的平台，例如 Docker Model Runner (DMR) 或相容的雲端供應商。如果您使用 DMR，請參閱需求。

什麼是 Compose 模型？

Compose models 是一種在應用程式中定義 AI 模型依賴項的標準化方式。透過在 Compose 檔案中使用 models 頂層元素，您可以：

  • 宣告您的應用程式需要哪些 AI 模型
  • 指定模型設定與需求
  • 使您的應用程式能在不同平台間具備可攜性
  • 讓平台處理模型的部署與生命週期管理

基本模型定義

若要在您的 Compose 應用程式中定義模型，請使用 models 頂層元素

services:
  chat-app:
    image: my-chat-app
    models:
      - llm

models:
  llm:
    model: ai/smollm2

此範例定義了：

  • 一個名為 chat-app 的服務，其使用名為 llm 的模型
  • 一個針對 llm 的模型定義，該定義引用了 ai/smollm2 模型映像檔

模型設定選項

模型支援多種設定選項

models:
  llm:
    model: ai/smollm2
    context_size: 1024
    runtime_flags:
      - "--a-flag"
      - "--another-flag=42"

常見的設定選項包括：

  • model（必填）：模型的 OCI 構件識別碼。這是 Compose 透過模型執行器 (model runner) 所拉取並執行的內容。

  • context_size：定義模型的最大 Token 上下文大小。

    注意

    每個模型都有其自有的最大上下文大小。增加上下文長度時，請考量您的硬體限制。一般而言，請嘗試將上下文大小保持在滿足您特定需求的可行最小範圍內。

  • runtime_flags：啟動模型時傳遞給推理引擎的原始命令列旗標清單。例如，如果您使用 llama.cpp，則可以傳遞 任何可用參數。

  • 平台特定的選項也可以透過擴充屬性 x-* 取得。

提示

在常見執行時期設定一節中查看更多範例。

使用供應商服務的替代設定

重要

此方法已被棄用。請改用 models 頂層元素。

您也可以使用 provider 服務類型，它允許您宣告應用程式所需的平台功能。對於 AI 模型，您可以使用 model 類型來宣告模型依賴項。

若要定義模型供應商：

services:
  chat:
    image: my-chat-app
    depends_on:
      - ai_runner

  ai_runner:
    provider:
      type: model
      options:
        model: ai/smollm2
        context-size: 1024
        runtime-flags: "--no-prefill-assistant"

服務模型綁定

服務可以透過兩種方式引用模型：簡短語法和長語法。

短語法

簡短語法是將模型綁定到服務的最簡單方式

services:
  app:
    image: my-app
    models:
      - llm
      - embedding-model

models:
  llm:
    model: ai/smollm2
  embedding-model:
    model: ai/all-minilm

使用簡短語法時，平台會根據模型名稱自動產生環境變數

  • LLM_URL - 存取 LLM 模型的 URL
  • LLM_MODEL - LLM 模型的模型識別碼
  • EMBEDDING_MODEL_URL - 存取嵌入模型的 URL
  • EMBEDDING_MODEL_MODEL - 嵌入模型的模型識別碼

長語法

長語法允許您自訂環境變數名稱

services:
  app:
    image: my-app
    models:
      llm:
        endpoint_var: AI_MODEL_URL
        model_var: AI_MODEL_NAME
      embedding-model:
        endpoint_var: EMBEDDING_URL
        model_var: EMBEDDING_NAME

models:
  llm:
    model: ai/smollm2
  embedding-model:
    model: ai/all-minilm

透過此設定，您的服務會接收：

  • 針對 LLM 模型的 AI_MODEL_URL 和 AI_MODEL_NAME
  • 針對嵌入模型的 EMBEDDING_URL 和 EMBEDDING_NAME

平台可攜性

使用 Compose 模型的主要優點之一是能在支援 Compose 規範的不同平台上實現可攜性。

Docker 模型執行器

當 啟用 Docker Model Runner 時：

services:
  chat-app:
    image: my-chat-app
    models:
      llm:
        endpoint_var: AI_MODEL_URL
        model_var: AI_MODEL_NAME

models:
  llm:
    model: ai/smollm2
    context_size: 4096
    runtime_flags:
      - "--no-prefill-assistant"

Docker Model Runner 將會：

  • 在本地拉取並執行指定的模型
  • 提供用於存取模型的端點 URL
  • 將環境變數注入到服務中

雲端供應商

相同的 Compose 檔案可以在支援 Compose 模型的雲端供應商上執行

services:
  chat-app:
    image: my-chat-app
    models:
      - llm

models:
  llm:
    model: ai/smollm2
    # Cloud-specific configurations
    x-cloud-options:
      - "cloud.instance-type=gpu-small"
      - "cloud.region=us-west-2"

雲端供應商可能會：

  • 使用託管的 AI 服務，而不是在本地執行模型
  • 應用特定於雲端的最佳化與擴展
  • 提供額外的監控與記錄功能
  • 自動處理模型版本控制與更新

常見執行時期設定

以下是針對各種使用案例的一些設定範例。

開發

services:
  app:
    image: app
    models:
      dev_model:
        endpoint_var: DEV_URL
        model_var: DEV_MODEL

models:
  dev_model:
    model: ai/model
    context_size: 4096
    runtime_flags:
      - "--verbose"                       # Set verbosity level to infinity
      - "--verbose-prompt"                # Print a verbose prompt before generation
      - "--log-prefix"                    # Enable prefix in log messages
      - "--log-timestamps"                # Enable timestamps in log messages
      - "--log-colors"                    # Enable colored logging

保守模式（停用推理）

services:
  app:
    image: app
    models:
      conservative_model:
        endpoint_var: CONSERVATIVE_URL
        model_var: CONSERVATIVE_MODEL

models:
  conservative_model:
    model: ai/model
    context_size: 4096
    runtime_flags:
      - "--temp"                # Temperature
      - "0.1"
      - "--top-k"               # Top-k sampling
      - "1"
      - "--reasoning-budget"    # Disable reasoning
      - "0"

創意模式（高隨機性）

services:
  app:
    image: app
    models:
      creative_model:
        endpoint_var: CREATIVE_URL
        model_var: CREATIVE_MODEL

models:
  creative_model:
    model: ai/model
    context_size: 4096
    runtime_flags:
      - "--temp"                # Temperature
      - "1"
      - "--top-p"               # Top-p sampling
      - "0.9"

高度確定性

services:
  app:
    image: app
    models:
      deterministic_model:
        endpoint_var: DET_URL
        model_var: DET_MODEL

models:
  deterministic_model:
    model: ai/model
    context_size: 4096
    runtime_flags:
      - "--temp"                # Temperature
      - "0"
      - "--top-k"               # Top-k sampling
      - "1"

並行處理

services:
  app:
    image: app
    models:
      concurrent_model:
        endpoint_var: CONCURRENT_URL
        model_var: CONCURRENT_MODEL

models:
  concurrent_model:
    model: ai/model
    context_size: 2048
    runtime_flags:
      - "--threads"             # Number of threads to use during generation
      - "8"
      - "--mlock"               # Lock memory to prevent swapping

豐富詞彙模型

services:
  app:
    image: app
    models:
      rich_vocab_model:
        endpoint_var: RICH_VOCAB_URL
        model_var: RICH_VOCAB_MODEL

models:
  rich_vocab_model:
    model: ai/model
    context_size: 4096
    runtime_flags:
      - "--temp"                # Temperature
      - "0.1"
      - "--top-p"               # Top-p sampling
      - "0.9"

參考

© . This site is unofficial and not affiliated with Kubernetes or Docker Inc.