OpenAI SDK가 필요한 모든 것을 제공하는 이유
사람들이 qwen api sdk를 검색할 때 일반적으로 인증, 재시도, 스트리밍 및 타입 안전 응답을 처리하는 클라이언트 라이브러리를 원합니다. OpenAI SDK는 이미 이를 모두 처리하며, 이 서비스는 동일한 HTTP 인터페이스를 구현합니다: POST /v1/chat/completions, POST /v1/responses 및 GET /v1/models. Base URL을 재정의할 수 있는 클라이언트는 모두 이 서비스에 연결할 수 있습니다.
시작하기 전 한 가지 명확히 하겠습니다. 이는 Alibaba나 다른 모델 벤더의 공식 API가 아니며, 요청을 다른 곳으로 보내는 라우터도 아닙니다. 하나의 오픈 웨이트 모델이며, 독립적인 제공자가 실행하고 법적인 성인 사용에 콘텐츠 거부 없이 답변하도록 튜닝되었습니다. 전달하는 유일한 모델 ID는 uncensored입니다.
이로 인해 마이그레이션이 단순해집니다. 프로젝트가 이미 OpenAI SDK를 통해 호스팅된 채팅 모델을 호출한다면, Base URL, API 키 및 모델 이름 세 가지 값만 변경하면 됩니다. 코드에서 다른 부분은 변경할 필요가 없습니다.
설치 및 첫 번째 호출
Python 또는 Node용 공식 패키지를 설치하세요. 서비스별 추가 설정은 없습니다.
pip install openai
# Node: npm install openai
API 키 페이지에서 키를 생성한 후, 소스 코드에 남지 않도록 내보내세요.
export API_KEY="paste-your-key-here"
이제 가장 작은 유용한 Python 스크립트입니다. 클라이언트는 환경에서 키를 읽은 후 OpenAI가 아닌 서비스에 요청을 보냅니다.
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.uncensoredqwen.com/v1",
api_key=os.environ["API_KEY"],
)
resp = client.chat.completions.create(
model="uncensored",
messages=[
{"role": "system", "content": "You are a concise technical assistant."},
{"role": "user", "content": "Explain what a context window is in two sentences."},
],
temperature=0.7,
)
print(resp.choices[0].message.content)
print(resp.usage)
원시 HTTP를 선호한다면 curl의 동일한 요청은 다음과 같습니다:
curl https://api.uncensoredqwen.com/v1/chat/completions \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"uncensored","messages":[{"role":"user","content":"Say hello."}]}'SDK로 스트리밍 응답 받기
stream=True로 설정하고 청크를 반복하세요. 서비스는 서버 전송 이벤트를 보내고 스트림 끝에 토큰 사용량을 보고하므로, 두 번째 호출 없이 비용을 로깅할 수 있습니다.
import os
from openai import OpenAI
client = OpenAI(base_url="https://api.uncensoredqwen.com/v1",
api_key=os.environ["API_KEY"])
stream = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Write a short product description for a desk lamp."}],
stream=True,
stream_options={"include_usage": True},
)
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
if getattr(chunk, "usage", None):
print("\nTokens:", chunk.usage.prompt_tokens, chunk.usage.completion_tokens)
한 가지 명심하세요: 스트리밍 요청은 스트림이 끝날 때까지 동시성 슬롯을 점유합니다. 소비자가 느리거나 스트림을 닫는 것을 잊으면 예상보다 빨리 동시성 제한에 도달합니다.
Node에서의 동일한 패턴:
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.uncensoredqwen.com/v1",
apiKey: process.env.API_KEY,
});
const stream = await client.chat.completions.create({
model: "uncensored",
messages: [{ role: "user", content: "Name three uses of JSON mode." }],
stream: true,
});
for await (const chunk of stream) {
process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}도구 호출 및 JSON 모드
도구를 위해 이미 사용하는 SDK 파라미터는 그대로 전달됩니다: tools, tool_choice, 스트리밍된 tool_calls, 그리고 role: "tool"로 메시지 형태로 반환되는 결과입니다. 최소 라운드 트립은 다음과 같습니다:
import os, json
from openai import OpenAI
client = OpenAI(base_url="https://api.uncensoredqwen.com/v1",
api_key=os.environ["API_KEY"])
tools = [{
"type": "function",
"function": {
"name": "get_order_status",
"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?"}]
first = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
call = first.choices[0].message.tool_calls[0]
messages.append(first.choices[0].message)
messages.append({
"role": "tool",
"tool_call_id": call.id,
"content": json.dumps({"status": "shipped"}),
})
final = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
print(final.choices[0].message.content)
구조화된 출력을 위해 response_format={"type": "json_object"}를 전달하고 프롬프트에 "JSON으로 응답하세요"라고 명시하세요. JSON 모드는 모델에게 JSON 출력을 요청하지만, 코드에서는 이를 사용하고 필드 이름과 타입을 검증하기 위해 여전히 파싱해야 합니다.
temperature, top_p, stop, seed 및 페널티와 같은 샘플링 설정은 전달되므로 기존 튜닝이 그대로 적용됩니다.
429 오류 처리 및 헤더 읽기
SDK는 HTTP 429 응답 시 속도 제한 예외를 발생시키며, 응답 본문에는 어떤 제한에 도달했는지 알려줍니다. 전체 키는 동시 요청 8개와 분당 300개의 요청을 허용합니다. 체험 키는 동시 요청 2개와 분당 60개의 요청을 허용합니다.
| 오류 코드 | 의미 | 대응 방법 |
|---|---|---|
rate_limited | 분당 요청 수 초과 | 호출을 분산하거나 클라이언트 측 제한기를 추가하세요 |
concurrency | 너무 많은 동시 요청 | 워커 풀을 8로 제한하세요 (체험 키의 경우 2) |
429 응답 시 Retry-After: 5 헤더가 함께 제공됩니다. | 일시적 과부하 | 5초 대기 후 재시도 |
모든 응답에는 X-Request-Id, X-Balance-USD, X-RateLimit-Limit-Requests 및 X-RateLimit-Limit-Concurrency가 포함됩니다. Python SDK로 읽으려면 raw-response 래퍼를 사용하세요:
import os
from openai import OpenAI
client = OpenAI(base_url="https://api.uncensoredqwen.com/v1",
api_key=os.environ["API_KEY"])
raw = client.chat.completions.with_raw_response.create(
model="uncensored",
messages=[{"role": "user", "content": "ping"}],
max_tokens=5,
)
print("Balance:", raw.headers.get("X-Balance-USD"))
print("Request id:", raw.headers.get("X-Request-Id"))
completion = raw.parse()
실패하거나 거부된 요청에는 요금이 부과되지 않으므로, 429 후 재시도해도 두 번 요금이 부과되지 않습니다. 일반적인 Qwen API 실수에 대한 기존 기사에는 사람들이 자주 겪는 설정 오류에 대해 더 자세히 나와 있습니다.
호출 비용
가격은 입력 토큰 100만 토큰당 $0.15, 출력 토큰 100만 토큰당 $0.50이며 선불 크레딧에서 차감됩니다. 프롬프트 토큰 2,000개와 생성 토큰 500개를 가진 요청을 고려해 보세요:
- 입력: 2,000 x $0.15 / 1,000,000 = $0.0003
- 출력: 500 x $0.50 / 1,000,000 = $0.00025
- 합계: $0.00055
$0.50 체험 크레딧은 해당 크기의 약 900개 요청을 처리할 수 있습니다($0.50 / $0.00055는 약 909). 체험은 로그인 후 키 페이지에서 한 번 클릭으로 시작하며, 카드가 필요 없고 7일 동안 유효합니다. 무료 티어 기사에서 작동 방식을 설명합니다. 유료 충전은 $20부터 시작하며, 가격 책정 페이지에는 보너스 티어와 허용된 결제 수단이 나열되어 있습니다.
컨텍스트 창은 프롬프트와 완성을 합쳐 100,000 토큰이며, max_tokens은 선택 사항입니다. 비용의 예측 가능한 상한선을 원할 때 이를 설정하는 것은 좋은 습관입니다.
기존 프로젝트 마이그레이션
대부분의 독자는 이미 채팅 모델을 호출하는 코드를 가지고 도착합니다. 짧은 체크리스트는 전환을 원활하게 유지합니다:
base_url(또는 Node의baseURL)을https://api.uncensoredqwen.com/v1로 변경하세요./v1접미사를 유지하고 SDK가 경로를 추가하므로/chat/completions을 직접 추가하지 마세요.- 계정에서 얻은 키로 기존 키를 교체하세요. 인증은 SDK가 자동으로 생성하는 표준
Authorization: Bearer헤더입니다. - 모델 이름을
uncensored로 교체하세요. 알 수 없는 모델 이름으로 요청하면 실패하므로 코드베이스에서 하드코딩된 이름을 검색하세요. - 서비스에서 제공하지 않는 기능(이미지 입력 또는 임베딩 호출 등)에 대한 요청 필드를 제거하세요.
- 스모크 테스트로
GET /v1/models호출을 실행하세요. 모델이 나열되면 URL과 API 키가 정확합니다.
OpenAI 클라이언트를 감싸는 프레임워크는 일반적으로 openai_api_base 또는 OPENAI_BASE_URL과 같은 이름으로 동일한 두 설정을 노출합니다. 도구가 Base URL용 환경 변수를 제공하는 경우, 소스 코드를 수정하지 않고 전체 애플리케이션을 전환할 수 있습니다. 체험 키로 먼저 테스트하세요. 낮은 동시 요청 제한(2)과 분당 60개 제한으로 인해 계획한 것보다 많은 동시 연결을 열면 앱에서 빠르게 확인할 수 있습니다.
컨텍스트 처리도 다시 살펴볼 가치가 있습니다. 여기에서의 창은 프롬프트와 생성이 공유하는 100,000 토큰입니다. 이전 설정이 이력을 다른 크기로 자른 경우, 그 크기에 맞게 자름을 느슨하게 또는 조밀하게 조정할 수 있지만, 매 턴마다 긴 이력을 다시 보내는 비용에 주의하세요.
프로덕션 코드를 위한 실용적인 팁
- 키를 저장소에 두지 마세요. 위의 예제와 같이 환경 변수 또는 비밀 저장소에서 읽으세요.
- 시간 초과를 설정하세요. SDK는 클라이언트에
timeout인수를 허용합니다. 스트리밍이 있는 긴 생성에는 넉넉한 읽기 시간 초과가 필요합니다. - 워커를 제한하세요. 동시성 제한에 맞춰 조정된 스레드 풀 또는 세마포어는 429 오류를 사전에 방지합니다.
- 요청 ID를 로그에 기록하세요. 지원팀에 문의할 때
X-Request-Id의 값이 호출을 식별합니다. - 잔액을 모니터링하세요. 응답에서
X-Balance-USD을 읽거나GET /v1/balance를 호출하여 크레딧이 떨어지기 전에 배치 작업을 중단하세요.
모델은 텍스트 전용입니다. 이미지, 오디오 또는 비디오 생성, 임베딩, 파인튜닝이 없으므로 해당 SDK 메서드를 계획에 포함하지 마세요. 전체 파라미터 세부 정보는 문서에 있습니다. 프롬프트는 학습에 사용되지 않습니다.
