Qwen 3.5 API 사용법

알리바바 클라우드는 2026년 2월 15일에 Qwen 3.5를 출시했으며, 개발자 커뮤니티는 즉시 주목했습니다. 이 모델은 기본 다중 모드 이해, 1백만 토큰 컨텍스트 창, 그리고 추론, 코딩, 도구 사용 벤치마크에서 GPT-4.5, Claude 4, Gemini 2.5를 꾸준히 능가하는 에이전트 기능을 제공합니다.

Qwen 3.5 API는 이러한 모든 강력한 기능을 깔끔하고 OpenAI 호환 가능한 엔드포인트 뒤에 배치합니다. 한 번 인증하고 표준 채팅 완료 요청을 전송하면, 이전에는 복잡한 오케스트레이션 계층이 필요했던 기능들을 잠금 해제할 수 있습니다.

이 가이드는 첫 토큰 생성부터 프로덕션급 다중 모드 에이전트 구축에 이르기까지 모든 기술적 세부 사항을 안내합니다. 실제 작업 부하에서 작동하는 정확한 페이로드, 고급 매개변수, 오류 처리 패턴, 비용 최적화 전략을 배우게 될 것입니다.

💡

코드를 한 줄도 작성하기 전에 Apidog를 무료로 다운로드하세요. 이 게시물의 예제, 특히 도구 호출, 스트리밍 추론 추적 및 다중 모드 입력 섹션을 따라갈 때, Apidog는 프로토타입 제작, 스키마 검증, 테스트 시나리오 연결 및 클라이언트 코드 생성을 위한 가장 빠른 방법이 됩니다. 이 플랫폼은 이전에는 몇 시간 동안의 Postman 혼란이었던 작업을 몇 분의 집중적인 개발로 바꿉니다. 이제 Qwen 3.5를 사용하는 많은 팀은 Apidog를 필수적인 인프라로 간주합니다.

button

준비되셨나요? 환경을 설정하고 Qwen 3.5로 첫 번째 프로덕션 준비 요청을 보내봅시다.

Qwen 3.5가 돋보이는 이유는 무엇인가요?

Qwen 3.5는 Qwen 시리즈의 중요한 도약을 나타냅니다. 알리바바는 오픈 가중치 Qwen3.5-397B-A17B를 출시했습니다. 이 모델은 총 3,970억 개의 매개변수를 가진 하이브리드 MoE 모델이지만, 추론당 170억 개의 활성 매개변수만 사용합니다. 이 아키텍처는 선형 어텐션을 위한 Gated Delta Networks와 스파스 전문가를 결합하여 탁월한 효율성을 제공합니다.

API에 호스팅된 Qwen 3.5-Plus 모델은 기본적으로 1M 토큰 컨텍스트 창을 제공합니다. 201개 언어 및 방언을 지원하며, 이미징과 비디오를 기본적으로 처리하고, 벤치마크에서 뛰어난 성능을 보입니다:

추론: MMLU-Pro에서 87.8점
코딩: SWE-bench Verified에서 76.4점
에이전트 기능: TAU2-Bench에서 86.7점
비전: MMMU에서 85.0점

이러한 결과는 Qwen 3.5를 에이전트, 코드 어시스턴트 또는 다중 모드 애플리케이션을 구축하는 개발자에게 강력한 선택으로 자리매김합니다. API는 거대한 하드웨어 관리가 필요 없이 이러한 기능에 즉시 액세스할 수 있도록 합니다.

또한, Qwen 3.5는 웹 검색 및 코드 해석과 같은 내장 도구를 도입합니다. 간단한 매개변수로 이들을 활성화할 수 있으므로, 사용자 지정 오케스트레이션 계층을 구축할 필요가 없습니다. 결과적으로 팀은 지능형 워크플로를 더 빠르게 출시할 수 있습니다.

Qwen 3.5 API 통합을 위한 전제 조건

첫 요청을 보내기 전에 환경을 준비해야 합니다. Qwen 3.5 API는 알리바바 클라우드의 Model Studio(이전 DashScope)에서 실행되므로, 거기서 계정을 생성해야 합니다.

알리바바 클라우드 Model Studio 콘솔을 방문하세요.
알리바바 클라우드 자격 증명으로 가입하거나 로그인하세요.
API 키 섹션으로 이동하여 새 DASHSCOPE_API_KEY를 생성하세요. 이를 안전하게 보관하세요. 프로덕션 비밀처럼 다루십시오.

또한, OpenAI Python SDK를 설치하세요. Qwen 3.5는 완벽한 호환성을 유지하므로 다른 공급자의 익숙한 패턴을 재사용할 수 있습니다.

pip install openai

이 단계에서 Apidog의 이점도 누릴 수 있습니다. 공식 사이트에서 무료로 다운로드한 후, OpenAPI 사양을 가져오거나 Qwen 3.5 엔드포인트를 수동으로 추가하세요. Apidog는 요청 스키마를 자동 생성하고 응답을 검증하며, 이는 나중에 사용자 지정 매개변수를 탐색할 때 매우 유용합니다.

클라이언트 인증 및 구성

연결하려면 기본 URL과 API 키를 설정합니다. 국제 사용자는 일반적으로 낮은 지연 시간을 위해 싱가포르 또는 미국 엔드포인트를 선택합니다.

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

이 클라이언트 객체는 모든 후속 호출을 처리합니다. 기본 URL을 변경하여 리전을 전환할 수 있습니다. 중국 기반 작업 부하의 경우 베이징, 미국 트래픽의 경우 버지니아를 선택할 수 있습니다. SDK는 인증을 추상화하므로 페이로드 설계에 집중할 수 있습니다.

그러나 프로덕션 애플리케이션은 종종 환경 변수 및 비밀 관리자를 사용합니다. 키를 정기적으로 교체하고, 일시적인 네트워크 문제를 처리하기 위해 지수 백오프를 사용한 재시도 로직을 구현해야 합니다.

첫 채팅 완료 요청 보내기

이제 기본 요청을 실행합니다. Qwen 3.5는 표준 OpenAI 메시지 형식을 받아들이고 구조화된 응답을 반환합니다.

messages = [
    {"role": "system", "content": "You are a helpful technical assistant."},
    {"role": "user", "content": "Explain the architecture of Qwen 3.5 in simple terms."}
]

completion = client.chat.completions.create(
    model="qwen3.5-plus",
    messages=messages,
    temperature=0.7,
    max_tokens=1024
)

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

이 코드는 쿼리를 보내고 응답을 출력합니다. 다른 모델과 마찬가지로 temperature와 top_p를 조정하여 창의성을 제어할 수 있습니다.

이를 빠르게 테스트하려면 Apidog를 열고 새 요청을 생성한 다음 엔드포인트 https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions를 붙여넣고 헤더와 본문을 추가한 다음 보내기를 누릅니다. Apidog는 전체 응답 타임라인, 헤더를 표시하고 cURL 또는 Python 코드 스니펫까지 생성해줍니다.

추가 매개변수로 고급 기능 잠금 해제

Qwen 3.5-Plus는 기본 기능을 활성화할 때 빛을 발합니다. 이들은 extra_body 필드를 통해 전달합니다.

completion = client.chat.completions.create(
    model="qwen3.5-plus",
    messages=messages,
    extra_body={
        "enable_thinking": True,      # 사고의 사슬 추론 활성화
        "enable_search": True,        # 웹 검색 + 코드 인터프리터 활성화
    },
    stream=True
)

for chunk in completion:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
    if hasattr(chunk.choices[0].delta, "reasoning_content") and chunk.choices[0].delta.reasoning_content:
        print("\n[Thinking]:", chunk.choices[0].delta.reasoning_content)

따라서, 모델은 답변하기 전에 단계별로 생각하고 필요할 때 실시간 정보를 가져옵니다. 스트리밍 응답은 토큰 단위로 도착하여 채팅 인터페이스에서 인지되는 지연 시간을 개선합니다.

또한, Qwen 3.5는 다중 모드 입력을 지원합니다. 메시지에 이미지나 비디오를 직접 포함할 수 있습니다:

messages = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "What is happening in this image?"},
            {"type": "image_url", "image_url": {"url": "https://example.com/chart.png"}}
        ]
    }
]

API는 시각 데이터를 기본적으로 처리하고 추론된 설명 또는 답변을 반환합니다. 문서 분석 도구 또는 시각 에이전트를 구축하는 개발자들은 이 기능이 혁신적이라고 생각합니다.

도구 호출 및 에이전트 워크플로 구현

Qwen 3.5는 함수 호출에 능숙합니다. 요청에 도구를 정의하면 모델이 언제 호출할지 결정합니다.

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get current weather for a location",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"}
                },
                "required": ["location"]
            }
        }
    }
]

completion = client.chat.completions.create(
    model="qwen3.5-plus",
    messages=messages,
    tools=tools,
    tool_choice="auto"
)

모델이 도구 호출을 반환하면, 사용자 측에서 함수를 실행하고 결과를 다시 대화에 추가합니다. 이 루프는 외부 시스템과 상호 작용하는 강력한 에이전트를 생성합니다.

Apidog는 이러한 흐름을 테스트하는 것을 단순화합니다. 여러 요청을 연결하고, 도구 호출 형식에 대해 단언하며, 심지어 외부 API를 모의(mock)하는 테스트 시나리오를 생성할 수 있습니다. 결과적으로 프로덕션에 배포하기 전에 복잡한 에이전트 동작을 검증할 수 있습니다.

실제 애플리케이션 예시

개발자들은 많은 영역에서 Qwen 3.5 API를 통합합니다. 다음은 오늘 재현할 수 있는 실용적인 패턴입니다.

지능형 코딩 지원

작업 공간의 컨텍스트와 함께 코드 스니펫을 Qwen 3.5로 보내는 VS Code 확장을 구축할 수 있습니다. 모델은 리팩터링된 코드, 단위 테스트 및 설명을 반환합니다. 강력한 SWE-bench 성능 덕분에 실제 리포지토리 규모의 작업을 효과적으로 처리합니다.

다중 모드 연구 에이전트

PDF 업로드 또는 스크린샷을 수락하고, 데이터를 추출하고, 검증을 위해 웹을 검색하고, 보고서를 생성하는 에이전트를 생성할 수 있습니다. 1M 컨텍스트 창은 전체 연구 논문을 단일 대화에 담을 수 있습니다.

고객 지원 챗봇

Qwen 3.5를 지식 베이스 및 CRM과 결합할 수 있습니다. 모델은 대화 기록을 추론하고, 도구를 통해 실시간 주문 데이터를 가져오며, 201개 언어 지원을 통해 사용자가 선호하는 언어로 응답합니다.

각 경우에 알리바바 클라우드 콘솔을 통해 토큰 사용량과 비용을 모니터링합니다. Qwen 3.5-Plus는 특히 대규모 환경에서 그 기능에 대해 경쟁력 있는 가격을 제공합니다.

프로덕션 배포를 위한 모범 사례

신뢰성과 성능을 보장하기 위해 다음 지침을 따르십시오:

속도 제한: 클라이언트 측 스로틀링을 구현하고 알리바바의 문서화된 제한을 준수하십시오.
오류 처리: RateLimitError, InvalidRequestError를 포착하고 백오프를 사용하여 재시도하십시오.
비용 통제: 응답의 토큰 수를 추적하고 max_tokens를 보수적으로 설정하십시오.
보안: 프런트엔드 코드에 API 키를 노출하지 마십시오. 모든 호출에 백엔드 프록시를 사용하십시오.
관찰 가능성: 전체 요청/응답 페이로드(민감한 데이터 제외)를 로깅하고 지연 시간을 모니터링하십시오.

또한, 프롬프트 버전을 관리하고 변경 사항을 Apidog에서 테스트한 후 배포하십시오. 플랫폼의 환경 변수를 사용하면 개발, 스테이징 및 프로덕션 키를 원활하게 전환할 수 있습니다.

일반적인 Qwen 3.5 API 문제 해결

가끔 다음과 같은 문제가 발생할 수 있습니다:

인증 오류: DASHSCOPE_API_KEY 및 지역별 기본 URL을 다시 확인하십시오.
컨텍스트 길이 초과: 모델은 1M 토큰을 지원하지만, 여전히 사용량을 모니터링해야 합니다. 기록을 지능적으로 잘라내십시오.
도구 호출 실패: 함수 스키마가 예상 JSON 스키마와 정확히 일치하는지 확인하십시오.
느린 응답: 스트리밍을 활성화하고 간단한 쿼리의 경우 enable_thinking: false를 고려하십시오.

Apidog도 여기서 도움이 됩니다. 상세한 로그, 응답 유효성 검사 및 모의 서버를 통해 문제를 신속하게 격리할 수 있습니다.

오픈 가중치 모델의 로컬 배포

API가 대부분의 사용 사례에 적합하지만, 민감한 데이터 또는 오프라인 요구 사항을 위해 Qwen3.5-397B-A17B 모델을 로컬에서 실행할 수 있습니다. 이 모델은 Hugging Face에서 사용할 수 있습니다:

pip install transformers

높은 처리량을 위해 vLLM 또는 SGLang으로 서비스할 수 있습니다:

python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen3.5-397B-A17B \
  --tensor-parallel-size 8

로컬 서버는 동일한 /v1/chat/completions 엔드포인트를 노출합니다. Apidog 작업 공간을 http://localhost:8000/v1로 지정하고 클라우드 API와 동일하게 테스트할 수 있습니다.

397B 모델은 상당한 GPU 리소스(일반적으로 8×H100 또는 이에 상응하는 것)를 필요로 합니다. 더 작은 양자화된 버전은 곧 커뮤니티에 나타날 수 있습니다.

Qwen 3.5 API와 다른 공급자 비교

Qwen 3.5는 GPT-4.5, Claude 4, Gemini 2.5와 직접 경쟁합니다. 코딩 및 에이전트 벤치마크에서 선두를 달리고 있으며, 더 낮은 가격으로 기본 다중 모드 기능을 제공합니다. OpenAI 호환 인터페이스는 최소한의 코드 변경으로 마이그레이션할 수 있음을 의미합니다.

그러나 알리바바 클라우드의 글로벌 리전은 아시아 태평양 지역의 작업 부하에 이점을 제공합니다. 특정 시장에 대해 더 낮은 지연 시간과 더 나은 규정 준수를 달성할 수 있습니다.

결론: 오늘 Qwen 3.5로 구축을 시작하세요

이제 Qwen 3.5 API에 대한 완전한 기술 로드맵을 갖게 되었습니다. 기본적인 채팅 완료부터 정교한 다중 모드 에이전트에 이르기까지, 이 플랫폼은 개발자 친화적인 도구와 함께 최첨단 성능을 제공합니다.

지금 바로 Apidog를 무료로 다운로드하고 Qwen 3.5 엔드포인트를 가져오세요. 몇 시간 대신 몇 분 만에 통합을 프로토타입화, 테스트 및 문서화할 수 있습니다. API 워크플로에서 내리는 작은 결정들, 즉 올바른 테스트 플랫폼 선택, 프롬프트 구성, 도구 호출 처리 등이 개발 속도와 애플리케이션 품질에 큰 차이를 만듭니다.

Qwen 3.5 팀은 계속해서 한계를 뛰어넘고 있습니다. 업데이트를 위해 공식 Qwen 블로그, GitHub 리포지토리, Hugging Face 컬렉션을 확인하십시오.

가장 먼저 무엇을 구축하시겠습니까? 자율 연구 에이전트든, 비전 기반 분석 도구든, 다국어 고객 경험 플랫폼이든, Qwen 3.5 API는 기반을 제공합니다. 코딩을 시작하고, Apidog로 빠르게 반복하며, 아이디어를 현실로 만들어보세요.

button