Qwen3 Embedding 4B GGUF

🚀 Qwen3-Embedding-4B GGUF模型

Qwen3-Embedding-4B GGUF模型是专为文本嵌入和排序任务设计的模型，基于Qwen3系列的密集基础模型构建，在多语言文本处理和代码检索等方面具有出色表现。

🚀 快速开始

环境要求

使用该模型前，请确保你的transformers版本大于等于4.51.0，否则可能会遇到如下错误：

KeyError: 'qwen3'

代码示例

Sentence Transformers使用示例

# Requires transformers>=4.51.0

from sentence_transformers import SentenceTransformer

# Load the model
model = SentenceTransformer("Qwen/Qwen3-Embedding-4B")

# We recommend enabling flash_attention_2 for better acceleration and memory saving,
# together with setting `padding_side` to "left":
# model = SentenceTransformer(
#     "Qwen/Qwen3-Embedding-4B",
#     model_kwargs={"attn_implementation": "flash_attention_2", "device_map": "auto"},
#     tokenizer_kwargs={"padding_side": "left"},
# )

# The queries and documents to embed
queries = [
    "What is the capital of China?",
    "Explain gravity",
]
documents = [
    "The capital of China is Beijing.",
    "Gravity is a force that attracts two bodies towards each other. It gives weight to physical objects and is responsible for the movement of planets around the sun.",
]

# Encode the queries and documents. Note that queries benefit from using a prompt
# Here we use the prompt called "query" stored under `model.prompts`, but you can
# also pass your own prompt via the `prompt` argument
query_embeddings = model.encode(queries, prompt_name="query")
document_embeddings = model.encode(documents)

# Compute the (cosine) similarity between the query and document embeddings
similarity = model.similarity(query_embeddings, document_embeddings)
print(similarity)
# tensor([[0.7534, 0.1147],
#         [0.0320, 0.6258]])

Transformers使用示例

# Requires transformers>=4.51.0
import torch
import torch.nn.functional as F

from torch import Tensor
from transformers import AutoTokenizer, AutoModel


def last_token_pool(last_hidden_states: Tensor,
                 attention_mask: Tensor) -> Tensor:
    left_padding = (attention_mask[:, -1].sum() == attention_mask.shape[0])
    if left_padding:
        return last_hidden_states[:, -1]
    else:
        sequence_lengths = attention_mask.sum(dim=1) - 1
        batch_size = last_hidden_states.shape[0]
        return last_hidden_states[torch.arange(batch_size, device=last_hidden_states.device), sequence_lengths]


def get_detailed_instruct(task_description: str, query: str) -> str:
    return f'Instruct: {task_description}\nQuery:{query}'

# Each query must come with a one-sentence instruction that describes the task
task = 'Given a web search query, retrieve relevant passages that answer the query'

queries = [
    get_detailed_instruct(task, 'What is the capital of China?'),
    get_detailed_instruct(task, 'Explain gravity')
]
# No need to add instruction for retrieval documents
documents = [
    "The capital of China is Beijing.",
    "Gravity is a force that attracts two bodies towards each other. It gives weight to physical objects and is responsible for the movement of planets around the sun."
]
input_texts = queries + documents

tokenizer = AutoTokenizer.from_pretrained('Qwen/Qwen3-Embedding-4B', padding_side='left')
model = AutoModel.from_pretrained('Qwen/Qwen3-Embedding-4B')

# We recommend enabling flash_attention_2 for better acceleration and memory saving.
# model = AutoModel.from_pretrained('Qwen/Qwen3-Embedding-4B', attn_implementation="flash_attention_2", torch_dtype=torch.float16).cuda()

max_length = 8192

# Tokenize the input texts
batch_dict = tokenizer(
    input_texts,
    padding=True,
    truncation=True,
    max_length=max_length,
    return_tensors="pt",
)
batch_dict.to(model.device)
outputs = model(**batch_dict)
embeddings = last_token_pool(outputs.last_hidden_state, batch_dict['attention_mask'])

# normalize embeddings
embeddings = F.normalize(embeddings, p=2, dim=1)
scores = (embeddings[:2] @ embeddings[2:].T)
print(scores.tolist())
# [[0.7534257769584656, 0.1146894246339798], [0.03198453038930893, 0.6258305311203003]]

💡 使用建议：

• 建议开发者根据具体场景、任务和语言自定义instruct。测试表明，在大多数检索场景中，查询端不使用instruct会导致检索性能下降约1% - 5%。
• 推荐启用flash_attention_2以获得更好的加速和内存节省效果，并将padding_side设置为"left"。

✨ 主要特性

卓越的通用性

嵌入模型在广泛的下游应用评估中达到了最先进的性能。8B大小的嵌入模型在MTEB多语言排行榜上排名第一（截至2025年6月5日，得分70.58），而重排序模型在各种文本检索场景中表现出色。

全面的灵活性

Qwen3 Embedding系列为嵌入和重排序模型提供了全范围的大小（从0.6B到8B），满足了优先考虑效率和效果的各种用例。开发者可以无缝组合这两个模块。此外，嵌入模型允许在所有维度上灵活定义向量，并且嵌入和重排序模型都支持用户定义的指令，以提高特定任务、语言或场景的性能。

多语言能力

由于Qwen3模型的多语言能力，Qwen3 Embedding系列支持100多种语言，包括各种编程语言，并提供强大的多语言、跨语言和代码检索能力。

📦 安装指南

文档未提及具体安装步骤，可参考transformers官方文档进行安装。

💻 使用示例

上述快速开始部分已给出Sentence Transformers和Transformers的使用示例。

📚 详细文档

模型概述

Qwen3-Embedding-4B 具有以下特点：

更多详细信息，包括基准评估、硬件要求和推理性能，请参考我们的博客、GitHub。

Qwen3 Embedding系列模型列表

注意：

• MRL支持表示嵌入模型是否支持最终嵌入的自定义维度。
• 指令感知表示嵌入或重排序模型是否支持根据不同任务自定义输入指令。
• 我们的评估表明，对于大多数下游任务，使用指令（instruct）通常比不使用指令提高1%到5%的性能。因此，建议开发者为其任务和场景创建量身定制的指令。在多语言环境中，也建议用户用英语编写指令，因为模型训练过程中使用的大多数指令最初是用英语编写的。

模型格式选择

选择正确的模型格式取决于你的硬件能力和内存限制。以下是不同模型格式的介绍：

BF16（Brain Float 16）

• 一种16位浮点格式，专为更快的计算而设计，同时保持良好的精度。
• 提供与FP32相似的动态范围，但内存使用更低。
• 如果你的硬件支持BF16加速（检查设备规格），则推荐使用。
• 与FP32相比，适用于具有减少内存占用的高性能推理。

使用场景：

• 你的硬件具有原生BF16支持（例如，较新的GPU、TPU）。
• 你希望在节省内存的同时获得更高的精度。
• 你计划将模型重新量化为另一种格式。

避免场景：

• 你的硬件不支持BF16（可能会回退到FP32并运行较慢）。
• 你需要与缺乏BF16优化的旧设备兼容。

F16（Float 16）

• 一种16位浮点格式，具有高精度，但值的范围比BF16小。
• 适用于大多数支持FP16加速的设备（包括许多GPU和一些CPU）。
• 数值精度略低于BF16，但通常足以进行推理。

使用场景：

• 你的硬件支持FP16但不支持BF16。
• 你需要在速度、内存使用和准确性之间取得平衡。
• 你在GPU或其他针对FP16计算优化的设备上运行。

避免场景：

• 你的设备缺乏原生FP16支持（可能运行比预期慢）。
• 你有内存限制。

混合精度模型（例如，bf16_q8_0，f16_q4_K）

这些格式选择性地对非关键层进行量化，同时保持关键层的全精度（例如，注意力和输出层）。

• 命名方式如bf16_q8_0（表示全精度BF16核心层 + 量化Q8_0其他层）。
• 在内存效率和准确性之间取得平衡，比完全量化的模型有所改进，而不需要BF16/F16的全部内存。

使用场景：

• 你需要比仅量化模型更好的准确性，但无法在所有地方使用全BF16/F16。
• 你的设备支持混合精度推理。
• 你希望在受限硬件上优化生产级模型的权衡。

避免场景：

• 你的目标设备不支持混合或全精度加速。
• 你在超严格的内存限制下操作（在这种情况下使用完全量化的格式）。

量化模型（Q4_K，Q6_K，Q8等）

量化在尽可能保持准确性的同时减小模型大小和内存使用。

• 低比特模型（Q4_K）：最适合最小的内存使用，可能精度较低。
• 高比特模型（Q6_K，Q8_0）：更好的准确性，需要更多的内存。

使用场景：

• 你在CPU上运行推理，需要优化的模型。
• 你的设备具有低VRAM，无法加载全精度模型。
• 你希望在保持合理准确性的同时减少内存占用。

避免场景：

• 你需要最大的准确性（全精度模型更适合此需求）。
• 你的硬件有足够的VRAM用于更高精度的格式（BF16/F16）。

极低比特量化（IQ3_XS，IQ3_S，IQ3_M，Q4_K，Q4_0）

这些模型针对非常高的内存效率进行了优化，使其非常适合低功耗设备或内存是关键限制的大规模部署。

• IQ3_XS：超低比特量化（3位），具有非常高的内存效率。适用于超低内存设备，即使Q4_K也太大的情况。准确性较低。
• IQ3_S：小块大小，以实现最大的内存效率。适用于低内存设备，IQ3_XS过于激进的情况。
• IQ3_M：中等块大小，比IQ3_S具有更好的准确性。适用于低内存设备，IQ3_S过于受限的情况。
• Q4_K：4位量化，具有逐块优化，以提高准确性。适用于低内存设备，Q6_K太大的情况。
• Q4_0：纯4位量化，针对ARM设备进行了优化。适用于基于ARM的设备或低内存环境。

超极低比特量化（IQ1_S，IQ1_M，IQ2_S，IQ2_M，IQ2_XS，IQ2_XSS）

• 超极低比特量化（1 - 2位），具有极高的内存效率。
• 使用场景：适用于必须将模型装入非常受限内存的情况。
• 权衡：准确性非常低，可能无法按预期运行。使用前请充分测试。

模型格式选择总结表

🔧 技术细节

模型生成细节

该模型使用llama.cpp在提交版本1f63e75f生成。

超越IMatrix的量化

测试一种新的量化方法，使用规则将重要层的量化级别提高到标准IMatrix使用的级别之上。发现标准IMatrix在低比特量化和MOE模型中表现不佳，因此使用llama.cpp的--tensor-type来提高选定层的量化级别。这会创建更大的模型文件，但会提高给定模型大小的精度。

评估结果

MTEB（多语言）

注意：对于比较的模型，分数从MTEB在线排行榜获取。

📄 许可证

本项目采用Apache-2.0许可证。