NVIDIA

NVIDIA (NVIDIA provider integration)

LangChain Python에서 NVIDIA를 통합하는 방법을 설명할게요. LangChain과 NVIDIA는 에이전트 스택 전반에서 파트너십을 맺고 있어요. OpenShell을 이용한 샌드박스 에이전트, LangGraph 가속 프리미티브, NeMo Agent Toolkit 최적화, 포스트 트레이닝 에이전트 워크플로우, NeMo Switchyard를 통한 모델 라우팅, 풀스택 블루프린트까지 폭넓게 지원돼요. 아래에서 컴포넌트별로 하나씩 살펴볼게요.

출처: 공식문서

컴포넌트 (Components)

langchain-nvidia-ai-endpoints 패키지는 NVIDIA AI에서 제공하는 채팅, 임베딩, 리랭킹, 검색용 LangChain 통합을 제공해요. 여기에는 에이전틱 AI용으로 만들어진 NVIDIA의 오픈 모델군 Nemotron과 NVIDIA API Catalog의 수백 개 커뮤니티 모델이 포함돼요.

모델은 표준 OpenAI 호환 API를 노출하고 TensorRT-LLM으로 NVIDIA 하드웨어에서 최고 처리량을 내도록 최적화된 컨테이너 이미지인 NVIDIA NIM 마이크로서비스에서 실행돼요. 호스팅되는 API Catalog로 접근하거나 온프레미스에서 자체 호스팅할 수 있어요.

컴포넌트	클래스	설명
채팅	ChatNVIDIA	NVIDIA 호스팅 모델 또는 로컬 NIM으로 채팅 완성
채팅 (Dynamo)	ChatNVIDIADynamo	Dynamo 배포용 KV 캐시 라우팅 힌트를 가진 ChatNVIDIA
임베딩	NVIDIAEmbeddings	시맨틱 검색과 RAG용 밀집 벡터 임베딩
리랭킹	NVIDIARerank	쿼리 관련성 기준 문서 리랭킹
검색	NVIDIARAGRetriever	NVIDIA RAG Blueprint 서버에서 검색

채팅: ChatNVIDIA

ChatNVIDIA는 NVIDIA 호스팅 모델과 로컬 NIM 배포에 대해 채팅 완성을 제공해요. 도구 호출, 구조화 출력, 이미지 입력, 스트리밍을 지원해요.

설치 (Install)

pip install -qU langchain-nvidia-ai-endpoints

NVIDIA API Catalog 접근

NVIDIA API Catalog에서 무료 계정을 만들고 로그인해요. 프로필 아이콘을 클릭한 뒤 API Keys > Generate API Key를 눌러 키를 생성하고 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

Nemotron: 에이전틱 AI용 주요 모델

Nemotron은 에이전틱 AI를 위해 설계된 NVIDIA의 오픈 모델군이에요. 하이브리드 Mamba-Transformer mixture-of-experts 아키텍처를 사용해 최고 수준의 벤치마크 성능과 높은 처리량, 최대 1M 토큰 컨텍스트 윈도우를 지원해요. Nemotron 모델 가중치, 학습 데이터, 구현 레시피는 NVIDIA Open Model License 하에 공개돼 있어요.

from langchain_nvidia_ai_endpoints import ChatNVIDIA

# Nemotron 3 Ultra - frontier reasoning and agentic workflows
llm = ChatNVIDIA(model="nvidia/nemotron-3-ultra-550b-a55b")
result = llm.invoke("Plan a three-step research workflow for competitive analysis.")
print(result.content)

도구 호출, 멀티모달 입력, Nemotron 특화 예제를 포함한 전체 문서는 ChatNVIDIA 통합 페이지를 참고해요.

채팅: ChatNVIDIADynamo

ChatNVIDIADynamo는 NVIDIA Dynamo 배포용으로 ChatNVIDIA를 대체하는 드롭인 방식이에요. 모든 요청에 KV 캐시 라우팅 힌트를 자동으로 주입해서 Dynamo 스케줄러가 메모리 할당, 로드 라우팅, 요청 우선순위를 최적화하게 해요.

from langchain_nvidia_ai_endpoints import ChatNVIDIADynamo

llm = ChatNVIDIADynamo(
    base_url="http://localhost:8099/v1",
    model="nvidia/nemotron-3-ultra-550b-a55b",
    osl=512,             # expected output sequence length (tokens)
    iat=250,             # expected inter-arrival time (ms)
    latency_sensitivity=1.0,
    priority=1,
)
result = llm.invoke("Summarize KV cache routing in one sentence.")
print(result.content)

호출별 오버라이드와 스트리밍을 포함한 전체 ChatNVIDIADynamo 레퍼런스는 ChatNVIDIA 통합 페이지를 참고해요.

임베딩: NVIDIAEmbeddings

NVIDIAEmbeddings는 시맨틱 검색과 RAG 파이프라인에 사용할 밀집 벡터 임베딩을 생성해요.

from langchain_nvidia_ai_endpoints import NVIDIAEmbeddings

embedder = NVIDIAEmbeddings(model="NV-Embed-QA")
embedder.embed_query("What's the temperature today?")

전체 문서는 NVIDIAEmbeddings 통합 페이지를 참고해요.

리랭킹: NVIDIARerank

NVIDIARerank는 NeMo Retriever 리랭킹 NIM을 사용해 쿼리 관련성 기준으로 문서 목록을 리랭킹해요.

from langchain_core.documents import Document
from langchain_nvidia_ai_endpoints import NVIDIARerank

ranker = NVIDIARerank(model="nvidia/llama-3.2-nv-rerankqa-1b-v1")
docs = ranker.compress_documents(
    query="What is GPU memory bandwidth?",
    documents=[Document(page_content=p) for p in passages],
)

검색: NVIDIARAGRetriever

NVIDIARAGRetriever는 실행 중인 NVIDIA RAG Blueprint 서버에 LangChain을 연결하고 /v1/search 엔드포인트로 관련 문서를 검색해요. 리랭킹, 쿼리 재작성, 메타데이터 필터링을 지원해요.

from langchain_nvidia_ai_endpoints import NVIDIARAGRetriever

retriever = NVIDIARAGRetriever(base_url="http://localhost:8081", k=4)
docs = retriever.invoke("What is NVIDIA NIM?")

전체 문서는 NVIDIARAGRetriever 통합 페이지를 참고해요.

NVIDIA NIM 마이크로서비스로 자체 호스팅

AI 애플리케이션을 배포할 준비가 되면 NVIDIA NIM으로 모델을 자체 호스팅할 수 있어요. 자세한 내용은 NVIDIA NIM Microservices 문서를 참고해요.

from langchain_nvidia_ai_endpoints import ChatNVIDIA, NVIDIAEmbeddings, NVIDIARerank

# localhost:8000에서 실행 중인 채팅 NIM에 연결, 모델 지정
llm = ChatNVIDIA(base_url="http://localhost:8000/v1", model="nvidia/nemotron-3-ultra-550b-a55b")
# localhost:8080에서 실행 중인 임베딩 NIM에 연결
embedder = NVIDIAEmbeddings(base_url="http://localhost:8080/v1")
# localhost:2016에서 실행 중인 리랭킹 NIM에 연결
ranker = NVIDIARerank(base_url="http://localhost:2016/v1")

OpenShell로 샌드박스 에이전트 (Sandboxed Agents with OpenShell)

OpenShell은 LangChain 에이전트에 코드 실행, 파일 접근, 프로세스 권한, 네트워크 이그레스(egress)를 위한 정책 기반 Linux 샌드박스를 제공해요. 데이터 검사, 코드 작성, 명령 실행, 로컬 리소스에 대한 도구 사용이 필요하면서도 실행 환경을 호스트와 격리하고 싶은 딥 에이전트에 유용해요.

LangChain 애플리케이션에서는 langchain-nvidia-openshell 패키지가 OpenShell을 Deep Agents 샌드박스 인터페이스에 맞춰줘요. 에이전트는 ChatNVIDIA로 호스트에서 실행하고, 도구 실행은 OpenShellSandbox 백엔드를 통해 OpenShell 샌드박스로 디스패치돼요.

리소스: LangChain NVIDIA samples(OpenShell 사고 분석 에이전트 포함), OpenShell Deep Agent(NVIDIA Nemotron 구동 참조 코딩 에이전트), langchain-nvidia-openshell(Python 어댑터, 설정 노트, 정책 가이드, 노트북 워크스루).

import openshell
from deepagents import create_deep_agent
from langchain_nvidia_ai_endpoints import ChatNVIDIA
from langchain_nvidia_openshell import OpenShellSandbox

with openshell.Sandbox() as sandbox:
    backend = OpenShellSandbox(sandbox=sandbox)
    agent = create_deep_agent(
        model=ChatNVIDIA(model="nvidia/nemotron-3-ultra-550b-a55b"),
        system_prompt="You are a careful coding agent.",
        backend=backend,
    )

NVIDIA로 LangGraph 가속화 (Accelerate LangGraph with NVIDIA)

langchain-nvidia-langgraph 패키지는 LangGraph 그래프를 위한 NVIDIA 최적화 실행 전략을 제공해요. 컴파일 시점에 적용되는 두 가지 상호 보완 최적화가 있어요:

• 병렬 실행 (Parallel execution): 독립적인 노드를 자동 식별해 동시에 실행해 불필요한 순차 병목을 제거해요.
• 스펙큘레이티브 실행 (Speculative execution): 조건부 엣지의 양쪽 분기를 동시에 실행하고, 라우팅 조건이 결정되면 틀린 분기를 버려요.

두 최적화 모두 노드 로직이나 그래프 엣지 변경이 필요 없어요.

설치 (Install)

pip install -qU langchain-nvidia-langgraph

병렬 실행 (Parallel execution)

LangGraph의 StateGraph를 langchain_nvidia_langgraph.graph의 StateGraph로 바꿔주면 나머지 그래프 정의는 그대로예요.

from langchain_nvidia_langgraph.graph import StateGraph, OptimizationConfig
from langgraph.graph import END
from typing import TypedDict

class AgentState(TypedDict):
  ...

graph = StateGraph(AgentState)
app = graph.compile(optimization=OptimizationConfig(enable_parallel=True))

또는 기존 StateGraph를 래핑해요.

from langgraph.graph import StateGraph as LangGraphStateGraph

graph = LangGraphStateGraph(AgentState)
app = with_app_compile(graph).compile(optimization=OptimizationConfig(enable_parallel=True))

데코레이터로 어떤 노드가 최적화에 참여할지 명시적으로 제어할 수 있어요.

from langchain_nvidia_langgraph.graph import sequential, depends_on, speculation_unsafe

# 노드가 병렬화되지 않도록 방지 (예: 공유 상태에 쓰는 경우)
@sequential
def write_to_db(state):
    ...

# 그래프 엣지에 표현되지 않은 의존성 선언
@depends_on("write_to_db")
def next_action(state):
    ...

스펙큘레이티브 실행 (Speculative execution)

컴파일 시점에 OptimizationConfig로 스펙큘레이션을 활성화해요. 실행기가 조건부 분기를 병렬로 실행하고 라우팅 결정과 일치하는 결과를 유지해요.

app = graph.compile(optimization=OptimizationConfig(enable_speculation=True))

LangSmith 텔레메트리를 이용한 NeMo Agent Toolkit 최적화

NVIDIA NeMo Agent Toolkit은 에이전트를 구축·프로파일링·최적화하는 오픈소스 AI 툴킷이에요. 개발자는 LangChain을 최소한의 코드 변경으로 NeMo Agent Toolkit과 함께 사용해 프로파일링, 평가, GPU 용량 계획, 자동 최적화를 활성화할 수 있어요. NeMo Agent Toolkit은 LangSmith와 상호운용돼요.

• Get Started with NeMo Agent Toolkit and LangChain
• Optimize LangChain with NeMo Agent Toolkit and LangSmith

포스트 트레이닝 에이전트 워크플로우 (Post-training Agent Workflows)

NVIDIA NeMo Gym은 에이전트 시스템용 포스트 트레이닝 워크플로우를 제공하며, LangGraph 에이전트를 Responses API 스타일 학습 데이터·평가 루프와 짝지은 예제가 포함돼요. 초기 프롬프팅과 하네스 튜닝 이후 에이전트 동작을 개선하고 싶을 때, 특히 도구 사용과 다단계 추론 작업에 이 워크플로우를 사용해요.

• NeMo Gym LangGraph agent example

NeMo Switchyard로 모델 라우팅 (Model Routing with NeMo Switchyard)

실험적인 langchain-nvidia-switchyard 패키지는 딥 에이전트가 NeMo Switchyard 알고리즘으로 기존 LangChain 채팅 모델들 사이에서 각 모델 호출을 라우팅하게 해줘요. Deep Agents가 에이전트 루프, 도구, 상태, 미들웨어를 계속 관리하는 동안 하나의 에이전트 뒤에서 효율적인 모델과 능력 있는 모델을 결합하는 데 사용해요.

이 통합이 제공하는 것:

• 모델 무관 타깃: 모든 LangChain BaseChatModel을 Switchyard 타깃으로 적용
• 플러그 가능 라우팅: 설치된 nemo-switchyard Python 바인딩이 노출하는 모든 알고리즘 제공 (LLM 작업 분류, 신호 기반 Stage 라우팅 포함)
• 에이전트 호환 미들웨어: 모델 호출을 라우팅하면서 Deep Agents 도구 바인딩, 콜백, LangChain 추적, 구조화 출력 유지
• 결정 메타데이터: 반환된 각 AIMessage에서 선택된 모델과 완전한 순서 라우팅 트레이스를 검사

소스에서 설치 (Install from source)

이 패키지는 Python 3.12 이상이 필요해요. Switchyard의 libsy Python 바인딩을 소스 트리에서 빌드한 뒤 OpenRouter와 Deep Agents 의존성과 함께 통합을 설치해요.

git clone https://github.com/NVIDIA-NeMo/Switchyard.git
python -m pip install -e ./Switchyard
git clone https://github.com/langchain-ai/langchain-nvidia.git
python -m pip install -e "./langchain-nvidia/libs/switchyard[openrouter]"

딥 에이전트 라우팅 (Route a deep agent)

두 LangChain 채팅 모델을 만들고 Switchyard 타깃으로 래핑한 뒤 라우팅 알고리즘을 SwitchyardRoutingMiddleware에 전달해요. stage_router에 전달하는 타깃의 순서가 중요해요 — capability 타깃을 먼저, efficient 타깃을 두 번째로 넘겨요.

from deepagents import create_deep_agent
from langchain_openrouter import ChatOpenRouter
from switchyard.libsy import LlmTarget, algorithms
from langchain_nvidia_switchyard import LangChainLlmClient, SwitchyardRoutingMiddleware

efficient_model = ChatOpenRouter(model="nvidia/nemotron-3-ultra-550b-a55b")
capable_model = ChatOpenRouter(model="anthropic/claude-sonnet-4.6")

router = algorithms.stage_router(
    LlmTarget("capable", LangChainLlmClient(capable_model)),
    LlmTarget("efficient", LangChainLlmClient(efficient_model)),
    picker="efficient_first",
    confidence_threshold=0.5,
    recent_window=3,
)

agent = create_deep_agent(
    model=efficient_model,
    middleware=[SwitchyardRoutingMiddleware(router)],
)

result = await agent.ainvoke({
    "messages": [
        {
            "role": "user",
            "content": "Summarize the important files in this project.",
        }
    ]
})

고급 라우팅 설정, 지원되는 요청·응답 데이터, 현재 제한 사항은 langchain-nvidia-switchyard 패키지 README를 참고해요.

풀스택 블루프린트 (Full Stack Blueprints)

NVIDIA와 LangChain은 모든 컴포넌트를 결합하는 방법을 보여주는 풀스택 예제에서 협력했어요. 프로덕션 레디니스에 초점을 맞춘 두 가지 엔터프라이즈 사용 사례가 있어요:

• NVIDIA AI-Q: LangChain Deep Agents를 사용해 엔터프라이즈 데이터 소스 전반의 딥 리서치용 블루프린트
• NVIDIA VSS: LangChain과 LangGraph를 사용한 비디오 검색·요약용 블루프린트

더 알아보기 (Learn more)

• langchain-nvidia-ai-endpoints 패키지 README
• langchain-nvidia-langgraph 패키지
• langchain-nvidia-switchyard 패키지
• langchain-nvidia-openshell 패키지
• Nemotron 모델군
• LangChain NVIDIA samples
• OpenShell Deep Agent
• NeMo Gym LangGraph agent example
• NVIDIA NIM 마이크로서비스 개요
• ChatNVIDIA 모델
• NVIDIA Dynamo