Qwen3：重磅开源，重夺开源第一！（包含详细使用教程）-海口c网

1.简介

Qwen3，这是 Qwen 系列大型语言模型的最新成员。我们的旗舰模型 Qwen3-235B-A22B 在代码、数学、通用能力等基准测试中，与 DeepSeek-R1、o1、o3-mini、Grok-3 和 Gemini-2.5-Pro 等顶级模型相比，表现出极具竞争力的结果。此外，小型 MoE 模型 Qwen3-30B-A3B 的激活参数数量是 QwQ-32B 的 10%，表现更胜一筹，甚至像 Qwen3-4B 这样的小模型也能匹敌 Qwen2.5-72B-Instruct 的性能。

本次一共开源8个模型：

其中两个 MoE 模型的权重：Qwen3-235B-A22B，一个拥有 2350 多亿总参数和 220 多亿激活参数的大模型，以及Qwen3-30B-A3B，一个拥有约 300 亿总参数和 30 亿激活参数的小型 MoE 模型。
此外，六个 Dense 模型也已开源，包括 Qwen3-32B、Qwen3-14B、Qwen3-8B、Qwen3-4B、Qwen3-1.7B 和 Qwen3-0.6B，均在 Apache 2.0 许可下开源。

Qwen3具有以下核心特性：

独特的双模式切换能力：可在单一模型内无缝切换“思考模式”（适用于复杂逻辑推理、数学计算与代码生成）与“非思考模式”（适用于高效通用对话），确保在各类应用场景中实现最优性能。
显著增强的推理能力：在数学、代码生成以及常识性逻辑推理任务上，表现超越了此前的 QwQ 模型（在思考模式下）和 Qwen2.5 指令模型（在非思考模式下）。
卓越的人类偏好对齐能力：在创意写作、角色扮演、多轮对话和指令遵循方面表现出色，带来更加自然、生动且沉浸式的交互体验。
强大的智能体（Agent）能力：无论在思考还是非思考模式下，均可精准对接外部工具，在复杂基于智能体的任务中展现出开源模型中的领先水平。
广泛的多语言支持：支持 100 多种语言和方言，具备强大的多语言指令理解和翻译能力，满足全球化、多语种场景的需求。

权重地址（huggingface）：https://huggingface.co/collections/Qwen/qwen3-67dd247413f0e2e4f653967f

权重地址（魔搭）：魔搭社区

代码地址：https://github.com/QwenLM/Qwen3

使用：Qwen Chat

2.效果

模型参数

Models	Layers	Heads (Q / KV)	Tie Embedding	Context Length
Qwen3-0.6B	28	16 / 8	Yes	32K
Qwen3-1.7B	28	16 / 8	Yes	32K
Qwen3-4B	36	32 / 8	Yes	32K
Qwen3-8B	36	32 / 8	No	128K
Qwen3-14B	40	40 / 8	No	128K
Qwen3-32B	64	64 / 8	No	128K

Models	Layers	Heads (Q / KV)	# Experts (Total / Activated)	Context Length
Qwen3-30B-A3B	48	32 / 4	128 / 8	128K
Qwen3-235B-A22B	94	64 / 4	128 / 8	128K

模型性能

核心亮点

多种思考模式

Qwen3 模型支持两种思考模式：

思考模式：在这种模式下，模型会逐步推理，经过深思熟虑后给出最终答案。这种方法非常适合需要深入思考的复杂问题。
非思考模式：在此模式中，模型提供快速、近乎即时的响应，适用于那些对速度要求高于深度的简单问题。

这种灵活性使用户能够根据具体任务控制模型进行“思考”的程度。例如，复杂的问题可以通过扩展推理步骤来解决，而简单的问题则可以直接快速作答，无需延迟。至关重要的是，这两种模式的结合大大增强了模型实现稳定且高效的“思考预算”控制能力。如上文所述，Qwen3 展现出可扩展且平滑的性能提升，这与分配的计算推理预算直接相关。这样的设计让用户能够更轻松地为不同任务配置特定的预算，在成本效益和推理质量之间实现更优的平衡。

多语言

Qwen3 模型支持 119 种语言和方言。这一广泛的多语言能力为国际应用开辟了新的可能性，让全球用户都能受益于这些模型的强大功能。

语系	语种&方言
印欧语系	英语、法语、葡萄牙语、德语、罗马尼亚语、瑞典语、丹麦语、保加利亚语、俄语、捷克语、希腊语、乌克兰语、西班牙语、荷兰语、斯洛伐克语、克罗地亚语、波兰语、立陶宛语、挪威语（博克马尔语）、挪威尼诺斯克语、波斯语、斯洛文尼亚语、古吉拉特语、拉脱维亚语、意大利语、奥克语、尼泊尔语、马拉地语、白俄罗斯语、塞尔维亚语、卢森堡语、威尼斯语、阿萨姆语、威尔士语、西里西亚语、阿斯图里亚语、恰蒂斯加尔语、阿瓦德语、迈蒂利语、博杰普尔语、信德语、爱尔兰语、法罗语、印地语、旁遮普语、孟加拉语、奥里雅语、塔吉克语、东意第绪语、伦巴第语、利古里亚语、西西里语、弗留利语、撒丁岛语、加利西亚语、加泰罗尼亚语、冰岛语、托斯克语、阿尔巴尼亚语、林堡语、罗马尼亚语、达里语、南非荷兰语、马其顿语僧伽罗语、乌尔都语、马加希语、波斯尼亚语、亚美尼亚语
汉藏语系	中文（简体中文、繁体中文、粤语）、缅甸语
亚非语系	阿拉伯语（标准语、内志语、黎凡特语、埃及语、摩洛哥语、美索不达米亚语、塔伊兹-阿德尼语、突尼斯语）、希伯来语、马耳他语
南岛语系	印度尼西亚语、马来语、他加禄语、宿务语、爪哇语、巽他语、米南加保语、巴厘岛语、班加语、邦阿西楠语、伊洛科语、瓦雷语（菲律宾）
德拉威语	泰米尔语、泰卢固语、卡纳达语、马拉雅拉姆语
突厥语系	土耳其语、北阿塞拜疆语、北乌兹别克语、哈萨克语、巴什基尔语、鞑靼语
壮侗语系	泰语、老挝语
乌拉尔语系	芬兰语、爱沙尼亚语、匈牙利语
南亚语系	越南语、高棉语
其他	日语、韩语、格鲁吉亚语、巴斯克语、海地语、帕皮阿门托语、卡布维尔迪亚努语、托克皮辛语、斯瓦希里语

增强的 Agent 能力

我们优化了 Qwen3 模型的 Agent 和代码能力，同时也加强了对 MCP 的支持。下面我们将提供一些示例，展示 Qwen3 是如何思考并与环境进行交互的。

mcp演示视频：

https://qianwen-res.oss-accelerate-overseas.aliyuncs.com/mcp.mov

3.训练

预训练

在预训练方面，Qwen3 的数据集相比 Qwen2.5 有了显著扩展。Qwen2.5是在 18 万亿个 token 上进行预训练的，而 Qwen3 使用的数据量几乎是其两倍，达到了约 36 万亿个 token，涵盖了 119 种语言和方言。

为了构建这个庞大的数据集，作者不仅从网络上收集数据，还从 PDF 文档中提取信息。作者使用 Qwen2.5-VL 从这些文档中提取文本，并用 Qwen2.5 改进提取内容的质量。
为了增加数学和代码数据的数量，作者利用 Qwen2.5-Math 和 Qwen2.5-Coder 这两个数学和代码领域的专家模型合成数据，合成了包括教科书、问答对以及代码片段等多种形式的数据。

预训练过程分为三个阶段。

在第一阶段（S1），模型在超过 30 万亿个 token 上进行了预训练，上下文长度为 4K token。这一阶段为模型提供了基本的语言技能和通用知识。
在第二阶段（S2），我们通过增加知识密集型数据（如 STEM、编程和推理任务）的比例来改进数据集，随后模型又在额外的 5 万亿个 token 上进行了预训练。
在最后阶段，我们使用高质量的长上下文数据将上下文长度扩展到 32K token，确保模型能够有效地处理更长的输入。

由于模型架构的改进、训练数据的增加以及更有效的训练方法，Qwen3 Dense 基础模型的整体性能与参数更多的Qwen2.5基础模型相当。例如，Qwen3-1.7B/4B/8B/14B/32B-Base 分别与 Qwen2.5-3B/7B/14B/32B/72B-Base 表现相当。特别是在 STEM、编码和推理等领域，Qwen3 Dense 基础模型的表现甚至超过了更大规模的 Qwen2.5 模型。对于 Qwen3 MoE 基础模型，它们在仅使用 10% 激活参数的情况下达到了与 Qwen2.5 Dense 基础模型相似的性能。这带来了训练和推理成本的显著节省。

后训练

为了开发能够同时具备思考推理和快速响应能力的混合模型，作者实施了一个四阶段的训练流程。该流程包括：（1）长思维链冷启动，（2）长思维链强化学习，（3）思维模式融合，以及（4）通用强化学习。

在第一阶段，作者使用多样的的长思维链数据对模型进行了微调，涵盖了数学、代码、逻辑推理和 STEM 问题等多种任务和领域。这一过程旨在为模型配备基本的推理能力。
第二阶段的重点是大规模强化学习，利用基于规则的奖励来增强模型的探索和钻研能力。
在第三阶段，作者在一份包括长思维链数据和常用的指令微调数据的组合数据上对模型进行微调，将非思考模式整合到思考模型中。确保了推理和快速响应能力的无缝结合。
最后，在第四阶段，我们在包括指令遵循、格式遵循和 Agent 能力等在内的 20 多个通用领域的任务上应用了强化学习，以进一步增强模型的通用能力并纠正不良行为。

4.代码/使用教程

得益于qwen团队强大的生态，本次qwen3的更新实现了全生态链0天级的更新，包括但不限于：

部署：vllm、xinference、ollama、ktransformers
量化：AutoAWQ、AutoGPTQ
合作网站：huggingface、kaggle
微调：llama-factory

Transformers

要快速上手 Qwen3 ，我们建议您首先尝试使用 transformers 进行推理。请确保已安装了 transformers>=4.51.0 版本。我们建议您使用 Python 3.10 或以上版本， PyTorch 2.6 或以上版本。

如果出现以下错误，请更新transformers库

KeyError: 'qwen3'

以下是一个非常简单的代码片段示例，展示如何运行 Qwen3 模型：Qwen3 将在实际回复前思考，与 QwQ 模型类似。这意味着模型将运用其推理能力来提升生成回复的质量。模型会首先生成包含在 <think>...</think> 块中的思考内容，随后给出最终回复。

from transformers import AutoModelForCausalLM, AutoTokenizermodel_name = "Qwen/Qwen3-8B"# 加载模型和分词器
model = AutoModelForCausalLM.from_pretrained(model_name,torch_dtype="auto",device_map="auto"
)
tokenizer = AutoTokenizer.from_pretrained(model_name)# 准备模型输入
prompt = "Give me a short introduction to large language models."
messages = [{"role": "user", "content": prompt},
]
text = tokenizer.apply_chat_template(    # 用于将对话格式的输入转换为适合模型处理的文本格式。messages,tokenize=False,add_generation_prompt=True,enable_thinking=True, # Switches between thinking and non-thinking modes. Default is True.
)
model_inputs = tokenizer([text], return_tensors="pt").to(model.device)# 生成文本
generated_ids = model.generate(    # 模型的生成函数，用于根据输入生成新的文本。**model_inputs,        max_new_tokens=32768    # 指定生成的最大新标记数。
)
output_ids = generated_ids[0][len(model_inputs.input_ids[0]):].tolist()     # 从生成的标记序列中提取出的输出部分（去掉了输入部分）。# 解析思考内容和最终内容
try:# rindex finding 151668 (</think>)    # 尝试解析生成内容中的“思考内容”和最终的输出内容。index = len(output_ids) - output_ids[::-1].index(151668)
except ValueError:index = 0thinking_content = tokenizer.decode(output_ids[:index], skip_special_tokens=True).strip("\n")    # 思考内容部分的标记序列。
content = tokenizer.decode(output_ids[index:], skip_special_tokens=True).strip("\n")    # 最终内容部分的标记序列。print("thinking content:", thinking_content)
print("content:", content)

禁用思考模式

你也可以手动禁用思考模式：

硬开关：为了严格禁用模型的思考行为，使其功能与之前的Qwen2.5-Instruct模型保持一致，您可以在格式化文本时设置enable_thinking=False。

text = tokenizer.apply_chat_template(messages,tokenize=False,add_generation_prompt=True,enable_thinking=False,  # 设置 enable_thinking=False 可以禁用思考模式。
)

软开关方法1：Qwen3 还能够理解用户对其思考行为的指令，特别是软开关 /think 和 /no_think。您可以将这些指令添加到用户 (user) 或系统 (system) 消息中，以在对话轮次之间灵活切换模型的思考模式。在多轮对话中，模型将遵循最近的指令。

messages = [{"role": "user", "content": "Give me a short introduction to large language model./no_think"},
]
messages = generator(messages, max_new_tokens=32768)[0]{"generated_text"}
# print(messages[-1]["content"])messages.append({"role": "user", "content": "In a single sentence./think"})
messages = generator(messages, max_new_tokens=32768)[0]{"generated_text"}
# print(messages[-1]["content"])

软开关方法2：追加一条仅包含 <think>\n\n</think>\n\n 的最终助手 (assistant) 消息。此方法是无状态的，意味着它仅对当前轮对话生效，并且会严格阻止模型生成思考内容。例如：

messages = [{"role": "user", "content": "Give me a short introduction to large language model."},{"role": "assistant", "content": "<think>\n\n</think>\n\n"},
]
messages = generator(messages, max_new_tokens=32768)[0]{"generated_text"}
# print(messages[-1]["content"])messages.append({"role": "user", "content": "In a single sentence."})
messages = generator(messages, max_new_tokens=32768)[0]{"generated_text"}
# print(messages[-1]["content"])

对于思考模式，使用 Temperature=0.6，TopP=0.95，TopK=20，以及 MinP=0（generation_config.json 中的默认设置）。不要使用贪婪解码，因为它可能导致性能下降和无尽的重复。更多详细指导，请参阅最佳实践部分。
对于非思考模式，我们建议使用 Temperature=0.7，TopP=0.8，TopK=20，以及 MinP=0。

以下是一个多轮对话的示例：

from transformers import AutoModelForCausalLM, AutoTokenizerclass QwenChatbot:def __init__(self, model_name="Qwen3-30B-A3B/Qwen3-30B-A3B"):self.tokenizer = AutoTokenizer.from_pretrained(model_name)self.model = AutoModelForCausalLM.from_pretrained(model_name)self.history = []def generate_response(self, user_input):messages = self.history + [{"role": "user", "content": user_input}]text = self.tokenizer.apply_chat_template(messages,tokenize=False,add_generation_prompt=True)inputs = self.tokenizer(text, return_tensors="pt")response_ids = self.model.generate(**inputs, max_new_tokens=32768)[0][len(inputs.input_ids[0]):].tolist()response = self.tokenizer.decode(response_ids, skip_special_tokens=True)# Update historyself.history.append({"role": "user", "content": user_input})self.history.append({"role": "assistant", "content": response})return response# Example Usage
if __name__ == "__main__":chatbot = QwenChatbot()# First input (without /think or /no_think tags, thinking mode is enabled by default)user_input_1 = "How many r's in strawberries?"print(f"User: {user_input_1}")response_1 = chatbot.generate_response(user_input_1)print(f"Bot: {response_1}")print("----------------------")# Second input with /no_thinkuser_input_2 = "Then, how many r's in blueberries? /no_think"print(f"User: {user_input_2}")response_2 = chatbot.generate_response(user_input_2)print(f"Bot: {response_2}") print("----------------------")# Third input with /thinkuser_input_3 = "Really? /think"print(f"User: {user_input_3}")response_3 = chatbot.generate_response(user_input_3)print(f"Bot: {response_3}")

解析思考内容

如果您希望获得更结构化的助手消息格式，可以使用以下函数将思考内容提取到名为 reasoning_content 的字段中，该字段的格式类似于 vLLM、SGLang 等使用的格式。

import copy
import redef parse_thinking_content(messages):messages = copy.deepcopy(messages)for message in messages:if message["role"] == "assistant" and (m := re.match(r"<think>\n(.+)</think>\n\n", message["content"], flags=re.DOTALL)):message["content"] = message["content"][len(m.group(0)):]if thinking_content := m.group(1).strip():message["reasoning_content"] = thinking_contentreturn messages

启用长上下文

Qwen3 模型在预训练中的最大上下文长度为 32,768 个 token。通过 RoPE 缩放技术，它可以扩展到 131,072 个 token。我们已使用 YaRN 验证了性能。

Transformers 支持 YaRN，可以通过修改模型文件或在加载模型时覆盖默认参数来启用。

1.修改模型文件：在 config.json 文件中，添加 rope_scaling 字段：

{...,"rope_scaling": {"type": "yarn","factor": 4.0,"original_max_position_embeddings": 32768}
}

2.覆盖默认参数：

from transformers import pipelinemodel_name_or_path = "Qwen/Qwen3-8B"generator = pipeline("text-generation", model_name_or_path, torch_dtype="auto", device_map="auto",model_kwargs={"rope_scaling": {"type": "yarn","factor": 4.0,"original_max_position_embeddings": 32768}}
)

Transformers 实现了静态 YaRN，这意味着无论输入长度如何，缩放因子保持不变，这可能会对较短文本的性能产生影响。 建议仅在需要处理长上下文时添加 rope_scaling 配置。还建议根据需要修改 factor。例如，如果您的应用程序的典型上下文长度为 65,536 个 token，则最好将 factor 设置为 2.0。

流式输出

借助 TextStreamer ，您可以将与 Qwen3 的对话切换到流式传输模式。下面是一个关于如何使用它的示例：

from transformers import pipeline, TextStreamermodel_name_or_path = "Qwen/Qwen3-8B"generator = pipeline("text-generation", model_name_or_path, torch_dtype="auto", device_map="auto",
)streamer = TextStreamer(pipe.tokenizer, skip_prompt=True, skip_special_tokens=True)messages= generator(messages, max_new_tokens=32768, streamer=streamer)[0]["generated_text"]

除了使用 TextStreamer 之外，我们还可以使用 TextIteratorStreamer ，它将可打印的文本存储在一个队列中，以便下游应用程序作为迭代器来使用：

from transformers import pipeline, TextIteratorStreamermodel_name_or_path = "Qwen/Qwen3-8B"generator = pipeline("text-generation", model_name_or_path, torch_dtype="auto", device_map="auto",
)streamer = TextIteratorStreamer(pipe.tokenizer, skip_prompt=True, skip_special_tokens=True)# Use Thread to run generation in background
# Otherwise, the process is blocked until generation is complete
# and no streaming effect can be observed.
from threading import Thread
generation_kwargs = dict(text_inputs=messages, max_new_tokens=32768, streamer=streamer)
thread = Thread(target=pipe, kwargs=generation_kwargs)
thread.start()generated_text = ""
for new_text in streamer:generated_text += new_textprint(generated_text)

批处理

from transformers import pipelinemodel_name_or_path = "Qwen/Qwen3-8B"generator = pipeline("text-generation", model_name_or_path, torch_dtype="auto", device_map="auto",
)
generator.tokenizer.padding_side="left"batch = [[{"role": "user", "content": "Give me a short introduction to large language model."}],[{"role": "user", "content": "Give me a detailed introduction to large language model."}],
]results = generator(batch, max_new_tokens=32768, batch_size=2)
batch = [result[0]["generated_text"] for result in results]

魔搭 (ModelScope)

开始之前，需要使用 pip 安装 modelscope 。

modelscope 采用了与 transformers 类似（但不完全一致）的编程接口。对于基础使用，仅需将上面代码第一行做如下修改：

from modelscope import AutoModelForCausalLM, AutoTokenizer

欲获取更多信息，请参考 modelscope 文档。

vLLM

vLLM 是一个用于 LLM 推理和服务的快速且易于使用的框架。以下，我们将展示如何使用 vLLM 构建一个与 OpenAI 兼容的 API 服务。要了解更多关于vLLM的信息，请参阅论文和文档。

更详细的部署教程，请参考：

Vllm进行Qwen2-vl部署（包含单卡多卡部署及爬虫请求）-CSDN博客
基于LightRAG进行本地RAG部署（包括单卡多卡本地模型部署、调用阿里云或DeepSeekAPI的部署方法、RAG使用方法）_lightrag本地部署-CSDN博客

首先，确保你已经安装 vLLM>=0.8.5 ：

运行以下代码以构建 vLLM 服务。此处我们以 Qwen3-8B 为例：

--enable-reasoning: 启用推理功能。这个选项可能是指让模型能够执行一些更复杂的逻辑推理任务，而不仅仅是生成文本。
--reasoning-parser deepseek_r1: 指定了使用哪个推理解析器来处理输入和输出。

vllm serve Qwen/Qwen3-8B --enable-reasoning --reasoning-parser deepseek_r1

然后，可以使用 “create chat” interface 来与 Qwen 进行交流：

curl http://localhost:8000/v1/chat/completions -H "Content-Type: application/json" -d '{"model": "Qwen/Qwen3-8B","messages": [{"role": "user", "content": "Give me a short introduction to large language models."}],"temperature": 0.6,"top_p": 0.95,"top_k": 20,"max_tokens": 32768
}'

您可以按照下面所示的方式，使用 openai Python SDK中的客户端：

from openai import OpenAI
# Set OpenAI's API key and API base to use vLLM's API server.
openai_api_key = "EMPTY"
openai_api_base = "http://localhost:8000/v1"client = OpenAI(api_key=openai_api_key,base_url=openai_api_base,
)chat_response = client.chat.completions.create(model="Qwen/Qwen3-8B",messages=[{"role": "user", "content": "Give me a short introduction to large language models."},],temperature=0.6,top_p=0.95,top_k=20,max_tokens=32768,
)
print("Chat response:", chat_response)

硬开关

虽然软开关始终可用，但硬开关也可以通过以下 API 调用配置在 vLLM 中使用。要禁用思考，请使用

curl http://localhost:8000/v1/chat/completions -H "Content-Type: application/json" -d '{"model": "Qwen/Qwen3-8B","messages": [{"role": "user", "content": "Give me a short introduction to large language models."}],"temperature": 0.7,"top_p": 0.8,"top_k": 20,"max_tokens": 8192,"presence_penalty": 1.5,"chat_template_kwargs": {"enable_thinking": false}
}'

您可以按照下面所示的方式，使用 openai Python SDK中的客户端：

from openai import OpenAI
# Set OpenAI's API key and API base to use vLLM's API server.
openai_api_key = "EMPTY"
openai_api_base = "http://localhost:8000/v1"client = OpenAI(api_key=openai_api_key,base_url=openai_api_base,
)chat_response = client.chat.completions.create(model="Qwen/Qwen3-8B",messages=[{"role": "user", "content": "Give me a short introduction to large language models."},],temperature=0.7,top_p=0.8,top_k=20,presence_penalty=1.5,extra_body={"chat_template_kwargs": {"enable_thinking": False}},
)
print("Chat response:", chat_response)

解析思考内容

vLLM 支持将模型生成的思考内容解析为结构化消息：

--enable-reasoning-parser: 这是一个标志，表示启用推理解析器功能。推理解析器可以帮助模型更好地理解和处理复杂的查询或者执行某些类型的逻辑推理。
--reasoning-parser deepseek_r1: 进一步指定了使用哪个具体的推理解析器实现。

vllm serve Qwen/Qwen3-8B --enable-reasoning-parser --reasoning-parser deepseek_r1

响应消息除了包含 content 字段外，还会有一个名为 reasoning_content 的字段，其中包含模型生成的思考内容。

上下文长度

Qwen3 模型在预训练中的上下文长度最长为 32,768 个 token。为了处理显著超过 32,768 个 token 的上下文长度，应应用 RoPE 缩放技术。我们已经验证了 YaRN 的性能，这是一种增强模型长度外推的技术，可确保在长文本上的最佳性能。

vLLM 支持 YaRN，可以配置为

vllm serve Qwen3/Qwen3-8B --rope-scaling '{"type":"yarn","factor":4.0,"original_max_position_embeddings":32768}' --max-model-len 131072

vLLM 实现了静态 YaRN，这意味着无论输入长度如何，缩放因子都保持不变，这可能会对较短文本的性能产生影响。 我们建议仅在需要处理长上下文时添加 rope_scaling 配置。还建议根据需要调整 factor。例如，如果您的应用程序的典型上下文长度为 65,536 个 token，则最好将 factor 设置为 2.0。

如果未指定 --max-model-len，config.json 中的默认 max_position_embeddings 被设置为 40,960，vLLM 将使用该值。此分配包括为输出保留 32,768 个 token，为典型提示保留 8,192 个 token，这足以应对大多数涉及短文本处理的场景，并为模型思考留出充足空间。如果平均上下文长度不超过 32,768 个 token，我们不建议在此场景中启用 YaRN，因为这可能会降低模型性能。

Python 库使用

vLLM 也可以直接用作 Python 库，这对离线批量推理非常方便，但缺少一些仅限 API 的功能，例如将模型生成解析为结构化消息。

以下展示了将 vLLM 用作库的基本用法：

from transformers import AutoTokenizer
from vllm import LLM, SamplingParams# Initialize the tokenizer
tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen3-8B")# Configurae the sampling parameters (for thinking mode)
sampling_params = SamplingParams(temperature=0.6, top_p=0.95, top_k=20, max_tokens=32768)# Initialize the vLLM engine
llm = LLM(model="Qwen/Qwen3-8B")# Prepare the input to the model
prompt = "Give me a short introduction to large language models."
messages = [{"role": "user", "content": prompt}
]
text = tokenizer.apply_chat_template(messages,tokenize=False,add_generation_prompt=True,
)# Generate outputs
outputs = llm.generate([text], sampling_params)# Print the outputs.
for output in outputs:prompt = output.promptgenerated_text = output.outputs[0].textprint(f"Prompt: {prompt!r}, Generated text: {generated_text!r}")

SGLang

要了解更多关于 SGLang 的信息，请参阅官方文档。

默认情况下，你可以通过 pip 在新环境中安装 sglang ：

pip install "sglang[all]>=0.4.6"

借助 SGLang ，构建一个与OpenAI API兼容的API服务十分简便，该服务可以作为实现OpenAI API协议的服务器进行部署。默认情况下，它将在 http://localhost:30000 启动服务器。您可以通过 --host 和 --port 参数来自定义地址。请按照以下所示运行命令：

python -m sglang.launch_server --model-path Qwen/Qwen3-8B

然后，您可以利用 create chat interface 来与Qwen进行对话：

curl http://localhost:30000/v1/chat/completions -H "Content-Type: application/json" -d '{"model": "Qwen/Qwen3-8B","messages": [{"role": "user", "content": "Give me a short introduction to large language models."}],"temperature": 0.6,"top_p": 0.95,"top_k": 20,"max_tokens": 32768
}'

from openai import OpenAI
# Set OpenAI's API key and API base to use SGLang's API server.
openai_api_key = "EMPTY"
openai_api_base = "http://localhost:30000/v1"client = OpenAI(api_key=openai_api_key,base_url=openai_api_base,
)chat_response = client.chat.completions.create(model="Qwen/Qwen3-8B",messages=[{"role": "user", "content": "Give me a short introduction to large language models."},],temperature=0.6,top_p=0.95,top_k=20,max_tokens=32768,
)
print("Chat response:", chat_response)

思考与非思考模式

Qwen3 模型会在回复前进行思考。这种行为可以通过硬开关（完全禁用思考）或软开关（模型遵循用户关于是否应该思考的指令）来控制。

硬开关在 vLLM 中可以通过以下 API 调用配置使用。要禁用思考，请使用

curl http://localhost:30000/v1/chat/completions -H "Content-Type: application/json" -d '{"model": "Qwen/Qwen3-8B","messages": [{"role": "user", "content": "Give me a short introduction to large language models."}],"temperature": 0.7,"top_p": 0.8,"top_k": 20,"max_tokens": 8192,"presence_penalty": 1.5,"chat_template_kwargs": {"enable_thinking": false}
}'

from openai import OpenAI
# Set OpenAI's API key and API base to use SGLang's API server.
openai_api_key = "EMPTY"
openai_api_base = "http://localhost:30000/v1"client = OpenAI(api_key=openai_api_key,base_url=openai_api_base,
)chat_response = client.chat.completions.create(model="Qwen/Qwen3-8B",messages=[{"role": "user", "content": "Give me a short introduction to large language models."},],temperature=0.7,top_p=0.8,top_k=20,presence_penalty=1.5,extra_body={"chat_template_kwargs": {"enable_thinking": True}},
)
print("Chat response:", chat_response)

解析思考内容

SGLang 支持将模型生成的思考内容解析为结构化消息：

python -m sglang.launch_server --model-path Qwen/Qwen3-8B --reasoning-parser deepseek-r1

响应消息除了包含 content 字段外，还会有一个名为 reasoning_content 的字段，其中包含模型生成的思考内容。

上下文长度

SGLang 支持 YaRN，可以配置为

python -m sglang.launch_server --model-path Qwen3/Qwen3-8B --json-model-override-args '{"rope_scaling":{"type":"yarn","factor":4.0,"original_max_position_embeddings":32768}}'

SGLang 实现了静态 YaRN，这意味着无论输入长度如何，缩放因子都保持不变，这可能会对较短文本的性能产生影响。 我们建议仅在需要处理长上下文时添加 rope_scaling 配置。还建议根据需要调整 factor。例如，如果您的应用程序的典型上下文长度为 65,536 个 token，则最好将 factor 设置为 2.0。

config.json 中的默认 max_position_embeddings 被设置为 40,960，SGLang 将使用该值。此分配包括为输出保留 32,768 个 token，为典型提示保留 8,192 个 token，这足以应对大多数涉及短文本处理的场景，并为模型思考留出充足空间。如果平均上下文长度不超过 32,768 个 token，我们不建议在此场景中启用 YaRN，因为这可能会降低模型性能。

Agent 示例

Qwen3 在工具调用能力方面表现出色。推荐使用 Qwen-Agent 来充分发挥 Qwen3 的 Agent 能力。Qwen-Agent 内部封装了工具调用模板和工具调用解析器，大大降低了代码复杂性。

要定义可用的工具，您可以使用 MCP 配置文件，使用 Qwen-Agent 内置的工具，或者自行集成其他工具。

from qwen_agent.agents import Assistant# 定义 LLM
llm_cfg = {'model': 'Qwen3-30B-A3B',# 使用阿里云服务:# 'model_type': 'qwen_dashscope',# 'api_key': os.getenv('DASHSCOPE_API_KEY'),# 使用本地部署的模型:'model_server': 'http://localhost:8000/v1',  # 指定模型服务的 API 地址。这里使用了本地运行的服务'api_key': 'EMPTY',    # 用于访问模型服务的密钥# 其他参数:# 'generate_cfg': {#         # 添加： 当应答内容为"<think>this is the thought</think>this is the answer;#         # 不添加： 当回复内容已被 reasoning_content 和 content.翻译分开时。#         'thought_in_content': True,#     },
}# 定义工具（Tools）
tools = [{'mcpServers': {  # 定义了一个工具，用于访问某些服务（如 time 和 fetch）。'time': {        # 调用 mcp-server-time 命令，获取本地时间（时区为上海）。'command': 'uvx','args': ['mcp-server-time', '--local-timezone=Asia/Shanghai']},"fetch": {    # 调用 mcp-server-fetch 命令，可能用于获取某些数据。"command": "uvx","args": ["mcp-server-fetch"]}}},'code_interpreter',  # 表示启用内置的代码解释器工具，用于执行代码片段。
]# 定义 Agent
bot = Assistant(llm=llm_cfg, function_list=tools)    # 使用 llm_cfg 和 tools 创建了一个 Assistant 对象。这个对象将作为智能助手，处理用户输入的消息。# Streaming generation
messages = [{'role': 'user', 'content': 'https://qwenlm.github.io/blog/ Introduce the latest developments of Qwen'}]    # 用户输入的消息，包含一个 URL 和一个请求
for responses in bot.run(messages=messages):    # 调用智能助手的 run 方法，处理用户输入的消息。pass
print(responses)    # 打印最终生成的响应内容。

更多使用等待更新！