MobileLLM-125M (昇腾 NPU 适配版)

MobileLLM-125M 是 Facebook/Meta 推出的轻量级大语言模型，参数量 125M，基于优化的标准 Transformer 架构设计，适用于资源受限场景下的文本生成任务。

本仓库提供该模型在 华为昇腾 NPU 上使用 vLLM-Ascend 的适配部署方案及功能验证。

模型信息

快速开始

1. 下载模型权重

# 从 HuggingFace 下载原始权重（约 0.23 GB）
git lfs install
git clone https://huggingface.co/facebook/MobileLLM-125M

# 或使用 HuggingFace CLI
pip install huggingface-hub
huggingface-cli download facebook/MobileLLM-125M --local-dir ./MobileLLM-125M

注意：本仓库不包含模型权重，需自行从 HuggingFace 下载。

2. 环境要求

3. 安装 vLLM-Ascend

# 克隆 vLLM-Ascend
git clone https://github.com/vllm-project/vllm-ascend.git
cd vllm-ascend

# 根据 MobileLLM 架构进行适配（参见下文昇腾适配说明）
# ...

# 安装
pip install -e .

4. 运行推理

from vllm import LLM, SamplingParams

llm = LLM(
    model='./MobileLLM-125M',
    trust_remote_code=True,
    max_model_len=512,
    tokenizer_mode='slow',  # 必须：MobileLLM 仅有 slow tokenizer
    dtype='float16',
)

output = llm.generate('Hello, my name is')
print(output[0].outputs[0].text)

功能验证

📐 精度说明（重要）

本仓库已同时提供 CPU 贪心解码基线 和 NPU 采样解码输出，用于精度对比。

⚠️ 重要前提：下表中的 CPU 与 NPU 使用不同的解码策略

CPU 基线使用 贪心解码 (temperature=0)，输出完全确定、可复现。 NPU 输出使用 随机采样 (temperature=0.7, top_p=0.9)，每次运行结果不同。

因此 表中 CPU 与 NPU 的文本差异是解码策略不同导致的，而非 NPU 精度问题。 如需有意义的精度对比，请使用 get_baseline.py --greedy 在您的 GPU/CPU 上生成基线后，再与同样使用贪心解码运行的 NPU 输出进行对比。

CPU 贪心解码基线 (temperature=0, 确定性输出)

使用原始 Transformers 在 CPU 上运行 贪心解码 (temperature=0) 的结果：

NPU 采样输出 (temperature=0.7, top_p=0.9, 供功能验证)

CPU 首 Token Logits（Top-10，供数值精度对比）

以下数据记录了 CPU 上输入 "Hello, my name is" 后首个预测 token 的概率分布 Top-10。NPU 端可在 vLLM 中设置 logprobs=10 获取类似数据进行端到端精度验证：

完整 logits 数据见 cpu_baseline_logits.json。

🔧 如何自行验证精度

本仓库提供完整的基线生成脚本和 NPU 参考输出，您可以在自己的 GPU/CPU 机器上运行：

步骤 1：在您的 GPU/CPU 机器上生成基线输出

# 安装依赖
pip install transformers torch

# 运行基线生成脚本（会自动下载原始 MobileLLM-125M 权重）
python3 get_baseline.py

该脚本将使用与 NPU 测试 完全相同的 Prompt、max_tokens、temperature、top_p 在 GPU/CPU 上运行推理，输出参考结果。

步骤 2：对比 NPU 参考输出

将 GPU/CPU 基线输出与本仓库 validation_results.json 中的 NPU 输出进行对比：

建议精度对比方法：

• 词级别 Jaccard 相似度：衡量生成文本的词汇重合度
• 贪心解码对比：将 temperature 设为 0（贪心解码）后对比 NPU 与 GPU/CPU 的确定输出
• logits 对比：比较首 token 的 logits 分布（余弦相似度、欧氏距离）

在华为昇腾 NPU 上使用 vLLM-Ascend 对 MobileLLM-125M 进行推理测试，性能结果如下：

验证状态：

• ✅ 模型加载成功（耗时 41.01s）
• ✅ 权重加载正确（0.23 GB）
• ✅ 推理输出正常（文本连贯、语义合理）
• ❌ 精度对比缺失：未在 GPU/CPU 上运行同输入测试，无法提供 NPU vs GPU/CPU 的精度误差数据

自动化验证脚本

本仓库提供 validate_accuracy.py 自动化脚本，可在昇腾 NPU 上快速验证：

python3 validate_accuracy.py --model-path ./MobileLLM-125M

脚本将执行上述三个测试用例，输出结果并保存到 validation_results.json。

精度对齐提示：validation_results.json 中记录了 NPU 的推理输出文本。如需进行精度对齐验证，请：

1. 在 GPU/CPU 上使用 相同的 Prompt、max_tokens、temperature、top_p 运行推理
2. 将 GPU/CPU 输出与本仓库的 validation_results.json 中的 NPU 输出进行对比
3. 计算余弦相似度、绝对误差等精度指标

昇腾适配说明

MobileLLM-125M 为标准 Llama 架构变体，适配昇腾 NPU 需对 vLLM-Ascend 源码做两处改动：

1. 模型注册

文件：vllm/vllm/model_executor/models/registry.py

# 在 _TEXT_GENERATION_MODELS 字典中添加
"MobileLLMForCausalLM": ("llama", "LlamaForCausalLM"),

MobileLLM 的架构与 Llama 高度一致，可直接路由到 vLLM 的 LlamaForCausalLM 实现。

2. 配置字段映射

文件：vllm/vllm/config/model.py

# 在 ConfiguredModel.__init__ 中添加
if (
    hasattr(hf_config, "share_embedding")
    and hf_config.share_embedding
    and not getattr(hf_config, "tie_word_embeddings", False)
):
    hf_config.tie_word_embeddings = True

MobileLLM 使用 share_embedding 字段控制 embedding 共享，而 vLLM 的 Llama 实现期望 tie_word_embeddings 字段。

3. Tokenizer 注意事项

MobileLLM-125M 仅包含 tokenizer.model（SentencePiece），缺少 tokenizer.json（HuggingFace fast tokenizer），因此必须使用 slow tokenizer 模式：

llm = LLM(..., tokenizer_mode='slow')

如果在不指定 tokenizer_mode='slow' 的情况下加载，会触发 fast→slow 的自动降级，可能因 bool 类型不匹配而报错。

📌 临时验证方案：如果不想修改 vLLM 源码，可将模型 config.json 中 architectures 字段临时替换为 LlamaForCausalLM，同时设置 tie_word_embeddings=True，使 vLLM 可直接加载。但正式部署仍需完成上述源码注册。

适配总结

详细适配流程见 README_ASCEND.md。

许可

本仓库仅包含模型部署适配方案，不包含模型权重。模型权重版权归 Facebook/Meta 所有，遵循原模型许可协议。