4 - Langflow UI 사용법 – 노드 연결·파라미터 설정·실행 흐름

Langflow 웹 UI는 좌측 사이드바 → 중앙 워크스페이스 → 우측 컨텍스트 패널의 3‑영역 레이아웃을 기반으로, 상단 툴바와 하단 상태바까지 총 5개의 주요 인터랙션 지점을 제공합니다.

---

4‑1. UI 구성 한눈에 보기

구역	주요 역할	핵심 요소	단축키·팁
상단 툴바	프로젝트·플로우 관리	▶ Run, 💬 Playground, 📁 My Projects, 저장 상태, Undo/Redo, Zoom	Ctrl + S 저장, Ctrl + Z/Y 실행 취소·복원
좌측 사이드바	컴포넌트 검색·추가	카테고리 트리, 검색창, 드래그 앤드 드롭	/ 검색창 포커스 → Enter로 삽입
중앙 워크스페이스	노드 배치·연결·그룹화	노드 카드, 엣지, 노트, 그룹, 스냅 가이드	Space + Drag: 패닝, G: 그룹화
우측 컨텍스트 패널	노드 설정·Playground·Logs·Publish	탭 전환형 패널	Esc: 패널 닫기, Tab: 최근 노드 설정
하단 상태바	실시간 알림·토큰 카운터	실행 상태, 오류 토스트, API 크레딧	오류 배너 클릭 시 해당 노드로 이동

빠른 시작 예시 : 새 플로우에서 Chat Input → Prompt → OpenAI → Chat Output 노드 네 개만 연결해도 GPT‑4 챗봇이 완성됩니다.

---

4‑2. 노드 추가·연결 절차

1️⃣ 컴포넌트 찾기

• / 키로 검색창에 곧바로 포커스를 주십시오.
• 검색어 입력 후 Enter를 누르면 사이드바 맨 위에 결과가 표시됩니다.
• Q 키를 누르면 카테고리 트리를 접었다 폈다 할 수 있어 긴 목록을 빠르게 탐색할 수 있습니다.

2️⃣ 드래그 & 드롭

• 노드를 워크스페이스로 끌어오면 스마트 스냅이 작동해 수평·수직 정렬을 돕습니다.
• Shift 키를 누른 채 여러 노드를 연속 배치하면 직전 노드의 출력과 새 노드의 입력이 자동으로 연결됩니다(Chain 모드).

3️⃣ 포트 연결

• 출력 포트에서 입력 포트로 선을 끌면 즉시 타입 검사가 이루어집니다.
  · 빨간선 → 타입 불일치 · 초록선 → 연결 가능
• 선을 끌다 Space 를 누르면 Quick‑Add 메뉴가 뜨며, 호환 가능한 노드를 추천합니다.

4️⃣ 엣지 정리

• 엣지를 클릭하면 우측에 라벨 편집창이 열려 데이터 형식을 주석처럼 적어둘 수 있습니다.
• 복잡한 그래프는 노드를 모두 선택한 뒤 Ctrl + G로 그룹화하고 색 태그를 부여해 시각적 구조를 명확히 하십시오.

---

4‑3. 노드 설정·코드 커스터마이징

노드 유형	주요 파라미터	활용 팁
Prompt	템플릿, 입력 변수	{variable} 추가 시 자동 입력 포트 생성
LLM	Model, Temperature, Max Tokens, Streaming, API Key	실행 중 파라미터 수정 시 Live Reload
Vector Store	DB URL, Collection, Embedding Model	“Test Connection” 버튼으로 핑 테스트
Memory	Type, Window Size, Session ID	session_id에 사용자 ID 매핑하여 개인화
Tool	Google Search, Calculator 등 각 툴별 설정	Agent 노드의 Tools 포트에 묶어서 연결

코드 아이콘 (</>) 사용법

1. 빠른 프로토타입: 전처리 코드 몇 줄을 추가해 결과를 즉시 확인합니다.
2. 고급 확장: 클래스 상속으로 입·출력 포트를 동적으로 늘려 완전히 새로운 컴포넌트를 제작합니다.
3. 버전 관리: 수정 시 node_id에 revision 넘버가 붙으므로 손쉽게 롤백할 수 있습니다.

⚠️ 공동 작업 시에는 충돌 방지를 위해 노드 Lock 기능을 활용해 주세요.

---

4‑4. 변수·메모리·데이터 흐름 최적화

1. 변수 스코프 — Prompt 변수는 플로우 로컬 범위이므로 충돌 위험이 없습니다. 다만 의미 있는 짧은 접두어를 쓰면 가독성이 높아집니다.
2. 메모리 윈도우 — BufferMemory는 5~20 메시지로 시작해 비용과 품질에 맞춰 조정하십시오.
3. RAG 구성 — RetrievalQA Chain과 VectorStore를 결합하고 {context} 변수에 검색 결과를 삽입, context_separator="\n---\n"로 구분선을 넣으면 프롬프트 해석성이 높아집니다.
4. 세션 관리 — session_id를 HTTP 헤더나 쿠키와 연동하면 사용자마다 독립된 대화 문맥을 유지할 수 있습니다.

---

4‑5. Playground 실행·디버깅

1. 실행 모드 선택 : Run 버튼 옆 ▼ 클릭 후 Step‑Through, Full Run, Batch Run 중 선택합니다.
2. 스트리밍 출력 : LLM 노드에서 Streaming ON 시 토큰이 실시간으로 흘러오는 그래프를 확인할 수 있습니다.
3. 중단점 : 노드 우클릭 → Set Breakpoint 를 지정하면 해당 노드 이전 단계에서 실행이 일시 중지됩니다.
4. 엣지 데이터 미리보기 : 엣지를 더블클릭하면 최근 N건 샘플과 CSV 다운로드 버튼이 표시됩니다.
5. 비용 분석 : Logs 탭 우측 $ 아이콘으로 토큰 사용량과 예상 과금을 시각화할 수 있습니다.
6. Freeze/Thaw : 상단 툴바 🐧 아이콘으로 Freeze 모드를 활성화해 수정하지 않은 상위 노드 실행을 건너뛰어 비용을 절감합니다.

---

4‑6. 프로젝트·플로우 관리 고급 기능

• 멀티 프로젝트 태그 — 프로젝트 카드에 색상·아이콘 태그를 달아 도메인·팀·버전별로 구분합니다.
• 버전 히스토리 트리 — 플로우 페이지 ‘History’ 버튼에서 브랜치 트리를 시각적으로 확인하고 단일 클릭으로 롤백할 수 있습니다.
• JSON Export 옵션 — 구성만, 구성 + 파일, 구성 + DB 스냅샷 중 선택해 요구 수준에 맞게 내보내십시오.
• Git 연동 — langflow git init CLI를 사용하면 플로우 JSON이 자동 커밋되어 CI 파이프라인에서 리뷰 가능합니다.

---

4‑7. Publish·통합·보안

방식	설명	유의사항
Python Embed	from langflow import load_flow 로 프로젝트 코드에 직접 임베드	pip install langflow[embed] 필요
REST API	POST /api/v1/predict/flow/{id} 로 호출	헤더 x-api-key 필수, 토큰 관리 필요
Web Component	iframe 스니펫을 사이트에 삽입	동일 출처 정책(SOP) 확인
MCP	플로우를 원격 툴로 노출·호출	TLS, 포트 개방, 인증 설정 확인

API 보안 Best Practice

1. LANGFLOW_AUTO_LOGIN=False 환경 변수를 설정하고 API Key 인증을 활성화하십시오.
2. Nginx 리버스 프록시로 HTTPS 종단 암호화를 적용하고 WebSocket 업그레이드를 허용하십시오.
   3. 사용자 권한을 Read‑Only / Execute / Admin으로 세분화하여 최소 권한 원칙을 지키십시오.

---

4‑8. 자주 묻는 질문(FAQ)

증상	원인	해결책
페이지가 무한 로딩됨	CORS 헤더 미설정	프록시에 Access-Control-Allow-Origin: * 추가
LLM 노드 Timeout	프롬프트 과다 또는 네트워크 지연	Max Tokens 축소, timeout 파라미터 증가
API 403 오류	API Key 누락	헤더 x-api-key: <key> 추가
포트 미표시	코드 수정 후 UI 미갱신	페이지 새로고침 또는 노드 다시 선택

---

4‑9. 요약 및 다음 단계

Langflow UI는 아이디어 구상 → 시각적 설계 → 즉시 실행 → 세밀한 디버깅 → 안전한 배포라는 전 과정을 브라우저 한 화면에서 완결합니다. 이 가이드대로

1. 노드를 추가·연결하고,
2. 파라미터와 코드를 세밀하게 조정한 뒤,
3. Playground에서 검증·로그를 분석하고,
4. 프로젝트 버전 관리를 통해 변경 내역을 체계화하며,
5. Publish 기능으로 외부 애플리케이션과 안전하게 통합

하시기 바랍니다. 이렇게 하면 챗봇, RAG, 멀티에이전트 등 어떤 LLM 파이프라인도 손쉽게 구축·운영하실 수 있습니다. 다음 5부에서는 이러한 환경을 기반으로 대표 프로젝트 템플릿을 활용한 종합 사례를 직접 구현해 보겠습니다.