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許可證。