Qwen3-VL-8B-embedding

Qwen3-VL-8B Embedding Model

提取自 Qwen3-VL-8B-Instruct 的轻量级多模态 embedding 模型，专为 RAG 和多模态检索场景设计。

Lightweight multimodal embedding model extracted from Qwen3-VL-8B-Instruct, designed for RAG and multimodal retrieval.

模型特点 | Features

• 🎯 轻量高效: 从 17GB 压缩到 4.5GB，保留核心编码能力
• 🖼️ 视觉编码: 1.1GB Vision Transformer (27层)，支持图像和视频
• 📝 文本编码: 3.4GB Text Encoder (前6层 Transformer + embedding)
• 🔄 统一维度: 文本和图像输出相同的 4096 维 embedding，可直接计算跨模态相似度
• ⚡ 快速推理: 相比完整模型，推理速度提升 3-4 倍

模型架构 | Architecture

Vision Encoder

• Layers: 27-layer Vision Transformer
• Hidden Size: 1152
• Output Dim: 4096
• Supports: Images and videos

Text Encoder

• Layers: 6-layer Transformer (from Qwen3)
• Hidden Size: 4096
• Vocab Size: 151,936
• Attention: Grouped Query Attention (32 Q-heads, 8 KV-heads)
• Features: QK-Norm, RoPE positional encoding

快速开始 | Quick Start

安装依赖 | Installation

pip install torch transformers safetensors pillow

加载模型 | Load Model

import sys
from pathlib import Path

# 将模型目录添加到路径
sys.path.insert(0, '.')

from qwen3vl_embedding import load_embedding_model
from transformers import AutoTokenizer

# 加载模型
model = load_embedding_model('.', device='cuda')

# 加载 tokenizer（需要从原始 Qwen3-VL 模型下载）
tokenizer = AutoTokenizer.from_pretrained(
    'Qwen/Qwen3-VL-8B-Instruct',
    trust_remote_code=True
)

文本编码 | Text Encoding

# 单个文本
text = "机器学习是人工智能的重要分支"
embedding = model.encode_text(text, tokenizer, normalize=True)
print(embedding.shape)  # torch.Size([1, 4096])

# 批量文本
texts = ["你好世界", "Hello world", "深度学习"]
embeddings = model.encode_text(texts, tokenizer, normalize=True)

# 计算相似度
import torch
similarity = torch.mm(embeddings, embeddings.T)
print(similarity)

图像编码 | Image Encoding

from PIL import Image

# 单张图片
image = Image.open("example.jpg")
embedding = model.encode_image(image, normalize=True)

# 批量图片
images = ["image1.jpg", "image2.jpg", "image3.jpg"]
embeddings = model.encode_image(images, normalize=True)

# 支持 URL
image_url = "https://example.com/image.jpg"
embedding = model.encode_image(image_url, normalize=True)

视频编码 | Video Encoding

# 视频自动抽帧编码
video_path = "example.mp4"
embedding = model.encode_video(
    video_path,
    fps=2.0,           # 每秒采样帧数
    max_frames=32,     # 最大帧数
    normalize=True
)

跨模态检索 | Cross-Modal Retrieval

# 文本查询图像
query_text = "一只可爱的猫"
query_emb = model.encode_text(query_text, tokenizer, normalize=True)

image_paths = ["cat1.jpg", "dog1.jpg", "cat2.jpg"]
image_embs = model.encode_image(image_paths, normalize=True)

# 计算相似度并排序
scores = torch.mm(query_emb, image_embs.T)[0]
for img, score in sorted(zip(image_paths, scores), key=lambda x: x[1], reverse=True):
    print(f"{img}: {score:.4f}")

使用场景 | Use Cases

• 📚 多模态 RAG: 文本-图像混合检索
• 🔍 语义搜索: 高质量文本/图像相似度计算
• 🎨 图像检索: 以文搜图、以图搜图
• 📹 视频理解: 视频内容编码与检索
• 🏷️ 零样本分类: 基于 embedding 的分类任务

性能对比 | Performance

测试环境: NVIDIA A100, batch_size=8

API 参数 | API Parameters

encode_text()

• text: 单个文本或文本列表
• tokenizer: HuggingFace tokenizer
• normalize: 是否 L2 归一化 (默认 True)
• pooling: 池化策略 - "mean" (默认), "first", "last"
• max_length: 最大序列长度 (默认 512)

encode_image()

• image: 图像路径、URL 或 PIL.Image 对象
• normalize: 是否 L2 归一化 (默认 True)
• pooling: 池化策略 - "mean" (默认), "first", "last", "none"

encode_video()

• video_path: 视频文件路径
• fps: 采样帧率 (默认 2.0)
• max_frames: 最大帧数 (默认 32)
• normalize: 是否 L2 归一化 (默认 True)
• pooling: 池化策略 - "mean" (默认), "first", "last"

模型文件 | Model Files

.
├── vision_encoder.safetensors      # 1.1GB - 视觉编码器权重
├── text_encoder.safetensors        # 3.4GB - 文本编码器权重
├── embedding_config.json           # 模型配置
├── qwen3vl_embedding.py           # 主模型代码
├── text_encoder.py                # 文本编码器实现
├── vision_process.py              # 视觉预处理
└── weight_index.json              # 权重索引

技术细节 | Technical Details

提取方法

从 Qwen3-VL-8B-Instruct 中提取：

• 完整的 27 层 Vision Transformer
• 词嵌入层 (151,936 vocab)
• 前 6 层 Text Transformer
• 最终 LayerNorm

为什么只用前 6 层？

实验表明，前 6 层已经能够捕获丰富的语义信息，适合 embedding 任务。更深的层主要用于生成任务，对检索任务贡献有限。

维度对齐

视觉编码器通过 PatchMerger 将 1152 维投影到 4096 维，与文本编码器输出对齐，实现真正的跨模态检索。

限制 | Limitations

• 仅支持编码任务，不支持生成
• 文本编码质量略低于完整模型（使用前 6 层）
• 视频处理需要足够的 GPU 内存

引用 | Citation

如果使用本模型，请引用原始 Qwen3-VL 论文：

@article{qwen3vl,
  title={Qwen3-VL: Towards Versatile Vision-Language Understanding},
  author={Qwen Team},
  year={2024}
}

许可证 | License

本模型遵循 Apache 2.0 许可证，与原始 Qwen3-VL 模型保持一致。

相关链接 | Links

• 🤗 原始模型 Qwen3-VL-8B-Instruct
• 📖 详细文档
• 🐛 问题反馈

更新日志 | Changelog

v1.0.0 (2024-03)

• 初始版本发布
• 支持文本、图像、视频编码
• 统一 4096 维输出