简介：面向国产昇腾推理服务器与加速卡的大模型部署场景，该可运行源码包提供了在华为硬件上搭建Dify平台的完整参考。内容涵盖大模型推理引擎MindIE以及Embedding、Rerank组件的部署测试，并给出Qwen模型在双卡环境下的配置与验证结果，包括实际运行效果和显存占用情况，适合需要将Dify接入国产AI算力的开发者和运维人员。资源共两个文件，包括项目配置和说明页面，整体仅四KB，轻量便携，可对照源码快速梳理部署步骤，规避镜像启动、模型调用等常见问题，也适合用于国产化部署方案的预研与最小验证。已有八十六人学习下载，可作为昇腾环境下部署Dify的起步模板，帮助节省环境调试时间，快速验证国产化平台运行大模型应用的可行性。 最近把Dify完整跑在了华为昇腾环境里，前后折腾了小一周，终于把从应用编排到模型推理的整条链路打通了。Dify本身是个开源智能体平台，负责工作流编排、知识库管理、Agent对话这些事情；昇腾是国产AI芯片，负责真正的模型推理。这两个放在一起，就构成了一套完全跑在国产算力上的LLM应用底座。
写这篇文章，主要是因为有类似需求的人其实不少，但网上能查到的资料，要么是Dify接OpenAI官方接口，要么是接国外推理框架，针对昇腾的完整实操记录非常少。如果你手里有昇腾开发板、训推一体机或者服务器，想把Dify这类平台跑起来做私有化智能体应用，这篇内容可以直接照着做。我会把环境配置、源码部署、模型对接、常见坑全部梳理一遍，尽量做到每一步都说得明白。
1. 部署前先看全局：这套组合到底需要哪些角色
1.1 Dify在整条链路里扮演什么角色
先说清楚一个容易搞混的概念：Dify不是一个模型推理引擎，它不直接调用NPU，也不负责跑大模型的forward过程。它是一个LLM应用开发与编排平台，提供的是对话应用、工作流、Agent、知识库、工具调用、模型管理这些层能力。你可以把它理解成餐厅的前台和后厨之间的传菜员——它负责接单、配菜、安排出餐流程，但真正炒菜的后厨，得另外找。
所以部署Dify这件事，天然分成两半：一半是让Dify自己的Web服务、API服务、数据库、缓存跑起来；另一半是准备一个可以被Dify调用的模型推理服务。Dify通过OpenAI兼容的接口格式，把用户的请求转发给推理服务，拿到结果后再做后续的工作流处理和展示。
这个认知很重要，因为我见过不少人在部署的时候，Dify页面起来了，但一问模型就报错，到处找问题，最后发现是推理服务那一半压根没配。下面所有的部署工作，都是围绕这两半来展开的。
1.2 昇腾侧推理方案怎么选
昇腾上跑推理，目前主流的有三条路：MindIE、vLLM-Ascend、以及llama.cpp在昇腾上的移植版本。这里面我实际用的是MindIE，也就是华为官方提供的昇腾推理引擎。选择理由很简单：它跟CANN底层的适配最深，多卡并行、量化、连续批处理这些关键特性都做得比较完善，而且官方会提供配套的容器镜像和部署文档，对于生产环境来说是最稳的选项。
vLLM-Ascend我也试过，它在API接口风格上跟原版vLLM几乎一致，用惯了vLLM的人上手更快，但当时我在模型权重格式转换和设备映射上遇到了一些麻烦，版本匹配没有MindIE那么直觉。llama.cpp那条路适合轻量级、低资源场景，但功能完整度和并发能力偏弱，用于Dify这种需要稳定服务化调用的场景，不是首选。
所以最终架构是：Dify的api服务和web前端跑在应用层，后端接MindIE启动的推理服务，模型跑在昇腾NPU上，中间走OpenAI兼容的HTTP接口。这样一个组合，既能保留Dify完整的工作流编排能力，又能把算力底座换成国产芯片，整个链路可控性非常强。
2. 环境和软件栈准备：一步错步步错
2.1 硬件与系统要求
先说硬件。昇腾设备目前在市面上比较常见的是910B系列和310P系列，310P算力偏入门，适合跑7B左右的模型做轻量推理；910B性能强很多，跑14B甚至更大模型、或者需要较高并发的时候，建议直接上910B。显存方面，7B模型用FP16精度大概需要16GB以上显存，加上推理过程中的KV Cache和中间激活值，单卡32GB会比较从容。如果你的模型更大，或者想跑长上下文，最好上多卡或者直接选更大显存的型号。
系统层面，官方对openEuler和Ubuntu的支持比较好，我用的Ubuntu 22.04 LTS，整体很顺利。内存建议至少64GB，因为除了模型本身，前端构建、后端服务、中间缓存都要吃内存，如果机器配置太低，后面编译前端的时候容易直接被OOM干掉。存储建议准备至少100GB可用空间，Dify源码、依赖包、模型权重文件加起来，体积比你想象的大得多。
2.2 驱动、CANN、MindIE的版本配对
昇腾这套软件栈，最让人头疼的其实是版本配对。驱动、固件、CANN Toolkit、MindIE每一个都有版本号，而且它们之间必须匹配，不能随便乱装。这一点跟CUDA生态不太一样，CUDA至少是向下兼容的，昇腾这边版本不匹配，轻则某个API找不到，重则设备直接识别不到。
操作顺序是这样的：先装NPU驱动和固件，再装CANN Toolkit，最后装MindIE。驱动安装一般是一个.run文件，以root权限执行后，用npu-smi info这个命令检查芯片是否被系统识别。如果这个命令能正常列出昇腾芯片的型号、显存、温度这些信息，说明驱动层已经通了。接下来设置环境变量，把CANN和MindIE的库路径加进去：
source /usr/local/Ascend/ascend-toolkit/set_env.sh source /usr/local/Ascend/mindie/set_env.sh这一步很多人会漏。尤其是直接用systemd或者脚本启动服务的时候，如果忘了source环境变量，后面跑模型服务会报一堆libascendcl.so找不到之类的错，但其实库都是装好的，纯粹是环境变量没生效。
版本方面我举一个我实际用过的组合：NPU驱动23.0.rc1 + CANN 8.0.RC1 + MindIE 1.0.RC2，跑Qwen2.5系列没有问题。不同型号的昇腾芯片，驱动包不一样，千万别装错。拿不准的时候，去查官方发布的兼容矩阵，比对好芯片型号和系统版本再选包，这一步能省下大量排查时间。
3. 获取可运行源码，把Dify应用层搭起来
3.1 源码部署还是容器部署
Dify官方推荐的是Docker Compose方式，一行命令拉起所有依赖，很省事。但在昇腾环境里，我更推荐源码方式部署。原因是推理服务通常也需要在容器或者特殊环境里跑，如果Dify本身用Docker，要考虑容器网络、NPU设备映射、环境变量传递一堆问题，调试起来非常绕。源码部署的话，所有进程都在宿主机上，日志直接在终端里刷，哪里出错一眼就能看到。
Dify的源码可以从GitHub官方仓库拉取。拿到源码后，先看目录结构，重点是有三个：api是后端Python服务，web是前端Next.js应用，docker里面是各个依赖组件的编排文件。源码部署本质上就是先把api跑起来，再把web构建出来跑起来，中间依赖PostgreSQL、Redis这两个基础组件。
3.2 后端服务和依赖组件启动
后端和依赖组件的顺序，我建议是先起PostgreSQL和Redis，再起Dify的api服务。数据库和缓存如果直接用源码方式不好装，可以偷懒用Docker把这两个组件先跑起来，业务进程保持源码方式，这样兼顾了调试便利和依赖管理的省心。大致步骤是：
# 启动PostgreSQL和Redis容器 docker run -d --name dify-pg -p 5432:5432 \ -e POSTGRES_PASSWORD=difyai \ -e POSTGRES_DB=dify \ postgres:15-alpine docker run -d --name dify-redis -p 6379:6379 redis:7-alpine然后进入api目录，创建虚拟环境，安装Python依赖：
cd api python3 -m venv venv source venv/bin/activate pip install -r requirements.txt依赖安装这块有个经验：如果网络环境比较慢，千万别硬等，配置好镜像源再装。Dify的依赖列表里有不少重量级包，直接装可能要半小时以上，用国内镜像源能快很多。
接下来需要配置环境变量。源码目录里有一个.env.example文件，先把它复制成.env，然后重点改几个值：数据库连接地址、Redis地址、以及SECRET_KEY。SECRET_KEY是Dify用来加密会话和敏感信息的，随便生成一串随机字符就行，但不要用默认值。改完之后，执行数据库迁移：
flask db upgrade这个命令会把Dify的所有数据表结构初始化到PostgreSQL里。如果这里报错，九成是.env里的数据库连接地址写错了，或者PostgreSQL没起来。
3.3 前端构建与整体启动
后端跑起来之后，还需要启动前端。前端是Next.js项目，依赖pnpm管理，先确认环境里有Node.js 18或20，版本太老或太新都可能出问题。构建命令如下：
cd web pnpm install pnpm build pnpm start前端构建的时间取决于机器性能，一般在五到十分钟左右。构建完成后，pnpm start会默认监听3000端口，这时候浏览器访问http://localhost:3000，就能看到Dify的安装引导页面了。首次访问会让你设置管理员邮箱和密码，走完引导，平台主体就算部署完成。
到这里，Dify应用层已经通了，但还差最关键的模型推理服务。下一步是把昇腾上的MindIE跑起来，再让两边对接上。
4. 昇腾推理服务的配置与模型对接
4.1 用MindIE启动一个开源模型服务
模型选型上，我以Qwen2.5-7B-Instruct为例，这个模型在昇腾上的适配情况比较成熟，效果也不错。你要做的第一件事是拿到模型权重文件，可以是HuggingFace格式的原始权重。MindIE支持直接加载这类权重，但如果追求更高推理性能，可以先把它转换成MindIE IR格式，转换这一步官方提供了工具和文档，这里不展开，直接启动的话用原始权重也没问题。
启动推理服务前，先确认显存和模型占用情况，可以用npu-smi info查看。然后通过MindIE提供的启动脚本，指定模型路径、设备编号、上下文长度这些参数：
mindie --model /data/models/qwen2.5-7b-instruct \ --port 8000 \ --device 0 \ --max-seq-len 4096参数含义说一下：--model指定权重目录；--port是服务监听端口，Dify之后会通过这个端口来访问；--device指定使用哪张NPU卡，多卡机器从0开始编号；--max-seq-len是最大序列长度，这个值决定了模型能处理多长的上下文，但也会直接影响显存占用，不是越大越好。
启动之后，可以用curl快速验证服务是否正常：
curl http://127.0.0.1:8000/v1/models如果返回一个包含模型名称的JSON列表，说明推理服务已经就绪。这一步成功，昇腾上的模型推理就算是跑通了。
4.2 在Dify后台配置自定义模型供应商
推理服务就绪后，接下来让Dify认识它。登录Dify管理后台，进入“设置”里的“模型供应商”页面，选择添加自定义模型，接口格式选OpenAI API兼容。这里需要填几个关键参数：
- Base URL：填推理服务的地址，例如
http://127.0.0.1:8000/v1 - API Key：填一个占位符就行，比如
EMPTY，因为MindIE服务本身不做鉴权 - 模型类型：选LLM
- 模型名称：填你在MindIE启动时指定的模型ID，比如
qwen2.5-7b-instruct - 上下文长度：根据你启动服务时设置的
--max-seq-len来填，建议保守一点，填比实际值稍小
配置完成后，先别急着用，点一下“测试”按钮，确认连通性。如果测试通过，说明模型对接成功。如果失败，最常见的原因是Base URL没拼对，检查一下是不是少了/v1后缀。
如果你后续还要用知识库功能，记得在同一个页面再添加一个Embedding模型。知识库做文档分段和向量化的时候，需要用到Embedding模型来把文本转成向量，没有它，上传文档后检索会直接报错。Embedding模型可以选一个小尺寸中文模型，比如bge-large-zh，同样按OpenAI兼容格式配置。
4.3 创建应用进行端到端验证
这些都配置好之后，最后做一个端到端验证。在Dify首页创建一个新的对话应用，在提示词编排页面把模型切换到刚才配置的模型，然后直接在调试框里输入一句话，比如“用一句话介绍你自己”，如果模型能正常回复，恭喜，整条链路已经通了。
我第一次跑通的时候，看到回复刷出来，还是有点感慨的。从浏览器里的Dify界面，到后端的API服务，再到昇腾NPU上的推理进程，整条链路中间跨越了好几个软件层，每一步都有坑，但打通之后的体验非常顺滑。后面你完全可以基于这个底座，去搭建自己的工作流、Agent、知识库问答应用。
5. 实际部署中踩过的坑和排查方法
5.1 高频问题速查表
这部分我把部署过程中遇到的高频问题和排查思路整理成了一张表，希望能帮你快速定位问题。很多问题不是配置复杂，而是出错的地方和表象离得太远，让人想不到。
| 现象 | 可能原因 | 排查和解决 |
|---|---|---|
| 前端页面能打开，但对话一直转圈无响应 | 推理服务没启动或Dify模型配置错误 | 先确认MindIE服务进程是否在跑，再用curl直接请求推理服务，看是否返回结果 |
| 模型返回401或认证失败 | API Key配置问题 | MindIE不校验key，填EMPTY之类的占位符即可，不要留空 |
| 请求推理服务时报连接拒绝 | Base URL或端口配置不对 | 检查Dify后台填的地址，确认端口和MindIE启动时一致，注意有没有遗漏/v1 |
| 模型加载到一半进程退出 | 显存不足，或权重文件路径错误 | 回头看npu-smi info显存占用，降低max-seq-len，或换成量化权重 |
| 数据库迁移失败 | PostgreSQL连接信息错误 | 检查.env里的数据库地址、端口、用户名和密码，确认PostgreSQL容器状态 |
| 环境变量找不到，运行时报动态库错误 | 启动时没有source昇腾环境变量 | 确认source /usr/local/Ascend/ascend-toolkit/set_env.sh，并检查启动脚本中的环境变量 |
| 多卡机器上模型始终跑在0号卡 | 未指定设备编号 | 在MindIE启动参数中通过--device指定目标卡号 |
5.2 几个不容易注意但很关键的经验
除了表里的这些问题，还有几个经验想单独说一说。第一个是版本一致性。昇腾这套软件栈，驱动、CANN、MindIE三个版本必须严格匹配。我见过一个比较典型的场景：用户CANN装的是8.0，但MindIE还是老版本，结果跑推理服务的时候各种莫名其妙的行为，有的接口报错，有的参数不生效。后来升级MindIE到对应版本，问题全消失了。所以拿到一个新环境，第一时间把三个版本号列出来，比对兼容矩阵，确认没问题再动手。
第二个经验是关于日志的。Dify的api服务日志、MindIE的推理日志，你都要知道在哪看。排查问题最怕的就是只在Dify界面看到一个大大的错误提示，无从下手。我第一次遇到对话无响应时，爬上服务器把journalctl翻了一通，又看了api服务的输出，才发现是MindIE服务的进程不知什么原因退了。从那以后，我把推理日志统一输出到固定文件，Dify后端也保持前台运行，出问题几秒钟就能定位。
第三个经验，源码部署不要手动硬扛进程管理。直接用systemd或者Supervisor把api服务和web服务管起来，设置好环境变量、启动命令、开机自启。这样即使某个进程异常退出，也能自动拉起，不用每次都手动跑到命令行里敲命令。尤其是生产环境，这个方法能省非常多的事。
最后说一个容易被忽略的小地方：知识库的Embedding模型尽量选小尺寸的，比如bge系列的中等版本。因为Embedding模型和对话模型共用NPU显存，主模型已经吃掉了一大半，如果再放一个大尺寸Embedding模型，很容易把显存挤爆。小尺寸Embedding模型在检索效果上差距不大，但对显存的压力会小很多，整体运行会更从容。
我个人实际操作下来的体会是，这套组合跑通之后，日常用来搭工作流、做企业知识库问答、甚至跑一些轻量级Agent应用，完全够用。整个过程虽然有不少坑，但只要把环境版本对上、部署顺序理清、模型接口接好，后面再用起来就非常顺手了。还有一个建议是，第一次部署最好在终端前台启动服务，看着日志一步一步过，不要急着做后台化。一旦整条链路验证通过，再考虑用systemd做成服务托管，这样既能保证可维护性，也能避免在出错时被一堆间接信息带偏方向。
本文还有配套的精品资源，点击获取
