Switch 사용 설명서 개발 중

시작하기

임의의 OpenAI 클라이언트를 Switch에 연결하기

Switch는 실행 후 로컬에 OpenAI API 호환 엔드포인트를 노출하며, base_url 한 줄만 바꾸면 모든 요청이 자동으로 Switch를 통해 라우팅됩니다.

빠른 연동

Switch는 실행 후 로컬에 OpenAI API 호환 엔드포인트 http://localhost:19090/v1을 노출합니다(Switch gateway 기본 포트 19090). 애플리케이션/SDK의 base_url을 이 주소로 변경하면 모든 요청이 자동으로 Switch를 통해 라우팅됩니다. api_key에는 임의의 값(예: switch)을 넣으면 되며, Switch는 설정에 있는 provider key를 사용합니다.

1. 클라이언트의 base_url을 로컬 Switch 엔드포인트로 지정하고, api_key에는 임의의 값(예: switch)을 넣은 뒤 평소처럼 요청을 보냅니다:

   cURL

   curl http://localhost:19090/v1/chat/completions \
     -H "Content-Type: application/json" -H "Authorization: Bearer switch" \
     -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hello"}]}'

   Python

   from openai import OpenAI
   
   client = OpenAI(
       base_url="http://localhost:19090/v1",
       api_key="switch",
   )
   resp = client.chat.completions.create(
       model="gpt-4o",
       messages=[{"role": "user", "content": "Hello"}],
   )
   print(resp.choices[0].message.content)

   Node.js

   import OpenAI from "openai";
   
   const client = new OpenAI({
     baseURL: "http://localhost:19090/v1",
     apiKey: "switch",
   });
   const resp = await client.chat.completions.create({
     model: "gpt-4o",
     messages: [{ role: "user", content: "Hello" }],
   });
   console.log(resp.choices[0].message.content);

2. OpenAI SDK(Python / Node.js)는 base_url/baseURL과 api_key만 바꾸면 나머지 호출은 평소대로 사용합니다 — Switch가 설정에 있는 provider key로 실제 라우팅을 수행하므로, 클라이언트는 하위 제공자를 인식할 필요가 없습니다.

api_key에 임의의 값을 넣어도 되는 이유

Switch는 로컬 프록시로서 설정에 저장된 실제 provider key를 사용해 하위 제공자를 호출합니다. 클라이언트 측의 api_key는 자리표시자로만 쓰이므로 switch를 넣으면 됩니다.

통합

AI 코딩 도구에서 사용하기

모든 도구의 API Base / 인터페이스 주소에는 http://localhost:19090/v1을, API Key에는 switch를 입력합니다.

AI 코딩 도구에서 사용하기

모든 도구의 API Base / 인터페이스 주소에는 http://localhost:19090/v1을, API Key에는 switch를 입력합니다:

Cursor

설정(Ctrl+,) → 「AI」 검색 → 「OpenAI API Base」를 이 주소로 변경 → 저장하면, 자동 완성과 대화가 자동으로 Switch를 거칩니다.

Continue（VS Code）

~/.continue/config.json을 편집하여 각 model 항목에 "provider": "openai", "apiBase": "http://localhost:19090/v1", "apiKey": "switch"를 설정하고, "model"에는 deepseek-chat / gpt-4o 등을 입력합니다.

Cherry Studio

설정 → API 설정 → 「사용자 정의 OpenAI 호환」 선택 → 주소와 Key 입력 → 「연결 테스트」.

Lobe Chat

설정 → 언어 모델 → OpenAI → API Key와 인터페이스 주소 입력.

런타임

모니터링, 전환 및 스트리밍

요청 모니터링

「로그」 탭에서 실시간 요청 로그를 확인할 수 있으며, 필드는 다음과 같습니다: 시간(타임스탬프), 모델, 제공자(실제 라우팅 대상), 소요 시간(ms), Token(prompt/completion), 상태(200 / 4xx-5xx). 「CSV 내보내기」로 최근 7일 기록을 내보내 비용 통계에 활용할 수 있습니다.

제공자 원클릭 전환

메뉴 막대 아이콘(macOS) / 시스템 트레이(Windows)를 클릭하면 다음을 할 수 있습니다: 「현재 활성 제공자」 전환, 특정 제공자 임시 비활성화(디버깅), 오늘 사용량 개요 확인.

스트리밍 응답

SSE 스트리밍 응답을 완전히 지원하며 하위로 그대로 전달합니다: chat.completions.create(..., stream=True) 이후 chunk.choices[0].delta.content를 반복 처리하면 됩니다.

고급

로드 밸런싱

동일 모델에 여러 제공자를 구성하면 라운드 로빈 또는 가중치 기반으로 분배할 수 있습니다.

고급: 로드 밸런싱

동일 모델에 여러 제공자를 구성하면 라운드 로빈 또는 가중치 기반으로 분배할 수 있습니다:

{
  "routing": {
    "rules": [
      {
        "pattern": "deepseek-chat",
        "providers": [
          { "name": "Lurus API", "weight": 70 },
          { "name": "DeepSeek Official", "weight": 30 }
        ],
        "strategy": "weighted_random"
      }
    ]
  }
}

문제 해결

문제 해결

해당 증상을 펼쳐 처리 단계를 확인하세요.

문제 해결

"connection refused" — 연결이 거부됨

Switch가 실행되지 않았거나 포트가 잘못되었습니다. 프로세스와 포트를 확인하세요:

• 프로세스: Windows tasklist | findstr LurusSwitch / macOS·Linux ps aux | grep lurus-switch
• 포트: curl http://localhost:19090/v1/models

401 / 403 — 인증 실패

제공자 API Key 설정이 잘못되었습니다. 설정 화면에서 다시 입력하고 「테스트」를 클릭해 연결 상태를 확인하세요.

지연 시간이 비정상적으로 높음

1. 로그에서 라우팅이 올바른 제공자에 적중했는지 확인하세요.
2. 해외 제공자(OpenAI / Anthropic)의 높은 지연은 정상입니다(300-1500ms).
3. Lurus API 국내 노드로 변경하세요(일반적으로 < 200ms).

macOS 앱 응답 없음

메뉴 막대에서 우클릭 후 「종료」하고 다시 시작하거나, 터미널에서 실행하세요:

pkill -f LurusSwitch && open -a "Lurus Switch"

다음 단계

다음 단계

MCP 서버 관리비용 모니터링팀 설정 동기화