Node.js를 위한 LangChain 개요

LangChain.js는 TypeScript 및 Node.js 환경에서 LLM (Large Language Model) 애플리케이션을 구축하기 위한 프레임워크입니다. 이 프레임워크는 프롬프트 (prompts), 모델 (models), 도구 (tools), 문서 로더 (document loaders), 임베딩 (embeddings), 그리고 리트리버 (retrievers)를 재사용 가능한 파이프라인 (pipelines)과 에이전트 (agents)로 연결하는 방식을 표준화합니다.

LangChain, Deep Agents, LangGraph, 그리고 LangSmith

프로젝트	역할
LangChain	상위 수준 API: LCEL 체인 (chains), createAgent, 로더 (loaders), 리트리버 (retrievers)
...

복잡한 다단계 작업을 즉시 수행하려면 Deep Agents를 사용하세요. 미들웨어 (middleware)와 함께 구성할 최소한의 하네스 (harness)가 필요할 때는 LangChain의 createAgent를 사용하세요. 사용자 정의 상태 저장 워크플로 (stateful workflows), 분기 (branching), 또는 에이전트 루프 (agent loop)에 대한 세밀한 제어가 필요할 때는 LangGraph를 사용하세요.

패키지 (Packages)

먼저 핵심 패키지를 설치하세요 (설치 가이드):

npm i langchain @langchain/core @langchain/openai zod

공급자(Provider)별 통합 패키지는 별도의 패키지로 존재합니다:

• langchain - createAgent, tool, 그리고 상위 수준의 체인 헬퍼 (chain helpers)
• zod - tool()로 도구를 정의할 때 사용하는 도구 입력 스키마 (tool input schemas)
• @langchain/core - 프롬프트 (prompts), 출력 파서 (output parsers), Runnable 인터페이스, LCEL
• @langchain/openai - ChatOpenAI, OpenAIEmbeddings
• @langchain/textsplitters - 문서 청킹 (document chunking) (RAG 포스트에서 사용됨))
• 기타 공급자 및 도구를 위한 독립형 통합 패키지 (통합 페이지 참조)

원시 API (Raw API) 접근에 대해서는 Chat Completions 및 OpenAI Responses API 포스트를 참조하세요. 제공자 중립적인 (provider-agnostic) 텍스트 및 에이전트 (agents)에 대해서는 Vercel AI SDK 및 OpenAI Agents SDK 포스트를 참조하세요.

LangChain을 사용하는 시점

도구	최적의 용도
원시 openai 패키지	최소한의 호출, 완전한 제어, 가장 낮은 추상화
...

RAG (Retrieval-Augmented Generation) 또는 다단계 LLM 파이프라인 (pipelines)이 몇 번의 수동 API 호출 수준을 넘어 확장될 때 LangChain을 고려하세요.

사전 요구 사항

• OpenAI 계정
• 생성된 API 키
• 결제 활성화
• Node.js 버전 26
• langchain, @langchain/core, @langchain/openai, 그리고 zod 설치
• 환경 변수에 OPENAI_API_KEY 설정

핵심 개념 (Core concepts)

Document (문서) - 선택적 메타데이터 (metadata)를 포함하는 텍스트 청크 (chunk)입니다. 로더 (Loaders)는 Document 인스턴스를 생성하며, 스플리터 (splitters)는 긴 소스를 검색에 용이한 조각으로 나눕니다.

import { Document } from '@langchain/core/documents';

const doc = new Document({
...

Runnable (러너블) - .invoke(), .stream(), 또는 .batch() 메서드를 가진 모든 컴포넌트입니다. 프롬프트 (Prompts), 모델 (models), 파서 (parsers), 그리고 조합된 체인 (composed chains)은 모두 Runnable입니다.

LCEL (LangChain Expression Language) - .pipe()를 사용하여 Runnable을 체이닝 (chaining)합니다. 데이터는 왼쪽에서 오른쪽으로 흐릅니다: 프롬프트 (prompt) → 모델 (model) → 파서 (parser). 체인 내의 모든 Runnable에는 동일한 .invoke(), .stream(), .batch() 인터페이스가 적용됩니다.

import { ChatPromptTemplate } from '@langchain/core/prompts';
import { StringOutputParser } from '@langchain/core/output_parsers';
import { ChatOpenAI } from '@langchain/openai';
...

Agents (에이전트) - LangChain의 현재 고수준 에이전트 API는 createAgent입니다. 모델 문자열 또는 채팅 모델 (chat model), 선택적 도구 (tools, zod 스키마 포함), 그리고 대화 메모리 (conversation memory)를 위한 선택적 체크포인터 (checkpointer, @langchain/langgraph)를 전달합니다.

import { createAgent } from 'langchain';

const agent = createAgent({
...

LangChain이 할 수 있는 일

• 문서 로드 및 분할 (Load and split documents) - PDF, HTML, CSV, 디렉토리; 토큰(token) 또는 문자(character) 기반 분할기 (splitters)
• 임베딩 (Embeddings) 및 벡터 스토어 (vector stores) - pgvector, Pinecone, Chroma 등을 활용한 OpenAI 임베딩 (embeddings)
• 리트리버 (Retrievers) 및 RAG 체인 (RAG chains) - 관련 컨텍스트 (context)를 가져온 후 모델 호출 (pgvector를 활용한 RAG 포스트)
• 대화 메모리 (Conversation memory) - @langchain/langgraph 체크포인터 (checkpointers) 및 thread_id를 통한 단기 메모리 (short-term memory); 스토어 (stores)를 통한 장기 메모리 (long-term memory)
• 도구 (Tools) 및 에이전트 (agents) - 도구 (tools) 및 미들웨어 (middleware)를 포함한 createAgent; 프로덕션용 에이전트 (agents)의 경우 Vercel AI SDK 에이전트 포스트 또는 OpenAI Agents SDK 포스트를 선호할 수도 있습니다.
• 관측 가능성 (Observability) - LangSmith를 통한 실행 추적 (LANGSMITH_TRACING=true); 선택 사항인 LangSmith Engine은 추적을 모니터링하고 문제를 식별합니다.

스트리밍 (Streaming) 및 배치 (batch)

동일한 LCEL 체인 (chain)은 스트리밍 (streaming) 및 배치 (batch) 호출을 지원합니다:

for await (const chunk of await chain.stream({ question: 'What is LCEL?' })) {
  process.stdout.write(chunk);
}
...

데모 (Demo)

이 포스트를 위한 실행 가능한 LCEL 스크립트는 langchain-overview-nodejs-demo 폴더에 있습니다. 코드 데모 (code demos)를 통해 접속할 수 있습니다.