全部產品
Search

搜尋本產品

    Container Service for Kubernetes：使用 AgentScope 將智能體應用部署為 Knative 服務

    文件中心

    Container Service for Kubernetes：使用 AgentScope 將智能體應用部署為 Knative 服務

    更新時間：May 27, 2026

    將 AgentScope 架構開發的智能體應用一鍵式部署到ACK Knative 環境中後，可利用 Knative 的自動擴縮容（縮容至0）、版本管理等 Serverless 能力，實現 AI 智能體的快速、彈性與低成本託管。

    工作原理

    agentscope deploy knative 命令封裝了將智能體應用程式容器化並部署到叢集的複雜流程。其核心工作流程如下：

    1. 打包應用：將指定的 Python 智能體應用代碼、依賴項（requirements.txt）和環境變數打包。

    2. 構建鏡像：基於指定的基礎鏡像，在本地 Docker 環境中構建一個包含智能體應用的容器鏡像。

    3. 推送鏡像：將構建好的鏡像推送到指定的容器鏡像倉庫，如ACR。

    4. 部署服務：在目的地組群中，產生並應用一個 Knative Service（ksvc）資源清單。Knative 會根據此清單建立 Deployment 和 Pod，並自動設定網路路由、負載平衡和自動調整策略。

    準備工作

    • 已在叢集中部署Knative組件。

    • 本地已安裝並運行 Docker，用於構建容器鏡像。

    • 已通過 pip 命令安裝 AgentScope Runtime。

      # 基礎安裝
pip install agentscope-runtime>=1.1.0
# Kubernetes部署依賴
pip install "agentscope-runtime[ext]>=1.1.0"

    步驟一：建立智能體專案

    如當前未準備智能體應用，可參見下方樣本檔案結構和代碼。

    1. 建立專案目錄結構：

      my-agent-project/
├── app_agent.py          # 智能體應用主檔案
├── requirements.txt      # Python 依賴（可選）
└── .env                  # 環境變數（可選）

    2. 在 app_agent.py 檔案中編寫智能體代碼。

      下方代碼建立了一個使用千問模型，具備代碼執行和多輪對話能力的智能體。
      # -*- coding: utf-8 -*-
import os
from contextlib import asynccontextmanager
from fastapi import FastAPI
from agentscope.agent import ReActAgent
from agentscope.formatter import DashScopeChatFormatter
from agentscope.model import DashScopeChatModel
from agentscope.pipeline import stream_printing_messages
from agentscope.tool import Toolkit, execute_python_code
from agentscope.memory import InMemoryMemory
from agentscope.session import JSONSession
from agentscope_runtime.engine.app import AgentApp
from agentscope_runtime.engine.schemas.agent_schemas import AgentRequest
@asynccontextmanager
async def lifespan(app: FastAPI):
    """初始化服務。"""
    app.state.session = JSONSession(
        save_dir="./",  # 儲存所有session檔案的目錄
    )
    try:
        yield
    finally:
        print("AgentApp is shutting down...")
# 建立 AgentApp
agent_app = AgentApp(
    app_name="MyAssistant",
    app_description="A helpful assistant agent",
    lifespan=lifespan,
)
@agent_app.query(framework="agentscope")
async def query_func(
    self,
    msgs,
    request: AgentRequest = None,
    **kwargs,
):
    """處理使用者查詢。"""
    session_id = request.session_id
    user_id = request.user_id
    # Create toolkit with Python execution
    toolkit = Toolkit()
    toolkit.register_tool_function(execute_python_code)
    # Create agent
    agent = ReActAgent(
        name="MyAssistant",
        model=DashScopeChatModel(
            "qwen-turbo",
            api_key=os.getenv("DASHSCOPE_API_KEY"),
            enable_thinking=True,
            stream=True,
        ),
        sys_prompt="You're a helpful assistant.",
        toolkit=toolkit,
        memory=InMemoryMemory(),
        formatter=DashScopeChatFormatter(),
    )
    agent.set_console_output_enabled(False)
    await agent_app.state.session.load_session_state(
        session_id=session_id,
        user_id=user_id,
        agent=agent,
    )
    async for msg, last in stream_printing_messages(
        agents=[agent],
        coroutine_task=agent(msgs),
    ):
        yield msg, last
    await agent_app.state.session.save_session_state(
        session_id=session_id,
        user_id=user_id,
        agent=agent,
    )
if __name__ == "__main__":
    agent_app.run()

    步驟二：部署智能體應用

    使用 agentscope deploy 命令將本地的智能體應用一鍵部署為 Knative 服務。

    1. 執行部署命令。

      進入 my-agent-project 目錄，參見以下樣本部署服務。

      將 DASHSCOPE_API_KEY替換為實際值。
      agentscope deploy knative app_agent.py \
  --image-name agent_app \
  --env DASHSCOPE_API_KEY=sk-xxx \
  --image-tag linux-amd64-18 \
  --registry-url registry.cn-hangzhou.aliyuncs.com \
  --base-image registry.cn-hangzhou.aliyuncs.com/knative-sample/python:3.10-slim-bookworm \
  --registry-namespace knative-sample \
  --namespace default \
  --push

      展開查看命令文法說明

      agentscope deploy knative SOURCE [OPTIONS]

      • SOURCE：Python 檔案路徑，如 app_agent.py。

      • [OPTIONS]：常用參數如下：

        更多參數，可執行 agentscope deploy knative --help 查看。

        參數

        類型

        預設值

        說明

        --namespace

        string

        agentscope-runtime

        指定部署智能體的命名空間。

        --kube-config-path, -c

        path

        None

        指定串連叢集的 KubeConfig 檔案路徑。若不指定，則使用預設路徑。

        --port

        integer

        8080

        指定智能體應用在容器內監聽的連接埠。

        --image-name

        string

        agent_app

        為智能體應用構建的容器鏡像名稱。

        --image-tag

        string

        linux-amd64

        為智能體應用構建的容器鏡像標籤。

        --registry-url

        string

        localhost

        推送鏡像的目標容器鏡像倉庫地址，例如 registry.cn-hangzhou.aliyuncs.com。

        --registry-namespace

        string

        agentscope-runtime

        在容器鏡像倉庫中使用的命名空間（或專案）。

        --push

        flag

        False

        添加此標誌以將構建的鏡像推送到遠程倉庫。部署到遠程叢集時通常需要開啟。

        --base-image

        string

        python:3.10-slim-bookworm

        用於構建應用的基礎鏡像，需包含 Python 環境。

        --requirements

        string

        None

        指定應用的 Python 依賴。可以是一個 requirements.txt 檔案路徑，或用逗號分隔的包列表。

        --cpu-request

        string

        200m

        設定 Pod 的 CPU 資源請求。單位為 m（千分之一核）或整數核，例如 200m、1。

        --cpu-limit

        string

        1000m

        設定 Pod 的 CPU 資源限制。例如 1000m、2。

        --memory-request

        string

        512Mi

        設定 Pod 的記憶體資源請求。單位通常為 Mi 或 Gi，例如 512Mi、1Gi。

        --memory-limit

        string

        2Gi

        設定 Pod 的記憶體資源限制。例如 2Gi、4Gi。

        --image-pull-policy

        choice

        IfNotPresent

        設定 Pod 的鏡像拉取策略。可選值為 Always、IfNotPresent、Never。

        --deploy-timeout

        integer

        300

        等待 Knative 服務部署成功的逾時時間，單位為秒。

        --health-check

        flag

        None

        添加此標誌以在 Knative 服務中啟用健全狀態檢查。

        --platform

        string

        linux/amd64

        指定構建鏡像的目標硬體平台，例如 linux/amd64 或 linux/arm64。

        --pypi-mirror

        string

        None

        指定安裝 Python 包時使用的 PyPI 鏡像源，例如 https://pypi.tuna.tsinghua.edu.cn/simple。

    2. 查看部署結果。

      部署成功後，終端將輸出服務的存取 URL 等資訊。記錄此處的URL資訊，供下一步訪問服務。

      Deployment successful!
Deployment ID: d4b4a54d-9976-443c-a1da-a77643******
Resource Name: agent-d4b4*****
URL: http://agent-03e*****.default.example.com
Namespace: default

    步驟三：訪問已部署的智能體

    1. 擷取訪問網關。

      1. 在ACK叢集列表頁面，單擊目的地組群名稱，在叢集詳情頁左側導覽列，選擇應用 > Knative。

      2. 在服務管理或組件管理頁面，擷取訪問網關。

        頁面底部顯示訪問網關的 IP 位址（例如 120.xxx.159）。服務訪問前，需將訪問服務的網域名稱與訪問網關進行 Host 綁定。

    2. 通過 curl 命令向智能體服務發送請求。

      將下文中 115.29.xxx.xxx 替換為 Knative 訪問網關；將 Host 替換為此前擷取的存取 URL。
      curl -i -X POST "http://115.29.xxx.xxx:80/process" \
  -H "Content-Type: application/json" \
  -H "Host: agent-03e*****.default.example.com" \
  -d '{
    "input": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "Hello, how are you?"
          }
        ]
      }
    ],
    "session_id": "123"
  }'

    3. 查看返回結果，包含智能體思考過程和最終計算結果的流式響應。

    步驟四：觀察自動擴縮容

    • 自動縮容：在一段時間沒有請求後，Knative 會自動將該服務的 Pod 數量縮減為 0，以節省資源。可通過以下命令觀察 Pod 的變化。

      # 持續觀察指定命名空間下的 Pod
kubectl get pods -n default -w

      也可在Knative頁面單擊服務管理，然後單擊服務名稱，在頁面下方查看目前的版本的 Pod 運行情況。

      在修訂版本資訊頁簽下，當前修訂版本的 Ready/requested pods 列顯示為 0/0，確認 Pod 已縮容到零。

    • 自動擴容：當有新請求到達時，Knative 會在數秒內自動啟動新的 Pod 來處理請求。

    生產環境使用建議

    • 狀態持久化：範例程式碼中的 InMemoryStateService 和 InMemorySessionHistoryService 會在 Pod 重啟後丟失所有狀態和對話歷史，不適用於生產環境。生產部署時，應切換為基於 Redis 或其他持久化儲存的實現方案。

    • 密鑰管理：避免在命令列中直接傳遞或在代碼中寫入程式碼 API_KEY 等敏感資訊。推薦使用 Kubernetes Secrets，並通過 Knative Service 的配置將其作為環境變數掛載到容器中。

    • 資源規劃：根據業務負載，通過壓力測試評估併合理配置 --cpu-request、--cpu-limit、--memory-request、--memory-limit 等參數，確保服務的效能和穩定性。

    • 可觀測性：配置日誌收集（如 ACK 的Log Service）和監控警示（如 ARMS），以便於排查問題和掌握服務健全狀態。

    相關操作

    • 更新智能體：修改代碼後，使用新的鏡像標籤（例如 --image-tag v1.1）重新執行 agentscope deploy knative 命令即可實現變換。

    • 卸載智能體：

      # 將 resource-name 和 namespace 替換為您的實際值
kubectl delete ksvc <resource-name> -n <namespace>
      此操作僅刪除 Kubernetes 中的服務，不會刪除推送至鏡像倉庫的容器鏡像。