가장 빠르게 Qwen 사용해보기

설치보다 먼저 대화해 보기

Qwen을 처음 만날 때는 개발 환경을 먼저 꾸미지 않는 편이 좋습니다. 우선 Qwen Chat이나 Alibaba Cloud Model Studio 같은 웹 화면에서 질문을 던져 보세요. 설치, 패키지 충돌, GPU 설정 없이 모델의 답변 성격을 바로 확인할 수 있습니다.

처음에는 어려운 질문보다 익숙한 업무 문장으로 시작합니다.

• "아래 회의 메모를 세 줄로 요약해 줘."

• "이 문장을 자연스러운 비즈니스 영어로 번역해 줘."

• "신입 개발자에게 RAG를 쉽게 설명해 줘."

같은 질문을 두세 번 반복해 보는 것도 좋습니다. 답변이 얼마나 일관적인지, 한국어 표현이 자연스러운지, 표나 목록 형식을 잘 지키는지 빠르게 감을 잡을 수 있습니다.

AI 생성 이미지

API 키 준비하기

웹에서 감을 잡았다면 다음 단계는 API 호출입니다. Alibaba Cloud Model Studio의 Key Management 화면에서 API 키를 만들고, 로컬 환경 변수 이름을 DASHSCOPE_API_KEY로 설정합니다. 공식 예제도 이 환경 변수명을 사용합니다.¹

export DASHSCOPE_API_KEY="sk-..."

환경 변수를 쓰지 않는 간단한 테스트라면 예제의 sk-xxx 자리에 직접 키를 넣을 수 있습니다. 다만 실제 프로젝트 코드에는 키를 직접 적지 않는 것이 원칙입니다. 저장소에 올라가거나 로그에 남으면 외부에서 비용을 발생시킬 수 있습니다.

API 호출에는 base_url, model, messages가 필요합니다. Singapore 리전의 OpenAI 호환 주소는 https://dashscope-intl.aliyuncs.com/compatible-mode/v1입니다. US, China 리전 주소는 서로 다르며 바꿔 쓸 수 없으므로, 키를 만든 리전과 엔드포인트를 맞춰야 합니다.¹

첫 chat/completions 호출

DashScope는 OpenAI 호환 방식의 chat/completions 구조를 지원합니다. 그래서 OpenAI SDK 사용 경험이 있다면 base_url과 모델명만 바꿔 빠르게 호출할 수 있습니다.

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",
)

completion = client.chat.completions.create(
    model="qwen-plus",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Qwen을 한 문단으로 소개해 줘."}
    ],
)

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

로컬에서 Qwen 서버를 띄워 테스트하는 경우에는 같은 OpenAI 호환 형식으로 base_url을 http://localhost:8000/v1처럼 지정할 수 있습니다.² 즉, 클라우드와 로컬의 차이는 주로 주소, 모델명, 인증 방식에 있습니다. 애플리케이션 코드의 큰 흐름은 비슷하게 유지할 수 있습니다.

messages 역할 이해하기

messages는 모델에게 전달하는 대화 기록입니다. 최소 요청은 user 메시지 하나만으로도 가능합니다. 그러나 실제 업무에서는 역할을 나누는 편이 안정적입니다.

• system: 모델의 기본 규칙을 정합니다. 예: "한국어로, 핵심만 답하라."

• user: 사용자의 실제 요청입니다.

• assistant: 이전 모델 답변을 이어 붙여 대화 맥락을 유지할 때 사용합니다.

예를 들어 고객 응대 봇이라면 system에 "환불 규정은 제공된 문서 안에서만 답하라"는 규칙을 넣고, user에 고객 질문을 넣습니다. 이전 답변을 다시 참고해야 하는 다중 턴 대화라면 assistant 메시지도 함께 전달합니다.

파라미터를 하나씩 바꿔 보기

첫 호출이 성공하면 같은 프롬프트로 생성 파라미터를 바꿔 보세요.

• temperature: 높을수록 표현이 다양해지고, 낮을수록 안정적입니다.

• top_p: 후보 단어의 선택 범위를 조절합니다.

• max_tokens: 답변의 최대 길이를 제한합니다.

처음부터 여러 값을 동시에 바꾸면 원인을 알기 어렵습니다. "회의록을 세 줄로 요약해 줘"라는 같은 요청에 대해 temperature만 0.2, 0.7로 바꿔 비교해 보세요. 보고서, 번역, 고객 응대처럼 일관성이 중요한 작업은 낮은 값을 먼저 시험하는 편이 안전합니다.

웹과 API를 함께 비교하기

마지막으로 세 가지 짧은 실습을 웹 인터페이스와 API 양쪽에서 실행해 봅니다.

1. 긴 문단 요약

2. 한국어↔영어 번역

3. 문서 일부를 넣고 질문하기

같은 입력이어도 인터페이스, 모델명, 파라미터, 시스템 메시지에 따라 결과가 달라질 수 있습니다. 이 차이를 관찰하는 것이 Qwen 사용의 첫 감각입니다. 처음 목표는 완벽한 시스템을 만드는 것이 아니라, 질문을 넣고 답을 받고 설정을 바꿔 보는 작은 순환을 익히는 것입니다.

참고

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

²Quickstart - Qwen