> ## 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 整合相同之 Responses 或 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 相容的 chat 路徑

  **支援信心**: 在範圍限制內支援
</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 特有的 Responses 或 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>