使用 Docker 建置並執行代理式 AI 應用程式

目錄

簡介

代理式應用程式正在改變軟體的構建方式。這些應用程式不僅僅是回應，它們還能進行決策、規劃和行動。它們由模型驅動，由代理編排，並與 API、工具和服務即時整合。

所有這些新的代理式應用程式，無論其功能為何，都共用一種通用架構。這是一種由三個核心組件構成的新型堆疊：

  • 模型 (Models)：指 GPT、CodeLlama、Mistral 等。它們負責推理、編寫和規劃。它們是智慧背後的引擎。

  • 代理 (Agent)：這是邏輯所在。代理接收目標，將其拆解，並找出達成目標的方法。它們負責編排一切。它們會與 UI、工具、模型和閘道進行通訊。

  • MCP 閘道 (MCP gateway)：這是將代理連接到外部世界（包括 API、工具和服務）的橋樑。它為代理提供了一種透過模型上下文協定 (MCP) 呼叫功能的標準化方式。

Docker 透過將模型、工具閘道和雲端基礎設施統一為開發者友善的工作流程（使用 Docker Compose），使這種人工智慧堆疊變得更簡單、更快速且更安全。

A diagram of the agentic stack

本指南將帶您了解代理式開發的核心組件，並示範 Docker 如何透過下列工具將它們整合在一起：

  • Docker Model Runner 讓您能夠透過簡單的指令和 OpenAI 相容的 API 在本地執行 LLM。
  • Docker MCP Catalog and Toolkit 協助您發現並安全地執行外部工具（例如 API 和資料庫），並使用模型上下文協定 (MCP)。
  • Docker MCP Gateway 讓您能夠編排並管理 MCP 伺服器。
  • Docker Offload 提供了一個強大的 GPU 加速環境，讓您可以使用與本地相同的 Compose 工作流程來執行 AI 應用程式。
  • Docker Compose 是將這一切整合在一起的工具，讓您能透過單一檔案定義並執行多容器應用程式。

在本指南中，您將從在 Docker Offload 中執行應用程式開始，使用您已經熟悉的 Compose 工作流程。接著，如果您的機器硬體支援，您將使用相同的工作流程在本地執行相同的應用程式。最後，您將深入剖析 Compose 檔案、Dockerfile 和應用程式，了解它們如何協同運作。

先決條件

若要學習本指南，您需要：

步驟 1：複製範例應用程式

您將使用一個現有的範例應用程式，該應用程式示範了如何利用 Docker 的 AI 功能將模型連接到外部工具。

$ git clone https://github.com/docker/compose-for-agents.git
$ cd compose-for-agents/adk/

步驟 2：使用 Docker Offload 執行應用程式

您將首先在 Docker Offload 中執行應用程式，它為執行 AI 工作負載提供了一個託管環境。如果您想利用雲端資源，或者您的本地機器未達執行模型的硬體要求，這將是理想選擇。Docker Offload 包含對 GPU 加速實例的支援，使其非常適合 AI 模型推論等運算密集型工作負載。

若要使用 Docker Offload 執行應用程式，請依照下列步驟操作：

  1. 登入 Docker Desktop Dashboard。

  2. 在終端機中，執行下列指令以啟動 Docker Offload：

    $ docker offload start

    出現提示時，選擇您要用於 Docker Offload 的帳戶，並在詢問「Do you need GPU support? (您需要 GPU 支援嗎？)」時選擇 Yes。

  3. 在已複製儲存庫的 adk/ 目錄中，於終端機執行下列指令來建置並執行應用程式：

    $ docker compose up

    第一次執行此指令時，Docker 會從 Docker Hub 拉取模型，這可能需要一些時間。

    應用程式現在已透過 Docker Offload 執行。請注意，使用 Docker Offload 時的 Compose 工作流程與在本地執行時相同。您在 compose.yaml 檔案中定義應用程式，然後使用 docker compose up 來建置並執行它。

  4. 造訪 https://:8080。在提示字元中輸入一個正確或錯誤的事實並按下 Enter。一個代理程式會搜尋 DuckDuckGo 來驗證它，另一個代理程式則會修改輸出結果。

    Screenshot of the application

  5. 完成後，在終端機中按下 ctrl-c 以停止應用程式。

  6. 執行下列指令以停止 Docker Offload：

    $ docker offload stop

步驟 3：選用。在本地執行應用程式

如果您的機器符合必要的硬體要求，您可以使用 Docker Compose 在本地執行整個應用程式堆疊。這讓您無需在雲端執行，即可端對端測試應用程式，包括模型和 MCP 閘道。此範例使用的是 Gemma 3 4B 模型，上下文長度為 10000。

硬體要求：

  • VRAM：3.5 GB
  • 儲存空間：2.31 GB

如果您的機器超過這些要求，請考慮以更大的上下文長度或更大的模型來執行應用程式，以提升代理程式的效能。您可以輕鬆地在 compose.yaml 檔案中更新模型和上下文長度。

若要於本地執行應用程式，請依照下列步驟操作：

  1. 在已複製儲存庫的 adk/ 目錄中，於終端機執行下列指令來建置並執行應用程式：

    $ docker compose up

    第一次執行此指令時，Docker 會從 Docker Hub 拉取模型，這可能需要一些時間。

  2. 造訪 https://:8080。在提示字元中輸入一個正確或錯誤的事實並按下 Enter。一個代理程式會搜尋 DuckDuckGo 來驗證它，另一個代理程式則會修改輸出結果。

  3. 完成後，在終端機中按下 ctrl-c 以停止應用程式。

步驟 4：檢閱應用程式環境

您可以在 adk/ 目錄中找到 compose.yaml 檔案。請使用文字編輯器開啟它，查看服務是如何定義的。

compose.yaml
services:
  adk:
    build:
      context: .
    ports:
      # expose port for web interface
      - "8080:8080"
    environment:
      # point adk at the MCP gateway
      - MCPGATEWAY_ENDPOINT=http://mcp-gateway:8811/sse
    depends_on:
      - mcp-gateway
    models:
      gemma3 :
        endpoint_var: MODEL_RUNNER_URL
        model_var: MODEL_RUNNER_MODEL

  mcp-gateway:
    # mcp-gateway secures your MCP servers
    image: docker/mcp-gateway:latest
    use_api_socket: true
    command:
      - --transport=sse
      # add any MCP servers you want to use
      - --servers=duckduckgo

models:
  gemma3:
    # pre-pull the model when starting Docker Model Runner
    model: ai/gemma3:4B-Q4_0
    context_size: 10000 # 3.5 GB VRAM
    # increase context size to handle search results
    # context_size: 131000 # 7.6 GB VRAM

該應用程式由三個主要組件組成：

  • adk 服務：這是執行代理式 AI 應用程式的 Web 應用程式。此服務會與 MCP 閘道和模型進行通訊。
  • mcp-gateway 服務：這是將應用程式連接到外部工具和服務的 MCP 閘道。
  • models 區塊：這定義了應用程式要使用的模型。

當您檢查 compose.yaml 檔案時，會發現模型有兩個顯著的元素：

  • adk 服務內部的服務層級 models 區塊
  • 頂層的 models 區塊

這兩個區塊共同運作，讓 Docker Compose 自動啟動您的 ADK Web 應用程式並連接到指定的 LLM。

提示

想尋找更多可使用的模型嗎？請查看 Docker AI 模型目錄。

在檢查 compose.yaml 檔案時，您會發現閘道服務是一個由 Docker 維護的映像檔：docker/mcp-gateway:latest。此映像檔是 Docker 開源的 MCP 閘道，讓您的應用程式能夠連接到 MCP 伺服器，進而公開模型可以呼叫的工具。在此範例中，它使用 duckduckgo MCP 伺服器來執行網頁搜尋。

提示

想尋找更多可使用的 MCP 伺服器嗎？請查看 Docker MCP 目錄。

只需在 Compose 檔案中輸入幾行指令，您就能執行並連接代理式 AI 應用程式所需的所有服務。

除了 Compose 檔案外，Dockerfile 和它所建立的 entrypoint.sh 指令碼，也在建置與執行階段串連 AI 堆疊中發揮作用。您可以在 adk/ 目錄中找到 Dockerfile。請使用文字編輯器開啟它。

Dockerfile
# Use Python 3.11 slim image as base
FROM python:3.13-slim
ENV PYTHONUNBUFFERED=1

RUN pip install uv

WORKDIR /app
# Install system dependencies
COPY pyproject.toml uv.lock ./
RUN --mount=type=cache,target=/root/.cache/uv \
    UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy \
    uv pip install --system .
# Copy application code
COPY agents/ ./agents/
RUN python -m compileall -q .

COPY <<EOF /entrypoint.sh
#!/bin/sh
set -e

if test -f /run/secrets/openai-api-key; then
    export OPENAI_API_KEY=$(cat /run/secrets/openai-api-key)
fi

if test -n "\${OPENAI_API_KEY}"; then
    echo "Using OpenAI with \${OPENAI_MODEL_NAME}"
else
    echo "Using Docker Model Runner with \${MODEL_RUNNER_MODEL}"
    export OPENAI_BASE_URL=\${MODEL_RUNNER_URL}
    export OPENAI_MODEL_NAME=openai/\${MODEL_RUNNER_MODEL}
    export OPENAI_API_KEY=cannot_be_empty
fi
exec adk web --host 0.0.0.0 --port 8080 --log_level DEBUG
EOF
RUN chmod +x /entrypoint.sh

# Create non-root user
RUN useradd --create-home --shell /bin/bash app \
    && chown -R app:app /app
USER app

ENTRYPOINT [ "/entrypoint.sh" ]

entrypoint.sh 有五個關鍵的環境變數：

  • MODEL_RUNNER_URL：由 Compose（透過服務層級的 models: 區塊）注入，指向您的 Docker Model Runner HTTP 端點。

  • MODEL_RUNNER_MODEL：由 Compose 注入，用以選擇要在 Model Runner 中啟動的模型。

  • OPENAI_API_KEY：如果您在 Compose 檔案中定義了 openai-api-key 密鑰，Compose 會將其掛載至 /run/secrets/openai-api-key。入口點指令碼會讀取該檔案並將其匯出為 OPENAI_API_KEY，使應用程式使用託管的 OpenAI 而非 Model Runner。

  • OPENAI_BASE_URL：當沒有提供真實金鑰時，此變數會被設定為 MODEL_RUNNER_URL，以便 ADK 的 OpenAI 相容用戶端將請求發送到 Docker Model Runner。

  • OPENAI_MODEL_NAME：在退回到 Model Runner 時，模型名稱會加上 openai/ 前綴，讓用戶端能夠抓取正確的模型別名。

總結來說，這些變數讓相同的 ADK Web 伺服器程式碼可以無縫地指向：

  • 託管的 OpenAI：如果您提供了 OPENAI_API_KEY（以及選擇性的 OPENAI_MODEL_NAME）
  • Model Runner：透過將 MODEL_RUNNER_URL 和 MODEL_RUNNER_MODEL 重新對應到 OpenAI 用戶端預期的變數中

步驟 5：檢閱應用程式

adk Web 應用程式是一種代理實作，透過環境變數和 API 呼叫連接到 MCP 閘道和模型。它使用 ADK (Agent Development Kit) 定義了一個名為 Auditor 的根代理程式，該代理程式負責協調兩個子代理程式（Critic 和 Reviser），以驗證並優化模型產生的答案。

這三個代理程式分別是：

  • Critic：使用工具集（如 DuckDuckGo）驗證事實主張。
  • Reviser：根據 Critic 提供的驗證結論來編輯答案。
  • Auditor：一個更高層級的代理程式，負責安排 Critic 和 Reviser 的執行順序。它作為入口點，評估 LLM 產生的答案、驗證它們並優化最終輸出。

應用程式的所有行為都在 agents/ 目錄下的 Python 檔案中定義。以下是重要檔案的細項說明：

  • agents/agent.py：定義了 Auditor，這是一個 SequentialAgent，它將 Critic 和 Reviser 代理程式串聯起來。此代理程式是應用程式的主要入口點，負責使用現實世界的驗證工具來審核 LLM 產生的內容。

  • agents/sub_agents/critic/agent.py：定義了 Critic 代理程式。它載入語言模型（透過 Docker Model Runner）、設定代理程式的名稱與行為，並連接到 MCP 工具（例如 DuckDuckGo）。

  • agents/sub_agents/critic/prompt.py：包含 Critic 的提示詞 (prompt)，指示代理程式使用外部工具來擷取並驗證聲明。

  • agents/sub_agents/critic/tools.py：定義 MCP 工具集設定，包含解析 mcp/ 字串、建立工具連接以及處理 MCP 閘道通訊。

  • agents/sub_agents/reviser/agent.py：定義了 Reviser 代理程式，它會接收 Critic 的發現並對原始答案進行最小程度的重寫。它還包含清理 LLM 輸出並確保其格式正確的回呼函數。

  • agents/sub_agents/reviser/prompt.py：包含 Reviser 的提示詞，指示代理程式根據驗證過的聲明結論來修改答案文字。

MCP 閘道是透過 MCPGATEWAY_ENDPOINT 環境變數進行設定的，在此例中為 http://mcp-gateway:8811/sse。這讓應用程式能夠使用伺服器發送事件 (SSE) 與 MCP 閘道容器通訊，該容器本身則充當存取 DuckDuckGo 等外部工具服務的中介。

總結

基於代理的 AI 應用程式正演變為一種強大的新軟體架構。在本指南中，您探索了一個模組化、思維鏈系統，其中 Auditor 代理程式協調 Critic 和 Reviser 的工作，以進行事實查核並優化模型產生的答案。此架構展示了如何以結構化、模組化的方式將本地模型推論與外部工具整合結合。

您也看到了 Docker 如何透過提供一套支援本地與雲端代理式 AI 開發的工具，來簡化此過程：

  • Docker Model Runner：透過 OpenAI 相容 API 在本地執行並託管開源模型。
  • Docker MCP Catalog and Toolkit：啟動並管理遵循模型上下文協定 (MCP) 標準的工具整合。
  • Docker MCP Gateway：編排並管理 MCP 伺服器，將代理連接到外部工具和服務。
  • Docker Compose：使用單一檔案定義並執行多容器代理式 AI 應用程式，在本地和雲端使用相同的工作流程。
  • Docker Offload：在安全、託管的雲端環境中執行 GPU 密集型 AI 工作負載，並使用與您本地相同的 Docker Compose 工作流程。

透過這些工具，您可以使用一致的工作流程，高效地在本地或雲端開發和測試代理式 AI 應用程式。

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