본문으로 건너뛰기

공급자 추가하기

공급자를 추가하면 다양한 LLM 서비스를 Elftia에 연결하고 대화 중에 모델을 자유롭게 전환할 수 있습니다. Elftia는 프리셋 템플릿, 사용자 지정 설정, 가져오기/내보내기의 세 가지 방법을 제공합니다.

사용 시점​

  • Elftia를 처음 설정할 때 기본 공급자를 활성화하기 위해 API 키를 구성해야 하는 경우
  • 기본 목록에 없는 LLM 서비스에 연결해야 하는 경우
  • 동일한 공급자의 여러 인스턴스를 추가하려는 경우 (예: 다른 지역의 엔드포인트)
  • 다른 기기에서 설정을 마이그레이션하는 경우

방법 1: 프리셋 템플릿으로 추가​

프리셋 템플릿에는 공급자의 Base URL, 기본 모델 목록, 권장 설정이 포함되어 있으므로 API 키만 입력하면 설정이 완료됩니다.

단계​

  1. 설정 → 공급자 관리 열기
  2. 공급자 추가 버튼 클릭
  3. 공급자 목록에서 프리셋 템플릿 선택
  1. 표시되는 설정 패널에서 API 키 입력
    • 키 값 직접 붙여넣기, 예: sk-xxxxxxxxxxxxxxxx
    • 또는 환경 변수 참조, 예: $OPENAI_API_KEY

  1. 연결 테스트 클릭으로 키 유효성 확인

    • 성공: 녹색 메시지 "연결 성공" 표시
    • 실패: 오류 메시지 표시 (문제 해결 참조)

  2. 활성화 토글 켜기

  3. 저장 클릭

완료되면 해당 공급자의 모델이 채팅 UI의 모델 선택 드롭다운에 나타납니다.

프리셋 템플릿 참고​

국제 공급자​

프리셋 ID이름API 형식Base URL특징
openaiOpenAIopenaihttps://api.openai.com/v1/chat/completionsGPT-4o/5, o1/o3 추론 시리즈, 비전 지원
anthropicAnthropicanthropichttps://api.anthropic.com/v1/messagesClaude Sonnet/Opus/Haiku 4.5, 네이티브 사고 연쇄
geminiGoogle Geminigooglehttps://generativelanguage.googleapis.com/v1beta/models/100만 토큰 컨텍스트, 비전 + 추론
openai-responseOpenAI (Responses API)openai-responsehttps://api.openai.comGPT-5 시리즈 + o3/o4, 새 API
azure-openaiAzure OpenAIazure-openai(사용자 지정)엔터프라이즈 SLA; 배포 이름을 모델로 사용
openrouterOpenRouteropenaihttps://openrouter.ai/api/v1단일 키로 200개 이상의 모델 통합
groqGroqopenaihttps://api.groq.com/openai/v1초고속 추론 엔진
ollamaOllamaopenaihttp://localhost:11434/v1로컬 배포, 무료 사용

중국 클라우드 플랫폼​

프리셋 ID이름API 형식Base URL특징
zhipuZhipu GLMopenaihttps://api.z.ai/api/paas/v4GLM-5/4.5/4.6V/4.7, Coding Plan
volcengineVolcengine (Ark)openaihttps://ark.cn-beijing.volces.com/api/v3Doubao Seed 2.0, 지능형 라우팅, 멀티모델 통합
kimiKimi (Moonshot)openaihttps://api.moonshot.ai/v1Kimi K2.5, 256K 컨텍스트
dashscopeAlibaba Cloud Bailianopenaihttps://dashscope.aliyuncs.com/compatible-mode/v1Qwen3 시리즈, 1M 토큰
tencentTencent Cloud Hunyuanopenaihttps://api.lkeap.cloud.tencent.com/v1Hunyuan 2.0, 멀티모델 통합
minimaxMiniMaxanthropichttps://api.minimaxi.com/anthropicM2.5/M2.1, Anthropic 형식
baiduBaidu Qianfanopenaihttps://qianfan.baidubce.com/v2ERNIE 시리즈, Coding Plan
kuaishouKuaishou KwaiKATopenaihttps://wanqing.streamlakeapi.com/api/gateway/v1KAT-Coder, 코딩 최적화
mthreadsMoore Threadsopenai(설정 필요)국산 칩 Coding Plan

방법 2: 사용자 지정 OpenAI 호환 공급자​

사용 중인 LLM 서비스가 OpenAI 호환 API를 제공하는 경우(대부분의 서비스가 지원), 사용자 지정 공급자로 추가할 수 있습니다.

단계​

  1. 설정 → 공급자 관리 열기
  2. 공급자 추가 → 사용자 지정 공급자 선택
  1. 기본 정보 입력:
필드필수설명예시
이름예표시 이름My Local LLM
API 형식예프로토콜 형식 선택openai (가장 일반적)
Base URL예API 주소http://localhost:8080/v1/chat/completions
API 키아니오인증 키sk-... (로컬 서비스는 비워도 됨)
  1. 모델 추가:
    • 모델 추가 클릭
    • 모델 ID 입력 (API 호출 시 사용되는 이름, 예: llama-3.1-70b)
    • 표시 이름 입력
    • 모델 기능 플래그 설정 (비전, 함수 호출, 추론 등)

  1. (선택 사항) Transformer 설정:

    • 대상 서비스의 API가 표준 OpenAI 형식과 다른 경우, 적절한 Transformer 추가
    • 일반적인 선택: deepseek (DeepSeek 호환 서비스), groq (Groq 호환 서비스)

  2. 연결 테스트 클릭으로 설정 확인

  3. 활성화 토글을 켜고 저장

모델 검색​

일부 공급자는 /v1/models 엔드포인트를 통한 자동 모델 검색을 지원합니다.

  1. 공급자 설정에서 모델 검색 엔드포인트 입력 (예: https://api.example.com/v1/models)
  2. 모델 검색 버튼 클릭
  3. Elftia가 엔드포인트를 호출하여 모델 목록 가져오기
  4. 반환된 결과에서 추가할 모델 선택

방법 3: 가져오기 / 내보내기​

설정 내보내기​

  1. 설정 → 공급자 관리 열기
  2. 내보낼 공급자 선택
  3. 내보내기 버튼 클릭
  4. 설정이 JSON 파일로 저장됨

설정 가져오기​

  1. 설정 → 공급자 관리 열기
  2. 가져오기 버튼 클릭
  3. 이전에 내보낸 JSON 파일 선택
  4. 가져온 공급자 정보 검토
  5. API 키 입력 (보안상의 이유로 내보내기 파일에는 API 키가 포함되지 않음)
  6. 저장 및 활성화

환경 변수 API 키​

환경 변수를 사용하여 API 키를 관리하는 것이 권장되는 방식이며, 특히 다음과 같은 경우에 유용합니다.

  • 키를 앱 데이터베이스에 평문으로 저장하고 싶지 않은 경우
  • 여러 기기에서 설정 파일을 공유하되 각 기기마다 다른 키를 사용하는 경우
  • CI/CD 또는 자동화 환경에서 Elftia를 사용하는 경우

설정 방법​

API 키 입력 필드에 $를 앞에 붙여 환경 변수 이름을 입력합니다.

입력 값런타임에 해석되는 값
$OPENAI_API_KEYprocess.env.OPENAI_API_KEY의 값
$ANTHROPIC_API_KEYprocess.env.ANTHROPIC_API_KEY의 값
$MY_CUSTOM_KEYprocess.env.MY_CUSTOM_KEY의 값

참고: 해당 환경 변수가 설정되지 않은 경우 API 요청이 인증 오류로 실패합니다. 환경 변수를 변경한 후에는 새 값이 적용되도록 Elftia를 재시작해야 합니다.

설정 참고​

설정유형기본값설명
이름문자열(템플릿 이름)공급자 표시 이름
API 형식열거형openaiopenai / anthropic / google / azure-openai / openai-response
Base URLURL(템플릿에 따라 다름)API 요청 주소; http:// 또는 https://로 시작해야 함
API 키문자열(비어 있음)$ 접두사로 환경 변수 참조 지원
모델 목록배열(템플릿에 따라 다름)추가, 삭제하거나 모델 검색으로 가져올 수 있음
모델 검색 엔드포인트URL(선택 사항)/v1/models 또는 유사한 엔드포인트를 호출하여 모델 목록 자동 가져오기
활성화Booleanfalse새로 추가된 공급자는 기본적으로 비활성화 상태
Transformer배열(형식에 따라 다름)요청/응답 형식 변환 체인
아이콘문자열(템플릿에 따라 다름)공급자 아이콘 식별자
웹사이트 링크URL(선택 사항)공급자의 웹사이트, 문서 링크에 사용
메모문자열(비어 있음)자유 형식 메모
API 버전문자열(Azure 전용)Azure OpenAI의 API 버전 번호
동시성 제한숫자(공급자에 따라 다름)Agent 모드의 최대 동시 요청 수
공식 여부Booleanfalse공급자를 공식 Anthropic 공급자로 표시 (사고 연쇄 서명 처리에 영향)

동작 안내​

프리셋 템플릿 vs. 사용자 지정 공급자​

기능프리셋 템플릿사용자 지정 공급자
Base URL자동 입력직접 입력해야 함
모델 목록미리 설정됨직접 추가해야 함
Transformer자동 설정됨선택 사항
모델 검색일부 지원엔드포인트 직접 설정 필요
Coding Plan일부 지원지원 안 함
검색 통합미리 설정됨직접 설정해야 함

공급자 ID 고유성​

각 공급자는 고유한 ID를 가집니다. 동일한 프리셋 템플릿에서 여러 인스턴스를 추가할 경우, Elftia가 ID에 자동으로 접미사를 추가하여 고유성을 보장합니다.

추가 후 초기 상태​

새로 추가된 공급자는 기본적으로 비활성화 상태입니다. 다음 단계를 완료해야 합니다.

  1. 유효한 API 키 입력
  2. 연결 테스트 성공
  3. 토글을 수동으로 활성화

그래야만 해당 공급자의 모델을 채팅에서 사용할 수 있습니다.

Troubleshooting​

문제가능한 원인해결 방법
연결 테스트 401 반환API 키가 유효하지 않거나 만료됨공급자 웹사이트에서 키 재발급
연결 테스트 403 반환키에 권한 없음키가 대상 모델에 접근 권한이 있는지 확인
연결 테스트 시간 초과네트워크 연결 없음 또는 잘못된 Base URL네트워크 연결 및 URL 철자 확인
$ENV_VAR 키가 유효하지 않음환경 변수가 설정되지 않음시스템에서 환경 변수를 설정하고 Elftia 재시작
모델 검색이 빈 목록 반환잘못된 엔드포인트 또는 키에 권한 없음모델 검색 엔드포인트 URL 확인; 키에 모델 목록 조회 권한이 있는지 확인
URL 오류로 저장 실패Base URL 형식이 잘못됨http:// 또는 https://로 시작하는지 확인
사용자 지정 공급자 요청 실패Transformer 설정 불일치API 형식 선택이 올바른지 확인하거나 해당 Transformer 추가 시도
Azure OpenAI 연결 실패잘못된 API 버전 또는 배포 이름API Version 필드가 입력되었는지 확인 (예: 2024-08-01-preview); 배포 이름을 모델 이름으로 사용
MiniMax 요청 형식 오류anthropic 형식을 사용하지 않음MiniMax는 Anthropic API 형식을 사용하므로 anthropic을 선택하고 anthropic Transformer 설정

관련 페이지​