LlamaIndex NVIDIA 嵌入集成：NVIDIAEmbedding 类的完整 API 参考与 NIM 接入实战

本文围绕 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.1；
• Python 要求：>=3.10,<4.0；
• 核心依赖：llama-index-core>=0.13.0,<0.15；
• 运行时通过 openai SDK（OpenAI / AsyncOpenAI 客户端）访问 OpenAI 兼容的 /v1/embeddings 接口，另依赖 httpx。

安装命令（见 README.md）：

pip 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_key

3.2 托管端点的判定与强制校验

base_url 字段默认值来自环境变量 NVIDIA_BASE_URL，兜底为 utils.py 中的 BASE_URL：

BASE_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_MODEL（nvidia/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(model="nv-embedqa-e5-v5")
embedder.get_query_embedding("What's the weather like in Komchatka?")

注意：模型名校验逻辑 _validate_model 对表中已知模型会自动把客户端的 base_url 重写为该模型登记的 endpoint（例如 NV-Embed-QA 对应 https://ai.api.nvidia.com/v1/retrieval/nvidia），并同步更新同步与异步两个客户端的 base_url（base.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 参考使用：

参数	类型 / 取值	默认值	说明
model	Optional[str]	托管端为 nvidia/nv-embedqa-e5-v5；自托管端自动探测	要使用的 NVIDIA 嵌入模型名
base_url	str	环境变量 NVIDIA_BASE_URL，否则 https://integrate.api.nvidia.com/v1	模型列表与调用请求的基础 URL；设为非 KNOWN_URLS 地址即切换为自托管 NIM
truncate	"NONE" / "START" / "END"	"NONE"	输入超过模型最大 token 长度时的截断策略；NONE 表示超长时报错
timeout	float（秒）	120	单次 API 请求超时时间
max_retries	int	5	API 请求最大重试次数
dimensions	Optional[int]	None	嵌入向量维度，并非所有模型都支持该参数
nvidia_api_key / api_key	Optional[str]	读环境变量 NVIDIA_API_KEY	API Key，推荐用环境变量
embed_batch_size	int	DEFAULT_EMBED_BATCH_SIZE	批量嵌入批大小，必须 ≤ 259
callback_manager	Optional[CallbackManager]	None	LlamaIndex 回调管理器
http_client / async_http_client	Optional[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_size=300 断言了该异常。此外，同步与异步批量方法内部还有 assert len(texts) <= 259 的双重防线（base.py 第 265 行、306 行）。

test_nvidia_embedding_param_setting 用例验证了 truncate、timeout、max_retries、embed_batch_size 全部会透传到内部 OpenAI 客户端：

emb = NVIDIAEmbedding(
    api_key="BOGUS",
    model="NV-Embed-QA",
    truncate="END",
    timeout=20,
    max_retries=10,
    embed_batch_size=15,
)
assert emb._client.timeout == 20
assert emb._client.max_retries == 10
assert emb._aclient.timeout == 20
assert emb._aclient.max_retries == 10

test_nvidia_embedding_custom_http_clients 则验证传入自定义 httpx 客户端后，会透传给 OpenAI/AsyncOpenAI 的 http_client 参数。

五、已知嵌入模型表（EMBEDDING_MODEL_TABLE）

available_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-l
NV-Embed-QA	独立 endpoint https://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],
            model=self.model,
            extra_body=extra_body,
        )
        .data[0]
        .embedding
    )

从源码结构看有两个值得注意的细节：

1. truncate 与 dimensions 通过 extra_body 下发。这是 NIM 嵌入接口的扩展字段，非 OpenAI 标准参数；dimensions 仅在非零时加入请求体。测试 test_truncate.py 用 Mock 客户端对 get_query_embedding、get_text_embedding、get_text_embedding_batch 及对应的三个异步方法做了 NONE/START/END 全组合的参数化验证。
2. 同步与异步客户端行为存在细微差异。同步的 _get_query_embedding 使用 input_type="passage"，而异步的 _aget_query_embedding 使用 input_type="query"（base.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_url="http://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_hosted：Mock 一个 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(
    model="nvidia/nv-embedqa-e5-v5",   # 默认值，可省略
    truncate="END",                     # 超长文本从尾部截断
    timeout=120,                        # 请求超时（秒）
    max_retries=5,
)

documents = SimpleDirectoryReader("data/").load_data()
index = VectorStoreIndex.from_documents(documents, embeddings=embedder)

需要注意的适用前提：

• 托管模式（默认 https://integrate.api.nvidia.com/v1）必须提供 NVIDIA_API_KEY，否则构造函数报错；
• 批量调用单批不超过 259 条文本；
• 若你的模型不在 EMBEDDING_MODEL_TABLE 中，构造时只会收到无法验证的警告，请求本身仍会发出，最终有效性由服务端决定。

九、相关文件索引

内容	路径
API 参考页（本文主体文档）	docs/api_reference/api_reference/embeddings/nvidia.md
主实现（NVIDIAEmbedding）	llama_index/embeddings/nvidia/base.py
URL、默认模型与模型表	llama_index/embeddings/nvidia/utils.py
使用与接入说明	README.md
版本与依赖声明	pyproject.toml
参数透传与批大小限制测试	tests/test_embeddings_nvidia.py
base_url 优先级与自托管探测测试	tests/test_base_url.py
truncate 参数全组合测试	tests/test_truncate.py