Hướng Dẫn Sử Dụng API Qwen 3.7

Nhóm Qwen của Alibaba đã phát hành Qwen3.7-Max-Preview vào giữa tháng 5 năm 2026, và các nhà phát triển ngay lập tức đặt cùng một câu hỏi: làm thế nào để tôi gọi nó từ mã của riêng mình? Mô hình này là một hệ thống suy luận hàng đầu với cửa sổ ngữ cảnh 1M token và theo dõi chuỗi suy nghĩ rõ ràng, rất phù hợp cho các backend agent, phân tích tài liệu dài và tạo mã. Nhưng từ "preview" (bản xem trước) đang thực hiện rất nhiều công việc trong tên gọi đó. Việc truy cập bị giới hạn, giao diện API vẫn đang được hoàn thiện và các chi tiết bạn cần để viết mã hoạt động được rải rác trong các ghi chú phát hành và tài liệu nền tảng.

nút

TÓM TẮT

Qwen3.7-Max-Preview là mô hình suy luận hàng đầu của Alibaba, được phát hành dưới dạng bản xem trước vào ngày 14 tháng 5 năm 2026, với cửa sổ ngữ cảnh 1M token. Trong giai đoạn xem trước, cách đáng tin cậy nhất để sử dụng nó là Qwen Chat (chat.qwen.ai); truy cập API sản xuất thông qua Alibaba Cloud Model Studio (DashScope) bằng cách sử dụng một endpoint tương thích với OpenAI, nơi bạn đặt URL cơ sở, chuyển khóa của mình dưới dạng Bearer token và gọi /chat/completions. Vì cấp độ 3.7 chỉ dành cho bản xem trước, hãy xác nhận ID mô hình và endpoint chính xác trong tài liệu chính thức trước khi bạn triển khai và sử dụng Apidog để kiểm tra và mô phỏng endpoint trong khi tính khả dụng ổn định.

Cách truy cập Qwen 3.7 ngay bây giờ

Qwen cung cấp các mô hình của mình trên một số giao diện, và chúng không phải lúc nào cũng hoạt động cùng lúc. Tính đến cuối tháng 5 năm 2026, đây là tình trạng truy cập thực tế.

Qwen Chat (chat.qwen.ai). Cách nhanh nhất để thử Qwen3.7-Max-Preview. Đăng nhập bằng tài khoản Qwen miễn phí, chọn qwen3.7-max-preview trong bộ chọn mô hình và bật Chế độ Tư duy (Thinking Mode) để xem dấu vết suy luận. Có giới hạn tỷ lệ sử dụng trong giai đoạn xem trước, nhưng nó không tốn phí và không cần thiết lập. Đây là sản phẩm trình duyệt, không phải API, vì vậy nó dành cho việc đánh giá hơn là tích hợp.

Alibaba Cloud Model Studio (DashScope). Đây là nơi các mô hình Qwen trở thành một API thực sự. Model Studio cung cấp Qwen thông qua một endpoint tương thích với OpenAI, vì vậy bất kỳ mã nào đã giao tiếp với OpenAI SDK đều có thể gọi Qwen bằng cách thay đổi URL cơ sở và khóa. Các cấp độ cũ hơn như qwen3.6-max-preview và dòng qwen-max đã có sẵn tại đây. Cấp độ xem trước 3.7 có thể chưa có một mục nhập API công khai khi bạn đọc bài này; Qwen theo truyền thống đã mở quyền truy cập API vài tuần sau bản xem trước trò chuyện.

Mẫu tương thích OpenAI. Mọi mô hình Qwen gần đây trên Model Studio đều theo cùng một cấu trúc. Bạn trỏ client OpenAI tiêu chuẩn đến URL cơ sở DashScope, xác thực bằng Bearer token và gọi tuyến chat completions. Mẫu này ổn định qua các phiên bản, vì vậy mã dưới đây vẫn hoạt động khi ID mô hình 3.7 được đưa vào; bạn chủ yếu thay đổi một chuỗi.

Vì mã định danh mô hình và endpoint có thể thay đổi trong thời gian xem trước, hãy coi tài liệu Qwen chính thức và danh sách mô hình Model Studio là nguồn thông tin đáng tin cậy. Để có một lộ trình miễn phí trong khi chờ truy cập API, hướng dẫn của chúng tôi về cách sử dụng Qwen 3.7 miễn phí bao gồm chi tiết các kênh xem trước.

Tổng quan các phương thức truy cập

Phương thức	Truy cập API	Chi phí	Tốt nhất cho
Qwen Chat (chat.qwen.ai)	Không	Miễn phí, giới hạn tỷ lệ	Đánh giá nhanh, kiểm tra lời nhắc
Alibaba Cloud Model Studio (DashScope)	Có, tương thích OpenAI	Trả tiền theo token	Tích hợp sản xuất
Qwen trên Hugging Face	Trọng số, khi phát hành	Miễn phí (tự lưu trữ)	Mô hình mã nguồn mở, không phải bản xem trước Max
Cổng bên thứ ba	Thay đổi	Thay đổi	Định tuyến đa mô hình

Một điểm đáng lưu ý: các mô hình Qwen mã nguồn mở có mặt trên Hugging Face, nhưng cấp độ Max-Preview là độc quyền, vì vậy đừng mong đợi các trọng số có thể tải xuống cho qwen3.7-max-preview.

Lấy API key của Qwen 3.7

Truy cập API thông qua tài khoản Alibaba Cloud. Các bước rất ngắn gọn.

Tạo tài khoản Alibaba Cloud và mở bảng điều khiển Model Studio (modelstudio.console.alibabacloud.com).
Kích hoạt Model Studio cho tài khoản và khu vực của bạn. Các khóa được giới hạn theo khu vực, vì vậy một khóa cho endpoint Singapore sẽ không xác thực được đối với Bắc Kinh.
Mở phần API keys trong bảng điều khiển và tạo một khóa. Nó trông giống như sk- theo sau là một chuỗi ký tự.
Sao chép khóa một lần và lưu trữ nó như một mật khẩu.

Hãy chọn khu vực của bạn một cách cẩn thận, vì nó sẽ đặt URL cơ sở của bạn:

Khu vực	URL cơ sở
Singapore	`https://dashscope-intl.aliyuncs.com/compatible-mode/v1`
US (Virginia)	`https://dashscope-us.aliyuncs.com/compatible-mode/v1`
Bắc Kinh (Trung Quốc)	`https://dashscope.aliyuncs.com/compatible-mode/v1`

Không bao giờ hardcode khóa trong mã nguồn bạn commit. Thay vào đó, hãy đặt nó vào một biến môi trường:

# macOS / Linux
export DASHSCOPE_API_KEY="sk-your-key-here"

# Windows PowerShell
setx DASHSCOPE_API_KEY "sk-your-key-here"

Mã của bạn đọc DASHSCOPE_API_KEY khi chạy. Điều này giữ bí mật ra khỏi kho lưu trữ của bạn và cho phép bạn xoay vòng khóa mà không cần chạm vào mã. Thói quen tương tự áp dụng cho bất kỳ mô hình nào bạn gọi; bạn sẽ thấy cùng một mẫu trong hướng dẫn của chúng tôi về API Gemini 3.5.

Yêu cầu đầu tiên của bạn: Python, curl và JavaScript

Endpoint Model Studio của Qwen tương thích với OpenAI, vì vậy bạn có hai lựa chọn: OpenAI SDK chính thức trỏ đến URL cơ sở DashScope, hoặc một cuộc gọi HTTP thô. Cả hai đều được trình bày dưới đây.

Một lưu ý trước khi đến phần mã. ID mô hình qwen3.7-max-preview là mã định danh mà Qwen Chat sử dụng cho mô hình xem trước. Chuỗi chính xác mà API mong đợi có thể khác nhau trong cửa sổ xem trước và một cấp độ cũ hơn như qwen3.6-max-preview có thể đang hoạt động khi bạn thử điều này. Xác nhận ID mô hình hiện tại trong danh sách mô hình Model Studio, sau đó thả nó vào trường model. Cấu trúc yêu cầu không thay đổi.

Python với OpenAI SDK

Cài đặt SDK bằng pip install openai, sau đó gửi yêu cầu:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DASHSCOPE_API_KEY"],
    # Sử dụng URL cơ sở cho khu vực tài khoản của bạn
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)

response = client.chat.completions.create(
    # Xác nhận ID mô hình trực tiếp trong danh sách mô hình Model Studio
    model="qwen3.7-max-preview",
    messages=[
        {"role": "system", "content": "Bạn là một trợ lý lập trình chính xác."},
        {"role": "user", "content": "Viết một hàm Python đảo ngược một danh sách liên kết."},
    ],
)

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

Đó là một yêu cầu hoàn chỉnh. Mảng messages tuân theo mẫu vai trò tiêu chuẩn: một tin nhắn system đặt hành vi, sau đó là lượt của user. Phản hồi mang văn bản được tạo trong choices[0].message.content.

curl

Để kiểm tra nhanh từ terminal, hoặc để xác nhận một khóa hoạt động trước khi viết mã ứng dụng:

curl 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions' \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "qwen3.7-max-preview",
    "messages": [
      {"role": "user", "content": "Giải thích tính bất biến (idempotency) trong REST API bằng hai câu."}
    ]
  }'

Nếu khóa và ID mô hình hợp lệ, bạn sẽ nhận được một phản hồi JSON với kết quả hoàn thành. Nếu không, phần thân lỗi sẽ cho bạn biết cần sửa gì; thêm về lỗi bên dưới.

JavaScript / Node.js

OpenAI SDK tương tự hoạt động trong Node. Cài đặt nó bằng npm install openai:

import OpenAI from "openai";

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

const response = await client.chat.completions.create({
  model: "qwen3.7-max-preview",
  messages: [
    { role: "user", content: "Liệt kê ba đánh đổi của GraphQL so với REST." },
  ],
});

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

Ba ngôn ngữ, một cấu trúc yêu cầu; đó là lợi thế của một API tương thích OpenAI.

Phản hồi truyền tải (Streaming responses)

Đối với bất kỳ thứ gì hướng đến người dùng, bạn không muốn đợi hoàn thành đầy đủ trước khi hiển thị đầu ra. Truyền tải sẽ gửi token khi chúng được tạo. Đặt stream thành true và lặp qua các khối.

stream = client.chat.completions.create(
    model="qwen3.7-max-preview",
    messages=[
        {"role": "user", "content": "Tóm tắt định lý CAP."},
    ],
    stream=True,
)

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

Trong Node, phản hồi được truyền tải là một iterable không đồng bộ:

const stream = await client.chat.completions.create({
  model: "qwen3.7-max-preview",
  messages: [{ role: "user", content: "Tóm tắt định lý CAP." }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || "");
}

Truyền tải quan trọng hơn với mô hình suy luận so với mô hình trò chuyện thông thường. Qwen 3.7 có thể dành thời gian thực để suy nghĩ trước khi đưa ra câu trả lời cuối cùng, vì vậy nếu không có truyền tải, người dùng sẽ nhìn chằm chằm vào một màn hình trống. Với truyền tải, bạn có thể hiển thị dấu vết suy nghĩ, chỉ báo đang gõ hoặc câu trả lời khi nó hình thành.

Tham số suy luận và tư duy

Qwen3.7-Max-Preview là một mô hình suy luận. Nó có thể tạo ra một chuỗi suy nghĩ rõ ràng bên trong các khối <think> trước khi đưa ra câu trả lời cuối cùng. Dấu vết đó đẩy điểm của nó trên các bài toán toán học và các vấn đề đa bước khó, và nó giúp gỡ lỗi: bạn có thể thấy logic của mô hình đã đi sai ở đâu.

Trên các mô hình Qwen gần đây được cung cấp thông qua DashScope, hành vi tư duy được kiểm soát bằng một cờ enable_thinking. Xác nhận cơ chế và tên tham số chính xác cho cấp độ xem trước 3.7 so với tài liệu tham khảo API hiện tại, vì các kiểm soát suy luận đã thay đổi giữa các phiên bản Qwen. Về mặt khái niệm, yêu cầu trông như thế này:

response = client.chat.completions.create(
    model="qwen3.7-max-preview",
    messages=[
        {"role": "user", "content": "Một chuyến tàu rời đi lúc 2 giờ chiều với tốc độ trung bình 60mph. "
                                    "Chuyến thứ hai rời đi lúc 3 giờ chiều với tốc độ 75mph trên cùng một tuyến đường. "
                                    "Khi nào chuyến thứ hai bắt kịp chuyến đầu tiên?"},
    ],
    # Các kiểm soát suy luận thay đổi theo phiên bản Qwen; xác nhận tham số hiện tại
    # trong tài liệu tham khảo API Model Studio trước khi dựa vào nó.
    extra_body={"enable_thinking": True},
)

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

Một vài lưu ý thực tế:

Tư duy tốn token và thời gian. Dấu vết suy luận là văn bản được tạo. Nó tính vào đầu ra và làm tăng độ trễ. Đối với các tra cứu hoặc định dạng đơn giản, hãy tắt tư duy.
Bật nó lên cho các vấn đề khó. Toán học đa bước, mã có các trường hợp biên khó, lập kế hoạch và phân tích là nơi chuỗi suy nghĩ đáng giá chi phí của nó.
Quyết định có hiển thị dấu vết hay không. Một số ứng dụng hiển thị nội dung <think> để người dùng thấy quá trình làm việc của mô hình; những ứng dụng khác loại bỏ nó và chỉ hiển thị câu trả lời cuối cùng. Cả hai đều hợp lệ.

Nếu bạn đang cân nhắc chất lượng và chi phí suy luận so với các mô hình tiên tiến khác, so sánh của chúng tôi về Qwen 3.7 so với GPT-5.5 so với Opus 4.7 đặt các đánh đổi cạnh nhau. Các mô hình suy luận có thể tiêu tốn token nhanh chóng trong các vòng lặp agent; nếu đó là trường hợp của bạn, các kỹ thuật trong bài viết của chúng tôi về cách giảm chi phí token agent áp dụng trực tiếp.

Xử lý lỗi và giới hạn tỷ lệ

Một yêu cầu có thể thất bại vì những lý do có thể đoán trước. Hãy xử lý chúng để ứng dụng của bạn giảm hiệu suất một cách hợp lý.

Trạng thái HTTP	Ý nghĩa	Cần làm gì
400	Yêu cầu không hợp lệ: JSON không đúng định dạng, tham số không hợp lệ	Sửa phần thân yêu cầu; kiểm tra ID mô hình và tên trường
401	API key không hợp lệ hoặc thiếu	Xác minh key và đảm bảo nó khớp với khu vực endpoint
403	Không có quyền truy cập vào mô hình	Cấp độ xem trước có thể bị giới hạn; xác nhận tài khoản của bạn đã được kích hoạt
404	Không tìm thấy mô hình	ID mô hình sai hoặc không khả dụng trong khu vực của bạn
429	Vượt quá giới hạn tỷ lệ hoặc hạn ngạch	Tạm dừng và thử lại; kiểm tra giới hạn QPS và số dư tài khoản
500 / 503	Lỗi phía máy chủ	Thử lại với khoảng lùi lũy thừa

Các mô hình xem trước thường gặp lỗi 403 và 404 nhiều hơn các mô hình ổn định, vì quyền truy cập bị giới hạn và các mã định danh thay đổi. Nếu bạn gặp một trong số đó, vấn đề thường là quyền truy cập hoặc chuỗi mô hình, chứ không phải mã của bạn.

Giới hạn tỷ lệ trên Model Studio được đặt cho mỗi tài khoản dưới dạng truy vấn mỗi giây hoặc mỗi phút, và các số liệu chính xác phụ thuộc vào cấp độ tài khoản và mô hình của bạn; hãy kiểm tra bảng điều khiển thay vì giả định một giá trị cố định. Mẫu này vẫn như nhau: bắt lỗi 429, chờ và thử lại với độ trễ tăng dần.

import time
from openai import OpenAI, RateLimitError, APIStatusError

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

def ask_qwen(prompt, max_retries=4):
    for attempt in range(max_retries):
        try:
            response = client.chat.completions.create(
                model="qwen3.7-max-preview",
                messages=[{"role": "user", "content": prompt}],
            )
            return response.choices[0].message.content
        except RateLimitError:
            wait = 2 ** attempt          # 1s, 2s, 4s, 8s
            print(f"Bị giới hạn tốc độ. Thử lại sau {wait}s...")
            time.sleep(wait)
        except APIStatusError as e:
            # 400/401/403/404 không đáng để thử lại; hiển thị chúng
            print(f"Lỗi API {e.status_code}: {e.message}")
            raise
    raise RuntimeError("Thất bại sau nhiều lần thử lại")

Khoảng lùi lũy thừa trên 429 và 5xx, thất bại nhanh trên 4xx. Sự phân chia này giúp bạn không gửi quá nhiều yêu cầu đến API khi gặp các lỗi mà việc thử lại không thể khắc phục.

Kiểm thử và mô phỏng API Qwen với Apidog

Đây là lúc một API xem trước trở nên khó khăn, và là lúc các công cụ tốt phát huy tác dụng. Khi quyền truy cập bị giới hạn, ID mô hình đang thay đổi và giới hạn tỷ lệ chặt chẽ, bạn không muốn kiểm thử bằng cách chạy toàn bộ ứng dụng của mình và đọc nhật ký. Bạn muốn gửi một yêu cầu, xem chính xác những gì trả về và giữ lại để chạy lại. Apidog được xây dựng cho vòng lặp đó.

Mô phỏng endpoint trong khi bạn xây dựng. Đây là điểm lớn nhất đối với bản xem trước bị giới hạn. Máy chủ giả lập của Apidog trả về các phản hồi thực tế từ lược đồ API, không cần khóa và không giới hạn tỷ lệ. Vì vậy, frontend hoặc agent của bạn có thể phát triển dựa trên một endpoint Qwen thay thế luôn phản hồi ngay lập tức, ngay cả khi quyền truy cập xem trước thực tế bị điều tiết, ngừng hoạt động hoặc chưa mở cho tài khoản của bạn. Khi API trực tiếp sẵn sàng, hãy chuyển đổi URL cơ sở từ giả lập sang DashScope và mã của bạn vẫn không thay đổi. Để biết thêm về các quy trình làm việc ưu tiên lược đồ, hãy xem hướng dẫn chế độ ưu tiên đặc tả của chúng tôi.

Mẫu này áp dụng cho bất kỳ API mô hình nào. Vòng lặp kiểm thử và mô phỏng tương tự trong Apidog hoạt động cho dù bạn đang gọi Qwen, Gemini hay API ERNIE 5.1; một mô hình xem trước làm cho bước mô phỏng trở nên có giá trị hơn, bởi vì endpoint thực tế là phần ít đáng tin cậy nhất trong ngăn xếp của bạn.

Kết luận

Gọi Qwen 3.7 rất đơn giản một khi bạn biết cách. Khó khăn nằm ở việc giới hạn bản xem trước, chứ không phải API.

Đừng đoán Qwen trả về gì nữa mà hãy bắt đầu thấy nó. Tải xuống Apidog để thiết kế endpoint Qwen, gửi các yêu cầu kiểm thử thực tế, lưu các kịch bản có thể tái sử dụng và mô phỏng API trong khi bạn xây dựng. Nó miễn phí để bắt đầu và biến một bản xem trước không ổn định thành thứ bạn có thể tự tin phát triển.