Qwen 시리즈

Alibaba Cloud Qwen(통의천문)의 텍스트 모델로 Qwen3.8, Qwen3.7, Qwen3.6 시리즈와 Qwen Flash, Qwen Plus가 있습니다. OpenAI 호환 API로 호출하며, Qwen3.x 시리즈는 Anthropic 네이티브 API도 지원합니다. 이미지 생성 모델은 Qwen-Image를 참고하십시오.

주요 작업

모델

전체 모델 목록과 실시간 가격은 모델 페이지 를 참고하거나 Models API로 조회하십시오. 모델 ID에서 qwen/ 접두사를 생략할 수 있습니다.

Qwen 모델은 Alibaba Cloud Model Studio(百炼)가 제공하며, 중국 사이트(aliyun)와 국제 사이트(alicloud) 두 공급자가 있고 기본적으로 자동 선택됩니다. 지정 방법은 공급자 라우팅을 참고하십시오.

호출 예시

import os
from openai import OpenAI
 
client = OpenAI(base_url="https://api.ofox.io/v1", api_key=os.environ["OFOX_API_KEY"])
 
resp = client.chat.completions.create(
    model="qwen/qwen3.8-flash",
    messages=[{"role": "user", "content": "멱등성이 무엇인지 한 문장으로 설명해 주세요."}],
    extra_body={"enable_thinking": False},
)
print(resp.choices[0].message.content)

curl https://api.ofox.io/v1/chat/completions \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen/qwen3.8-flash",
    "messages": [{"role": "user", "content": "멱등성이 무엇인지 한 문장으로 설명해 주세요."}],
    "enable_thinking": false
  }'

사고 모드

같은 수학 문제로 실측한 결과, Qwen3.8 Flash는 기본 설정으로 약 5800 토큰을 사고하며 약 1.5분이 걸렸고, Qwen3.6 Flash는 기본 설정으로 3만 토큰 이상을 사고하며 4분 이상 걸렸습니다. 사고를 끄면 둘 다 몇 초 안에 응답했습니다.

사고 길이 제한

사고는 필요하지만 소요 시간과 비용을 제어하고 싶다면 thinking_budget(사고 토큰 상한)을 전달하십시오.

import os
from openai import OpenAI
 
client = OpenAI(base_url="https://api.ofox.io/v1", api_key=os.environ["OFOX_API_KEY"])
 
resp = client.chat.completions.create(
    model="qwen/qwen3.8-flash",
    messages=[{"role": "user", "content": "n² + n + 41이 소수가 아닌 50 미만의 양의 정수 n을 모두 찾아 주세요."}],
    extra_body={"enable_thinking": True, "thinking_budget": 1000},
)
msg = resp.choices[0].message
details = getattr(msg, "reasoning_details", None) or []
print("[사고]", "".join(d.get("text", "") for d in details)[:200], "…")
print("[답변]", msg.content)
print("사고 토큰:", resp.usage.completion_tokens_details.reasoning_tokens)

• 실측 결과 thinking_budget은 엄격하게 적용됩니다. 200으로 설정하면 사고 토큰이 정확히 200입니다.
• enable_thinking, thinking_budget은 OpenAI SDK의 표준 파라미터가 아니므로 extra_body에 넣으십시오. HTTP 요청을 직접 보낼 때는 요청 본문 최상위에 넣습니다.
• 사고 토큰은 출력 단가로 과금되며, 수량은 usage.completion_tokens_details.reasoning_tokens에서 확인할 수 있습니다.

사고 내용 읽기

• 스트리밍 응답에서는 사고 내용이 delta.reasoning_content에 있으며, Alibaba Cloud Model Studio 공식 API와 같습니다.
• 비스트리밍 응답에서는 사고 내용이 message.reasoning_details에 있으며, 각 항목의 text를 순서대로 이어 붙이십시오(위 예시 참고).

이미지 입력

이미지 입력을 지원하는 모델은 표준 image_url 콘텐츠 블록을 사용합니다.

import base64
import os
from openai import OpenAI
 
client = OpenAI(base_url="https://api.ofox.io/v1", api_key=os.environ["OFOX_API_KEY"])
img_b64 = base64.b64encode(open("photo.png", "rb").read()).decode()
 
resp = client.chat.completions.create(
    model="qwen/qwen3.8-flash",
    messages=[{"role": "user", "content": [
        {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{img_b64}"}},
        {"type": "text", "text": "이 이미지를 설명해 주세요."},
    ]}],
    extra_body={"enable_thinking": False},
)
print(resp.choices[0].message.content)

Qwen3.7 Max, Qwen Plus, Qwen Flash는 텍스트만 지원하므로, 위 표에서 이미지 입력을 지원하는 모델을 사용하십시오.

Claude Code에서 사용

Qwen3.x 시리즈와 Qwen Flash는 Anthropic 네이티브 API를 지원하며, 주소는 https://api.ofox.io/anthropic입니다.

• Anthropic API로 호출하면 사고 내용이 thinking 블록으로 반환됩니다.
• Qwen3.8 시리즈는 사고량이 많으므로 max_tokens를 충분히 크게 설정하십시오. 실측 결과 max_tokens가 4000이면 응답에 답변 없이 thinking 블록만 있을 수 있습니다.
• Qwen Plus는 Anthropic API를 지원하지 않으며, 호출하면 protocol_not_supported가 반환됩니다.

Claude Code의 전체 설정 방법은 Claude Code 설정을 참고하십시오.

JSON 출력과 도구 호출

response_format은 {"type": "json_object"}와 {"type": "json_schema", ...}를 지원하며, 도구 호출에는 표준 tools 파라미터를 사용합니다. json_object를 사용할 때는 프롬프트에 「JSON으로 반환」과 필요한 필드를 명시하십시오. 작성법은 구조화된 출력과 함수 호출을 참고하십시오.

프롬프트 캐싱

Qwen은 반복되는 요청 접두부를 자동으로 캐시하므로 요청을 수정할 필요가 없습니다. 적중량은 usage.prompt_tokens_details.cached_tokens에서 확인할 수 있으며, 적중한 부분은 캐시 읽기 단가로 과금됩니다. 캐시는 최선형(best effort)이므로 접두부가 같은 요청도 적중하지 않을 수 있습니다.

자주 발생하는 오류

기타 일반 오류는 오류 처리를 참고하십시오.

공식 문서

• Alibaba Cloud Model Studio · 모델 목록 
• Alibaba Cloud Model Studio · 심층 사고 
• Alibaba Cloud Model Studio · OpenAI 호환 

공식 문서는 Alibaba Cloud Model Studio에 직접 연결할 때의 동작을 설명합니다. OfoxAI에서 호출할 때는 모델 ID와 엔드포인트 주소를 이 페이지 기준으로 사용하십시오.

자주 묻는 질문