BroadRouter
시작하기

OpenAI 호환 API로 전환하기: 마이그레이션 체크리스트

BroadNet Inference 팀 · 5분 분량 · 게시 · 업데이트

OpenAI 호환 API로 옮기려면 base_url, api_key, model 세 가지 설정을 바꾼 뒤 달라지는 부분을 확인하면 됩니다. 모델 ID, 추론 토큰이 max_tokens에 포함되는 방식, 스트리밍의 사용량 보고 방식, 재시도할 오류, 속도 제한, 키 보안입니다. BroadNet Inference의 base URL은 https://inference.broadnet.ai/v1 주소입니다.

이제 대부분의 LLM 제공업체가 OpenAI API 형식을 지원합니다. 그래서 전환은 한 줄만 바꾸면 되는 일처럼 보이고, 첫 답변을 받는 데까지는 실제로 그렇습니다. 하지만 프로덕션 트래픽을 돌리려면 이 목록을 차례로 확인하세요. 모든 항목은 실제로 마이그레이션이 깨졌던 사례에서 나왔습니다.

0. 지금 앱은 무엇을 쓰고 있나요?

무엇이든 바꾸기 전에 앱이 의존하는 것을 적어 두세요. 코드에서 SDK 호출을 모두 찾아 목록으로 만드세요. OpenAI의 Whisper API를 호출하고 있다면, OpenAI가 whisper-1을 2027년 2월 26일에 종료한다고 게시했다는 점을 기억하세요. 오디오 쪽은 Whisper API 대안에서 다룹니다.

기능 찾을 곳 전환 후 테스트
채팅 완성 모든 chat.completions.create 같은 프롬프트로 답변 비교
스트리밍 stream=True 청크가 도착하고 [DONE]으로 끝나며 사용량이 있음
도구 호출 tools= 도구 호출이 파싱되고 실행됨
구조화된 출력 response_format= JSON이 스키마 검증을 통과함
이미지 메시지의 이미지 파트 모델이 받아들임
오디오 전사 audio.transcriptions 텍스트와 언어가 정확함
임베딩, 파일, 배치 그 밖의 엔드포인트 제공업체가 아예 제공하는지 확인

마지막 행이 중요합니다. “OpenAI 호환”은 대개 채팅 완성부터 지원합니다. BroadNet Inference의 카탈로그에는 /v1/chat/completions의 채팅 모델과 /v1/audio/transcriptions의 음성 인식 모델이 있습니다. 다른 엔드포인트를 쓴다면 현재 제공업체에 그대로 두거나 대체할 곳을 찾으세요.

1. 바뀌는 설정 세 가지는 무엇인가요?

from openai import OpenAI
import os

client = OpenAI(
    base_url="https://inference.broadnet.ai/v1",
    api_key=os.environ["BROADNET_API_KEY"],
)

base URL 설정의 이름은 라이브러리마다 다릅니다. Python SDK와 LangChain의 ChatOpenAI에서는 base_url, Node.js SDK에서는 baseURL입니다. README에 따르면 Python SDK는 OPENAI_BASE_URL 환경 변수도 읽습니다. 환경에 예전 값이 남아 있지 않은지 확인하세요. 남아 있으면 요청이 오류 없이 이전 제공업체로 갈 수 있습니다.

API 키는 코드가 아니라 환경 변수나 시크릿 매니저에 두세요. SDK별 설정: Python, Node.js, LangChain. 첫 요청을 직접 만들어 테스트하려면 API 요청 빌더를 쓰세요. 기존 코드에 base URL, 키, 모델 변경을 적용하려면 OpenAI에서 BroadNet으로 마이그레이션 도우미에 코드를 붙여 넣으세요. 확인할 항목도 함께 알려 줍니다.

2. 새 모델 ID는 무엇인가요?

제공업체마다 모델 이름을 붙이는 방식이 다릅니다. BroadNet Inference에서는 다음과 같습니다.

모델 ID
DeepSeek V4.1 Flash broadnet/deepseek-v4.1-flash
GLM 5.3 broadnet/glm-5.3
Qwen3.8 27B broadnet/qwen3.8-27b
Gemma 4 VL 26B broadnet/gemma-4-26b-a4b

모델 ID는 코드가 아니라 설정에 두세요. 그래야 나중에 바꿀 때 코드를 다시 쓰지 않고 배포만 하면 됩니다. 모델별 한도와 가격은 각 페이지에 있습니다: DeepSeek V4.1 Flash, GLM 5.3, Qwen3.8 27B, Gemma 4 VL 26B.

3. 전환한 뒤 답변이 비어 있는 이유는 무엇인가요?

가장 흔하게 당황하는 지점입니다. DeepSeek V4.1 Flash, GLM 5.3, Qwen3.8 27B는 답하기 전에 추론하며, 추론 토큰은 max_tokens에 포함됩니다. 비추론 모델에서 잘 되던 256 한도가 생각하는 데 모두 쓰이면 답변이 비어서 돌아옵니다. 1,000 토큰 이상을 남겨 두거나, 단순한 작업에는 reasoning_effort를 low로 설정하세요. 자세한 설명.

4. 스트리밍은 여전히 사용량을 보고하나요?

스트림은 Server-Sent Events를 쓰고 data: [DONE]으로 끝납니다. 토큰 사용량은 요청할 때만 마지막 청크에 담겨 옵니다.

stream = client.chat.completions.create(
    model="broadnet/deepseek-v4.1-flash", messages=messages,
    stream=True, stream_options={"include_usage": True},
)

이 옵션이 없으면 비용 대시보드는 0을 표시합니다. 스트림이 [DONE] 전에 끝나면 불완전한 응답으로 처리하세요. 스트리밍 가이드.

5. 어떤 오류를 재시도해야 하나요?

상태 의미 조치
401 잘못되었거나 폐기된 키, 또는 소진된 종량제 한도 고치고, 재시도하지 않음
402 잔액 또는 예산 부족 충전하고, 재시도하지 않음
403 모델, 경로, IP 정책에 의해 거부됨 불일치를 해결
413 요청이 너무 큼 줄이고, 재시도하지 않음
429 속도, 동시 처리, 지출 한도 백오프 후 재시도
5xx 서버 쪽 문제 상한을 둔 백오프로 재시도

공식 Python SDK는 일부 오류를 이미 재시도합니다. README에 따르면 연결 오류, 408, 409, 429, 5xx 응답은 기본적으로 짧은 지수 백오프로 두 번 재시도됩니다. max_retries를 명시적으로 설정해, 이 동작이 기본값이 아니라 의도한 결정이 되게 하세요. 모든 응답의 요청 ID를 로그로 남겨 지원팀이 문제를 추적할 수 있게 하세요. 전체 코드.

6. 새 속도 제한은 어떻게 되나요?

트래픽이 들어오기 전에 새 한도를 파악하세요. BroadNet 종량제 키는 분당 30 요청, 동시 요청 4개까지 허용합니다. 무제한 플랜은 세션마다 한 번에 요청 1개를 처리합니다. 워커 풀 크기를 이에 맞추지 않으면 첫날부터 429를 보게 됩니다. 크기 계산은 속도 제한 계산기가 해 줍니다. 병렬 에이전트를 위한 규모 산정.

7. 프롬프트가 여전히 들어가나요?

컨텍스트 윈도를 확인하세요. DeepSeek V4.1 Flash와 GLM 5.3은 1,048,576 토큰, Qwen3.8 27B는 262,144 토큰, Gemma 4 VL 26B는 32,768 토큰입니다. 이전 모델에 들어가던 프롬프트가 더 작은 윈도에는 들어가지 않을 수 있습니다. 컨텍스트 윈도 계산기로 확인하세요. 변하지 않는 프롬프트 내용을 앞에 두면 캐시된 입력 가격 혜택을 받을 수 있습니다.

8. 키와 데이터 보관은 어떻게 하나요?

IP 허용 목록으로 프로덕션 키를 서버 IP에서만 쓰도록 잠그세요. 새 제공업체에 무엇을 보관하는지 물어보세요. ZDR 체크리스트를 참고하세요.

9. 안전하게 전환하려면 어떻게 하나요?

  1. 하루치 실제 요청의 복사본을 두 제공업체에 모두 보내세요.
  2. 표본의 답변과 함께 지연 시간, 오류, 요청당 비용을 비교하세요.
  3. 트래픽의 10%를 옮기고 하루 동안 지켜본 뒤 나머지를 옮기세요.
  4. 1주일 동안 이전 제공업체를 대체(fallback) 경로로 설정해 두세요.

서비스가 많다면 LiteLLM 같은 프록시를 쓰면 앱마다가 아니라 한곳에서 제공업체를 바꿀 수 있습니다.

흔한 마이그레이션 실수는 무엇인가요?

  • base URL에 /v1 누락. 요청이 404를 반환합니다. 전체 URL을 쓰세요.
  • 설정에 남은 이전 모델 이름. 새 제공업체는 그 이름을 모릅니다.
  • 요청에 남은 제공업체 전용 필드. 이전 제공업체만 이해하던 필드는 거부되거나 무시될 수 있습니다. 범용 클라이언트에서는 지우세요.
  • 프롬프트 하나만 테스트. 0단계의 목록을 기능별로 하나씩 확인하세요.
  • 금요일에 전환. 실제 트래픽을 하루 종일 지켜볼 시간을 남겨 두세요.

BroadNet Inference의 위치

BroadNet Inference는 OpenAI SDK로 채팅 완성과 오디오 전사를 쓰는 앱이라면 그대로 옮겨 올 수 있는 대상입니다. 설정 세 가지를 바꾸고 위 목록을 확인하면 됩니다. 카탈로그에는 채팅 모델과 음성 인식 모델만 있으므로, 임베딩이나 파일 저장소 같은 다른 엔드포인트에 의존한다면 그 부분은 다른 제공업체에 두세요. 새 계정은 $5 상당의 초기 크레딧으로 시작합니다. 채팅 모델 중에서는 Gemma 4 VL 26B만 이 크레딧으로 쓸 수 있으므로(Transcribe 모델 두 개에도 쓸 수 있습니다), DeepSeek, GLM, Qwen으로 섀도 테스트를 하려면 충전이 필요합니다.

자주 묻는 질문

다른 SDK가 필요한가요?

아니요. Python과 Node.js용 공식 OpenAI SDK는 사용자 지정 base URL을 받습니다. LangChain의 ChatOpenAI처럼 이 SDK 위에 만든 프레임워크도 마찬가지입니다.

OpenAI SDK에서 base URL은 어떻게 바꾸나요?

Python에서는 클라이언트에 base_url을, Node.js에서는 baseURL을 넘기거나 OPENAI_BASE_URL 환경 변수를 설정하세요. BroadNet Inference의 값은 https://inference.broadnet.ai/v1 주소이고, 키는 api_key에 넣습니다.

전환한 뒤 빈 응답이 오는 이유는 무엇인가요?

DeepSeek V4.1 Flash, GLM 5.3, Qwen3.8 27B 같은 추론 모델은 답하기 전에 생각하고, 그 생각이 max_tokens에 포함됩니다. max_tokens를 1,000 이상으로 올리거나 reasoning_effort를 low로 설정하세요.

전환한 뒤 404나 model not found 오류가 나는 이유는 무엇인가요?

대개 모델 ID가 아직 이전 제공업체의 이름이거나, base URL에 /v1 경로가 빠져 있기 때문입니다. 새 제공업체의 정확한 모델 ID와 전체 base URL을 쓰세요.

어떤 오류를 재시도해야 하나요?

429와 5xx는 상한을 둔 지수 백오프로 재시도하세요. 401, 402, 413은 원인을 고친 뒤 다시 보내세요. 이 사이트의 오류 가이드에 모든 코드가 정리되어 있습니다.

OpenAI 호환이면 완전히 똑같은가요?

아니요. 요청과 응답의 형태는 같지만, 모델 ID, 지원 파라미터, 한도, 사용량 필드, 오류 세부 정보는 다를 수 있습니다. 앱이 쓰는 모든 기능을 테스트하세요.

Markdown으로 읽기ChatGPT에 질문하기Claude에 질문하기Perplexity에 질문하기