Granite-Embedding-311M-Multilingual-R2

IBM Granite Embedding 多语言文本嵌入模型 · 昇腾 NPU 适配验证版

本仓库在标准 HuggingFace 模型基础上，提供了 华为 Ascend 910B NPU 的完整适配验证结果，包括：

• ✅ 精度对齐（NPU vs GPU H100，cosine similarity 最大误差 < 0.15%）
• ✅ Matryoshka 维度裁剪验证（128/256/384/512 dim）
• ✅ 性能基准测试（单卡吞吐最高 192 req/s）
• ✅ vLLM-Ascend 部署指南与代码示例

模型概述

Granite-Embedding-311M-Multilingual-R2 是 IBM 发布的轻量级多语言嵌入模型。基于 ModernBERT 架构（仅编码器），支持 32K 超长上下文，适用于跨语言语义检索、文本相似度计算、RAG 系统中的文档嵌入。

关键特性

• 🪆 Matryoshka Representation Learning — 支持动态维度裁剪（768→128/256/384/512），无需重新编码即可在精度与效率之间灵活平衡
• 🌐 多语言对齐 — 在英语、中文、日语等语种上均有出色的跨语言检索表现
• 📐 32K 上下文 — ModernBERT 原生支持超长文本编码，适用于长文档检索
• 🚀 昇腾 NPU 就绪 — 已验证在华为 Ascend 910B 上通过 vLLM-Ascend 高效推理

精度验证：NPU vs GPU

在 3 种语言（中文、英文、日文）× 3 条文本的跨语言余弦相似度矩阵上进行精度对比：

结论：NPU 推理结果与 GPU H100 基线高度一致，误差来源于 bfloat16 精度及算子实现差异，对实际检索排序无影响。

完整的 3×3 相似度矩阵对比见 models/ibm-granite/granite-embedding-311m-multilingual-r2/README.md

Matryoshka 维度裁剪验证

注意：裁剪后的子向量需重新 L2 归一化后才能进行正确的余弦相似度比较。

性能基准（Ascend 910B2）

吞吐峰值：192 req/s（batch=16, seq_len=32）· 显存占用 < 2 GB

快速部署

方式 1: vLLM-Ascend Python API

from vllm import LLM

model_path = "2502_90647073/granite-embedding-311m-multilingual-r2"  # 或本地路径
llm = LLM(
    model=model_path,
    trust_remote_code=True,
    dtype="bfloat16",
    max_model_len=32768,
    max_num_seqs=16,
    enforce_eager=True,
    gpu_memory_utilization=0.8,
)

texts = ["你的文本", "Your text here", "テキスト"]
outputs = llm.embed(texts)
for i, out in enumerate(outputs):
    embedding = out.outputs.embedding  # 768 维 list
    print(f"[{i}] dim={len(embedding)}")

方式 2: OpenAI 兼容 API 服务

python -m vllm.entrypoints.openai.api_server \
    --model 2502_90647073/granite-embedding-311m-multilingual-r2 \
    --task embed \
    --dtype bfloat16 \
    --max-model-len 32768 \
    --max-num-seqs 16 \
    --enforce-eager \
    --gpu-memory-utilization 0.8 \
    --port 8000

curl http://localhost:8000/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{"model": "granite-embedding", "input": "Hello world"}'

环境要求

模型架构详情

• Backbone: ModernBERT (bidirectional encoder-only Transformer)
• Parameters: 311M
• Hidden Size: 768
• Layers: 22
• Attention Heads: 12
• Activation: GeGLU
• Vocab Size: 50,368
• Pooling: CLS token
• Normalization: L2 normalization on output
• Training Loss: Multiple Negatives Ranking Loss + Matryoshka Representation Learning

详细验证报告

完整的精度对比矩阵、Matryoshka 裁剪验证、性能分析、FAQ 等内容请查看：

👉 models/ibm-granite/granite-embedding-311m-multilingual-r2/README.md

原始精度与性能数据：

👉 granite_npu_results.json

协议与引用

本项目基于 MIT 协议开源。

@misc{granite-embedding-311m-multilingual-r2,
  author = {IBM},
  title = {Granite-Embedding-311M-Multilingual-R2},
  year = {2025},
  url = {https://huggingface.co/ibm-granite/granite-embedding-311m-multilingual-r2}
}

相关链接

• 🤗 HuggingFace 官方模型卡
• ⚡ vLLM-Ascend
• 🏗️ ModernBERT 论文