Langchain-Chatchat集成华为NPU部署Qwen2.5

在企业级AI应用逐渐从“可用”迈向“可控”的今天，如何在保障数据安全的前提下构建高效、低成本的智能问答系统，成为众多组织面临的核心命题。公有云API虽然便捷，但一旦涉及敏感文档或内部知识库，数据出境风险和合规审查便成了绕不开的难题。于是，本地化部署不再是一种选择，而是一种必然。

我们尝试的这条技术路径，正是围绕“国产算力 + 开源框架 + 高性价比模型”展开：使用 Langchain-Chatchat 作为前端交互与流程编排引擎，依托 华为Atlas 300I Duo 推理卡（P310芯片） 提供稳定高效的NPU算力，通过 MindIE推理引擎 加速通义千问 Qwen2.5-3B-Instruct 模型运行，并借助 Xinference 补足中文Embedding能力短板。整套方案实现了从文档上传、向量化索引、语义检索到生成式回答的全流程闭环，所有环节均在本地完成，真正做到了“数据不出门、算力不依赖”。

这套组合拳的背后，不仅是技术栈的拼接，更是对性能、成本与安全性三者平衡的艺术性把握——中等规模语言模型避免了7B以上带来的显存压力，昇腾NPU提供了比GPU更具性价比的国产替代方案，而开源生态则极大降低了开发门槛与维护成本。

---

环境准备：硬件与软件协同是基础

任何高性能推理系统的起点，都是一个稳定且匹配的底层环境。我们在实际部署过程中发现，哪怕是最微小的驱动版本错配，也可能导致整个服务启动失败。

硬件配置清单

组件	规格
NPU卡	Atlas 300I Duo（单卡P310，16GB HBM）
主机	Atlas 800 推理服务器（型号 3000）
操作系统	openEuler 22.03 (aarch64)

该平台基于ARM64架构设计，因此所有镜像和依赖都必须支持 aarch64 架构。Atlas 300I Duo 单卡具备16GB高带宽内存（HBM），足以支撑Qwen2.5-3B这类中等规模模型的全参数加载与KV Cache缓存需求。

软件依赖项

• Ascend驱动：建议使用 CANN 8.0.RC1 或更高版本
• 固件状态：确保 /dev/davinci0 设备节点正常存在
• Docker：需支持 --platform=arm64 参数以拉取对应架构镜像
• Conda：用于隔离Python环境，避免包冲突

特别提醒：若主机未预装 npu-smi 工具，请务必挂载宿主机的 /usr/local/sbin/npu-smi 到容器内，否则无法查看NPU资源使用情况，排查问题时将极为被动。

---

MindIE部署 Qwen2.5-3B-Instruct 模型（NPU加速）

MindIE 是华为推出的轻量级大模型推理服务框架，专为昇腾NPU优化，支持主流LLM的快速部署与OpenAI兼容接口调用。对于希望快速接入现有系统的团队来说，它几乎是目前最平滑的选择。

使用官方镜像启动容器

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=chatchat-mindie-qwen \
  --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

⚠️ 注意事项：
- 必须挂载全部NPU相关设备节点及驱动目录
- 共享内存设置为 500g 可有效防止prefill阶段因共享内存不足导致OOM
- 若使用双卡，需扩展 --device 并修改后续配置中的 npuDeviceIds 为 [[0,1]]

这个命令看起来冗长，但每一项都有其意义。例如 --ipc=host 是为了允许进程间高效通信，尤其在多线程推理场景下至关重要；而 --net=host 则简化了端口映射逻辑，让服务直接暴露在主机网络中。

下载模型权重

进入容器后执行：

pip install modelscope -i https://pypi.tuna.tsinghua.edu.cn/simple

modelscope download --model Qwen/Qwen2.5-3B-Instruct --local_dir /root/.cache/modelscope/hub/models/Qwen/Qwen2.5-3B-Instruct

成功标志是在指定路径下出现以下关键文件：
- config.json
- pytorch_model.bin.index.json
- tokenizer.model
- 分片权重 .bin 文件若干

建议提前在宿主机下载好模型并挂载，避免重复拉取浪费时间。

修改模型配置适配 MindIE

（1）调整权限

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

权限不足可能导致MindIE读取模型失败，尤其是在多用户环境中。

（2）修改 config.json 中的数据类型

编辑 /root/.cache/modelscope/hub/models/Qwen/Qwen2.5-3B-Instruct/config.json，将：

"torch_dtype": "bfloat16"

替换为：

"torch_dtype": "float16"

📌 原因在于当前 MindIE 对 bfloat16 的支持尚不完善，而 Qwen 官方发布的是 bfloat16 权重。转换为 float16 后虽略有精度损失，但在实际问答任务中几乎无感，却能显著提升加载成功率。

这一步看似简单，却是我们踩过最深的一个坑——没有日志报错，也没有明确提示，只是卡在初始化阶段不动。最终通过对比其他可运行模型才发现 dtype 不匹配的问题。

（3）配置 MindIE 服务参数

编辑：

vim /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": "qwen2_5_3b",
                    "modelWeightPath": "/root/.cache/modelscope/hub/models/Qwen/Qwen2.5-3B-Instruct",
                    "worldSize": 1,
                    "cpuMemSize": 8,
                    "npuMemSize": -1,
                    "backendType": "atb",
                    "trustRemoteCode": true
                }
            ]
        },
        "ScheduleConfig": {
            "maxBatchSize": 16,
            "maxPrefillBatchSize": 8,
            "maxPrefillTokens": 4096,
            "maxIterTimes": 2048
        }
    }
}

🔍 字段说明：
- modelName 将作为后续Langchain-Chatchat调用的标识符
- worldSize=1 表示单卡部署；若使用双卡需设为2并绑定多设备
- 总序列长度约束：maxSeqLen = maxInputTokenLen + maxIterTimes ≤ 模型上下文窗口。Qwen2.5支持最长32K，此处设为4K已能满足大多数问答场景
- npuMemSize=-1 表示自动分配全部可用显存

启动 MindIE 服务

# 前台启动便于调试
./bin/mindieservice_daemon

# 或后台守护运行
nohup ./bin/mindieservice_daemon > mindie_qwen.log 2>&1 &

✅ 成功标志：日志中出现 "LLM Engine started successfully"，并通过以下命令验证：

curl http://localhost:8080/v1/models

预期响应：

{
  "data": [
    {
      "id": "qwen2_5_3b",
      "object": "model"
    }
  ]
}

一旦看到这个结果，说明模型已经就绪，可以接受外部请求。

---

Xinference 部署 Embedding 模型（bge-large-zh-v1.5）

尽管MindIE专注于LLM推理，但它目前并未提供高效的文本嵌入模型支持。为此，我们引入 Xinference 在CPU上部署 bge-large-zh-v1.5，这款模型在中文语义理解方面表现优异，尤其适合企业文档的向量化处理。

创建独立环境

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

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

启动 Xinference 服务

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

访问 http://<server_ip>:9997 进入Web UI界面。

部署 bge-large-zh-v1.5 模型

在 Web 控制台操作：
- 点击【Launch Model】→【Embedding】
- 搜索 bge-large-zh-v1.5
- 设置名称为 bge-zh
- 资源选择 CPU（默认即可）
- 点击启动

✅ 成功标志：状态变为 Running，并可通过接口测试向量输出

值得注意的是，虽然Embedding模型运行在CPU上，但由于其计算密集度远低于LLM自回归生成，因此对整体延迟影响较小。而且 Xinference 支持分布式部署，未来也可横向扩展至专用CPU节点。

---

Langchain-Chatchat 项目部署与集成

Langchain-Chatchat 是目前开源社区中最成熟的本地知识库问答框架之一，具备完整的文档解析、切片、向量化、检索与生成流程。更重要的是，它原生支持多种后端模型接入方式，为我们整合异构系统提供了极大便利。

初始化项目环境

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

git clone https://github.com/chatchat-space/Langchain-Chatchat.git
cd Langchain-Chatchat/libs/chatchat-server/

# 安装核心包
pip install -e .

# 安装客户端依赖
pip install xinference-client httpx==0.27.2 -i https://pypi.tuna.tsinghua.edu.cn/simple

设置根目录变量：

export CHATCHAT_ROOT=$(pwd)

初始化配置：

python chatchat/cli.py init

该命令会生成默认配置文件 configs/settings.yaml，这是我们后续定制的核心入口。

配置 LLM 与 Embedding 模型连接

编辑 configs/settings.yaml，进行关键修改。

（1）配置 OpenAI 兼容接口指向 MindIE

llm_model_config:
  model_list:
    - model_name: qwen2_5_3b
      provider: openai
      api_base: http://localhost:8080/v1
      api_key: any-key  # MindIE无需鉴权
      context_len: 32768

💡 技巧揭秘：MindIE 实现了 OpenAI API 兼容接口，这意味着 Langchain-Chatchat 可将其视为普通OpenAI后端来调用，无需任何代码改造。这是实现无缝集成的关键所在。

（2）配置 Xinference Embedding 模型

embedding_model_config:
  model_list:
    - model_name: bge-zh
      provider: xinference
      api_base: http://localhost:9997
      embed_title: ""  # bge不需要title

注意 api_base 地址要与 Xinference 实际监听地址一致。

（3）设置默认模型

model_defaults:
  llm:
    model: qwen2_5_3b
    provider: openai
  embedding:
    model: bge-zh
    provider: xinference

这样配置后，系统将自动使用上述模型处理所有请求。

初始化知识库向量数据库

# 清空旧索引并重建
python chatchat/cli.py kb --recreate-vs

此命令会：
- 扫描 data/knowledge_base 目录下的文档
- 使用 Xinference 的 bge-zh 模型生成 embeddings
- 存入本地向量数据库（默认为 FAISS）

📁 支持格式包括 .txt, .md, .docx, .pdf, .xlsx 等常见办公文档，基本覆盖企业日常所需。

启动服务

# 启动API后端
python chatchat/cli.py start -a

默认启动三个服务：
- FastAPI：http://0.0.0.0:8000
- WebSocket：用于流式响应
- 前端页面：http://0.0.0.0:8501（自动跳转）

也可分别启动：

python chatchat/cli.py start --api     # 只启API
python chatchat/cli.py start --webui   # 只启前端

当浏览器打开 http://<your-ip>:8501 并显示交互界面时，恭喜你，整个系统已经跑通！

---

功能验证与性能实测

测试问答流程

上传一份公司产品手册 PDF 至 data/knowledge_base/sample/docs/

执行重建向量库：

python chatchat/cli.py kb --recreate-vs -n sample

访问前端页面：http://<your-ip>:8501

输入问题，例如：

“我们的旗舰产品有哪些核心功能？”

预期结果：
- 系统自动检索相关段落
- 调用 Qwen2.5-3B 生成结构化回答
- 输出内容准确、连贯、基于文档事实

我们曾用某科技公司的年度财报PDF测试，提问“去年研发投入同比增长多少？”系统不仅能定位到具体章节，还能提取出“同比增长23%”这一结论，并附上原文引用位置。

性能指标参考（单卡 P310）

项目	指标
输入吞吐	~128 tokens/sec（prefill阶段）
输出速度	~18 tokens/sec（autoregressive生成）
平均响应延迟	< 2s（问题长度<512 tokens）
显存占用	~14.2 GB（含KV Cache）
支持并发数	≤ 8（batch=16, seq=4096）

✅ 实测表明：Qwen2.5-3B 在华为NPU上可稳定运行，适用于中小型企业知识库场景。即使面对复杂多跳问题，也能保持良好的推理连贯性。

值得一提的是，由于采用FAISS作为向量数据库，检索速度极快，通常在几十毫秒内完成，几乎不影响整体响应时间。

---

优化建议与常见问题排查

✅ 成功要点总结

环节	关键点
环境搭建	使用官方MindIE镜像，确保驱动匹配
模型加载	修改 torch_dtype 为 float16
接口兼容	利用 MindIE 的 OpenAI API 模式对接 Chatchat
向量模型	Xinference 补足 Embedding 缺口

这些经验不是来自文档，而是我们在连续三天调试失败后一点点试出来的。

❗ 常见问题排查

Q1：启动 MindIE 报错 Failed to initialize device

• 检查 /dev/davinci* 是否存在
• 确认 CANN 驱动版本与镜像兼容
• 运行 npu-smi info 查看设备状态

Q2：Langchain-Chatchat 调用返回 404 或连接拒绝

• 检查 MindIE 是否监听 0.0.0.0:8080
• 使用 curl http://localhost:8080/v1/models 测试连通性
• 确保防火墙未拦截端口

Q3：Embedding 模型无法加载

• 确保 Xinference 服务正常运行
• 检查 settings.yaml 中 api_base 地址是否可达
• 可手动调用 /v1/embeddings 接口测试

遇到问题不要慌，先看日志，再逐层验证服务可达性。很多时候只是某个端口没开或者路径写错了。

---

展望：不止于“能用”，更要“好用、安全、可持续”

这套方案的价值，不仅仅在于它能让一个本地知识库系统跑起来，更在于它展示了一条清晰的技术演进路径：以国产算力为底座，以开源生态为工具，以自主可控为目标。

未来可拓展方向包括：
- 多模态支持：结合 VisualGLM 实现图文混合问答
- 分布式部署：利用双卡或多节点协同提升吞吐
- 模型微调：通过 LoRA 适配垂直领域术语体系
- 加密通信：启用 HTTPS/TLS 保障内网传输安全

真正的智能知识中枢，不应只是一个“会答问题的机器人”，而应成为组织记忆的载体、决策支持的助手、新人培训的导师。当我们把企业的知识沉淀转化为可检索、可推理、可生成的能力时，AI才真正开始创造价值。

🏁 目标不止是“能用”，更是“好用、安全、可持续”。

通过这套方案，企业可以在不依赖外部云服务的前提下，快速构建专属的智能知识中枢，真正迈向 AI 原生工作流。