Universal 목록
SWDEV / 가이드 배포자료

SW_DEV Gateway 사용 가이드

redtree2379@swdev.co.kr2026. 10. 30.· 2026. 10. 30. 수정
#swdev#gateway#llm#openai호환api#ai모델

gateway-02-models

Gateway는 Planet에 등록한 AI 모델을 주소 하나로 부르게 해 주는 App입니다. OpenAI API와 같은 형식이라, 쓰던 OpenAI SDK 코드에서 주소와 키만 바꾸면 GPT, Claude, Gemini, 사내 모델 서버를 같은 방식으로 부릅니다. LLM 말고도 임베딩, 리랭크, 결정(Decision), 이미지, 음성 모델을 같은 키로 부를 수 있습니다.

화면에 나오는 Planet, 모델, 숫자는 모두 설명용 예시입니다.

한눈에 보기

메뉴 하는 일
Overview 요청 수 · 토큰 · 비용 · 응답 시간, 연동 방법
Models 모델 등록, 종류별로 모아 보기
Tools · MCP 에이전트가 쓸 HTTP API 도구와 MCP 서버 연결
Route 모델 별칭, 실패 시 다음 모델로 넘기기
Limit 분당 요청 · 토큰, 월 예산, 키마다 허용할 라우트
Log 요청 하나하나의 결과와 비용

1. 모델 등록하기 (Models)

Models에는 등록한 모델이 카드로 나옵니다. 카드마다 종류와 프로바이더, 자격 증명, 연결 상태, 100만 토큰당 가격이 보입니다. 검색창 오른쪽의 버튼으로 LLM · Embedding · Reranking · Decision · Image · Audio 가운데 한 종류만 골라 볼 수 있습니다.

모델 추가를 누르면 세 단계로 진행합니다.

gateway-03-model-add

  1. 종류 · 프로바이더: 모델 종류와 프로바이더를 고릅니다. OpenAI, Claude, Gemini, Vertex AI, Cohere, Jina AI, Voyage AI, OpenRouter, vLLM, Ollama 등이 있습니다. OpenAI 형식을 따르는 다른 서버는 'OpenAI 호환'을 고른 뒤 주소(Base URL)를 넣습니다.
  2. 자격 증명 · 모델: Secret에 저장해 둔 토큰을 고르거나 키를 바로 넣은 뒤 조회된 목록에서 쓸 모델을 고릅니다. 필요하면 별칭을 붙입니다.
  3. 연결 확인: 아주 짧은 실제 호출로 쓸 수 있는지 확인합니다. 통과한 모델만 등록됩니다.

호출할 때 model에 넣는 값은 모델의 이름입니다. 별칭을 붙였으면 별칭이, 아니면 모델 ID가 이름입니다. 같은 종류 안에서는 이름이 겹칠 수 없습니다. 같은 모델을 다른 키로 한 번 더 등록하려면 별칭을 달리 붙이면 됩니다.

2. 라우트 만들기 (Route)

gateway-04-routes

라우트는 model 값으로 부르는 별칭입니다. 안에 실제 모델을 하나 이상 넣어 둡니다.

  • 순차 (폴백): 앞의 모델이 실패하면 다음 모델로 넘어갑니다.
  • 가중치 (분산): 정한 비율대로 요청을 나눠 보냅니다.

모델을 바꿔야 할 때 앱 코드는 그대로 두고 라우트의 대상만 바꾸면 됩니다. 라우트도 종류가 정해져 있어서 위 화면의 decide에는 결정 모델만, embed에는 임베딩 모델만 들어갑니다.

3. 호출하기

API 키는 Access의 API 메뉴에서 범위에 Gateway를 넣어 발급합니다. 기본 주소는 https://swdev.co.kr/api/llm/v1입니다. Overview 아래쪽 연동 방법에 Python · Node.js · curl 예제가 있습니다.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://swdev.co.kr/api/llm/v1",
    api_key=os.environ["SWDEV_API_KEY"],
)
res = client.chat.completions.create(
    model="chat-default",  # 모델 이름 또는 라우트 이름
    messages=[{"role": "user", "content": "안녕하세요"}],
)
print(res.choices[0].message.content)

종류마다 부르는 경로가 다릅니다.

종류 경로
LLM /chat/completions
Embedding /embeddings
Reranking /rerank
Decision /systemone
Image /images/generations
Audio /audio/speech, /audio/transcriptions

요청 형식과 오류 코드는 화면 맨 아래 Docs의 Gateway 문서에 자세히 정리했습니다.

4. 사용량과 기록 보기 (Overview · Log)

gateway-01-overview

Overview에는 기간별 요청 수와 토큰, 비용, 평균 응답 시간, 폴백 · 캐시 횟수가 그래프와 함께 나옵니다. 아래 표에서는 모델별 · 라우트별 · API 키별로 나눠 봅니다.

gateway-05-logs

Log에는 요청이 하나씩 남습니다. 결과와 종류, 라우트, 모델로 걸러 볼 수 있습니다. 요청마다 부른 이름과 실제로 답한 모델, 시도 횟수, 토큰, 비용, 걸린 시간이 나옵니다. 프롬프트와 응답 본문은 저장하지 않으며 기록은 90일 동안 보관합니다.

5. 한도 걸기 (Limit)

Planet 전체, API 키, 라우트 단위로 분당 요청 수와 분당 토큰 수, 일 · 월 토큰, 월 예산을 겁니다. 한도를 넘은 요청은 429로 거절됩니다. 키마다 부를 수 있는 라우트를 제한하는 API 키 정책도 여기서 정합니다.

한도를 하나도 걸지 않으면 호출량에 제한이 없습니다. 키를 외부에 나눠 줄 때는 키별 한도부터 걸어 두십시오.

6. 도구와 MCP (Tools · MCP)

Tools에는 사내 HTTP API를 도구로 등록하고, MCP에는 MCP 서버를 연결합니다. 여기 등록한 도구는 Agent의 에이전트 편집 화면에서 골라 붙입니다.

댓글 0 조회 0

댓글

등록된 댓글이 없습니다.