---
title: AI 提供商
description: 为 AI Chat 和 AI Agent 连接兼容 OpenAI 的 AI 端点——开启 AI 模块，输入端点和密钥，进行测试并设置限制。
url: https://nexcmp.com/zh-cn/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（用自然语言管理虚拟机）不自带内置模型。您需选择**自己的提供商**：任何提供 **OpenAI 兼容** `chat/completions` API 的服务——例如 OpenAI、OpenRouter、LiteLLM 网关或您自己的 vLLM 服务器。NexCMP 会加密存储端点和 API 密钥，并将其用于所有 AI 功能。费用由您直接支付给提供商。

## 前提条件 {#requirements}

| 项目 | 要求 |
|---|---|
| 端点 | 兼容OpenAI的基准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-cn/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** 卡片中填写：

   | 字段 | 示例 | 备注 |
   |---|---|---|
   | 使用此提供商 | 开启 | 启用时需要基本 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-cn/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 为聊天、Agent 和工单排查使用单一配置的提供商。回退模型在该提供商内部提供弹性保障。
- **密钥安全。** 保存的密钥仅发送至保存的端点。如果您更改了基本 URL，必须在测试前重新输入密钥。
- **每个客户的限制。**AI Chat仅限已登录客户使用，并设有每分钟和每对话的消息限制。Agent对每个账号设有每日调用次数限制。请参阅[AI Chat](https://nexcmp.com/zh-cn/docs/ai/ai-chat/)和[AI Agent](https://nexcmp.com/zh-cn/docs/ai/ai-agent/)。
- **隐私。**客户的问题以及AI为该客户读取的数据（只读）会被发送至您的服务提供商。请在您的[隐私政策](https://nexcmp.com/zh-cn/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 - _ . / : @` | 字符无效 | 使用服务提供商确切的模型ID。 |
| `fallback_models: up to 4 model names` | 数量过多 | 保留四个或更少。 |
| 测试失败并返回401 | 密钥错误 | 检查密钥和端点。 |
| 测试失败并返回404或“model not found” | 路径或模型错误 | 检查基础URL（`/v1`）和模型ID。 |
| `Too many tests — wait a minute` (429) | 每分钟测试超过10次 | 请稍候。 |
| 门户中仍未显示AI菜单 | 模块已关闭，或服务提供商未处于“使用中”状态 | 开启模块并启用服务提供商。 |