耿雨飞的个人博客

[[ slide_text ]]

[[ item.c ]]

Dify 系列教程 | 第 3 篇：配置你的第一个 AI 模型供应商

发布时间：2026-04-08 作者：gengyufei 来源：gengyufei个人博客

dify 教程

> **Dify 系列教程** | 模块一：认识 Dify -- 从零开始 | 第 3 篇 / 共 30 篇
>
> **适合读者**：所有技术水平
>
> **学习目标**：理解 Dify 的模型供应商体系；学会配置主流 LLM 供应商；了解模型负载均衡和配额管理

---

## 开篇：Dify 部署完了，为什么还不能用？

如果你跟着上一篇完成了 Dify 的本地部署，登录控制台后你可能会发现 -- 创建应用时，模型选择框是空的。

这是因为 Dify 本身**不内置任何 AI 模型**，它是一个模型无关的平台。你需要告诉 Dify 去哪里调用 AI 模型、用什么凭证。这个"告诉"的过程，就是配置模型供应商。

本篇将带你完成这个关键步骤，配置完成后，Dify 才真正具备"智能"。

---

## 一、理解 Dify 的模型供应商体系

### 1.1 什么是模型供应商？

在 Dify 的架构中，"模型供应商"（Model Provider）是连接 Dify 平台与 AI 模型服务之间的桥梁。每个供应商代表一个模型服务提供方，可以提供一种或多种类型的模型。

Dify 的模型管理由后端 `ProviderManager` 统一编排，核心流程如下：

```
用户在设置页面填写 API Key
        │
        ▼
ModelProviderService 接收凭证
        │
        ▼
ProviderManager 验证凭证有效性
        │
        ▼
加密存储到 ProviderCredential 表
        │
        ▼
前端 ModelProvider 组件显示供应商已激活
        │
        ▼
创建应用时可选择该供应商的模型
```

### 1.2 两种配置模式

Dify 的模型供应商支持两种配置模式（对应后端 `ConfigurateMethod` 枚举）：

| 模式           | 代码标识             | 说明                                               | 典型供应商                  |
| -------------- | -------------------- | -------------------------------------------------- | --------------------------- |
| **预定义模型** | `predefined-model`   | 供应商预先定义好可用模型列表，用户只需填写 API Key | OpenAI、Anthropic、Google   |
| **自定义模型** | `customizable-model` | 用户需要手动指定模型名称和配置参数                 | Ollama、Xinference、LocalAI |

在前端代码中，这两种模式通过 `ConfigurationMethodEnum` 枚举定义：

```typescript
// 源码位置: web/app/components/header/account-setting/
//           model-provider-page/declarations.ts
export enum ConfigurationMethodEnum {
  predefinedModel = 'predefined-model',
  customizableModel = 'customizable-model',
  fetchFromRemote = 'fetch-from-remote',
}
```

**预定义模型**供应商（如 OpenAI）：配置一次 API Key，即可使用该供应商下的所有模型（GPT-4o、GPT-4、GPT-3.5-turbo 等）。

**自定义模型**供应商（如 Ollama）：需要逐个添加模型，指定模型名称和连接参数。

### 1.3 六种模型类型

Dify 将 AI 模型按功能分为六种类型，对应后端 `ModelType` 枚举和前端 `ModelTypeEnum`：

| 模型类型           | 后端标识                   | 前端标识         | 用途                     | 典型模型                    |
| ------------------ | -------------------------- | ---------------- | ------------------------ | --------------------------- |
| **LLM**            | `ModelType.LLM`            | `llm`            | 文本生成、对话推理       | GPT-4o、Claude 3.5、Qwen    |
| **Text Embedding** | `ModelType.TEXT_EMBEDDING` | `text-embedding` | 文本向量化（知识库必需） | text-embedding-3-small      |
| **Rerank**         | `ModelType.RERANK`         | `rerank`         | 检索结果重排序           | Cohere Rerank、bge-reranker |
| **Speech2Text**    | `ModelType.SPEECH2TEXT`    | `speech2text`    | 语音转文字               | Whisper                     |
| **TTS**            | `ModelType.TTS`            | `tts`            | 文字转语音               | OpenAI TTS、Azure TTS       |
| **Moderation**     | `ModelType.MODERATION`     | `moderation`     | 内容安全审核             | OpenAI Moderation           |

**重要提示**：如果你打算使用知识库功能（RAG），**至少需要配置一个 LLM 和一个 Text Embedding 模型**。Rerank 模型是可选的，但能显著提升检索质量。

### 1.4 模型状态

每个模型在 Dify 中有明确的状态标识，对应前端 `ModelStatusEnum`：

| 状态                 | 含义                   |
| -------------------- | ---------------------- |
| `active`             | 可用，已配置且正常工作 |
| `no-configure`       | 未配置凭证             |
| `quota-exceeded`     | 配额耗尽               |
| `no-permission`      | 无权限使用             |
| `disabled`           | 已被管理员禁用         |
| `credential-removed` | 凭证已删除             |

---

## 二、配置 OpenAI -- 完整步骤演示

OpenAI 是最常用的模型供应商之一，我们以它为例，演示完整的配置流程。

### 2.1 获取 API Key

1. 访问 OpenAI 平台，登录你的账号
2. 进入 API Keys 管理页面
3. 点击「Create new secret key」
4. 为密钥命名（如 "dify-production"），点击创建
5. **立即复制保存密钥**（关闭后无法再次查看）

### 2.2 在 Dify 中配置

1. 登录 Dify 控制台
2. 点击左上角头像 -> **设置**
3. 在左侧菜单中选择 **模型供应商**
4. 在供应商列表中找到 **OpenAI**，点击进入
5. 点击 **添加 API Key** 按钮
6. 在弹出的表单中填写：
   - **凭证名称**：给这个凭证起个名字（如"我的 OpenAI 密钥"）
   - **API Key**：粘贴你的 OpenAI API Key

7. 点击 **保存**

### 2.3 配置背后发生了什么？

当你点击保存时，Dify 内部执行了以下流程：

```
1. 前端发送 POST 请求到:
   /workspaces/current/model-providers/openai/credentials

2. 后端 ModelProviderService.create_provider_credential() 被调用

3. 通过 ProviderManager 调用 OpenAI 的凭证验证接口
   （实际会发一个简单的 API 请求来确认 Key 是否有效）

4. 验证通过后，API Key 使用 encrypt_token() 加密

5. 加密后的凭证存入 provider_credentials 表

6. 返回成功，前端刷新供应商状态
```

所有凭证在数据库中都是**加密存储**的，前端列表接口也不会返回解密后的密钥值，确保安全性。

### 2.4 验证配置

配置完成后，你应该能看到：

- OpenAI 供应商卡片显示绿色状态指示器
- 展开后可以看到所有可用模型列表：GPT-4o、GPT-4、GPT-3.5-turbo、text-embedding-3-small 等
- 每个模型旁边有开关按钮，可以控制是否启用

**快速验证方法**：

1. 回到控制台首页，点击「创建应用」
2. 选择「聊天助手」
3. 在模型选择下拉框中，应该能看到 OpenAI 的模型列表
4. 选择一个模型（如 GPT-4o），在调试面板中发送一条消息
5. 如果收到正常回复，说明配置成功

---

## 三、配置国产模型供应商

对于国内用户，国产模型往往有更好的中文能力、更低的延迟和更便宜的价格。配置流程与 OpenAI 类似，关键区别在于获取 API Key 的平台和部分额外参数。

### 3.1 通义千问（Qwen）

**获取凭证**：登录阿里云 DashScope 控制台，在 API-KEY 管理中创建密钥。

**在 Dify 中配置**：

1. 模型供应商页面找到「通义千问」
2. 点击添加凭证，填写 DashScope API Key
3. 保存后可使用 qwen-max、qwen-plus、qwen-turbo 等模型
4. 通义千问同时提供 LLM 和 Text Embedding 模型

### 3.2 智谱 GLM（ChatGLM）

**获取凭证**：登录智谱 AI 开放平台，在个人中心 -> API Keys 中创建密钥。

**在 Dify 中配置**：

1. 模型供应商页面找到「ZHIPU AI」
2. 填写 API Key
3. 可使用 GLM-4、GLM-4-Flash 等模型

### 3.3 DeepSeek

**获取凭证**：登录 DeepSeek 开放平台，在 API Keys 页面创建密钥。

**在 Dify 中配置**：

1. 找到「DeepSeek」供应商
2. 填写 API Key
3. 可使用 deepseek-chat、deepseek-reasoner 等模型

### 3.4 文心一言（ERNIE）

**获取凭证**：登录百度智能云千帆大模型平台，获取 API Key 和 Secret Key。

**在 Dify 中配置**：

1. 找到「百度千帆」供应商
2. 需要填写 API Key 和 Secret Key 两个字段
3. 可使用 ERNIE-4.0、ERNIE-3.5 等模型

### 3.5 Moonshot（月之暗面 Kimi）

**获取凭证**：登录 Moonshot AI 开放平台，在 API Key 管理页面创建密钥。

**在 Dify 中配置**：

1. 找到「Moonshot AI」供应商
2. 填写 API Key
3. 可使用 moonshot-v1-8k、moonshot-v1-32k、moonshot-v1-128k 等模型

> **配置建议**：建议至少配置 2 个以上的模型供应商，既可以在不同场景下选择最合适的模型，也能在某个供应商出现故障时快速切换。

---

## 四、本地模型接入：Ollama + 开源模型

如果你不想依赖第三方 API，或者有数据隐私方面的顾虑，可以在本地部署开源模型，然后通过 Ollama 接入 Dify。

### 4.1 什么是 Ollama？

Ollama 是一个本地运行大语言模型的工具，支持 Llama 3、Qwen 2.5、Gemma、Mistral 等热门开源模型。它提供了兼容 OpenAI 的 API 接口，可以被 Dify 直接调用。

### 4.2 安装 Ollama

```bash
# Linux 一键安装
curl -fsSL https://ollama.ai/install.sh | sh

# 验证安装
ollama --version
```

### 4.3 下载并运行模型

```bash
# 下载并运行 Qwen 2.5（7B 参数量，推荐中文场景）
ollama run qwen2.5:7b

# 或者下载 Llama 3.1（8B 参数量）
ollama run llama3.1:8b

# 查看已安装的模型
ollama list
```

### 4.4 在 Dify 中配置 Ollama

Ollama 属于**自定义模型**类型的供应商（`ConfigurationMethodEnum.customizableModel`），配置方式与预定义模型供应商不同 -- 你需要逐个添加模型。

**配置步骤**：

1. 在模型供应商页面找到 **Ollama**
2. 点击 **添加模型**
3. 填写模型信息：
   - **模型名称**：`qwen2.5:7b`（必须与 `ollama list` 中的名称完全一致）
   - **模型类型**：选择 LLM
   - **服务器地址**：`http://host.docker.internal:11434`（Docker 环境中访问宿主机的 Ollama 服务）

4. 点击保存

> **关键注意**：如果 Dify 运行在 Docker 中，而 Ollama 运行在宿主机上，服务器地址不能填 `localhost`，应该填 `http://host.docker.internal:11434`（Docker Desktop）或宿主机的实际 IP 地址。

### 4.5 添加 Embedding 模型（可选）

Ollama 也可以提供 Embedding 模型，用于知识库功能：

```bash
# 下载 Embedding 模型
ollama pull nomic-embed-text
```

在 Dify 中添加时，模型类型选择 **Text Embedding**，模型名称填 `nomic-embed-text`。

---

## 五、模型负载均衡

当你的 AI 应用流量较大时，单个 API Key 可能会遇到速率限制。Dify 提供了模型级别的负载均衡功能，允许你为同一个模型配置多个凭证，自动轮转分担压力。

### 5.1 负载均衡的工作原理

```
用户请求
    │
    ▼
Dify 选择模型
    │
    ▼
LBModelManager 检查负载均衡配置
    │
    ├─ Key A (正常) ──→ 发送请求 ✓
    │
    ├─ Key B (冷却中, TTL=45s) ──→ 跳过
    │
    └─ Key C (正常) ──→ 下次轮转使用
```

核心逻辑：

- **轮转策略**：Round-Robin 依次使用各凭证
- **冷却机制**：当某个 Key 触发限流时，自动进入 60 秒冷却期
- **状态追踪**：通过 Redis 记录冷却状态（键格式：`model_lb_index:cooldown:{tenant_id}:{provider}:{model_type}:{model}:{config_id}`）

### 5.2 配置负载均衡

1. 在模型供应商页面，找到已配置的供应商
2. 展开模型列表，找到目标模型
3. 点击模型旁边的 **配置** 按钮
4. 在弹出的模态框中启用 **负载均衡** 开关
5. 添加多个 API Key 凭证（至少 2 个）
6. 每个凭证可以独立启用/禁用
7. 保存配置

配置完成后，模型旁边会显示负载均衡图标，表示该模型已启用多凭证轮转。

### 5.3 负载均衡最佳实践

- **数量建议**：同一模型建议配置 3-5 个 API Key，既能分散限流风险，又便于管理
- **监控冷却**：如果频繁看到凭证进入冷却状态，说明整体流量已经接近限额，需要增加 Key 或优化调用频率
- **混合使用**：可以混合使用不同账号甚至不同组织的 API Key
- **命名规范**：为每个凭证起有意义的名称（如"团队账号-A"、"团队账号-B"），方便排查问题

---

## 六、设置默认模型

配置好供应商后，建议为每种模型类型设置默认值，这样创建新应用时会自动选用。

**设置路径**：设置 -> 模型供应商 -> 页面顶部的「系统模型设置」

建议配置：

| 模型类型        | 推荐默认值                                         |
| --------------- | -------------------------------------------------- |
| 推理模型（LLM） | 根据你的主力模型选择（如 GPT-4o 或 qwen-max）      |
| Embedding 模型  | text-embedding-3-small（OpenAI）或供应商对应的模型 |
| Rerank 模型     | 如已配置 Cohere 或 bge-reranker，可在此选择        |
| 语音转文字      | Whisper（如有需要）                                |
| 文字转语音      | OpenAI TTS 或其他 TTS 模型                         |

---

## 七、实践环节

### 任务 1：配置你的主力模型供应商

根据你的实际情况，选择以下方案之一完成配置：

**方案 A -- 使用 OpenAI**：

1. 获取 OpenAI API Key
2. 在 Dify 中添加 OpenAI 凭证
3. 验证 GPT-4o 和 text-embedding-3-small 可用

**方案 B -- 使用国产模型**：

1. 获取通义千问或 DeepSeek 的 API Key
2. 在 Dify 中添加对应供应商凭证
3. 验证 LLM 和 Embedding 模型可用

**方案 C -- 使用本地模型（Ollama）**：

1. 安装 Ollama 并下载 qwen2.5:7b 模型
2. 在 Dify 中配置 Ollama 自定义模型
3. 验证模型可用

### 任务 2：配置验证清单

完成配置后，逐项确认：

- [ ] 模型供应商页面显示至少一个供应商为已配置状态（绿色指示器）
- [ ] 创建聊天助手时，模型下拉框中能看到可用模型
- [ ] 在调试面板中发送消息能收到正常回复
- [ ] （如需要知识库）确认有至少一个 Text Embedding 模型可用
- [ ] 设置了系统默认模型

### 任务 3（进阶）：配置负载均衡

如果你有多个 API Key：

1. 为同一个模型（如 GPT-4o）添加 2 个以上凭证
2. 启用负载均衡
3. 连续发送多条消息，观察是否正常轮转

---

## 小结

本篇我们完成了 Dify 最关键的配置环节 -- 模型供应商：

- **供应商体系**：Dify 通过插件化架构支持 100+ 模型供应商，分为预定义模型和自定义模型两种配置模式
- **六种模型类型**：LLM、Text Embedding、Rerank、Speech2Text、TTS、Moderation，各有不同用途
- **配置流程**：获取 API Key -> 在设置页面添加凭证 -> Dify 自动验证并加密存储
- **本地模型**：通过 Ollama 可以零成本使用开源模型，完全本地化运行
- **负载均衡**：多 API Key 轮转 + 自动冷却，应对高流量场景

**下一篇预告**：模型已经配好了，接下来我们要正式上手了！下一篇《5 分钟创建你的第一个 AI 聊天助手》将带你创建一个真正可用的 AI 应用，深入理解 Prompt 编排和模型参数调优。

---

**你选择了哪个模型供应商？配置过程中遇到了什么问题？国产模型和 OpenAI 在你的场景下表现如何？欢迎在评论区分享你的体验！**

---

> 本文基于 Dify v1.13.3 源码编写，代码引用来自 `api/services/model_provider_service.py`、`api/core/entities/provider_configuration.py`、`web/app/components/header/account-setting/model-provider-page/declarations.ts` 等文件。如有更新请以官方文档为准。

上一篇：Dify 系列教程 | 第 2 篇：10 分钟搞定！Dify 本地部署完全指南下一篇：Dify 系列教程 | 第 4 篇：5 分钟创建你的第一个 AI 聊天助手

你觉得文章怎么样