NodeLLM

Node.js용 공급자 독립적인 LLM 런타임(The Provider-Agnostic LLM Runtime for Node.js).

NodeLLM은 안정적이고, 테스트 가능하며, 공급자 독립적인 AI 시스템을 구축하도록 설계된 백엔드 오케스트레이션 레이어입니다.

여러 LLM 공급자를 통합하는 과정은 종종 다양한 SDK, API 스타일, 업데이트 주기를 다루는 것을 의미합니다. NodeLLM은 OpenAI, Gemini, Anthropic, DeepSeek, OpenRouter, xAI, Ollama 등 여러 공급자의 540개 이상의 모델에 대해 일관성을 유지하는 단일하고 통합된 API를 제공하며, 이 구조는 공급자가 변경되어도 변함이 없습니다.

License: MIT

TypeScript

npm install @node-llm/core

🛑 NodeLLM이 아닌 것 (What NodeLLM is NOT)

NodeLLM을 이해하려면, 그것이 무엇이 아닌지를 이해해야 합니다.

NodeLLM은 다음이 아닙니다:

• ❌ 벤더 SDK를 감싼 단순한 Wrapper: (openai나 @anthropic-ai/sdk와 같은)
• ❌ UI 스트리밍 라이브러리: (Vercel AI SDK와 같은)
• ❌ 프롬프트 전용 프레임워크

NodeLLM은 다음입니다:

• ✅ 백엔드 런타임(Backend Runtime): 워커, cron job, 에이전트 및 API 서버를 위해 설계되었습니다.
• ✅ 공급자 독립적(Provider Agnostic): 코드 재작성 없이 설정만으로 공급자를 전환합니다.
• ✅ 계약 기반(Contract Driven): 모든 모델에 걸쳐 Tool과 Streaming의 동일한 동작을 보장합니다.
• ✅ 인프라 우선(Infrastructure First): 평가(evals), 원격 측정(telemetry), 재시도(retries), 회로 차단(circuit breaking)을 위해 구축되었습니다.

🏗️ NodeLLM을 사용하는 이유? (Why NodeLLM?)

"인프라 우선" 접근 방식 (The "Infrastructure-First" Approach)

대부분의 AI SDK는 '사용자에게 빠르게 응답을 전달하는 것' (프론트엔드/엣지)에 최적화되어 있습니다. NodeLLM은 시스템 신뢰성 (백엔드)에 최적화되어 있습니다.

대부분의 AI SDK(예: Vercel AI SDK)가 프론트엔드 스트리밍(Next.js, React Server Components)에 중점적으로 최적화된 반면, NodeLLM은 백엔드를 위해 구축되었습니다.

• 추론 모델 (Reasoning Models): OpenAI o1/o3 및 Anthropic Thinking 모델을 기본 지원하며, 최고 수준의 토큰 추적이 가능합니다.
• 미들웨어 (Middlewares): 감사(auditing), 비용 추적, PII 마스킹 등을 위해 요청/응답을 가로채고 수정할 수 있습니다.
• ORM 및 영속성 (Persistence): 전체 대화 스레드, 도구 호출, 지연 시간 측정 지표를 데이터베이스에 자동으로 저장합니다.
• 결정론적 테스트 (Deterministic Testing): VCR 스타일의 테스트를 통해 LLM 상호 작용을 기록하고 재현할 수 있습니다.
• 엄격한 프로세스 보호 (Strict Process Protection): 멈춘 요청(hung requests)이 이벤트 루프를 지연시키는 것을 방지합니다.

전략적 목표 (Strategic Goals)

• 분리 (Decoupling): 비즈니스 로직을 AI 모델 버전의 급격한 변화로부터 격리시킵니다.
• 운영 안전성 (Production Safety): 회로 차단(circuit breaking), 마스킹, 감사 로깅에 대한 기본 지원을 제공합니다.
• 예측 가능성 (Predictability): 스트리밍, 구조화된 출력, 비전(vision)에 대한 통일된 정신 모델(Mental Model)을 제공합니다.

⚡ 아키텍처 경로 (The Architectural Path)

import { NodeLLM } from "@node-llm/core";

// 1. Zero-Config (NodeLLM이 NODELLM_PROVIDER 및 API 키를 자동으로 읽음)
...

🎯 실제 사례: 브랜드 인식 검사기 (Brand Perception Checker)

NodeLLM으로 구축됨 - 다중 공급자 AI 분석, 도구 호출, 구조화된 출력이 함께 작동합니다.

예제 보기 →

🤖 대표 기능: HR 챗봇 RAG (HR Chatbot RAG)

@node-llm/orm을 활용하고 실시간 스트리밍 및 RAG 아키텍처를 시연하는 운영 등급(production-grade) Next.js 애플리케이션입니다.

예제 보기 →

🔧 전략적 설정 (Strategic Configuration)

NodeLLM은 엔터프라이즈 사용을 위해 설계된 유연하고 지연 초기화(lazy-initialized) 설정 시스템을 제공합니다. 이는 ESM 환경에서 안전하며, 첫 요청이 있을 때만 해결되므로 일반적인 dotenv 레이스 컨디션 문제를 제거합니다.

// 다중 공급자 파이프라인에 권장
const llm = createLLM({
  openaiApiKey: process.env.OPENAI_API_KEY,
...

// 사용자 지정 엔드포인트 지원 (예: Azure 또는 LocalAI)
const llm = createLLM({
  openaiApiKey: process.env.AZURE_KEY,
...

전체 설정 가이드 →

🔮 기능 (Capabilities)

💬 통합 채팅 (Unified Chat)

모든 공급자(provider)마다 코드를 다시 작성하는 것을 멈추세요. NodeLLM은 입력과 출력을 단일하고 예측 가능한 정신 모델(mental model)로 정규화합니다.

import { NodeLLM } from "@node-llm/core";

// 환경 변수에서 NODELLM_PROVIDER 사용 (기본값: GPT-4o)
...

👁️ 스마트 비전 및 파일 (Smart Vision & Files)

이미지, PDF 또는 오디오 파일을 ask()와 stream() 모두에 직접 전달할 수 있습니다. 저희가 무거운 작업을 처리합니다: 원격 URL 가져오기, base64 인코딩 및 MIME 타입 매핑.

await chat.ask("이 인터페이스를 분석해 주세요", {
  files: ["./screenshot.png", "https://example.com/spec.pdf"]
});

🛠️ 자동 실행 도구 (Auto-Executing Tools)

도구를 한 번 정의하면 됩니다. NodeLLM이 재귀적 실행 루프(recursive execution loop)를 관리하여 컨트롤러 로직을 깔끔하게 유지합니다. 일반 채팅과 스트리밍 모두에서 원활하게 작동합니다!

import { Tool, z } from "@node-llm/core";

// 클래스 기반 DSL
...

전체 도구 호출 가이드 →

🔌 모델 컨텍스트 프로토콜 (Model Context Protocol, MCP)

업계 표준인 MCP를 사용하여 수백 개의 외부 데이터 소스 및 도구에 NodeLLM을 연결하세요. 도구, 리소스, 프롬프트 템플릿을 여러 서버에 동적으로 공유할 수 있습니다.

import { MCP } from "@node-llm/mcp";

// 모든 MCP 서버에 연결 (GitHub, Postgres, Slack 등)
...

전체 MCP 가이드 →

🔍 포괄적인 디버그 로깅 (Comprehensive Debug Logging)

모든 기능과 제공업체(provider)에 걸친 모든 API 요청 및 응답에 대한 상세 로깅을 활성화하세요:

// 환경 변수 설정
process.env.NODELLM_DEBUG = "true";

...

지원 범위: 채팅(Chat), 스트리밍(Streaming), 이미지(Images), 임베딩(Embeddings), 전사(Transcription), 유해성 검토(Moderation) - 모든 제공업체에서 지원!

✨ 구조화된 출력 (Structured Output)

Zod 스키마를 사용하여 타입 안전하고 검증된 JSON을 받으세요.

import { z } from "@node-llm/core";
const Product = z.object({ name: z.string(), price: z.number() });

...

🎨 이미지 생성 (Image Generation)

await NodeLLM.paint("비 오는 사이버펑크 도시");

🎤 오디오 전사 (Audio Transcription)

await NodeLLM.transcribe("meeting-recording.wav");

💾 영속성 계층 (Persistence Layer)

@node-llm/orm을 사용하여 채팅 기록, 도구 실행(tool executions), API 메트릭을 자동으로 추적합니다.

import { createChat } from "@node-llm/orm/prisma";

// 채팅 상태가 데이터베이스(Postgres/MySQL/SQLite)에 자동으로 저장됩니다.
...

⚡ 스코프 병렬 처리 (Scoped Parallelism)

격리된 컨텍스트를 사용하여 전역 설정 부작용 없이 여러 제공업체를 안전하게 병렬로 실행합니다.

const [gpt, claude] = await Promise.all([
  // 각 호출은 자체 격리 컨텍스트에서 분기됩니다
  NodeLLM.withProvider("openai").chat("gpt-4o").ask(prompt),
...

🧠 심층 추론 (Deep Reasoning)

.reasoning 필드를 사용하여 DeepSeek R1 또는 OpenAI o1/o3와 같은 모델의 사고 과정에 직접 접근합니다.

const res = await NodeLLM.chat("deepseek-reasoner").ask("이 논리 퍼즐을 풀어주세요");
console.log(res.reasoning); // Chain-of-thought (사고의 사슬)

🔒 에이전트형 제로 트러스트 (Agentic Zero Trust)

보안은 나중에 고려하는 것이 아닙니다. NodeLLM에는 인프라를 보호하기 위한 네이티브 **"Invisible Perimeter(가시적 경계)"**가 포함되어 있습니다:

• Redaction (마스킹): 로그에서 API 키를 자동으로 마스킹합니다.
• Guardrails (가드레일): Bedrock/Azure 안전 필터에 대한 통합 지원을 제공합니다.
• Auditing (감사): @node-llm/orm을 통해 전체 프롬프트/응답 추적 기능을 제공합니다.

📋 지원되는 Provider

📚 문서 및 설치

npm install @node-llm/core

전체 문서 보기 ↗

🍿 라이브 데모 사용해보기

작동하는 것을 보고 싶으신가요? 터미널에서 다음을 실행하세요:

git clone https://github.com/node-llm/node-llm.git
cd node-llm
npm install
...

🤝 기여 (Contributing)

기여를 환영합니다! 시작하는 방법에 대한 자세한 내용은 **기여 가이드**를 참조하세요.

🫶 크레딧 (Credits)

RubyLLM의 우아한 디자인에서 큰 영감을 받았습니다.

📄 라이선스 (License)

MIT © [NodeLLM contributors]