Providers Guide: Connect AI Models to OmniRoute (한국어)

공급자란 무엇인가요?

공급자를 이동통신사와 비슷하다고 생각해 보세요. 전화를 걸려면 이동통신사가 필요한 것처럼, AI 모델을 사용하려면 AI 공급자가 필요합니다. OmniRoute는 모든 이동통신사와 호환되는 전화기와 같습니다. 즉, 공급자를 자동으로 전환할 수 있습니다.

공급자 유형

유형	설명	예시	비용
무료	결제가 필요하지 않음	Kiro, OpenCode Free, Pollinations	$0
API 키	API 키가 필요함	OpenAI, Anthropic, Google	사용량에 따라 결제
OAuth	계정으로 로그인	Claude Code, GitHub Copilot	구독
웹 쿠키	브라우저 세션을 사용	ChatGPT Web (Codex), Gemini Web	$0 (사용자 계정 사용)

웹 쿠키 공급자

일반적인 설정 방법, 제한 사항, 문제 해결 및 공급자별 인증 지침은 **WEB-COOKIE-GUIDE.md**를 참조하세요.

빠른 시작: 첫 번째 공급자 연결하기

선택 사항인 최초 실행 무료 공급자 설정

최초 실행 마법사는 명시적인 무료 공급자 설정 카드를 제공합니다. OmniRoute의 인증 불필요 공급자 레지스트리에서 현재 사용 가능한 목록을 가져온 다음, 확인하기 전에 각 공급자를 검토하고 선택 해제할 수 있게 해줍니다. OmniRoute는 공급자의 주의 사항과 해당 사이트 링크를 표시하므로 먼저 서드 파티 약관, 개인정보 보호, 가용성 및 사용량 제한을 검토할 수 있습니다.

이 작업은 선택 사항입니다. 마법사를 완료해도 무료 공급자 연결이 자동으로 생성되지 않습니다. 아직 추가되지 않은 공급자만 생성하고, 기존에 사용자 지정된 연결은 변경하지 않으며, 생성된 공급자, 이미 구성된 공급자, 실패한 공급자를 개별적으로 보고합니다. 일부만 처리된 경우 실패한 항목만 안전하게 다시 시도할 수 있습니다.

옵션 A: 무료 공급자(신용카드 불필요)

1. http://localhost:20128에서 대시보드를 엽니다
2. 공급자 → 공급자 추가로 이동합니다
3. 다음 무료 공급자 중 하나를 선택합니다:
   • Kiro AI — 무료 Claude 모델(인증 불필요)
   • OpenCode Free — 무료 GPT 모델(인증 불필요)
   • Pollinations — 무료 GPT-5, Claude, Gemini(키 불필요)
   • LongCat — 10M 토큰 무료(일회성 제공, 계정 + KYC 필요)
   • Cloudflare AI — 50개 이상의 모델, 일일 10K 뉴런
   • MLX Gemma 26B — 로컬 Apple Silicon 모델(~38.5 tok/s, ~15.9GB RAM)
   • MLX Qwen 3.8 27B — 로컬 Apple Silicon 모델(~9.1 tok/s, ~13.1GB RAM)
4. 연결을 클릭합니다
5. 완료되었습니다! 이제 AI를 무료로 사용할 수 있습니다.

옵션 B: API 키 공급자(유료)

1. 공급자 웹사이트에서 API 키를 발급받습니다:
   • OpenAI: https://platform.openai.com/api-keys
   • Anthropic: https://console.anthropic.com/
   • Google: https://aistudio.google.com/apikey
   • DeepSeek: https://platform.deepseek.com/
   • Groq: https://console.groq.com/
2. http://localhost:20128에서 대시보드를 엽니다
3. 공급자 → 공급자 추가로 이동합니다
4. 공급자를 선택합니다
5. API 키를 붙여넣습니다
6. 연결을 클릭합니다
7. 완료되었습니다! 이제 해당 공급자의 모델을 사용할 수 있습니다.

옵션 C: OAuth 공급자(구독)

1. http://localhost:20128에서 대시보드를 엽니다
2. 공급자 → 공급자 추가로 이동합니다
3. 공급자를 선택합니다(예: Claude Code, GitHub Copilot)
4. OAuth로 연결을 클릭합니다
5. 계정으로 로그인합니다
6. 완료되었습니다! 이제 구독 모델을 사용할 수 있습니다.

옵션 D: 로컬 MLX 모델(Apple Silicon)

통합 메모리를 사용하는 Apple Silicon Mac의 경우, OmniRoute는 mlx-lm.server를 통해 실행되는 로컬 MLX 모델을 일반적인 OpenAI 호환 로컬 공급자로 연결할 수 있도록 지원합니다.

사전 요구 사항

• 24GB 이상의 통합 메모리가 권장되는 Apple Silicon Mac(M1/M2/M3/M4)
• uv 패키지 관리자: curl -LsSf https://astral.sh/uv/install.sh | sh
• mlx-lm: uv pip install mlx-lm

빠른 시작

1. 종속성 설치:

   # 아직 설치하지 않았다면 uv 설치
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # mlx-lm 설치
   uv pip install mlx-lm

2. MLX 서버 수동 시작(각각 별도의 터미널에서):

   # 터미널 1: Gemma 4 26B A4B IT-QAT(포트 11435)
   uv run mlx_lm.server --model mlx-community/gemma-4-26B-A4B-it-qat-q4_0-mlx-aligned --port 11435 --host 127.0.0.1
   
   # 터미널 2: Qwen 3.8 27B MLX Mixed(포트 11436)
   uv run mlx_lm.server --model maglun/Qwen3.8-27B-MLX-Mixed-3.80bpw --port 11436 --host 127.0.0.1

3. OmniRoute 대시보드에서 연결:

   • 공급자 → 공급자 추가로 이동합니다
   • MLX Gemma 26B 또는 MLX Qwen 3.8 27B를 선택합니다
   • 연결을 클릭합니다(API 키 불필요)

4. OpenCode와 함께 사용:

   # OmniRoute를 사용하도록 OpenCode 구성
   opencode config set api.base_url http://localhost:20128/v1
   opencode config set api.key <your-omniroute-api-key>
   
   # MLX 모델 사용
   opencode run --model mlx-gemma/gemma-4-26b
   opencode run --model mlx-qwen/qwen3.8-27b

메모리 관리

중요: 통합 메모리가 24GB인 경우, 대규모 MLX 모델은 한 번에 하나만 실행할 수 있습니다.

• Gemma 26B: 최대 메모리 약 15.9GB
• Qwen 3.8 27B: 최대 메모리 약 13.1GB

이를 수동으로 관리해야 합니다:

• 한 번에 하나의 MLX 서버만 실행하거나
• 각각 별도의 머신에서 실행하거나
• 다른 서버를 시작하기 전에 하나를 중지합니다

OmniRoute는 MLX 서버 프로세스를 자동으로 관리하지 않습니다. 사용자가 구성한 OpenAI 호환 엔드포인트로 요청을 라우팅하기만 합니다.

도구 호출 지원

두 모델 모두 OpenAI 호환 도구 호출을 지원합니다. 다음과 같이 테스트하세요:

curl -X POST http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mlx-gemma/gemma-4-26b",
    "messages": [{"role": "user", "content": "2+2는 무엇인가요? 계산기 도구를 사용하세요."}],
    "tools": [{"type": "function", "function": {"name": "calculator", "description": "계산", "parameters": {"type": "object", "properties": {"expression": {"type": "string"}}, "required": ["expression"]}}}]
  }'

문제 해결

문제	해결 방법
서버가 시작되지 않음	uv run mlx_lm.server --help를 확인하고 모델 ID를 검증하세요
메모리 부족	하나의 모델만 실행 중인지 확인하고, 다른 앱을 종료한 후 Activity Monitor를 확인하세요
연결이 거부됨	서버가 올바른 포트(11435/11436)에서 실행 중인지 확인하세요
응답이 느림	첫 번째 요청 시 모델을 메모리에 로드합니다(3060초). 이후 요청은 빠르게 처리됩니다
도구 호출 실패	모델이 도구를 지원하는지 확인하고, OmniRoute 로그에서 변환 오류를 확인하세요

---

최고의 무료 제공업체

다음 제공업체는 신용카드 없이 무료로 이용할 수 있습니다:

제공업체	무료 할당량	모델	연결 방법
Kiro AI	월 50크레딧	Claude Sonnet 4.5, Haiku 4.5, Opus 4.6	인증 불필요
OpenCode Free	무제한	GPT-4o, Claude, Gemini	인증 불필요
Pollinations	키 불필요	GPT-5, Claude, Gemini, DeepSeek, Llama 4	인증 불필요
LongCat	일회성 10M	LongCat-2.0	API 키 + KYC
Cloudflare AI	일일 10K뉴런	50개 이상의 모델	인증 불필요
NVIDIA NIM	약 40 RPM	129개 모델	API 키 필요
Cerebras	가입 시 $5 크레딧	GLM 4.7, GPT-OSS 120B	API 키 + 카드
Qoder	무제한	Kimi-K2, DeepSeek-R1, Qwen3-coder	인증 불필요

팁: 여러 무료 제공업체를 연결하면 자동 대체 기능을 통해 AI를 무제한으로 무료 이용할 수 있습니다!

---

최고의 유료 제공업체

다음 제공업체는 API 키를 통해 고품질 모델을 제공합니다:

제공업체	최고의 모델	비용	무료 요금제
OpenAI	GPT-5, GPT-4o	토큰 1M개당 $2.50-$10	무료 크레딧 $5
Anthropic	Claude Opus 4.6, Sonnet 4.6	토큰 1M개당 $3-$15	무료 크레딧 $5
Google	Gemini 2.5 Pro, Flash	토큰 1M개당 $0.075-$1.25	일일 요청 1,500건 무료
DeepSeek	DeepSeek V4	토큰 1M개당 $0.14-$0.28	무료 토큰 5M개
Groq	Llama 4, Mixtral	토큰 1M개당 $0.05-$0.27	30 RPM 무료
xAI	Grok 3	토큰 1M개당 $0.30-$0.60	—

---

제공업체 연결 방법(단계별)

1단계: 대시보드 열기

브라우저에서 http://localhost:20128로 이동합니다.

2단계: 제공업체로 이동

사이드바에서 제공업체를 클릭합니다.

3단계: 제공업체 추가 클릭

+ 제공업체 추가 버튼을 클릭합니다.

4단계: 제공업체 선택

목록을 탐색하거나 제공업체를 검색한 후 클릭합니다.

5단계: 인증 정보 입력

• 무료 제공업체: 인증 정보가 필요하지 않습니다. 연결만 클릭하세요
• API 키 제공업체: API 키를 붙여 넣으세요
• OAuth 제공업체: OAuth로 연결을 클릭하고 로그인하세요

6단계: 연결 테스트

연결 테스트를 클릭하여 정상 작동하는지 확인합니다.

7단계: 완료!

이제 제공업체가 연결되었습니다. model: "auto"로 사용하거나 제공업체를 직접 지정할 수 있습니다.

---

여러 제공업체 사용하기

OmniRoute는 여러 제공업체와 함께 사용할 때 가장 효과적입니다. 다음과 같은 이점이 있습니다:

• 자동 대체 — 한 제공업체에 장애가 발생하면 OmniRoute가 다음 제공업체를 시도합니다
• 비용 최적화 — OmniRoute가 각 요청에 가장 저렴한 제공업체를 선택합니다
• 속도 최적화 — OmniRoute가 각 요청에 가장 빠른 제공업체를 선택합니다
• 품질 최적화 — OmniRoute가 각 작업에 가장 적합한 제공업체를 선택합니다

권장 설정

최상의 경험을 위해 최소 3개의 제공업체를 연결하세요:

1. 무료 제공업체 1개(Kiro, OpenCode Free 또는 Pollinations) — 항상 사용 가능
2. 빠른 제공업체 1개(Groq, Cerebras) — 빠른 응답용
3. 고품질 제공업체 1개(OpenAI, Anthropic, Google) — 복잡한 작업용

그런 다음 model: "auto"를 사용하면 OmniRoute가 각 요청에 가장 적합한 제공업체를 자동으로 선택합니다.

---

제공업체별 설정

OpenAI

1. API 키 발급: https://platform.openai.com/api-keys
2. OmniRoute에서: 제공업체 → 제공업체 추가 → OpenAI
3. API 키 붙여넣기 → 연결

Anthropic

1. API 키 발급: https://console.anthropic.com/
2. OmniRoute에서: 제공업체 → 제공업체 추가 → Anthropic
3. API 키 붙여넣기 → 연결

Google (Gemini)

1. API 키 발급: https://aistudio.google.com/apikey
2. OmniRoute에서: 제공업체 → 제공업체 추가 → Gemini
3. API 키 붙여넣기 → 연결

DeepSeek

1. API 키 발급: https://platform.deepseek.com/
2. OmniRoute에서: 제공업체 → 제공업체 추가 → DeepSeek
3. API 키 붙여넣기 → 연결

Groq

1. API 키 발급: https://console.groq.com/
2. OmniRoute에서: 제공업체 → 제공업체 추가 → Groq
3. API 키 붙여넣기 → 연결

---

자주 묻는 질문

“OmniRoute를 사용하려면 비용을 지불해야 하나요?”

아니요! OmniRoute는 무료 오픈 소스입니다. 무료 제공업체(Kiro, OpenCode Free, Pollinations)는 비용을 전혀 지불하지 않고 사용할 수 있습니다. 유료 제공업체를 사용하기로 선택한 경우에만 비용을 지불하면 됩니다.

“어떤 제공업체로 시작하는 것이 좋나요?”

Kiro AI로 시작하세요. 무료이고 API 키가 필요하지 않으며 Claude 모델을 사용할 수 있습니다. 그런 다음 필요에 따라 제공업체를 더 추가하세요.

“여러 제공업체를 동시에 사용할 수 있나요?”

네! 이것이 바로 OmniRoute의 핵심입니다. 여러 제공업체를 연결하고 model: "auto"를 사용하면 OmniRoute가 각 요청에 가장 적합한 제공업체를 선택합니다.

“제공업체에 장애가 발생하면 어떻게 되나요?”

OmniRoute는 실패한 제공업체를 자동으로 건너뛰고 다음 제공업체를 시도합니다. 별도로 조치할 필요가 없습니다.

“제공업체의 연결을 해제하려면 어떻게 하나요?”

제공업체 → 해당 제공업체 클릭 → 연결 해제를 클릭하세요.

“기존 API 키를 사용할 수 있나요?”

네! OpenAI, Anthropic, Google 등의 API 키를 이미 보유하고 있다면 OmniRoute에서 사용할 수 있습니다. 제공업체를 연결할 때 키를 붙여넣기만 하면 됩니다.

---

다음 단계

• 자동 조합 가이드 — OmniRoute가 가장 적합한 AI를 선택하도록 설정하기
• 무료 요금제 가이드 — 신용카드 없이 무료 AI 이용하기
• 문제 해결 — 일반적인 문제 해결하기
• 제공업체 참조 — 226개 제공업체 전체 목록

Cursor 이미지

Cursor 요금제 이미지는 IMAGE_PROVIDERS.cursor(cursor-agent-image)를 사용합니다. CURSOR_IMAGE.md를 참조하세요.

---

OmniRoute 소스 코드 (a58000c7685f)