LlamaIndex NVIDIA 嵌入集成NVIDIAEmbedding 类的完整 API 参考与 NIM 接入实战【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index本文围绕 LlamaIndex 官方 API 文档页docs/api_reference/api_reference/embeddings/nvidia.md所描述的llama_index.embeddings.nvidia模块展开从该模块唯一公开成员NVIDIAEmbedding类的字段与构造参数讲起结合llama-index-integrations/embeddings/llama-index-embeddings-nvidia包的真实源码与测试用例说明如何接入 NVIDIA API Catalog托管 NIM与自托管的 NIM 微服务。读完本文你可以独立完成包的安装、API Key 配置、模型选择、截断策略设置与批量嵌入调用并理解底层 OpenAI 兼容客户端的组装逻辑。一、API 文档页对应的模块结构API 参考页 docs/api_reference/api_reference/embeddings/nvidia.md 是 MkDocs 自动生成的模块文档其全部内容指向一个目标::: llama_index.embeddings.nvidia options: members: - NVIDIA它声明该文档页展示llama_index.embeddings.nvidia包中NVIDIA相关的公共 API。查看该包入口 llama_index/embeddings/nvidia/init.py 可知整个包只导出一个类from llama_index.embeddings.nvidia.base import NVIDIAEmbedding __all__ [NVIDIAEmbedding]因此该 API 参考页实际覆盖的核心内容就是 base.py 中定义的NVIDIAEmbedding类以及 utils.py 中的默认 URL、默认模型与已知模型表。二、安装与运行前提该集成位于 monorepo 的 llama-index-embeddings-nvidia 子包中其 pyproject.toml 声明了如下关键约束包名llama-index-embeddings-nvidia当前仓库内版本为0.5.1Python 要求3.10,4.0核心依赖llama-index-core0.13.0,0.15运行时通过openaiSDKOpenAI/AsyncOpenAI客户端访问 OpenAI 兼容的/v1/embeddings接口另依赖httpx。安装命令见 README.mdpip install llama-index-embeddings-nvidia包元数据中还包含[tool.llamahub]段声明import_path llama_index.embeddings.nvidia即 LlamaHub 索引中该集成的导入路径与本文示例一致。三、API Key 与托管端接入API Catalog 模式3.1 密钥来源与优先级__init__中通过get_from_param_or_env解析密钥base.py 第 123-128 行api_key get_from_param_or_env( api_key, nvidia_api_key or api_key, NVIDIA_API_KEY, NO_API_KEY_PROVIDED, )即按“显式参数api_key/nvidia_api_key→ 环境变量NVIDIA_API_KEY”的顺序取用。README 给出的密钥验证脚本可直接复制使用Key 需以nvapi-开头import getpass import os if os.environ.get(NVIDIA_API_KEY, ).startswith(nvapi-): print(Valid NVIDIA_API_KEY already in environment. Delete to reset) else: nvapi_key getpass.getpass(NVAPI Key (starts with nvapi-): ) assert nvapi_key.startswith( nvapi- ), f{nvapi_key[:5]}... is not a valid key os.environ[NVIDIA_API_KEY] nvapi_key3.2 托管端点的判定与强制校验base_url字段默认值来自环境变量NVIDIA_BASE_URL兜底为utils.py中的BASE_URLBASE_URL https://integrate.api.nvidia.com/v1 DEFAULT_MODEL nvidia/nv-embedqa-e5-v5构造函数根据self.base_url in KNOWN_URLS设置私有属性_is_hosted。KNOWN_URLS目前包含两个地址utils.py 第 145-148 行KNOWN_URLS [ BASE_URL, https://ai.api.nvidia.com/v1/retrieval/snowflake/arctic-embed-l, ]若判定为托管端_is_hosted True且没有提供任何 API Key构造函数会直接抛出ValueError(An API key is required for hosted NIM.)测试 test_base_url.py 中test_create_without_base_url验证了不设置NVIDIA_BASE_URL时base_url回落到https://integrate.api.nvidia.com/v1而test_base_url_priority验证了“构造参数base_url优先于环境变量NVIDIA_BASE_URL”的覆盖顺序。3.3 默认模型与基础用法未显式指定model时托管端直接使用DEFAULT_MODELnvidia/nv-embedqa-e5-v5自托管端则会调用__get_default_model向本地服务查询/models列表取第一个base_model为空或等于自身的模型并发出UserWarning提示改用available_models属性显式指定。最基本的调用示例README “Work with the API Catalog” 一节这里使用模型名nv-embedqa-e5-v5的简写from llama_index.embeddings.nvidia import NVIDIAEmbedding embedder NVIDIAEmbedding(modelnv-embedqa-e5-v5) embedder.get_query_embedding(Whats the weather like in Komchatka?)注意模型名校验逻辑_validate_model对表中已知模型会自动把客户端的base_url重写为该模型登记的endpoint例如NV-Embed-QA对应https://ai.api.nvidia.com/v1/retrieval/nvidia并同步更新同步与异步两个客户端的base_urlbase.py 第 191-211 行。对于无法在模型表中确定的名称如google/deplot只会发出Unable to determine validity警告而不会报错——这一点由 test_embeddings_nvidia.py 的test_model_incompatible_client_known_model用例确认。四、完整参数表NVIDIAEmbedding 字段与构造函数以下参数清单综合自类字段定义base.py 第 27-68 行与构造函数签名可直接作为 API 参考使用参数类型 / 取值默认值说明modelOptional[str]托管端为nvidia/nv-embedqa-e5-v5自托管端自动探测要使用的 NVIDIA 嵌入模型名base_urlstr环境变量NVIDIA_BASE_URL否则https://integrate.api.nvidia.com/v1模型列表与调用请求的基础 URL设为非KNOWN_URLS地址即切换为自托管 NIMtruncateNONE / START / ENDNONE输入超过模型最大 token 长度时的截断策略NONE表示超长时报错timeoutfloat秒120单次 API 请求超时时间max_retriesint5API 请求最大重试次数dimensionsOptional[int]None嵌入向量维度并非所有模型都支持该参数nvidia_api_key/api_keyOptional[str]读环境变量NVIDIA_API_KEYAPI Key推荐用环境变量embed_batch_sizeintDEFAULT_EMBED_BATCH_SIZE批量嵌入批大小必须 ≤ 259callback_managerOptional[CallbackManager]NoneLlamaIndex 回调管理器http_client/async_http_clientOptional[httpx.Client/AsyncClient]None自定义底层 HTTP 客户端如关闭 TLS 校验构造函数对embed_batch_size 259会直接抛出ValueError(The batch size should not be larger than 259.)测试 test_embeddings_nvidia.py 第 71-74 行 用embed_batch_size300断言了该异常。此外同步与异步批量方法内部还有assert len(texts) 259的双重防线base.py 第 265 行、306 行。test_nvidia_embedding_param_setting用例验证了truncate、timeout、max_retries、embed_batch_size全部会透传到内部 OpenAI 客户端emb NVIDIAEmbedding( api_keyBOGUS, modelNV-Embed-QA, truncateEND, timeout20, max_retries10, embed_batch_size15, ) assert emb._client.timeout 20 assert emb._client.max_retries 10 assert emb._aclient.timeout 20 assert emb._aclient.max_retries 10test_nvidia_embedding_custom_http_clients则验证传入自定义httpx客户端后会透传给OpenAI/AsyncOpenAI的http_client参数。五、已知嵌入模型表EMBEDDING_MODEL_TABLEavailable_models属性在托管模式下返回EMBEDDING_MODEL_TABLE中登记的全部模型utils.py 第 53-106 行当前仓库登记的模型为模型 id备注snowflake/arctic-embed-l别名ai-arctic-embed-l托管地址为ai.api.nvidia.com/v1/retrieval/snowflake/arctic-embed-lNV-Embed-QA独立 endpointhttps://ai.api.nvidia.com/v1/retrieval/nvidia别名ai-embed-qa-4、playground_nvolveqa_40k、nvolveqa_40k别名已废弃nvidia/nv-embed-v1别名ai-nv-embed-v1已废弃nvidia/nv-embedqa-mistral-7b-v2—nvidia/nv-embedqa-e5-v5默认模型baai/bge-m3—nvidia/embed-qa-4—nvidia/llama-3.2-nv-embedqa-1b-v1/...-v2—nvidia/llama-3.2-nemoretriever-1b-vlm-embed-v1—nvidia/nv-embedcode-7b-v1代码嵌入模型lookup_model支持按 id 或别名查找determine_model在命中别名时发出弃用警告“Model X is deprecated. Using Y instead.”随后_validate_model会依据Model.endpoint重写客户端地址。自托管模式下available_models改为调用self._client.models.list()实时查询本地/models接口并以params.root字段作为base_model判断是否为“基础模型”base_model为空或等于id。六、嵌入调用链路同步与异步方法NVIDIAEmbedding继承自llama_index.core.base.embeddings.base.BaseEmbedding重写了四类底层方法全部通过 OpenAI 兼容的client.embeddings.create(...)发起请求def _get_query_embedding(self, query: str) - List[float]: extra_body {input_type: passage, truncate: self.truncate} if self.dimensions: extra_body[dimensions] self.dimensions return ( self._client.embeddings.create( input[query], modelself.model, extra_bodyextra_body, ) .data[0] .embedding )从源码结构看有两个值得注意的细节truncate与dimensions通过extra_body下发。这是 NIM 嵌入接口的扩展字段非 OpenAI 标准参数dimensions仅在非零时加入请求体。测试 test_truncate.py 用 Mock 客户端对get_query_embedding、get_text_embedding、get_text_embedding_batch及对应的三个异步方法做了NONE/START/END全组合的参数化验证。同步与异步客户端行为存在细微差异。同步的_get_query_embedding使用input_typepassage而异步的_aget_query_embedding使用input_typequerybase.py 第 233-288 行异步批量方法_aget_text_embeddings目前未透传dimensions。从源码结构看这意味着对查询/段落区分敏感、或依赖dimensions的模型应优先使用同步路径。客户端初始化时为同步和异步客户端分别设置了User-Agent: llama-index-embeddings-nvidia自定义请求头便于服务端识别流量来源base.py 第 146、158 行。七、自托管 NIM 微服务接入当需要把模型部署到自有基础设施如 NVIDIA AI Enterprise 环境时只需把base_url指向本地 NIM 的 OpenAI 兼容端点即可切换到自托管模式from llama_index.embeddings.nvidia import NVIDIAEmbedding # 连接运行在 localhost:8080 的嵌入 NIM embedder NVIDIAEmbedding(base_urlhttp://localhost:8080/v1)切换为自托管后的行为差异均有源码与测试支撑_is_hosted变为False不再强制要求 API Key若未指定model构造函数调用__get_default_model查询本地/models并自动选取基础模型同时发出UserWarning若一个本地模型都没有则抛出ValueError(No locally hosted model was found.)available_models从静态表切换为实时查询。对应验证用例是 test_base_url.py 第 101-111 行 的test_base_url_valid_not_hostedMock 一个http://localhost:8080/v1上返回model1的/models接口断言cls._is_hosted is False且自动选中cls.model model1。同文件还验证了带深层路径的代理 URL如http://host/path0/path1/path2/v1可正常作为base_url使用。提示该包内已移除了对base_url必须以/v1结尾的校验与告警test_param_base_url_negative、test_expect_warn两个用例被标记为skip原因为 base_url validation is removed因此请自行确保自托管端点路径与 NIM 实际暴露的 OpenAI 兼容路径一致。八、在 LlamaIndex 应用中的典型用法NVIDIAEmbedding是标准的BaseEmbedding子类可直接作为嵌入引擎传给VectorStoreIndex。托管模式的完整可运行示例import os os.environ[NVIDIA_API_KEY] nvapi-xxxxxxxx # 推荐用环境变量注入 from llama_index.core import VectorStoreIndex, SimpleDirectoryReader from llama_index.embeddings.nvidia import NVIDIAEmbedding embedder NVIDIAEmbedding( modelnvidia/nv-embedqa-e5-v5, # 默认值可省略 truncateEND, # 超长文本从尾部截断 timeout120, # 请求超时秒 max_retries5, ) documents SimpleDirectoryReader(data/).load_data() index VectorStoreIndex.from_documents(documents, embeddingsembedder)需要注意的适用前提托管模式默认https://integrate.api.nvidia.com/v1必须提供NVIDIA_API_KEY否则构造函数报错批量调用单批不超过 259 条文本若你的模型不在EMBEDDING_MODEL_TABLE中构造时只会收到无法验证的警告请求本身仍会发出最终有效性由服务端决定。九、相关文件索引内容路径API 参考页本文主体文档docs/api_reference/api_reference/embeddings/nvidia.md主实现NVIDIAEmbeddingllama_index/embeddings/nvidia/base.pyURL、默认模型与模型表llama_index/embeddings/nvidia/utils.py使用与接入说明README.md版本与依赖声明pyproject.toml参数透传与批大小限制测试tests/test_embeddings_nvidia.pybase_url 优先级与自托管探测测试tests/test_base_url.pytruncate 参数全组合测试tests/test_truncate.py【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考