我

LiquidAI/LFM2.5-1.2B-Instruct 在 vLLM-Ascend 上的部署

1. 简介

本文档记录 LiquidAI/LFM2.5-1.2B-Instruct 模型在 vLLM-Ascend 环境下的部署流程与验证结果。

模型架构：Lfm2ForCausalLM（混合架构：10 层卷积 + 6 层 GQA 注意力，共 16 层）

参数量：约 1.17B
上下文长度：128K（max_position_embeddings），建议在 32K 以内使用
词表大小：65,536
隐藏维度：2048

原始权重下载地址：

ModelScope：https://modelscope.cn/models/LiquidAI/LFM2.5-1.2B-Instruct
HuggingFace：https://huggingface.co/LiquidAI/LFM2.5-1.2B-Instruct

已知限制：vllm-ascend 当前版本的 patch_mamba_config 函数在处理小型混合模型（mamba 状态小于注意力页面大小）时存在断言失败问题。本交付件包含修复补丁，启动服务前需通过 serve_lfm2.py 注入该补丁。

2. 验证环境

组件	版本
硬件	华为 Ascend 910B4（32GB HBM × 2）
CANN	25.5.2
Python	3.11
PyTorch	2.9.0+cpu
torch-npu	2.9.0.post1+gitee7ba04
vLLM	0.18.0+empty
vllm-ascend	0.18.0rc1
transformers	4.57.6

NPU：1 逻辑卡
模型路径：/opt/atomgit/models/LiquidAI/LFM2___5-1___2B-Instruct
服务端口：8000

3. 安装步骤

3.1 安装 CANN 工具包

参考华为官方文档安装 CANN 25.5.2 并配置 Ascend NPU 驱动。

3.2 安装 Python 依赖

pip install torch==2.9.0 --index-url https://download.pytorch.org/whl/cpu
pip install torch_npu==2.9.0.post1
pip install vllm==0.18.0
pip install vllm-ascend==0.18.0rc1
pip install transformers==4.57.6
pip install requests

3.3 下载模型权重

export VLLM_USE_MODELSCOPE=true
python -c "from modelscope import snapshot_download; snapshot_download('LiquidAI/LFM2.5-1.2B-Instruct', cache_dir='models')"

4. 服务启动

4.1 使用修复脚本启动 (推荐)

由于 vllm-ascend 对 hybrid 模型的 mamba state 对齐存在已知问题，请使用仓库自带的 serve_lfm2.py 启动服务，该脚本会在导入 vllm-ascend 之前注入修复补丁。

export VLLM_USE_MODELSCOPE=true
export ASCEND_RT_VISIBLE_DEVICES=0

python3 serve_lfm2.py serve /path/to/LFM2___5-1___2B-Instruct \
  --host 0.0.0.0 \
  --port 8000 \
  --tensor-parallel-size 1 \
  --max-model-len 4096 \
  --gpu-memory-utilization 0.5 \
  --dtype bfloat16 \
  --served-model-name LFM2.5-1.2B-Instruct

注意:

首次启动包含 ACL Graph 编译，约需 15-20 秒
PIECEWISE 编译模式在 NPU 上自动启用
由于 LFM2.5 的 mamba state 较小，vllm-ascend 默认 patch 会因 page size 对齐断言失败，必须使用 serve_lfm2.py

4.2 后台启动脚本

bash -c '
  export VLLM_USE_MODELSCOPE=true
  export ASCEND_RT_VISIBLE_DEVICES=0
  nohup python3 serve_lfm2.py serve /path/to/LFM2___5-1___2B-Instruct \
    --host 0.0.0.0 --port 8000 \
    --tensor-parallel-size 1 \
    --max-model-len 4096 \
    --gpu-memory-utilization 0.5 \
    --dtype bfloat16 \
    --served-model-name LFM2.5-1.2B-Instruct \
    > vllm_serve.log 2>&1 &
  echo "Server started"
'

5. 冒烟验证

5.1 基础检查

curl -sf http://127.0.0.1:8000/v1/models

返回模型信息，确认服务正常。

5.2 聊天补全

curl -sf http://127.0.0.1:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "LFM2.5-1.2B-Instruct",
    "messages": [
      {"role": "user", "content": "Explain the difference between TCP and UDP in one sentence."}
    ],
    "temperature": 0,
    "max_tokens": 50
  }'

验证结果：

返回 HTTP 200
回复内容连贯准确
示例输出：TCP 是一种可靠的、面向连接的协议，而 UDP 是一种无连接的、速度更快的协议。

5.3 使用 inference.py

# Chat 模式
python3 inference.py \
  --server-url http://localhost:8000 \
  --mode chat \
  --prompt "What is the capital of France?" \
  --max-tokens 30

# Completion 模式
python3 inference.py \
  --server-url http://localhost:8000 \
  --mode completion \
  --prompt "Once upon a time" \
  --max-tokens 30

6. 精度评测

6.1 评测方法

使用 verify_accuracy.py 对 NPU 推理结果与 CPU 基线进行 FP32 精度对比。

python3 verify_accuracy.py \
  --model-path /path/to/LFM2___5-1___2B-Instruct \
  --prompt "The future of AI is"

评测流程：

CPU 基线推理（FP32）
NPU 推理（FP32）
计算 logits 与 hidden states 的精度指标

6.2 验证结果

指标	Logits	Hidden States
max_abs_error	0.003267	0.005180
mean_abs_error	0.000212	0.000230
relative_error	0.1030%	0.0672%
cosine_similarity	1.000000	1.000000
threshold	1.0%	1.0%
结果	PASS	PASS

结论：NPU 与 CPU 基线高度一致，cosine_similarity = 1.0，relative_error < 0.11%，验证通过。

7. 性能参考

测试条件：1x Ascend 910B4, bfloat16, tensor-parallel=1, max-model-len=4096

指标	数值
模型加载时间	~8.5s
ACL Graph 编译	~15s
首次推理延迟 (chat)	~0.16s
首次推理延迟 (completion)	~0.37s

注：LFM2.5-1.2B 为轻量级模型，推理速度极快，适合边缘部署场景。

8. 注意事项

vllm-ascend patch 问题：当前 vllm-ascend 0.18.0rc1 的 patch_mamba_config.py 对小型 hybrid 模型（如 LFM2.5）会因 ssm_block_page_size < kernel_block_size * attn_single_token_k_page_size 导致断言失败。必须使用交付件中的 serve_lfm2.py 或手动注入 patch_mamba_config_fixed.py。
trust_remote_code：LFM2 使用自定义建模代码 (Lfm2ForCausalLM)，加载时需要 trust_remote_code=True。
内存占用：由于 patch 中对 mamba cache 的 padding 机制，实际运行时 KV cache 内存开销略大于纯 Transformer 模型。建议 gpu-memory-utilization 根据实际环境调整。

9. 文件结构

lfm2.5-1.2b-instruct/
├── inference.py                 # vLLM API 推理客户端
├── verify_accuracy.py           # CPU vs NPU FP32 精度验证
├── serve_lfm2.py                # 带修复补丁的 vLLM 服务启动脚本
├── patch_mamba_config_fixed.py  # vllm-ascend patch 修复
├── readme.md                    # 本文档
├── validation_report.json       # 结构化验证报告
└── logs/
    ├── verify_accuracy.log      # 精度验证日志
    └── smoke_test.log           # 功能测试日志

10. 许可协议

本适配遵循原始模型 MIT License。请参考 LiquidAI/LFM2.5-1.2B-Instruct 获取详细许可信息。

标签：#+NPU #Ascend #vLLM #LFM #LiquidAI