ChatNVIDIA 集成

本文档将帮助您快速上手 NVIDIA 聊天模型。有关 ChatNVIDIA 所有功能和配置的详细文档，请参阅 API 参考。

概述

langchain-nvidia-ai-endpoints 包包含 LangChain 与 NVIDIA AI Foundation 模型支持的聊天模型和嵌入模型的集成，托管于 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 用量	对数概率
✅	✅	✅	❌	❌	✅	✅	✅	❌

安装包

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 — efficient reasoning and agentic tasks
llm = ChatNVIDIA(model="nvidia/nemotron-3-nano-30b-a3b")

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

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

# connect to a chat NIM running at localhost:8000, specifying a model
llm = ChatNVIDIA(base_url="http://localhost:8000/v1", model="meta/llama3-8b-instruct")

# connect to an embedding NIM running at localhost:8080
embedder = NVIDIAEmbeddings(base_url="http://localhost:8080/v1")

# connect to a reranking NIM running at localhost:2016
ranker = NVIDIARerank(base_url="http://localhost:2016/v1")

流式传输、批量处理与异步

这些模型原生支持流式传输，与所有 LangChain LLM 一样，它们提供批量处理方法以处理并发请求，以及用于 invoke、stream 和 batch 的异步方法。以下是几个示例。

print(llm.batch(["What's 2*3?", "What's 2*6?"]))
# Or via the async 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?"):
    # Show the token separations
    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-nano-30b-a3b") | 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="meta/llama3-8b-instruct") | 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"  ## Large Image
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

## Works for simpler images. For larger images, see actual implementation
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 独特地支持将图像作为 base64 图像内联在 <img/> HTML 标签中。虽然这与其他 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。以下示例将 LangChain RunnableWithMessageHistory 应用于 mistralai/mixtral-8x22b-instruct-v0.1 模型。

pip install -qU langchain

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

# store is a dictionary that maps session IDs to their corresponding chat histories.
store = {}  # memory is maintained outside the chain


# A function that returns the chat history for a given session 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="mistralai/mixtral-8x22b-instruct-v0.1",
    temperature=0.1,
    max_tokens=100,
    top_p=1.0,
)

#  Define a RunnableConfig object, with a `configurable` key. session_id determines thread
config = {"configurable": {"session_id": "1"}}

conversation = RunnableWithMessageHistory(
    chat,
    get_session_history,
)

conversation.invoke(
    "Hi I'm Srijan Dubey.",  # input or query
    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 以避免冗余计算，并通过数据缓存到经济高效的存储层来扩展 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"

# Standard ChatNVIDIA — no Dynamo hints
llm_standard = ChatNVIDIA(base_url=BASE_URL, model=MODEL)

# ChatNVIDIADynamo — identical interface, automatically injects 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 提示。当某个模型实例始终服务于特定角色时（例如高优先级交互助手与低优先级后台摘要器），这非常有用。

# High-priority: short responses, latency-critical
llm_critical = ChatNVIDIADynamo(
    base_url=BASE_URL,
    model=MODEL,
    osl=20,
    priority=0,
    latency_sensitivity=10.0,
)

# Low-priority: long responses, latency-tolerant
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 参考：python.langchain.com/api_reference/nvidia_ai_endpoints/chat_models/langchain_nvidia_ai_endpoints.chat_models.ChatNVIDIA.html

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 参考

相关主题