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

# Dify 설정 가이드

> Dify에서 Crazyrouter를 통해 채팅, 임베딩, 워크플로우 모델을 연동하고, 모델 공급자 설정, 검증 및 트러블슈팅을 완료하는 방법

> 업데이트: 2026-06-06

Dify는 워크플로우, 에이전트, 지식 베이스, 내부 AI 애플리케이션 플랫폼을 구축하는 데 적합합니다. Crazyrouter와 연동할 때는 먼저 Dify의 OpenAI 호환 모델 공급자 경로를 통해 채팅 모델을 먼저 정상적으로 동작시킨 뒤, 점차 임베딩이나 다른 기능을 추가하는 것을 권장합니다.

## 개요

Dify의 모델 공급자 설정을 통해 Crazyrouter를 OpenAI 호환 업스트림으로 연동할 수 있습니다.

* 권장 프로토콜: `OpenAI-compatible API`
* 권장 진입점: `설정 / Settings` → `모델 공급자 / Model Provider`
* Base URL: `https://api.crazyrouter.com/v1`
* 인증 방식: `sk-...` 토큰
* 최초 검증 권장 모델: `gpt-5.5`

<Tip>
  Dify 버전이나 플러그인 배포판에 따라 공급자 이름이 `OpenAI`, `OpenAI-API-compatible`, `OpenAI Compatible` 또는 유사한 이름으로 표시될 수 있습니다. 커스텀 `API Base URL`을 지원하는 OpenAI 호환 진입점을 우선 선택하면 됩니다.
</Tip>

<Note>
  Dify 공식 문서에서는 커스텀 `API Base URL`을 프록시나 호환 업스트림 시나리오에서의 선택 사항으로 취급합니다. Crazyrouter와 연동할 때는 Crazyrouter를 이러한 OpenAI 호환 업스트림으로 간주하고 `https://api.crazyrouter.com/v1`을 입력해야 합니다. 또한 모델 공급자 설정은 일반적으로 워크스페이스 관리자 또는 Owner 권한이 필요합니다. 진입점이 보이지 않는다면 먼저 현재 계정의 역할을 확인하세요.
</Note>

## 이런 분들께 적합합니다

* 워크플로우, 에이전트, 지식 베이스 애플리케이션을 구축하려는 분
* 채팅 모델과 임베딩 모델을 Crazyrouter로 통합하여 연동하려는 팀
* 업무 부서에 시각화된 AI 오케스트레이션 플랫폼을 제공하려는 분
* 테스트와 프로덕션 모델을 환경별로 관리하려는 분

## 사용 프로토콜

권장 프로토콜: `OpenAI-compatible API`

Dify에서 Crazyrouter를 연동할 때 일반적으로 입력하는 OpenAI 호환 base URL은 다음과 같습니다.

```text theme={null}
https://api.crazyrouter.com/v1
```

다음과 같이 입력하지 마세요.

* `https://api.crazyrouter.com`
* `https://api.crazyrouter.com/v1/chat/completions`

<Tip>
  Dify 버전에 따라 화면의 문구가 `Model Provider`, `모델 공급자`, `Providers` 또는 플러그인 마켓 진입점 사이에서 다르게 표시될 수 있지만, 최초 검증 경로는 동일하게 유지하세요. 먼저 공급자를 저장한 후, `LLM` 모델 `gpt-5.5` 하나만 추가하고, 마지막으로 최소한의 Chat 애플리케이션을 만들어 검증합니다.
</Tip>

## 사전 조건

| 항목             | 설명                                                        |
| -------------- | --------------------------------------------------------- |
| Crazyrouter 계정 | 먼저 [crazyrouter.com](https://crazyrouter.com)에서 가입하세요     |
| Crazyrouter 토큰 | Dify 전용으로 `sk-...` 토큰을 별도로 생성하는 것을 권장합니다                  |
| Dify           | 현재 안정 버전을 사용하는 것을 권장합니다. 버전에 따라 진입점 이름이 약간 다를 수 있습니다      |
| 사용 가능한 모델      | 당일 테스트를 통해 성공이 확인된 채팅 모델을 최소 하나 이상 허용해야 합니다. 예: `gpt-5.5` |

권장 초기 화이트리스트:

* `gpt-5.5`
* `claude-opus-4-8`
* `text-embedding-3-large`
* `text-embedding-3-small`

지식 베이스를 구축하려는 경우, 채팅 모델과 임베딩 모델을 최소 하나씩 함께 준비하는 것을 권장합니다.

## 5분 빠른 시작

<Steps>
  <Step title="Dify 전용 토큰 생성">
    Crazyrouter 백엔드에서 새 토큰을 생성하고, 이름은 `dify`로 지정하는 것을 권장합니다. 처음에는 `gpt-5.5`와 임베딩 모델 하나(예: `text-embedding-3-large`)만 허용하세요.
  </Step>

  <Step title="모델 공급자 설정으로 이동">
    워크스페이스 관리 권한이 있는 계정으로 Dify에 로그인하고, `설정 / Settings` → `모델 공급자 / Model Provider`로 이동합니다.
  </Step>

  <Step title="OpenAI 호환 공급자 추가">
    `OpenAI` 또는 `OpenAI-compatible` 유형의 공급자 진입점을 선택하고 다음을 입력합니다.

    * `API Key`: 사용할 `sk-...`
    * `API Base URL`: `https://api.crazyrouter.com/v1`
  </Step>

  <Step title="채팅 모델 하나만 먼저 설정">
    처음에는 LLM 하나만 추가하세요. 예:

    * `모델 이름 / Model`: `gpt-5.5`
    * `모델 유형 / Type`: `LLM`

    저장 후 가장 간단한 Chat 애플리케이션이나 Workflow 애플리케이션을 만들어 검증하세요. 처음부터 채팅, 임베딩, Rerank, 워크플로우 도구를 동시에 추가하면 트러블슈팅이 뒤섞일 수 있으므로 지양하세요.
  </Step>

  <Step title="최초 검증 완료">
    애플리케이션에서 `Reply only OK`를 보내보세요. 정상적으로 응답이 오고 Crazyrouter 백엔드에 로그가 남는다면 채팅 경로가 정상적으로 연동된 것입니다. 그 후 임베딩이나 다른 모델을 추가하세요.
  </Step>
</Steps>

## 임베딩 및 지식 베이스 권장 사항

Dify에서 지식 베이스, RAG 또는 문서 검색을 사용하려는 경우, 두 번째 단계로 임베딩 모델을 추가하는 것을 권장합니다.

| 용도      | 권장 모델                    | 설명                           |
| ------- | ------------------------ | ---------------------------- |
| 기본 임베딩  | `text-embedding-3-large` | 품질이 더 안정적이며 지식 베이스 초기 구축에 적합 |
| 저비용 임베딩 | `text-embedding-3-small` | 비용을 절약할 수 있어 대규모 문서에 적합      |

권장 순서:

1. 먼저 채팅 모델을 검증합니다
2. 그다음 임베딩을 검증합니다
3. 마지막으로 지식 베이스 임포트와 검색 튜닝을 진행합니다

이렇게 하면 트러블슈팅이 가장 명확해집니다.

## 권장 모델 설정

| 사용 시나리오        | 권장 모델                    | 이유                                    |
| -------------- | ------------------------ | ------------------------------------- |
| 기본 워크플로우 채팅 모델 | `gpt-5.5`                | 당일 테스트에서 성공이 확인되어 Dify 채팅의 주 기준선으로 적합 |
| 고품질 복잡한 시나리오   | `claude-opus-4-8`        | 복잡한 설명, 요약, 긴 텍스트에 더 적합               |
| Gemini 대체 옵션   | `gemini-3.1-pro`         | 두 번째 업스트림 호환성 검증 경로로 적합               |
| 기본 임베딩         | `text-embedding-3-large` | 지식 베이스 품질이 더 안정적                      |
| 저비용 임베딩        | `text-embedding-3-small` | 예산에 민감한 인덱싱 시나리오에 적합                  |

권장 순서: 채팅 모델을 먼저 정상 동작시킨 후 임베딩 모델을 추가하세요.

## 토큰 설정 모범 사례

| 설정        | 권장 사항                  | 설명                                                 |
| --------- | ---------------------- | -------------------------------------------------- |
| 전용 토큰     | 필수                     | Dify는 채팅 프론트엔드나 CLI 도구와 토큰을 공유하지 않아야 합니다           |
| 모델 화이트리스트 | 강력 권장                  | Dify 워크플로우가 실제로 호출하는 모델만 허용하세요                     |
| IP 제한     | 고정 배포 출구가 있는 경우 활성화 권장 | 로컬 개발 환경에서 자주 변경되는 경우에는 신중히 사용하세요                  |
| 할당량 상한    | 강력 권장                  | Dify 워크플로우, 배치 처리, 지식 베이스 임포트는 할당량을 빠르게 소진할 수 있습니다 |
| 환경 분리     | 필수                     | 개발, 테스트, 프로덕션에 각각 다른 토큰을 사용하는 것을 권장합니다             |
| 채팅/임베딩 분리 | 권장                     | 트래픽이 많은 시나리오에서는 청구와 속도 제한을 쉽게 하기 위해 토큰을 분리할 수 있습니다 |

## 검증 체크리스트

* [ ] `모델 공급자 / Model Provider`에 Crazyrouter 설정을 저장했습니다
* [ ] `API Base URL`을 `https://api.crazyrouter.com/v1`로 설정했습니다
* [ ] LLM 최소 하나를 성공적으로 추가했습니다
* [ ] 첫 번째 Dify 애플리케이션 요청이 성공적으로 응답을 받았습니다
* [ ] Crazyrouter 백엔드 로그에서 해당 요청을 확인할 수 있습니다
* [ ] 지식 베이스가 필요하다면 임베딩 모델 최소 하나를 성공적으로 설정했습니다
* [ ] 토큰 할당량과 모델 화이트리스트가 예상과 일치합니다
* [ ] 개발/테스트/프로덕션 토큰 분리가 완료되었습니다

## 자주 발생하는 오류와 해결 방법

| 증상                                    | 일반적인 원인                                            | 해결 방법                                                                                         |
| ------------------------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `모델 공급자 / Model Provider` 진입점이 보이지 않음 | 현재 계정이 워크스페이스 관리자나 Owner가 아님                       | 권한이 있는 계정을 사용하거나 관리자에게 설정을 대신 요청하세요                                                           |
| 공급자 진입점은 보이지만 OpenAI 호환 옵션이 없음        | 현재 버전에서 플러그인 형태로 제공되거나 이름이 다르거나 해당 공급자를 먼저 활성화해야 함 | `OpenAI`, `OpenAI Compatible`, `OpenAI-API-compatible` 같은 진입점을 찾아보고, 필요하면 플러그인이나 버전 설명을 확인하세요 |
| 공급자를 저장할 수 없음                         | API Key 오류 또는 커스텀 Base URL을 지원하는 공급자 유형을 입력하지 않음   | OpenAI 호환 공급자 진입점으로 변경하고 `sk-...`를 다시 입력하세요                                                   |
| 401 unauthorized                      | 토큰이 만료되었거나, 복사 오류가 있거나, 삭제됨                        | 토큰을 재생성하고 교체하세요                                                                               |
| 403 / model not allowed               | Dify에서 선택한 모델이 토큰 화이트리스트에 없음                       | Crazyrouter 백엔드에서 해당 모델을 허용하세요                                                                |
| 404                                   | `API Base URL`을 루트 도메인이나 전체 엔드포인트 경로로 입력함          | `https://api.crazyrouter.com/v1`로 변경하세요                                                       |
| 채팅 모델은 설정되지만 애플리케이션에서 오류 발생           | 모델 이름이 잘못되었거나 컨텍스트 파라미터 설정이 부적절함                   | 먼저 `gpt-5.5`로 돌아가 기준선을 검증하세요                                                                  |
| 지식 베이스 임포트 실패                         | 채팅 모델은 정상 동작하지만 임베딩 모델이 제대로 설정되지 않음                | 먼저 임베딩 설정을 개별적으로 검증한 후 지식 베이스를 다시 임포트하세요                                                      |
| 워크플로우 비용이 빠르게 증가함                     | 배치 실행, 긴 컨텍스트, 또는 여러 애플리케이션이 동일한 토큰을 공유함           | 토큰을 분리하고 할당량 상한을 설정하며 모델 범위를 줄이세요                                                             |
| 일부 고급 모델 기능이 Dify에서 일관되지 않게 동작함       | 모델별로 Dify 노드와의 파라미터 호환성이 다름                        | 먼저 `gpt-5.5`로 기준선을 확인한 후 다른 모델로 점진적으로 교체하세요                                                   |

## 성능 및 비용 권장 사항

* 워크플로우는 기본적으로 `gpt-5.5`로 먼저 테스트한 후 안정화되면 다른 모델을 추가하세요
* 지식 베이스를 처음 도입할 때는 소량의 문서로 검색 품질을 먼저 검증한 후 대량으로 임포트하세요
* 채팅 모델과 임베딩 모델의 비용을 분리하여 계산하면 비용 원인을 파악하기 쉬워집니다
* 배치 작업, 예약 작업, 내부 테스트 환경에는 더 엄격한 할당량 상한을 설정하세요
* 소비가 급증한 경우, 먼저 Crazyrouter 로그를 확인하여 워크플로우 재시도, 지식 베이스 임포트, 또는 여러 애플리케이션의 토큰 공유 중 어느 것이 원인인지 파악하세요

## FAQ

### Dify는 어떤 Base URL을 입력해야 하나요?

`https://api.crazyrouter.com/v1`을 입력하세요.

### 여기서 루트 도메인 입력을 권장하지 않는 이유는 무엇인가요?

Dify의 OpenAI 호환 공급자는 일반적으로 루트 도메인이 아닌 OpenAI 호환 base URL을 요구하기 때문입니다.

### 채팅 모델과 임베딩 중 무엇을 먼저 설정해야 하나요?

먼저 채팅 모델을 설정하고 애플리케이션이 정상적으로 결과를 반환하는지 확인한 후 임베딩을 설정하세요.

### Rerank 모델을 바로 설정할 수 있나요?

사용 중인 Dify 버전과 현재 사용 가능한 공급자 플러그인에 따라 다릅니다. 먼저 채팅과 임베딩을 정상 동작시킨 후 Rerank를 별도로 연동할 필요가 있는지 판단하는 것을 권장합니다.

### 여기서 채팅 모델 하나만 먼저 설정하도록 강조하는 이유는 무엇인가요?

Dify의 문제는 공급자, 모델 유형, 애플리케이션 파라미터, 지식 베이스 체인에서 동시에 발생하기 쉽기 때문입니다. `gpt-5.5` 채팅 애플리케이션 하나만 먼저 정상 동작시키면 문제 위치를 훨씬 명확하게 파악할 수 있습니다.

### Dify는 토큰을 여러 개로 분리해야 하나요?

분리하는 것을 권장합니다. 최소한 개발/프로덕션을 분리하고, 트래픽이 많은 시나리오라면 채팅과 임베딩도 분리하세요.

<Note>
  Dify는 "애플리케이션 플랫폼"과 "워크플로우 플랫폼"의 위치에 가장 적합합니다. 채팅 프론트엔드와 비교했을 때, 프로세스 오케스트레이션, 지식 베이스, 다중 환경 관리를 더 강조하므로 전용 토큰, 모델 화이트리스트, 할당량 전략이 더 필요합니다.
</Note>