LLM 제공업체 개요
Elftia의 LLM 제공업체 시스템을 사용하면 여러 대형 언어 모델 서비스에 연결하고, 통합 API 추상화를 통해 기반 API 형식의 차이를 신경 쓰지 않고 제공업체 간에 원활하게 전환할 수 있습니다.
사용 시나리오
- 새로운 LLM 서비스(OpenAI, Anthropic, DeepSeek 등)에 연결해야 할 때
- 동일한 애플리케이션 내에서 여러 제공업체의 모델을 사용하고 싶을 때
- 로컬에 배포된 모델(Ollama 또는 LM Studio 등)에 연결해야 할 때
- API 키 풀링을 통해 고가용성 및 부하 분산을 실현하고 싶을 때
핵심 개념
제공업체 (Provider)
제공업체는 LLM API 서비스의 구성 단위입니다. 각 제공업체에는 다음과 같은 핵심 정보가 포함됩니다:
| 개념 | 설명 | 예시 |
|---|---|---|
| 이름 | 제공업체의 표시 이름 | OpenAI, DeepSeek, Zhipu GLM |
| API 형식 | 제공업체가 사용하는 API 프로토콜 형식 | openai, anthropic, google |
| Base URL | API 요청의 기본 주소 | https://api.openai.com/v1/chat/completions |
| API 키 | 인증 자격 증명 | sk-... 또는 $OPENAI_API_KEY 같은 환경 변수 참조 |
| 모델 목록 | 해당 제공업체에서 사용 가능한 모델 | gpt-4o, claude-sonnet-4-5, gemini-3-pro |
API 형식
Elftia는 5가지 API 형식을 지원하며, 내장된 형식 변환기(Transformer)를 사용해 요청 및 응답 형식 차이를 자동으로 처리합니다:
| API 형식 | 설명 | 사용 제공업체 |
|---|---|---|
openai | OpenAI Chat Completions 형식 (/v1/chat/completions) | OpenAI, DeepSeek, Zhipu, Ollama, Groq 및 대부분의 기타 제공업체 |
anthropic | Anthropic Messages 형식 (/v1/messages) | Anthropic 공식, MiniMax |
google | Google Gemini 형식 | Google Gemini |
azure-openai | Azure OpenAI 형식 (OpenAI와 동일, 인증 방식 상이) | Azure OpenAI Service |
openai-response | OpenAI Responses API 형식 (/v1/responses) | OpenAI 신규 Responses API |
모델 (Model)
각 제공업체 아래에 여러 모델을 구성할 수 있습니다. 모델 구성에는 다음이 포함됩니다:
- 모델 ID: API 호출 시 사용되는 식별자 (예:
gpt-4o) - 표시 이름: UI에 표시되는 이름 (예:
GPT-4o) - 카테고리: chat, reasoning, code, image 등
- 기능 플래그: 비전, 함수 호출, 추론 모드, 웹 검색 지원 여부
- 컨텍스트 길이: 모델이 지원하는 최대 입력 토큰 수
- 최대 출력: 모델이 한 번의 응답에서 생성할 수 있는 최대 토큰 수
API 키
API 키는 제공업체 서비스에 접근하기 위한 인증 자격 증명입니다. Elftia는 두 가지 API 키 구성 방식을 지원합니다:
- 직접 입력: 설정 UI에 API 키를 직접 붙여넣기
- 환경 변수 참조: 이름 앞에
$를 붙여 시스템 환경 변수를 참조 (예:$OPENAI_API_KEY) — 애플리케이션 구성에 키를 저장하지 않으려는 경우 유용
요청 처리 흐름
사용자가 메시지를 보내면 Elftia는 다음과 같이 요청을 처리합니다:
사용자가 메시지 전송
|
v
제공업체 및 모델 선택
|
v
API 키 결정 (직접 값 / 환경 변수 / 키 풀)
|
v
Transformer: 통합 요청을 대상 API 형식으로 변환
| (openai / anthropic / google / ...)
v
제공업체 API에 요청 전송
|
v
Transformer: 제공업체 응답을 통합 형식으로 변환
|
v
채팅 UI에 응답 렌더링
기본 제공업체 목록
Elftia는 다음 제공업체 템플릿을 기본으로 제공하며, 첫 실행 시 자동으로 생성됩니다 (기본적으로 비활성화 — API 키를 입력하고 활성화해야 사용 가능):
| 제공업체 | API 형식 | Base URL | 특징 |
|---|---|---|---|
| DeepSeek | openai | https://api.deepseek.com/v1 | 뛰어난 가성비, 추론 모드 지원 |
| OpenRouter | openai | https://openrouter.ai/api/v1 | 200개 이상의 모델 집계, 통합 청구 |
| SiliconFlow | openai | https://api.siliconflow.cn/v1 | 중국 내 가속 접속, 오픈소스 모델 호스팅 |
| OpenAI | openai | https://api.openai.com/v1/chat/completions | GPT 시리즈, o-시리즈 추론 모델 |
| Anthropic | anthropic | https://api.anthropic.com/v1/messages | Claude 시리즈, 네이티브 chain-of-thought |
| Google Gemini | https://generativelanguage.googleapis.com/v1beta/models/ | 초장문 컨텍스트 (100만 토큰) | |
| Zhipu GLM | openai | https://api.z.ai/api/paas/v4 | GLM 시리즈, Coding Plan 지원 |
| Moonshot (Kimi) | openai | https://api.moonshot.ai/v1 | Kimi K2.5, 초장문 컨텍스트 |
| Alibaba Cloud Bailian | openai | https://dashscope.aliyuncs.com/compatible-mode/v1 | Qwen 시리즈, 100만 토큰 |
| Ollama | openai | http://localhost:11434/v1 | 로컬 배포, 완전 오프라인 |
| Groq | openai | https://api.groq.com/openai/v1 | 초고속 추론, 낮은 지연 |
| Claude Code | anthropic | https://api.anthropic.com/v1/messages | Claude Agent SDK 통합 |
위의 기본 목록 외에도, Elftia는 더 많은 중국 클라우드 플랫폼(Volcengine, Tencent Cloud Hunyuan, Baidu Qianfan, MiniMax, Kuaishou KwaiKAT, Moore Threads 등)을 위한 사전 설정 템플릿을 제공하며, "제공업체 추가" 대화상자에서 확인할 수 있습니다.
구성 참조
| 설정 | 유형 | 기본값 | 설명 |
|---|---|---|---|
| 제공업체 이름 | 문자열 | (템플릿 이름) | 표시 이름, 사용자 정의 가능 |
| API 형식 | 열거형 | openai | openai / anthropic / google / azure-openai / openai-response |
| Base URL | URL | (템플릿마다 다름) | API 요청 주소 |
| API 키 | 문자열 | (비어 있음) | 환경 변수 참조를 위한 $ 접두사 지원 |
| 모델 목록 | 배열 | (템플릿마다 다름) | 수동으로 추가하거나 모델 검색으로 가져올 수 있음 |
| 활성화 여부 | 불리언 | false | 제공업체가 모델 선택 목록에 표시될지 여부 |
| Transformer | 객체 | (형식마다 다름) | 요청/응답 형식 변환기 구성 |
| 기본 파라미터 | 객체 | temperature: 0.7 | 제공업체 수준의 기본 생성 파라미터 |
| API 타임아웃 | 밀리초 | (전역 설정) | 단일 요청의 타임아웃 |
| 동시 요청 제한 | 숫자 | (제공업체마다 다름) | Agent 모드에서의 최대 동시 요청 수 |
동작 참고 사항
제공업체 활성화 및 비활성화
- 비활성화된 제공업체는 모델 선택 드롭다운에 표시되지 않습니다
- 제공업체를 비활성화해도 구성이 삭제되지 않으며, 다시 활성화하면 모든 설정이 유지됩니다
- 현재 세션에서 사용 중인 모델의 제공업체를 비활성화하더라도 기존 세션에는 영향이 없지만, 새 메시지에서는 해당 모델을 사용할 수 없습니다
모델 검색 (Model Discovery)
일부 제공업체는 모델 검색을 지원합니다: Elftia가 제공업체의 모델 목록 API(예: /v1/models)를 호출하여 사용 가능한 모델을 자동으로 가져옵니다. 모델 검색을 지원하는 제공업체로는 OpenAI, Anthropic, Gemini, Zhipu 등이 있습니다.
환경 변수 API 키
API 키가 $로 시작하면, Elftia는 런타임에 시스템 환경 변수에서 실제 값을 읽습니다. 예를 들어:
- 구성값
$OPENAI_API_KEY→ 런타임에process.env.OPENAI_API_KEY읽기 - 환경 변수가 존재하지 않으면 인증 오류로 요청이 실패합니다
형식 변환기 (Transformer)
Transformer는 Elftia의 다중 API 형식 지원의 핵심 메커니즘입니다. OpenAI 형식이 아닌 형식을 사용하는 모든 제공업체에는 해당 변환기가 할당됩니다:
| 제공업체 유형 | Transformer | 용도 |
|---|---|---|
| Anthropic 공식 | anthropic | Anthropic Messages 형식 유지, chain-of-thought 처리 |
| Google Gemini | gemini | 요청을 Gemini 형식으로 변환 |
| OpenAI Responses | openai-response | /v1/responses 엔드포인트에 적응 |
| OpenRouter | openrouter | 제공업체 라우팅 구성 처리 |
| DeepSeek | deepseek | DeepSeek 전용 추론 필드 처리 |
| Groq | groq | Groq의 파라미터 제약에 적응 |
문제 해결
| 문제 | 가능한 원인 | 해결 방법 |
|---|---|---|
| 제공업체가 모델 선택 목록에 없음 | 제공업체가 비활성화됨 | 제공업체 설정으로 이동하여 토글을 활성화 |
| 요청이 401 오류 반환 | API 키가 유효하지 않거나 만료됨 | API 키를 확인하고 업데이트; 키에 충분한 할당량이 있는지 확인 |
| 요청이 403 오류 반환 | API 키에 권한 없음 | API 키가 선택한 모델에 대한 접근 권한을 가지고 있는지 확인 |
| 환경 변수 키가 유효하지 않음 | 환경 변수 이름이 잘못되었거나 설정되지 않음 | 환경 변수가 시스템에 설정되어 있는지 확인하고 Elftia를 재시작 |
| 요청 타임아웃 | 네트워크 연결 없음 또는 제공업체 서비스 중단 | 네트워크 연결 확인, Base URL이 올바른지 검증, 프록시 사용 시도 |
| 모델 목록이 비어 있음 | 제공업체가 모델 검색을 지원하지 않거나 키가 유효하지 않음 | 모델을 수동으로 추가하거나 API 키가 올바른지 확인 |
| 응답 형식이 비정상적 | Transformer 구성 불일치 | API 형식 선택이 올바른지 확인; 특정 Transformer가 필요한지 확인 |
| 중국 제공업체 연결 느림 | 네트워크 지연 | 올바른 국내 Base URL을 사용하고 있는지 확인; 프록시 설정 확인 |
관련 페이지
- 제공업체 추가 - 사전 설정 템플릿 또는 사용자 정의 구성으로 새 제공업체 추가
- API 키 풀 - 다중 키 부하 분산 및 자동 장애 조치
- 사용자 정의 엔드포인트 - Ollama 및 LM Studio 같은 로컬 서비스 연결
- 모델 파라미터 - temperature 및 max_tokens 같은 생성 파라미터 구성