系統需求

私有雲與地端部署的主機需求：CPU、記憶體、磁碟、作業系統、對外與內部連線埠、依服務人數的建議規格，以及 GPU 節點的驅動與運算能力需求

本頁列出以部署包安裝 MaiAgent（私有雲或地端）時，主機要準備的規格與網路條件，寫給規劃硬體與網路的客戶 IT 與 SI 夥伴。部署型態的差異見部署型態與功能對照。

下方「最低」與「建議」是部署包安裝前檢查使用的門檻，用來判斷主機能不能安裝，不是採購規格。正式環境的硬體規劃請洽 MaiAgent 評估。

主機門檻

項目	最低（不符合就不能安裝）	建議（低於只適合測試、PoC）
CPU	—	8 vCPU
記憶體	16 GB	48 GB
可用磁碟（部署目錄所在的磁碟；Docker 資料目錄在另一顆磁碟時，那一顆也要看）	40 GB（全新安裝）	200 GB

• 記憶體以系統回報的數字判斷，會比標稱容量少一點（64 GB 的主機約顯示 61 GB），檢查已把這個差距算進去。

• 映像下載與載入需要雙倍空間，所以全新安裝至少要 40 GB 可用空間；後端映像單一檔案約 7.5 GB。

• 升級時需要額外空間放新版部署包與映像，見版本與升級：升級前要準備的空間。

依服務人數的建議規格

Docker 單機、所有服務在同一台主機時的建議規格，不含在本機執行模型所需的 GPU 資源：

服務人數	建議規格
200 人以下	12 vCPU／64 GB
400 人以下	16 vCPU／64 GB
超過 400 人	建議改用 Docker 分散式或 Kubernetes，規格請洽 MaiAgent 評估

這組數字來自 MaiAgent 的壓力測試，假設同時在線人數約為服務人數的 20%。實際負載（知識庫大小、檔案解析量、同時對話數）差異大時，請洽 MaiAgent 重新評估。

Docker 分散式的實測拓樸（部署主機 8 vCPU／32 GB，資料主機與背景工作主機各 4 vCPU／16 GB）見部署型態與功能對照：Docker 分散式。

Kubernetes 規模設定

Kubernetes 部署依規模設定配置各服務的儲存容量：

規模	適用	PostgreSQL	Redis	物件儲存	Elasticsearch（容量／heap）	映像倉庫
test	單節點 PoC	5Gi	2Gi	5Gi	5Gi／2g	30Gi
small	10 人以下	10Gi	2Gi	20Gi	10Gi／4g	50Gi
mid	100 人以下	20Gi	5Gi	50Gi	30Gi／8g	50Gi
large	正式環境	100Gi	10Gi	200Gi	100Gi／16g	100Gi

• 映像倉庫只在多節點時安裝；單節點直接把映像匯入節點，不占這一欄的空間。

• Elasticsearch 的記憶體會保留 heap 大小、上限是 heap 的兩倍（mid：8Gi／16Gi），節點的可用記憶體要放得下。

• 單節點時所有容量都放在同一台主機的儲存路徑，儲存元件（Longhorn）會保留磁碟的 20% 不用。放不下時服務會停在 Pending、安裝中途失敗，請改選較小的規模或改用更大的磁碟。

作業系統與帳號

項目	需求
作業系統	Ubuntu 22.04／24.04／26.04、RHEL 8／9、Rocky Linux 8／9
CPU 架構	amd64 或 arm64
帳號	一個有 sudo 權限的一般帳號；安裝程式不接受以 root 執行
Docker	不需要預先安裝，由部署流程安裝

• RHEL／Rocky Linux：要先關閉 SELinux 並重新開機。RHEL／Rocky 8 離線安裝需要 8.10 以上。

• Kubernetes 1.36 用在 RHEL／Rocky 8：要 8.6 以上，並切換到 cgroup v2。

• 離線安裝時，部署包要包含目標主機作業系統的離線套件；主機盤點會列出需要的版本，缺少時請 MaiAgent 提供對應的部署包。

連線埠

主機上不能被其他服務占用的埠：80、443、5432、6379、9000、9200；以 IP 加埠號連線時另加 8000、3333、3334。

要對使用者開放的埠（防火牆或安全群組）：

使用者連線方式	要開放的埠
IP 加埠號	8000（API）、3333（後台）、3334（對話頁）、9000（物件儲存；瀏覽器上傳與下載檔案會直接連這個埠）
每個服務一個網域	80、443

• Kubernetes 只支援「每個服務一個網域」。

• Docker 分散式：部署主機要能以 SSH 金鑰登入其他主機；主機之間還需要互通資料庫、快取、搜尋引擎、物件儲存與訊息佇列的連線，實際清單依拓樸而定，請洽 MaiAgent 提供。

連線安裝時主機要能連到的地方（離線安裝不需要）：MaiAgent 的映像與部署包下載站、Hugging Face（在本機執行模型時下載權重）、Docker Hub（本機模型服務的映像）、Docker 官方套件來源、PyPI，以及作業系統的套件來源。只開白名單、要經過 proxy，或只連得到其中一部分時，一律改用離線安裝，見維運重點：離線安裝。

營運時主機要連出去的地方

安裝完成後，平台只在使用對應功能時才需要主機連出去；連線一律由 MaiAgent 主機主動發起，防火牆只要放行主機到目的地的方向。全部不開放也能運作（只用主機上的模型、不接外部系統）。

功能	目的地	常見埠號
模型服務在另一台主機或雲端	模型服務的網址，或雲端供應商的 API 端點	443，或模型服務自訂的埠
資料庫功能（Text to SQL）接客戶既有資料庫	客戶的 PostgreSQL、MySQL、SQL Server、Oracle 或 SynxDB	5432、3306、1433、1521（依資料庫設定）
知識庫改用自帶向量資料庫	客戶的 Elasticsearch、OpenSearch、Oracle 或 SynxDB	9200、1521、5432
對話平台（LINE、Teams、Email 等）	各平台的 API；Email 另需 SMTP／IMAP 伺服器	443；SMTP 25／465／587
寄送邀請信、通知信	客戶的 SMTP 伺服器	25／465／587
爬蟲、網路搜尋、地圖、圖片與影片生成	對應的雲端服務（見功能可用性對照）	443
單一登入（SSO）與 LDAP 身分同步	客戶的 IdP 或目錄伺服器	依 IdP；LDAP 389／636
自架 MCP Server、API 工具	客戶指定的網址	依服務

• 只有連出，沒有連入：客戶內部系統不需要主動連到 MaiAgent 主機，例外是對話平台的 webhook（LINE、Messenger 等平台要能從網際網路呼叫 MaiAgent 的 API）與客戶自己寫的 API 串接。

• 內部網段：主機與客戶內部資料庫、模型主機之間的路由由客戶網路團隊規劃；部署包不包含 VPN、專線或 VPC 對等連線等網路元件。主機放在客戶雲端上時，與機房內資料庫的連線請用客戶既有的雲端到機房連線（VPN 或專線）。

• SaaS 連到客戶內部資料庫時，連線來自 MaiAgent 的雲端服務，需要在客戶防火牆放行來源 IP，請洽 MaiAgent 窗口取得；需要 VPN 或 VPC 對等連線等其他接法時，請先洽 MaiAgent 評估。資料庫端的檢查項目見使用者手冊建立與設定資料庫：網路前置。

GPU 節點

平台本身不需要 GPU。只有在主機上自建模型服務或離線語音辨識時才需要：

項目	需求
作業系統	與平台主機相同（Ubuntu 22.04／24.04／26.04、RHEL 8／9、Rocky Linux 8／9，amd64 或 arm64），見作業系統與帳號
GPU	NVIDIA GPU，運算能力（compute capability）7.0 以上，例如 V100、A100、H100
NVIDIA 驅動	525.60 以上
NVIDIA Container Toolkit	部署時自動安裝（連線與離線安裝都支援 Ubuntu 與 RHEL／Rocky，離線安裝的套件隨部署包提供）
GPU 容器執行環境	由部署流程把 Docker（或 Kubernetes 節點的容器執行環境）設定成使用 NVIDIA runtime；主機上已裝好驅動、Toolkit 與 runtime 時會直接沿用

• 驅動由誰裝：連線安裝且主機是 Ubuntu 時，部署流程會自動安裝最適合的 NVIDIA 驅動並重新開機；RHEL／Rocky Linux 或離線安裝時，請在部署前自行安裝驅動，確認 nvidia-smi 可以執行後再開始部署。

• NVSwitch 平台（HGX／DGX 的 SXM GPU）要在部署設定開啟 NVIDIA Fabric Manager。

• 使用 FP8 的模型設定（FP8 KV cache）需要 Ada Lovelace、Hopper 或 Blackwell 世代；Ampere 世代（例如 A100）不支援。各模型的 GPU 建議見 GPU 算力硬體規劃。

• NVIDIA GB10（Dell Pro Max GB10、DGX Spark，GPU 與系統共用 128 GB 記憶體）要改用另一種 GPU 掛載方式，而且同一台主機上所有模型服務的記憶體占用比例合計不要超過 0.92，部署時請告知 MaiAgent。

• 部署範本只支援 NVIDIA GPU。其他加速卡請洽 MaiAgent 評估。

• 離線語音辨識需要 GPU。離線文件解析（Docling）本身不需要 GPU；要描述文件裡的圖片時，需要接一個 OpenAI 相容的 LLM（例如主機上的模型服務）。

相關頁面

• 部署型態與功能對照

• 地端模型服務接入

• GPU 算力硬體規劃