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.8GPU: NVIDIA GPU推荐Ampere、Blackwell或Hopper架构CUDA: 11.8或更高版本安装依赖包根据您选择的调用方式安装相应的依赖Transformers Sentence Transformers方式pip install --upgrade transformers5.2.0 sentence-transformers5.4.1vLLM方式pip install --upgrade vllm0.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, devicecuda, # 使用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表示使用GPUdtype: 模型精度torch.bfloat16提供最佳性能attn_implementation: 注意力实现方式flash_attention_2提供最快速度max_seq_length: 最大序列长度支持最长32768个token完整调用示例# 查询和文档示例 QUERIES [ 如何快速学习Python编程, 什么是机器学习中的梯度下降算法, 如何优化数据库查询性能, ] DOCUMENTS [ Python是一种高级编程语言适合初学者快速上手。, 梯度下降是机器学习中常用的优化算法用于最小化损失函数。, 数据库查询优化包括索引优化、查询重写和缓存策略。, ] # 生成嵌入向量 query_embeddings model.encode_query(QUERIES, batch_size1, convert_to_tensorTrue) document_embeddings model.encode_document(DOCUMENTS, batch_size1, convert_to_tensorTrue) # 计算相似度 scores model.similarity(query_embeddings, document_embeddings) print(相似度得分:) print(f{:4} .join(fd[{i}].rjust(10) for i in range(scores.shape[1]))) for query_index, row in enumerate(scores): print(fq[{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(dim1) / attention_mask.sum(dim1)[..., 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_lengthMAX_LENGTH, truncationTrue, paddingTrue, return_tensorspt, ) 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, p2, dim-1) embedding_batches.append(embeddings.detach().cpu().to(torch.float32)) return torch.cat(embedding_batches, dim0)完整调用示例# 初始化模型和tokenizer device torch.device(cuda) tokenizer AutoTokenizer.from_pretrained(MODEL_ID, padding_sideleft) if tokenizer.pad_token is None: tokenizer.pad_token tokenizer.eos_token model AutoModel.from_pretrained( MODEL_ID, dtypeDTYPE, attn_implementationATTN_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.TTransformers方式优势✅ 完全控制tokenization过程✅ 可自定义池化策略✅ 灵活调整批处理大小✅ 适合集成到复杂工作流中 vLLM高性能推理引擎对于生产环境和高吞吐量场景vLLM提供了最优的性能表现。它支持在线服务和离线推理两种模式。vLLM离线Python APIimport numpy as np from vllm import LLM MODEL_ID nvidia/Nemotron-3-Embed-8B-BF16 def main(): # 初始化vLLM模型 llm LLM(modelMODEL_ID) # 准备文本需要手动添加前缀 texts [query: query for query in QUERIES] [ passage: doc for doc in DOCUMENTS ] # 生成嵌入向量 outputs llm.embed(texts, use_tqdmFalse) embeddings np.array( [output.outputs.embedding for output in outputs], dtypenp.float32, ) # 计算相似度 query_embeddings embeddings[: len(QUERIES)] document_embeddings embeddings[len(QUERIES):] scores query_embeddings document_embeddings.TvLLM在线服务API启动vLLM服务器MODEL_IDnvidia/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, }, timeout120, ) response.raise_for_status() return np.array(response.json()[embeddings][float], dtypenp.float32) # 生成嵌入向量 query_embeddings embed(query, QUERIES) document_embeddings embed(document, DOCUMENTS)vLLM优势✅ 最高性能的推理引擎✅ 支持在线服务部署✅ 自动批处理和优化✅ 兼容OpenAI API格式 三种方式对比分析特性Sentence TransformersTransformersvLLM易用性⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐性能⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐灵活性⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐生产就绪⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐部署复杂度低中高内存效率高高非常高多语言支持内置需要手动处理内置 配置与优化建议1. 处理长文本Nemotron-3-Embed-8B-BF16支持最长32768个token。对于超长文本# 分块处理长文本 def chunk_text(text, max_length30000): 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, axis0)2. 批量大小优化根据GPU内存调整批量大小8GB GPU: batch_size116GB GPU: batch_size2-424GB GPU: batch_size4-83. 精度选择BF16: 推荐选择平衡精度和性能FP16: 兼容性更好FP32: 最高精度但内存消耗大⚠️ 常见问题与解决方案1. 配置警告处理加载模型时可能看到警告[transformers] Unrecognized keys in rope_parameters for rope_typeyarn: {apply_yarn_scaling}这是预期行为不会影响模型功能。apply_yarn_scaling字段用于vLLM兼容性。2. 前缀处理注意事项Sentence Transformers: 自动处理query:和passage:前缀Transformers: 需要手动添加前缀vLLM在线服务: 使用input_type参数自动添加前缀3. 内存不足问题如果遇到内存不足# 减少批量大小 model.encode_query(queries, batch_size1) # 使用梯度检查点 model SentenceTransformer(MODEL_ID, devicecuda, model_kwargs{use_gradient_checkpointing: True}) 性能基准测试根据官方测试结果Nemotron-3-Embed-8B-BF16在多个基准测试中表现优异基准测试Nemotron-3-Embed-8B-BF16得分RTEB 1678.46ViDoRe-V3 text60.60MMTEB (Retrieval)75.45 项目文件结构参考了解模型文件结构有助于更好地集成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 # 池化层配置 最佳实践建议开发阶段: 使用Sentence Transformers快速原型开发生产部署: 使用vLLM在线服务获得最佳性能自定义需求: 使用Transformers进行深度定制多语言应用: 充分利用模型的34种语言支持性能监控: 监控推理延迟和内存使用 下一步行动现在您已经掌握了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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考