matchanything_eloftr Ascend NPU 部署指南

项目简介

matchanything_eloftr 是基于 EfficientLoFTR 的关键点匹配模型，能够在两张图像之间进行特征点匹配。该模型使用 Transformer 架构实现高效的特征匹配，适用于视觉定位、图像配准、3D 重建等任务。

特性

支持 Ascend NPU 推理加速
CPU vs NPU 精度对比测试 (误差 < 1%)
关键点匹配 (Keypoint Matching)
兼容 HuggingFace transformers
482.18x 加速比

环境要求

硬件: 华为 Ascend 910 系列 NPU
CANN: 8.0.RC1 或更高版本
PyTorch: 2.0+ with torch_npu
transformers: 4.56+
Pillow, numpy

目录结构

matchanything_eloftr-ascend/
├── inference.py          # 推理测试脚本
├── test.log              # 测试日志
├── README.md             # 本文档

部署步骤

1. 设置环境变量

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

2. 准备模型文件

模型文件位于 /opt/atomgit/mxy/matchanything_eloftr/zju-community/matchanything_eloftr/ 目录下：

model.safetensors - 模型权重 (约 64MB)
config.json - 模型配置
preprocessor_config.json - 图像预处理配置

3. 安装依赖

pip install transformers torch_npu pillow numpy

使用方式

方式一：普通推理模式

运行推理脚本进行关键点匹配：

cd /opt/atomgit/mxy/matchanything_eloftr-ascend/

python3 inference.py

python3 inference.py --mode inference

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

运行精度对比测试：

cd /opt/atomgit/mxy/matchanything_eloftr-ascend/

python3 inference.py --mode precision_test

命令行参数说明

参数	说明	默认值
`--mode`	测试模式: all, inference 或 precision_test	`all`

测试验证

精度测试结果

指标	实测值	阈值	状态
最大相对误差	~0%	< 1.00%	PASS
CPU 推理时间	84.239s	-	-
NPU 推理时间	0.175s	-	-
加速比	482.18x	> 1x	PASS

推理结果示例

输入: 两张图像 (640x480)

输出:

关键点坐标: torch.Size([1, 2, 10816, 2])
匹配结果: EfficientLoFTRKeypointMatchingOutput

Python API 使用示例

基本推理

import torch
from PIL import Image
from transformers import AutoImageProcessor, EfficientLoFTRForKeypointMatching

MODEL_DIR = "/opt/atomgit/mxy/matchanything_eloftr/zju-community/matchanything_eloftr"

processor = AutoImageProcessor.from_pretrained(MODEL_DIR)
model = EfficientLoFTRForKeypointMatching.from_pretrained(MODEL_DIR)
model = model.to("npu:0").eval()

image1 = Image.open("image1.jpg").convert("RGB")
image2 = Image.open("image2.jpg").convert("RGB")

inputs = processor(images=[image1, image2], return_tensors="pt")
inputs = {k: v.to("npu:0") for k, v in inputs.items()}

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

keypoints0 = outputs.keypoints[0]
keypoints1 = outputs.keypoints[1]
print(f"Keypoints image 0: {keypoints0.shape}")
print(f"Keypoints image 1: {keypoints1.shape}")

模型结构

架构类型: EfficientLoFTR (Efficient Local Feature Transformer)
特征提取: 4 阶段 CNN
Transformer: 4 层注意力
隐藏层维度: 256
输出: 关键点坐标

组件	说明
backbone	多阶段特征提取 CNN
transformer	4层Transformer编码器
head	关键点预测头

推理参数配置

从 config.json 提取的关键参数:

{
  "hidden_size": 256,
  "num_attention_heads": 8,
  "num_attention_layers": 4,
  "intermediate_size": 512,
  "image_size": [832, 832]
}

常见问题

Q: 精度测试失败?

A: 检查 NPU 驱动是否正确安装。LoFTR 模型在 CPU 和 NPU 上应保持数值一致。

Q: 如何提高推理速度?

A: NPU 相比 CPU 有极其显著的加速（482x），特别适合实时匹配场景。

Q: 输入图像尺寸有限制吗?

A: 模型会将输入图像 resize 到 832x832 进行处理。

参考链接

原始模型: https://huggingface.co/zju-community/matchanything_eloftr
EfficientLoFTR 论文: https://arxiv.org/abs/2111.12011
HuggingFace Transformers: https://huggingface.co/transformers

许可证

本项目遵循 Apache-2.0 许可证