개발 환경과 API 호출 기본기

API 호출은 세 가지 값에서 시작한다

Qwen을 서비스에 연결할 때 먼저 고정해야 할 값은 세 가지다. API 키, base URL, 모델명이다. API 키는 코드에 직접 쓰지 않는다. 로컬 개발 환경이나 서버의 환경 변수에 DASHSCOPE_API_KEY로 저장하고, 실행 시점에 읽어야 한다. Python에서는 os.getenv("DASHSCOPE_API_KEY"), Node.js에서는 process.env.DASHSCOPE_API_KEY로 가져온다.¹

base URL은 사용하는 리전에 맞춰야 한다. 예를 들어 Singapore는 https://dashscope-intl.aliyuncs.com/compatible-mode/v1, US는 https://dashscope-us.aliyuncs.com/compatible-mode/v1, Beijing은 https://dashscope.aliyuncs.com/compatible-mode/v1을 사용한다. 리전별 주소는 서로 바꿔 쓰는 값이 아니므로, API 키가 발급된 환경과 호출 주소를 함께 확인해야 한다.¹

Qwen은 OpenAI 호환 Chat Completions 방식으로 호출할 수 있다. 기존 OpenAI SDK를 써 본 개발자라면 base_url과 모델명만 바꿔 빠르게 시작할 수 있다. 더 많은 고유 기능이 필요하면 DashScope 네이티브 인터페이스도 검토할 수 있지만, 첫 연동은 OpenAI 호환 방식이 가장 단순하다.²

AI 생성 이미지

Python에서 기본 호출 만들기

아래 코드는 OpenAI 호환 SDK로 Qwen을 호출하는 가장 작은 구조다. 핵심은 client를 만들 때 API 키와 base URL을 넣고, messages 배열에 역할별 메시지를 전달하는 것이다.

import os
from openai import OpenAI

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

response = client.chat.completions.create(
    model="qwen-plus",
    messages=[
        {"role": "system", "content": "너는 핵심만 답하는 한국어 업무 도우미다."},
        {"role": "user", "content": "Qwen API 호출 구조를 한 문단으로 설명해줘."},
    ],
)

print(response.choices[0].message.content)

system은 답변 방식과 역할을 정한다. user는 실제 요청이다. 이전 대화를 이어가야 한다면 과거의 user, assistant 메시지를 필요한 만큼만 함께 넣는다. 모든 대화 이력을 무제한으로 넣으면 비용과 응답 시간이 늘어난다.

직접 HTTP로 호출할 때는 base URL 뒤에 /chat/completions를 붙이고, Authorization: Bearer ... 헤더를 보낸다.³ SDK를 쓰든 HTTP를 쓰든 요청의 중심은 같다. 모델명, 메시지, 출력 옵션을 JSON으로 보내고 choices[0].message.content에서 답변을 읽는다.

Node.js에서는 서버에서만 키를 다룬다

Node.js에서도 구조는 거의 같다. 단, 이 코드는 브라우저가 아니라 서버에서 실행해야 한다. 프런트엔드 코드에 API 키를 넣으면 사용자가 개발자 도구로 키를 볼 수 있다.

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.DASHSCOPE_API_KEY,
  baseURL: "https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
});

const result = await client.chat.completions.create({
  model: "qwen-plus",
  messages: [
    { role: "system", content: "답변은 짧고 명확하게 작성한다." },
    { role: "user", content: "RAG를 쉽게 설명해줘." },
  ],
});

console.log(result.choices[0].message.content);

서비스 구조는 단순하게 나누는 것이 좋다. 프런트엔드는 입력값 읽기, 사용자 메시지 즉시 표시, 로딩 상태 출력, 응답 렌더링만 맡는다. 백엔드는 API 키 보관, Qwen 호출, 사용량 제한, 로그 기록, 오류 처리를 담당한다. 실제 채팅 UI에서도 입력을 비우고 로딩 메시지를 보여준 뒤 응답을 추가하는 흐름이 기본이다.⁴

Node 생태계에서는 qwen-ai-provider 같은 공급자 라이브러리도 사용할 수 있다. 기본 인스턴스는 환경 변수의 DASHSCOPE_API_KEY를 읽고, 필요하면 createQwen()으로 baseURL, 헤더, fetch 구현을 바꿀 수 있다.⁵

import { qwen } from "qwen-ai-provider";
import { generateText } from "ai";

const { text } = await generateText({
  model: qwen("qwen-plus"),
  prompt: "Qwen을 API로 호출할 때 주의할 점 3가지를 알려줘.",
});

스트리밍과 오류 처리는 처음부터 넣는다

사용자가 긴 답변을 기다려야 한다면 스트리밍을 사용한다. Python에서는 stream=True를 켜고 생성되는 조각을 바로 출력한다.

stream = client.chat.completions.create(
    model="qwen-plus",
    messages=[{"role": "user", "content": "API 장애 대응 전략을 요약해줘."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

운영 코드에는 실패를 정상 흐름의 일부로 봐야 한다. API 키가 틀리면 인증 오류가 나고, 호출이 많으면 속도 제한에 걸릴 수 있다. 네트워크 지연이나 일시적인 서버 오류도 생긴다. 따라서 타임아웃을 설정하고, 재시도는 2~3회로 제한한다. 재시도 간격은 바로 반복하지 말고 조금씩 늘리는 지수 백오프를 사용한다. 마지막에는 사용자에게 "잠시 후 다시 시도해 주세요" 같은 안전한 대체 메시지를 보여준다.

처음 만든 코드는 작아도 된다. 하지만 API 키 보호, 리전별 base URL, 역할 기반 messages, 서버 측 호출, 스트리밍, 예외 처리까지 포함되어야 서비스 코드의 출발점이 된다.

참고

¹Alibaba Cloud Model Studio: Make your first API call to Qwen

²Alibaba Cloud Model Studio: Qwen API reference

³How to Use the Qwen 3.7 API?

⁴前端接入通义千问（Qwen）API：5 分钟实现你的 AI 问答助手-阿里云开发者社区

⁵Community Providers: Qwen