地端模型服務接入

私有雲與地端部署怎麼接模型：部署包內建的本機模型目錄（vLLM）、接既有的 OpenAI 相容模型服務（含網址 /v1 規則）、雲端模型自備金鑰，以及自備 Embedding 與 Reranker 的限制

MaiAgent 需要三種模型才能運作：大型語言模型（LLM）、Embedding 與 Reranker。私有雲與地端部署可以從三種來源取得這些模型，也可以混用，例如 LLM 用雲端、Embedding 與 Reranker 在主機上執行。本頁寫給規劃模型與 GPU 的客戶 IT 與 SI 夥伴。

模型在部署時寫進部署設定。本頁說明各種接法的規則與限制；實際的設定欄位寫在隨部署包提供的安裝手冊，請洽 MaiAgent 窗口取得。

三種接法

接法	說明	適合
在主機上執行（本機模型）	部署包在 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 算力硬體規劃。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 服務。

• 主機要能連到該雲端服務。

• 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 只能使用自建的模型，見部署型態與功能對照。

混合雲：平台在地、模型在雲端

平台裝在客戶機房或客戶雲端、模型用雲端供應商，就是上面「接雲端模型服務」的接法，沒有另外的部署型態或元件。設定順序：

1

決定每種模型的來源

LLM、Embedding、Reranker 各自決定走雲端還是主機；常見的組合是 LLM 用雲端、Embedding 與 Reranker 在主機上執行（資料不出內網、也不需要大卡）。Embedding 與 Reranker 能用的雲端供應商較少，見雲端模型推論 API 服務。

2

放行主機到供應商端點的連線

只需要主機連出去（443 埠）到各供應商的 API 端點；供應商不會連回主機。要經過 proxy 或只開白名單時，請在部署前告知 MaiAgent。離線安裝的環境也可以這樣接，見本頁開頭的說明。

3

把金鑰填進部署設定

在部署設定填入供應商的憑證（AWS Bedrock 要先備妥有「呼叫模型」權限的 IAM 身分）。部署設定含金鑰，請依公司規定保存；安裝後要換金鑰或改模型，重新載入模型設定即可，不需重新安裝。

4

驗證

安裝或重新載入設定後，執行功能驗收測試確認對話與知識庫搜尋都正常；再到後台的模型調用權限確認組織看得到這些模型。

• 不會自動切換：雲端模型逾時或供應商停機時，平台不會自動改用主機上的模型；需要備援請在規劃時洽 MaiAgent。

• 改回地端算力：LLM 與 Reranker 可以隨時換成主機上的模型；Embedding 一旦被知識庫使用就不能更換，要換 Embedding 需另建知識庫並重新匯入文件。

• 資料流：對話內容會送到雲端供應商處理；只有模型呼叫出內網，對話紀錄、知識庫檔案與向量仍留在主機上。

自備 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 算力硬體規劃

• 雲端模型推論 API 服務

• 系統需求

• 使用者手冊模型調用權限