MIS-TEI 是华为推出的基于昇腾 AI 处理器的文本嵌入推理（Text Embeddings Inference）解决方案，专为 Embedding 和 Reranker 类模型优化。它支持容器化快速部署、动态批处理和硬件加速，广泛应用于检索增强生成（RAG）、语义搜索等场景，是昇腾设备上部署文本嵌入模型的主流方案之一。

一、环境要求

1.1 硬件要求

  • NPU 设备：昇腾系列 AI 处理器，常见型号包括：
    • Atlas 300I / 310P（对应镜像 TAG：300I-Duo）
    • Atlas 800I A2 910B（对应镜像 TAG：800I-A2）
    • Atlas 800I A3 910C（对应镜像 TAG：800I-A3）
  • 系统架构：aarch64（ARM64）架构

1.2 软件要求

  • 操作系统：银河麒麟 aarch64、Ubuntu 20.04/22.04 等 Linux 发行版
  • 驱动与 CANN：昇腾配套驱动及 CANN 7.1 及以上版本
  • 容器环境：Docker（已正确安装并启动）

二、前置环境校验

2.1 检查 NPU 设备状态

npu-smi info

正常输出会显示 NPU 设备型号、算力、显存、温度等信息。若提示无设备，请重新安装昇腾驱动与 CANN 套件。

💡 小技巧：安装驱动后建议重启系统，避免某些内核模块加载不全的问题。

2.2 校验 Docker 环境

docker --version
systemctl status docker

确保 Docker 已正常启动。

三、获取 MIS-TEI 镜像

3.1 获取镜像的两种方式

方式一：直接拉取（服务器可访问互联网）

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

硬件平台 镜像地址
Atlas 300I / 310P swr.cn-south-1.myhuaweicloud.com/ascendhub/mis-tei:7.3.0-300I-Duo-aarch64
Atlas 800I A2 910B swr.cn-south-1.myhuaweicloud.com/ascendhub/mis-tei:7.3.0-800I-A2-aarch64
Atlas 800I A3 910C swr.cn-south-1.myhuaweicloud.com/ascendhub/mis-tei:7.3.0-800I-A3-aarch64

注意：部分镜像可能需要提前在昇腾社区申请下载权限。推荐使用华为云公共镜像仓库版本，部分版本无需企业权限申请，可直接拉取。

方式二：离线加载（服务器无法访问互联网）

  1. 在可访问互联网的机器上下载镜像：
docker pull --output "/path/to/mis-tei_image.tar" swr.cn-south-1.myhuaweicloud.com/ascendhub/mis-tei:7.3.0-300I-Duo-aarch64
  1. 将镜像文件上传至目标服务器
  2. 在目标服务器上加载镜像：
docker load -i mis-tei_image.tar

3.2 GPUStack 社区镜像（推荐）

社区对官方镜像进行了重打包与优化，简化了启动脚本和参数配置：

硬件平台 社区镜像地址
Atlas 300I / 310P swr.cn-south-1.myhuaweicloud.com/gpustackcommunity/mis-tei:7.3.0-300I-Duo-aarch64
Atlas 800I A2 910B swr.cn-south-1.myhuaweicloud.com/gpustackcommunity/mis-tei:7.3.0-800I-A2-aarch64
Atlas 800I A3 910C swr.cn-south-1.myhuaweicloud.com/gpustackcommunity/mis-tei:7.3.0-800I-A3-aarch64

社区版本相比官方镜像的主要优化：

  • ✅ 简化启动脚本，优化默认参数配置
  • ✅ 支持任意参数透传，增强灵活性
  • ✅ 开箱即用接入 GPUStack，降低使用门槛

拉取完成后确认镜像存在：

docker images | grep mis-tei

四、准备模型权重

建议提前下载模型权重到本地，避免容器运行时在线拉取超时。

4.1 创建模型存放目录

mkdir -p /home/model_path/bge-m3

4.2 下载模型

以 BGE-M3 为例，可从 Hugging Face 镜像站下载：

# 下载地址：https://hf-mirror.com/BAAI/bge-m3/tree/main

其他常用模型：

  • 向量化模型（Embedding） ：
    • BAAI/bge-m3（多语言通用嵌入模型）
    • nlp_gte_sentence-embedding_chinese-base
    • bge-large-zh-v1.5
  • 重排序模型（Reranker） ：
    • bce-reranker-base_v1
    • BAAI/bge-reranker-v2-m3
  • Qwen3-Reranker 系列：Qwen3-Reranker-0.6B / 4B / 8B

五、启动容器

5.1 基础启动命令

docker run -u root -e ASCEND_VISIBLE_DEVICES=4 \
    -itd --name=bge-m3 --net=host \
    -e HOME=/home/HwHiAiUser \
    --privileged=true \
    -v /home/BAAI/:/home/HwHiAiUser/model \
    -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
    -v /usr/local/Ascend/driver:/usr/local/Ascend/driver \
    --entrypoint /home/HwHiAiUser/start.sh \
    mis-tei:7.3.0-300I-Duo-aarch64 \
    BAAI/bge-m3 127.0.0.1 8086

5.2 参数说明

参数 说明
-u root 以 root 用户运行，避免设备访问权限问题
-e ASCEND_VISIBLE_DEVICES=4 指定使用的 NPU 设备编号
--net=host 使用主机网络模式
--privileged=true 赋予容器特权模式，确保设备访问权限
-v 挂载模型目录和驱动目录
--entrypoint 指定容器入口脚本
末尾三个参数 <model_id> <listen_ip> <listen_port>

注意：镜像的入口脚本（如 start.sh）期望在命令末尾接收 model_id、listen_ip、listen_port 三个参数，缺失或格式错误会提示 Need param: <model_id> <listen_ip> <listen_port>。

5.3 使用 docker-compose 启动（推荐）

创建 docker-compose.yml 文件：

version: '3'
services:
  mis-tei:
    image: swr.cn-south-1.myhuaweicloud.com/ascendhub/mis-tei:7.3.0-300I-Duo-aarch64
    container_name: bge-m3
    user: root
    network_mode: host
    privileged: true
    environment:
      - ASCEND_VISIBLE_DEVICES=4
      - HOME=/home/HwHiAiUser
    volumes:
      - /home/BAAI/:/home/HwHiAiUser/model
      - /usr/local/bin/npu-smi:/usr/local/bin/npu-smi
      - /usr/local/Ascend/driver:/usr/local/Ascend/driver
    entrypoint: /home/HwHiAiUser/start.sh
    command: ["BAAI/bge-m3", "127.0.0.1", "8086"]

启动：

docker-compose up -d

5.4 更完整的启动方式（手动控制）

如需在容器内手动启动服务，可先以 bash 方式进入容器：

docker run -it -d --net=host --shm-size=2g \
    --privileged \
    --name <container-name> \
    --device=/dev/davinci_manager \
    --device=/dev/hisi_hdc \
    --device=/dev/devmm_svm \
    -v /usr/local/Ascend/driver:/usr/local/Ascend/driver:ro \
    -v /usr/local/sbin:/usr/local/sbin:ro \
    -v <path-to-model>:<path-to-model> \
    --entrypoint bash \
    <image-id>

进入容器后手动启动服务：

docker exec -it <container-name> bash
# 在容器内执行启动脚本
./start.sh <model_id> <listen_ip> <listen_port>

5.5 环境变量配置

MIS-TEI 支持通过环境变量切换运行配置：

环境变量 说明
MIS_CONFIG 切换推理执行后端、量化模型配置、性能倾向（高吞吐/低时延/均衡）
LOCAL_CACHE_PATH 设置模型权重本地缓存路径
ENABLE_BOOST 启用性能加速（如 "True"）
AUTO_TRUNCATE 自动截断超长文本（如 "true"）

六、验证部署

6.1 检查容器状态

docker ps | grep <container-name>
docker logs <container-name>  # 查看启动日志

6.2 测试 Embedding 接口（单文本）

curl http://127.0.0.1:8086/v1/embeddings \
    -H "Content-Type: application/json" \
    -d '{
        "input": "test text",
        "model": "bge-m3"
    }'

6.3 批量文本嵌入测试

curl http://127.0.0.1:8086/v1/embeddings \
    -H "Content-Type: application/json" \
    -d '{
        "input": ["text1", "text2", "text3"],
        "model": "bge-m3"
    }'

6.4 Python 代码调用测试

import requests

url = "http://127.0.0.1:8086/v1/embeddings"
payload = {
    "input": "测试文本",
    "model": "bge-m3"
}
response = requests.post(url, json=payload)
print(response.json())

6.5 健康检查

curl http://127.0.0.1:8086/health

6.6 检查 NPU 使用情况

npu-smi info

七、常见问题与排查

7.1 容器启动后立即退出

  • 原因：启动命令末尾缺少三个必需参数（model_id、listen_ip、listen_port）
  • 解决方案：确保在镜像名称后面完整跟上三个参数

7.2 容器内无法看到 NPU 设备

  • 原因：容器未以 root 用户启动，或设备被其他容器独占
  • 解决方案：在 docker run 命令中添加 -u root 参数，并确保 ASCEND_VISIBLE_DEVICES 指定的设备未被占用

7.3 接口调用超时/无响应

  • 原因：模型加载耗时过长，或端口未正确暴露
  • 解决方案：
    • 查看容器日志确认模型是否加载完成：docker logs <container-name>
    • 确保使用 --net=host 或正确映射端口 -p <host_port>:<container_port>
    • 启动时将 listen_ip 从 127.0.0.1 改为 0.0.0.0 或本机 IP

7.4 模型加载报错

  • 原因：模型权重未正确下载或路径挂载错误
  • 解决方案：
    • 确认模型权重已正确下载并挂载到容器内
    • 检查容器内模型路径是否与启动脚本中的 MODEL_DIR 配置一致
    • 确认镜像版本支持该模型

7.5 外部无法访问服务

  • 原因：网络配置问题
  • 解决方案：
    • 检查容器是否使用 --net=host 模式
    • 如使用桥接网络，需正确映射端口 -p <host_port>:<container_port>
    • 检查宿主机防火墙是否放行对应端口

7.6 模型精度验证

部署完成后，建议对模型输出进行精度验证，确保与官方结果一致。可使用标准测试集对比 Embedding 向量的余弦相似度或 Reranker 的排序结果。

八、性能优化建议

8.1 硬件层面

  • 根据实际负载选择合适的 NPU 设备型号（310P 适合低功耗推理，800I 系列适合高吞吐场景）
  • 合理分配 NPU 设备：通过 ASCEND_VISIBLE_DEVICES 指定设备，避免多服务争抢资源

8.2 软件层面

  • 开启性能加速：设置环境变量 ENABLE_BOOST="True"
  • 启用自动截断：设置 AUTO_TRUNCATE="true" 避免超长文本处理异常
  • 通过 MIS_CONFIG 切换性能倾向（高吞吐/低时延/均衡）
  • 使用共享内存：--shm-size=2g 或更大值提升数据处理效率

8.3 部署层面

  • 使用 docker-compose 管理容器，便于配置维护和重启
  • 模型权重放置于高速存储（如 SSD）以缩短加载时间
  • 对于生产环境，建议配置 Prometheus 监控服务状态

九、与 Dify / GPUStack 集成

MIS-TEI 提供兼容 Hugging Face TEI 和 OpenAI 标准的 API 接口，可方便地集成到 Dify、GPUStack 等平台中。

9.1 GPUStack 集成

  1. 进入 推理后端 页面
  2. 点击右上角 添加后端 → 自定义
  3. 按如下 YAML 配置填写参数：
backend_name: mis-tei-custom
health_check_path: /health
default_run_command: --model-id {{model_path}} -p {{port}}
default_env:
  ENABLE_BOOST: "True"
  AUTO_TRUNCATE: "true"
version_configs:
  7.3.0-310p:
    image_name: swr.cn-south-1.myhuaweicloud.com/gpustackcommunity/mis-tei:7.3.0-300I-Duo-aarch64
    custom_framework: cann

⚠️ 注意：镜像需根据昇腾设备型号选择对应的 TAG。

9.2 Dify 集成

在 Dify 中配置 Embedding 或 Reranker 模型时，将 API 地址指向 MIS-TEI 服务地址（如 http://127.0.0.1:8086），选择兼容的模型名称即可。

参考资源

  • MIS-TEI 官方镜像页面：https://www.hiascend.com/developer/ascendhub/detail/07a016975cc341f3a5ae131f2b52399d
  • 昇腾推理微服务 MIS 技术文章：https://www.hiascend.com/developer/techArticles/20250619-1
  • GPUStack 社区后端仓库：https://github.com/gpustack/community-inference-backends/tree/main/mis-tei
  • BGE-M3 模型下载：https://hf-mirror.com/BAAI/bge-m3/tree/main
# 人工智能 # python # 自然语言处理
Logo
鲲鹏昇腾开发者社区是面向全社会开放的“联接全球计算开发者，聚合华为+生态”的社区，内容涵盖鲲鹏、昇腾资源，帮助开发者快速获取所需的知识、经验、软件、工具、算力，支撑开发者易学、好用、成功，成为核心开发者。

鲲鹏昇腾开发者社区是面向全社会开放的“联接全球计算开发者，聚合华为+生态”的社区，内容涵盖鲲鹏、昇腾资源，帮助开发者快速获取所需的知识、经验、软件、工具、算力，支撑开发者易学、好用、成功，成为核心开发者。

更多推荐

cover

工控机厂商能力分层拆解：从L1参数级到L2软硬一体的五家选型参考

avatar 鲲鹏昇腾开发者社区
cover

华为ICT学院昇腾开发者高校训练营暨CANN启航营在兰州大学开营

avatar 鲲鹏昇腾开发者社区
cover

华为ICT学院昇腾开发者高校训练营暨CANN启航营在兰州大学开营

avatar 鲲鹏昇腾开发者社区