Dify

필수 필드 하나 — OpenAI-API-compatible 플러그인의 Add Model 양식에 있는 API Base URL — 로 Dify 작업 공간의 모든 LLM 노드를 Kunavo에 연결합니다

# Integrations → Model Provider → OpenAI-API-compatible → Add Model
Type                          LLM
Model Name                    claude-sonnet-5
Model display name            Kunavo · Claude Sonnet 5
API Key                       sk-kn-...
API Base URL                  https://api.kunavo.com/v1
model name for API endpoint   (leave blank — Model Name is already the id)
Completion mode               Chat
Model context size            1000000
Upper bound for max tokens    (your own ceiling for one reply)
Function Call Type            Tool Call     # defaults to no_call
Vision Support                Support       # only if you will send images
Structured Output             Support       # defaults to not supported

# Model context size is per model, not per endpoint: 1000000 is
# claude-sonnet-5's. The table below carries the rest.

단계별 안내

1. /app/keys에서 키를 생성해 복사하세요. 키는 한 번만 표시됩니다.
2. Dify에서 Integrations → Model Provider를 열고 Install model providers(또는 Marketplace)에서 langgenius가 게시한 OpenAI-API-compatible을 찾아 설치합니다. Dify 문서에 따르면 워크스페이스 소유자와 관리자만 공급자를 관리할 수 있습니다.
3. 해당 공급자 카드에서 Add Model을 클릭합니다. 이 플러그인은 미리 정의된 모델을 제공하지 않는 customizable-model 공급자이므로 원하는 각 ID를 별도 항목으로 추가해야 합니다.
4. 위와 같이 양식을 작성합니다. Type = LLM, Model Name = Kunavo ID를 정확히 입력, API Key = 본인의 sk-kn- 키, API Base URL = https://api.kunavo.com/v1, Completion mode = Chat, Model context size = 아래 표의 값으로 지정합니다. 그런 다음 Function Call Type을 설정하고, 필요하면 Structured Output 및 Vision Support도 설정합니다. 저장합니다.
5. 워크플로를 열고 해당 모델을 사용할 노드에서 모델을 선택합니다. Dify는 앱별이 아니라 노드별로 모델을 지정하므로 분류기와 최종 작성 노드가 서로 다른 ID와 가격을 사용할 수 있습니다. 모델을 지정하지 않은 앱과 노드는 Default Models → System Reasoning Model로 대체됩니다.
6. 범위를 제한한 워크플로를 하나 실행한 다음, 아래 비용 표시 참고 사항을 확인하고 Dify가 아니라 Kunavo 계정에서 요금을 확인합니다.

Dify의 OpenAI-API-compatible 플러그인 페이지에서 확인했습니다(2026년 9월 21일 기준). 서드파티 설정은 변경될 수 있으므로, 여기의 필드 이름이 실제 화면과 다르면 이 문서가 아니라 해당 페이지를 기준으로 삼으세요.

클라이언트를 디버깅하기 전에 확인할 사항

한 번의 요청으로 문제가 엔드포인트, 키 또는 구성 파일 중 어디에 있는지 판단할 수 있습니다. 이 요청에서 JSON이 반환되면 동일한 base URL과 키가 Dify에서 작동합니다.

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer sk-kn-..."

필드에 입력할 model id

모든 텍스트 모델은 model id로 접근할 수 있습니다. 현재 목록은 GET /v1/models이며, 가격이 포함된 카탈로그는 모델 페이지에서 확인할 수 있습니다. 요금은 토큰 100만 개당 USD 기준이며 입력 / 출력 순서입니다.

“Dify API”라고 불리는 것은 서로 다른 두 가지입니다.

이 페이지는 그중 하나를 다루며, 검색 결과에서는 두 가지가 계속 혼재됩니다.

1. Dify에 모델 연결 — 위 설정 블록에서 다루는 내용입니다. 클라이언트는 Dify이고 엔드포인트는 Kunavo이며, 입력하는 자격 증명은 sk-kn- 키입니다. 그러면 해당 워크스페이스의 모든 앱에 있는 모든 LLM 노드에서 추가한 ID를 사용할 수 있습니다.
2. 자신의 코드에서 Dify 앱 호출 — 게시된 앱을 위해 Dify가 제공하는 Service API이며, Dify가 발급하는 자체 app- 키를 사용합니다. 그 키는 Dify의 키이지 Kunavo의 키가 아니며, 다른 곳을 가리키도록 할 수 없습니다. 이 방향의 호출에는 Kunavo가 관여하지 않습니다.

두 방식은 같은 앱에서 동시에 실행할 수 있으며, 보통 그렇게 사용합니다. 백엔드는 Dify 키로 Dify 앱을 호출하고, 앱의 노드는 Kunavo 키로 Kunavo를 호출합니다. 키 두 개, 청구서 두 개이며, 401 오류가 발생하면 두 곳을 확인해야 합니다.

Dify에 추가한 모델의 비용이 표시되지 않는 이유

Dify의 자체 미리 정의된 모델 파일에는 입력 및 출력 요금과 토큰당 단위가 포함된 가격 블록이 있습니다. Dify는 이를 토큰 수에 곱해 로그에 금액을 표시합니다. 위 날짜에 확인한 OpenAI-API-compatible 공급자 스키마에는 가격, 단위 또는 통화 필드가 어디에도 선언되어 있지 않습니다. 따라서 이 플러그인으로 추가한 모델에는 Dify가 곱할 요금이 없습니다. 비용 열에 표시되지 않는 것은 할인을 찾았거나 오류를 만든 결과가 아니라, 해당 필드 자체가 없기 때문입니다. 실제 금액은 Kunavo 사용량에서 확인하고, Dify의 토큰 수는 토큰 수로 확인하세요.

그대로 두는 것이 좋은 관련 스위치가 하나 있습니다. Include Usage in Stream은 기본적으로 활성화되어 있으며, 최종 스트림 청크에 프롬프트 및 완성 토큰 수를 포함하도록 엔드포인트에 요청합니다. 이 설정을 끄면 토큰 수도 받지 못하게 됩니다.

Dify를 자체 호스팅하는 경우

Docker Compose 스택은 아웃바운드 요청을 ssrf_proxy 서비스로 라우팅하므로, 엔드포인트는 노트북 브라우저에서만 연결되는 것이 아니라 컨테이너 네트워크 내부에서도 연결 가능해야 합니다. 한쪽에서는 작동하고 다른 쪽에서는 시간 초과되는 구성은 대개 이 문제이며, 자격 증명이 아니라 네트워킹 문제입니다. 위의 curl를 컨테이너 내부에서 실행하면 바로 확인할 수 있습니다.