> 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/onprem-model-services.md).
# 地端模型服務接入
私有雲與地端部署怎麼接模型：部署包內建的本機模型目錄（vLLM）、接既有的 OpenAI 相容模型服務（含網址 /v1 規則）、雲端模型自備金鑰，以及自備 Embedding 與 Reranker 的限制
MaiAgent 需要三種模型才能運作：大型語言模型（LLM）、Embedding 與 Reranker。私有雲與地端部署可以從三種來源取得這些模型，也可以混用，例如 LLM 用雲端、Embedding 與 Reranker 在主機上執行。本頁寫給規劃模型與 GPU 的客戶 IT 與 SI 夥伴。
{% hint style="info" %}
模型在部署時寫進部署設定。本頁說明各種接法的規則與限制；實際的設定欄位寫在隨部署包提供的安裝手冊，請洽 MaiAgent 窗口取得。
{% endhint %}
## 三種接法
| 接法 | 說明 | 適合 |
| ------------ | -------------------------------------- | ------------------- |
| 在主機上執行（本機模型） | 部署包在 GPU 主機上啟動 vLLM 模型服務，模型從部署包的模型目錄挑選 | 資料不能離開機房、已備有 GPU |
| 接既有的模型服務 | 客戶已經有 OpenAI 相容的模型服務，填入網址與金鑰即可 | 已有自建推論平台或模型中繼服務 |
| 接雲端模型服務 | 客戶自備雲端供應商的金鑰，由 MaiAgent 直接呼叫雲端 API | 可接受資料送往雲端供應商、想用閉源模型 |
離線安裝也能接外部或雲端的模型服務：離線指的是安裝物料不從網路下載，只要防火牆放行主機到模型服務的連線即可（實測環境只放行模型服務的 443 埠）。
## 本機模型目錄
部署包的模型目錄提供以下模型，用 vLLM 執行。權重不包含在部署包裡：連線安裝時自動從 Hugging Face 下載，離線安裝要在備料時一起下載。
| 模型 | 類型 | 重點 | 預設 context |
| ---------------------------------- | --------- | ---------------------- | ---------- |
| gpt-oss-20b | LLM | 支援工具呼叫 | 128K |
| gpt-oss-120b | LLM | 支援工具呼叫 | 128K |
| Gemma 3 4B | LLM | 支援圖片輸入；**不支援工具呼叫** | 128K |
| Gemma 4 26B A4B | LLM | MoE 架構，支援工具呼叫與圖片輸入 | 128K |
| Gemma 4 31B | LLM | 支援工具呼叫與圖片輸入 | 64K |
| Qwen3.6 27B（FP8） | LLM | 支援工具呼叫 | 32K |
| Qwen3-VL 32B | LLM | 支援工具呼叫與圖片輸入（每次最多 5 張圖） | 32K |
| jina-embeddings-v3 | Embedding | — | — |
| jina-reranker-v2-base-multilingual | Reranker | 多語言 | — |
| bge-reranker-v2-m3 | Reranker | — | — |
* 各模型的權重大小與建議 GPU 見 [GPU 算力硬體規劃](/tech/platform-development/gpu.md)。Embedding 與 Reranker 預設只占一小部分 GPU 記憶體，可以和 LLM 共用同一張卡。
* Agent 要使用工具（Agent 模式）時，請選支援工具呼叫的 LLM；Gemma 3 4B 不適合。
* 表中的 context 是部署範本的預設值，依 GPU 記憶體設定；要調整請洽 MaiAgent 評估。
* 目錄以外的開放權重模型，請洽 MaiAgent 評估。
## 接既有的 OpenAI 相容模型服務
每個模型都可以改成「外部服務」，填入網址與金鑰；模型服務不需要金鑰時，可留空使用預設值。
**網址規則**（最常見的設定錯誤）：
| 模型類型 | 網址要不要包含 `/v1` | 例子 |
| --------- | ------------- | -------------------------- |
| LLM | 要 | `http://10.0.0.20:8001/v1` |
| Embedding | 要 | `http://10.0.0.20:8001/v1` |
| Reranker | **不要** | `http://10.0.0.20:8001` |
系統呼叫 Reranker 時會自己加上 `/v1/rerank`。Reranker 網址填成 `…/v1`，實際會打到 `…/v1/v1/rerank`，知識庫搜尋與 FAQ 搜尋會全部失敗。
其他規則：
* **模型名稱**：模型服務上的模型名稱和部署設定預設的名稱不同時，要在部署設定另外指定模型服務上的名稱。
* **安裝後改設定**：改完模型網址或金鑰，只要重新載入模型設定（實測約 1 分鐘），不需要重新安裝。一般的重新安裝會略過已載入的模型設定，改了不會生效。
## 接雲端模型服務（自備金鑰）
私有雲與地端部署呼叫雲端模型時，使用客戶自己的雲端帳號與金鑰。部署設定可以填入以下供應商的憑證：OpenAI、Anthropic、Azure、AWS Bedrock、Cohere、Voyage、Gemini、Groq、Google Vertex AI。各供應商能用在 LLM、Embedding 還是 Reranker 不同，對照見[雲端模型推論 API 服務](/tech/platform-development/cloud-model-inference-api-service.md)。
* 主機要能連到該雲端服務。
* **AWS Bedrock**：金鑰所屬的 IAM 身分需要「呼叫模型」權限（含串流與跨區域 inference profile；Claude 系列在多數區域只能透過 inference profile 呼叫）。有使用 Bedrock Guardrails 或 Bedrock 的 Reranker 時，另外加上對應權限。IAM policy 範例隨部署包提供。
* **Bedrock 與後端版本**：`2026.Q3-08.24` 到 `2026.Q3-09.14` 之間的後端無法使用 Bedrock 金鑰，請使用 `2026.Q3-09.15` 之後的版本。
* **AI Gateway**：地端部署的 AI Gateway 只能使用自建的模型，見[部署型態與功能對照](/tech/platform-development/onprem-deployment-types.md#feature-availability)。
### 混合雲：平台在地、模型在雲端
平台裝在客戶機房或客戶雲端、模型用雲端供應商，就是上面「接雲端模型服務」的接法，沒有另外的部署型態或元件。設定順序：
{% stepper %}
{% step %}
### 決定每種模型的來源
LLM、Embedding、Reranker 各自決定走雲端還是主機；常見的組合是 LLM 用雲端、Embedding 與 Reranker 在主機上執行（資料不出內網、也不需要大卡）。Embedding 與 Reranker 能用的雲端供應商較少，見[雲端模型推論 API 服務](/tech/platform-development/cloud-model-inference-api-service.md)。
{% endstep %}
{% step %}
### 放行主機到供應商端點的連線
只需要主機連出去（443 埠）到各供應商的 API 端點；供應商不會連回主機。要經過 proxy 或只開白名單時，請在部署前告知 MaiAgent。離線安裝的環境也可以這樣接，見本頁開頭的說明。
{% endstep %}
{% step %}
### 把金鑰填進部署設定
在部署設定填入供應商的憑證（AWS Bedrock 要先備妥有「呼叫模型」權限的 IAM 身分）。部署設定含金鑰，請依公司規定保存；安裝後要換金鑰或改模型，重新載入模型設定即可，不需重新安裝。
{% endstep %}
{% step %}
### 驗證
安裝或重新載入設定後，執行功能驗收測試確認對話與知識庫搜尋都正常；再到後台的[模型調用權限](https://docs.maiagent.ai/org/model-access)確認組織看得到這些模型。
{% endstep %}
{% endstepper %}
{% hint style="warning" %}
* **不會自動切換**：雲端模型逾時或供應商停機時，平台不會自動改用主機上的模型；需要備援請在規劃時洽 MaiAgent。
* **改回地端算力**：LLM 與 Reranker 可以隨時換成主機上的模型；Embedding 一旦被知識庫使用就不能更換，要換 Embedding 需另建知識庫並重新匯入文件。
* **資料流**：對話內容會送到雲端供應商處理；只有模型呼叫出內網，對話紀錄、知識庫檔案與向量仍留在主機上。
{% endhint %}
## 自備 Embedding 與 Reranker 的限制
| 限制 | 說明 |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Embedding 服務要接受兩個參數 | MaiAgent 會送出 `encoding_format: base64` 與 `truncate_prompt_tokens`。不接受的服務會拒絕請求，知識庫檔案全部解析失敗。接上前請向模型服務的提供者確認 |
| Embedding 名稱有冒號（`:`） | 要另外指定索引名稱，只能用英文小寫、數字與連字號；沒指定時知識庫無法建立搜尋索引 |
| Reranker 網址 | 不加 `/v1`，見上方網址規則 |
| 支援的供應商類型 | Embedding：vLLM、Ollama、OpenAI、Cohere、Voyage、AWS Bedrock；Reranker：Cohere、Voyage、AWS Bedrock、FlagEmbedding、vLLM。Azure 與 Google Vertex AI 不支援 Embedding 與 Reranker |
實測例子：經同一個 OpenAI 相容的模型中繼服務呼叫時，Cohere Embed v4 可以使用；Cohere Embed Multilingual v3 不接受 `encoding_format: base64`、Amazon Titan Text Embeddings V2 不接受 `truncate_prompt_tokens`，在該環境下都無法當作 Embedding 使用。
## 常見問題
**知識庫搜尋、FAQ 搜尋都失敗，其他功能正常。**\
先檢查 Reranker 網址是不是多加了 `/v1`。改好後重新載入模型設定，再執行一次功能驗收測試確認。
**接上外部模型服務後，知識庫檔案全部「解析失敗」。**\
多半是 Embedding 的問題：確認模型服務接受上表的兩個參數，以及名稱有冒號時已指定索引名稱。
**不同問題得到相同回覆。**\
模型服務沒有正確回應，常見原因是網址或模型名稱填錯。
## 相關頁面
* [GPU 算力硬體規劃](/tech/platform-development/gpu.md)
* [雲端模型推論 API 服務](/tech/platform-development/cloud-model-inference-api-service.md)
* [系統需求](/tech/platform-development/system-requirements.md)
* 使用者手冊[模型調用權限](https://docs.maiagent.ai/org/model-access)
---
# 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/onprem-model-services.md?ask=&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.