> ## 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

> Tích hợp TokenLab với Dify sử dụng nhà cung cấp OpenAI và một base URL tùy chỉnh

## Tổng quan

Dify hoạt động hiệu quả với TokenLab thông qua luồng nhà cung cấp mô hình tương thích với OpenAI.

Đây là lộ trình tích hợp hướng tới chat-completions. Tài liệu này không đảm bảo rằng Dify sẽ hiển thị các phản hồi (Responses) hoặc hành vi WebSocket giống như các tích hợp Codex chuyên dụng.

Đối với các phiên bản Dify hiện tại, lộ trình an toàn nhất thường là:

* chọn nhà cung cấp **OpenAI** tích hợp sẵn
* thiết lập API key TokenLab của bạn
* thiết lập base URL tùy chỉnh là `https://api.tokenlab.sh/v1`

<Note>
  Một số bản dựng Dify cũ hơn hiển thị tùy chọn này dưới dạng `OpenAI-API-compatible` thay vì nhà cung cấp `OpenAI` tích hợp sẵn với trường base URL tùy chỉnh. Nếu giao diện Dify của bạn trông khác, hãy sử dụng luồng nhà cung cấp tùy chỉnh tương thích với OpenAI gần nhất có sẵn trong phiên bản đó.
</Note>

<Note>
  **Loại**: Framework hoặc Nền tảng

  **Lộ trình chính**: Lộ trình chat tương thích với OpenAI

  **Độ tin cậy hỗ trợ**: Được hỗ trợ với các giới hạn phạm vi
</Note>

## Điều kiện tiên quyết

* Tài khoản TokenLab có quyền truy cập API
* Dify Cloud hoặc Dify tự lưu trữ (self-hosted)

## Các bước cấu hình

### Bước 1: Lấy API Key của bạn

1. Đăng nhập vào [TokenLab Dashboard](https://tokenlab.sh/dashboard)
2. Mở [API Keys](https://tokenlab.sh/dashboard/api)
3. Tạo hoặc sao chép một API key bắt đầu bằng `sk-`

### Bước 2: Cấu hình nhà cung cấp

<Steps>
  <Step title="Mở Model Providers">
    Trong Dify, đi tới **Settings** → **Model Providers**
  </Step>

  <Step title="Chọn OpenAI">
    Mở cài đặt nhà cung cấp **OpenAI**. Nếu phiên bản Dify của bạn không cung cấp base URL tùy chỉnh tại đây, hãy sử dụng tùy chọn nhà cung cấp tùy chỉnh tương thích với OpenAI được hiển thị trong phiên bản đó.
  </Step>

  <Step title="Nhập cài đặt TokenLab">
    Sử dụng các giá trị sau:

    | Trường                         | Giá trị                      |
    | ------------------------------ | ---------------------------- |
    | API Key                        | `sk-your-tokenlab-key`       |
    | API Base URL / Custom Base URL | `https://api.tokenlab.sh/v1` |
  </Step>

  <Step title="Thêm các mô hình">
    Thêm các mô hình bạn muốn sử dụng, ví dụ:

    * `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>

### Bước 3: Kiểm tra kết nối

1. Chọn một mô hình như `gpt-5-mini` hoặc `gpt-4o`
2. Gửi một prompt kiểm tra
3. Xác nhận Dify nhận được phản hồi hợp lệ

## Embeddings cho Cơ sở tri thức (Knowledge Bases)

Đối với RAG và lập chỉ mục cơ sở tri thức, hãy thêm một mô hình embedding như:

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

Sau đó, đặt nó làm mô hình embedding mặc định trong cơ sở tri thức hoặc cài đặt ứng dụng có liên quan.

## Các vai trò mô hình được đề xuất

| Trường hợp sử dụng  | Các mô hình gợi ý                                          |
| ------------------- | ---------------------------------------------------------- |
| Chat mặc định       | `gpt-5.4-mini`, `gpt-5.4`, `claude-sonnet-5`               |
| Suy luận chuyên sâu | `gpt-5.5`, `gpt-5.4`, `claude-opus-4-8`, `deepseek-v4-pro` |
| Nhanh/Rẻ            | `gpt-5.4-mini`, `gemini-3.5-flash`, `deepseek-v4-flash`    |
| Embeddings          | `text-embedding-3-small`, `text-embedding-3-large`         |

## Các phương pháp tốt nhất

<AccordionGroup>
  <Accordion title="Bắt đầu với nhà cung cấp OpenAI tích hợp sẵn">
    Trong các phiên bản Dify mới hơn, nhà cung cấp OpenAI tích hợp sẵn với base URL tùy chỉnh thường là thiết lập sạch nhất cho TokenLab.
  </Accordion>

  <Accordion title="Sử dụng các mô hình rẻ hơn để lặp lại">
    Sử dụng `gpt-5.4-mini`, `gemini-3.5-flash`, hoặc `deepseek-v4-flash` trong khi lặp lại, sau đó chỉ chuyển các luồng công việc nặng hơn sang các mô hình mạnh hơn khi cần thiết.
  </Accordion>

  <Accordion title="Lưu ý rằng Dify thường hướng tới chat-completions">
    Hầu hết các luồng Dify sử dụng hành vi chat tương thích với OpenAI. Nếu bạn cần các phản hồi (Responses) hoặc hành vi WebSocket đặc thù của Codex, hãy sử dụng các tích hợp Codex chuyên dụng thay vì Dify.
  </Accordion>
</AccordionGroup>

## Khắc phục sự cố

<AccordionGroup>
  <Accordion title="Lỗi kết nối">
    * Xác minh base URL chính xác là `https://api.tokenlab.sh/v1`
    * Xóa dấu gạch chéo ở cuối nếu Dify tự động thêm vào
    * Xác nhận máy chủ Dify có thể truy cập TokenLab qua internet công cộng
  </Accordion>

  <Accordion title="401 Unauthorized">
    * Kiểm tra kỹ API key
    * Xác nhận key đang hoạt động trong bảng điều khiển TokenLab
    * Đảm bảo giá trị dán vào Dify không chứa khoảng trắng hoặc ngắt dòng thừa
  </Accordion>

  <Accordion title="Không tìm thấy mô hình">
    * Xác minh chính xác tên mô hình
    * Thêm lại mục mô hình nếu giao diện nhà cung cấp đã lưu bộ nhớ đệm giá trị cũ
    * Kiểm tra tính khả dụng của mô hình hiện tại trong tài liệu hoặc bảng điều khiển TokenLab
  </Accordion>
</AccordionGroup>