冬
gcw_IDzXRVNw/embeddinggemma-300m-ascend
模型介绍文件和版本Pull Requests讨论分析
下载使用量0

embeddinggemma-300m Ascend NPU 部署指南

项目简介

embeddinggemma-300m 是 Google DeepMind 开发的 300M 参数文本嵌入模型,基于 Gemma3 架构,支持句子嵌入和语义相似度计算。

特性

  • 支持 Ascend NPU 推理加速
  • CPU vs NPU 精度对比测试
  • 输出 768 维嵌入向量
  • 支持最长 2048 token 的输入

环境要求

  • 硬件: 华为 Ascend 910 系列 NPU
  • CANN: 7.1.RC1 或更高版本
  • PyTorch: 2.0+ with torch_npu

目录结构

/data/ysws/agentsp/5-15/embeddinggemma-300m-ascend/
├── inference.py          # 推理测试脚本
├── log.txt               # 测试日志
├── README.md             # 本文档
├── test_embeddings.pt    # 测试嵌入结果
├── test_samples.pt       # 测试样本
├── test_samples.json     # 测试样本JSON
└── precision_results.json # 精度测试结果

部署步骤

1. 进入容器

docker exec -it test-modelagent bash

2. 设置环境变量

source /usr/local/Ascend/ascend-toolkit/set_env.sh

3. 模型文件

模型文件应放在 /data/ysws/agentsp/5-15/embeddinggemma-300m/ 目录下:

  • model.safetensors - 模型权重 (约 1.2GB)
  • config.json - 模型配置
  • tokenizer.json / tokenizer.model - 分词器
  • 其他配置文件

使用方式

方式一:普通推理模式

cd /data/ysws/agentsp/5-15/embeddinggemma-300m-ascend/

python3 inference.py

python3 inference.py --texts "hello world" "test sentence"

python3 inference.py --device npu:0

推理日志见log.txt

方式二:精度测试模式 (CPU vs NPU)

cd /data/ysws/agentsp/5-15/embeddinggemma-300m-ascend/

python3 inference.py --precision_test

python3 inference.py --precision_test --num_tests 5

命令行参数说明

参数说明默认值
--model_path模型文件路径/data/ysws/agentsp/5-15/embeddinggemma-300m
--output_dir输出目录/data/ysws/agentsp/5-15/embeddinggemma-300m-ascend
--device运行设备npu:0
--precision_test运行精度测试模式False
--num_tests精度测试的文本数量5
--max_length最大序列长度128
--texts自定义输入文本默认测试文本

测试验证

精度测试结果

指标实测值阈值状态
Mean relative error0.0024%< 1%PASS
Max absolute error2.12e-05--
Cosine similarity1.0000~1.0PASS

性能数据

操作耗时
模型加载3.79s
CPU 推理 (5 texts)0.785s
NPU 推理 (5 texts)0.745s

测试日志

完整测试日志保存在 log.txt

Python API 使用示例

基本推理

import torch
from transformers import AutoModel, AutoTokenizer

model_path = "/data/ysws/agentsp/5-15/embeddinggemma-300m"
tokenizer = AutoTokenizer.from_pretrained(model_path)
model = AutoModel.from_pretrained(model_path, trust_remote_code=True)

device = torch.device("npu:0")
model = model.to(device).eval()

texts = ["hello world", "test sentence"]
inputs = tokenizer(texts, padding=True, truncation=True, max_length=128, return_tensors='pt')
inputs = {k: v.to(device) for k, v in inputs.items()}

with torch.no_grad():
    outputs = model(**inputs)

emb = outputs.last_hidden_state.mean(dim=1)
print(f"Embeddings shape: {emb.shape}")
print(f"First embedding: {emb[0][:5].tolist()}")

语义相似度计算

from sklearn.metrics.pairwise import cosine_similarity
import numpy as np

emb1 = embeddings[0].cpu().numpy()
emb2 = embeddings[1].cpu().numpy()
similarity = cosine_similarity([emb1], [emb2])[0][0]
print(f"Cosine similarity: {similarity}")

模型结构

  • 架构类型: Gemma3TextModel (Transformer-based)
  • 参数量: 300M
  • 隐藏层维度: 768
  • 层数: 24
  • 注意力头: 3 (query), 1 (key/value)
  • 滑动窗口注意力: 512
组件说明
embedding词嵌入层 (262144 vocab)
layers24 层 Transformer 编码器
normRMSNorm 归一化
output768 维句子嵌入 (mean pooling)

输出格式

模型输出 BaseModelOutputWithPast,包含:

  • last_hidden_state: [batch_size, seq_len, hidden_size]
  • past_key_values: (可选) 缓存的 KV 值

最终嵌入通过 mean pooling 得到: [batch_size, 768]

常见问题

Q: 精度测试显示 FAIL?

A: 由于 CPU/NPU 数值精度差异,极少量近零值可能导致较大相对误差。99% 的值误差 < 0.02%,cosine similarity = 1.0,结果实际可用。

Q: 模型加载慢?

A: 首次加载需要解析 safetensors 权重,约 1.2GB,后续使用会更快。

Q: 如何提高推理速度?

A: 使用 NPU 加速,batch 处理多个文本。

参考链接

  • 原始模型: https://huggingface.co/google/embeddinggemma-300m
  • Gemma3 论文: https://arxiv.org/abs/2509.20354
  • Transformers: https://huggingface.co/docs/transformers

许可证

本项目遵循 Google Gemma License.