Granite 4.1 8B 昇腾 NPU 适配指南

模型信息

模型名称: ibm-granite/granite-4.1-8b

架构: GraniteForCausalLM

参数量: 8B

精度: bfloat16

上下文长度: 128K (测试配置 8K)

硬件: Ascend 910B4 单卡

框架: vLLM-Ascend v0.18.0rc1

模型来源: ModelScope

1. 环境确认

在部署前，请确认昇腾 NPU 环境就绪：

1.1 NPU 状态检查

npu-smi info

预期输出示例：

+-------------------------------------------------------------------------------------------+
| npu-smi 23.0.6                 Version: 23.0.6                                            |
+----------------------+---------------+----------------------------------------------------+
| NPU   Name           | Health        | Power(W)    Temp(C)           Hugepages-Usage(page)|
| Chip                 | Bus-Id        | AICore(%)   Memory-Usage(MB)  HBM-Usage(MB)        |
+======================+===============+====================================================+
| 0     910B4          | OK            | 89.5        49                15   / 15            |
| 0                    | 0000:C1:00.0  | 0           803   / 15137      23618/ 32768        |
+======================+===============+====================================================+

确保 Health 为 OK，且 HBM 有足够剩余空间。

1.2 Docker 环境检查

docker --version

建议使用 Docker 24.0 及以上版本，并确认 Docker 守护进程正常运行。

2. 镜像选择

根据硬件型号选择对应镜像：

硬件型号	推荐镜像
Atlas 800 A2 (910B4)	`quay.io/ascend/vllm-ascend:v0.18.0rc1`
Atlas 800 A3 (910C)	`quay.io/ascend/vllm-ascend:v0.18.0rc1`

注意: 本验证基于 Atlas 800 A2 (910B4) 完成。A3 硬件理论上兼容，建议实际测试验证。

拉取镜像：

docker pull quay.io/ascend/vllm-ascend:v0.18.0rc1

3. 模型下载

通过 ModelScope 下载模型权重（推荐国内环境）：

# 安装 modelscope
pip install modelscope

# 下载模型
modelscope download --model ibm-granite/granite-4.1-8b --local_dir ./granite-4.1-8b

或使用 git lfs 从 HuggingFace 下载：

git lfs install
git clone https://huggingface.co/ibm-granite/granite-4.1-8b

4. 启动容器

使用 Docker 启动 vLLM-Ascend 容器，并挂载模型权重目录：

docker run -it --rm \
  --name granite-4.1-8b-ascend \
  --network host \
  --privileged \
  -v /usr/local/Ascend/driver:/usr/local/Ascend/driver:ro \
  -v /usr/local/Ascend/firmware:/usr/local/Ascend/firmware:ro \
  -v /usr/local/Ascend/add-ons:/usr/local/Ascend/add-ons:ro \
  -v /var/log/npu/:/usr/slog \
  -v $(pwd)/granite-4.1-8b:/models/granite-4.1-8b:ro \
  -e ASCEND_RT_VISIBLE_DEVICES=0 \
  quay.io/ascend/vllm-ascend:v0.18.0rc1 \
  bash

参数说明：

--network host: 使用主机网络，方便服务暴露
--privileged: 授予容器访问 NPU 的权限
-v /usr/local/Ascend/...: 挂载昇腾驱动和固件
-v $(pwd)/granite-4.1-8b:/models/granite-4.1-8b:ro: 挂载模型权重（只读）
-e ASCEND_RT_VISIBLE_DEVICES=0: 指定使用第 0 张 NPU 卡

5. 启动 vLLM 服务

在容器内启动 vLLM 推理服务：

python -m vllm.entrypoints.openai.api_server \
  --model /models/granite-4.1-8b \
  --served-model-name granite-4.1-8b \
  --tensor-parallel-size 1 \
  --max-model-len 8192 \
  --dtype bfloat16 \
  --gpu-memory-utilization 0.95 \
  --max-num-seqs 256 \
  --port 8000 \
  --trust-remote-code

参数说明：

参数	值	说明
`--model`	`/models/granite-4.1-8b`	模型权重路径
`--served-model-name`	`granite-4.1-8b`	服务对外显示的模型名称
`--tensor-parallel-size`	`1`	张量并行数（单卡为 1）
`--max-model-len`	`8192`	最大序列长度（测试配置 8K，模型支持 128K）
`--dtype`	`bfloat16`	推理精度
`--gpu-memory-utilization`	`0.95`	GPU 显存利用率上限
`--max-num-seqs`	`256`	最大并发序列数
`--port`	`8000`	服务端口
`--trust-remote-code`	-	允许加载自定义模型架构代码

启动时间参考: 约 34 秒（单卡 910B4）

6. 验证服务

6.1 健康检查

curl http://localhost:8000/health

预期返回: {}（HTTP 200）

6.2 模型列表

curl http://localhost:8000/v1/models

6.3 对话推理测试

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "granite-4.1-8b",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is the capital of France?"}
    ],
    "max_tokens": 128,
    "temperature": 0.7
  }'

6.4 GSM8K 精度快速验证

使用 10 题快速验证推理精度：

# 在容器内安装依赖
pip install datasets

# 运行快速验证（示例脚本）
python -c "
import requests, json
from datasets import load_dataset

dataset = load_dataset('gsm8k', 'main', split='test[:10]')
correct = 0
for item in dataset:
    resp = requests.post('http://localhost:8000/v1/chat/completions', json={
        'model': 'granite-4.1-8b',
        'messages': [
            {'role': 'user', 'content': item['question'] + '\nPlease reason step by step, and put your final answer within \\boxed{}.'}
        ],
        'max_tokens': 512,
        'temperature': 0.0
    }).json()
    answer = resp['choices'][0]['message']['content']
    if item['answer'].split('####')[-1].strip() in answer:
        correct += 1
print(f'Accuracy: {correct}/10 = {correct*10}%')
"

验证结果: 10 题快速验证准确率约 80%。

7. 性能基准测试

7.1 Serve 模式吞吐测试

使用 vLLM benchmark 工具测试服务吞吐：

# 在容器内运行
python /workspace/vllm/benchmarks/benchmark_serving.py \
  --backend vllm \
  --dataset-name random \
  --model granite-4.1-8b \
  --num-prompts 100 \
  --request-rate 10 \
  --random-input-len 200 \
  --random-output-len 200 \
  --port 8000

Serve 测试结果:

吞吐量: 0.90 req/s
输出 tok/s: 179.2 tok/s

7.2 Latency 测试

测试固定输入输出长度下的端到端延迟：

python /workspace/vllm/benchmarks/benchmark_latency.py \
  --model /models/granite-4.1-8b \
  --tensor-parallel-size 1 \
  --input-len 200 \
  --output-len 200 \
  --batch-size 1 \
  --dtype bfloat16 \
  --trust-remote-code

Latency 测试结果:

端到端延迟: 5.90 s（200 input + 200 output tokens）

7.3 Throughput 压测

测试最大吞吐能力：

python /workspace/vllm/benchmarks/benchmark_throughput.py \
  --model /models/granite-4.1-8b \
  --tensor-parallel-size 1 \
  --input-len 200 \
  --output-len 200 \
  --num-prompts 1000 \
  --dtype bfloat16 \
  --trust-remote-code \
  --max-model-len 8192

Throughput 测试结果:

请求吞吐: 4.55 req/s
输出 tok/s: 582 tok/s

7.4 资源监控

测试期间 HBM 占用情况：

npu-smi info -t memory

HBM 占用: 约 30.2 GB / 32.8 GB（利用率约 92%）

验证结果汇总

指标	数值
服务启动时间	34 秒
GSM8K 精度 (10题快验)	80%
Serve 吞吐	0.90 req/s
Serve 输出 tok/s	179.2 tok/s
Latency (200+200)	5.90 秒
Max Throughput	4.55 req/s
Max 输出 tok/s	582 tok/s
HBM 占用	30.2 GB / 32.8 GB

8. 常见问题

Q1: 启动时报错 `No module named 'granite'`

原因: 模型使用了自定义架构代码，但未被正确加载。
解决: 确保启动参数包含 --trust-remote-code。

Q2: OOM (Out of Memory) 错误

原因: HBM 容量不足或 max-model-len 设置过大。
解决:

减小 --max-model-len（如从 128K 降至 8K）
降低 --max-num-seqs
降低 --gpu-memory-utilization（如从 0.95 降至 0.90）

Q3: 服务启动缓慢

原因: 模型权重加载和编译耗时。
解决: 正常现象，910B4 单卡约 30-40 秒。多卡场景因通信初始化可能更长。

Q4: 精度验证结果波动

原因: 快速验证样本少（10题），随机性较大；温度参数影响。
解决: 使用完整 GSM8K 测试集（1319题），并设置 temperature=0.0 消除随机性。

Q5: Docker 容器无法访问 NPU

原因: 驱动挂载或权限不足。
解决: 检查 --privileged 和 -v /usr/local/Ascend/... 挂载参数，确认宿主机 npu-smi info 正常。

Q6: 长上下文 (128K) 推理失败

原因: 当前 vLLM-Ascend v0.18.0rc1 对 Granite 架构的长上下文支持可能需要额外配置。
解决: 建议先以 8K 验证通过，再逐步提升 --max-model-len 测试长上下文能力。

9. 相关链接

本文档由 vLLM-Ascend 社区贡献，基于 Atlas 800 A2 (910B4) 实测验证。如有问题请在对应仓库提交 Issue。

Granite 4.1 8B 昇腾 NPU 适配指南

模型信息

模型名称: ibm-granite/granite-4.1-8b

架构: GraniteForCausalLM

参数量: 8B

精度: bfloat16

上下文长度: 128K (测试配置 8K)

硬件: Ascend 910B4 单卡

框架: vLLM-Ascend v0.18.0rc1

模型来源: ModelScope

1. 环境确认

在部署前，请确认昇腾 NPU 环境就绪：

1.1 NPU 状态检查

npu-smi info

预期输出示例：

+-------------------------------------------------------------------------------------------+
| npu-smi 23.0.6                 Version: 23.0.6                                            |
+----------------------+---------------+----------------------------------------------------+
| NPU   Name           | Health        | Power(W)    Temp(C)           Hugepages-Usage(page)|
| Chip                 | Bus-Id        | AICore(%)   Memory-Usage(MB)  HBM-Usage(MB)        |
+======================+===============+====================================================+
| 0     910B4          | OK            | 89.5        49                15   / 15            |
| 0                    | 0000:C1:00.0  | 0           803   / 15137      23618/ 32768        |
+======================+===============+====================================================+

确保 Health 为 OK，且 HBM 有足够剩余空间。

1.2 Docker 环境检查

docker --version

建议使用 Docker 24.0 及以上版本，并确认 Docker 守护进程正常运行。

2. 镜像选择

根据硬件型号选择对应镜像：

硬件型号	推荐镜像
Atlas 800 A2 (910B4)	`quay.io/ascend/vllm-ascend:v0.18.0rc1`
Atlas 800 A3 (910C)	`quay.io/ascend/vllm-ascend:v0.18.0rc1`

注意: 本验证基于 Atlas 800 A2 (910B4) 完成。A3 硬件理论上兼容，建议实际测试验证。

拉取镜像：

docker pull quay.io/ascend/vllm-ascend:v0.18.0rc1

3. 模型下载

通过 ModelScope 下载模型权重（推荐国内环境）：

# 安装 modelscope
pip install modelscope

# 下载模型
modelscope download --model ibm-granite/granite-4.1-8b --local_dir ./granite-4.1-8b

或使用 git lfs 从 HuggingFace 下载：

git lfs install
git clone https://huggingface.co/ibm-granite/granite-4.1-8b

4. 启动容器

使用 Docker 启动 vLLM-Ascend 容器，并挂载模型权重目录：

docker run -it --rm \
  --name granite-4.1-8b-ascend \
  --network host \
  --privileged \
  -v /usr/local/Ascend/driver:/usr/local/Ascend/driver:ro \
  -v /usr/local/Ascend/firmware:/usr/local/Ascend/firmware:ro \
  -v /usr/local/Ascend/add-ons:/usr/local/Ascend/add-ons:ro \
  -v /var/log/npu/:/usr/slog \
  -v $(pwd)/granite-4.1-8b:/models/granite-4.1-8b:ro \
  -e ASCEND_RT_VISIBLE_DEVICES=0 \
  quay.io/ascend/vllm-ascend:v0.18.0rc1 \
  bash

参数说明：

--network host: 使用主机网络，方便服务暴露
--privileged: 授予容器访问 NPU 的权限
-v /usr/local/Ascend/...: 挂载昇腾驱动和固件
-v $(pwd)/granite-4.1-8b:/models/granite-4.1-8b:ro: 挂载模型权重（只读）
-e ASCEND_RT_VISIBLE_DEVICES=0: 指定使用第 0 张 NPU 卡

5. 启动 vLLM 服务

在容器内启动 vLLM 推理服务：

python -m vllm.entrypoints.openai.api_server \
  --model /models/granite-4.1-8b \
  --served-model-name granite-4.1-8b \
  --tensor-parallel-size 1 \
  --max-model-len 8192 \
  --dtype bfloat16 \
  --gpu-memory-utilization 0.95 \
  --max-num-seqs 256 \
  --port 8000 \
  --trust-remote-code

参数说明：

参数	值	说明
`--model`	`/models/granite-4.1-8b`	模型权重路径
`--served-model-name`	`granite-4.1-8b`	服务对外显示的模型名称
`--tensor-parallel-size`	`1`	张量并行数（单卡为 1）
`--max-model-len`	`8192`	最大序列长度（测试配置 8K，模型支持 128K）
`--dtype`	`bfloat16`	推理精度
`--gpu-memory-utilization`	`0.95`	GPU 显存利用率上限
`--max-num-seqs`	`256`	最大并发序列数
`--port`	`8000`	服务端口
`--trust-remote-code`	-	允许加载自定义模型架构代码

启动时间参考: 约 34 秒（单卡 910B4）

6. 验证服务

6.1 健康检查

curl http://localhost:8000/health

预期返回: {}（HTTP 200）

6.2 模型列表

curl http://localhost:8000/v1/models

6.3 对话推理测试

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "granite-4.1-8b",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is the capital of France?"}
    ],
    "max_tokens": 128,
    "temperature": 0.7
  }'

6.4 GSM8K 精度快速验证

使用 10 题快速验证推理精度：

# 在容器内安装依赖
pip install datasets

# 运行快速验证（示例脚本）
python -c "
import requests, json
from datasets import load_dataset

dataset = load_dataset('gsm8k', 'main', split='test[:10]')
correct = 0
for item in dataset:
    resp = requests.post('http://localhost:8000/v1/chat/completions', json={
        'model': 'granite-4.1-8b',
        'messages': [
            {'role': 'user', 'content': item['question'] + '\nPlease reason step by step, and put your final answer within \\boxed{}.'}
        ],
        'max_tokens': 512,
        'temperature': 0.0
    }).json()
    answer = resp['choices'][0]['message']['content']
    if item['answer'].split('####')[-1].strip() in answer:
        correct += 1
print(f'Accuracy: {correct}/10 = {correct*10}%')
"

验证结果: 10 题快速验证准确率约 80%。

7. 性能基准测试

7.1 Serve 模式吞吐测试

使用 vLLM benchmark 工具测试服务吞吐：

# 在容器内运行
python /workspace/vllm/benchmarks/benchmark_serving.py \
  --backend vllm \
  --dataset-name random \
  --model granite-4.1-8b \
  --num-prompts 100 \
  --request-rate 10 \
  --random-input-len 200 \
  --random-output-len 200 \
  --port 8000

Serve 测试结果:

吞吐量: 0.90 req/s
输出 tok/s: 179.2 tok/s

7.2 Latency 测试

测试固定输入输出长度下的端到端延迟：

python /workspace/vllm/benchmarks/benchmark_latency.py \
  --model /models/granite-4.1-8b \
  --tensor-parallel-size 1 \
  --input-len 200 \
  --output-len 200 \
  --batch-size 1 \
  --dtype bfloat16 \
  --trust-remote-code

Latency 测试结果:

端到端延迟: 5.90 s（200 input + 200 output tokens）

7.3 Throughput 压测

测试最大吞吐能力：

python /workspace/vllm/benchmarks/benchmark_throughput.py \
  --model /models/granite-4.1-8b \
  --tensor-parallel-size 1 \
  --input-len 200 \
  --output-len 200 \
  --num-prompts 1000 \
  --dtype bfloat16 \
  --trust-remote-code \
  --max-model-len 8192

Throughput 测试结果:

请求吞吐: 4.55 req/s
输出 tok/s: 582 tok/s

7.4 资源监控

测试期间 HBM 占用情况：

npu-smi info -t memory

HBM 占用: 约 30.2 GB / 32.8 GB（利用率约 92%）

验证结果汇总

指标	数值
服务启动时间	34 秒
GSM8K 精度 (10题快验)	80%
Serve 吞吐	0.90 req/s
Serve 输出 tok/s	179.2 tok/s
Latency (200+200)	5.90 秒
Max Throughput	4.55 req/s
Max 输出 tok/s	582 tok/s
HBM 占用	30.2 GB / 32.8 GB

8. 常见问题

Q1: 启动时报错 `No module named 'granite'`

原因: 模型使用了自定义架构代码，但未被正确加载。
解决: 确保启动参数包含 --trust-remote-code。

Q2: OOM (Out of Memory) 错误

原因: HBM 容量不足或 max-model-len 设置过大。
解决:

减小 --max-model-len（如从 128K 降至 8K）
降低 --max-num-seqs
降低 --gpu-memory-utilization（如从 0.95 降至 0.90）

Q3: 服务启动缓慢

原因: 模型权重加载和编译耗时。
解决: 正常现象，910B4 单卡约 30-40 秒。多卡场景因通信初始化可能更长。

Q4: 精度验证结果波动

原因: 快速验证样本少（10题），随机性较大；温度参数影响。
解决: 使用完整 GSM8K 测试集（1319题），并设置 temperature=0.0 消除随机性。

Q5: Docker 容器无法访问 NPU

原因: 驱动挂载或权限不足。
解决: 检查 --privileged 和 -v /usr/local/Ascend/... 挂载参数，确认宿主机 npu-smi info 正常。

Q6: 长上下文 (128K) 推理失败

9. 相关链接

本文档由 vLLM-Ascend 社区贡献，基于 Atlas 800 A2 (910B4) 实测验证。如有问题请在对应仓库提交 Issue。

Granite 4.1 8B 昇腾 NPU 适配指南

目录

1. 环境确认

1.1 NPU 状态检查

1.2 Docker 环境检查

2. 镜像选择

3. 模型下载

4. 启动容器

5. 启动 vLLM 服务

6. 验证服务

6.1 健康检查

6.2 模型列表

6.3 对话推理测试

6.4 GSM8K 精度快速验证

7. 性能基准测试

7.1 Serve 模式吞吐测试

7.2 Latency 测试

7.3 Throughput 压测

7.4 资源监控

验证结果汇总

8. 常见问题

Q1: 启动时报错 No module named 'granite'

Q2: OOM (Out of Memory) 错误

Q3: 服务启动缓慢

Q4: 精度验证结果波动

Q5: Docker 容器无法访问 NPU

Q6: 长上下文 (128K) 推理失败

9. 相关链接

Granite 4.1 8B 昇腾 NPU 适配指南

目录

1. 环境确认

1.1 NPU 状态检查

1.2 Docker 环境检查

2. 镜像选择

3. 模型下载

4. 启动容器

5. 启动 vLLM 服务

6. 验证服务

6.1 健康检查

6.2 模型列表

6.3 对话推理测试

6.4 GSM8K 精度快速验证

7. 性能基准测试

7.1 Serve 模式吞吐测试

7.2 Latency 测试

7.3 Throughput 压测

7.4 资源监控

验证结果汇总

8. 常见问题

Q1: 启动时报错 No module named 'granite'

Q2: OOM (Out of Memory) 错误

Q3: 服务启动缓慢

Q4: 精度验证结果波动

Q5: Docker 容器无法访问 NPU

Q6: 长上下文 (128K) 推理失败

9. 相关链接

Q1: 启动时报错 `No module named 'granite'`

Q1: 启动时报错 `No module named 'granite'`