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

# Dify BetterToken 설정: API Key, Base URL 및 사용자 지정 모델

> Base URL, API Key 및 호환되는 provider model로 Dify를 BetterToken에 연결한 다음 연결을 확인하고 일반적인 오류를 해결하세요.

Dify를 BetterToken에 연결하려면 API Key를 준비하고 아래 Base URL을 입력한 후 모델 광장에서 현재 Model ID를 선택하세요.

## 주요 설정

| 필드       | 값                                                                 |
| -------- | ----------------------------------------------------------------- |
| API Key  | BetterToken API Key                                               |
| Base URL | `https://www.bettertoken.ai/v1`                                   |
| 모델       | <a href={"https://bettertoken.ai/pricing"}>모델 광장</a>의 현재 Model ID |

## 사전 요구 사항

* 최신 버전의 도구가 설치되어 있음
* BetterToken API Key: <a href={"https://bettertoken.ai/register"}>등록하고 발급받기</a>
* <a href={"https://bettertoken.ai/pricing"}>모델 광장</a>의 Model ID

### 추가 요구 사항

* Dify Cloud 또는 plugins가 활성화된 self-hosted Dify instance
* model plugins 설치 및 workspace models 관리 권한

<Note>
  이 가이드는 **LLM Chat**만 구성합니다. GPT chat model을 Text Embedding, Rerank, Speech-to-Text 또는 Text-to-Speech로 추가하지 마세요.
</Note>

## 설치

### OpenAI-compatible model plugin 설치

<Steps>
  <Step title="Model Providers 열기">
    Dify workspace에서 **Integrations > Model Providers**로 이동하세요.
  </Step>

  <Step title="공식 plugin 설치">
    **Install model providers**를 클릭하고 **OpenAI-API-compatible**를 검색하여 설치하세요.

    Dify는 model providers를 workspace-level plugins로 관리합니다. 설치 후 필요한 workspace permissions가 있는 apps는 이 provider에서 models를 선택할 수 있습니다.
  </Step>

  <Step title="사용자 지정 model 추가">
    **OpenAI-API-compatible** card에서 **Add Model**을 클릭하세요. card에 먼저 **Setup** 또는 **Configure**가 표시되면 열고 model 추가 option을 선택하세요.
  </Step>
</Steps>

## 수동 설정

Dify model-provider UI에서 이 설정을 완료하세요. configuration file을 편집할 필요가 없습니다.

| 필드       | 값                                                                 |
| -------- | ----------------------------------------------------------------- |
| API Key  | BetterToken API Key                                               |
| Base URL | `https://www.bettertoken.ai/v1`                                   |
| 모델       | <a href={"https://bettertoken.ai/pricing"}>모델 광장</a>의 현재 Model ID |

### model configuration 입력

첫 번째 model에 다음 values를 사용하세요.

| Dify field                  | 권장 value                                    |
| --------------------------- | ------------------------------------------- |
| Model Type                  | `LLM`                                       |
| Model Name                  | 모델 광장의 지원되는 provider의 model ID              |
| Model display name          | Model Name과 같은 value 사용 가능                  |
| API Key                     | BetterToken API Key                         |
| API Base URL                | `https://www.bettertoken.ai/v1`             |
| model name for API endpoint | Model Name과 동일한 model ID                    |
| Completion mode             | `Chat`                                      |
| Model context size          | 선택한 model과 일치시킴; 확실하지 않으면 plugin default 유지 |
| Upper bound for max tokens  | 선택한 model을 넘지 않음; 첫 테스트에는 plugin default 유지 |
| Compatibility mode          | `OpenAI compatible` / strict                |
| Token parameter name        | `Auto`                                      |
| Function Call Type          | 첫 테스트에는 `Not Support`                       |

<Warning>
  API Base URL로 `https://www.bettertoken.ai/v1`만 입력하세요. `/chat/completions`를 추가하지 마세요. Dify plugin이 필요한 endpoint를 호출합니다.
</Warning>

남은 optional capabilities에는 conservative values를 사용하세요.

* **Thinking Mode Support**: model support를 확인한 후에만 활성화
* **Stream function calling**: 첫 테스트에는 `Not Support` 선택
* **Vision Support**: model과 endpoint 모두 image input을 허용할 때만 활성화
* **Structured Output**: plain chat이 작동할 때까지 비활성화 유지

**Save**를 클릭하세요. Dify가 API Key, Base URL 및 model ID를 validate합니다.

### app에서 model 사용

<Steps>
  <Step title="Dify app 만들기 또는 열기">
    Chatbot, Agent, Chatflow 또는 Workflow를 여세요.
  </Step>

  <Step title="model 선택">
    app model selector 또는 **LLM** node에서 **OpenAI-API-compatible** 아래에 추가한 model을 선택하세요.
  </Step>

  <Step title="먼저 plain chat 테스트">
    tools 또는 images 없이 짧은 text input으로 첫 request를 실행하세요.

    ```text theme={null}
    Reply with exactly: Connection successful
    ```
  </Step>

  <Step title="이후 Agent capabilities 활성화">
    plain chat이 작동한 후 tool calls가 필요하면 model configuration을 편집하세요. **Function Call Type**을 model이 지원하는 mode로 설정합니다. OpenAI-compatible tool calling은 보통 `Tool Call`을 사용하지만 선택한 model과 endpoint의 support를 확인해야 합니다.
  </Step>
</Steps>

## 연결 확인

짧은 테스트 prompt를 보내세요. 도구가 authentication 또는 Model ID 오류 없이 response를 반환하면 연결이 작동합니다. configuration을 변경한 후에는 도구를 완전히 다시 시작하세요.

## 모델 전환

model selector를 열거나 configuration의 `Model` field를 변경하세요. <a href={"https://bettertoken.ai/pricing"}>모델 광장</a>의 정확한 Model ID를 사용한 다음 현재 session을 다시 시작하세요.

Dify는 model ID별로 custom configuration을 저장합니다. 지원되는 provider의 다른 model을 추가하려면 같은 provider에서 **Add Model**을 다시 클릭하세요. 새 ID를 **Model Name** 및 **model name for API endpoint** 모두에 사용합니다. Base URL과 API Key는 재사용할 수 있습니다.

## 일반적인 오류

### 저장 시 401 반환

* API Key가 완전한지 확인
* Model ID가 **지원되는 provider**에서 왔는지 확인
* BetterToken Dashboard에서 key status와 balance 확인

### 저장 시 404 반환

* API Base URL은 `https://www.bettertoken.ai/v1`이어야 함
* `/chat/completions`를 추가하지 않음
* **model name for API endpoint**가 모델 광장 ID와 정확히 일치하는지 확인

### Dify가 model not found 보고

**Model Name**은 Dify가 model을 표시하고 선택하는 방식에 영향을 줄 수 있습니다. 실제 request model은 **model name for API endpoint**가 제어합니다. 두 필드 모두 지원되는 provider의 동일한 model ID를 사용하세요.

### Plain chat은 작동하지만 Agent tools가 실패함

**Function Call Type**을 `Not Support`로 되돌리고 기본 LLM node를 확인하세요. 선택한 model이 tool calling을 지원할 때만 `Tool Call`로 변경한 후 tool arguments를 다시 테스트하세요.

### Knowledge에서 이 model을 Embedding Model로 사용할 수 없음

이는 예상된 동작입니다. chat LLM은 embedding model을 대체할 수 없습니다. 이 가이드는 Dify용 BetterToken embedding 또는 rerank endpoints를 확인하지 않으므로 Knowledge용 지원되는 embedding provider를 별도로 구성하세요.

## Advanced setup

## 지원 Provider

| Provider | 상태      |
| -------- | ------- |
| Claude   | 지원되지 않음 |
| GPT      | 수동 설정   |
| Kimi     | 수동 설정   |
| GLM      | 수동 설정   |

<Note>표시된 상태는 이 페이지에서 설명하는 BetterToken 설정 방식에 적용됩니다.</Note>

<Accordion title="설정 방식 설명">
  * **수동 설정**: API Key, Base URL, Model을 입력하세요.
  * **지원되지 않음**: 검증된 직접 연결 방식이 아직 없습니다.
</Accordion>

### 관련 가이드

* [Dify Model Providers](https://docs.dify.ai/en/cloud/use-dify/workspace/model-providers)
* [Dify 공식 OpenAI-API-compatible plugin](https://github.com/langgenius/dify-official-plugins/tree/main/models/openai_api_compatible)
* [OpenAI-compatible API와 Anthropic-compatible API 비교](/ko/faq/concepts/openai-compatible-vs-anthropic-compatible)
* [model 선택 방법](/ko/faq/model-calling/model-selection-guide)

## 기술 세부 정보

<Accordion title="Protocol, endpoint 및 내부 provider 필드">
  이 설정은 `https://www.bettertoken.ai/v1`을 사용합니다. 도구가 OpenAI-compatible endpoint path를 추가합니다. 특정 field에서 명시적으로 요구하지 않는 한 `/chat/completions` 또는 `/responses`를 추가하지 마세요.
</Accordion>