L
Lumiire/UAE-Large-V1
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

UAE-Large-V1 昇腾 NPU 模型适配与部署

简介

UAE-Large-V1(Universal AnglE Embedding)是 WhereIsAI 团队开源的通用语义向量模型,MIT 协议授权,基于 AnglE 方法在 BERT-large 骨干网络上进行对比学习训练,输出 1024 维句向量。模型在 MTEB 多项英文评测上表现出色,广泛应用于文本检索、语义相似度、文本聚类、分类等场景。

本仓库完成了 UAE-Large-V1 在华为昇腾 Ascend910 NPU 上的完整适配与部署:权重自 GitCode(HF 镜像仓)拉取,采用 vLLM-Ascend 0.18.0 以 embedding 推理(pooling runner)形态承载模型执行,打通「权重加载 → NPU 推理 → OpenAI 兼容服务化」全链路,并围绕服务启动、冒烟验证、性能与精度进行了系统化测评。推理计算完全运行在昇腾 NPU 上,对外提供 /v1/embeddings 接口。

验证环境

组件版本 / 规格
操作系统Linux 5.10.0-182 (aarch64)
NPU 设备华为昇腾 Ascend910,双 Chip,单 Chip 64GB HBM
NPU 驱动CANN 8.5.1
npu-smi25.5.5
Python3.11.14
PyTorch2.9.0
torch_npu2.9.0.post1
vLLM0.18.0
vLLM-Ascend0.18.0

模型权重为 fp32 精度 model.safetensors(1.34GB,391 个 tensor),参数量约 3.55 亿。模型配置:BertModel 架构、24 层、hidden_size 1024、16 注意力头、max_position_embeddings 512,池化方式为 CLS 池化。

适配说明

适配过程中重点确认了三件事:

  1. 架构兼容性:UAE-Large-V1 的 config.json 声明 architectures: [BertModel],在 vLLM 注册表中映射为 BertEmbeddingModel(is_pooling_model=True),vLLM-Ascend 平台插件可原生加载,无需在 vllm-ascend 侧新增模型文件。
  2. 算子兼容性:vllm/model_executor/models/bert.py 实现均为 PyTorch 原生算子(LayerNorm、Linear、Attention 抽象接口),无 CUDA-only 内核;vllm-ascend 已内置 patch_bert.py 补丁,用位运算替代 token_type_ids 的位移实现,规避 ACLGraph 对 shift 算子的限制。
  3. 池化策略对齐:模型 1_Pooling/config.json 指定 pooling_mode_cls_token: true,vLLM 解析 sentence-transformers 配置后自动采用 seq_pooling_type=CLS,与模型原始推理语义一致。

服务启动

1. 依赖安装

pip install -r requirements.txt

2. 权重下载

git clone https://atomgit.com/hf_mirrors/WhereIsAI/UAE-Large-V1.git /opt/atomgit/models/UAE-Large-V1

3. 启动推理服务

ASCEND_RT_VISIBLE_DEVICES=0 python3 -m vllm.entrypoints.openai.api_server \
  --model /opt/atomgit/models/UAE-Large-V1 \
  --host 0.0.0.0 --port 8012 \
  --max-model-len 512 \
  --gpu-memory-utilization 0.25 \
  --dtype bfloat16 \
  --enforce-eager

vLLM 依据 BertModel 架构自动选择 pooling runner(embedding 任务),无需显式声明任务类型。启动日志出现 Application startup complete 即就绪,权重加载耗时约 30 秒。

4. 提供的接口

方法路径说明
GET/v1/models模型信息(max_model_len 等)
POST/v1/embeddings文本向量化,{"input": "..."} 或 {"input": ["...", ...]}

Smoke 验证

模型信息

curl -s http://127.0.0.1:8012/v1/models

返回 BertModel 对应的 pooling 服务信息,max_model_len 为 512。

文本向量化

curl -s http://127.0.0.1:8012/v1/embeddings \
  -H 'Content-Type: application/json' \
  -d '{"input": "The capital of France is Paris."}'

正常返回 object: "list",data[0].embedding 为 1024 维浮点数组,data[0].index 为 0。

语义相似度冒烟

python3 inference.py --host 127.0.0.1 --port 8012 --encode "A dog is chasing a cat." "A cat is being chased by a dog." --similarity
# 相似度: 0.9107

性能参考

以下数据在 Ascend910 (Chip0) 上、单实例服务条件下测得,输入为平均 20 token 的英文短句:

指标数值
并发基准请求数1200(12 并发 × 100 轮)
平均延迟44.50 ms
P50 延迟44.22 ms
P95 延迟48.33 ms
最小 / 最大延迟37.96 ms / 62.00 ms
并发吞吐269 req/s
单线程持续吞吐(45s 压测)~48 req/s
推理期 AICore 利用率7% ~ 9%
推理期 NPU 功耗~192 W
推理期 HBM 占用(进程)~1.0 GB
权重加载耗时~30 s

说明:UAE-Large-V1 为中小规模 BERT 编码器,单请求计算量小,AICore 利用率在串行负载下处于个位数区间,属正常现象;并发批处理可进一步提升利用率与吞吐。

精度测评

语义相似度验证

对 5 组句子对计算余弦相似度,相关句子对相似度显著高于无关句子对:

句子对内容相似度
同义改写"The capital of France is Paris." ↔ "Paris is the capital city of France."0.9781
同义改写"A dog is chasing a cat in the garden." ↔ "A cat is being chased by a dog in the yard."0.9107
语义相关"Machine learning models require large amounts of data." ↔ "Deep neural networks are trained on big datasets."0.7626
语义无关"The weather is sunny and warm today." ↔ "I am going to cook pasta for dinner tonight."0.3268
语义无关"Apple released a new smartphone model." ↔ "A basket of fresh green apples sits on the table."0.4833

检索 Hit@1 验证

构建 8 文档语料库与 8 条对应查询,全部查询的正确文档均排在第 1 位:

指标数值
语料规模8 篇英文文档
查询数8 条
Hit@1 准确率8/8 = 100%

结论:UAE-Large-V1 在昇腾 NPU 上经 bf16 精度加载后,语义区分能力与句向量检索排序均表现正确,满足生产使用对向量质量的要求。

注意事项

  1. model 请求字段:vLLM 服务以模型路径作为 served name,请求体携带 "model" 字段时必须与之一致(如 /opt/atomgit/models/UAE-Large-V1),否则返回 404;推荐请求体省略该字段。
  2. NPU 设备选择:通过 ASCEND_RT_VISIBLE_DEVICES 指定空闲设备,避免与同机其他推理任务争用 HBM;本机双 Chip 均承载其他进程,部署时应先确认目标 Chip 剩余显存。
  3. 端口冲突:默认 8012,如被占用可通过 --port 更换。同机多任务部署时请先探测空闲端口。
  4. 精度与 dtype:默认以 bf16 加载,fp32 权重自动降精度;经检索验证向量质量无损。如需更高精度可移除 --dtype bfloat16(显存占用上升至约 1.4GB)。
  5. 输入长度:max_position_embeddings=512,超长文本会被截断,长文档建议先切片再编码后聚合。
  6. eager 模式:本次部署使用 --enforce-eager 关闭 torch.compile 以保证算子兼容稳定性;如需更优性能可尝试移除该参数启用 ACLGraph。