Langchain-Chatchat 集成 MindIE + NPU 实战部署指南

在企业对数据主权和系统可控性要求日益提升的今天，一个真正“跑在自己机房里”的智能知识库系统，正从可选项变成刚需。我们不再满足于把文档上传到某个云端API换来几句回答——我们需要的是：文档不离内网、推理不碰公网、模型运行在自己的昇腾卡上。

这正是本文要解决的问题：如何用 华为 Atlas 300I Duo 推理卡 搭配 MindIE 推理引擎 和开源框架 Langchain-Chatchat，构建一套完全国产化、全链路离线、高性能的本地知识问答系统。

整个方案的核心思路是——让NPU干它最擅长的事，其余交给生态工具补足。大语言模型（LLM）推理由昇腾NPU通过 MindIE 加速执行；向量化部分则借助 Xinference 在 CPU 上稳定运行 BGE 等 embedding 模型；最后通过 Langchain-Chatchat 完成文档解析、检索增强与自然语言交互闭环。

这套组合拳不仅规避了对外部云服务的依赖，还能充分发挥国产硬件的算力优势。下面我们就从零开始，一步步把这个系统搭起来。

---

环境准备：打牢基础才能跑得更快

一切的前提是你手上有块能干活的昇腾卡。本次实测环境如下：

• 硬件平台：Atlas 300I Duo 推理卡（单卡或双卡均可）
• 服务器型号：Atlas 800 推理服务器（3000 型号）
• 操作系统：openEuler 22.03 LTS SP2，aarch64 架构
• 驱动栈：CANN 7.0.RC1 及以上版本
• 固件状态：已更新至最新版，确保 /dev/davinci* 设备节点正常挂载

⚠️ 提醒几点：

• 所有操作建议以 root 用户进行，避免权限问题干扰；
• 若未使用默认路径安装驱动，请务必调整 Docker 挂载参数；
• 单卡推荐部署 3B~7B 规模模型，其中 7B 模型建议启用双卡以避免显存溢出。

确认好这些之后，就可以进入下一步：拉起 MindIE 容器，加载 Qwen 大模型。

---

启动 MindIE：让 Qwen 在 NPU 上跑起来

MindIE 是华为推出的轻量级大模型推理引擎，专为昇腾芯片优化设计。它支持主流架构如 Llama、Qwen、ChatGLM，并提供标准 RESTful 接口和 OpenAI 兼容协议，非常适合集成进现有 AI 应用生态。

使用 Docker 快速部署

docker pull --platform=arm64 swr.cn-south-1.myhuaweicloud.com/ascendhub/mindie:2.1.RC2-300I-Duo-py311-openeuler24.03-lts

docker run -it --privileged \
  --ipc=host \
  --net=host \
  --name=MindIE-qwen3b \
  --shm-size=500g \
  --device=/dev/davinci0 \
  --device=/dev/davinci_manager \
  --device=/dev/hisi_hdc \
  --device=/dev/devmm_svm \
  -v /usr/local/Ascend/driver:/usr/local/Ascend/driver \
  -v /usr/local/Ascend/firmware:/usr/local/Ascend/firmware \
  -v /usr/local/sbin/npu-smi:/usr/local/sbin/npu-smi \
  -v /usr/local/sbin:/usr/local/sbin \
  -v /root/.cache/modelscope/hub/models/Qwen/Qwen2.5-3B-Instruct:/path-to-weights/Qwen/Qwen2.5-3B-Instruct \
  swr.cn-south-1.myhuaweicloud.com/ascendhub/mindie:2.1.RC2-300I-Duo-py311-openeuler24.03-lts \
  /bin/bash

几个关键点说明一下：

• --shm-size=500g：这是必须的。MindIE 会在共享内存中缓存 Attention KV 缓冲区，如果太小会导致性能骤降甚至崩溃；
• 所有 /dev/davinci* 设备都需要挂载进去，否则无法访问 NPU；
• 模型权重目录做了映射，这样宿主机下载一次后，多个容器可以复用，节省时间也节约空间。

进容器之后第一件事就是装 modelscope 并下载模型：

pip install modelscope -i https://pypi.tuna.tsinghua.edu.cn/simple
modelscope download --model Qwen/Qwen2.5-3B-Instruct

默认会保存到 /root/.cache/modelscope/hub/models/Qwen/Qwen2.5-3B-Instruct，记得在后续配置中正确指向这个路径。

---

配置与启动：别让一个小参数卡住你一整天

接下来是最容易踩坑的部分——配置文件。

权限设置不能少

先给模型目录加个权限，防止因读取失败导致加载异常：

chmod -R 750 /root/.cache/modelscope/hub/models/Qwen/Qwen2.5-3B-Instruct

修改模型 dtype

目前 MindIE 对 bfloat16 支持尚不完善，而 Qwen 默认保存为 bfloat16 格式。所以需要手动修改其 config.json 中的类型声明：

{
  "architectures": ["Qwen2ForCausalLM"],
  "torch_dtype": "float16"
}

改成 float16 后才能顺利加载。

主配置文件调整

编辑路径下的主配置文件：

/usr/local/Ascend/mindie/latest/mindie-service/conf/config.json

重点修改以下内容：

"ServerConfig": {
  "ipAddress": "0.0.0.0",
  "port": 8080,
  "allowAllZeroIpListening": true,
  "httpsEnabled": false
},
"BackendConfig": {
  "npuDeviceIds": [[0]],
  "ModelDeployConfig": {
    "maxSeqLen": 4096,
    "maxInputTokenLen": 2048,
    "maxIterTimes": 2048,
    "ModelConfig": [
      {
        "modelName": "qwen_3b_instruct",
        "modelWeightPath": "/path-to-weights/Qwen/Qwen2.5-3B-Instruct",
        "worldSize": 1,
        "trustRemoteCode": true
      }
    ]
  },
  "ScheduleConfig": {
    "maxBatchSize": 16,
    "maxPrefillBatchSize": 8,
    "maxIterTimes": 2048
  }
}

这里有几个工程经验值得分享：

• modelName 要记牢，后面 Langchain-Chatchat 会根据这个名字去调用模型；
• 单卡部署时 worldSize 必须设为 1，否则会报设备不可达；
• maxBatchSize 不宜过大，尤其是高并发场景下，容易触发 OOM；
• maxInputTokenLen 控制输入长度上限，超过可能直接崩掉服务。

全部改完后，就可以启动服务了。

启动方式选择

调试阶段建议前台启动，方便看日志：

./bin/mindieservice_daemon

上线后可以用守护进程方式运行：

nohup ./bin/mindieservice_daemon > /var/log/mindie.log 2>&1 &

验证是否成功？很简单，curl 一下就知道：

curl http://127.0.0.1:8080/v1/models

如果返回结果中包含 "id": "qwen_3b_instruct"，那就说明模型已经就绪，等待被召唤。

---

补齐另一半拼图：Xinference 部署 BGE Embedding 模型

虽然 MindIE 很强，但它目前主要聚焦于生成类大模型推理，在 embedding 模型支持方面还不够全面。因此，Langchain-Chatchat 所需的向量编码任务，我们交给另一个优秀的国产工具——Xinference 来完成。

Xinference 是一个分布式推理框架，支持多种 embedding、reranker、语音等模型，部署简单、接口统一，特别适合做模块化拆分。

安装与启动

新建一个 Conda 环境专门跑 Xinference：

conda create -n xinference python=3.11 -y
conda activate xinference

pip install xinference -i https://pypi.tuna.tsinghua.edu.cn/simple
pip install sentence-transformers -i https://pypi.tuna.tsinghua.edu.cn/simple

然后启动服务：

xinference-local --host 0.0.0.0 --port 9997 --log-level DEBUG

打开浏览器访问 http://<your-ip>:9997，你会看到一个简洁的 Web UI 界面。

部署 BGE-M3 模型

在页面上选择：

• Model Type: embedding
• Model Name: BAAI/bge-m3
• 自定义名称：比如 bge-m3
• Dimensions: 1024
• Max Length: 8192

点击 Launch，几分钟后模型就会加载完成。

测试一下接口是否可用：

curl http://localhost:9997/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bge-m3",
    "input": ["这是一个测试句子"]
  }'

只要返回 embedding 向量，说明 embedding 这条链路也通了。

---

整合所有组件：Langchain-Chatchat 上场

现在，LLM 有了（MindIE + Qwen），Embedding 有了（Xinference + BGE），接下来就是主角登场——Langchain-Chatchat。

它是目前中文社区中最成熟的本地知识库问答框架之一，支持多格式文档解析、多模型切换、可视化界面，且完全开源。

初始化项目环境

conda create -n chat python=3.11 -y
conda activate chat

cd /root/Langchain-Chatchat
pip install -e libs/chatchat-server/

设置根目录变量：

export CHATCHAT_ROOT=/root/Langchain-Chatchat/libs/chatchat-server
cd $CHATCHAT_ROOT

安装客户端依赖：

pip install xinference-client httpx==0.27.2 -i https://pypi.tuna.tsinghua.edu.cn/simple

初始化配置文件：

python chatchat/cli.py init

这一步会自动生成两个核心配置文件：

• configs/model_config.yaml
• configs/settings.yaml

---

关键配置：打通三端通信

1. 配置 LLM 模型（对接 MindIE）

编辑 model_config.yaml，添加如下项：

llm_models:
  - model_name: qwen_3b_instruct
    model_type: openai
    api_key: "none"
    base_url: "http://127.0.0.1:8080/v1"
    api_base_url: "http://127.0.0.1:8080/v1"
    prefix_keys: ["qwen"]

注意这里的 base_url 正是指向 MindIE 的 OpenAI 兼容接口。由于 MindIE 实现了 /v1/chat/completions 等标准路由，Langchain-Chatchat 只需当作普通 OpenAI 模型调用即可。

2. 配置 Embedding 模型（对接 Xinference）

继续在同一文件中添加：

embedding_models:
  - model_name: bge-m3
    model_path: ""
    device: cpu
    normalized: true
    is_online: true
    online_api_key: "none"
    base_url: "http://127.0.0.1:9997/v1"

因为模型运行在 Xinference 上，无需本地路径，只需指定 base_url 和模型名即可。

3. 设置默认模型（settings.yaml）

llm:
  default_llm: qwen_3b_instruct

embeddings:
  default_embedding: bge-m3

这样系统就知道该用哪个模型来处理请求了。

---

启动服务，见证闭环时刻

一切就绪后，重建知识库并启动服务：

# 清空旧向量库（首次运行必做）
python chatchat/cli.py kb --recreate-vs

# 启动所有服务（API + Web UI）
python chatchat/cli.py start -a

默认端口如下：

• API Server: 7861
• Web UI: 8501

访问 http://<your-ip>:8501，你应该能看到熟悉的图形界面。

试着上传一份 PDF 或 Word 文档，系统会自动完成切片、向量化、入库全过程。稍等片刻，就可以开始提问了。

当你看到答案准确出自你上传的文档内容时，整个链条才算真正跑通。

---

实战调优：不只是“能跑”，更要“跑得好”

部署成功只是第一步，真正的挑战在于稳定性与性能平衡。

性能优化建议清单

项目	推荐值	说明
maxBatchSize	8~16	提高吞吐但增加延迟，视业务需求权衡
maxInputTokenLen	≤2048	输入过长易引发 OOM
共享内存 (shm-size)	≥300G	特别是长文本对话场景，必须足够
Embedding 加速	若有 GPU，可用 CUDA 版本加速 BGE
日志级别	生产环境关闭 DEBUG 输出

常见故障排查指南

• ❌ Connection refused
  → 检查 MindIE 是否正在运行，防火墙是否放行 8080 端口

• ❌ Model not found
  → 核对 modelName 是否与 config.json 中一致

• ❌ npu-smi not found
  → 确认 /usr/local/sbin/npu-smi 已正确挂载进容器

• ❌ OOM 错误频繁出现
  → 减小 batch size 或降低 max token 长度

• ❌ 返回乱码或截断严重
  → 检查 maxIterTimes 是否限制过死

这类问题往往不是技术难点，而是细节疏忽所致。保持耐心，逐层验证，总能找到根源。

---

写在最后：为什么这套组合值得投入

当我们回顾整套架构时，会发现它具备几个非常突出的优势：

• 🔐 数据安全可控：所有处理均在本地完成，文档不出内网，彻底杜绝泄露风险；
• ⚙️ 硬件加速明显：相比纯 CPU 推理，NPU 可将响应延迟降低 60% 以上；
• 🔄 接口高度兼容：MindIE 支持 OpenAI 协议，使得迁移成本极低；
• 🧩 模块解耦灵活：LLM 与 Embedding 分开部署，便于独立升级与扩展；
• 📦 完全开源开放：Langchain-Chatchat 社区活跃，迭代迅速，适配能力强。

更重要的是，这套方案代表了一种趋势：国产算力+国产软件+开源生态 的深度融合正在成为现实。

未来你可以轻松拓展：

• 【进阶】双卡部署 Qwen-7B，显著提升回答质量；
• 【优化】尝试 ATB 引擎替代 MindIE，进一步压榨 NPU 性能；
• 【增强】接入 BGE Reranker 模型，提升检索排序精度；
• 【监控】集成 Prometheus + Grafana 实现 NPU 资源可视化监控。

每一步都不再是空中楼阁，而是基于已有基础设施的自然延伸。

---

💡 结语

当你的企业文档终于能在自家服务器上被“理解”和“回应”时，那种掌控感是任何 SaaS 服务都无法替代的。这不是炫技，而是一种实实在在的技术自主能力。

随着昇腾生态的持续成熟，MindIE、CANN、Xinference 等工具链日趋完善，搭建一个私有化大模型应用的门槛正在快速下降。Langchain-Chatchat 则像一座桥梁，把复杂的底层技术与直观的业务需求连接在一起。

希望这篇实战记录，能帮你少走几小时弯路，早点看到那个绿色的“回答成功”提示。

📢 更多更新请关注：Langchain-Chatchat GitHub
📞 技术交流群信息详见官网公告（微信/QQ）