Dify와 Claude 및 GPT: OpenAI-API 호환 플러그인의 모든 필드 설명

Disclosure: 저는 예제에 사용된 게이트웨이인 APIVAI를 운영합니다. 설정은 OpenAI 또는 Anthropic 형식을 사용하는 모든 엔드포인트에 동일하게 적용됩니다.

Dify는 챗봇, 에이전트, 워크플로우 및 지식 기반(RAG) 앱을 구축하기 위한 오픈 소스 플랫폼입니다. Dify는 모델 제공자 플러그인을 통해 모델에 접근하며, 서드파티 게이트웨이가 있기 때문에 채워야 할 필드가 많아 하나를 잘못 입력하기 쉽습니다. 이 게시물에서는 Dify의 공식 openai_api_compatible 플러그인(버전 0.0.68)과 anthropic 플러그인의 실제 필드들을 살펴보겠습니다.

어떤 제공자 플러그인을 사용할까요?

Plugin	Address field	Models	Best for
OpenAI-API-compatible	API Base URL: `https://api.apivai.com/v1`	Claude 및 GPT	모든 모델을 하나의 제공자로 사용; 모델 ID를 직접 입력합니다
Anthropic	API URL: `https://api.apivai.com`	Claude만	Claude 전용, 프롬프트 캐싱이 적용된 네이티브 형식

OpenAI-API-compatible로 시작하세요: 각 모델 ID를 직접 입력하므로 게이트웨이가 목록에 추가하는 즉시 새로운 모델을 사용할 수 있습니다.

제공자는 Model Provider 페이지에서 찾을 수 있습니다. 현재 Dify Cloud에서는 Integrations 아래, 구형 자체 호스팅 버전의 계정 메뉴에서는 Settings 아래에 있습니다. 각 제공자는 전체 작업 공간(workspace)에 적용되며, 소유자 및 관리자만 변경할 수 있습니다.

1단계: 플러그인 설치

Model Provider를 열고, 설치 가능한 제공자 목록에서 OpenAI-API-compatible을 찾아 클릭하여 Install합니다.

2단계: 모델 추가

OpenAI-API-compatible 카드에서 Add Model을 클릭하고 다음 필드를 채웁니다:

Field	Value
Model Type	LLM
...
남은 필드는 기본값으로 둡니다. 플러그인의 구형 버전에서는 주소 필드를 API endpoint URL이라고 부르며, 값은 동일합니다.

사람들이 가장 자주 오해하는 필드들:

Model Name은 Dify가 API에 실제로 전송하는 값이므로 정확한 ID여야 합니다. 표시 이름(display name)은 인터페이스용일 뿐입니다.
Model context size는 Dify가 대화 기록과 검색된 지식을 프롬프트에 포함시킬 때 사용하는 제한 크기입니다. 모델의 실제 컨텍스트 창보다 낮은 값이어도 괜찮으며, 긴 채팅을 더 저렴하게 유지할 수 있습니다.
Upper bound for max tokens는 앱에서 Max Tokens가 얼마나 높게 설정될 수 있는지만 지정합니다. 추론(Thinking)은 기본적으로 켜져 있으며 출력으로 간주되므로 4096보다 여유 공간을 남겨두세요.
Function Call Type: Tool Call은 Agent 앱이 네이티브 도구 호출(tool calling) 기능을 사용할 수 있게 해줍니다.

Save를 클릭하면 Dify가 테스트 요청을 보내고, 통과할 경우에만 저장합니다. 원하는 모델마다 Add Model을 반복하여 추가해야 하며, 이때 키와 주소는 동일하게 설정해야 합니다. 예를 들어 gpt-5.5와 claude-haiku-4-5처럼요.

API에서 모델 ID를 가져오세요:

curl https://api.apivai.com/v1/models -H "Authorization: Bearer your-key"

3단계: 모델 사용하기

앱의 모델 선택기에서 OpenAI-API와 호환되는 모델을 선택하고 Max Tokens를 4096 이상으로 설정하세요.
워크플로우에서는 각 LLM 노드가 자체 모델을 선택하므로, 저렴하면서도 강력한 모델들을 같은 흐름에 배치할 수 있습니다.
모델 제공자(Model Provider) 페이지의 Default Models 아래에서 System Reasoning Model을 작업 공간 기본값으로 설정하세요.

대안: Claude용 Anthropic 플러그인

Anthropic 플러그인을 설치하고 설정을 엽니다.
API Key는 사용자의 키로, API URL은 https://api.apivai.com으로 설정합니다. /v1을 추가하지 마세요. 플러그인의 Anthropic 클라이언트가 자체적으로 /v1/messages를 추가하기 때문입니다. Enable request metadata는 'Disabled' 상태로 두세요.
플러그인에 내장된 모델 목록 중 일부 ID(예: claude-sonnet-4-6)는 게이트웨이의 ID와 일치하지만, 다른 모델들은 이름이 다르거나 구 버전일 수 있습니다. 만약 모델이 누락되었거나

Question Classifier 노드, 추출(extraction), 대용량 Q&A: claude-haiku-4-5 또는 gpt-6-luna
챗봇 및 에이전트의 기본값: claude-sonnet-4-6
도구가 많거나 긴 문서를 다루는 에이전트: claude-sonnet-5-5
가장 복잡한 추론(reasoning) 노드만 처리할 때: claude-opus-5-5

라우팅 워크플로우(A routing workflow, 저렴한 모델이 먼저 분류하고 어려운 케이스를 강력한 모델에 전달하는 방식)는 Dify 비용을 낮게 유지하는 가장 일반적인 방법입니다.

일반적인 오류 (Common errors)

Credentials validation fails on save / 401: 키가 불완전하거나 삭제된 경우입니다. 또한 API Base URL에 /v1이 정확히 한 번만 포함되어 있는지 확인하세요.
402 / insufficient_quota: 키의 예산이 소진되었거나, 남은 금액이 고비용 모델(Opus, Sonnet 4.6 등) 요청 하나를 처리하기에는 너무 적은 경우입니다 (Opus, Sonnet 4.6가 먼저 이 오류를 발생시킵니다). 키에 예산을 추가하거나 해당 노드를 더 저렴한 모델로 옮기세요. 키에 약간의 잔액이 남아 있어도 작동하지 않을 수 있습니다. 그 잔액은 손실되지 않으며, 키를 삭제하면 계정 잔액으로 돌아옵니다.
404: OpenAI-API 호환 방식은 /chat/completions 없이 https://api.apivai.com/v1이 필요하며, Anthropic 플러그인은 /v1 없이 https://api.apivai.com이 필요합니다.
Model not found: Model Name에 ID 대신 표시 이름(display name)이 포함되어 있거나, Anthropic 플러그인의 내장 목록에서 오래된 이름을 사용한 경우입니다.
Empty or cut-off answers: 앱의 Max Tokens가 너무 낮은 경우입니다 (사고 과정은 출력 토큰을 사용합니다). 이를 4096 이상으로 높이고 Upper bound for max tokens도 충분히 높은지 확인하세요.
The agent never calls tools: Function Call Type이 Tool Call로 설정되지 않은 경우입니다.
Knowledge base errors: 지식 기반(knowledge base)은 임베딩 모델을 필요로 하지만, APIVAI는 임베딩을 제공하지 않습니다. 별도의 임베딩 공급자(embedding provider)를 설정해야 합니다. 답변을 작성하는 LLM은 여전히 Claude 또는 GPT일 수 있습니다.
429: 각 키는 분당 60회 요청과 동시에 5개의 요청을 허용합니다 (추가 요청은 일정 시간 동안 대기열에 머뭅니다). 바쁜 앱의 경우, 각 앱마다 별도의 키를 할당해 주세요.

비용 (What it costs)

작성 시점 기준, APIVAI의 대부분 Claude 모델은 Anthropic의 공식 가격 대비 56–62% 저렴하며, GPT 모델은 OpenAI의 공식 가격 대비 최대 86% 저렴합니다. 예를 들어, Claude Sonnet 4.6은 입력/출력 토큰 백만 개당 $1.26 / $6.32로, 공식 가격인 각각 $3 / $15와 비교됩니다. 이 서비스는 구독 방식이 아닌 선불(prepaid)이며 토큰 단위로 청구됩니다. 전체 표는 https://apivai.com/pricing에서 확인할 수 있습니다.

댓글을 통해 질문해 주셔도 좋습니다.