LangFlow 완전 가이드 1편 — 개요, 핵심 개념, 환경 세팅

LangFlow가 뭔가

AI 파이프라인을 코드로 짜면 이렇게 돼요.

from langchain.document_loaders import PyPDFLoader
from langchain.text_splitter import RecursiveCharacterTextSplitter
from langchain.embeddings import OpenAIEmbeddings
from langchain.vectorstores import Chroma
from langchain.chains import RetrievalQA
from langchain.chat_models import ChatAnthropic
from langchain.memory import ConversationBufferMemory
# ... 계속

loader = PyPDFLoader("document.pdf")
docs = loader.load()
splitter = RecursiveCharacterTextSplitter(chunk_size=1000, overlap=200)
chunks = splitter.split_documents(docs)
embeddings = OpenAIEmbeddings()
vectorstore = Chroma.from_documents(chunks, embeddings)
retriever = vectorstore.as_retriever()
memory = ConversationBufferMemory()
llm = ChatAnthropic(model="claude-sonnet-4-6")
chain = RetrievalQA.from_chain_type(llm=llm, retriever=retriever)
# ... 에러 나면 어디서 났는지 추적
# ... 모델 바꾸면 코드 다시 작성
# ... 파이프라인 구조 바꾸면 의존성 전부 수정

LangFlow로 똑같은 걸 만들면:

브라우저 열기
→ 컴포넌트 드래그
→ 선으로 연결
→ Run 버튼

코드 한 줄 없이 동일한 RAG 파이프라인이 완성돼요.

---

LangFlow는 LangChain/LangGraph 위에 올라가는 시각적 로우코드 빌더예요.

드래그앤드롭으로 AI 파이프라인을 설계하고, 클릭 한 번으로 REST API나 MCP 서버로 배포해요.

GitHub 스타: 146,000+
라이선스: MIT (완전 무료, 상업 사용 가능)
만든 곳: DataStax (Cassandra DB 회사)
출시: 2023년 → 3년 만에 14만 스타

---

LangChain이랑 관계

헷갈리는 사람이 많아서 정리해요.

LangChain:
→ AI 파이프라인 구축 Python 라이브러리
→ LLM, 벡터DB, 툴을 코드로 연결
→ 개발자용

LangFlow:
→ LangChain을 시각적으로 쓰는 도구
→ LangChain 컴포넌트들이 드래그앤드롭 노드로
→ 개발자 + 비개발자 모두 가능

관계:
LangFlow = LangChain의 GUI
LangChain 없이 LangFlow 없음
LangFlow 없어도 LangChain 가능 (코드로)

LangFlow에서 만든 플로우는 내부적으로 LangChain 코드로 실행돼요. 화면에서 보이는 건 캔버스지만, 실제로는 Python이 돌아가는 거예요.

---

어떤 상황에서 쓰는가

써야 할 때

1. 빠른 프로토타입이 필요할 때
   → LangChain 코드로 3일 → LangFlow로 3시간

2. 파이프라인 구조를 자주 바꿀 때
   → 컴포넌트 연결만 바꾸면 됨
   → 코드 리팩토링 없음

3. 팀에 비개발자가 있을 때
   → 기획자, PM도 파이프라인 이해하고 수정 가능

4. 여러 LLM/벡터DB를 실험해볼 때
   → 컴포넌트 하나 바꾸면 모델 교체 완료

5. RAG 앱을 빠르게 내부 도구로 만들 때
   → 배포까지 당일 가능

6. 아이디어 검증 단계
   → "이 파이프라인이 실제로 작동하는지" 확인

쓰지 말아야 할 때

1. 복잡한 비즈니스 로직이 필요할 때
   → if/else 분기, 루프가 복잡한 경우
   → 직접 코드 짜는 게 낫다

2. 고성능 프로덕션 환경
   → 대용량 트래픽, 낮은 지연 요구
   → LangChain 직접 + FastAPI가 더 유리

3. 세밀한 커스터마이징 필요
   → 컴포넌트 내부 동작을 바꿔야 할 때
   → Python 코드가 더 자유로움

---

핵심 개념

플로우 (Flow)

AI 파이프라인 전체 = 플로우
캔버스에 그려진 컴포넌트들의 연결 구조

예:
[PDF 파일] → [텍스트 분할] → [임베딩] → [벡터DB]
                                              ↓
[사용자 질문] ──────────────────────────→ [LLM] → [답변]

이게 하나의 플로우

컴포넌트 (Component)

플로우를 구성하는 각 블록
각각 특정 역할을 담당

입력 포트(왼쪽):  데이터를 받는 곳 ●
출력 포트(오른쪽): 데이터를 내보내는 곳 ●

포트 색깔 = 데이터 타입
→ 같은 색깔끼리만 연결 가능

컴포넌트 종류

Inputs/Outputs (입출력):
- Chat Input    ← 사용자 메시지
- Chat Output   ← LLM 응답
- Text Input    ← 고정 텍스트
- File          ← 파일 업로드

Models (LLM):
- Language Model    ← Claude, GPT, Gemini 통합 컴포넌트
- Anthropic         ← Claude 전용
- OpenAI            ← GPT 전용
- Ollama            ← 로컬 모델

Vector Stores (벡터DB):
- Chroma            ← 로컬, 무료
- Pinecone          ← 클라우드
- Weaviate
- Qdrant

Document Loaders (문서 로더):
- Read File         ← PDF, DOCX, TXT 등
- URL               ← 웹페이지 로드
- YouTube           ← 자막 추출
- GitHub            ← 레포지토리 로드

Processing (처리):
- Split Text        ← 텍스트 청킹
- Embedding Model   ← 임베딩 생성
- Prompt Template   ← 프롬프트 설계
- Parse Data        ← 데이터 변환

Agents (에이전트):
- Agent             ← LangGraph 기반 에이전트
- MCP Tools         ← MCP 서버 연결

Memory (메모리):
- Chat Memory       ← 대화 히스토리
- External Memory   ← 외부 저장소

---

아키텍처

내부 구조를 알면 쓸 때 더 잘 이해돼요.

[브라우저 캔버스]
      ↓ JSON 그래프 명세
[FastAPI 백엔드]
      ↓
[그래프 실행 엔진]
      ↓
[LangChain/LangGraph 실행]
      ↓
[LLM API / 벡터DB / 외부 서비스]

프론트엔드: React 19 + React Flow
백엔드:     FastAPI + Python
실행엔진:   LangChain + LangGraph
데이터베이스: SQLite (로컬) / PostgreSQL (프로덕션)

플로우를 캔버스에서 그리면 JSON으로 직렬화돼서 백엔드로 전달되고, 백엔드가 이걸 DAG(방향 비순환 그래프)로 해석해서 컴포넌트를 순서대로 실행해요.

---

환경 세팅

방법 1 — pip 설치 (권장)

# Python 3.10 이상 필요
python --version

# 가상환경 만들기 (권장)
python -m venv langflow-env
source langflow-env/bin/activate   # Mac/Linux
# langflow-env\Scripts\activate   # Windows

# 설치
pip install langflow

# 실행
langflow run

실행하면:

╭─────────────────────────────────────────╮
│  Welcome to ⛓ Langflow                  │
│                                          │
│  Access http://127.0.0.1:7860           │
╰─────────────────────────────────────────╯

브라우저에서 http://localhost:7860 접속하면 끝.

방법 2 — Docker (서버 배포용)

docker run \
  -p 7860:7860 \
  -v $(pwd)/langflow-data:/app/langflow \
  langflowai/langflow:latest

데이터가 langflow-data 폴더에 영구 저장돼요.

방법 3 — 클라우드 (설치 없이 바로)

1. langflow.new 접속
2. 구글 계정으로 로그인
3. 무료 플랜으로 바로 시작

무료 플랜 제한:
→ 플로우 5개
→ 월 1,000회 실행
→ 팀 기능 없음

개인 프로토타입은 무료 플랜으로 충분해요.

---

API 키 설정

LangFlow 안에서 API 키를 관리해요. 코드에 하드코딩 불필요.

우상단 프로필 아이콘
→ Settings
→ Global Variables
→ + Add Variable
→ 이름: ANTHROPIC_API_KEY
→ 값: sk-ant-xxxxx
→ Type: Credential
→ Save

이후 컴포넌트에서 API 키 필드 클릭하면 자동으로 불러와요.

주요 API 키:

Anthropic:  sk-ant-xxxxx  → Claude 모델
OpenAI:     sk-xxxxx      → GPT, 임베딩
Google:     AIzaxxx       → Gemini
Cohere:     cohere-xxxxx  → 임베딩, 무료 티어 있음

---

인터페이스 완전 정복

┌─────────────────────────────────────────────┐
│  [프로젝트명] [Playground] [API] [Share]    │  ← 상단 메뉴
├──────────┬──────────────────────────────────┤
│          │                                  │
│ 사이드바  │         캔버스                  │
│          │                                  │
│ Search   │   [컴포넌트] ─── [컴포넌트]     │
│ Core     │        │                         │
│ Bundles  │   [컴포넌트] ─── [컴포넌트]     │
│          │                                  │
│          │                         [Zoom]   │
└──────────┴──────────────────────────────────┘

사이드바 탭:

Search:  컴포넌트 검색
Core:    기본 컴포넌트 (Inputs, Models, Tools 등)
Bundles: 서비스별 묶음 (Anthropic, OpenAI, Google 등)
MCP:     MCP 서버 연결

캔버스 조작:

드래그:        컴포넌트 이동
스크롤:        줌 인/아웃
우클릭:        컨텍스트 메뉴
Ctrl+Z:       실행 취소
컴포넌트 클릭: 오른쪽에 설정 패널 열림

상단 메뉴:

Playground: 채팅 창으로 바로 테스트
API:        배포용 코드 자동 생성
            (Python, JavaScript, cURL 전부)
Share:      플로우 공유 링크 생성
Run:        전체 플로우 실행

---

2편 예고

다음 편에서는 실제로 만들어봐요.

2편 — 기본 튜토리얼:
- 기본 챗봇 (10분)
- PDF RAG 챗봇 (20분)
- REST API로 배포 (5분)
- Python에서 호출하기

---

📌 다음 글: LangFlow 2편 — 챗봇부터 PDF RAG까지

LangFlow 완전 가이드 2편 — 기본 튜토리얼 : 챗봇부터 PDF RAG까지