WeMM-Embedding 是腾讯微信视觉团队开源的通用多模态嵌入模型家族

WeMM-Embedding 是腾讯微信视觉团队开源的通用多模态嵌入模型家族。它最大的特点是能将文本、图像、视频和视觉文档统一编码到同一个向量空间，让您可以通过一个模型完成跨模态的检索、推荐和分类任务。该模型已在微信视频号、公众号等生产环境中大规模部署，每日调用量达十亿量级。

本教程将指导您完成从环境准备到生产部署的全过程。

1. 了解核心特性和模型选择

在部署前，先了解这个模型能做什么，以及如何根据您的需求选择合适的版本。

1.1 模型能做什么？

您可以将它理解为一个“超级编目员”：

输入：接受文字、图片、视频片段、扫描的PDF文档，甚至是图文混排的内容。
输出：将它们全部转换成一系列数字向量（Embedding）。向量之间的距离代表了内容在语义上的相似度。
应用：因此，它非常适合用于多模态搜索（用文字搜图/视频）、内容推荐、RAG（检索增强生成） 等场景。

1.2 选择合适的模型版本

模型版本	参数量	完整向量维度	推荐场景与硬件要求
WeMM-Embedding-2B	20亿	2048	轻量首选。模型权重约 4GB，适合消费级显卡（如8GB显存）或个人开发环境。
WeMM-Embedding-4B	40亿	2560	性能与资源的平衡选择。需要更高的GPU显存。
WeMM-Embedding-9B	90亿	4096	最高精度。模型权重约 18.8GB，需要 16-24GB 显存的GPU，适合对性能有极致要求的场景。

注意：所有模型目前均不支持音频输入。

2. 环境准备与安装

2.1 基础依赖

操作系统：Linux, macOS, Windows。
GPU：推荐使用NVIDIA GPU并安装CUDA，以获得最佳推理性能。
Python版本：3.8或更高。

2.2 克隆与安装

首先，克隆项目仓库并安装核心依赖。

git clone https://github.com/Tencent/WeMM-Embedding.git
cd WeMM-Embedding

# 安装核心依赖 (推荐使用虚拟环境)
pip install -r requirements.txt

关键说明: 官方明确指出，为保证推理结果和复现性，建议锁定 transformers==5.2.0 版本。更新版本可能在预处理行为上有差异，导致结果不一致。对于视频处理，还需安装 qwen-vl-utils[decord]==0.0.14 等依赖。

3. 快速推理：使用 Transformers 与 Sentence Transformers

官方提供了两种最直接的Python推理方式。

3.1 使用 Transformers 库（灵活控制）

这是最基础的方式，适合需要对处理流程进行精细控制的场景。

import torch
from qwen_vl_utils import process_vision_info
from transformers import AutoModel, AutoProcessor

# 1. 加载模型和处理器 (将模型ID替换为本地路径或 'tencent/WeMM-Embedding-2B')
model_id = "tencent/WeMM-Embedding-2B"
processor = AutoProcessor.from_pretrained(model_id, trust_remote_code=True)
model = AutoModel.from_pretrained(
    model_id, trust_remote_code=True, torch_dtype=torch.bfloat16
).cuda().eval()

# 2. 准备多模态输入
messages = [{
    "role": "user",
    "content": [
        {"type": "text", "text": "这是一段描述文本"},
        {"type": "image", "image": "/path/to/your/image.jpg"},
        # 视频按帧处理, 可指定帧数
        {"type": "video", "video": "/path/to/your/video.mp4", "nframes": 16},
    ]
}]

# 3. 处理输入并生成Embedding
text = processor.apply_chat_template(messages, tokenize=False, add_generation_prompt=False)
images, videos, video_kwargs = process_vision_info(
    messages, image_patch_size=16, return_video_kwargs=True, return_video_metadata=True
)

# ... (详细数据转换步骤参见官方示例) ...
inputs = processor(text=text, images=images, videos=videos, return_tensors="pt", **video_kwargs).to("cuda")

with torch.inference_mode():
    embedding = model.embedding(**inputs)  # 核心调用

print(embedding.shape)  # 输出向量维度

官方也提供了可直接运行的脚本 examples/transformers_inference.py。

3.2 使用 Sentence Transformers (更简洁)

这是更简洁、集成度更高的方式，如果您的任务主要是将文本、图片或视频编码为向量，推荐使用。

from sentence_transformers import SentenceTransformer

# 直接通过Hugging Face ID加载，模型会自动适配
model = SentenceTransformer("tencent/WeMM-Embedding-2B", trust_remote_code=True)

# 编码不同类型的内容
inputs = [
    "一只在沙滩上奔跑的狗",  # 纯文本
    {"image": "/path/to/dog.jpg", "text": "代表这张图片"},  # 图片加文本说明
    {"video": "/path/to/dog.mp4", "text": "代表这个视频"},  # 视频加文本说明
]

embeddings = model.encode(inputs, batch_size=1, normalize_embeddings=True)
print(embeddings.shape)

官方脚本 examples/sentence_transformers_inference.py 演示了完整用法。

3.3 核心技巧：Matryoshka 可变维度

WeMM-Embedding 支持 Matryoshka 嵌入，意味着您可以截取完整向量的前 d 维（例如从2048维截取256维），然后重新归一化。在性能几乎不损失的情况下（2B模型在256维时保留98.7%性能），大幅降低向量数据库的存储和检索成本。

1 2	d = 256 # 从模型支持的维度中选择: 64, 128, 256, ... reduced_embedding = torch.nn.functional.normalize(full_embedding[..., :d], dim=-1)

4. 生产级部署：使用 vLLM 或 SGLang

对于需要高并发、低延迟的生产环境，可以使用 vLLM 或 SGLang 框架将模型部署为服务。官方已验证 vLLM 0.27.0 和 SGLang 0.5.9 版本。

4.1 使用 vLLM 部署

# 设置模型路径
MODEL_PATH=/path/to/your/WeMM-Embedding-2B

# 启动vLLM服务，指定 pooling runner
vllm serve "$MODEL_PATH" \
  --runner pooling \
  --chat-template "$MODEL_PATH/embedding_chat_template.jinja"

4.2 使用 SGLang 部署

MODEL_PATH=/path/to/your/WeMM-Embedding-2B

# 需要先运行补丁脚本，解决视频处理兼容性
python scripts/patch_sglang_video.py

# 启动SGLang服务
python -m sglang.launch_server \
  --model-path "$MODEL_PATH" \
  --is-embedding \
  --enable-precise-embedding-interpolation

官方也准备了 scripts/serve_vllm.sh 和 scripts/serve_sglang.sh 一键脚本。

5. 评估与测试（可选）

如果需要在自己的数据集上复现官方的 MMEB-v3 基准测试结果，可以使用 mmeb_v3_eval/ 目录下的脚本。

cd mmeb_v3_eval

# 1. 下载测试数据
DATA_ROOT=/path/to/MMEB-V3 bash scripts/download_data.sh

# 2. 运行评估
MODEL_PATH=/path/to/WeMM-Embedding-2B \
DATA_BASEDIR=/path/to/MMEB-V3 \
OUTPUT_DIR=exps/wemm_embedding bash scripts/run_eval.sh

6. 常见问题与建议

锁死 transformers 版本：这是官方最强调的一点。在生产部署时，务必使用 transformers==5.2.0，以避免因新版本预处理逻辑变化导致的向量结果不一致问题。
视频处理的内存占用：处理视频时，显存占用会显著增加（例如抽取64帧）。官方评测中视频任务使用64帧采样，部署时请根据实际硬件能力调整 nframes 参数。
许可证：项目代码采用 Apache 2.0 许可证，允许商业使用。部分第三方组件保留其原始许可证。
硬件建议：
- 2B模型：是性价比最高的选择，消费级显卡（如RTX 3060 12GB）即可流畅运行。
- 9B模型：需要16-24GB显存，推荐使用 A10G、A100 等专业显卡。

通过以上步骤，您应该可以成功部署 WeMM-Embedding 模型。无论是用于快速原型验证，还是搭建生产级的跨模态检索系统，它都提供了从模型到工具链的完整支持。建议从 2B 版本开始尝试，熟悉流程后再根据业务需求选择更大模型或进行服务化部署。