---
title: AI 提供者
description: 為 AI Chat 和 AI Agent 連線相容 OpenAI 的 AI 端點 — 開啟 AI 模組開關、輸入端點與金鑰、進行測試並設定限制。
url: https://nexcmp.com/zh-tw/docs/ai/ai-providers/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# AI 提供者 {#ai-provider}

> **管理後台位置：** System › Settings › AI provider (`/settings/ai`)。AI 模組開關位於該處，以及 System › Admin › License & updates (`/license`) 的 **Module** 卡片中。

## 功能 {#what-it-does}

AI Chat（自動支援聊天）與 AI Agent（以日常語言管理 VM）未隨附內建模型。您必須選擇**自己的提供者**：任何提供**相容 OpenAI** `chat/completions` API 的服務 — 例如 OpenAI、OpenRouter、LiteLLM 閘道或您自己的 vLLM 伺服器。NexCMP 會儲存端點與 API 金鑰（已加密）並將其用於各項 AI 功能。您直接向提供者付費。

## 需求 {#requirements}

| 項目 | 需求 |
|---|---|
| Endpoint | 相容 OpenAI 的 Base URL（`https://api.openai.com/v1`、`https://ai.example.com/v1`）。NexCMP 會將 `/chat/completions` 加到以 `/v1` 結尾的 URL；對於任何其他 URL，則會加上 `/v1/chat/completions`；若 URL 本身已以 `/chat/completions` 結尾，則直接使用。 |
| 模型 | 支援**工具（函式）呼叫**的模型。AI Chat 與 Agent 均依賴它。 |
| API 金鑰 | 該端點的金鑰。建議在供應商端設定**消費上限**（例如具有每月預算的 LiteLLM 虛擬金鑰）。 |
| 網路 | 面板伺服器必須透過 HTTP(S) 存取該端點。表單中輸入的 URL 僅允許指向網際網路的 80、443、8080 或 8443 連接埠；若要使用內部位址，請先儲存供應商再進行測試。 |
| 相依項目 | **AI** 模組已開啟。關於 Agent 請參閱 [AI Agent](https://nexcmp.com/zh-tw/docs/ai/ai-agent/#requirements)。 |

## 準備基礎設施 {#prepare-the-infrastructure}

1. 向供應商註冊並建立 API 金鑰。若供應商支援預算或速率限制，請設定每月上限。
2. 記錄**基礎 URL** 與確切的**模型名稱**（並可選擇性最多四個備用模型）。
3. 在輸入之前，先從 NexCMP 伺服器進行測試：

   ```bash
   curl -s https://ai.example.com/v1/chat/completions \
     -H "Authorization: Bearer XXXX" -H "Content-Type: application/json" \
     -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Reply with one word: OK"}]}'
   ```

   帶有 `choices[0].message.content` 的 JSON 回應代表端點運作正常。

## 在 NexCMP 中連線 {#connect-in-nexcmp}

1. 開啟 **System › Settings › AI provider**。
2. 在 **Module AI** 卡片中將模組切換為**開啟**。在開啟之前，客戶無法在客戶端看到 AI Chat 或 AI Agent。（您也可以在 **License & updates** 中切換它。）
3. 在 **Connection** 卡片中填入：

   | 欄位 | 範例 | 注意事項 |
   |---|---|---|
   | 使用此供應商 | on | 需要基礎 URL、模型與金鑰才能啟用。 |
   | 顯示名稱 | `LiteLLM` | 最多 60 個字元。 |
   | 基礎 URL（相容於 OpenAI） | `https://ai.example.com/v1` | `http://` 或 `https://`，最多 300 個字元，不可有空格。 |
   | 供應商 API 金鑰 | `sk-XXXX` | 會以加密方式儲存；之後僅會顯示最後 4 個字元。保持空白即可保留已儲存的金鑰。 |
   | 預設模型 | `gpt-4o-mini` | 英文字母、數字與 `- _ . / : @`。 |
   | 備用模型 | `gemini-2.5-flash` | 以逗號分隔，最多 4 個。當預設模型失敗時使用。 |
   | 推理強度 | 預設（不傳送） | `Minimal`、`Low`、`Medium` 或 `High`。對於推理模型（Gemini、o 系列），低階層的回應速度會快得多。一般模型請保持預設值。 |

4. 點擊 **Save**，然後點擊 **Test connection**。測試會發送一個簡短的問題，並顯示 `Connected — <model>, <ms> ms` 或供應商傳回的錯誤。

![已開啟 AI 模組且連線表單已填入範例數值的 AI provider 頁面](https://nexcmp.com/zh-tw/docs/images/ai/ai-providers-01-connection.webp)


### 儲存的作用 {#what-saving-does}

- 供應商設定會儲存為一個組態項目，且金鑰會使用安裝時的主金鑰以專屬用途的 AES-256-GCM 進行加密。
- 支援設定 **Primary model** 與 **Fallback model**（由 AI Chat 使用）會自動設為您的預設與第一個備用模型。
- 變更會寫入稽核記錄中（端點、模型、金鑰是否變更——絕不包含金鑰本身）。

## 驗證 {#verify}

1. **Test connection** 顯示綠色。
2. 以測試客戶身分登入客戶端：選單現在會提供 **AI Chat**（或聊天氣泡）與 **AI Agent**。
3. 向 AI Chat 詢問「我的餘額是多少？」。傳回真實餘額的回應表示供應商能正確處理工具呼叫。

## 限制與注意事項 {#limits-notes}

- **單一供應商。** NexCMP 針對 Chat、Agent 與工單調查使用單一已設定的供應商。備用模型可在該供應商內提供備援能力。
- **金鑰安全。** 儲存的金鑰僅會傳送至儲存的端點。如果您變更了基礎 URL，必須在測試前重新輸入金鑰。
- **每個客戶的限制。** AI Chat 僅限已登入的客戶使用，並設有每分鐘及每對話的訊息限制。Agent 每個帳號設有每日呼叫限制。參見 [AI Chat](https://nexcmp.com/zh-tw/docs/ai/ai-chat/) 與 [AI Agent](https://nexcmp.com/zh-tw/docs/ai/ai-agent/)。
- **隱私權。** 客戶的問題以及 AI 為該客戶讀取的資料（唯讀）將傳送給你的提供者。請在你的 [privacy policy](https://nexcmp.com/zh-tw/docs/customers/legal/) 中說明。
- **成本控制。** NexCMP 不計算 AI 成本；請使用提供者的預算功能。
- 該模組可隨時關閉：AI 選單項目將會消失，且 AI 路由會回傳 404 錯誤 `module_disabled`。AI Chat 的部分背景作業（工單調查、延遲回覆）會在面板下次重新啟動時套用變更。

## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| `base_url must be an http(s) URL` | 缺少通訊協定或包含空格 | 使用 `https://host/v1`。 |
| `api_key is required to enable the provider` | 未儲存金鑰 | 輸入金鑰並儲存。 |
| `base_url and model are required to enable the provider` | 欄位空白 | 兩者皆須填寫。 |
| 「Base URL已遭封鎖：僅限公開http(s)，連接埠80/443/8080/8443」 | 正在測試未儲存的內部地址或其他連接埠 | 請先儲存提供者，然後再進行測試。 |
| `api_key is required (enter the key again when you change the endpoint)` | Base URL 與已儲存的不同 | 重新輸入金鑰。 |
| `model: letters, digits and - _ . / : @` | 無效的字元 | 使用提供者的精確 model id。 |
| `fallback_models: up to 4 model names` | 數量過多 | 保留四個或更少。 |
| 測試失敗並回傳 401 | 金鑰錯誤 | 檢查金鑰與端點。 |
| 測試失敗並回傳 404 或 "model not found" | 路徑或模型錯誤 | 檢查 base URL（`/v1`）與 model id。 |
| `Too many tests — wait a minute` (429) | 每分鐘測試超過 10 次 | 請稍候。 |
| 入口網站仍未顯示 AI 選單 | 模組已關閉，或提供者未設定為「使用中」 | 開啟模組並啟用提供者。 |