ChatNVIDIA 集成

本文档将帮助您开始使用 NVIDIA 聊天模型。有关所有 ChatNVIDIA 功能和配置的详细文档，请访问 API 参考。

概述

langchain-nvidia-ai-endpoints 包包含 LangChain 与 NVIDIA AI Foundation Models 提供的聊天模型和嵌入模型的集成，这些模型托管在 NVIDIA API Catalog 上。一个强大的起点是 Nemotron，这是 NVIDIA 为智能体 AI 专门构建的开放模型系列。Nemotron 模型采用混合 Mamba-Transformer 专家混合架构，提供领先的准确性，并且吞吐量比同类模型高出 3 倍，上下文窗口高达 100 万个 token。模型权重、训练数据和实现配方均根据 NVIDIA 开放模型许可证公开发布。 NVIDIA AI Foundation 模型在 NIM 微服务上运行：通过 NVIDIA NGC Catalog 分发的容器镜像，公开标准的 OpenAI 兼容 API，并通过 TensorRT-LLM 进行优化以实现最大吞吐量。可以通过托管的 NVIDIA API Catalog 访问，或者使用 NVIDIA AI Enterprise 许可证在本地部署。本文档介绍如何使用 LangChain 通过 ChatNVIDIA 与 NVIDIA 模型交互，包括 Nemotron 和 API Catalog 中的其他模型。有关通过此 API 访问嵌入模型的更多信息，请参阅 NVIDIAEmbeddings 文档。

集成详情

类	包	可序列化	JS 支持	下载量	版本
`ChatNVIDIA`	`langchain-nvidia-ai-endpoints`	beta	❌

模型功能

工具调用	结构化输出	图像输入	音频输入	视频输入	Token 级流式传输	原生异步	Token 使用情况	Logprobs
✅	✅	✅	❌	❌	✅	✅	✅	❌

安装包

pip install -qU langchain-nvidia-ai-endpoints

访问 NVIDIA API Catalog

要访问 NVIDIA API Catalog，请执行以下操作：

在 NVIDIA API Catalog 上创建一个免费帐户并登录。
单击您的个人资料图标，然后单击 API Keys。将出现 API Keys 页面。
单击 Generate API Key。将出现 Generate API Key 窗口。
单击 Generate Key。您应该会看到 API Key Granted，并且您的密钥会出现。
复制并保存密钥为 NVIDIA_API_KEY。
要验证您的密钥，请使用以下代码。

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

您现在可以使用您的密钥访问 NVIDIA API Catalog 上的端点。要启用模型调用的自动跟踪，请设置您的 LangSmith API 密钥：

os.environ["LANGSMITH_TRACING"] = "true"
os.environ["LANGSMITH_API_KEY"] = getpass.getpass("Enter your LangSmith API key: ")

实例化

现在我们可以访问 NVIDIA API Catalog 中的模型。Nemotron 模型是智能体和推理工作负载的推荐起点：

from langchain_nvidia_ai_endpoints import ChatNVIDIA

# Nemotron 3 Nano — 高效推理和智能体任务
llm = ChatNVIDIA(model="nvidia/nemotron-3-super-120b-a12b")

API Catalog 中的任何其他模型都可以通过传递其模型 ID 来使用：

llm = ChatNVIDIA(model="mistralai/mixtral-8x7b-instruct-v0.1")

调用

result = llm.invoke("Write a ballad about LangChain.")
print(result.content)

使用 NVIDIA NIM 微服务自托管

当您准备好部署 AI 应用程序时，可以使用 NVIDIA NIM 自托管模型。有关更多信息，请参阅 NVIDIA NIM 微服务。以下代码连接到本地托管的 NIM 微服务。

from langchain_nvidia_ai_endpoints import ChatNVIDIA, NVIDIAEmbeddings, NVIDIARerank

# 连接到在 localhost:8000 运行的聊天 NIM，指定模型
llm = ChatNVIDIA(base_url="http://localhost:8000/v1", model="nvidia/nemotron-3-super-120b-a12b")

# 连接到在 localhost:8080 运行的嵌入 NIM
embedder = NVIDIAEmbeddings(base_url="http://localhost:8080/v1")

# 连接到在 localhost:2016 运行的重排序 NIM
ranker = NVIDIARerank(base_url="http://localhost:2016/v1")

流式传输、批处理和异步

这些模型原生支持流式传输，并且与所有 LangChain LLM 一样，它们公开了一个批处理方法来处理并发请求，以及用于调用、流式传输和批处理的异步方法。以下是一些示例。

print(llm.batch(["What's 2*3?", "What's 2*6?"]))
# 或通过异步 API
# await llm.abatch(["What's 2*3?", "What's 2*6?"])

for chunk in llm.stream("How far can a seagull fly in one day?"):
    # 显示 token 分隔
    print(chunk.content, end="|")

async for chunk in llm.astream(
    "How long does it take for monarch butterflies to migrate?"
):
    print(chunk.content, end="|")

支持的模型

查询 available_models 仍将为您提供您的 API 凭据提供的所有其他模型。 playground_ 前缀是可选的。

ChatNVIDIA.get_available_models()
# llm.get_available_models()

模型类型

以上所有模型都受支持，并且可以通过 ChatNVIDIA 访问。某些模型类型支持独特的提示技术和聊天消息。我们将在下面回顾一些重要的类型。 要了解有关特定模型的更多信息，请导航到 AI Foundation 模型的 API 部分如这里所链接。

用于智能体 AI 的 Nemotron 模型

Nemotron 是 NVIDIA 为智能体工作流专门构建的开放模型系列。主要特点：

效率：混合 Mamba-Transformer MoE 架构提供比同类密集模型高出 3 倍的吞吐量
长上下文：原生支持高达 100 万个 token 的上下文窗口
智能体推理：专门针对多步规划、工具使用和自主软件工程任务进行训练
开放：权重、训练配方和精选数据集根据 NVIDIA 开放模型许可证发布

from langchain_core.output_parsers import StrOutputParser
from langchain_core.prompts import ChatPromptTemplate
from langchain_nvidia_ai_endpoints import ChatNVIDIA

prompt = ChatPromptTemplate.from_messages(
    [
        ("system", "You are a helpful research assistant. Think step by step."),
        ("user", "{input}"),
    ]
)
chain = prompt | ChatNVIDIA(model="nvidia/nemotron-3-super-120b-a12b") | StrOutputParser()

for txt in chain.stream({"input": "What are the key considerations when designing a multi-agent RAG system?"}):
    print(txt, end="")

通用聊天

诸如 meta/llama3-8b-instruct 和 mistralai/mixtral-8x22b-instruct-v0.1 之类的模型是很好的通用模型，可用于任何 LangChain 聊天消息。下面是一个示例。

from langchain_core.output_parsers import StrOutputParser
from langchain_core.prompts import ChatPromptTemplate
from langchain_nvidia_ai_endpoints import ChatNVIDIA

prompt = ChatPromptTemplate.from_messages(
    [("system", "You are a helpful AI assistant named Fred."), ("user", "{input}")]
)
chain = prompt | ChatNVIDIA(model="nvidia/nemotron-3-super-120b-a12b") | StrOutputParser()

for txt in chain.stream({"input": "What's your name?"}):
    print(txt, end="")

代码生成

这些模型接受与常规聊天模型相同的参数和输入结构，但它们在代码生成和结构化代码任务方面往往表现更好。meta/codellama-70b 就是这样一个例子。

prompt = ChatPromptTemplate.from_messages(
    [
        (
            "system",
            "You are an expert coding AI. Respond only in valid python; no narration whatsoever.",
        ),
        ("user", "{input}"),
    ]
)
chain = prompt | ChatNVIDIA(model="meta/codellama-70b") | StrOutputParser()

for txt in chain.stream({"input": "How do I solve this fizz buzz problem?"}):
    print(txt, end="")

多模态

NVIDIA 还支持多模态输入，这意味着您可以提供图像和文本供模型推理。支持多模态输入的示例模型是 nvidia/neva-22b。以下是使用示例：

import IPython
import requests

image_url = "https://www.nvidia.com/content/dam/en-zz/Solutions/research/ai-playground/nvidia-picasso-3c33-p@2x.jpg"  ## 大图像
image_content = requests.get(image_url).content

IPython.display.Image(image_content)

from langchain_nvidia_ai_endpoints import ChatNVIDIA

llm = ChatNVIDIA(model="nvidia/neva-22b")

通过 URL 传递图像

from langchain.messages import HumanMessage

llm.invoke(
    [
        HumanMessage(
            content=[
                {"type": "text", "text": "Describe this image:"},
                {"type": "image_url", "image_url": {"url": image_url}},
            ]
        )
    ]
)

通过 base64 编码字符串传递图像

目前，一些额外的处理发生在客户端，以支持像上面这样的大图像。但对于较小的图像（并更好地说明底层发生的过程），我们可以直接传递图像，如下所示：

import IPython
import requests

image_url = "https://picsum.photos/seed/kitten/300/200"
image_content = requests.get(image_url).content

IPython.display.Image(image_content)

import base64

from langchain.messages import HumanMessage

## 适用于简单图像。对于更大的图像，请参阅实际实现
b64_string = base64.b64encode(image_content).decode("utf-8")

llm.invoke(
    [
        HumanMessage(
            content=[
                {"type": "text", "text": "Describe this image:"},
                {
                    "type": "image_url",
                    "image_url": {"url": f"data:image/png;base64,{b64_string}"},
                },
            ]
        )
    ]
)

直接在字符串中

NVIDIA API 独特地接受内联在 <img/> HTML 标签中的 base64 图像。虽然这与其他 LLM 不兼容，但您可以直接相应地提示模型。

base64_with_mime_type = f"data:image/png;base64,{b64_string}"
llm.invoke(f'What\'s in this image?\n<img src="{base64_with_mime_type}" />')

在 `RunnableWithMessageHistory` 中的示例用法

与任何其他集成一样，ChatNVIDIA 可以很好地支持聊天实用程序，如 RunnableWithMessageHistory，这类似于使用 ConversationChain。下面，我们展示了应用于 mistralai/mixtral-8x22b-instruct-v0.1 模型的 LangChain RunnableWithMessageHistory 示例。

pip install -qU langchain

from langchain_core.chat_history import InMemoryChatMessageHistory
from langchain_core.runnables.history import RunnableWithMessageHistory

# store 是一个字典，将会话 ID 映射到其相应的聊天历史记录。
store = {}  # 内存维护在链外部


# 一个函数，用于返回给定会话 ID 的聊天历史记录。
def get_session_history(session_id: str) -> InMemoryChatMessageHistory:
    if session_id not in store:
        store[session_id] = InMemoryChatMessageHistory()
    return store[session_id]


chat = ChatNVIDIA(
    model="nvidia/nemotron-3-super-120b-a12b",
    temperature=0.1,
    max_tokens=100,
    top_p=1.0,
)

#  定义一个 RunnableConfig 对象，带有一个 `configurable` 键。session_id 决定线程
config = {"configurable": {"session_id": "1"}}

conversation = RunnableWithMessageHistory(
    chat,
    get_session_history,
)

conversation.invoke(
    "Hi I'm Srijan Dubey.",  # 输入或查询
    config=config,
)

conversation.invoke(
    "I'm doing well! Just having a conversation with an AI.",
    config=config,
)

conversation.invoke(
    "Tell me about yourself.",
    config=config,
)

工具调用

从 v0.2 开始，ChatNVIDIA 支持 bind_tools。 ChatNVIDIA 提供与 build.nvidia.com 上各种模型以及本地 NIM 的集成。并非所有这些模型都经过工具调用训练。请务必选择一个支持工具调用的模型用于您的实验和应用程序。您可以获取已知支持工具调用的模型列表，

tool_models = [
    model for model in ChatNVIDIA.get_available_models() if model.supports_tools
]
tool_models

使用支持工具的模型，

from langchain.tools import tool
from pydantic import Field


@tool
def get_current_weather(
    location: str = Field(description="The location to get the weather for."),
):
    """Get the current weather for a location."""
    ...


llm = ChatNVIDIA(model=tool_models[0].id).bind_tools(tools=[get_current_weather])
response = llm.invoke("What is the weather in Boston?")
response.tool_calls

有关其他示例，请参阅如何使用聊天模型调用工具。

与 NVIDIA Dynamo 一起使用

NVIDIA Dynamo 是一个分布式推理服务框架，旨在在数据中心规模的多节点环境中部署模型。它通过将推理的各个阶段分散到不同的 GPU 上，智能地将请求路由到适当的 GPU 以避免冗余计算，并通过数据缓存扩展到经济高效的存储层，从而简化和自动化分布式服务的复杂性。 ChatNVIDIADynamo 是 ChatNVIDIA 的直接替代品，它会自动将 nvext.agent_hints 注入每个请求中。这些提示告诉 Dynamo 部署：

osl（输出序列长度）——预期有多少个 token，以便调度器可以规划内存分配
iat（到达间隔时间）——请求到达的速度，以便路由器可以预测负载
latency_sensitivity——请求的延迟关键程度，以便交互式调用获得优先路由
priority——请求优先级，以便后台工作可以为关键路径请求让路

每个请求都会自动生成一个唯一的 prefix_id，使路由器能够跟踪 KV 缓存关联性。

本节假设您有一个正在运行的 NVIDIA Dynamo 部署。

基本用法

将 ChatNVIDIA 替换为 ChatNVIDIADynamo，每个请求都会自动包含路由提示。所有标准的 ChatNVIDIA 参数都受支持。

from langchain_nvidia_ai_endpoints import ChatNVIDIA, ChatNVIDIADynamo

BASE_URL = "http://localhost:8099/v1"
MODEL = "your-model-name"

# 标准 ChatNVIDIA — 无 Dynamo 提示
llm_standard = ChatNVIDIA(base_url=BASE_URL, model=MODEL)

# ChatNVIDIADynamo — 相同的接口，自动注入 agent_hints
llm = ChatNVIDIADynamo(base_url=BASE_URL, model=MODEL)

result = llm.invoke("What is KV cache optimization?")
print(result.content)

ChatNVIDIADynamo 接受四个额外的参数，这些参数超出了 ChatNVIDIA 支持的参数：

参数	类型	默认值	描述
`osl`	`int`	`512`	预期输出序列长度（token）
`iat`	`int`	`250`	预期到达间隔时间（毫秒）
`latency_sensitivity`	`float`	`1.0`	较高的延迟敏感性获得优先路由
`priority`	`int`	`1`	较低的优先级设置获得更多的调度优先级

在构造时设置默认值

在创建模型实例时配置 Dynamo 提示。当模型实例始终服务于特定角色（例如高优先级交互式助手与低优先级后台摘要器）时，这很有用。

# 高优先级：简短响应，延迟关键
llm_critical = ChatNVIDIADynamo(
    base_url=BASE_URL,
    model=MODEL,
    osl=20,
    priority=0,
    latency_sensitivity=10.0,
)

# 低优先级：长响应，延迟容忍
llm_background = ChatNVIDIADynamo(
    base_url=BASE_URL,
    model=MODEL,
    osl=512,
    priority=10,
    latency_sensitivity=0,
)

每次调用时覆盖

Dynamo 参数也可以在每次调用时覆盖。当同一个模型实例处理具有不同特征的请求时，这很有用。

result = llm.invoke(
    "Classify this as positive or negative: 'I love this product!'",
    osl=10,
    iat=100,
    latency_sensitivity=1.0,
    priority=10,
)
print(result.content)

使用 Dynamo 提示进行流式传输

Dynamo 提示包含在初始流式请求中。Dynamo 使用它们在 token 开始流动之前选择最佳工作器。

for chunk in llm_critical.stream("Give a one-sentence summary of GPU computing."):
    print(chunk.content, end="", flush=True)

检查有效负载

为了进行调试，使用内部 _get_payload 方法检查 ChatNVIDIADynamo 发送到 NIM 端点的确切有效负载。

import json

payload = llm_critical._get_payload(
    inputs=[{"role": "user", "content": "Hello!"}],
    stop=None,
)
print(json.dumps(payload["nvext"], indent=2))

这将输出 nvext.agent_hints 部分：

{
  "agent_hints": {
    "prefix_id": "langchain-dynamo-a1b2c3d4e5f6",
    "osl": 20,
    "iat": 250,
    "latency_sensitivity": 1.0,
    "priority": 10
  }
}

API 参考

有关所有 ChatNVIDIA 功能和配置的详细文档，请访问 API 参考。

Popular Providers

Integrations by component

概述

集成详情

模型功能

安装包

访问 NVIDIA API Catalog

实例化

调用

使用 NVIDIA NIM 微服务自托管

流式传输、批处理和异步

支持的模型

模型类型

用于智能体 AI 的 Nemotron 模型

通用聊天

代码生成

多模态

通过 URL 传递图像

通过 base64 编码字符串传递图像

直接在字符串中

在 `RunnableWithMessageHistory` 中的示例用法

工具调用

与 NVIDIA Dynamo 一起使用

基本用法

在构造时设置默认值

每次调用时覆盖

使用 Dynamo 提示进行流式传输

检查有效负载

API 参考

相关主题

Popular Providers

Integrations by component

​概述

​集成详情

​模型功能

​安装包

​访问 NVIDIA API Catalog

​实例化

​调用

​使用 NVIDIA NIM 微服务自托管

​流式传输、批处理和异步

​支持的模型

​模型类型

​用于智能体 AI 的 Nemotron 模型

​通用聊天

​代码生成

​多模态

​通过 URL 传递图像

​通过 base64 编码字符串传递图像

​直接在字符串中

​在 RunnableWithMessageHistory 中的示例用法

​工具调用

​与 NVIDIA Dynamo 一起使用

​基本用法

​在构造时设置默认值

​每次调用时覆盖

​使用 Dynamo 提示进行流式传输

​检查有效负载

​API 参考

​相关主题

概述

集成详情

模型功能

安装包

访问 NVIDIA API Catalog

实例化

调用

使用 NVIDIA NIM 微服务自托管

流式传输、批处理和异步

支持的模型

模型类型

用于智能体 AI 的 Nemotron 模型

通用聊天

代码生成

多模态

通过 URL 传递图像

通过 base64 编码字符串传递图像

直接在字符串中

在 `RunnableWithMessageHistory` 中的示例用法

工具调用

与 NVIDIA Dynamo 一起使用

基本用法

在构造时设置默认值

每次调用时覆盖

使用 Dynamo 提示进行流式传输

检查有效负载

API 参考

相关主题