Qwen3 Embedding 8B GGUF

🚀 Qwen/Qwen3-Embedding-8B GGUF 模型

Qwen3 嵌入模型系列是 Qwen 家族的最新專有模型，專為文本嵌入和排序任務設計。它基於 Qwen3 系列的密集基礎模型構建，提供了多種大小（0.6B、4B 和 8B）的文本嵌入和重排序模型。該系列繼承了基礎模型出色的多語言能力、長文本理解和推理能力，在多個文本嵌入和排序任務中取得了顯著進展，包括文本檢索、代碼檢索、文本分類、文本聚類和雙語挖掘。

✨ 主要特性

• 卓越的通用性：嵌入模型在廣泛的下游應用評估中達到了最先進的性能。8B 大小的嵌入模型在 MTEB 多語言排行榜上排名第一（截至 2025 年 6 月 5 日，得分 70.58），而重排序模型在各種文本檢索場景中表現出色。
• 全面的靈活性：Qwen3 嵌入系列為嵌入和重排序模型提供了全範圍的大小（從 0.6B 到 8B），滿足了優先考慮效率和效果的各種用例。開發人員可以無縫組合這兩個模塊。此外，嵌入模型允許在所有維度上靈活定義向量，並且嵌入和重排序模型都支持用戶定義的指令，以提高特定任務、語言或場景的性能。
• 多語言能力：由於 Qwen3 模型的多語言能力，Qwen3 嵌入系列支持 100 多種語言，包括各種編程語言，並提供強大的多語言、跨語言和代碼檢索能力。

📦 安裝指南

使用早於 4.51.0 版本的 Transformers 時，可能會遇到以下錯誤：

KeyError: 'qwen3'

請確保安裝符合要求的依賴庫：

• transformers>=4.51.0
• sentence-transformers>=2.7.0
• vllm>=0.8.5

💻 使用示例

基礎用法

Sentence Transformers 使用示例

# Requires transformers>=4.51.0
# Requires sentence-transformers>=2.7.0

from sentence_transformers import SentenceTransformer

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

# We recommend enabling flash_attention_2 for better acceleration and memory saving,
# together with setting `padding_side` to "left":
# model = SentenceTransformer(
#     "Qwen/Qwen3-Embedding-8B",
#     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.7493, 0.0751],
#         [0.0880, 0.6318]])

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-8B', padding_side='left')
model = AutoModel.from_pretrained('Qwen/Qwen3-Embedding-8B')

# We recommend enabling flash_attention_2 for better acceleration and memory saving.
# model = AutoModel.from_pretrained('Qwen/Qwen3-Embedding-8B', 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.7493016123771667, 0.0750647559762001], [0.08795969933271408, 0.6318399906158447]]

vLLM 使用示例

# Requires vllm>=0.8.5
import torch
import vllm
from vllm import LLM
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
model = LLM(model="Qwen/Qwen3-Embedding-8B", task="embed")
outputs = model.embed(input_texts)
embeddings = torch.tensor([o.outputs.embedding for o in outputs])
scores = (embeddings[:2] @ embeddings[2:].T)
print(scores.tolist())
# [[0.7482624650001526, 0.07556197047233582], [0.08875375241041183, 0.6300010681152344]]

高級用法

⚠️ 重要提示

我們建議開發人員根據具體場景、任務和語言自定義 instruct。我們的測試表明，在大多數檢索場景中，查詢端不使用 instruct 會導致檢索性能下降約 1% 到 5%。

💡 使用建議

對於大多數下游任務，使用指令（instruct）通常比不使用指令能提高 1% 到 5% 的性能。因此，建議開發人員根據自己的任務和場景創建定製的指令。在多語言環境中，建議用戶用英語編寫指令，因為模型訓練過程中使用的大多數指令最初都是用英語編寫的。

📚 詳細文檔

模型生成細節

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

選擇合適的模型格式

選擇正確的模型格式取決於你的 硬件能力 和 內存限制。

BF16（Brain Float 16）—— 如果有 BF16 加速功能則使用

• 一種 16 位浮點格式，專為 更快的計算 而設計，同時保持良好的精度。
• 提供與 FP32 相似的動態範圍，但 內存使用更低。
• 如果你的硬件支持 BF16 加速（檢查設備規格），建議使用。
• 與 FP32 相比，適用於 高性能推理 且 內存佔用減少。

使用 BF16 的情況：

• 你的硬件具有原生 BF16 支持（例如，較新的 GPU、TPU）。
• 你想在節省內存的同時獲得 更高的精度。
• 你計劃將模型 重新量化 為其他格式。

避免使用 BF16 的情況：

• 你的硬件 不支持 BF16（可能會回退到 FP32 並運行得更慢）。
• 你需要與缺乏 BF16 優化的舊設備兼容。

F16（Float 16）—— 比 BF16 更廣泛支持

• 一種 16 位浮點格式，具有 高精度，但取值範圍比 BF16 小。
• 適用於大多數支持 FP16 加速 的設備（包括許多 GPU 和一些 CPU）。
• 數值精度略低於 BF16，但通常足以用於推理。

使用 F16 的情況：

• 你的硬件支持 FP16 但 不支持 BF16。
• 你需要在 速度、內存使用和準確性 之間取得平衡。
• 你在 GPU 或其他針對 FP16 計算優化的設備上運行。

避免使用 F16 的情況：

• 你的設備缺乏 原生 FP16 支持（可能運行得比預期慢）。
• 你有內存限制。

混合精度模型（例如，bf16_q8_0，f16_q4_K）—— 兩全其美

這些格式選擇性地 量化非關鍵層，同時保持 關鍵層的全精度（例如，注意力和輸出層）。

• 命名方式如 bf16_q8_0（意味著 全精度 BF16 核心層 + 量化 Q8_0 其他層）。
• 在 內存效率和準確性 之間取得平衡，比完全量化的模型有所改進，而無需 BF16/F16 的全部內存。

使用混合模型的情況：

• 你需要比僅量化模型 更高的準確性，但無法承受在所有地方使用全 BF16/F16。
• 你的設備支持 混合精度推理。
• 你想在受限硬件上為生產級模型 優化權衡。

避免使用混合模型的情況：

• 你的目標設備不支持 混合或全精度加速。
• 你在 超嚴格的內存限制 下操作（在這種情況下，使用完全量化的格式）。

量化模型（Q4_K，Q6_K，Q8 等）—— 用於 CPU 和低 VRAM 推理

量化在儘可能保持準確性的同時減小模型大小和內存使用。

• 低比特模型（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 位），具有 極高的內存效率。
  • 用例：最適合需要將模型放入非常受限內存的情況。
  • 權衡：準確性非常低。可能無法按預期運行。使用前請充分測試。

模型格式選擇總結表

Qwen3 嵌入系列模型列表

注意：

• MRL 支持 表示嵌入模型是否支持最終嵌入的自定義維度。
• 指令感知 表示嵌入或重排序模型是否支持根據不同任務自定義輸入指令。
• 我們的評估表明，對於大多數下游任務，使用指令（instruct）通常比不使用指令能提高 1% 到 5% 的性能。因此，建議開發人員根據自己的任務和場景創建定製的指令。在多語言環境中，也建議用戶用英語編寫指令，因為模型訓練過程中使用的大多數指令最初都是用英語編寫的。

🔧 技術細節

更多詳細信息，包括基準評估、硬件要求和推理性能，請參考我們的 博客、GitHub。

📄 許可證

本項目採用 Apache-2.0 許可證。