如果你最近常逛模型社区应该已经注意到Qwen3.5的动静了。我是在魔乐社区看到正式上线的通知当时第一反应不是“又有新模型可以玩了”而是“昇腾上的适配跟上了没有”。说实话等一个模型的开源版本和等它在国产算力上跑起来完全是两回事。手里这批昇腾设备总不能一直只跑老模型新模型上线如果不能快速部署那再强的能力也只是纸面参数。这篇教程就是我基于自己的部署过程整理的从魔乐社区拉权重、检查环境、配推理框架、起服务到接口联调全流程都有适合手里有昇腾卡、想快速把Qwen3.5跑起来做二次开发的开发者参考。我尽量把每一步为什么要这么做讲清楚不只是甩命令。因为部署这件事命令只是表面真正容易出问题的是环境匹配、路径处理和框架版本选择。把这些磨明白了换下一个模型上来你也能自己搞定。1. Qwen3.5上线魔乐社区为什么值得专门写一篇1.1 这次模型更新解决的核心痛点先说模型本身。Qwen3.5这一代在魔乐社区的模型卡片上挂出来之后我粗略扫了一圈特性说明几个关键变化其实都踩在咱们日常使用的痛点上面。一个是长上下文能力的继续增强。之前跑Qwen3的时候长文本任务最怕的就是上下文窗口拉长之后显存占用跟着暴涨稍微设置不对就OOM。Qwen3.5在架构上做了一些调整同样长度下的显存开销比上一代更可控。我自己实测的感受是处理几十页文档摘要或者整仓库代码分析时首轮我们需要塞进去的提示词很大但推理过程中的资源占用没有像以前那样陡增。这对做RAG和代码助手这类场景的开发来说是个实打实的利好。另一个是工具调用和结构化输出的稳定性。以前让模型调用外部工具经常出现参数格式不对、漏字段、把JSON输出成Markdown代码块之类的问题。Qwen3.5在这块明显下了功夫至少在魔乐社区提供的权重版本里工具调用的成功率和格式规整度都要好不少。我后面在部署完测功能的时候故意拿多轮工具调用去压它出错率比之前低很多。还有一个值得说的点是多模态能力的整合方式。Qwen3.5并不是单纯把文本模型和视觉模型拼在一起而是走了更统一的tokenizer和embedding方案。这意味着部署的时候不需要单独加载两个模型再拼接一个模型目录就能搞定图文理解。对于昇腾上部署来说这大大减少了工作量因为不需要处理跨模型的特征对齐。1.2 昇腾栈部署为什么是刚需可能有人会问模型上线魔乐社区我用别的推理框架跑不就行了为什么非得基于昇腾专门写一篇教程原因是生态差异。Qwen3.5发布之后x86加CUDA的环境下部署教程满天飞因为生态成熟装上就能跑。但昇腾这边不一样虽然硬件性能不差可软件栈的适配节奏总是慢半拍。很多开源模型发布之后昇腾上的可用方案要过一段时间才跟上。这次Qwen3.5在魔乐社区上线同时就有昇腾适配的推理方案放出来这是个很积极的信号。另一个原因是实际需求。现在不少企业和研究机构都在用昇腾设备做私有化部署数据不出域、模型本地跑。但很多开发者拿着昇腾卡辛辛苦苦把模型权重下载下来结果卡在环境配置上。昇腾的软件栈比CUDA复杂驱动、固件、CANN、推理框架缺一不可版本之间还有兼容性要求。如果没有一份踏实的部署记录光是排查环境问题就能耗掉一整天。所以这篇教程的核心目标就是让你照着做能把Qwen3.5在昇腾上真正跑起来而不是停留在“模型下载好了”的阶段。2. 部署前的准备硬件选型与软件栈梳理2.1 硬件怎么选显存和算力怎么匹配先说硬件。昇腾设备目前常见的有训练卡和推理卡两大类形态上有整机也有加速卡。Qwen3.5的权重分多个尺寸从几B级别到几十B级别都有。我一般按一个粗口径估算模型权重需要的显存大约是参数量乘以2字节也就是FP16精度下每10亿参数约2GB显存。然后还要额外留出KV Cache的空间这个根据并发量和上下文长度动态变化。简单算的话一个7B模型光权重就14GB左右再加上KV Cache单卡至少需要32GB才跑得比较舒服如果是几十B的大尺寸基本就要考虑多卡张量并行或者量化了。如果你手里的卡显存不大建议先从小尺寸权重开始试。Qwen3.5在魔乐社区挂出来的权重小尺寸版本对部署环境的要求低很多跑通流程之后再上大模型也不迟。我这次演示用的就是中等尺寸的权重单卡可以搞定方便复现。还要注意算力匹配的问题。昇腾不同型号的算力差异很大但部署教程的核心逻辑是一样的只是性能参数会变。我的建议是先不管性能确保环境能跑通能跑通之后再去看吞吐量和延迟再做性能调优。2.2 驱动、固件与CANN版本匹配这是整个部署过程中最容易翻车的地方。昇腾设备要正常工作不是装个Python包就行必须保证底层软件栈是对的。从上到下大致是NPU驱动、固件、CANN Toolkit再往上才是Python层面的torch_npu和推理框架。每一层都有版本号层与层之间有匹配关系。如果驱动固件跟CANN不匹配很常见的现象就是npu-smi info能看到卡但一跑模型就报错报错信息五花八门有的说设备不存在有的说算子编译失败。我的习惯是装完环境之后先跑一遍官方提供的环境检查命令。昇腾的CANN安装包里自带一个npu-smi info工具能查看驱动固件版本和NPU状态。看到卡的状态是OK才算过了第一关。然后还需要确认CANN的版本和推理框架的适配情况。以vLLM-Ascend为例它会在安装时检查CANN的版本范围版本太老或太新都可能出问题。这里我给一个很实际的建议不要追求最新版本。昇腾的软件栈更新的节奏是“大版本稳定优先”选一个已经磨合过的组合比追新更省心。检查命令大概是这样的npu-smi info输出里会包含驱动版本、固件版本、芯片温度、显存使用情况。如果能看到多张卡说明驱动识别正常。再看CANN环境是否生效source /usr/local/Ascend/ascend-toolkit/set_env.sh echo $ASCEND_HOME_PATH能打印出CANN路径说明Toolkit已经装好。这里的路径不一定一样取决于你的安装位置。2.3 推理框架选型vLLM-Ascend 还是 MindIE昇腾上的推理框架现在主要两条路一条是昇腾官方孵化的MindIE另一条是vLLM的昇腾适配版vLLM-Ascend。MindIE的特点是性能优化做得多尤其是在大模型推理的调度和算子融合上官方倾注的资源多吞吐量往往有惊喜。但它的缺点是配置项复杂很多参数的概念跟社区常见的推理框架不一样新手容易迷糊。而且MindIE对模型输入格式有一定的要求权重转换步骤多一步Debug起来不够直观。vLLM-Ascend则是把社区熟悉的vLLM搬到了昇腾上好处是API和配置习惯跟vLLM一致OpenAI兼容的服务接口可以直接用部署经验可以迁移。虽然一些底层算子性能不如MindIE极端优化但胜在稳、好上手、社区问题多、踩坑记录也丰富。我这次的部署选的是vLLM-Ascend。理由很简单我要的是一个能快速跑通、方便二次开发的方案而不是极限性能压测。vLLM-Ascend的启动参数、服务接口、客户端调用方式都用的是大家熟悉的那一套。如果你之后要切成MindIE思路也类似只是配置文件要重写一些。3. 魔乐社区模型下载与权重落地3.1 从魔乐社区拉取模型权重确定好方案之后第一步就是把权重从魔乐社区拉到本地。魔乐社区的模型仓库是基于Git风格管理的常规做法有两种一种是在网页端直接点下载适合只想要单文件的情况另一种是用git命令克隆整个仓库适合需要完整权重和配置文件的场景。做部署的话我强烈建议用后一种方式因为模型推理需要的不只是权重文件还有config、tokenizer、chat_template等配套文件缺一个都可能出问题。git clone https://模型的仓库地址/Qwen3.5-7B-Instruct.git如果仓库比较大或者网络不稳定可以先拉下来再断网操作。这里有个细节模型仓库一般用的是Git LFS管理大文件所以本机要装好git-lfs。否则你拉下来的可能不是真正的权重而是一堆占位指针文件文件大小只有几百字节加载模型的时候直接报错。拉取完成后先看一眼目录大小确认权重文件真实存在du -sh Qwen3.5-7B-Instruct如果目录大小只有几十KB那基本就是LFS没生效需要重新拉取或者手动执行git lfs pull这一步很多第一次部署昇腾环境的人都会忽略在魔乐社区的模型下载评论里也经常能看到类似提问但其实就是一个工具没装全的问题。3.2 权重落地后必须检查的四个文件权重到位之后不要急着启动服务先花两分钟检查关键文件是否齐全。我通常按下面四个文件过一遍第一个是config.json。这里记录了模型架构、层数、头数、词汇表大小、context长度等关键参数。昇腾上的推理框架启动时主要靠它来构建计算图如果配置缺失或者与你下载的权重版本不一致后面跑到某个算子就会莫名其妙报错。第二个是tokenizer.json或者tokenizer.model。分词器文件决定了文本怎么被切分成tokenQwen系列的对话模板也依赖分词器配套的token id。如果这个文件不对最典型的症状是模型能启动但回答全是乱码或者输入对话内容被截断。第三个是generation_config.json。它控制模型默认的生成参数比如温度、top_p、max_length这些。有时候你在推理框架里没有显式指定参数框架会读这个文件作为默认值。如果文件里写了特殊的EOS和PAD token配置而你的加载脚本没适配会出现生成不停止、一直吐字的情况。第四个是模板文件通常是chat_template配置或包含在tokenizer_config.json里。Qwen3.5的对话格式需要特定的模板来组装用户消息和工具调用消息推理框架加载之后会用这个模板来格式化输入。检查的时候可以打开看几眼确认模板不是空的。都确认完之后再进下一步。这四步虽然枯燥但可以帮你把后面一大部分疑难杂症提前摁掉。我自己有一次部署别的模型就是tokenizer_config里的模板版本不对导致工具调用消息直接被模型忽略排查了一整个下午。4. 基于昇腾的推理服务部署实操4.1 安装vLLM-Ascend坑比想象中少环境检查和权重检查都过了之后就可以装推理框架了。vLLM-Ascend的安装比我想象中顺利核心原因是它把很多底层兼容问题都封装掉了。安装方式直接用pippip install vllm-ascend这里有个版本匹配的问题需要注意。vLLM-Ascend会根据你当前的Python版本、torch版本和CANN版本自动选择兼容的构建版本但为了保险我建议装完之后打印一下版本确认python -c import vllm; print(vllm.__version__) python -c import vllm_ascend; print(vllm_ascend.__version__)如果导入失败多半是torch和CANN的版本组合有问题。昇腾上跑大模型torch需要安装昇腾适配版torch_npu不能直接用社区版torch。一般CANN安装包会带配套的torch_npu或者需要单独安装pip install torch-npu这里有个容易混淆的点torch_npu不是普通的Python包它跟CANN版本强绑定。如果你装的torch_npu版本和CANN Toolkit版本不匹配import阶段可能不报错但一旦往NPU上放张量立刻报算子错误。我个人的经验是在昇腾环境里不要随意升级torch或者torch_npu除非你确认新版本跟CANN、vLLM-Ascend都兼容。稳定的组合比新版本带来的小提升更值钱。4.2 启动OpenAI兼容服务的完整命令装好框架之后启动服务的命令跟vLLM原生写法非常接近。我用的命令大概长这样python -m vllm.entrypoints.openai.api_server \ --model /path/to/Qwen3.5-7B-Instruct \ --host 0.0.0.0 \ --port 8000 \ --dtype float16 \ --max-model-len 32768 \ --gpu-memory-utilization 0.9 \ --tensor-parallel-size 1逐个解释一下参数。--model就是模型目录的路径可以传魔乐社区拉下来的本地目录也可以传一个模型标识符让它自动下载但本地部署一般建议直接用路径省得再走一遍网络。--max-model-len控制最大上下文长度。Qwen3.5支持比较长的上下文但实际长度要受显存约束。我填32768也就是32K如果你显存紧张可以调低到16384或8192。--gpu-memory-utilization是GPU显存利用率上限默认是0.9表示允许推理框架使用90%的显存。昇腾上这个参数同样有效调小一点可以留出显存给其他任务调大了容易OOM。建议先从0.85到0.9开始稳定运行之后再试着调大。--tensor-parallel-size是张量并行数。单卡跑就填1多卡就把多张卡编号测出来之后填对应数量。这个参数直接关系到多卡通信和显存分配如果填错了启动时会提示找不到可用设备。启动之后日志里会出现类似“Available routes”的信息说明服务已经起来了。看到这个再继续下一步。还有几个值得注意的细节。一个是昇腾环境里建议指定ASCEND_RT_VISIBLE_DEVICES环境变量来限定当前进程使用哪张卡export ASCEND_RT_VISIBLE_DEVICES0如果不指定某些版本可能把多张卡都占用或者出现调度混乱。另一个是如果启动时提示缺少libascend之类的库一般是CANN环境变量没source。所以启动服务前先把CANN的环境变量加载一遍确保source /usr/local/Ascend/ascend-toolkit/set_env.sh4.3 客户端调用与并发验证服务起来之后用OpenAI SDK或者纯HTTP请求都能调。先做最简单的验证用curl发一个对话请求curl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: /path/to/Qwen3.5-7B-Instruct, messages: [{role: user, content: 你好简单介绍一下你自己}], max_tokens: 256 }这里有个细节请求体里的model字段可以传启动服务时用的模型路径也可以传任意字符串。vLLM默认会把它当作一个标识不会去重新加载模型。但要注意如果你同时加载了多个模型model字段就要传准确否则会路由错误。能返回正常回复之后接下来我建议测一下并发。因为部署服务给业务用不是只给自己用并发能力才是关键。可以用简单的Python脚本发并发请求from openai import OpenAI client OpenAI( base_urlhttp://localhost:8000/v1, api_keyEMPTY ) def ask(prompt): resp client.chat.completions.create( modelQwen3.5, messages[{role: user, content: prompt}], max_tokens128 ) return resp.choices[0].message.content多线程并发调用重点观察两点一是是否出现超时或连接拒绝二是返回内容是否串了。服务端日志里会显示吞吐量和延迟指标如果吞吐量很低可能需要调大并发数或调整max-num-seqs参数。这个参数控制单次推理 batch 内最多处理多少个序列启动服务时可以用--max-num-seqs指定。增大它能让并发请求更好地打满算力但会占用更多显存。我一般从16开始调观察显存余量和吞吐变化找到平衡点。5. 性能调优与常见问题排查5.1 首token延迟偏高怎么查服务跑通之后接下来就是性能问题。首token延迟也就是用户发请求到收到第一个token的时间是体感最明显的指标。如果你发现这个值偏高先不要急着怀疑硬件我给一个排查顺序。先看是不是上下文过长。request里如果塞了很长的历史对话或者文档prefill阶段的计算量就大首token延迟自然高。Qwen3.5支持长上下文但长上下文的prefill计算时间是绕不开的。业务上可以通过限制输入长度、做检索裁剪来缓解。再看是不是模型体积和硬件算力不匹配。大模型在小卡上跑prefill阶段每个token的计算时间都很长这是硬件天花板除了换卡或者用量化没有别的办法。然后看调度参数。vLLM-Ascend里--max-model-len设置得很长比如128K但实际请求只有几百token显存和调度资源会为长序列预留影响小请求的处理效率。所以部署时不要把--max-model-len设置成模型上限而是根据业务实际需求来。如果业务最多用到8K就设成8192资源利用率会明显提升。最后看日志里有没有算子重编译的警告。昇腾上首次运行某些算子需要编译编译过程中首次请求会特别慢。这属于冷启动问题服务起来之后可以先发一个简单请求预热让算子编译完后续延迟就正常了。5.2 显存不足与OOM处理昇腾上跑大模型OOM是绕不开的话题。我在部署过程中也遇到过几次总结下来主要分两类。一类是权重加载阶段OOM。启动服务时框架需要把权重加载到显存如果权重本身超过显存容量直接启动失败。解决办法是换小模型、打开量化或者用多卡张量并行。另一类是KV Cache OOM。启动时--gpu-memory-utilization和--max-model-len的配置决定了KV Cache大小。运行时如果并发数暴涨、序列长度超过预期就可能出现显存不够分配。如果日志里出现“No available memory”或者“Out of memory”字样我的处理办法是先把--gpu-memory-utilization调低一点比如从0.9调到0.85给运行时留足缓冲。然后把--max-num-seqs调小限制单batch最大并发序列数。这两步做完OOM基本能缓解大半。还有一个经验昇腾的显存管理在部分版本下不会自动释放碎片长时间运行后可能出现“显存总量够但分配不出大块连续显存”的情况。遇到这种情况最简单的办法是重启服务。虽然粗暴但有效。如果要长期跑建议加个定时健康检查发现异常就自动重启。5.3 实测踩坑记录与避坑技巧最后分享几个我这次部署过程中真实遇到的坑希望能帮你省点时间。第一个坑是CANN环境变量没有在启动服务的终端里加载。我一开始是在普通终端里直接启动服务结果报错找不到CANN相关库。排查了半天发现是环境变量没source。这个问题很基础但容易因为终端复用而忽略。建议在启动命令前把source命令也写进启动脚本保证每次都是全新环境。第二个坑是模型路径中的符号链接。我图省事把模型目录做了一个软链接到另一个磁盘结果加载权重时一直报文件不存在。后来发现是软链接指向的磁盘挂载权限不对进程没有读取权限。所以模型权重目录最好放在本地磁盘避免跨文件系统软链带来的坑。第三个坑是请求返回内容偶尔出现截断。排查后发现是generation_config.json里的stop token配置和请求里的stop参数重叠导致。Qwen3.5的对话模板里本身有特殊结束符如果在调用时额外传了不兼容的stop字符串就会提前断掉。解决方法是先不传自定义stop参数用模板默认的结束行为跑业内测试确认没问题后再走业务逻辑。第四个坑是魔乐社区下载的超大文件校验问题。有些权重文件几个GB甚至几十GB下载过程中容易出错。如果启动时报Model weights file not found或者unexpected key可以先比对本地文件的SHA256和模型仓库里的校验值。没通过的话重新拉取单个文件没必要整个仓库重来一遍。还有一个我自己经常用的小技巧启动服务之前先用一个小尺寸模型跑通全流程确认环境、代码、接口都没问题再切换成目标尺寸模型。这样做的好处是问题定位很快因为小模型加载快、显存占用低报错信息也简单。等小模型通了再切大模型如果遇到性能或显存问题那基本可以确定是资源层面的问题不是配置问题。结尾一点个人经验这次基于昇腾部署Qwen3.5整体比我预想中顺利。魔乐社区里的权重文件组织得很规整加上vLLM-Ascend的适配已经比较成熟照着流程走一遍从下载到服务可用大概花了一下午。最费时间的反而不是配置而是排查版本匹配和文件完整性这些基础问题。我给同样在做昇腾部署的朋友一个建议不要先追求“把最大模型跑起来”而是先建立一套属于自己的部署检查单。从硬件状态、CANN版本、权重文件、框架启动参数到客户端验证每一步都明确该看什么、该跑什么命令。有了这个检查单之后不管换什么模型、换什么卡都是在既定流程上做参数调整而不是每次从零开始踩坑。Qwen3.5后续应该还会更新迭代昇腾的适配也会越来越完善。这篇教程里提到的方法和思路放到下一个模型上依然适用。如果你也正在用昇腾设备部署Qwen3.5希望这篇记录能帮你少走几步弯路。
