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

# Dify에서 ElkAPI 사용하기

> Dify LLMOps 플랫폼에서 ElkAPI API 서비스를 설정하고 사용하는 상세 가이드입니다. 이 가이드는 Dify에서 ElkAPI API를 설정하여 강력한 AI 애플리케이션을 구축하는 데 도움이 됩니다.

## 준비사항

시작하기 전에 다음을 확인하세요:

1. **Dify 계정 등록 완료**\
   [Dify 공식 웹사이트](https://dify.ai/)를 방문하여 계정을 등록하고 클라우드 또는 자체 호스팅 버전을 선택

2. **ElkAPI API 키 획득 완료**\
   [ElkAPI 콘솔](https://api.elkapi.com/keys)에 로그인하여 API 키(`sk-`로 시작)를 획득

<Note>
  **팁:** ElkAPI 계정이 아직 없다면, 먼저 [ElkAPI](https://api.elkapi.com)에서 등록하고 API 키를 획득하세요.
</Note>

## 1단계: Dify에 로그인하고 설정 접근

### 1.1 Dify 플랫폼 접근

* **클라우드 버전:** [https://cloud.dify.ai](https://cloud.dify.ai)를 방문하여 로그인
* **자체 호스팅 버전:** Dify 배포 주소로 접근

<Frame>
  <img src="https://mintcdn.com/apicore/YzmLocOfv2p0qXT_/images/integrations/dify/main-interface.png?fit=max&auto=format&n=YzmLocOfv2p0qXT_&q=85&s=b2629691b3ce6be3763872f6a49cda50" alt="Dify 메인 인터페이스" width="2560" height="1270" data-path="images/integrations/dify/main-interface.png" />
</Frame>

<caption>*Dify 메인 인터페이스, 애플리케이션 목록과 앱 만들기 버튼 표시*</caption>

### 1.2 모델 설정 페이지로 이동

1. 오른쪽 상단의 **아바타 아이콘** 클릭
2. **설정** 선택
3. 왼쪽 메뉴에서 **모델 공급자** 선택

<Frame>
  <img src="https://mintcdn.com/apicore/YzmLocOfv2p0qXT_/images/integrations/dify/model-provider-menu.png?fit=max&auto=format&n=YzmLocOfv2p0qXT_&q=85&s=8d581711b30768dd8d39bb6b7b37d8aa" alt="모델 공급자 설정 페이지" width="2560" height="1270" data-path="images/integrations/dify/model-provider-menu.png" />
</Frame>

<caption>*왼쪽 메뉴에서 "모델 공급자" 옵션 찾기*</caption>

<Note>
  **참고:** Dify는 여러 모델 공급자 설정을 지원합니다. ElkAPI를 다른 공급자와 함께 사용할 수 있습니다.
</Note>

## 2단계: ElkAPI 모델 공급자 추가

<Note>
  **설정 방법 안내:** Dify에서 ElkAPI를 설정하는 두 가지 방법이 있습니다:

  **방법 1(권장):** OpenAI 공급자의 사용자 지정 API 기능 사용

  * OpenAI 공급자 설정에서 Base URL을 `https://api.elkapi.com/v1`로 직접 수정
  * ElkAPI API 키 입력
  * 더 빠르고 간단한 설정

  **방법 2:** 사용자 지정 모델 공급자로 추가(본 가이드 방법)

  * 더 유연하며 ElkAPI 공급자를 개별적으로 관리 가능
  * 여러 API 공급자를 동시에 사용할 때 편리

  두 방법 모두 기능적으로 동일합니다. 선호도에 따라 선택하세요.
</Note>

### 2.1 설정 방법 선택

#### 방법 1: OpenAI 사용자 지정 API 사용(권장)

1. 모델 공급자 페이지에서 **OpenAI** 공급자 찾기
2. **설정** 버튼 클릭
3. 설정 페이지에서:
   * **API Key**: ElkAPI API 키 입력(`sk-xxxxxxxxxxxx`)
   * **API Base URL** 또는 **Base URL**: `https://api.elkapi.com/v1` 입력
4. **저장** 클릭

<Frame>
  <img src="https://mintcdn.com/apicore/YzmLocOfv2p0qXT_/images/integrations/dify/openai-custom-api.png?fit=max&auto=format&n=YzmLocOfv2p0qXT_&q=85&s=78a7bb17489c1271bea96da0f6ddfe82" alt="OpenAI 사용자 지정 API 설정" width="2560" height="1270" data-path="images/integrations/dify/openai-custom-api.png" />
</Frame>

<Frame>
  <img src="https://mintcdn.com/fuhu/rGvMBqASJ4r9KbNS/images/integrations/dify/openai-custom-setting.png?fit=max&auto=format&n=rGvMBqASJ4r9KbNS&q=85&s=e0e12be23a91d3ff0d41b3f342155253" alt="OpenAI 사용자 지정 API 설정" width="2560" height="1270" data-path="images/integrations/dify/openai-custom-setting.png" data-path="images/integrations/dify/openai-custom-setting.png" />
</Frame>

<caption>*OpenAI 공급자에서 ElkAPI의 API 키와 Base URL 설정*</caption>

5. 설정 완료 후 OpenAI 공급자 페이지로 돌아가 **모델 목록** 확인
6. 모델 목록에서 필요한 모델 찾기(예: `gpt-5.5`, `gpt-5.4-mini`, `gpt-5.5` 등)
7. 모델 오른쪽의 **스위치**를 클릭하여 활성화(파란색은 활성화를 나타냄)

<Frame>
  <img src="https://mintcdn.com/apicore/YzmLocOfv2p0qXT_/images/integrations/dify/openai-model-list.png?fit=max&auto=format&n=YzmLocOfv2p0qXT_&q=85&s=845665fe4f33a65169747c3813202c37" alt="OpenAI 모델 목록" width="2560" height="1270" data-path="images/integrations/dify/openai-model-list.png" />
</Frame>

<caption>*OpenAI 모델 목록에서 필요한 모델 활성화*</caption>

<Warning>
  **중요：** ElkAPI가 실제로 지원하는 모델만 활성화하세요!

  Dify의 OpenAI 모델 목록에는 많은 모델이 표시되지만, ElkAPI가 지원하는 모델만 정상적으로 작동합니다. 지원되지 않는 모델을 활성화하면 API 호출이 실패합니다.

  지원되는 모델의 전체 목록은 [ElkAPI API 문서](https://docs.elkapi.com)를 참조하세요.
</Warning>

<Tip>
  **ElkAPI 지원 권장 모델:**

  **GPT 시리즈:**

  * `gpt-5.5` / `gpt-5.5-pro` - GPT-5 시리즈 모델
  * `gpt-5.4` / `gpt-5.4-mini` - GPT-5.4 시리즈 모델
  * `gpt-5.4-mini` - 빠르고 경제적인 버전
  * `gpt-5.4` / `gpt-5.4-mini` - GPT-5.4 시리즈

  **Claude 시리즈:**

  * `claude-sonnet-4-6` - Claude Sonnet 4.6
  * `claude-sonnet-4-6` - Claude Opus 4.7

  **Gemini 시리즈:**

  * `gemini-3.1-flash-lite-preview` - Google Gemini 3.1 Flash Lite

  여러 모델을 동시에 활성화하여 애플리케이션에서 유연하게 전환하여 사용할 수 있습니다.
</Tip>

완료 후 바로 사용할 수 있습니다. [3단계](#3단계-애플리케이션에서-elkapi-모델-사용)로 이동하세요.

#### 방법 2: 사용자 지정 모델 공급자 추가

모델 공급자 페이지에서:

1. **사용자 지정 모델** 섹션으로 스크롤
2. **+ 모델 추가** 버튼 클릭

<Frame>
  <img src="https://mintcdn.com/apicore/YzmLocOfv2p0qXT_/images/integrations/dify/custom-model-section.png?fit=max&auto=format&n=YzmLocOfv2p0qXT_&q=85&s=9b48a67bc1bdc0f64976742c7fdd6c4a" alt="사용자 지정 모델 섹션" width="2560" height="1270" data-path="images/integrations/dify/custom-model-section.png" />
</Frame>

<caption>*사용자 지정 모델 섹션으로 스크롤하여 "+ 모델 추가" 버튼 클릭*</caption>

### 2.2 ElkAPI 공급자 설정

설정 대화상자에서 다음 정보를 입력:

| 필드                   | 값                                                                  |
| -------------------- | ------------------------------------------------------------------ |
| **모델 이름**            | `ElkAPI` 또는 사용자 지정 이름                                              |
| **모델 유형**            | `LLM`(대규모 언어 모델) 선택                                                |
| **API Key**          | ElkAPI API 키(`sk-xxxxxxxxxxxx`)                                    |
| **API endpoint URL** | `https://api.elkapi.com/v1`                                        |
| **Endpoint 모델 이름**   | 구체적인 모델 이름 입력(예: `gpt-5.5`, `gpt-5.4-mini`, `claude-sonnet-4-6` 등) |

<Frame>
  <img src="https://mintcdn.com/fuhu/rGvMBqASJ4r9KbNS/images/integrations/dify/add-provider-dialog.png?fit=max&auto=format&n=rGvMBqASJ4r9KbNS&q=85&s=7b3b837a2f8b43288c17773de8b8bce3" alt="공급자 추가 대화상자" width="2560" height="1270" data-path="images/integrations/dify/add-provider-dialog.png" data-path="images/integrations/dify/add-provider-dialog.png" />
</Frame>

<caption>*ElkAPI 공급자 설정 정보 입력*</caption>

<Warning>
  **중요:**

  * Base URL에는 `/v1` 접미사가 포함되어야 합니다: `https://api.elkapi.com/v1`
  * API 키는 ElkAPI 콘솔에서 획득한 `sk-`로 시작하는 키여야 합니다
  * API 키에 충분한 잔액이 있는지 확인하세요
</Warning>

### 2.3 더 많은 모델 추가(선택 사항)

더 많은 모델을 추가하려면 위 단계를 반복:

1. 사용자 지정 모델 섹션에서 **+ 모델 추가** 버튼을 다시 클릭
2. 다른 모델의 설정 정보 입력
3. 저장 클릭

**추가 권장 모델:**

#### GPT-4/5 시리즈

| 모델 ID          | 모델 이름        | 컨텍스트 길이 | 사용 사례            |
| -------------- | ------------ | ------- | ---------------- |
| `gpt-5.5`      | GPT-5        | 128,000 | 복잡한 작업, 긴 텍스트 처리 |
| `gpt-5.5`      | GPT-5.5      | 128,000 | 고품질 대화, 코드 생성    |
| `gpt-5.4-mini` | GPT-5.4 Mini | 128,000 | 빠른 응답, 비용 효율적    |

#### Claude 시리즈

| 모델 ID               | 모델 이름             | 컨텍스트 길이 | 사용 사례         |
| ------------------- | ----------------- | ------- | ------------- |
| `claude-sonnet-4-6` | Claude Sonnet 4.6 | 200,000 | 복잡한 추론, 코드 분석 |
| `claude-sonnet-4-6` | Claude Opus 4.7   | 200,000 | 빠른 응답, 간단한 작업 |

#### Gemini 시리즈

| 모델 ID                           | 모델 이름                 | 컨텍스트 길이 | 사용 사례            |
| ------------------------------- | --------------------- | ------- | ---------------- |
| `gemini-3.1-flash-lite-preview` | Gemini 3.1 Flash Lite | 32,000  | 멀티모달, 실시간 애플리케이션 |

<Tip>
  **성능 권장사항:**

  * 💰 **비용 효율적:** `gpt-5.4-mini`, `claude-sonnet-4-6`
  * 🚀 **고성능:** `gpt-5.5`, `gpt-5.5-pro`, `claude-sonnet-4-6`
  * ⚡ **빠른 응답:** `gemini-3.1-flash-lite-preview`, `gpt-5.4-mini`
</Tip>

## 3단계: 애플리케이션에서 ElkAPI 모델 사용

### 3.1 새 애플리케이션 만들기

1. Dify 홈페이지로 돌아가기
2. **앱 만들기** 버튼 클릭
3. 애플리케이션 유형 선택:
   * **챗봇** - 대화형 애플리케이션
   * **텍스트 생성기** - 텍스트 생성 애플리케이션
   * **에이전트** - 지능형 에이전트
   * **워크플로우** - 복잡한 워크플로우 애플리케이션

### 3.2 ElkAPI 모델 선택

애플리케이션 오케스트레이션 페이지에서:

1. **모델 설정** 영역 찾기
2. **모델 선택** 드롭다운 클릭
3. **ElkAPI** 공급자 선택
4. 설정한 모델 선택(예: `gpt-5.5`)

### 3.3 모델 매개변수 설정

필요에 따라 모델 매개변수 조정:

| 매개변수                  | 설명         | 권장 값                |
| --------------------- | ---------- | ------------------- |
| **Temperature**       | 출력 무작위성 제어 | 0.7(창의적) / 0.3(정확한) |
| **Max Tokens**        | 최대 출력 길이   | 2000-4000           |
| **Top P**             | 핵 샘플링 매개변수 | 0.9                 |
| **Presence Penalty**  | 반복 감소      | 0.0-0.5             |
| **Frequency Penalty** | 빈번한 단어 감소  | 0.0-0.5             |

## 4단계: 애플리케이션 구축 및 테스트

### 4.1 프롬프트 추가

애플리케이션 오케스트레이션 페이지에서:

1. **시스템 프롬프트** 영역에 프롬프트 작성
2. 변수를 사용하여 앱을 동적으로 만들기:
   * `{{variable_name}}` - 사용자 입력 변수
   * `{{context}}` - 지식 베이스 컨텍스트

**프롬프트 예시:**

```
당신은 제품에 관한 질문에 답변하는 데 능숙한 전문 고객 서비스 도우미입니다.

제품 정보: {{product_info}}

사용자 질문에 따라 정확하고 친근한 답변을 제공하세요. 확실하지 않은 경우 정직하게 사용자에게 알려주세요.

사용자 질문: {{user_question}}
```

### 4.2 지식 베이스 추가(선택 사항)

RAG(검색 증강 생성) 기능이 필요한 경우:

1. 왼쪽 메뉴에서 **지식 베이스** 클릭
2. 새 지식 베이스를 만들고 문서 업로드
3. 애플리케이션 오케스트레이션 페이지에서 지식 베이스 연결
4. 검색 매개변수 설정

### 4.3 애플리케이션 테스트

1. 오른쪽 **미리보기** 패널에 테스트 질문 입력
2. AI 응답 효과 검토
3. 필요에 따라 프롬프트와 매개변수 조정
4. 만족할 때까지 테스트 반복

### 4.4 애플리케이션 게시

테스트 후:

1. 오른쪽 상단의 **게시** 버튼 클릭
2. 게시 방법 선택:
   * **API 호출** - API를 통한 통합
   * **웹사이트에 임베드** - 임베드 코드 생성
   * **공개 링크** - 공유 링크 생성

## 5단계: 모니터링 및 최적화

### 5.1 애플리케이션 로그 보기

애플리케이션 세부정보 페이지에서:

1. **로그** 탭 클릭
2. 모든 대화 기록 보기
3. 사용자 질문 및 AI 응답 분석
4. 개선 기회 발견

### 5.2 API 사용 모니터링

[ElkAPI 콘솔](https://api.elkapi.com)에 로그인하여 확인:

* 📊 **API 호출 통계** - 총 호출 수, 성공률
* 💰 **비용 세부정보** - 일일/월간 비용
* 📈 **사용 추세** - 사용량 변화 추세
* 🔍 **요청 로그** - 상세한 요청 기록

### 5.3 애플리케이션 성능 최적화

모니터링 데이터를 기반으로 최적화:

1. **모델 선택 조정**
   * 간단한 작업에는 `gpt-5.4-mini`를 사용하여 비용 절감
   * 복잡한 작업에는 `gpt-5.5` 또는 `claude-sonnet-4-6`를 사용하여 품질 향상

2. **프롬프트 최적화**
   * 프롬프트를 더 명확하고 구체적으로 만들기
   * 예제를 추가하여 효과 향상
   * 사고의 연쇄를 사용하여 추론 능력 향상

3. **캐싱 설정**
   * 유사한 질문에 대해 캐싱 활성화
   * API 호출 비용 절감

## 자주 묻는 질문

### Q1: ElkAPI 서비스에 연결할 수 없습니까?

**해결책:**

1. **Base URL 확인**:
   * `https://api.elkapi.com/v1`(`/v1` 포함)인지 확인
   * 추가 경로를 추가하거나 `/v1`을 생략하지 마세요

2. **API 키 확인**:
   * API 키가 `sk-`로 시작하는지 확인
   * [ElkAPI 콘솔](https://api.elkapi.com/keys)에서 키가 유효한지 확인

3. **네트워크 연결 확인**:
   * 서버가 `https://api.elkapi.com`에 액세스할 수 있는지 확인
   * 자체 호스팅 버전의 경우 서버 네트워크 연결 확인

### Q2: 모델 응답이 느립니까?

**해결책:**

1. **더 빠른 모델로 전환**:
   * `gpt-5.5` 대신 `gpt-5.4-mini` 사용
   * 더 빠른 응답을 위해 `gemini-3.1-flash-lite-preview` 사용

2. **프롬프트 길이 최적화**:
   * 불필요한 컨텍스트 줄이기
   * 프롬프트 설명 단순화

3. **지식 베이스 검색 조정**:
   * 검색 문서 수 줄이기
   * 유사도 임계값 높이기

### Q3: API 호출이 실패하거나 오류를 반환합니까?

**일반적인 오류 및 해결책:**

| 오류 메시지                      | 원인                 | 해결 방법                       |
| --------------------------- | ------------------ | --------------------------- |
| `401 Unauthorized`          | 유효하지 않거나 만료된 API 키 | API 키를 다시 받고 설정 업데이트        |
| `429 Too Many Requests`     | 요청 속도 제한 초과        | 앱 동시성 설정 조정 또는 대기 후 재시도     |
| `500 Internal Server Error` | 일시적인 서버 문제         | 몇 분 기다린 후 재시도               |
| `insufficient_quota`        | 계정 잔액 부족           | 콘솔에서 충전                     |
| `context_length_exceeded`   | 입력이 컨텍스트 길이 초과     | 입력 길이를 줄이거나 더 큰 컨텍스트의 모델 사용 |

## 지원 및 도움말

문제가 발생한 경우:

* 📚 [ElkAPI 문서](https://docs.elkapi.com)
* 📚 [Dify 공식 문서](https://docs.dify.ai)
* 📧 기술 지원: [support@elkapi.com](mailto:support@elkapi.com)

***

<Card title="ElkAPI 시작하기" icon="rocket" href="https://api.elkapi.com">
  지금 ElkAPI에 등록하고 API 키를 받아 Dify에서 강력한 AI 애플리케이션을 구축하세요!
</Card>