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

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

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

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

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

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

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

硬件配置清单

该平台基于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）

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

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

优化建议与常见问题排查

✅ 成功要点总结

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

❗ 常见问题排查

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 原生工作流。