3131 字
16 分钟
Qwen3-VL-Embedding 解析

📖 项目概述#

Qwen3-VL-EmbeddingQwen3-VL-Reranker 是阿里巴巴通义团队基于 Qwen3-VL 视觉语言模型开发的多模态嵌入和重排序模型系列。

核心能力#

特性说明
🎨 多模态支持文本、图像、截图、视频及混合模态输入
🔄 统一表示空间不同模态映射到统一的语义向量空间
🎯 高精度重排通过交叉注意力实现精细的相关性评分
🌍 多语言支持支持 30+ 种语言
📏 灵活向量维度支持 Matryoshka Representation Learning (MRL)

🔄 项目整体流程#

下图展示了 Qwen3-VL-Embedding 项目的整体流程框架,从环境准备到最终结果输出,分为四个核心阶段:

千问3整体流程

流程说明#

整个系统分为 四个核心阶段

  1. 阶段 1:环境准备 - 安装依赖、下载模型、配置环境
  2. 阶段 2:离线索引 - 数据预处理、Embedding生成、向量入库
  3. 阶段 3:在线查询 - 查询向量生成、向量召回、Reranker精排
  4. 阶段 4:结果输出 - 排序文档、相关性分数、来源追溯

⚙️ 阶段 1:环境准备#

在开始使用 Qwen3-VL-Embedding 之前,需要确保系统满足以下要求并正确配置环境。

千问3环境配置

系统要求#

项目最低要求推荐配置
操作系统Linux / Windows / macOSUbuntu 20.04+ / Windows 11
Python 版本Python ≥ 3.11Python 3.11.x
GPUNVIDIA GPU (8GB+ 显存)RTX 4090 (24GB) 或 A100
CUDACUDA 11.8+CUDA 12.1+
磁盘空间20GB+50GB+ (含模型)
内存16GB RAM32GB+ RAM

核心依赖说明#

依赖包版本作用必需?
torch2.8.*深度学习框架核心✅ 必需
transformers≥4.57.3加载 Qwen3-VL 模型✅ 必需
qwen-vl-utils≥0.0.14图像/视频预处理工具✅ 必需
accelerate≥1.12.0分布式推理加速✅ 必需
decord≥0.6.0高效视频解码✅ 必需
flash-attn最新注意力加速 (2倍速)⭐ 推荐

安装步骤#

Terminal window
# 1. 克隆项目
git clone https://github.com/QwenLM/Qwen3-VL-Embedding.git
cd Qwen3-VL-Embedding
# 2. 运行安装脚本 (Linux/Mac)
bash scripts/setup_environment.sh
# 3. 激活环境
source .venv/bin/activate
# 4. 下载模型 (国内推荐使用 ModelScope)
pip install modelscope
modelscope download --model qwen/Qwen3-VL-Embedding-2B --local_dir ./models/Qwen3-VL-Embedding-2B

📂 支持的文件类型#

系统支持多种文件类型的处理,实现真正的多模态检索能力。

千问3支持文件类型

文件类型详解#

支持的文件类型文件扩展名处理方式
文本文档.txt, .md, .json直接读取文本
PDF 文档.pdf提取文本 + 截图页面
图片文件.jpg, .png, .webp直接作为图像输入
视频文件.mp4, .avi, .mov提取关键帧 (最多64帧)
网页文件.html解析提取正文内容

📊 阶段 2:离线索引#

离线索引阶段是将原始文档、图片、视频转化为向量并存储到向量数据库的过程。

离线索引流程

离线索引五步流程#

离线索引包含以下五个核心步骤:

步骤名称说明输出
2.1数据收集遍历文件目录,收集待处理文件文件列表
2.2内容解析根据文件类型解析内容标准化内容
2.3内容分块将长内容切分为小块文档块列表
2.4Embedding生成AI生成向量表示[B, 2048] 向量
2.5向量入库存入向量数据库持久化索引

步骤 2.2:内容解析#

系统根据不同的文件类型采用不同的解析策略:

千问3内容解析

各类型解析详解#

文件类型解析工具输出内容注意事项
PDFPyMuPDF (fitz)每页文本 + 页面图片表格/公式可能需要 OCR
图片PIL.ImageRGB 图像对象自动调整尺寸 ≤ 1280×1440
视频Decord帧序列 (fps=1, 最多64帧)长视频需要降采样
文本open()UTF-8 字符串注意编码问题

步骤 2.3:内容分块#

长文档需要切分成小块,每块保持语义完整,方便后续检索。

千问3内容分块

分块策略对比#

策略优势劣势适用场景
固定长度分块实现简单可能在句子中间切断快速原型
语义分块保持语义完整实现复杂技术文档、章节划分
滑动窗口分块有重叠,不漏信息数据量增加对准确性要求高的场景

分块参数建议#

内容类型推荐块大小重叠大小说明
技术文档512 tokens50 tokens段落/小节为单位
新闻文章256 tokens30 tokens较短,快速检索
法律合同1024 tokens100 tokens保持条款完整
图片文档1 页 = 1 块每页作为一个文档

步骤 2.4:Embedding 生成#

这是离线索引中最核心的步骤,使用 Qwen3-VL-Embedding 模型将文档块转换为 2048 维向量。

千问3Embedding生成

Embedding 生成流程概览#

Embedding 生成将多模态内容(文本+图片+视频)转换为统一的向量表示,使得不同类型的内容可以在同一个语义空间中进行比较。


Embedding 模型处理流程详解#

下图展示了 Embedding 模型内部的详细处理流程,从输入到输出的完整数据变换过程:

千问3Embedding模型处理流程

模型内部五步流程#

基于源代码 src/models/qwen3_vl_embedding.py,模型内部经过以下 5 个核心步骤:

步骤函数名称作用输出
1format_model_input()构造对话格式List[Dict] 对话
2_preprocess_inputs()Tokenize + 图像预处理Tensor Dict
3model.forward()Transformer 编码hidden_states [B,L,D]
4_pooling_last()EOS Pooling 提取[B, D] 向量
5F.normalize()L2 归一化单位向量

EOS Pooling 原理#

Token序列: [BOS] [产] [品] [介] [绍] [IMG] [IMG] ... [EOS] [PAD] [PAD]
attention: 1 1 1 1 1 1 1 ... 1 0 0
提取这个位置的向量 [D]
为什么用 EOS?
├─ EOS token 通过因果注意力"看过"整个序列的所有信息
└─ 是对整个输入的最佳压缩表示

关键代码实现#

def _pooling_last(hidden_state, attention_mask):
# 翻转 mask,找到最后一个 1 的位置 (EOS 位置)
flipped = attention_mask.flip(dims=[1])
last_pos = attention_mask.shape[1] - flipped.argmax(dim=1) - 1
row = torch.arange(hidden_state.shape[0])
return hidden_state[row, last_pos] # 取出 EOS 向量

步骤 2.5:向量入库#

将生成的向量和元数据存储到向量数据库,建立索引以便快速搜索。

千问3向量入库流程

支持的向量数据库#

数据库优势适用场景部署难度
Milvus功能全面,大规模支持生产环境、10亿+ 向量⭐⭐⭐
Qdrant易用,Rust 高性能中小规模、快速上手⭐⭐
Faiss纯 Python,无服务依赖本地开发、PoC 验证
Chroma最简单,内嵌式快速原型、学习测试

索引类型说明#

索引类型说明召回率速度适用场景
FLAT暴力搜索,无压缩100%小数据集 (<10万)
IVF_FLAT倒排索引~95%中等数据集
HNSW图索引 (推荐)~98%大数据集、实时搜索

🔍 阶段 3:在线查询#

在线查询阶段处理用户实时输入(文字/图片/视频),快速找出最相关的结果返回给用户。

千问3在线查询流程

在线查询五步流程#

步骤名称说明耗时
3.1接收查询解析用户输入即时
3.2查询向量生成Embedder 生成向量~50-100ms
3.3向量召回ANN 搜索 Top-100~10-50ms
3.4Reranker精排深度交互打分~30-50ms/对
3.5结果组装排序+元数据返回即时

🎯 完整多模态知识库流程#

下图展示了从知识库构建到查询的完整流程:

千问3多模态知识库构建和查询流程

RAG 系统完整流程#

┌───────────────────┐ ┌───────────────────┐ ┌───────────────────┐ ┌───────────────────┐
│ 阶段1: 召回 │ │ 阶段2: 精排 │ │ 阶段3: 上下文 │ │ 阶段4: 生成 │
│ │ │ │ │ │ │ │
│ Embedding │───▶│ Reranker │───▶│ Context │───▶│ Qwen3-VL │
│ 向量检索 │ │ 重排序 │ │ 构建 │ │ 生成回答 │
│ │ │ │ │ │ │ │
│ → Top-100 │ │ → Top-10 │ │ → Prompt组装 │ │ → 最终回答 │
└───────────────────┘ └───────────────────┘ └───────────────────┘ └───────────────────┘

📝 在线查询详细步骤#

步骤 3.1:接收查询#

系统支持多种查询类型,解析用户输入:

在线查询接受查询

支持的查询类型#

查询类型示例说明
纯文本查询”如何配置网络设置?“最常见,用文字搜内容
图片查询用户上传商品图片以图搜图,找相似商品
视频查询上传视频片段找相关视频内容
混合查询图片 + “找蓝色款式”图文组合,精确检索

步骤 3.2:查询向量生成#

用 Embedding 模型把用户查询转成向量,与索引阶段使用的是同一个模型

查询向量生成

代码示例#

# 生成查询向量
query = {"text": "如何配置网络设置?", "instruction": "检索产品文档"}
query_embedding = embedder.process([query], normalize=True)
# 输出: [1, 2048] 的归一化向量

⚠️ 重要: 查询和文档必须用同一个 Embedding 模型,否则向量空间不一致,无法比较!


步骤 3.3:向量召回#

在向量数据库中进行 ANN (近似最近邻) 搜索,快速返回 Top-K 相似候选:

向量召回

召回参数配置#

参数推荐值说明
top_k100召回数量,过大影响精排速度
ef_search128HNSW 搜索深度,越大越精确但更慢
distanceCOSINE距离度量,与归一化向量搭配

步骤 3.4:Reranker 精排#

用 Reranker 模型对每个 (Query, Document) 对进行深度交互打分,比向量召回更精准:

Reranker精排

Embedding vs Reranker 对比#

特性Embedding 召回 (双塔)Reranker 精排 (单塔)
架构独立编码交叉注意力
优势可预计算,毫秒级深度交互,更精准
劣势无交互,精度有限需逐对计算,较慢
适用百万级召回Top-20 精排

Reranker 内部处理流程#

下图详细展示了 Reranker 模型的内部工作原理:

Ranker内部处理流程

Reranker 打分原理#

Reranker 把问题转化为”判断文档是否满足查询需求”的二分类任务:

# 构造的 prompt 格式
{
"role": "system",
"content": "Judge whether the Document meets the requirements based on the
Query and the Instruct. Note that the answer can only be 'yes' or 'no'."
},
{
"role": "user",
"content": [
"<Instruct>: 检索相关产品文档",
"<Query>: 如何配置网络设置?",
"<Document>: 网络配置步骤:1. 打开设置面板..."
]
}

关键代码实现#

def get_binary_linear(self, model, token_yes, token_no):
lm_head_weights = model.lm_head.weight.data
weight_yes = lm_head_weights[token_yes] # "yes" token 的权重
weight_no = lm_head_weights[token_no] # "no" token 的权重
linear_layer = torch.nn.Linear(D, 1, bias=False)
linear_layer.weight[0] = weight_yes - weight_no # 差值作为分类权重
return linear_layer
def compute_scores(self, inputs):
hidden_state = self.model(**inputs).last_hidden_state[:, -1] # 取最后 token
scores = self.score_linear(hidden_state) # 线性变换
scores = torch.sigmoid(scores) # 归一化到 [0, 1]
return scores

为什么这样设计?

  • 利用模型预训练的 yes/no 语义知识
  • 只需一次前向传播,比生成更高效
  • 输出是连续分数,可排序

📊 性能对比#

性能对比

Embedding vs Reranker 性能对比#

指标Embedding 召回Reranker 精排
架构双塔 (独立编码)单塔 (交叉注意力)
延迟 (单条)50-100ms30-50ms/对
吞吐量可批处理,高需逐对,低
精度中等 (~80%)高 (~95%)
适用场景粗筛大规模候选精排少量候选
典型调用Top-100 候选Top-20 精排

与其他方案的对比#

方案模态支持视频支持中文能力开源模型规模
Qwen3-VL-Embedding文本+图像+视频✅ 64帧✅ 原生2B/8B
CLIP文本+图像0.4B
OpenAI Embedding仅文本未知
BGE-M3仅文本0.6B
VLM2Vec文本+图像⚠️ 有限⚠️ 弱2B

📤 阶段 4:结果输出#

结果输出

最终输出结构#

{
"query": "用户的查询内容",
"results": [
{
"rank": 1,
"id": "doc_042",
"content": "匹配的内容...",
"embedding_score": 0.89,
"rerank_score": 0.95,
"metadata": {
"source": "manual.pdf",
"page": 42,
"image_path": "/path/img.jpg"
}
}
],
"total_time_ms": 156
}

📊 模型规格#

模型参数量层数序列长度嵌入维度MRL支持
Qwen3-VL-Embedding-2B2B2832K2048
Qwen3-VL-Embedding-8B8B3632K4096
Qwen3-VL-Reranker-2B2B2832K--
Qwen3-VL-Reranker-8B8B3632K--

💡 部署建议#

业务规模推荐配置月成本估算
PoC/验证1x RTX 4090,2B 模型¥0 (自有) / ¥3k (云)
小规模2x A10,2B 模型¥6-10k
中规模2x A100 40GB,8B 模型¥30-50k
大规模4x A100 80GB + 向量库集群¥100k+

适用场景评估#

场景推荐程度说明
多模态知识库⭐⭐⭐⭐⭐核心优势场景,图文视频混合检索
电商图搜图⭐⭐⭐⭐⭐图像理解能力强,支持文字搜商品图
视频内容检索⭐⭐⭐⭐⭐少有的视频嵌入支持,时刻检索
文档理解 OCR⭐⭐⭐⭐ViDoRe 评测优秀,截图理解强
纯文本检索⭐⭐⭐可用但建议用 Qwen3-Embedding
边缘设备模型过大,不适合

📚 更多资源#

Qwen3-VL-Embedding 解析
https://www.fdssong.js.cn/posts/qwen3-vl-embedding/
作者
FDSSONG
发布于
2026-01-22
许可协议
CC BY-NC-SA 4.0