MindNLP

无需修改代码，即可在 MindSpore 上运行 HuggingFace 模型

在 Ascend NPU、GPU 和 CPU 上使用 20 多万个 HuggingFace 模型的最简单方法

快速入门 • 功能特性 • 安装 • 为什么选择 MindNLP • 文档

---

🎯 什么是 MindNLP？

MindNLP 桥接了 HuggingFace 海量模型生态与 MindSpore 硬件加速之间的鸿沟。只需 import mindnlp，你就可以在 Ascend NPU、NVIDIA GPU 或 CPU 上运行任意 HuggingFace 模型——无需任何代码改动。

import mindnlp  # 就这么简单！HuggingFace 现在可以在 MindSpore 上运行
from transformers import pipeline

pipe = pipeline("text-generation", model="Qwen/Qwen2-0.5B")
print(pipe("你好，我是")[0]["generated_text"])

⚡ 快速入门

使用大语言模型进行文本生成

import mindspore
import mindnlp
from transformers import pipeline

pipe = pipeline(
    "text-generation",
    model="Qwen/Qwen3-8B",
    ms_dtype=mindspore.bfloat16,
    device_map="auto"
)

messages = [{"role": "user", "content": "写一首关于编程的俳句"}]
print(pipe(messages, max_new_tokens=100)[0]["generated_text"][-1]["content"])

使用 Stable Diffusion 进行图像生成

import mindspore
import mindnlp
from diffusers import DiffusionPipeline

pipe = DiffusionPipeline.from_pretrained(
    "stable-diffusion-v1-5/stable-diffusion-v1-5",
    ms_dtype=mindspore.float16
)
image = pipe("山间日落，油画风格").images[0]
image.save("sunset.png")

使用 BERT 进行文本分类

import mindnlp
from transformers import AutoTokenizer、AutoModelForSequenceClassification

tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")
model = AutoModelForSequenceClassification.from_pretrained("bert-base-uncased")

inputs = tokenizer("MindNLP 太棒了！", return_tensors="pt")
outputs = model(**inputs)

✨ 功能特性

🤗 完全兼容 HuggingFace 来自 HuggingFace Hub 的 20 多万个模型 Transformers —— 所有模型架构 Diffusers —— Stable Diffusion、SDXL、ControlNet 无需修改代码 —— 只需 import mindnlp	🚀 硬件加速 Ascend NPU —— 完整支持华为 AI 芯片 NVIDIA GPU —— CUDA 加速 CPU —— 优化的 CPU 执行 多设备 —— 自动设备分配
🔧 高级能力 混合精度 —— FP16/BF16 训练与推理 量化 —— INT8/INT4 结合 BitsAndBytes 分布式 —— 多 GPU/NPU 训练 PEFT/LoRA —— 参数高效的微调	📦 易于集成 通过 mindtorch 提供与 PyTorch 兼容的 API 支持 Safetensors 以实现快速加载 模型库镜像加速下载 全面的文档支持

🧐 Mindtorch NPU 调试

Mindtorch NPU 操作默认为异步执行。如果需要等待结果完成，可以使用 torch.npu.synchronize()。调试时，可设置 ACL_LAUNCH_BLOCKING=1 强制每个操作同步执行。

📦 安装

# 推荐从 PyPI 安装
pip install mindnlp

# 从源码安装（获取最新功能）
pip install git+https://github.com/mindspore-lab/mindnlp.git

📋 版本兼容性

MindNLP	MindSpore	Python
0.6.x	≥2.7.1	3.10-3.11
0.5.x	2.5.0-2.7.0	3.10-3.11
0.4.x	2.2.x-2.5.0	3.9-3.11

💡 为什么选择 MindNLP？

特性	MindNLP	PyTorch + HF	TensorFlow + HF
HuggingFace 模型	✅ 20 多万个	✅ 20 多万个	⚠️ 有限
Ascend NPU 支持	✅ 原生支持	❌	❌
无需代码迁移	✅	-	❌
统一的 API	✅	✅	❌
中文模型支持	✅ 极佳	✅ 良好	⚠️ 有限

🏆 主要优势

1. 即时迁移：现有 HuggingFace 代码可立即运行
2. Ascend 优化：原生支持华为 NPU 硬件
3. 生产就绪：经过企业级部署验证
4. 活跃社区：定期更新且响应迅速的支持

🗺️ 支持的模型

MindNLP 支持来自 HuggingFace Transformers 和 Diffusers 的 所有模型。以下是一些热门模型：

类别	模型
大语言模型	Qwen、Llama、ChatGLM、Mistral、Phi、Gemma、BLOOM、Falcon
视觉模型	ViT、CLIP、Swin、ConvNeXt、SAM、BLIP
音频模型	Whisper、Wav2Vec2、HuBERT、MusicGen
扩散模型	Stable Diffusion、SDXL、ControlNet
多模态模型	LLaVA、Qwen-VL、ALIGN

👉 查看所有支持的模型

📚 资源

• 📖 文档
• 🚀 快速入门指南
• 📝 教程
• 💬 GitHub 讨论区
• 🐛 问题追踪器

🤝 贡献

我们欢迎各位贡献！详情请参阅我们的 贡献指南。

# 克隆并安装以进行开发
git clone https://github.com/mindspore-lab/mindnlp.git
cd mindnlp
pip install -e ".[dev]"

👥 社区

加入 MindSpore NLP SIG（特别兴趣小组），参与讨论、活动和协作：

⭐ 星标历史

如果您觉得 MindNLP 很有用，请考虑给它点个赞 ⭐ —— 这将帮助项目不断成长！

📄 许可证

MindNLP 采用 Apache 2.0 许可证 发布。

📖 引用

@misc{mindnlp2022,
    title={MindNLP：基于 MindSpore 的易用且高性能自然语言处理与大模型框架},
    author={MindNLP 贡献者},
    howpublished={\url{https://github.com/mindspore-lab/mindnlp}},
    year={2022}
}

---

由 MindSpore Lab 团队用心打造 ❤️

MindNLP 快速上手指南

MindNLP 是一个旨在打通 HuggingFace 模型生态与 MindSpore 硬件加速能力的桥梁。只需一行代码 import mindnlp，即可在昇腾 NPU、NVIDIA GPU或CPU上运行超过 20 万个 HuggingFace 模型，无需修改任何原有代码。

1. 环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux (推荐 Ubuntu 20.04/22.04)
• Python 版本: 3.10 - 3.11 (根据 MindNLP 版本不同略有差异)
• 后端框架:
  • MindSpore: 建议版本 ≥ 2.7.1 (对应 MindNLP 0.6.x)
  • 硬件驱动:
    • 若使用昇腾 NPU：需安装对应的 CANN 包和 Ascend 驱动。
    • 若使用NVIDIA GPU：需安装 CUDA 和 cuDNN。
• 前置依赖: 建议先安装好基础版的 mindspore。

提示：MindNLP 对国产大模型（如 Qwen, ChatGLM 等）及昇腾硬件有极佳的原生支持。

2. 安装步骤

推荐使用 PyPI 进行安装，也可从源码安装以获取最新特性。

方式一：通过 PyPI 安装（推荐）

pip install mindnlp

方式二：从源码安装（获取最新功能）

pip install git+https://github.com/mindspore-lab/mindnlp.git

国内加速方案（可选）

如果您在国内网络环境下安装较慢，可以使用国内镜像源加速：

# 使用清华源安装
pip install mindnlp -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 基本使用

MindNLP 的核心优势是零代码迁移。您只需要在现有的 HuggingFace 代码最上方添加 import mindnlp，后续代码完全保持不变，底层会自动切换至 MindSpore 引擎并适配当前硬件。

示例 1：大语言模型文本生成 (LLM)

以下示例展示如何运行 Qwen 模型进行对话生成，自动利用可用的 NPU 或 GPU 加速：

import mindspore
import mindnlp
from transformers import pipeline

# 初始化流水线，device_map="auto" 会自动选择最佳设备
pipe = pipeline(
    "text-generation",
    model="Qwen/Qwen3-8B",
    ms_dtype=mindspore.bfloat16,
    device_map="auto"
)

messages = [{"role": "user", "content": "Write a haiku about coding"}]
result = pipe(messages, max_new_tokens=100)[0]["generated_text"][-1]["content"]
print(result)

示例 2：图像生成 (Stable Diffusion)

直接运行 Diffusers 模型生成图片：

import mindspore
import mindnlp
from diffusers import DiffusionPipeline

# 加载模型，指定精度为 float16 以节省显存并加速
pipe = DiffusionPipeline.from_pretrained(
    "stable-diffusion-v1-5/stable-diffusion-v1-5",
    ms_dtype=mindspore.float16
)

# 生成图像
image = pipe("A sunset over mountains, oil painting style").images[0]
image.save("sunset.png")

示例 3：传统 NLP 任务 (BERT 分类)

适用于传统的 Transformer 模型推理：

import mindnlp
from transformers import AutoTokenizer, AutoModelForSequenceClassification

# 加载分词器和模型
tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")
model = AutoModelForSequenceClassification.from_pretrained("bert-base-uncased")

# 推理过程
inputs = tokenizer("MindNLP is awesome!", return_tensors="pt")
outputs = model(**inputs)
print(outputs)

---

下一步：更多高级用法（如量化、分布式训练、LoRA 微调）请参考 官方文档。