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

# Dify

> 使用 OpenAI 提供商和自定义 base URL 将 TokenLab 集成到 Dify

## 概述

Dify 可以通过其兼容 OpenAI 的模型提供商流程与 TokenLab 良好协作。

这是一个面向 chat-completions 的集成路径。请勿将其视为 Dify 会提供与专用 Codex 集成相同的响应或 WebSocket 行为的保证。

对于当前的 Dify 版本，最稳妥的路径通常是：

* 选择内置的 **OpenAI** 提供商
* 设置您的 TokenLab API key
* 设置自定义 base URL 为 `https://api.tokenlab.sh/v1`

<Note>
  一些较旧的 Dify 构建版本将其显示为 `OpenAI-API-compatible`，而不是带有自定义 base URL 字段的内置 `OpenAI` 提供商。如果您的 Dify UI 看起来不同，请使用该版本中可用的最接近的 OpenAI 兼容自定义提供商流程。
</Note>

<Note>
  **类型**: 框架或平台

  **主要路径**: OpenAI 兼容的聊天路径

  **支持置信度**: 在范围限制内支持
</Note>

## 前置要求

* 拥有 API 访问权限的 TokenLab 账户
* Dify Cloud 或自托管 Dify

## 配置步骤

### 第 1 步：获取您的 API Key

1. 登录 [TokenLab Dashboard](https://tokenlab.sh/dashboard)
2. 打开 [API Keys](https://tokenlab.sh/dashboard/api)
3. 创建或复制一个以 `sk-` 开头的 API key

### 第 2 步：配置提供商

<Steps>
  <Step title="打开模型提供商">
    在 Dify 中，前往 **设置 (Settings)** → **模型提供商 (Model Providers)**
  </Step>

  <Step title="选择 OpenAI">
    打开 **OpenAI** 提供商设置。如果您的 Dify 版本在此处不提供自定义 base URL，请改用该版本提供的 OpenAI 兼容自定义提供商选项。
  </Step>

  <Step title="输入 TokenLab 设置">
    使用以下值：

    | 字段                             | 值                            |
    | ------------------------------ | ---------------------------- |
    | API Key                        | `sk-your-tokenlab-key`       |
    | API Base URL / Custom Base URL | `https://api.tokenlab.sh/v1` |
  </Step>

  <Step title="添加模型">
    添加您想要使用的模型，例如：

    * `gpt-5.4`
    * `gpt-5.4-mini`
    * `claude-sonnet-5`
    * `claude-opus-4-8`
    * `gemini-3.5-flash`
    * `gemini-3.1-flash-lite`
    * `deepseek-v4-flash`
  </Step>
</Steps>

### 第 3 步：测试连接

1. 选择一个模型，例如 `gpt-5-mini` 或 `gpt-4o`
2. 发送一条测试提示词 (prompt)
3. 确认 Dify 收到了有效的响应

## 用于知识库的 Embeddings

对于 RAG 和知识库索引，请添加一个 embedding 模型，例如：

* `text-embedding-3-small`
* `text-embedding-3-large`

然后将其设置为相关知识库或应用程序设置中的默认 embedding 模型。

## 推荐模型角色

| 使用场景       | 建议模型                                                       |
| ---------- | ---------------------------------------------------------- |
| 默认聊天       | `gpt-5.4-mini`, `gpt-5.4`, `claude-sonnet-5`               |
| 深度推理       | `gpt-5.5`, `gpt-5.4`, `claude-opus-4-8`, `deepseek-v4-pro` |
| 快速/廉价      | `gpt-5.4-mini`, `gemini-3.5-flash`, `deepseek-v4-flash`    |
| Embeddings | `text-embedding-3-small`, `text-embedding-3-large`         |

## 最佳实践

<AccordionGroup>
  <Accordion title="从内置的 OpenAI 提供商开始">
    在较新的 Dify 版本中，带有自定义 base URL 的内置 OpenAI 提供商通常是 TokenLab 最简洁的设置方式。
  </Accordion>

  <Accordion title="在迭代时使用更便宜的模型">
    在迭代过程中使用 `gpt-5.4-mini`、`gemini-3.5-flash` 或 `deepseek-v4-flash`，仅在需要时将更繁重的工作流切换到更强大的模型。
  </Accordion>

  <Accordion title="请记住 Dify 通常是面向 chat-completions 的">
    大多数 Dify 流程使用 OpenAI 兼容的聊天行为。如果您需要 Codex 特定的响应或 WebSocket 行为，请使用专用的 Codex 集成，而不是 Dify。
  </Accordion>
</AccordionGroup>

## 故障排除

<AccordionGroup>
  <Accordion title="连接错误">
    * 验证 base URL 是否完全为 `https://api.tokenlab.sh/v1`
    * 如果 Dify 重复添加了斜杠，请删除末尾的斜杠
    * 确认 Dify 服务器可以通过公共互联网访问 TokenLab
  </Accordion>

  <Accordion title="401 Unauthorized">
    * 仔细检查 API key
    * 确认该 key 在 TokenLab dashboard 中处于激活状态
    * 确保粘贴到 Dify 中的值不包含多余的空格或换行符
  </Accordion>

  <Accordion title="模型未找到 (Model Not Found)">
    * 准确核对模型名称
    * 如果提供商 UI 缓存了旧值，请重新添加模型条目
    * 在 TokenLab 文档或 dashboard 中检查当前模型的可用性
  </Accordion>
</AccordionGroup>