알리바바의 Qwen 팀은 2026년 5월 중순 Qwen3.7-Max-Preview를 출시했고, 개발자들은 즉시 같은 질문을 던지기 시작했습니다. "내 코드에서 어떻게 호출해야 할까요?" 이 모델은 1M 토큰 컨텍스트 창과 명시적인 사고 연쇄 추적 기능을 갖춘 플래그십 추론 시스템으로, 에이전트 백엔드, 장문 분석, 코드 생성에 매우 적합합니다. 하지만 그 이름의 "미리보기(preview)"라는 단어는 많은 의미를 내포하고 있습니다. 접근이 제한되어 있고, API 표면은 아직 확정되지 않았으며, 작동하는 코드를 작성하는 데 필요한 세부 정보는 릴리스 노트와 플랫폼 문서 전반에 흩어져 있습니다.
요약
Qwen3.7-Max-Preview는 2026년 5월 14일 미리보기(preview)로 출시된 알리바바의 플래그십 추론 모델로, 1M 토큰 컨텍스트 창을 제공합니다. 미리보기 기간 동안 가장 안정적인 사용 방법은 Qwen Chat(chat.qwen.ai)을 이용하는 것입니다. 프로덕션 API 접근은 Alibaba Cloud Model Studio (DashScope)를 통해 OpenAI 호환 엔드포인트를 사용하여 이루어지며, 여기서 기본 URL을 설정하고 키를 Bearer 토큰으로 전달하여 /chat/completions를 호출합니다. 3.7 티어는 미리보기 전용이므로, 출시 전에 공식 문서에서 정확한 모델 ID와 엔드포인트를 확인하고, 가용성이 안정화될 때까지 Apidog를 사용하여 엔드포인트를 테스트하고 모의(mock)하세요.
지금 바로 Qwen 3.7에 접근하는 방법
Qwen은 여러 경로를 통해 모델을 제공하며, 모든 경로가 동시에 활성화되지는 않습니다. 2026년 5월 말 현재 접근 상태는 다음과 같습니다.
Qwen Chat (chat.qwen.ai). Qwen3.7-Max-Preview를 가장 빠르게 사용해 볼 수 있는 방법입니다. 무료 Qwen 계정으로 로그인하고, 모델 선택기에서 qwen3.7-max-preview를 선택한 다음, 사고 모드(Thinking Mode)를 켜서 추론 과정을 확인할 수 있습니다. 미리보기 기간 동안 사용량 제한이 있지만, 비용이 들지 않고 별도의 설정도 필요 없습니다. API가 아닌 브라우저 제품이므로 통합보다는 평가 목적으로 적합합니다.
Alibaba Cloud Model Studio (DashScope). 이곳에서 Qwen 모델은 실제 API가 됩니다. Model Studio는 OpenAI 호환 엔드포인트를 통해 Qwen을 노출하므로, OpenAI SDK와 이미 통신하는 모든 코드는 기본 URL과 키를 교체하여 Qwen을 호출할 수 있습니다. qwen3.6-max-preview 및 qwen-max 제품군과 같은 이전 티어는 이미 이곳에서 사용할 수 있습니다. 이 글을 읽을 때 3.7 미리보기 티어는 아직 공개 API 항목이 없을 수도 있습니다. Qwen은 역사적으로 채팅 미리보기 몇 주 후에 API 접근을 개방했습니다.
OpenAI 호환 패턴. Model Studio의 모든 최신 Qwen 모델은 동일한 형태를 따릅니다. 표준 OpenAI 클라이언트를 DashScope 기본 URL로 지정하고, Bearer 토큰으로 인증한 다음, 채팅 완료(chat completions) 경로를 호출합니다. 이 패턴은 버전 간에 안정적이므로, 3.7 모델 ID가 출시되어도 아래 코드는 계속 작동합니다. 주로 하나의 문자열만 변경하면 됩니다.
미리보기 기간 동안 모델 식별자와 엔드포인트가 변경될 수 있으므로, 공식 Qwen 문서와 Model Studio 모델 목록을 신뢰할 수 있는 정보원으로 삼으십시오. API 접근을 기다리는 동안 무료로 이용할 수 있는 방법으로는 Qwen 3.7을 무료로 사용하는 방법에 대한 저희 가이드에서 미리보기 채널에 대해 자세히 다루고 있습니다.
접근 방법 요약
| 방법 | API 접근 | 비용 | 가장 적합한 용도 |
|---|---|---|---|
| Qwen Chat (chat.qwen.ai) | 아니요 | 무료, 속도 제한 | 빠른 평가, 프롬프트 테스트 |
| Alibaba Cloud Model Studio (DashScope) | 예, OpenAI 호환 | 토큰당 지불 | 프로덕션 통합 |
| Hugging Face의 Qwen | 릴리스 시 가중치 | 무료 (자체 호스팅) | 오픈 가중치 모델 (Max 미리보기 제외) |
| 타사 게이트웨이 | 다양함 | 다양함 | 다중 모델 라우팅 |
주목할 만한 한 가지 차이점: 오픈 가중치 Qwen 모델은 Hugging Face에 도달하지만, Max-Preview 티어는 독점적이므로 qwen3.7-max-preview에 대한 다운로드 가능한 가중치는 기대하지 마십시오.
Qwen 3.7 API 키 얻기
API 접근은 Alibaba Cloud 계정을 통해 이루어집니다. 단계는 간단합니다.
- Alibaba Cloud 계정을 생성하고 Model Studio 콘솔(
modelstudio.console.alibabacloud.com)을 엽니다. - 귀하의 계정 및 지역에 대해 Model Studio를 활성화합니다. 키는 지역 범위이므로 싱가포르 엔드포인트용 키는 베이징에 대해 인증되지 않습니다.
- 콘솔의 API 키 섹션을 열고 키를 생성합니다.
sk-다음에 문자열이 오는 형태입니다. - 키를 한 번 복사하여 비밀번호처럼 보관합니다.
기본 URL을 설정하므로 지역을 신중하게 선택하세요:
| 지역 | 기본 URL |
|---|---|
| 싱가포르 | https://dashscope-intl.aliyuncs.com/compatible-mode/v1 |
| 미국 (버지니아) | https://dashscope-us.aliyuncs.com/compatible-mode/v1 |
| 베이징 (중국) | https://dashscope.aliyuncs.com/compatible-mode/v1 |
커밋할 소스 코드에 키를 하드코딩하지 마십시오. 대신 환경 변수에 저장하세요:
# macOS / Linux
export DASHSCOPE_API_KEY="sk-your-key-here"
# Windows PowerShell
setx DASHSCOPE_API_KEY "sk-your-key-here"
귀하의 코드는 런타임에 DASHSCOPE_API_KEY를 읽습니다. 이렇게 하면 비밀이 리포지토리에서 제외되고 코드를 건드리지 않고도 키를 순환할 수 있습니다. 어떤 모델을 호출하든 동일한 습관이 적용됩니다. Gemini 3.5 API 가이드에서도 동일한 패턴을 볼 수 있습니다.
첫 번째 요청: Python, curl, JavaScript
Qwen의 Model Studio 엔드포인트는 OpenAI와 호환되므로 두 가지 옵션이 있습니다: DashScope 기본 URL을 가리키는 공식 OpenAI SDK를 사용하거나, 원시 HTTP 호출을 사용하는 것입니다. 두 가지 방법 모두 아래에 설명되어 있습니다.
코드에 앞서 한 가지 유의할 점이 있습니다. 모델 ID qwen3.7-max-preview는 Qwen Chat이 미리보기 모델에 사용하는 식별자입니다. API가 예상하는 정확한 문자열은 미리보기 기간 동안 다를 수 있으며, qwen3.6-max-preview와 같은 이전 티어가 이 시점에 활성화되어 있을 수 있습니다. Model Studio 모델 목록에서 현재 모델 ID를 확인한 다음, model 필드에 입력하십시오. 요청 형태는 변경되지 않습니다.
OpenAI SDK를 이용한 Python
pip install openai로 SDK를 설치한 후 요청을 보냅니다:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["DASHSCOPE_API_KEY"],
# 계정 지역에 맞는 기본 URL을 사용하세요
base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)
response = client.chat.completions.create(
# Model Studio 모델 목록에서 실제 모델 ID를 확인하세요
model="qwen3.7-max-preview",
messages=[
{"role": "system", "content": "당신은 정확한 코딩 도우미입니다."},
{"role": "user", "content": "연결 리스트를 역순으로 만드는 Python 함수를 작성하세요."},
],
)
print(response.choices[0].message.content)
이것이 완전한 요청입니다. messages 배열은 표준 역할 패턴을 따릅니다: system 메시지가 동작을 설정하고, 이어서 user 차례가 옵니다. 응답은 생성된 텍스트를 choices[0].message.content에 담아 전달합니다.
curl
터미널에서 빠른 확인을 하거나, 앱 코드를 작성하기 전에 키가 작동하는지 확인하려면:
curl 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "qwen3.7-max-preview",
"messages": [
{"role": "user", "content": "REST API에서 멱등성을 두 문장으로 설명하세요."}
]
}'
키와 모델 ID가 유효하면, 완료된 JSON 응답을 받게 됩니다. 그렇지 않으면 오류 본문이 무엇을 수정해야 할지 알려줍니다. 오류에 대한 자세한 내용은 아래를 참조하세요.
JavaScript / Node.js
동일한 OpenAI SDK가 Node에서도 작동합니다. npm install openai로 설치하세요:
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.DASHSCOPE_API_KEY,
baseURL: "https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
});
const response = await client.chat.completions.create({
model: "qwen3.7-max-preview",
messages: [
{ role: "user", content: "GraphQL과 REST의 장단점 세 가지를 나열하세요." },
],
});
console.log(response.choices[0].message.content);
세 가지 언어, 하나의 요청 형태; 이것이 OpenAI 호환 API의 장점입니다.
스트리밍 응답
사용자에게 보이는 모든 것에 대해, 전체 완료가 되기 전에 출력을 보여주고 싶지 않을 것입니다. 스트리밍은 토큰이 생성되는 즉시 전송합니다. stream을 true로 설정하고 청크를 반복하세요.
stream = client.chat.completions.create(
model="qwen3.7-max-preview",
messages=[
{"role": "user", "content": "CAP 이론을 요약하세요."},
],
stream=True,
)
for chunk in stream:
delta = chunk.choices[0].delta.content
if delta:
print(delta, end="", flush=True)
Node에서는 스트리밍 응답이 비동기 이터러블(async iterable)입니다:
const stream = await client.chat.completions.create({
model: "qwen3.7-max-preview",
messages: [{ role: "user", content: "CAP 이론을 요약하세요." }],
stream: true,
});
for await (const chunk of stream) {
process.stdout.write(chunk.choices[0]?.delta?.content || "");
}
스트리밍은 일반 채팅 모델보다 추론 모델에서 더 중요합니다. Qwen 3.7은 최종 답변 전에 사고 연쇄에 실제 시간을 할애할 수 있으므로, 스트리밍이 없으면 사용자는 빈 화면만 바라보게 됩니다. 스트리밍을 사용하면 사고 추적, 타이핑 표시기 또는 답변이 형성되는 과정을 보여줄 수 있습니다.
추론 및 사고 매개변수
Qwen3.7-Max-Preview는 추론 모델입니다. 최종 답변을 확정하기 전에 <think> 블록 내부에 명시적인 사고 연쇄를 생성할 수 있습니다. 이 추적은 수학 및 복잡한 다단계 문제에서 모델의 점수를 높이며, 디버깅에도 도움이 됩니다. 모델의 논리가 어디에서 잘못되었는지 확인할 수 있습니다.
DashScope를 통해 제공되는 최신 Qwen 모델에서는 enable_thinking 플래그로 사고 동작을 제어합니다. Qwen 버전 간에 추론 제어 방식이 변경되었으므로, 3.7 미리보기 티어에 대한 정확한 메커니즘과 매개변수 이름은 현재 API 참조를 확인하십시오. 개념적으로 요청은 다음과 같습니다:
response = client.chat.completions.create(
model="qwen3.7-max-preview",
messages=[
{"role": "user", "content": "오후 2시에 평균 시속 60마일로 기차가 출발합니다. "
"두 번째 기차는 오후 3시에 동일한 경로에서 시속 75마일로 출발합니다. "
"두 번째 기차는 언제 첫 번째 기차를 따라잡습니까?"},
],
# 추론 제어는 Qwen 버전에 따라 다릅니다; 현재
# 매개변수는 Model Studio API 참조에서 확인해야 합니다.
extra_body={"enable_thinking": True},
)
print(response.choices[0].message.content)
몇 가지 실용적인 참고 사항:
- 사고는 토큰과 시간을 소모합니다. 추론 추적은 생성된 텍스트입니다. 이는 출력에 포함되며 지연 시간을 추가합니다. 간단한 조회 또는 서식 지정의 경우 사고를 끄십시오.
- 어려운 문제에는 켜세요. 다단계 수학, 까다로운 엣지 케이스가 있는 코드, 계획 및 분석은 사고 연쇄가 그 가치를 발휘하는 부분입니다.
- 추적을 표시할지 여부를 결정하세요. 일부 앱은
<think>콘텐츠를 노출하여 사용자가 모델의 작업을 볼 수 있도록 하고, 다른 앱은 이를 제거하고 최종 답변만 보여줍니다. 둘 다 유효합니다.
추론 품질과 비용을 다른 최첨단 모델과 비교한다면, Qwen 3.7 vs GPT-5.5 vs Opus 4.7 비교 글에서 장단점을 나란히 비교해 놓았습니다. 추론 모델은 에이전트 루프에서 토큰을 빠르게 소모할 수 있습니다. 이러한 상황이라면 에이전트 토큰 비용을 줄이는 방법에 대한 저희 글의 기술이 직접적으로 적용됩니다.
오류 처리 및 속도 제한
요청은 예측 가능한 이유로 실패할 수 있습니다. 앱이 우아하게 성능 저하를 보이도록 이를 처리하세요.
| HTTP 상태 | 의미 | 조치 |
|---|---|---|
| 400 | 잘못된 요청: 잘못된 형식의 JSON, 유효하지 않은 매개변수 | 요청 본문을 수정하고, 모델 ID 및 필드 이름을 확인하세요 |
| 401 | 유효하지 않거나 누락된 API 키 | 키를 확인하고 엔드포인트 지역과 일치하는지 확인하세요 |
| 403 | 모델에 대한 접근 권한 없음 | 미리보기 티어가 제한될 수 있습니다. 계정 활성화 여부를 확인하세요 |
| 404 | 모델을 찾을 수 없음 | 모델 ID가 잘못되었거나 해당 지역에서 사용할 수 없습니다 |
| 429 | 속도 제한 또는 할당량 초과 | 대기 후 재시도하세요. QPS 제한 및 계정 잔액을 확인하세요 |
| 500 / 503 | 서버 측 오류 | 지수 백오프(exponential backoff)로 재시도하세요 |
미리보기 모델은 접근이 제한되고 식별자가 변경되므로 안정적인 모델보다 403 및 404 오류가 더 자주 발생합니다. 이러한 오류가 발생하면 일반적으로 코드 문제가 아니라 접근 권한 또는 모델 문자열 문제입니다.
Model Studio의 속도 제한은 초당 또는 분당 쿼리 수로 계정별로 설정되며, 정확한 수치는 계정 티어와 모델에 따라 다릅니다. 고정된 값을 가정하기보다는 콘솔에서 확인하세요. 패턴은 동일합니다: 429를 잡고, 대기한 다음, 점진적으로 지연 시간을 늘려 재시도합니다.
import time
from openai import OpenAI, RateLimitError, APIStatusError
client = OpenAI(
api_key=os.environ["DASHSCOPE_API_KEY"],
base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)
def ask_qwen(prompt, max_retries=4):
for attempt in range(max_retries):
try:
response = client.chat.completions.create(
model="qwen3.7-max-preview",
messages=[{"role": "user", "content": prompt}],
)
return response.choices[0].message.content
except RateLimitError:
wait = 2 ** attempt # 1초, 2초, 4초, 8초
print(f"속도 제한에 걸렸습니다. {wait}초 후에 재시도합니다...")
time.sleep(wait)
except APIStatusError as e:
# 400/401/403/404는 재시도할 가치가 없습니다; 이를 노출하세요
print(f"API 오류 {e.status_code}: {e.message}")
raise
raise RuntimeError("재시도 후 실패했습니다.")
429 및 5xx 오류에는 지수 백오프를, 4xx 오류에는 빠른 실패를 적용합니다. 이러한 분리를 통해 재시도로 해결되지 않을 오류에 대해 API를 계속 호출하는 것을 방지할 수 있습니다.
Apidog를 이용한 Qwen API 테스트 및 모의(Mocking)
여기서 미리보기 API는 고통스러워지고, 좋은 툴링이 빛을 발합니다. 접근이 제한되고, 모델 ID가 계속 바뀌며, 속도 제한이 엄격할 때, 전체 앱을 실행하고 로그를 읽는 방식으로 테스트하고 싶지 않을 것입니다. 요청을 보내고, 정확히 무엇이 돌아오는지 확인하고, 다시 실행하기 위해 보관하고 싶을 것입니다. Apidog는 이러한 루프를 위해 만들어졌습니다.
개발 중에 엔드포인트를 모의(Mock)하세요. 이것은 제한된 미리보기에 있어 매우 중요합니다. Apidog의 모의 서버는 API 스키마에서 현실적인 응답을 키나 속도 제한 없이 반환합니다. 따라서 실제 미리보기 접근이 제한되거나, 중단되거나, 아직 계정에 열리지 않았을 때도 프론트엔드 또는 에이전트는 항상 즉시 응답하는 Qwen 임시 엔드포인트에 대해 개발할 수 있습니다. 실제 API가 준비되면 기본 URL을 모의 서버에서 DashScope로 전환하기만 하면 코드는 변경되지 않습니다. 스키마 우선 워크플로우에 대한 자세한 내용은 스키마 우선 모드 둘러보기를 참조하세요.
이 패턴은 모든 모델 API에 일반화됩니다. Qwen, Gemini 또는 ERNIE 5.1 API를 호출하든 Apidog의 동일한 테스트 및 모의 루프가 작동합니다. 미리보기 모델은 실제 엔드포인트가 스택에서 가장 신뢰할 수 없는 부분이므로 모의 단계를 더욱 가치 있게 만듭니다.
결론
경로를 알면 Qwen 3.7 호출은 간단합니다. 문제는 API 자체가 아니라 미리보기 제한 때문입니다.
Qwen이 무엇을 반환할지 추측하지 말고 직접 확인하세요. Apidog를 다운로드하여 Qwen 엔드포인트를 설계하고, 실제 테스트 요청을 보내고, 재사용 가능한 시나리오를 저장하며, 개발 중에 API를 모의(mock)하세요. 무료로 시작할 수 있으며, 불안정한 미리보기를 자신감을 가지고 개발할 수 있는 대상으로 바꿔줍니다.