> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/tech/platform-development/gai-lan.md).

# 概覽

平台部署概覽：MaiAgent 平台本身不需 GPU，模型服務可用雲端 API 推論或地端自建 GPU，SaaS、私有雲、地端與混合雲的部署環境。

MaiAgent 平台除提供 SaaS 服務外，亦提供平台自建方案（私有雲、地端），MaiAgent 平台本身僅需要一般運算資源，無需 GPU 服務。MaiAgent 使用的模型服務（LLM, Embedding Model, Reranker Model）需要算力，可使用雲端 API 推論服務亦或是地端自建 GPU。\\

亦可採取混合雲的架構，MaiAgent 在地（私有雲、地端），模型服務（LLM, Embedding Model, Reranker Model）在雲端。三類模型可串接的雲端供應商不同（例如 Embedding 與 Reranker 不支援 Azure 與 Google Vertex AI），對照見[雲端模型推論 API 服務](https://docs.maiagent.ai/tech/platform-development/cloud-model-inference-api-service.md)；地端主機上可執行的模型與接法見[地端模型服務接入](https://docs.maiagent.ai/tech/platform-development/onprem-model-services.md)。未來若因資料安全與地端成本考量想改用地端算力，也可以改接自建的推論服務（知識庫建立後無法更換 Embedding 模型，改用其他 Embedding 模型需另建知識庫並重新匯入文件）。

## MaiAgent 平台總覽

**MaiAgent** 是一個完整的生成式 AI 平台，提供從系統後端到使用者前端的全方位服務。平台採用可擴展的微服務架構，可以用雲端託管服務建置（下表的 AWS、GCP、Azure 欄），也可以用部署包安裝在雲端虛擬機或客戶機房，支援 Docker 單機、Docker 分散式與 Kubernetes 三種部署型態，能根據企業需求靈活部署。

平台核心以 **Docker** 為基礎，結合多元的服務模組，涵蓋 API、任務排程、資料儲存、快取管理，以及前後台應用程式。其整體設計確保了 **高可用性、彈性擴展性與跨雲整合能力**，同時兼顧安全性與可維運性。

| 服務項目                                            | 用途                                                                                                                  | AWS                                              | GCP                         | Azure                                                       | 虛擬機、地端（部署包）                                    |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | --------------------------- | ----------------------------------------------------------- | ---------------------------------------------- |
| MaiAgent Server                                 | MaiAgent 核心、API、系統管理後台                                                                                              | ECS (Fargate)                                    | Cloud Run                   | Container Apps                                              | Django on Docker                               |
| MaiAgent Worker Server                          | MaiAgent 處理排隊、非同步服務的 Worker，特別是訊息串流輸出                                                                               | ECS (Fargate)                                    | Cloud Run                   | Container Apps                                              | Django on Docker                               |
| <p>MaiAgent Worker Server<br>(Low-Priority)</p> | MaiAgent 處理排隊、非同步服務的 Worker，特別是文件向量化                                                                                | ECS (Fargate)                                    | Cloud Run                   | Container Apps                                              | Django on Docker                               |
| 排程器（Celery Beat）                                | 觸發週期性任務，固定只執行一個                                                                                                     | ECS (Fargate)                                    | Cloud Run                   | Container Apps                                              | Celery Beat on Docker                          |
| 訊息佇列（Message Broker）                            | 傳遞要交給 Worker 處理的背景任務                                                                                                | Amazon MQ（RabbitMQ），或與記憶體快取共用（ElastiCache Redis） | 與記憶體快取共用（Memorystore Redis） | 與記憶體快取共用（Azure Managed Redis），或 RabbitMQ on Azure VM        | RabbitMQ on Docker                             |
| 反向代理、負載平衡                                       | 對外的 HTTPS 入口與 TLS 終止                                                                                                | ALB                                              | Cloud Load Balancing        | Container Apps 內建入口（API）；前端經 Azure Front Door               | Nginx（Kubernetes 部署為 Traefik 或 Cilium Gateway） |
| MaiAgent Admin 前端                               | MaiAgent 管理平台                                                                                                       | S3 + CloudFront                                  | GCS+Google Cloud CDN        | Storage Account 靜態網站 + Azure Front Door                     | Nginx + Static Files on Docker                 |
| MaiAgent Web Chat 前端                            | MaiAgent 網頁對話前台                                                                                                     | S3 + CloudFront                                  | GCS+Google Cloud CDN        | Storage Account 靜態網站 + Azure Front Door                     | Nginx + Static Files on Docker                 |
| 關聯式資料庫(RDB) - PostgreSQL                        | 儲存 MaiAgent 各項資料                                                                                                    | RDS                                              | Cloud SQL                   | Azure Database for PostgreSQL Flexible Server（內建 PgBouncer） | PostgreSQL on Docker，前面加一層連線池 PgBouncer        |
| 向量資料庫(Vector DB) - Elasticsearch                | 儲存 RAG, 記憶功能所需的向量（知識庫也可改用[自帶向量資料庫](https://docs.maiagent.ai/tech/platform-development/bring-your-own-vector-db.md)） | Elasticsearch                                    | Elasticsearch               | Elasticsearch on Azure VM                                   | Elasticsearch on Docker（附 Kibana）              |
| 靜態儲存體(Storage)                                  | 儲存上傳的檔案、靜態文件                                                                                                        | S3                                               | GCS                         | Azure Blob Storage                                          | Garage on Docker（新安裝的預設；既有環境沿用 MinIO）          |
| 記憶體快取(Memory Cache) - Redis                     | API 快取；部分雲端架構同時作為訊息佇列                                                                                               | ElastiCache                                      | Memorystore                 | Azure Managed Redis                                         | Redis on Docker                                |

* **AWS、GCP、Azure 欄**是以該雲端的託管服務建置的架構，由 MaiAgent 以 Terraform 部署與維運。其他雲端的託管服務組合依專案評估，請洽 MaiAgent 窗口；也可以在雲端虛擬機上以部署包安裝（同右欄）。
* **虛擬機、地端欄**另外會部署背景工作的監控介面（Flower）。部署包的選配元件有：本機模型服務（vLLM，需要 GPU）、離線語音辨識、即時語音（LiveKit）、Code Interpreter 沙箱（限 Docker 部署）、Ask AI（MCP Server），以及監控（VictoriaMetrics、VictoriaLogs、Grafana）。
* 部署型態與主機規格見[部署型態與功能對照](https://docs.maiagent.ai/tech/platform-development/onprem-deployment-types.md)與[系統需求](https://docs.maiagent.ai/tech/platform-development/system-requirements.md)。

## 模型服務

**MaiAgent** 平台在設計上同時兼容「**雲端 API 推論服務」**&#x8207;「**自建 GPU 環境」**。

* 在 **雲端 API 推論服務** 下，MaiAgent 能直接串接各類 LLM、Embedding、Reranker API，快速擴容並支援動態流量需求，方便實驗與快速上線。
* 在 **自建 GPU 模式** 下，MaiAgent 可以與部署於本地或私有數據中心的模型服務串接，充分利用 GPU 資源並做最佳化推論，同時確保數據隱私與合規。

使用者可以依照需求，在彈性與成本之間自由切換，甚至混合使用兩種方式，讓 **MaiAgent** 成為統一的推論與服務管理層。

| <p><br></p>    | 雲端 API 推論服務                                                                                                        | 自建 GPU                                                                                 |
| -------------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
| MaiAgent 平台兼容  | <p>AWS Bedrock<br>Google Vertex AI<br>Azure<br>OpenAI、Anthropic、Cohere<br>OpenAI 相容 API（如 OpenRouter、Groq、xAI）</p> | <p>搭載 NVIDIA GPU 的伺服器，例如：<br>HPE（慧與科技）<br>Advantech（研華科技）<br>Cisco（思科）<br>Dell（戴爾）</p> |
| 模型能力           | <p>閉源模型：高<br>開源模型：同自建 GPU</p>                                                                                      | 根據開源模型釋出而定                                                                             |
| 速度             | 依模型與供應商而定                                                                                                          | 依模型、GPU 規格與同時請求數而定                                                                     |
| 投入成本           | <p>Token API 費用<br>(pay-as-you-go)</p>                                                                             | <p>機器費用</p><p>機房費用</p><p>機器與模型維運人力費用</p><p>機器折舊</p>                                    |
| Concurrent 請求數 | 根據雲端服務供應商廠商支援                                                                                                      | 根據 GPU 規格、數量與模型而定，請洽 MaiAgent 評估                                                       |
| 資料安全性          | 使用承諾不將資料拿去做訓練的 雲端服務供應商（AWS, GCP, Azure）                                                                            | 高機密性、最安全                                                                               |
| 個資問題           | 使用 DLP Server 或服務去除個資                                                                                              | 無                                                                                      |

組織可以使用哪些雲端模型，見使用者手冊[模型調用權限](https://docs.maiagent.ai/org/model-access)。自建 GPU 時，可在主機上執行的模型與建議 GPU 見 [GPU 算力硬體規劃](https://docs.maiagent.ai/tech/platform-development/gpu.md)，主機規格見[系統需求](https://docs.maiagent.ai/tech/platform-development/system-requirements.md)，接法見[地端模型服務接入](https://docs.maiagent.ai/tech/platform-development/onprem-model-services.md)。

## 平台部署環境

為滿足不同客戶在開發、測試與上線過程中的需求，我們的軟體平台提供多個分層環境。這些環境的設置，確保了從開發階段到正式上線的每一個流程，都能被妥善驗證與控管。

### 環境架構

我們的平台建置遵循業界最佳實踐，並根據客戶需求彈性提供以下環境：

| 環境名稱 | 備註              | 主要用途    | 特點                                 |
| ---- | --------------- | ------- | ---------------------------------- |
| PROD | 行內              | 生產環境    | 正式對外服務，使用真實數據，要求高度穩定性與安全性。         |
| UAT  | 行內              | 使用者驗收測試 | 供客戶與業務單位驗收，確認系統功能符合需求，環境與生產環境相近。   |
| SIT  | 行內，因為可能需要串接內部系統 | 系統整合測試  | 驗證不同模組與服務之間的整合與相容性，使用接近真實的測試資料。    |
| DEV  | 加值功能行外開發加快速度    | 開發測試環境  | 供開發人員進行程式開發與單元測試，使用模擬資料，更新頻繁，容忍錯誤。 |

### 環境組合

不同客戶可依專案需求選擇合適的環境組合，例如：

* **僅 PROD**：適合小型專案或單純上線需求，直接部署於生產環境。
* **PROD + UAT**：適合需要驗收測試的專案，確保功能符合需求後再上線。
* **完整環境組合（DEV + SIT + UAT + PROD）**：適合大型或複雜專案，需經過完整的開發、整合測試與驗收流程。

我們會根據客戶需求彈性配置，確保在成本與品質之間取得最佳平衡。

### 環境怎麼隔離 <a href="#environment-isolation" id="environment-isolation"></a>

私有雲與地端以部署包安裝時，**每個環境是一套獨立的安裝**：各有自己的部署設定（設定裡的環境標識為 dev、staging、uat 或 prod；上表的 SIT 通常對應 staging），裝在各自的主機或 Kubernetes 叢集上，資料庫、物件儲存、搜尋索引、金鑰與憑證都不共用。各環境之間沒有平台層的資料同步；要把測試環境調好的設定搬到正式環境，技能可以用後台的技能包匯出與匯入，Agent 設定與知識庫文件要在正式環境重新建立與上傳。

* **主機**：正式環境建議獨立主機或叢集；DEV 與 SIT 可以共用一台主機，但要分成兩套安裝（不同的部署目錄與連線埠或網域）。
* **網路**：各環境各自的網域（或 IP 加埠號）與 TLS 憑證；SIT 要串接內部系統時，防火牆只放行該環境的主機。
* **模型服務**：可以共用同一組模型服務（例如一台 GPU 主機服務多個環境），也可以各自接雲端模型。
* **帳號與權限**：各環境的使用者帳號與角色獨立設定，建議以 SSO 或 LDAP 身分同步統一管理。
* **晉級**：新版本先在 UAT 升級並驗收，再排正式環境的升級時段；升級流程見[版本與升級](https://docs.maiagent.ai/tech/platform-development/onprem-versioning-and-upgrades.md)。

SaaS 的環境分層由 MaiAgent 維運，客戶不需要準備；要在 SaaS 上區分測試與正式用途時，用不同的組織。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/tech/platform-development/gai-lan.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
