Chat Completions를 쓰고 있다면 OpenAI에서 OpenAI 호환 제공업체로 앱을 옮기는 것은 작은 코드 변경이고, Responses API를 쓰고 있다면 다시 작성하는 일입니다. 이 글에서는 Python, Node, cURL의 정확한 변경점, Responses, 도구, 구조화된 출력, 임베딩의 처리 방법, 그리고 트래픽을 옮기기 전에 돌릴 스모크 테스트를 보여 드립니다. 예제는 https://inference.broadnet.ai/v1의 BroadNet Inference를 사용하지만, 같은 단계가 어떤 제공업체에도 적용됩니다.
이 글은 속도 제한, 오류, 전환 계획을 다루는 전환 체크리스트의 코드 편입니다. 다른 제공업체의 base URL은 확인을 거친 OpenAI 호환 base URL 목록을 참고하세요.
클라이언트 설정에서는 무엇이 바뀌나요?
base URL, API 키, 모델 ID 세 가지입니다.
Python
import os
from openai import OpenAI
# before: client = OpenAI() # reads OPENAI_API_KEY, calls api.openai.com
client = OpenAI(
base_url="https://inference.broadnet.ai/v1",
api_key=os.environ["BROADNET_API_KEY"],
)
r = client.chat.completions.create(
model="broadnet/gemma-4-26b-a4b", # was e.g. "gpt-..."
messages=[{"role": "user", "content": "Reply with one short sentence."}],
)
print(r.choices[0].message.content)
Node
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://inference.broadnet.ai/v1",
apiKey: process.env.BROADNET_API_KEY,
});
const r = await client.chat.completions.create({
model: "broadnet/gemma-4-26b-a4b",
messages: [{ role: "user", content: "Reply with one short sentence." }],
});
console.log(r.choices[0].message.content);
cURL
curl https://inference.broadnet.ai/v1/chat/completions \
-H "Authorization: Bearer $BROADNET_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"broadnet/gemma-4-26b-a4b","messages":[{"role":"user","content":"Reply with one short sentence."}]}'
경로에 주의하세요. base URL이 이미 /v1로 끝나므로 SDK는 /chat/completions만 덧붙입니다. /v1을 두 번 붙이는 것이 가장 흔한 첫 오류입니다.
코드를 건드리지 않고 전환할 수 있나요?
Chat Completions 코드라면 가능합니다. Python SDK는 base_url이 전달되지 않으면 OPENAI_BASE_URL을 읽고, Node 클라이언트는 baseURL의 기본값을 process.env['OPENAI_BASE_URL']로 둡니다. 둘 다 OPENAI_API_KEY를 읽습니다. 환경 변수 두 개만 설정하면 모든 호출이 옮겨 갑니다.
이것이 바로 위험 요소이기도 합니다. 임베딩, 모더레이션, 파일 업로드 등 새 제공업체에 없을 수 있는 기능까지 모든 호출이 옮겨 갑니다. 환경 변수 방식은 앱이 채팅 호출만 하고 다른 것은 하지 않을 때만 쓰세요.
코드가 Responses API를 쓰고 있다면요?
OpenAI SDK의 README는 이제 Responses API를 기본 API라고 부릅니다. Python README는 Chat Completions를 “the previous standard (supported indefinitely)“(번역: 이전 표준(무기한 지원))라고 부릅니다. 많은 호환 제공업체가 Chat Completions만 구현합니다. BroadNet은 POST /v1/chat/completions와 POST /v1/audio/transcriptions를 문서화하므로, Responses 호출은 다시 작성해야 합니다. 대응 관계는 다음과 같습니다.
| Responses API | Chat Completions |
|---|---|
client.responses.create(...) |
client.chat.completions.create(...) |
instructions="..." |
첫 메시지 {"role": "system", "content": "..."} |
input="..." 또는 항목 목록 |
messages=[...] |
response.output_text |
response.choices[0].message.content |
max_output_tokens |
max_tokens(BroadNet 문서) 또는 max_completion_tokens |
text={"format": {...}} |
response_format={...} |
previous_response_id, 대화(conversations) |
전체 메시지 이력을 직접 다시 전송 |
도구 {"type": "function", "name": ...} |
도구 {"type": "function", "function": {"name": ...}} |
출력 항목 function_call, function_call_output과 call_id로 응답 |
message.tool_calls, role tool과 tool_call_id로 응답 |
| 내장 도구(웹 검색, 파일 검색) | 사용 불가. 도구를 직접 실행 |
간단한 호출의 전후 비교:
# Before: Responses API
r = client.responses.create(model="gpt-...", instructions="Be brief.", input="What is RAG?")
text = r.output_text
# After: Chat Completions
r = client.chat.completions.create(
model="broadnet/gemma-4-26b-a4b",
messages=[{"role": "system", "content": "Be brief."},
{"role": "user", "content": "What is RAG?"}],
)
text = r.choices[0].message.content
가장 큰 구조적 변화는 상태입니다. Responses는 previous_response_id로 대화 상태를 OpenAI 쪽에 유지할 수 있습니다. Chat Completions에는 서버 쪽 상태가 없으므로, 코드가 메시지 목록을 저장하고 매 턴 전부 보내야 합니다. 이 비용을 예산에 반영하세요. 매 호출마다 전체 이력이 입력 토큰이 됩니다.
도구 호출은 어떻게 바뀌나요?
Chat Completions에서는 도구 정의가 함수를 function 키 아래에 중첩하며, 응답은 tool 메시지로 돌려보냅니다.
import json
tools = [{
"type": "function",
"function": {
"name": "get_order",
"description": "Look up an order by ID.",
"parameters": {"type": "object",
"properties": {"order_id": {"type": "string"}},
"required": ["order_id"]},
},
}]
messages = [{"role": "user", "content": "Where is order A-1042?"}]
r = client.chat.completions.create(model="broadnet/glm-5.3", messages=messages, tools=tools)
msg = r.choices[0].message
if msg.tool_calls:
messages.append(msg) # keep the assistant turn
for call in msg.tool_calls:
args = json.loads(call.function.arguments) # a JSON string: parse and validate it
messages.append({"role": "tool", "tool_call_id": call.id,
"content": json.dumps(lookup_order(args["order_id"]))})
r = client.chat.completions.create(model="broadnet/glm-5.3", messages=messages, tools=tools)
형식보다 중요한 것은 모델입니다. BroadNet 문서에는 GLM 5.3과 Qwen3.8 27B에만 도구가 표시되어 있습니다. 문서에 도구가 표시되지 않은 모델에는 도구 루프를 연결하지 말고, 무엇이든 실행하기 전에 인수를 검증하세요. 검증까지 포함한 전체 루프는 오픈 모델의 도구 호출에 있습니다.
구조화된 출력은 어떻게 되나요?
client.chat.completions.parse(..., response_format=MyPydanticModel)과 Node의 zodResponseFormat은 둘 다 JSON 스키마를 담은 response_format을 보냅니다. 제공업체가 해당 모델에서 그 형식을 받을 때만 동작합니다. BroadNet은 GLM 5.3과 Qwen3.8 27B에 구조화된 출력을 표시하지만 요청 파라미터 이름은 밝히지 않습니다. JSON 모드 vs json_schema의 4단계 테스트를 모델마다 한 번씩 돌리고, 제공업체가 무엇을 약속하든 파싱 결과는 계속 검증하세요.
임베딩은 어떻게 되나요?
공유 클라이언트의 base URL을 바꿨는데 제공업체에 임베딩 엔드포인트가 없다면, 모든 client.embeddings.create 호출이 실패합니다. BroadNet은 임베딩을 판매하지 않습니다. 클라이언트를 두 개 두세요.
chat = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])
embed = OpenAI(api_key=os.environ["OPENAI_API_KEY"]) # or any embeddings provider
vec = embed.embeddings.create(model="text-embedding-3-small", input=query).data[0].embedding
answer = chat.chat.completions.create(model="broadnet/glm-5.3", messages=build_prompt(query, search(vec)))
서로 다른 두 임베딩 모델의 벡터를 한 인덱스에 섞지 마세요. 임베딩 제공업체도 바꾼다면 전체 코퍼스를 다시 임베딩하세요. 그 비용은 임베딩 비용 계산기로 계산할 수 있습니다.
이미지 생성, 텍스트 음성 변환(TTS), 모더레이션, Batch API, 파일 저장소처럼 채팅이 아닌 기능에도 같은 원칙이 적용됩니다. BroadNet은 이 중 어느 것도 제공하지 않습니다. 음성 인식은 옮길 수 있습니다. client.audio.transcriptions.create는 WAV 또는 MP3와 language 필드로 /v1/audio/transcriptions에서 동작합니다(아랍어 음성 인식 가이드).
스트리밍 코드는 어떻게 바뀌나요?
Responses API는 response.output_text.delta, response.completed 같은 타입이 지정된 이벤트를 스트리밍합니다. Chat Completions는 청크를 스트리밍하며, 텍스트는 choices[0].delta.content에 담깁니다. usage는 요청하지 않으면 전송되지 않고, 요청하면 choices 목록이 빈 마지막 청크에 담겨 옵니다.
// Before (Responses): for await (const e of stream) if (e.type === "response.output_text.delta") out(e.delta);
const stream = await client.chat.completions.create({
model: "broadnet/gemma-4-26b-a4b",
messages: [{ role: "user", content: "Count from one to three." }],
stream: true,
stream_options: { include_usage: true },
});
for await (const chunk of stream) {
const text = chunk.choices[0]?.delta?.content;
if (text) process.stdout.write(text);
if (chunk.usage) console.log("\ntokens:", chunk.usage.total_tokens); // last chunk
}
전환 후 스트림 코드를 안전하게 지키는 습관이 두 가지 있습니다. usage 청크에는 choices가 없으므로 choices[0]에 방어 코드를 두세요. 그리고 마지막 data: [DONE] 줄 전에 끝난 스트림은 불완전한 것으로 취급하세요. BroadNet 문서는 X-Request-ID를 기록하고 새 요청을 보내도 안전한지 판단하라고 안내합니다. Python 전체 패턴은 Chat Completions 스트리밍에 있습니다.
오류 처리와 재시도도 바뀌나요?
SDK의 오류 클래스는 그대로입니다. 401은 AuthenticationError, 429는 RateLimitError, 나머지는 APIStatusError입니다. 바뀌는 것은 새 제공업체에서 각 상태 코드가 뜻하는 바입니다. BroadNet에서 401은 잘못된 키만이 아니라 종량제 허용량 소진을 뜻할 수도 있고, 402는 구매에 필요한 잔액 부족을 뜻합니다. 둘 다 재시도로는 해결되지 않습니다. 429는 요청 속도, 동시 처리, 토큰 속도, 지출 한도 중 어디서든 올 수 있습니다. 429와 5xx는 백오프로 재시도하고, 나머지는 원인을 고치세요. 전체 표는 오류와 재시도 가이드에 있습니다.
SDK는 연결 오류, 408, 409, 429, 5xx를 기본적으로 두 번 재시도합니다. 자체 재시도 루프를 추가한다면 둘이 겹치지 않도록 클라이언트에 max_retries=0을 설정하세요.
어떤 파라미터가 다르게 동작하나요?
| 파라미터 | 확인할 것 |
|---|---|
max_tokens / max_completion_tokens |
OpenAI는 max_tokens를 지원 중단했지만 BroadNet 문서는 이를 씁니다. 추론 모델에서는 사고 과정이 포함되므로 값이 작으면 빈 답변이 반환됩니다(이유) |
reasoning_effort |
BroadNet은 low를 문서화합니다. 다른 값은 의존하기 전에 테스트하세요 |
stream_options: {"include_usage": true} |
BroadNet이 문서화. usage는 마지막 청크에 담겨 옴 |
n, logprobs, seed, logit_bias |
BroadNet 문서에 없음. 테스트하거나 제거 |
store, metadata |
OpenAI 저장 기능. 제거 |
image_url 콘텐츠 파트 |
이미지 지원이 표시된 모델에서만: DeepSeek V4.1 Flash, Qwen3.8 27B, Gemma 4 VL 26B |
전환은 어떻게 테스트하나요?
트래픽을 옮기기 전에 새 제공업체를 대상으로 짧은 스모크 테스트를 돌리세요. 아래 테스트는 일반 채팅, 스트리밍 usage, 추론 예산, 인증을 확인합니다. 도구를 쓴다면 도구 호출 케이스를 추가하세요.
import os, openai
from openai import OpenAI
client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"], max_retries=0)
FAST, REASONING = "broadnet/gemma-4-26b-a4b", "broadnet/qwen3.8-27b"
msg = [{"role": "user", "content": "Reply with the word ok."}]
# 1. Plain chat returns text and usage
r = client.chat.completions.create(model=FAST, messages=msg)
assert r.choices[0].message.content and r.usage.prompt_tokens > 0
# 2. Streaming reports usage in the last chunk
chunks = list(client.chat.completions.create(model=FAST, messages=msg, stream=True,
stream_options={"include_usage": True}))
assert chunks[-1].usage is not None
# 3. A reasoning model needs room: a tiny budget can come back empty
r = client.chat.completions.create(model=REASONING, messages=msg, max_tokens=2000)
assert r.choices[0].finish_reason == "stop" and r.choices[0].message.content
# 4. A bad key raises AuthenticationError (401), which you should not retry
bad = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key="invalid", max_retries=0)
try:
bad.chat.completions.create(model=FAST, messages=msg)
raise AssertionError("expected 401")
except openai.AuthenticationError:
pass
print("smoke test passed")
그다음에는 형식만이 아니라 품질을 비교하세요. 실제 프롬프트 샘플을 두 제공업체에서 다시 실행하고 답변을 채점합니다. 방법은 모델을 바꾸기 전에 LLM을 평가하는 방법에 있습니다. OpenAI에서 BroadNet으로 전환 도구는 코드 조각을 다시 작성해 주고 어떤 기능을 쓰는지 알려 줍니다.
가장 자주 깨지는 것은 무엇인가요?
- 전역 base URL. 임베딩과 파일 호출까지 함께 옮겨 갑니다.
- Responses 전용 헬퍼. 이제 Chat Completions를 호출하는 코드에
output_text같은 것이 남아 있는 경우입니다. - 모델 ID.
gpt-...이름은 다른 곳에는 없습니다. BroadNet에서는broadnet/glm-5.3같은 형태입니다. - 빈 답변.
max_tokens가 작은 추론 모델에서 나옵니다. - 속도 제한. BroadNet 종량제 키는 분당 요청 30개, 동시 요청 4개까지 허용합니다. 대량 작업에는 큐가 필요합니다(429 처리).
BroadNet Inference는 어디에 적합한가요?
BroadNet Inference는 OpenAI 사용 범위가 채팅과 전사인 앱에 적합합니다. 어시스턴트, 추출, 요약, 번역, 아랍어 음성 인식 같은 경우입니다. 에이전트용으로 DeepSeek V4.1 Flash 정액 플랜을 원하는 앱에도 맞습니다. Responses API의 서버 쪽 상태, 내장 도구, 임베딩, 이미지 생성, 텍스트 음성 변환, 실시간 음성, Batch API에 의존한다면 맞지 않습니다. 그런 기능은 이를 제공하는 제공업체로 옮기거나, OpenAI에 남겨 두고 채팅 호출만 옮기세요. Gemma 4 VL 26B와 두 전사 모델은 $5 상당의 초기 크레딧으로 쓸 수 있고, GLM 5.3, Qwen3.8 27B, DeepSeek V4.1 Flash는 먼저 충전이 필요합니다.
