Qwen 첫 텍스트 생성 호출 만들기

Qwen 첫 텍스트 생성 호출 만들기

텍스트 생성 모델은 자연어를 입력받아 질의응답·글쓰기·요약·번역·구조화 출력 같은 결과를 내요. 이 문서는 messages 배열을 어떻게 구성하고, 어떤 API 스타일로 첫 추론 호출을 보내는지 가장 빠르게 확인할 수 있는 입문서예요. 요청 구조와 대표 응답 필드만 이해하면 곧바로 OpenAI 호환 코드를 붙여 쓸 수 있어요.

출처: QwenCloud 공식 문서 - Generate text

요청 구조

텍스트 생성 요청은 보통 messages 배열로 보내요. 각 메시지는 role과 content를 가집니다.

  • System message: 모델의 동작이나 전반적 지침을 정해요. 일관된 출력을 원할 때 쓰면 좋죠.
  • User message: 사용자의 입력이나 과제를 담아요.
  • Assistant message: 모델의 답변을 담아요.

전형적인 요청은 user 메시지를 포함하고, 더 안정적·제어 가능한 출력을 원하면 system 메시지를 곁들여요.

[
  {"role": "system", "content": "You are a helpful assistant. Answer clearly and concisely."},
  {"role": "user", "content": "Summarize the benefits of solar energy in three bullet points."}
]

모델은 답변을 assistant 메시지로 돌려주죠.

API 스타일 고르기

자신의 스택에 맞는 API를 고르면 돼요.

  • 신규 통합이라면 OpenAI Compatible - Responses API로 시작
  • 기존 OpenAI 호환 코드를 옮긴다면 OpenAI Compatible - Chat Completions API
  • Anthropic에서 이전한다면 Anthropic Messages API(thinking·도구 호출 지원)
  • 네이티브 SDK를 선호하면 DashScope

아래는 Chat Completions API로 첫 요청을 보내는 Python 예시예요. 기본 엔드포인트는 https://dashscope-intl.aliyuncs.com/compatible-mode/v1이고, 인증은 DASHSCOPE_API_KEY 환경변수(또는 api_key)에 담습니다.

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="qwen3.7-plus",
  messages=[
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Summarize the benefits of solar energy in three bullet points."},
  ],
)
print(completion.choices[0].message.content)

같은 호출을 curl로는 이렇게 보내요.

curl -X POST https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "qwen3.7-plus", "messages": [{"role":"user","content":"Hello!"}]}'

응답 필드

Chat Completions 응답의 핵심은 choices[0].message.content(생성 텍스트)와 usage(토큰 사용 통계)예요. Responses API를 쓰면 output 배열에 reasoning(deep thinking을 켰을 때만, 예: Qwen3.5·Qwen3.6 계열은 기본 활성)과 message가 나뉘어 옵니다.

토큰 계수 FAQ

보낸 텍스트보다 입력 토큰이 더 많게 잡혀요, 왜죠?

대화를 처리할 때 시스템이 Chat Template으로 원문을 감싸면서 역할 식별자·메시지 구분자 같은 제어 마커를 추가하고, 이 마커도 토큰으로 집계되기 때문이에요. 예를 들어 {"role":"user","content":"Hi"}를 qwen3.8-max에 보내면 "Hi"는 1토큰이지만, 실제 처리 문자열(<|im_start|>user\nHi<|im_end|>\n<|im_start|>assistant\n thinking)을 토큰화하면 입력이 11토큰으로 늘어나요.

Qwen API는 웹 링크를 직접 분석할 수 없나요?

네, 직접 접근·파싱은 못 해요. 대신 함수 호출(Function calling)을 쓰거나 Python의 Beautiful Soup 같은 스크래핑 도구로 페이지를 읽어 전달하면 됩니다.

Qwen 웹 앱과 API 응답이 다른 이유는요?

웹 앱은 API 위에 웹 페이지 파싱·검색·이미지 생성·PPT 제작 같은 별도 엔지니어링을 얹어서예요. 이런 기능은 코어 LLM API 밖이고, 함수 호출로 재현할 수 있어요.

더 알아보기