简介：面向在国产人工智能硬件上落地大模型应用平台的开发者，这个部署源码包聚焦华为昇腾推理服务器及配套加速卡环境，提供Dify 0.8.2可运行版本。资源完整覆盖大模型推理引擎、向量嵌入与重排序模块的部署和接口测试，也包含大语言模型、向量嵌入、重排序三类模型的接入配置，并用通义千问2.5-7B模型在双卡环境下做了实际运行与显存占用验证，可帮助读者快速复现国产化大模型应用平台的搭建过程。包内共两个文件，分别对应超文本说明文档与在线开发环境文件，整体仅4KB。超文本文件可作为操作指引，在线开发环境文件便于导入或对照配置，两者配合可明显缩短环境搭建与问题排查时间。该资源已有86人学习下载，适合正在选型或试水昇腾平台、希望借助Dify低代码方式搭建大模型应用的工程师参考。
1. 项目背景与整体思路拆解
1.1 为什么是“昇腾 + Dify”这套组合
这段时间 AI 应用落地的话题热度一直很高，像 Dify 这类开源 LLM 应用开发平台，把模型接入、知识库管理、工作流编排、Agent 搭建这些能力都揉到了一起，确实解决了不少团队从模型到应用之间的“最后一公里”问题。Dify 本身不依赖特定硬件，官方文档也提供了基于 Docker Compose 的部署方式，社区里有大量基于 x86 + NVIDIA GPU 的教程，但在国产化硬件上跑通的案例相对少很多，尤其是昇腾平台。
我之前在昇腾 310P 和 910B 上都做过模型推理的适配，这次要把 Dify 完整部署起来，核心要解决的就是两件事：第一，让 Dify 的服务端能正常跑起来；第二，把昇腾 NPU 上的推理服务接入 Dify，让应用真正调用到国产算力。这套方案跑通之后，上下游团队直接复用，省掉了很多重复踩坑的时间。
1.2 部署方案选型与硬件环境说明
先交代一下我这次的环境。机器是 Atlas 800 训练服务器，带昇腾 910B，操作系统是 openEuler 22.03 LTS，Docker 版本 24.0.7，Dify 社区版源码直接拉的 GitHub 上最新的 release 分支。昇腾的 CANN 工具包版本用的 8.0.RC1，配套的驱动和固件也是同步更新的。
关于方案，我最终选择了“Dify 官方 Docker Compose + 外部推理服务”的组合。为什么不直接在 Dify 容器里装昇腾的推理栈？因为 Dify 的容器镜像本身只负责应用层逻辑，硬塞推理引擎进去会让镜像体积失控，而且昇腾的 CANN、MindIE 这些底层库跟容器内系统库的版本兼容性非常敏感，隔离在外面更容易排查问题。推理服务这块我用了 MindIE 作为后端，因为它对昇腾 NPU 的算子是原生支持的，图模式推理的吞吐表现比 vLLM-Ascend 更稳定，尤其在并发请求上来以后。
架构上分了三个部分：Dify 应用层（api、worker、web 三个主要服务）、依赖层（PostgreSQL、Redis、Weaviate 或 Qdrant）、推理服务层（MindIE 独立容器对外暴露 OpenAI 兼容接口）。这样拆分的好处是每一层都可以独立升级、独立排查，不会互相拖累。
2. 核心细节解析与部署前置准备
2.1 昇腾驱动、固件与 CANN 工具链的版本匹配
昇腾平台和 NVIDIA GPU 最大的不同在于，它不只是装一个驱动就行，而是有一套完整的软件栈：固件、驱动、CANN 工具包，再加上具体的推理引擎。版本之间必须严格匹配，我在 910B 上就遇到过驱动和固件版本不匹配导致 NPU 状态异常的情况，npu-smi info直接报错，排查起来非常头疼。
建议按照官方文档的兼容性列表来选版本组合。我这次用的是驱动 24.1.rc1、固件配套版本、CANN 8.0.RC1。安装顺序也有讲究：先装固件，再装驱动，最后安装 CANN。每一步完成后都要用npu-smi info确认 NPU 状态是正常的，健康状态显示 OK 再继续下一步。
关键检查命令：
# 查看 NPU 设备状态 npu-smi info # 确认 CANN 环境变量 python3 -c "import torch; import torch_npu; print(torch_npu.__version__)"2.2 MindIE 推理服务的独立容器化
MindIE 是昇腾上做大模型推理的核心引擎，它支持 RAG 场景里常见的 Qwen、Llama 系列模型，也对 OpenAI 兼容接口做了支持。我在部署的时候没有直接用宿主机的 MindIE 环境，而是用官方镜像单独起了一个推理容器，这样 Dify 的依赖不会污染推理环境，后续换 MindIE 版本也方便。
拉取 MindIE 镜像并启动容器的参考操作：
docker pull mindie-910b:8.0.RC1 docker run -d \ --name mindie-service \ --device=/dev/davinci0 \ --device=/dev/davinci_manager \ --device=/dev/hisi_hdc \ -v /usr/local/Ascend:/usr/local/Ascend \ -v /data/models:/models \ --network dify-network \ -p 8000:8000 \ mindie-910b:8.0.RC1这里有个容易忽略的点：容器网络一定要和 Dify 的 compose 网络打通，我用的是外部网络dify-network，否则容器之间没法通过服务名互相访问。另一个就是/dev/davinci_manager和/dev/hisi_hdc这两个设备节点，很多人只映射了davinci0，会导致推理容器启动后找不到设备。
2.3 模型权重准备与目录规划
模型我选了 Qwen2.5-7B-Instruct，原因是昇腾生态对 Qwen 系列的适配最成熟，算子兼容性最好。权重文件需要转换成 MindIE 支持的格式，直接用 Hugging Face 的原始权重也可以，但建议按官方提供的转换脚本转成 MindIE 的推理格式，性能会有明显提升。
目录规划上是这样的：
/data/models/ └── qwen2.5-7b-instruct/ ├── config.json ├── generation_config.json ├── model.safetensors.index.json ├── model-00001-of-00004.safetensors └── tokenizer.json权重放在宿主机/data/models下，通过-v挂载进 MindIE 容器，这样后续更新模型不用重建容器，直接替换文件再重启服务就行。
3. 实操过程与核心环节实现
3.1 获取 Dify 源码并准备容器编排
我直接拉取的 Dify 社区版源码，版本用的是 1.6.x 的 release 分支。这个版本对多租户的支持已经比较完善，而且 API 的稳定性在社区里口碑不错。拉下来之后进到docker/目录，里面有完整的docker-compose.yaml和.env.example文件，改一下环境变量就能用。
git clone --branch 1.6.1 https://github.com/langgenius/dify.git cd dify/docker cp .env.example .env这里需要调整的核心配置项包括：
# 密钥，用 openssl rand -base64 42 生成 SECRET_KEY=your_secret_key # 向量数据库选择，我用的是 weaviate VECTOR_STORE=weaviate # 外部模型供应商的 API 地址，后面讲 MODEL_API_KEY=empty.env里还有一个容易被忽视的配置，就是EXPOSE_NGINX_PORT。默认是 80，如果宿主机端口已经被占用，改成 8080 之类的高位端口会省去很多麻烦。
3.2 启动核心依赖并调整 compose 文件
直接执行docker compose up -d之前，我建议先把docker-compose.yaml里api和worker两个服务的环境变量过一遍。重点看MODEL_PROVIDER_ENDPOINT或者是自定义模型供应商相关配置，如果有http://host.docker.internal这种写法，在 Linux 上是不生效的，需要改成实际的服务地址。
我最后选的方式是避开 Dify 内置的模型供应商机制，直接在 Dify 管理后台的“设置 -> 模型供应商”里添加一个自定义的 OpenAI-API-compatible 供应商，把 Base URL 指向 MindIE 服务容器的地址http://mindie-service:8000/v1，这样 compose 文件几乎不用大改，风险最小。
依赖服务起来以后，先确认数据库和 Redis 都健康：
docker compose ps docker compose logs postgres | tail -20这一步很关键，因为 Dify 首次启动会做数据库迁移，PostgreSQL 没有就绪会导致迁移失败，后面再想修复可比重新初始化麻烦多了。
3.3 初始化 Dify 数据库并创建管理员账号
Dify 的 API 服务启动时会自动执行数据库迁移，但我建议手动执行一次，方便及时看到报错信息：
docker compose exec api flask db upgrade迁移完成后，执行初始化命令创建管理员账号：
docker compose exec api flask create-admin --email admin@example.com --username admin --password your_password创建完管理员之后，访问http://服务器IP:80/install会进入安装引导页，这里再配置一次管理员密码也可以，不过既然命令行已经建了，直接跳过引导页用命令行配置的账号登录就行。
3.4 MindIE 推理服务配置与 Dify 模型接入
MindIE 的配置文件是config.json，里面定义了模型路径、推理参数、张量并行度这些。910B 单卡 64G 显存跑 7B 模型非常轻松，我配置的张量并行度是 1，max-seq-len设置为 8192，max-batch-size设置为 8。
实际启动 MindIE 服务的命令类似：
docker exec mindie-service bash -c "cd /workspace && mindie_service --config config.json"服务起来之后，先验证推理接口是否正常。MindIE 兼容 OpenAI 的/v1/chat/completions接口，用 curl 测试一下：
curl http://localhost:8000/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "qwen2.5-7b-instruct", "messages": [{"role": "user", "content": "你好"}], "max_tokens": 256 }'能正常返回内容之后，到 Dify 后台添加模型供应商。选择 OpenAI-API-compatible 类型，把 API Endpoint URL 填成http://mindie-service:8000/v1，API Key 随便填一个占位符即可（MindIE 默认不校验 Key），模型名称填qwen2.5-7b-instruct，保存之后在模型列表里就能看到这个模型了。
3.5 创建应用并验证完整链路
模型接入成功后，在 Dify 里创建一个对话型应用，选择刚才配置的模型作为默认推理模型，然后在调试界面输入一句话测试。这里我强烈建议先用最简单的“你好”做连通性验证，因为一旦不通过，问题可能出在 Dify 配置、网络、MindIE 参数、模型文件等多个环节，从简单场景开始排查效率最高。
如果基础对话通了，再逐步测试知识库上传、工作流编排这些高级功能。知识库做文档解析的时候，Dify 的 embedding 模型也需要配置，我这边是找了一个走 CPU 的 embedding 服务挂在同网络下，或者直接用本地跑一个轻量 embedding 模型，这块不难，按需选型即可。
4. 常见问题与排查技巧实录
4.1 MindIE 容器报错“Device 0 is busy”
这个是高概率问题。原因通常是设备映射不全或者驱动不匹配。用npu-smi info看设备状态，如果显示 busy 而宿主机上并没有其他进程占用，那大概率是容器内的 CANN 版本和宿主机驱动版本不兼容。解决方案是严格按版本匹配关系重装驱动或换 MindIE 镜像。
另一个容易忽略的点是：宿主机上如果跑着其他用到/dev/davinci0的进程，比如监控脚本或者测试程序，也会导致容器内申请不到设备。排查时可以暂时停掉这些进程再重启容器验证。
4.2 Dify 页面能打开但模型调用一直转圈
这种问题先别急着动 Dify，直接回到推理服务这一层验证。在 MindIE 容器所在宿主机上执行 curl 测试，如果接口正常，再进到 Dify 的 api 容器里执行同样的请求，看是否能通：
docker compose exec api curl http://mindie-service:8000/v1/models如果 api 容器里通不了，检查自定义模型供应商的 Base URL 填写是否正确，以及网络是否在同一 Docker 网络下。实测遇到最多的是把 URL 写成了localhost:8000，这在容器内实际指向的是 api 容器自身，永远连不上。一定要写服务名或者宿主机 IP。
4.3 知识库上传文档后命中率极低
这个通常不是部署问题，而是 embedding 模型的问题。默认如果没配置 embedding 模型，Dify 编排知识库时会报错或者走一个非常基础的兜底方案，检索效果自然差。我建议在模型供应商里至少配一个 embedding 服务，不管是昇腾上跑还是 CPU 的，都能明显改善检索质量。另外就是分段长度设置，默认 500 字对很多技术文档来说偏大，切成 200-300 字命中率会好不少。
4.4 推理速度忽快忽慢
昇腾平台的推理性能跟 MindIE 的配置关系很大。如果并发场景下速度波动明显，检查max-batch-size是否设置过小，以及prefill和decode的并行配置是否合理。910B 跑 7B 模型，max-batch-size建议至少 8，如果显存足够的话 16 也可以。另外，确保 MindIE 开了 prefix cache，这样多轮对话场景下性能会稳定很多。
4.5 常见问题速查表
| 现象 | 可能原因 | 排查/解决动作 |
|---|---|---|
npu-smi info报错 | 驱动/固件不匹配 | 按版本表重装 |
| MindIE 容器无法启动 | 设备节点未全部映射 | 补齐 davinci_manager、hisi_hdc 映射 |
| Dify 后台模型列表为空 | 模型供应商未正确保存 | 检查 Base URL 与模型名称 |
| 模型调用超时 | MindIE 显存不足或配置偏低 | 调大 max-batch-size，降低 max-seq-len |
| 知识库检索为空 | embedding 未配置 | 添加 embedding 模型并重新分段 |
5. 整个部署的体验与经验小结
整套方案从开始准备到完全跑通，我大概花了两天时间。其中第一天主要在等模型文件下载和踩 MindIE 配置的坑，真正 Dify 本身的部署反而很顺利，说明官方在应用层做得很成熟。
如果现在让我重新做一次，我会先在搭好 MindIE 之后，第一时间做一轮完整的并发测试，再接入 Dify。因为很多问题表面上像是 Dify 调用失败，本质上是推理服务本身扛不住压力。先把底座打稳，上层再接应用，排错成本低很多。
最后分享一个实用的小技巧：Dify 的日志在docker compose logs -f api，MindIE 的推理日志在容器内的/workspace/log目录。排查问题的时候两边的日志同时开两个终端一起看，上下文对齐了，大部分问题都能快速定位。这套环境现在还在稳定运行，后续打算再把 embedding 模型也切换成昇腾推理，进一步减少对 CPU 算力的依赖。
本文还有配套的精品资源，点击获取
