Nemotron-3-Embed-8B-BF16的API参考与调用示例：Transformers vs vLLM对比终极指南

Nemotron-3-Embed-8B-BF16的API参考与调用示例：Transformers vs vLLM对比终极指南

【免费下载链接】Nemotron-3-Embed-8B-BF16项目地址: https://ai.gitcode.com/hf_mirrors/nvidia/Nemotron-3-Embed-8B-BF16

想要在项目中集成强大的文本嵌入功能？Nemotron-3-Embed-8B-BF16作为NVIDIA推出的8B参数多语言嵌入模型，提供了卓越的检索和语义相似度计算能力。这篇完整指南将为您详细解析两种主流调用方式——Transformers与vLLM的API参考与调用示例，帮助您快速上手这个强大的嵌入模型。🎯

Nemotron-3-Embed-8B-BF16是基于Ministral-3-8B-Instruct-2512架构的Transformer编码器模型，专为多语言文本嵌入设计。它支持34种语言，包括中文、英文、日文、韩文等，能够将文本转换为4096维的密集向量表示，在检索增强生成（RAG）系统中表现卓越。

📋 快速环境准备与安装

在开始之前，确保您的环境满足以下要求：

• Python版本: 3.8+
• GPU: NVIDIA GPU（推荐Ampere、Blackwell或Hopper架构）
• CUDA: 11.8或更高版本

安装依赖包

根据您选择的调用方式，安装相应的依赖：

Transformers + Sentence Transformers方式：

pip install --upgrade "transformers>=5.2.0" "sentence-transformers>=5.4.1"

vLLM方式：

pip install --upgrade "vllm==0.25.0" openai requests numpy

如果您使用NVIDIA PyTorch容器（如nvcr.io/nvidia/pytorch:26.06-py3），容器已包含FlashAttention-2支持。否则，您可能需要手动安装FlashAttention-2或使用SDPA注意力实现。

🚀 Sentence Transformers：最简单的调用方式

对于大多数应用场景，Sentence Transformers提供了最简洁的API接口。它自动处理查询和文档前缀，以及L2归一化。

核心API参考

import torch from sentence_transformers import SentenceTransformer # 模型初始化 MODEL_ID = "nvidia/Nemotron-3-Embed-8B-BF16" model = SentenceTransformer( MODEL_ID, device="cuda", # 使用GPU model_kwargs={ "dtype": torch.bfloat16, # BF16精度 "attn_implementation": "flash_attention_2", # 使用FlashAttention-2 }, processor_kwargs={"padding_side": "left"}, # 左侧填充 ) model.max_seq_length = 32768 # 设置最大序列长度

关键参数说明

• device: 指定运行设备，"cuda"表示使用GPU
• dtype: 模型精度，torch.bfloat16提供最佳性能
• attn_implementation: 注意力实现方式，"flash_attention_2"提供最快速度
• max_seq_length: 最大序列长度，支持最长32768个token

完整调用示例

# 查询和文档示例 QUERIES = [ "如何快速学习Python编程？", "什么是机器学习中的梯度下降算法？", "如何优化数据库查询性能？", ] DOCUMENTS = [ "Python是一种高级编程语言，适合初学者快速上手。", "梯度下降是机器学习中常用的优化算法，用于最小化损失函数。", "数据库查询优化包括索引优化、查询重写和缓存策略。", ] # 生成嵌入向量 query_embeddings = model.encode_query(QUERIES, batch_size=1, convert_to_tensor=True) document_embeddings = model.encode_document(DOCUMENTS, batch_size=1, convert_to_tensor=True) # 计算相似度 scores = model.similarity(query_embeddings, document_embeddings) print("相似度得分:") print(f"{'':>4}" + "".join(f"d[{i}]".rjust(10) for i in range(scores.shape[1]))) for query_index, row in enumerate(scores): print(f"q[{query_index}]" + "".join(f"{score.item():>10.4f}" for score in row))

Sentence Transformers优势

• ✅ 自动处理query:和passage:前缀
• ✅ 内置L2归一化
• ✅ 简洁的API设计
• ✅ 支持批量处理

⚙️ Transformers：手动控制的高级方式

如果您需要更精细的控制，如自定义tokenization、pooling或批处理策略，可以使用原始的Transformers库。

核心API参考

import torch import torch.nn.functional as F from transformers import AutoModel, AutoTokenizer MODEL_ID = "nvidia/Nemotron-3-Embed-8B-BF16" MAX_LENGTH = 32768 BATCH_SIZE = 1 DTYPE = torch.bfloat16 ATTN_IMPLEMENTATION = "flash_attention_2"

关键函数定义

def average_pool(last_hidden_state: torch.Tensor, attention_mask: torch.Tensor) -> torch.Tensor: """平均池化函数""" last_hidden = last_hidden_state.masked_fill(~attention_mask[..., None].bool(), 0.0) return last_hidden.sum(dim=1) / attention_mask.sum(dim=1)[..., None] def encode_texts(texts: list[str]) -> torch.Tensor: """文本编码函数""" embedding_batches = [] for start in range(0, len(texts), BATCH_SIZE): encoded = tokenizer( texts[start : start + BATCH_SIZE], max_length=MAX_LENGTH, truncation=True, padding=True, return_tensors="pt", ) encoded = {name: tensor.to(device) for name, tensor in encoded.items()} with torch.inference_mode(): output = model(**encoded) pooled = average_pool(output.last_hidden_state, encoded["attention_mask"]) embeddings = F.normalize(pooled, p=2, dim=-1) embedding_batches.append(embeddings.detach().cpu().to(torch.float32)) return torch.cat(embedding_batches, dim=0)

完整调用示例

# 初始化模型和tokenizer device = torch.device("cuda") tokenizer = AutoTokenizer.from_pretrained(MODEL_ID, padding_side="left") if tokenizer.pad_token is None: tokenizer.pad_token = tokenizer.eos_token model = AutoModel.from_pretrained( MODEL_ID, dtype=DTYPE, attn_implementation=ATTN_IMPLEMENTATION, ).to(device) model.eval() # 准备文本（需要手动添加前缀） queries_with_prefix = ["query: " + query for query in QUERIES] documents_with_prefix = ["passage: " + doc for doc in DOCUMENTS] # 生成嵌入向量 all_texts = queries_with_prefix + documents_with_prefix embeddings = encode_texts(all_texts) # 分离查询和文档嵌入 query_embeddings = embeddings[: len(QUERIES)] document_embeddings = embeddings[len(QUERIES):] # 计算相似度 scores = query_embeddings @ document_embeddings.T

Transformers方式优势

• ✅ 完全控制tokenization过程
• ✅ 可自定义池化策略
• ✅ 灵活调整批处理大小
• ✅ 适合集成到复杂工作流中

🚀 vLLM：高性能推理引擎

对于生产环境和高吞吐量场景，vLLM提供了最优的性能表现。它支持在线服务和离线推理两种模式。

vLLM离线Python API

import numpy as np from vllm import LLM MODEL_ID = "nvidia/Nemotron-3-Embed-8B-BF16" def main(): # 初始化vLLM模型 llm = LLM(model=MODEL_ID) # 准备文本（需要手动添加前缀） texts = ["query: " + query for query in QUERIES] + [ "passage: " + doc for doc in DOCUMENTS ] # 生成嵌入向量 outputs = llm.embed(texts, use_tqdm=False) embeddings = np.array( [output.outputs.embedding for output in outputs], dtype=np.float32, ) # 计算相似度 query_embeddings = embeddings[: len(QUERIES)] document_embeddings = embeddings[len(QUERIES):] scores = query_embeddings @ document_embeddings.T

vLLM在线服务API

启动vLLM服务器：

MODEL_ID=nvidia/Nemotron-3-Embed-8B-BF16 vllm serve "$MODEL_ID" --host 0.0.0.0 --port 8000

使用推荐的检索端点：

import numpy as np import requests MODEL = "nvidia/Nemotron-3-Embed-8B-BF16" URL = "http://localhost:8000/v2/embed" def embed(input_type: str, texts: list[str]) -> np.ndarray: """调用vLLM嵌入API""" response = requests.post( URL, json={ "model": MODEL, "input_type": input_type, # "query" 或 "document" "texts": texts, "embedding_types": ["float"], "truncate": "END", }, timeout=120, ) response.raise_for_status() return np.array(response.json()["embeddings"]["float"], dtype=np.float32) # 生成嵌入向量 query_embeddings = embed("query", QUERIES) document_embeddings = embed("document", DOCUMENTS)

vLLM优势

• ✅ 最高性能的推理引擎
• ✅ 支持在线服务部署
• ✅ 自动批处理和优化
• ✅ 兼容OpenAI API格式

📊 三种方式对比分析

🔧 配置与优化建议

1. 处理长文本

Nemotron-3-Embed-8B-BF16支持最长32768个token。对于超长文本：

# 分块处理长文本 def chunk_text(text, max_length=30000): tokens = tokenizer.encode(text) chunks = [] for i in range(0, len(tokens), max_length): chunk_tokens = tokens[i:i + max_length] chunk_text = tokenizer.decode(chunk_tokens) chunks.append(chunk_text) return chunks # 对每个分块生成嵌入，然后平均 chunk_embeddings = [model.encode(chunk) for chunk in chunks] final_embedding = np.mean(chunk_embeddings, axis=0)

2. 批量大小优化

根据GPU内存调整批量大小：

• 8GB GPU: batch_size=1
• 16GB GPU: batch_size=2-4
• 24GB+ GPU: batch_size=4-8

3. 精度选择

• BF16: 推荐选择，平衡精度和性能
• FP16: 兼容性更好
• FP32: 最高精度，但内存消耗大

⚠️ 常见问题与解决方案

1. 配置警告处理

加载模型时可能看到警告：

[transformers] Unrecognized keys in `rope_parameters` for 'rope_type'='yarn': {'apply_yarn_scaling'}

这是预期行为，不会影响模型功能。apply_yarn_scaling字段用于vLLM兼容性。

2. 前缀处理注意事项

• Sentence Transformers: 自动处理query:和passage:前缀
• Transformers: 需要手动添加前缀
• vLLM在线服务: 使用input_type参数自动添加前缀

3. 内存不足问题

如果遇到内存不足：

# 减少批量大小 model.encode_query(queries, batch_size=1) # 使用梯度检查点 model = SentenceTransformer(MODEL_ID, device="cuda", model_kwargs={"use_gradient_checkpointing": True})

🎯 性能基准测试

根据官方测试结果，Nemotron-3-Embed-8B-BF16在多个基准测试中表现优异：

📁 项目文件结构参考

了解模型文件结构有助于更好地集成：

Nemotron-3-Embed-8B-BF16/ ├── config.json # 模型配置文件 ├── sentence_bert_config.json # Sentence Transformers配置 ├── tokenizer.json # 分词器配置 ├── tokenizer_config.json # 分词器额外配置 ├── model.safetensors.index.json # 模型权重索引 ├── model-0000X-of-00004.safetensors # 模型权重文件（4个分片） └── 1_Pooling/config.json # 池化层配置

💡 最佳实践建议

1. 开发阶段: 使用Sentence Transformers快速原型开发
2. 生产部署: 使用vLLM在线服务获得最佳性能
3. 自定义需求: 使用Transformers进行深度定制
4. 多语言应用: 充分利用模型的34种语言支持
5. 性能监控: 监控推理延迟和内存使用

🚀 下一步行动

现在您已经掌握了Nemotron-3-Embed-8B-BF16的三种调用方式，可以根据您的具体需求选择合适的方案：

• 快速原型开发: 选择Sentence Transformers
• 研究实验: 选择Transformers手动控制
• 生产部署: 选择vLLM在线服务

无论选择哪种方式，Nemotron-3-Embed-8B-BF16都能为您的文本检索和语义搜索应用提供强大的嵌入能力。开始构建您的多语言RAG系统吧！✨

记得在实际部署前进行充分的测试，特别是针对您的特定语言和领域数据。祝您项目顺利！

【免费下载链接】Nemotron-3-Embed-8B-BF16项目地址: https://ai.gitcode.com/hf_mirrors/nvidia/Nemotron-3-Embed-8B-BF16