Atomgit-Ascend/paraphrase-multilingual-minilm-l12-v2
模型介绍文件和版本Pull Requests讨论分析
下载使用量0

Paraphrase Multilingual MiniLM L12 V2 昇腾910B部署指南

项目简介

本项目提供基于华为昇腾910B的Paraphrase Multilingual MiniLM L12 V2文本嵌入模型部署方案，支持生产级API服务。该模型是多语言文本嵌入模型，支持100+种语言，适用于文本相似度计算、语义搜索等任务。

模型信息:

  • 模型来源: AtomGit - paraphrase-multilingual-MiniLM-L12-v2
  • AtomGit镜像: sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2
  • 模型大小: ~420MB
  • 支持语言: 100+种语言
  • 最大序列长度: 512 tokens
  • 输出维度: 384

硬件要求

  • NPU: 华为昇腾910B (至少1卡)
  • 内存: 16GB+ (推荐32GB)
  • 存储: 10GB+ SSD (用于模型和缓存)
  • 操作系统: openEuler 22.03 LTS SP1 或 Ubuntu 20.04+
  • CANN版本: 7.0.0+ (推荐7.0.4)

环境准备

1. 安装昇腾驱动和CANN工具包

# 下载并安装CANN工具包
# 参考华为官方文档: https://www.hiascend.com/software/cann

# 验证NPU状态
npu-smi info

# 验证CANN环境
source /usr/local/Ascend/ascend-toolkit/set_env.sh

2. 安装Docker和NPU运行时

# 安装Docker (如果未安装)
sudo apt-get update
sudo apt-get install -y docker.io

# 安装NPU Docker运行时
# 参考华为官方文档配置NPU设备映射

项目结构

paraphrase-multilingual-minilm-l12-v2/
├── api/
│   ├── main.py              # FastAPI主服务
│   ├── model_loader.py      # 模型加载器
│   └── inference.py         # 推理引擎
├── config/
│   ├── config.yaml          # 服务配置
│   └── model_config.yaml    # 模型配置
├── scripts/
│   ├── build.sh             # Docker构建脚本
│   ├── deploy.sh            # 部署脚本
│   └── download_model.sh    # 模型下载脚本
├── Dockerfile               # Docker构建文件
├── requirements.txt         # Python依赖
└── README.md               # 本文档

Docker部署

1. 构建Docker镜像

# 进入项目目录
cd paraphrase-multilingual-minilm-l12-v2

# 构建镜像
docker build -t paraphrase-minilm-ascend:latest .

# 或使用构建脚本
./scripts/build.sh

2. 运行容器

模型路径说明: 如果模型已下载到宿主机 /data0/workspace 目录，使用以下命令挂载模型：

# 使用本地模型（推荐）- 使用NPU 2 (davinci2)
docker run -d \
  --name paraphrase-minilm-api \
  --device=/dev/davinci2 \
  --restart=unless-stopped \
  -p 8003:8000 \
  -v /data0/workspace:/app/models \
  -e LOCAL_MODEL_PATH=/app/models/paraphrase-multilingual-MiniLM-L12-v2 \
  -e NPU_VISIBLE_DEVICES=0 \
  paraphrase-minilm-ascend:latest

# 生产环境运行（推荐）- 使用NPU 2 (davinci2)
docker run -d \
  --name paraphrase-minilm-api \
  --device=/dev/davinci2 \
  --restart=unless-stopped \
  -p 8003:8000 \
  --cpus="4" \
  --memory="8g" \
  -v /data0/workspace:/app/models \
  -v /data/logs/paraphrase-minilm:/app/logs \
  -e LOCAL_MODEL_PATH=/app/models/paraphrase-multilingual-MiniLM-L12-v2 \
  -e NPU_VISIBLE_DEVICES=0 \
  -e WORKERS=2 \
  -e MAX_BATCH_SIZE=32 \
  paraphrase-minilm-ascend:latest

# 如果不挂载模型，将从AtomGit自动下载
docker run -d \
  --name paraphrase-minilm-api \
  --device=/dev/davinci0 \
  -p 8003:8000 \
  -e NPU_VISIBLE_DEVICES=0 \
  paraphrase-minilm-ascend:latest

注意:

  • -v /data0/workspace:/app/models 将宿主机的模型目录挂载到容器内
  • -e LOCAL_MODEL_PATH=/app/models/paraphrase-multilingual-MiniLM-L12-v2 指定容器内的模型路径
  • 如果本地模型不存在，会自动从AtomGit下载

3. 验证部署

# 检查容器状态
docker ps | grep paraphrase-minilm-api

# 查看日志
docker logs -f paraphrase-minilm-api

# 健康检查
curl http://localhost:8003/health

API接口说明

本服务遵循 Sentence Transformers API 协议，提供标准化的文本嵌入接口。

基础信息

  • 服务地址: http://localhost:8003
  • API文档: http://localhost:8003/docs
  • 健康检查: http://localhost:8003/health

核心接口

1. 文本嵌入 (Embedding)

端点: POST /v1/embeddings

请求格式:

curl -X POST "http://localhost:8003/v1/embeddings" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "This is a sample text",
    "model": "paraphrase-multilingual-MiniLM-L12-v2"
  }'

请求参数:

  • input (必需): 输入文本或文本列表 (字符串或字符串数组)
  • model (可选): 模型名称，默认 "paraphrase-multilingual-MiniLM-L12-v2"
  • encoding_format (可选): 编码格式 ("float", "base64")
  • normalize_embeddings (可选): 是否归一化向量 (默认 false)

响应示例:

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "embedding": [0.1, 0.2, 0.3, ...],
      "index": 0
    }
  ],
  "model": "paraphrase-multilingual-MiniLM-L12-v2",
  "usage": {
    "prompt_tokens": 7,
    "total_tokens": 7
  }
}

2. 批量文本嵌入

端点: POST /v1/embeddings

请求格式:

curl -X POST "http://localhost:8003/v1/embeddings" \
  -H "Content-Type: application/json" \
  -d '{
    "input": [
      "First text",
      "Second text",
      "Third text"
    ],
    "model": "paraphrase-multilingual-MiniLM-L12-v2"
  }'

3. 文本相似度计算

端点: POST /v1/similarity

请求格式:

curl -X POST "http://localhost:8003/v1/similarity" \
  -H "Content-Type: application/json" \
  -d '{
    "texts": [
      "First text",
      "Second text"
    ],
    "model": "paraphrase-multilingual-MiniLM-L12-v2"
  }'

响应示例:

{
  "similarity": 0.85,
  "embeddings": [
    [0.1, 0.2, ...],
    [0.15, 0.18, ...]
  ]
}

4. Pipeline 文本相似度计算

端点: POST /pipeline/sentence-similarity

请求格式:

curl -X POST "http://localhost:8003/pipeline/sentence-similarity" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "source_sentence": "That is a happy person",
      "sentences": [
        "That is a happy dog",
        "That is a very happy person",
        "Today is a sunny day"
      ]
    }
  }'

响应示例:

[
  0.65,
  0.89,
  0.2
]

5. 语义搜索

端点: POST /v1/search

请求格式:

curl -X POST "http://localhost:8003/v1/search" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "search query",
    "documents": [
      "Document 1",
      "Document 2",
      "Document 3"
    ],
    "top_k": 3,
    "model": "paraphrase-multilingual-MiniLM-L12-v2"
  }'

响应示例:

{
  "results": [
    {
      "document": "Document 1",
      "score": 0.92,
      "index": 0
    },
    {
      "document": "Document 2",
      "score": 0.78,
      "index": 1
    }
  ]
}

6. 健康检查

端点: GET /health

响应示例:

{
  "status": "healthy",
  "model_loaded": true,
  "npu_available": true,
  "version": "1.0.0",
  "model_info": {
    "name": "paraphrase-multilingual-MiniLM-L12-v2",
    "max_seq_length": 512,
    "embedding_dim": 384
  }
}

7. 指标监控

端点: GET /metrics

返回Prometheus格式的监控指标。

生产环境配置

1. 性能优化

# config/config.yaml
model:
  device: "npu"
  dtype: "float16"
  batch_size: 32
  max_seq_length: 512
  normalize_embeddings: false
  num_workers: 2

api:
  workers: 2
  max_concurrent_requests: 64
  timeout: 60
  max_request_size: 10MB
  enable_batch_processing: true

2. 资源限制

# Docker资源限制
--cpus="4"              # CPU核心数
--memory="8g"           # 内存限制
--device=/dev/davinci0  # NPU设备

3. 日志配置

# 日志级别: DEBUG, INFO, WARNING, ERROR
-e LOG_LEVEL=INFO

# 日志目录挂载
-v /data/logs/paraphrase-minilm:/app/logs

4. 模型缓存

# 模型目录挂载（加速启动）
-v /data/models/paraphrase-minilm:/app/models

性能指标

  • 延迟:
    • 单文本 (512 tokens): ~10-30ms (NPU加速)
    • 批量32条: ~50-150ms
  • 吞吐量:
    • 单卡: ~100-300 请求/秒 (单文本)
    • 批处理: ~500-1000 请求/秒
  • 并发: 建议每卡16-32并发请求
  • 内存占用: ~2-4GB (含模型)

使用示例

Python客户端示例

import requests
import numpy as np

# 文本嵌入
response = requests.post(
    "http://localhost:8003/v1/embeddings",
    json={
        "input": "Hello, world!",
        "model": "paraphrase-multilingual-MiniLM-L12-v2"
    }
)
embedding = response.json()["data"][0]["embedding"]

# 相似度计算
response = requests.post(
    "http://localhost:8003/v1/similarity",
    json={
        "texts": ["文本1", "文本2"],
        "model": "paraphrase-multilingual-MiniLM-L12-v2"
    }
)
similarity = response.json()["similarity"]

故障排查

1. NPU不可用

# 检查NPU状态
npu-smi info

# 检查设备映射
ls -l /dev/davinci*

# 检查CANN环境
source /usr/local/Ascend/ascend-toolkit/set_env.sh

2. 模型加载失败

# 检查模型文件
ls -lh /app/models/

# 检查磁盘空间
df -h

# 查看详细日志
docker logs paraphrase-minilm-api

3. 性能问题

# 检查NPU利用率
npu-smi info

# 调整批处理大小
# 修改 config/config.yaml 中的 batch_size

# 检查内存使用
docker stats paraphrase-minilm-api

4. 文本长度超限

# 检查输入文本长度
# 模型最大支持512 tokens，超长文本会被截断

# 查看警告日志
docker logs paraphrase-minilm-api | grep "truncated"

监控和告警

Prometheus指标

  • paraphrase_requests_total: 总请求数
  • paraphrase_request_duration_seconds: 请求耗时
  • paraphrase_text_length_tokens: 文本长度（tokens）
  • paraphrase_batch_size: 批处理大小
  • paraphrase_npu_utilization: NPU利用率
  • paraphrase_memory_usage_bytes: 内存使用量

健康检查脚本

#!/bin/bash
# scripts/health_check.sh
response=$(curl -s http://localhost:8003/health)
if [[ $response == *"healthy"* ]]; then
    echo "Service is healthy"
    exit 0
else
    echo "Service is unhealthy"
    exit 1
fi

升级和维护

更新模型

# 停止服务
docker stop paraphrase-minilm-api

# 更新模型文件
# 将新模型放置到 /data/models/paraphrase-minilm/

# 重启服务
docker start paraphrase-minilm-api

更新代码

# 重新构建镜像
docker build -t paraphrase-minilm-ascend:latest .

# 滚动更新（零停机）
docker stop paraphrase-minilm-api
docker rm paraphrase-minilm-api
docker run -d [原配置参数] paraphrase-minilm-ascend:latest

许可证

请遵守模型的原始许可证要求。该模型基于Apache 2.0许可证。

参考资源

  • 模型页面 (AtomGit)
  • HuggingFace模型页面
  • Sentence Transformers文档
  • 昇腾CANN开发指南
  • FastAPI文档

支持与反馈

如有问题或建议，请提交Issue或联系维护团队。