Qwen API는 알리바바 클라우드의 바이리엔(Model Studio)이 제공하며 DashScope가 원시 인터페이스 체계입니다. 바이리엔은 OpenAI 호환 인터페이스와 DashScope 원시 인터페이스를 함께 제공합니다. 대부분의 팀에는 OpenAI 호환 인터페이스가 가장 간편합니다. 기존 SDK, Agent 프레임워크, 도구 체인에서 보통 API 키, Base URL, 모델명 세 곳만 바꾸면 됩니다.

진짜 함정은 "호출이 되는가"가 아니라 Base URL의 지역, 모델명이 유효한지, 스트리밍 출력을 어떻게 파싱하는지, OpenAI에서 이전할 때 어떤 파라미터를 그대로 가져오면 안 되는지입니다. 이 글은 최소 요청으로 경로를 실행한 뒤 도구 호출, 오류 해결, 이전 체크리스트를 보충합니다.

안내: Qwen, 통이첸원, 알리바바 클라우드, 바이리엔(Model Studio), DashScope는 알리바바 그룹 및 그 계열사의 상표 또는 제품명이며 이 글은 기술 설명만 제공합니다. 알리바바 그룹과 소속, 대리, 인증 관계가 없습니다. Base URL, 모델명, 컨텍스트 길이, 과금 기준은 조정될 수 있으므로 알리바바 클라우드 바이리엔 공식 문서와 사이트 내 모델 가격을 기준으로 하세요.

1. 연동 전 준비

시작 전에 세 가지를 확인하세요.

  • 사용 가능한 API 키가 있고 목표 지역과 맞는지.
  • 올바른 Base URL이 있고 중국 본토, 국제 사이트, 게이트웨이 주소를 섞지 않았는지.
  • 현재 실제로 사용 가능한 모델명이 있고 오래된 글의 예시를 그대로 복사하지 않았는지.

먼저 curl로 인증과 네트워크를 검증한 뒤 SDK를 연동하는 편이 좋습니다. 그래야 오류가 났을 때 키, 주소, 코드 중 어디가 문제인지 판단하기 쉽습니다.

2. Base URL: 지역을 먼저, 도메인을 다음에

OpenAI 호환 인터페이스 경로는 /compatible-mode/v1로 고정되어 있고 채팅 인터페이스는 여기에 /chat/completions를 붙입니다. 도메인은 지역에 따라 구분하며 흔한 표기는 다음과 같습니다.

시나리오 OpenAI 호환 Base URL 설명
중국 본토(베이징, 구 공유 도메인) https://dashscope.aliyuncs.com/compatible-mode/v1 기존 코드와 호환, 현재도 사용 가능
싱가포르(국제 사이트) https://dashscope-intl.aliyuncs.com/compatible-mode/v1 국제 사이트 계정과 키
미국 버지니아 https://dashscope-us.aliyuncs.com/compatible-mode/v1 IPv4 전용, 기능은 문서 기준
중국 홍콩 https://cn-hongkong.dashscope.aliyuncs.com/compatible-mode/v1 독립 지역과 키
업무 공간 전용 https://{WorkspaceId}.{region}.maas.aliyuncs.com/compatible-mode/v1 운영 권장, 처리량과 격리가 더 좋음
ZSQH AI 게이트웨이 https://ai.zhongshangqihang.com/v1 멀티모델 통합 진입점

핵심은 세 가지입니다. 첫째, API 키는 지역에 묶여 있어 다른 지역에서 호출하면 보통 401과 invalid_api_key가 반환됩니다. 이는 키와 주소가 맞지 않는다는 뜻이지 키가 무효라는 뜻은 아닙니다. 둘째, 중국 본토 계정과 국제 사이트 계정은 두 체계이며 키, 청구, 모델 목록이 호환되지 않습니다. 셋째, 업무 공간 전용 도메인은 해당 공간의 키만 받지만 처리량과 트래픽 격리가 좋아 운영 환경에 적합합니다. 구 공유 도메인은 공간을 넘나들기 쉽고 빠른 테스트에 편리합니다.

여러 모델을 함께 쓰면서 지역, 할당량, 여러 키를 직접 관리하고 싶지 않다면 ZSQH AI 게이트웨이에서 통합 키를 만들고 Base URL을 표의 마지막 주소로 바꾸세요.

3. 모델명 선택

바이리엔의 모델 목록은 빠르게 갱신됩니다. 현재 공식 모델 페이지를 예로 들면 텍스트 생성 부분에 qwen3.8-max, qwen3.7-plus, qwen3.8-flash가 있습니다. 이름에서 대략 max는 능력 상한, plus는 균형, flash는 저지연과 비용에 치우친다고 이해할 수 있습니다. 구체적인 포지션과 컨텍스트 길이는 공식 모델 문서를, 가격은 모델 가격 페이지를 기준으로 하세요.

선정할 때 "가장 강한" 모델만 보지 마세요. 고객지원 질의응답, 대량 분류, 콘텐츠 검수 같은 작업은 저지연 등급이 더 경제적인 경우가 많고 장문 문서 분석과 복잡한 Agent에 상위 등급을 씁니다. 모델명을 코드에 하드코딩하지 말고 설정 항목으로 만들면 이후 전환이 훨씬 쉬워집니다.

놓치기 쉬운 함정이 두 가지 더 있습니다. 오래된 튜토리얼의 qwen-max, qwen-plus 표기는 이미 조정되었을 수 있으므로 연동 전에 콘솔 모델 목록에서 확인하세요. 벡터 기능이 필요하면 embedding 시리즈(예: qwen3.7-text-embedding)를 쓰는데 채팅 인터페이스와 요청 본문이 같지 않습니다. Qwen-Audio는 OpenAI 호환 프로토콜을 지원하지 않으므로 DashScope 원시 인터페이스를 써야 합니다.

4. curl로 첫 호출 실행

먼저 환경 변수를 준비해 키가 명령 기록에 남지 않게 하세요.

export DASHSCOPE_API_KEY="your_key_here"

curl https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.8-max",
    "messages": [
      {"role": "system", "content": "당신은 간결한 기술 어시스턴트입니다."},
      {"role": "user", "content": "API 게이트웨이가 무엇인지 세 문장으로 설명하세요."}
    ],
    "temperature": 0.7
  }'

정상 반환 시 세 필드를 중점적으로 보세요. choices[0].message.content는 답변, usage는 이번 사용량, finish_reason은 종료 이유입니다. 401이면 키와 지역을, 404와 ModelNotFound면 모델명과 해당 지역에서 모델이 개통되었는지 먼저 확인하세요.

5. Python SDK 호출과 스트리밍 출력

OpenAI SDK 1.0 이상이 필요합니다. Base URL을 바이리엔으로 지정하면 호출 방식은 OpenAI와 거의 같습니다.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

stream = client.chat.completions.create(
    model="qwen3.8-max",
    messages=[{"role": "user", "content": "100자 이내의 제품 소개를 작성하세요."}],
    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)

스트리밍에서 주의할 점이 있습니다. 첫 chunk에는 역할 정보만 있고 content가 비어 있을 수 있으므로 모든 chunk에 텍스트가 있다고 가정하지 마세요. stream_options={"include_usage": True}를 추가하면 사용량이 마지막 chunk에 나타납니다. HTTP 직접 연결 시 응답은 SSE 형식이고 data: [DONE]으로 끝납니다. 사용자가 페이지를 닫으면 서버가 업스트림 요청을 빨리 취소해 계속 생성과 과금을 막아야 합니다.

6. 도구 호출과 파라미터 차이

도구 호출은 OpenAI의 tools와 tool_choice 형식을 따릅니다. 모델이 message.tool_calls를 반환하면 각 호출의 function.arguments를 JSON으로 파싱해 로컬 함수를 실행하고 결과를 role: "tool" 메시지로 되돌려 보내야 합니다. 멀티턴 흐름에서는 매 턴 요청에 tools를 포함해야 합니다. 운영 환경에서는 파라미터 검증, 권한 검증, 타임아웃 제어를 해야 하며 모델이 생성한 파라미터를 그대로 신뢰하면 안 됩니다.

공식 호환 문서에는 현재 도구에 두 가지 제한이 있습니다. 일부 모델만 지원하며 tools를 stream=True와 동시에 사용할 수 없습니다. 모델 목록과 능력은 계속 갱신되므로 출시 전에 대상 모델로 반드시 실측하세요. 업무상 스트리밍과 도구 호출을 동시에 해야 한다면 DashScope 원시 인터페이스를 쓰거나 도구 호출을 비스트리밍 단계로 분리하는 방안을 고려하세요.

OpenAI에서 이전할 때 다음 파라미터 차이도 주의하세요.

  • messages: messages[0]만 system 역할이 될 수 있습니다. user와 assistant는 보통 번갈아 나오며 마지막은 반드시 user여야 합니다.
  • temperature: 범위는 [0, 2)이며 공식적으로 0을 권장하지 않습니다.
  • top_p: 범위는 (0, 1.0)입니다.
  • seed: 부호 없는 64비트 정수를 씁니다.
  • stop: 배열 원소에 토큰 ID와 문자열을 섞을 수 없습니다.
  • system_fingerprint: 현재 빈 문자열을 반환합니다.
  • enable_search 등 확장 파라미터: 보통 extra_body로 전달하며 모든 모델이 지원하지는 않습니다.
  • response_format, frequency_penalty 등 필드: 호환 문서에서 명시하지 않으므로 OpenAI와 동일하게 동작한다고 가정하지 마세요.

7. 자주 발생하는 오류 대조표

현상 흔한 오류 코드 가능한 원인 처리 방식
401 InvalidApiKey / invalid_api_key 키 오류, 지역 불일치, 요금제 키 혼용 키와 Base URL의 지역·유형 확인
404 ModelNotFound / model_not_found 모델명 오타, 해당 지역에 모델 없음, 미개통 콘솔 모델 목록 확인
404 model_not_supported 모델이 OpenAI 호환 모드를 지원하지 않음 DashScope 원시 인터페이스로 전환
403 AccessDenied / Workspace.AccessDenied 공간 또는 모델 권한 부족 업무 공간 권한 확인
403 AllocationQuota.FreeTierOnly 무료 할당량 소진 충전 또는 요금제 조정
429 Throttling 계열 요청 빈도, 토큰, 동시성 초과 동시성 축소, 백오프 재시도, 할당량 신청
400 Arrearage 계정 연체 충전 후 재시도
400 Range of input length... 입력이 컨텍스트 상한 초과 프롬프트 압축 또는 분할
400 DataInspectionFailed 입력 또는 출력이 콘텐츠 안전 정책에 걸림 내용 조정 후 재시도

재시도는 429, 5xx, 네트워크 타임아웃에만 유효합니다. 401, 403, 404, 파라미터 오류는 재시도해도 나아지지 않고 시간과 할당량만 낭비합니다. 문제를 해결할 때 응답의 Request ID를 기록하고 콘솔 로그에서 조회하면 추측보다 훨씬 빠릅니다.

8. OpenAI에서 이전하는 체크리스트

  1. 기존 프롬프트, 모델 파라미터, 평가 세트를 백업합니다.
  2. 목표 지역과 맞는 Qwen 키를 새로 만들고 다른 벤더의 키를 재사용하지 않습니다.
  3. Base URL과 모델명을 설정 항목으로 바꿉니다.
  4. messages 역할 규칙을 확인해 첫 메시지가 system, 마지막이 user인지 확인합니다.
  5. 스트리밍 파싱과 usage 집계 방식을 확인합니다.
  6. 실제 도구로 도구 호출 회귀 테스트를 한 차례 실행합니다.
  7. 같은 샘플 세트로 출력 품질, 지연, 사용량을 비교합니다.
  8. 재시도, 타임아웃, 동시성을 조정하고 일주일 관찰한 뒤 전면 전환합니다.
  9. 로그에 Request ID를 기록하고 롤백 스위치를 유지합니다.

9. 자주 묻는 질문(FAQ)

1. Qwen API는 OpenAI와 호환되나요?

대부분의 주요 채팅 인터페이스는 호환되지만 지역 바인딩, 역할 순서, 파라미터 범위, 도구 호출 제한 등의 차이가 있습니다. 공식 OpenAI 호환 문서에 따라 항목별로 검증하고 모든 파라미터가 동일하게 동작한다고 가정하지 마세요.

2. 중국 본토와 국제 사이트에서 키 하나를 같이 쓸 수 있나요?

안 됩니다. 두 사이트의 계정, 키, 접속 도메인, 청구는 서로 독립적입니다. 지역이나 사이트를 넘어 호출하면 보통 401과 invalid_api_key가 반환됩니다.

3. Base URL은 구 도메인과 업무 공간 전용 도메인 중 무엇을 써야 하나요?

빠른 테스트는 구 공유 도메인으로 충분하고 운영 환경은 처리량과 트래픽 격리가 좋은 업무 공간 전용 도메인을 권장합니다. 핵심은 키가 도메인의 지역과 업무 공간에 맞아야 한다는 점입니다.

4. 모델명이 맞는데 model_not_found가 반환되는 이유는 무엇인가요?

해당 지역에 모델이 없거나, 모델이 개통되지 않았거나, 대소문자가 다르거나, 이미 종료된 버전에 접근했을 수 있습니다. 콘솔의 현재 모델 목록을 기준으로 하세요.

5. tools를 stream과 함께 쓸 수 있나요?

공식 호환 문서는 현재 둘을 동시에 쓸 수 없다고 명시하며 도구 호출은 일부 모델만 지원합니다. 능력과 제한은 모델 업데이트에 따라 바뀌므로 출시 전에 대상 모델로 실측하거나 DashScope 원시 인터페이스로 전환하세요.

관련 글