---
title: "OpenAI 호환 API 전환 방법: 마이그레이션 체크리스트 | BroadRouter"
description: "base_url 변경은 쉬운 부분입니다. 문제는 모델 ID, 추론 토큰, 스트리밍 사용량, 오류, 속도 제한, 키에서 생깁니다. 코드와 함께 보는 체크리스트입니다."
url: https://broadrouter.com/ko/blog/openai-compatible-api-migration-checklist/
lang: ko
updated: 2026-11-14
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

이 페이지는 영어 원문을 AI의 도움을 받아 번역했습니다. [영어 원문 읽기](https://broadrouter.com/blog/openai-compatible-api-migration-checklist/) (2026-11-16 업데이트).

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

BroadNet Inference 팀 · 5분 분량 · 게시 2026-11-14 · 업데이트 2026-11-16

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

## 핵심 요약

-   바뀌는 설정은 `base_url`, `api_key`, `model` 세 가지입니다.
-   전환하기 전에 앱이 쓰는 모든 엔드포인트와 필드를 목록으로 만들고, 하나씩 테스트하세요.
-   추론 모델은 생각하는 데 쓴 토큰도 `max_tokens`에 포함하므로, 한도가 작으면 빈 답변이 돌아옵니다.
-   스트림에서는 `stream_options`로 사용량을 요청하세요. 그러지 않으면 비용 추적이 먹통이 됩니다.
-   프로덕션 트래픽을 옮기기 전에 오류 코드별로 재시도할지 고칠지 정해 두세요.
-   완전히 넘어가기 전에 기존 제공업체와 새 제공업체를 실제 트래픽으로 하루 동안 나란히 돌려 보세요.

**이 페이지의 내용**

1.  0\. 지금 앱은 무엇을 쓰고 있나요?
2.  1\. 바뀌는 설정 세 가지는 무엇인가요?
3.  2\. 새 모델 ID는 무엇인가요?
4.  3\. 전환한 뒤 답변이 비어 있는 이유는 무엇인가요?
5.  4\. 스트리밍은 여전히 사용량을 보고하나요?
6.  5\. 어떤 오류를 재시도해야 하나요?
7.  6\. 새 속도 제한은 어떻게 되나요?
8.  7\. 프롬프트가 여전히 들어가나요?
9.  8\. 키와 데이터 보관은 어떻게 하나요?
10.  9\. 안전하게 전환하려면 어떻게 하나요?
11.  흔한 마이그레이션 실수는 무엇인가요?
12.  BroadNet Inference의 위치

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

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

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

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

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

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

```python
from openai import OpenAI
import os

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

[base URL](https://broadrouter.com/ko/glossary/base-url/) 설정의 이름은 라이브러리마다 다릅니다. Python SDK와 LangChain의 ChatOpenAI에서는 `base_url`, Node.js SDK에서는 `baseURL`입니다. [README](https://github.com/openai/openai-python)에 따르면 Python SDK는 `OPENAI_BASE_URL` 환경 변수도 읽습니다. 환경에 예전 값이 남아 있지 않은지 확인하세요. 남아 있으면 요청이 오류 없이 이전 제공업체로 갈 수 있습니다.

[API 키](https://broadrouter.com/ko/glossary/api-key/)는 코드가 아니라 환경 변수나 시크릿 매니저에 두세요. SDK별 설정: [Python](https://broadrouter.com/ko/guides/openai-python-sdk/), [Node.js](https://broadrouter.com/ko/guides/openai-node-sdk/), [LangChain](https://broadrouter.com/ko/guides/langchain-openai-base-url/). 첫 요청을 직접 만들어 테스트하려면 [API 요청 빌더](https://broadrouter.com/tools/api-request-builder/)를 쓰세요. 기존 코드에 base URL, 키, 모델 변경을 적용하려면 [OpenAI에서 BroadNet으로 마이그레이션 도우미](https://broadrouter.com/tools/openai-to-broadnet-migration/)에 코드를 붙여 넣으세요. 확인할 항목도 함께 알려 줍니다.

## 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](https://broadrouter.com/ko/models/deepseek-v4.1-flash/), [GLM 5.3](https://broadrouter.com/ko/models/glm-5.3/), [Qwen3.8 27B](https://broadrouter.com/ko/models/qwen3.8-27b/), [Gemma 4 VL 26B](https://broadrouter.com/ko/models/gemma-4-vl-26b/).

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

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

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

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

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

이 옵션이 없으면 비용 대시보드는 0을 표시합니다. 스트림이 `[DONE]` 전에 끝나면 불완전한 응답으로 처리하세요. [스트리밍 가이드](https://broadrouter.com/ko/guides/streaming-chat-completions/).

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

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

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

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

트래픽이 들어오기 전에 새 한도를 파악하세요. BroadNet 종량제 키는 분당 30 요청, 동시 요청 4개까지 허용합니다. 무제한 플랜은 세션마다 한 번에 요청 1개를 처리합니다. 워커 풀 크기를 이에 맞추지 않으면 첫날부터 429를 보게 됩니다. 크기 계산은 [속도 제한 계산기](https://broadrouter.com/tools/llm-rate-limit-calculator/)가 해 줍니다. [병렬 에이전트를 위한 규모 산정](https://broadrouter.com/ko/blog/run-parallel-coding-agents-flat-rate/).

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

컨텍스트 윈도를 확인하세요. DeepSeek V4.1 Flash와 GLM 5.3은 1,048,576 토큰, Qwen3.8 27B는 262,144 토큰, Gemma 4 VL 26B는 32,768 토큰입니다. 이전 모델에 들어가던 프롬프트가 더 작은 윈도에는 들어가지 않을 수 있습니다. [컨텍스트 윈도 계산기](https://broadrouter.com/tools/context-window-calculator/)로 확인하세요. 변하지 않는 프롬프트 내용을 앞에 두면 [캐시된 입력 가격](https://broadrouter.com/ko/blog/cached-input-tokens-explained/) 혜택을 받을 수 있습니다.

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

[IP 허용 목록](https://broadrouter.com/ko/guides/api-keys-ip-allow-lists/)으로 프로덕션 키를 서버 IP에서만 쓰도록 잠그세요. 새 제공업체에 무엇을 보관하는지 물어보세요. [ZDR 체크리스트](https://broadrouter.com/ko/blog/zero-data-retention-llm-api-checklist/)를 참고하세요.

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

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

서비스가 많다면 [LiteLLM](https://broadrouter.com/ko/guides/litellm-proxy-custom-provider/) 같은 프록시를 쓰면 앱마다가 아니라 한곳에서 제공업체를 바꿀 수 있습니다.

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

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

## BroadNet Inference의 위치

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

관련 무료 도구 (영어)

-   [OpenAI to BroadNet migration helper](https://broadrouter.com/tools/openai-to-broadnet-migration/) Paste OpenAI SDK code; get base URL, key and model edits, a diff and the checks that remain.
-   [max\_tokens calculator for reasoning models](https://broadrouter.com/tools/reasoning-token-budget/) Answer length + reasoning budget + margin = a max\_tokens that does not cut the answer off.
-   [JSON schema generator for LLM structured output](https://broadrouter.com/tools/json-schema-generator/) Sample JSON to strict schema, Pydantic, Zod and a ready request.
-   [LLM JSON output validator](https://broadrouter.com/tools/llm-json-output-validator/) Parse errors by line and column, safe repairs, cut-off detection and JSON Schema checks for model output.

[무료 도구 (영어)](https://broadrouter.com/tools/)

## 이 글의 용어

[도구 호출(tool calling)](https://broadrouter.com/ko/glossary/tool-calling/)

도구 호출(tool calling)은 함수 호출(function calling)이라고도 하며, 모델이 개발자가 정의한 함수를 실행해 달라는 구조화된 요청을 JSON 인자와 함께 반환하는 LLM API 기능입니다. 함수는 애플리케이션이 실행하고 그 결과를 다시 보냅니다. 모델이 직접 코드를 실행하지는 않습니다.

[종량제(Pay-as-you-go)](https://broadrouter.com/ko/glossary/pay-as-you-go/)

종량제(pay-as-you-go)는 구독이나 최소 약정 없이 토큰, 요청, 오디오 분 같은 단위로 사용량을 측정해 쓴 만큼만 내는 요금 방식입니다. 대부분의 LLM API가 선불 잔액에서 차감하거나 정기 청구서를 발행하는 식으로 이렇게 과금합니다.

[동시 처리(concurrency)](https://broadrouter.com/ko/glossary/concurrency/)

동시 처리(concurrency)는 클라이언트가 같은 시점에 진행 중인 요청 수입니다. LLM API는 분당 요청 수와 별도로 키나 플랜마다 이를 제한하는 경우가 많습니다. 열려 있는 요청은 응답이 끝날 때까지 GPU 용량을 차지하기 때문입니다.

[음성 인식(Speech-to-text, STT)](https://broadrouter.com/ko/glossary/speech-to-text/)

음성 인식(STT)은 자동 음성 인식(ASR)이라고도 하며, 말소리 오디오를 글로 변환하는 기술입니다. 음성 인식 API는 오디오 파일이나 스트림을 받아 전사 텍스트를 반환하며, 보통 오디오 분당 요금이 붙습니다. 정확도는 단어 오류율로 측정하며 억양, 방언, 녹음 품질에 따라 달라집니다.

[base URL(베이스 URL)](https://broadrouter.com/ko/glossary/base-url/)

base URL은 https://api.example.com/v1처럼 API의 고정된 루트 주소로, 클라이언트가 /chat/completions 같은 모든 엔드포인트 경로 앞에 붙입니다. OpenAI 호환 SDK에서는 base URL을 API 키, 모델 ID와 함께 바꾸면 같은 코드로 다른 제공업체를 호출할 수 있습니다.

[구조화된 출력(Structured output)](https://broadrouter.com/ko/glossary/structured-output/)

구조화된 출력(structured output)은 모델의 응답을 개발자가 지정한 형식, 주로 JSON Schema에 맞추도록 제한해 코드가 안정적으로 파싱할 수 있게 하는 LLM API 기능입니다. 유효한 JSON만 보장하고 특정 구조는 보장하지 않는 JSON 모드보다 더 엄격합니다.

[데이터 비보관(Zero data retention, ZDR)](https://broadrouter.com/ko/glossary/zero-data-retention/)

데이터 비보관(ZDR)은 AI 제공업체가 프롬프트와 출력을 요청 처리에만 사용하고, 처리 후에는 그 내용을 로그, 캐시, 학습 데이터 어디에도 저장하지 않는 데이터 처리 정책입니다. 토큰 수나 처리 시간처럼 내용이 없는 기록은 보통 계속 보관됩니다.

[속도 제한(rate limit)](https://broadrouter.com/ko/glossary/rate-limit/)

속도 제한(rate limit)은 API가 일정 시간 동안 클라이언트가 사용할 수 있는 양에 두는 상한으로, 분당 요청 수나 분당 토큰 수 같은 기준이 있습니다. 한도를 넘은 요청은 사용량이 다시 한도 아래로 내려갈 때까지 거부되며, 보통 HTTP 429 Too Many Requests가 반환됩니다.

## 자주 묻는 질문

### 다른 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, 지원 파라미터, 한도, 사용량 필드, 오류 세부 정보는 다를 수 있습니다. 앱이 쓰는 모든 기능을 테스트하세요.

## 이어서 읽기

-   [OpenAI 호환 API base\_url 목록: 제공업체 14곳 직접 확인](https://broadrouter.com/ko/blog/openai-compatible-api-base-urls/)
-   [AI 에이전트에는 OpenRouter와 정액 플랜 중 무엇이 더 저렴할까?](https://broadrouter.com/ko/blog/openrouter-alternative-flat-rate/)
-   [100만 토큰 컨텍스트 윈도우, 언제 쓸 만하고 언제 아닌가](https://broadrouter.com/ko/blog/million-token-context-window-guide/)
-   [데이터 비보관(ZDR) LLM API: 확인해야 할 질문 10가지](https://broadrouter.com/ko/blog/zero-data-retention-llm-api-checklist/)
-   [BroadNet의 GPU 하드웨어와 서빙 방식: BroadNet이 밝힌 내용](https://broadrouter.com/ko/blog/broadnet-gpu-fleet-and-serving/)
-   [LLM API 응답 캐싱으로 비용 줄이기: Python 정확 일치 캐시](https://broadrouter.com/ko/blog/cache-llm-responses-cut-cost/)
-   [가이드: BroadNet Inference에서 OpenAI Python SDK 사용하기](https://broadrouter.com/ko/guides/openai-python-sdk/)
-   [가이드: BroadNet Inference에서 OpenAI Node.js SDK 사용하기](https://broadrouter.com/ko/guides/openai-node-sdk/)
-   [가이드: BroadNet Inference에서 LangChain 사용하기](https://broadrouter.com/ko/guides/langchain-openai-base-url/)
-   [가이드: BroadNet Inference 오류 코드와 재시도해야 하는 경우](https://broadrouter.com/ko/guides/errors-and-retries/)
-   [가이드: 채팅 완성 스트리밍과 끊긴 연결 처리하기](https://broadrouter.com/ko/guides/streaming-chat-completions/)
-   [가이드: 추론 모델이 빈 답변을 반환하는 이유](https://broadrouter.com/ko/guides/reasoning-tokens-empty-response/)
-   [가이드: LiteLLM을 BroadNet Inference에 연결하기(SDK와 프록시)](https://broadrouter.com/ko/guides/litellm-proxy-custom-provider/)

실제 워크로드로 테스트해 보세요. 신규 계정에는 US$5 상당의 초기 크레딧이 제공되며 Gemma 및 음성 전사에 사용할 수 있습니다. DeepSeek, GLM 및 Qwen3.8 모델은 충전이 필요합니다.

[시작하기](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=ko-blog-openai-compatible-api-migration-checklist&utm_content=page-cta) ·

**출처**

-   [BroadNet Inference API 레퍼런스 (영어)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=ko-blog-openai-compatible-api-migration-checklist&utm_content=sources)
-   [OpenAI Python SDK README(base\_url, OPENAI\_BASE\_URL, 재시도; 2026-11-14 확인)](https://github.com/openai/openai-python)
