> ## 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 공급자 및 사용자 지정 기본 URL을 사용하여 TokenLab과 Dify 통합하기

## 개요

Dify는 OpenAI 호환 모델 공급자 흐름을 통해 TokenLab과 원활하게 작동합니다.

이 통합 경로는 채팅 완성(chat-completions) 지향적입니다. Dify가 전용 Codex 통합과 동일한 응답(Responses) 또는 WebSocket 동작을 노출한다고 보장하지는 않습니다.

현재 Dify 버전에서 가장 안전한 방법은 다음과 같습니다:

* 내장된 **OpenAI** 공급자 선택
* TokenLab API 키 설정
* 사용자 지정 기본 URL을 `https://api.tokenlab.sh/v1`으로 설정

<Note>
  일부 구형 Dify 빌드에서는 사용자 지정 기본 URL 필드가 있는 내장 `OpenAI` 공급자 대신 `OpenAI-API-compatible`로 노출될 수 있습니다. Dify UI가 다르게 보인다면 해당 버전에서 사용 가능한 가장 유사한 OpenAI 호환 사용자 지정 공급자 흐름을 사용하십시오.
</Note>

<Note>
  **유형**: 프레임워크 또는 플랫폼

  **기본 경로**: OpenAI 호환 채팅 경로

  **지원 신뢰도**: 범위 제한 내 지원
</Note>

## 사전 요구 사항

* API 액세스가 가능한 TokenLab 계정
* Dify Cloud 또는 자체 호스팅 Dify

## 구성 단계

### 1단계: API 키 가져오기

1. [TokenLab 대시보드](https://tokenlab.sh/dashboard)에 로그인합니다.
2. [API 키](https://tokenlab.sh/dashboard/api)를 엽니다.
3. `sk-`로 시작하는 API 키를 생성하거나 복사합니다.

### 2단계: 공급자 구성

<Steps>
  <Step title="모델 공급자 열기">
    Dify에서 **설정(Settings)** → \*\*모델 공급자(Model Providers)\*\*로 이동합니다.
  </Step>

  <Step title="OpenAI 선택">
    **OpenAI** 공급자 설정을 엽니다. Dify 버전에서 사용자 지정 기본 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. 테스트 프롬프트를 보냅니다.
3. Dify가 유효한 응답을 받는지 확인합니다.

## 지식 베이스를 위한 임베딩

RAG 및 지식 베이스 인덱싱을 위해 다음과 같은 임베딩 모델을 추가하십시오:

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

그런 다음 관련 지식 베이스 또는 애플리케이션 설정에서 기본 임베딩 모델로 설정합니다.

## 권장 모델 역할

| 사용 사례  | 권장 모델                                                      |
| ------ | ---------------------------------------------------------- |
| 기본 채팅  | `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`    |
| 임베딩    | `text-embedding-3-small`, `text-embedding-3-large`         |

## 모범 사례

<AccordionGroup>
  <Accordion title="내장 OpenAI 공급자로 시작하기">
    최신 Dify 버전에서는 사용자 지정 기본 URL을 사용하는 내장 OpenAI 공급자가 일반적으로 TokenLab을 위한 가장 깔끔한 설정입니다.
  </Accordion>

  <Accordion title="반복 작업 시 저렴한 모델 사용">
    반복 작업 중에는 `gpt-5.4-mini`, `gemini-3.5-flash` 또는 `deepseek-v4-flash`를 사용하고, 필요한 경우에만 더 강력한 모델로 전환하십시오.
  </Accordion>

  <Accordion title="Dify는 일반적으로 채팅 완성 지향적임을 기억하세요">
    대부분의 Dify 흐름은 OpenAI 호환 채팅 동작을 사용합니다. Codex 전용 응답이나 WebSocket 동작이 필요한 경우 Dify 대신 전용 Codex 통합을 사용하십시오.
  </Accordion>
</AccordionGroup>

## 문제 해결

<AccordionGroup>
  <Accordion title="연결 오류">
    * 기본 URL이 정확히 `https://api.tokenlab.sh/v1`인지 확인하십시오.
    * Dify가 슬래시를 중복 추가하는 경우 후행 슬래시를 제거하십시오.
    * Dify 서버가 공용 인터넷을 통해 TokenLab에 도달할 수 있는지 확인하십시오.
  </Accordion>

  <Accordion title="401 Unauthorized">
    * API 키를 다시 확인하십시오.
    * TokenLab 대시보드에서 키가 활성 상태인지 확인하십시오.
    * Dify에 붙여넣은 값에 공백이나 줄 바꿈이 포함되어 있지 않은지 확인하십시오.
  </Accordion>

  <Accordion title="모델을 찾을 수 없음">
    * 모델 이름을 정확히 확인하십시오.
    * 공급자 UI가 이전 값을 캐시한 경우 모델 항목을 다시 추가하십시오.
    * TokenLab 문서나 대시보드에서 현재 모델 가용성을 확인하십시오.
  </Accordion>
</AccordionGroup>