> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crazyrouter.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Dify 配置教程

> 在 Dify 中通过 Crazyrouter 接入聊天、Embedding 与工作流模型，并完成模型供应商配置、验证与排障

> 更新日期：2026-06-06

Dify 适合做工作流、Agent、知识库和内部 AI 应用平台。对接 Crazyrouter 时，推荐先走 Dify 的 OpenAI 兼容模型供应商路径，把聊天模型先跑通，再逐步补充 Embedding 或其他能力。

## 概览

通过 Dify 的模型供应商配置，你可以把 Crazyrouter 作为 OpenAI 兼容上游接入：

* 推荐协议：`OpenAI-compatible API`
* 推荐入口：`设置 / Settings` → `模型供应商 / Model Provider`
* Base URL：`https://api.crazyrouter.com/v1`
* 认证方式：`sk-...` token
* 推荐首次验证模型：`gpt-5.5`

<Tip>
  不同 Dify 版本或插件化发行版里，供应商名称可能显示为 `OpenAI`、`OpenAI-API-compatible`、`OpenAI Compatible` 或类似名称。优先选择支持自定义 `API Base URL` 的 OpenAI 兼容入口即可。
</Tip>

<Note>
  Dify 官方文档把自定义 `API Base URL` 视为代理或兼容上游场景下的可选项；对接 Crazyrouter 时，就应把 Crazyrouter 当作这个 OpenAI 兼容上游来填写 `https://api.crazyrouter.com/v1`。另外，模型供应商通常需要工作区管理员或 Owner 权限才能配置；如果你看不到入口，先检查当前账号角色。
</Note>

## 适合谁用

* 想搭建工作流、Agent、知识库应用的人
* 想把聊天模型、Embedding 模型统一接到 Crazyrouter 的团队
* 想给业务部门提供可视化 AI 编排平台的人
* 想把测试与生产模型分环境管理的人

## 使用协议

推荐协议：`OpenAI-compatible API`

在 Dify 中对接 Crazyrouter 时，通常填写的 OpenAI 兼容基址为：

```text theme={null}
https://api.crazyrouter.com/v1
```

不要填成：

* `https://api.crazyrouter.com`
* `https://api.crazyrouter.com/v1/chat/completions`

<Tip>
  不同 Dify 版本里，界面文案可能会在 `Model Provider`、`模型供应商`、`Providers` 或插件市场入口之间切换，但首轮验证路径不要变：先保存供应商，再只添加一个 `LLM` 模型 `gpt-5.5`，最后再创建最小 Chat 应用验证。
</Tip>

## 前置条件

| 项目                | 说明                                               |
| ----------------- | ------------------------------------------------ |
| Crazyrouter 账号    | 先在 [crazyrouter.com](https://crazyrouter.com) 注册 |
| Crazyrouter token | 建议为 Dify 单独创建一个 `sk-...` token                   |
| Dify              | 建议使用当前稳定版；不同版本的入口名称可能略有差异                        |
| 可用模型              | 至少放行一个当天已实测成功的聊天模型，如 `gpt-5.5`                   |

推荐首批白名单：

* `gpt-5.5`
* `claude-opus-4-8`
* `text-embedding-3-large`
* `text-embedding-3-small`

如果你要做知识库，建议至少同时准备一个聊天模型和一个 Embedding 模型。

## 5 分钟快速开始

<Steps>
  <Step title="创建 Dify 专用 token">
    在 Crazyrouter 后台创建一个新 token，名称建议写成 `dify`。首次先只开放 `gpt-5.5` 和一个 Embedding 模型，例如 `text-embedding-3-large`。
  </Step>

  <Step title="进入模型供应商设置">
    使用有工作区管理权限的账号登录 Dify，进入 `设置 / Settings` → `模型供应商 / Model Provider`。
  </Step>

  <Step title="添加 OpenAI 兼容供应商">
    选择 `OpenAI` 或 `OpenAI-compatible` 类型的供应商入口，填写：

    * `API Key`: 你的 `sk-...`
    * `API Base URL`: `https://api.crazyrouter.com/v1`
  </Step>

  <Step title="先只配置一个聊天模型">
    首次先添加一个 LLM，例如：

    * `模型名称 / Model`: `gpt-5.5`
    * `模型类型 / Type`: `LLM`

    保存后创建一个最简单的 Chat 应用或 Workflow 应用做验证。不要一开始就同时加聊天、Embedding、Rerank 和工作流工具，不然排障会混在一起。
  </Step>

  <Step title="完成首次验证">
    在应用里发送一句：`Reply only OK`。如果成功返回，并且 Crazyrouter 后台有日志，说明聊天路径已跑通。然后再继续加 Embedding 或其他模型。
  </Step>
</Steps>

## Embedding 与知识库建议

如果你要在 Dify 中使用知识库、RAG 或文档检索，建议第二步再补上 Embedding 模型：

| 用途            | 推荐模型                     | 说明           |
| ------------- | ------------------------ | ------------ |
| 默认 Embedding  | `text-embedding-3-large` | 质量更稳，适合知识库起步 |
| 低成本 Embedding | `text-embedding-3-small` | 更省钱，适合较大规模文档 |

建议顺序：

1. 先验证聊天模型
2. 再验证 Embedding
3. 最后再做知识库导入与召回调优

这样排障最清晰。

## 推荐模型配置

| 使用场景          | 推荐模型                     | 原因                      |
| ------------- | ------------------------ | ----------------------- |
| 默认工作流聊天模型     | `gpt-5.5`                | 当天已实测成功，适合作为 Dify 聊天主基线 |
| 高质量复杂场景       | `claude-opus-4-8`        | 更适合复杂解释、总结与长文本          |
| Gemini 备用档    | `gemini-3.1-pro`         | 适合做第二条上游兼容性验证路径         |
| 默认 Embedding  | `text-embedding-3-large` | 知识库质量更稳                 |
| 低成本 Embedding | `text-embedding-3-small` | 适合预算敏感的索引场景             |

推荐顺序：聊天模型先跑通，再补 Embedding 模型。

## Token 设置最佳实践

| 设置                | 建议         | 说明                          |
| ----------------- | ---------- | --------------------------- |
| 专用 token          | 必须         | Dify 不要和聊天前端、CLI 工具共用 token |
| 模型白名单             | 强烈建议       | 只开放 Dify 工作流真正会调用的模型        |
| IP 限制             | 固定部署出口建议开启 | 本地开发环境频繁切换时谨慎使用             |
| 配额上限              | 强烈建议       | Dify 工作流、批处理、知识库导入都可能快速消耗额度 |
| 环境隔离              | 必须         | 开发、测试、生产建议分别使用不同 token      |
| 聊天 / Embedding 分离 | 建议         | 高流量场景可拆成不同 token 便于计费与限流    |

## 验证清单

* [ ] 已在 `模型供应商 / Model Provider` 中保存 Crazyrouter 配置
* [ ] `API Base URL` 已设置为 `https://api.crazyrouter.com/v1`
* [ ] 至少一个 LLM 已成功添加
* [ ] 第一个 Dify 应用请求成功返回
* [ ] Crazyrouter 后台日志能看到对应请求
* [ ] 如需知识库，至少一个 Embedding 模型已成功配置
* [ ] token 配额与模型白名单符合预期
* [ ] 开发 / 测试 / 生产已做 token 隔离

## 常见错误与修复

| 现象                              | 常见原因                                  | 修复方式                                                                      |
| ------------------------------- | ------------------------------------- | ------------------------------------------------------------------------- |
| 看不到 `模型供应商 / Model Provider` 入口 | 当前账号不是工作区管理员或 Owner                   | 换用有权限的账号，或请管理员代为配置                                                        |
| 看到了供应商入口，但没有 OpenAI 兼容选项        | 当前版本把它做成插件、不同命名，或需要先启用对应供应商           | 先找 `OpenAI`、`OpenAI Compatible`、`OpenAI-API-compatible` 这类入口，必要时检查插件或版本说明 |
| 供应商无法保存                         | API Key 错误，或没有填写支持自定义 Base URL 的供应商类型 | 改用 OpenAI 兼容供应商入口，并重新填写 `sk-...`                                          |
| 401 unauthorized                | token 失效、复制错误或已被删除                    | 重新生成 token 并替换                                                            |
| 403 / model not allowed         | Dify 中选用的模型不在 token 白名单里              | 在 Crazyrouter 后台放行对应模型                                                    |
| 404                             | `API Base URL` 写成根域名或完整接口路径           | 改成 `https://api.crazyrouter.com/v1`                                       |
| 聊天模型可配但应用报错                     | 模型名称填错，或上下文参数配置不合理                    | 先回退到 `gpt-5.5` 做基线验证                                                      |
| 知识库导入失败                         | 聊天模型已通，但 Embedding 模型没配置好             | 先单独验证 Embedding 配置，再重新导入知识库                                               |
| 工作流成本增长很快                       | 批量运行、长上下文或多个应用共用同一 token              | 拆分 token、设置配额上限并缩小模型范围                                                    |
| 某些高级模型能力在 Dify 里表现不一致           | 不同模型在 Dify 节点中的参数兼容性不同                | 先用 `gpt-5.5` 跑通基线，再逐步替换为其他模型                                              |

## 性能与成本建议

* 工作流默认先用 `gpt-5.5` 做测试，稳定后再补充其他模型
* 知识库首次上线时，先少量导入文档验证召回质量，再批量导入
* 把聊天模型与 Embedding 模型分开记账，便于判断成本来源
* 对批量任务、定时任务和内部测试环境设置更严格的配额上限
* 遇到高消耗时，先回看 Crazyrouter 日志确认是工作流重试、知识库导入，还是多应用共用 token 所致

## FAQ

### Dify 应该填哪个 Base URL？

填 `https://api.crazyrouter.com/v1`。

### 为什么这里不推荐填根域名？

因为 Dify 的 OpenAI 兼容供应商通常要求填写 OpenAI 兼容基址，而不是根域名。

### 我应该先配聊天模型还是 Embedding？

先配聊天模型，确认应用能返回结果后，再配 Embedding。

### Rerank 模型可以直接配置吗？

取决于你的 Dify 版本和当前可用供应商插件。建议先把聊天和 Embedding 跑通，再评估是否需要单独接入 Rerank。

### 为什么这里强调先只配一个聊天模型？

因为 Dify 的问题很容易同时出现在供应商、模型类型、应用参数和知识库链路里。先只跑通一个 `gpt-5.5` 聊天应用，定位会清楚很多。

### Dify 要不要拆分多个 token？

建议拆。至少把开发 / 生产分开；高流量场景再把聊天与 Embedding 分开。

<Note>
  Dify 最适合放在“应用平台”和“工作流平台”的位置。和聊天前端相比，它更强调流程编排、知识库和多环境管理，因此更需要专用 token、模型白名单和配额策略。
</Note>