러시아에서 Dify 사용하기: OpenAI 호환 API와 첫 워크플로

Dify는 공식 모델 프로바이더 OpenAI-API-compatible를 통해 외부 API를 연결할 수 있습니다. 본인의 API Key, 호환되는 Base URL, 현재 Model ID가 필요합니다. 설정을 검증하려면 텍스트 입력, LLM 노드 하나, 텍스트 출력으로 구성된 워크플로를 만들고 한 번 실행한 후 결과를 프로바이더 기록과 대조하세요.

이 workflow에 본인의 API Key가 필요하신가요? BetterToken 계정 만들기

외부 동작 없이 워크플로 하나로 Dify를 시험하려면 별도의 BetterToken 테스트 Key를 사용하고 최신 Dify 가이드를 여세요. 이 가이드는 모델 API 연결을 다룹니다. Dify 설치, Marketplace, 서드파티 플러그인, Agent, Tool은 별도 계층입니다.

준비할 항목

• 정상 동작하는 Dify Cloud 또는 자체 호스팅 Dify 설치 환경;
• Integrations/Marketplace 및 Model Providers 접근 권한;
• 본인의 BetterToken API Key;
• BetterToken model plaza의 현재 Model ID;
• Tool과 외부 동작이 없는 새 테스트 워크플로.

러시아에서는 VPN 없이 BetterToken API Endpoint에 연결할 수 있습니다. 이는 Dify Cloud, Marketplace, GitHub, Docker registry 또는 서드파티 플러그인의 이용 가능성을 보장하는 뜻은 아닙니다.

1. 공식 프로바이더 설치

Dify에서 Integrations 또는 Marketplace를 열고 Model Providers로 이동하세요. 공식 OpenAI-API-compatible 프로바이더를 찾아 아직 사용할 수 없다면 설치합니다.

Dify 공식 Marketplace에서 작성자와 목록을 확인하세요. 비슷한 이름의 임의 플러그인을 사용하지 마세요. 필드와 credential 처리 방식이 다를 수 있습니다.

2. BetterToken 모델 추가

프로바이더 설정을 열고 새 LLM 모델을 추가합니다. 다음 값을 입력하세요.

1. Model Type: LLM.
2. Model Name / ID: 정확한 현재 Model ID.
3. API Key: 본인의 BetterToken API Key.
4. API Base URL: https://www.bettertoken.ai/v1.
5. Completion mode: 선택한 프로바이더와 모델이 요구하는 경우 Chat.

Base URL에 /chat/completions를 직접 붙이지 마세요. 전체 경로는 프로바이더가 구성합니다. 실제 credential을 앱 내보내기, 스크린샷 또는 issue에 복사해서는 안 됩니다.

UI가 context size, max tokens, vision 또는 streaming 매개변수를 요구한다면 현재 모델 문서에 있는 값만 사용하세요. 첫 테스트에는 추가 기능이 필요하지 않습니다.

3. credential 저장 및 검증

Dify는 저장할 때 credential을 검증합니다. 이는 프로바이더가 인증 절차를 완료할 수 있었음을 보여줄 뿐, 전체 워크플로가 검증되었다는 뜻은 아닙니다.

오류가 발생하면 다음의 안전한 진단 정보만 보관하세요.

• 프로바이더 이름과 버전;
• Model ID;
• Key를 제외한 Base URL;
• 짧은 오류 유형과 HTTP status;
• 시도한 시간.

API Key나 민감한 전체 응답을 저장하지 마세요.

4. 최소 워크플로 만들기

Workflow 유형의 새 애플리케이션을 만듭니다. 다음 세 요소만 추가하세요.

1. question이라는 텍스트 변수가 있는 Start.
2. 추가한 BetterToken 모델을 사용하는 LLM.
3. LLM의 응답 텍스트가 나오는 End.

LLM에는 다음과 같은 간단한 prompt template을 사용하세요.

한 줄로 답하세요. 입력: {{question}}

Start → LLM → End 순으로 연결합니다. HTTP Tool, 데이터베이스, knowledge retrieval, Agent loop, 게시 기능은 추가하지 마세요. 첫 실패 원인을 분리하기 어려워집니다.

5. 한 번 테스트 실행

다음 입력을 전달합니다.

2 + 2의 합으로 DIFY_OK와 숫자 4를 반환하세요.

다음 조건이 충족되면 설정이 확인된 것입니다.

• Dify가 예상한 텍스트 출력을 표시합니다;
• LLM 노드가 credential, model 또는 endpoint 오류 없이 완료됩니다;
• BetterToken Dashboard에 예상 모델과 status를 가진 기록이 표시됩니다;
• Dashboard에 input, output, 해당되는 cache token 및 관련 청구가 표시됩니다.

Dify 실행과 Dashboard를 대조하면 워크플로가 모르는 사이 다른 프로바이더나 모델을 사용한 경우를 배제할 수 있습니다.

오류 구분하기

프로바이더 또는 플러그인이 설치되지 않음

이 문제는 Dify Marketplace/plugin-daemon 계층에 속합니다. 자체 호스팅 환경에서는 Dify 버전, plugin daemon의 네트워크 접근, HTTPS, 인증서 체인을 확인하세요. BetterToken API Key를 바꿔도 해결되지 않습니다.

ToolProviderCredentialValidationError 또는 401

Key를 다시 입력하고 공백을 확인한 뒤 선택한 프로바이더를 검토하세요. credential이 관련 없는 Tool 플러그인이 아니라 모델에 속하는지 확인해야 합니다.

404

Base URL을 확인하세요.

https://www.bettertoken.ai/v1

필드가 API Base URL을 기대한다면 직접 추가한 /chat/completions를 제거하세요.

model not found

model plaza에서 현재 ID를 복사하세요. 이 ID가 새로 만든 Key와 선택한 OpenAI 호환 프로바이더에서 사용 가능한지 확인합니다.

credential은 저장되지만 워크플로가 실패함

LLM 노드만 따로 테스트하세요. Tool, streaming, structured output을 제거한 뒤 짧은 텍스트 입력/텍스트 출력 실행을 다시 시도합니다. 성공하면 추가 노드를 하나씩 복원하세요.

이 설정의 범위

첫 워크플로는 공식 OpenAI-API-compatible 프로바이더를 통한 모델 요청 한 건을 확인합니다. 모든 Dify Agent, 커뮤니티 플러그인, Tool, 외부 서비스와의 호환성을 증명하지는 않습니다. 부작용이 있는 모든 동작에는 별도 테스트를 만들고 명시적인 사용자 확인을 요구하세요.

현재 필드와 제한은 Dify용 BetterToken Docs에서 확인할 수 있습니다. 동적인 Model ID와 가격은 설정하는 당일에 확인하세요.