OpenAI에서 옮겨오기
Kiln은 OpenAI 형식의 엔드포인트를 제공하므로, 값 세 개만 바꾸면 기존 OpenAI 클라이언트가 그대로 연결됩니다. 이 페이지는 무엇이 바뀌는지, 아직 적용되지 않는 것이 무엇인지, 운영 트래픽을 옮기기 전에 확인할 항목을 정리합니다.
클라이언트 설정
같은 호출의 변경 전후입니다. base_url, API 키, 모델 ID만 다릅니다.
변경 전(OpenAI)
from openai import OpenAI
client = OpenAI(api_key="sk-...")
resp = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "Write a haiku about kilns."}],
max_tokens=800,
)변경 후(Kiln)
from openai import OpenAI
client = OpenAI(api_key="sk-bk-...", base_url="https://api.bricksum.com/v1")
resp = client.chat.completions.create(
model="qwen3-32b",
messages=[{"role": "user", "content": "Write a haiku about kilns."}],
max_tokens=800,
)- base_url은 Kiln 엔드포인트를 가리킵니다. SDK가 경로를 붙이므로 /chat/completions를 직접 붙이지 마세요.
- API 키는 콘솔에서 발급한 Kiln 키입니다. OpenAI 키는 사용할 수 없습니다.
- 모델 ID는 Kiln 카탈로그의 값입니다. 카탈로그에 없는 ID는 404로 거부됩니다.
알려진 제한
현재 서빙 스택은 모든 OpenAI 파라미터를 완전히 지원하지는 않습니다. 다음 사항에 유의하세요.
- response_format(json_object, json_schema)은 아직 지원하지 않습니다. 요청은 수락되지만 content가 비어 반환됩니다. JSON이 필요하면 프롬프트로 지시하고 클라이언트에서 파싱·검증하세요.
- stop 시퀀스는 아직 적용되지 않습니다. stop 문자열 이후에도 생성이 계속됩니다.
- tool_choice: required·함수 지정과 parallel_tool_calls는 모델 페이지의 지원 기능 표에 "지원"으로 표시된 모델에서만 적용됩니다. qwen3-32b에서는 강제 툴 선택이 명확한 에러 없이 실패합니다(2026-09-26 실측). tool_choice를 "required"로 보내면 본문이 평문 "Internal Server Error"인 HTTP 500이 오고, 함수를 지정하면 arguments가 빈 200(finish_reason "stop")이 옵니다. 둘 다 4xx가 아니므로 재시도로 해결되지 않습니다. tool_choice는 "auto"만 보내세요. qwen3-32b에서는 parallel_tool_calls 설정이 적용되지 않습니다. 이는 응답에 툴 호출이 하나만 온다는 뜻이 아닙니다. parallel_tool_calls: false를 보내도 한 응답에 툴 호출이 여러 건 올 수 있습니다. tool_calls의 모든 항목에 각각 tool 메시지로 답하세요. description이 없는 함수는 400으로 거부됩니다.
- finish_reason: "length"(max_tokens로 생성이 잘린 경우)에는 비스트리밍 응답의 content가 비어 있을 수 있습니다. max_tokens를 여유 있게 설정하거나 스트리밍을 사용하세요.
- 게이트웨이는 요청을 60분 뒤에 종료합니다. 비스트리밍 요청은 완료될 때까지 바이트를 보내지 않으며, 네트워크 엣지가 이런 연결을 약 100초 뒤에 끊을 수 있습니다. 긴 생성은 stream: true로 보내세요.
자동·강제·병렬 툴 선택을 어떤 모델이 지원하는지는 모델 페이지의 지원 기능 표에 모델별로 정리되어 있습니다.
점검 목록
- base_url, API 키, 모델 ID를 바꿉니다.
- 코드에서 response_format과 stop을 찾아 위 설명대로 대체합니다.
- max_tokens를 여유 있게 설정하고, 긴 생성은 stream: true로 보냅니다.
- 에러 처리는 message 문구가 아니라 HTTP 상태와 error.code로 분기합니다.
- 429와 5xx는 백오프로 재시도하고, 응답에 x-ratelimit-reset이 있으면 그 값을 읽습니다.
- 운영 트래픽을 옮기기 전에 모델 ID 하나로 테스트를 돌립니다.