2026. 9. 11. 11:33ㆍGitHub AI 스킬 연구소
A collection of apps powered by the LangChain LLM framework. https://github.com/alphasecio/langchain-examples
LangChain을 처음 붙잡았을 때 가장 먼저 한 일이 공식 문서 목차를 스크롤하는 거였습니다. Chains, Agents, Retrievers, Memory... 개념은 알겠는데 "그래서 PDF 하나 요약하는 앱을 만들려면 뭘 조합해야 하는데?"에 대한 답이 안 나오죠.
결국 저는 블로그 글 서너 개를 짜깁기해서 첫 프로토타입을 만들었습니다. 그게 2023년 이야기고, 지금도 상황이 크게 다르진 않습니다.
alphasecio/langchain-examples는 그 짜깁기 단계를 건너뛰게 해주는 레포입니다. 별 550개, 순수 Python, 앱 하나당 폴더 하나. 그게 전부입니다.
지금까지 LangChain 앱을 시작하던 방식
보통 세 갈래였습니다.
- 공식 문서 Quickstart: 개념 설명은 충실한데, 완성된 앱이 아니라 조각 코드라 UI까지 붙이려면 또 검색을 해야 함
- YouTube 튜토리얼 따라치기: 영상 찍힌 시점의 LangChain 버전과 지금 버전이 달라서 import 경로부터 깨짐 (
langchain.embeddings→langchain_openai전환 겪어보신 분들은 압니다) - ChatGPT한테 물어보기: 그럴듯한 코드가 나오는데 존재하지 않는 클래스명을 섞어서 줌
세 방법 모두 공통된 문제가 있죠. "이 코드가 실제로 돌아간다"는 보증이 없다는 것.
이 레포가 바꾸는 지점
langchain-examples는 튜토리얼이 아니라 완성된 Streamlit 앱들의 모음입니다. 폴더 하나 들어가면 streamlit_app.py, requirements.txt, README.md가 딱 세 개 있고, 그걸 그대로 실행하면 브라우저에 앱이 뜹니다.
README에 나열된 앱들을 보면 용도별로 갈립니다.
- all-in-one: 멀티페이지 Streamlit 앱. 여러 유스케이스를 한 앱에 모아놓은 쇼케이스
- chroma-summary: LangChain + Chroma 벡터DB로 문서 요약
- gemini-chat-pdf: Gemini 모델로 PDF에 질문하는 RAG 앱. OpenAI 말고 Gemini 쓴다는 게 포인트
- helicone: LLM 호출 로깅/모니터링 붙인 버전
오늘 README를 뜯어보다가 눈에 들어온 건 gemini-chat-pdf였습니다. 대부분의 LangChain 예제가 OpenAI에 종속돼 있는데, 여긴 Gemini + Chroma 조합을 따로 빼놨거든요. Gemini는 무료 티어 쿼터가 넉넉한 편이라 "일단 돌려보고 싶은데 결제카드 등록은 부담스럽다"는 상황에서 진입 장벽이 확 낮아집니다. 이런 배려는 문서 잘 쓴 레포에서도 흔치 않습니다.
핵심 스펙 정리
| 항목 | 내용 |
|---|---|
| 언어 | Python (3.9+ 권장) |
| UI 프레임워크 | Streamlit (전 앱 공통) |
| 필요 API 키 | 앱별 상이. OpenAI, Google Gemini, Pinecone, Helicone 등 |
| 벡터 스토어 | Chroma(로컬), Pinecone(클라우드) |
| 설치 난이도 | ★☆☆☆☆ (pip install 후 바로 실행) |
| 라이선스 | MIT (상업적 이용 가능) |
갈아탈 가치가 있는 경우, 없는 경우
솔직하게 나눠보죠.
이런 분께는 확실히 이득
- LangChain을 처음 만지는데 개념보다 동작하는 결과물을 먼저 봐야 이해가 되는 타입
- 사내 PoC 데모를 3일 안에 만들어야 하는 상황. Streamlit이라 UI 고민이 0에 수렴
- RAG 파이프라인의 기본 골격(문서 로드 → 청킹 → 임베딩 → 검색 → 생성)을 코드로 확인하고 싶은 경우
- OpenAI 말고 Gemini 기반 예제를 찾고 있던 경우
굳이 안 와도 되는 경우
- 이미 LangChain으로 프로덕션 서비스를 운영 중. 여기 코드는 데모 수준이라 얻을 게 별로 없음
- LangGraph 기반 멀티 에이전트 워크플로를 설계하려는 경우. 이 레포는 그쪽을 거의 다루지 않습니다
- Streamlit이 아닌 FastAPI/Next.js 백엔드가 목표라면, UI 코드를 걷어내는 작업이 오히려 번거로움
솔직히 말하면, 이 레포는 "왜 이렇게 짜야 하는가"에는 약합니다. 코드는 주는데 설계 의도나 트레이드오프 설명이 거의 없어요. Chroma를 쓴 이유, 청크 사이즈를 그 값으로 잡은 근거 같은 건 직접 실험해봐야 합니다. 정답지는 있는데 풀이과정은 없는 문제집 느낌.
비교하자면, 저는 아직 LangChain 공식 문서의 Tutorials 섹션이 학습용으로는 더 낫다고 봅니다. 이유는 버전 갱신 속도. langchain-examples는 개인 레포라 LangChain이 0.1 → 0.3으로 넘어가며 바꾼 import 경로가 일부 앱에 반영이 늦을 수 있거든요. 대신 "돌아가는 앱 전체"를 통째로 주는 건 공식 문서가 못 하는 일입니다. 둘은 대체재가 아니라 보완재에 가깝습니다.
10분 안에 첫 앱 띄우기
전체 레포를 클론할 필요 없습니다. 관심 있는 폴더 하나만 보면 되거든요.
git clone https://github.com/alphasecio/langchain-examples.git
cd langchain-examples/gemini-chat-pdf
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt여기서 한 번 끊고 갑니다. requirements.txt에 버전 핀이 느슨하게 걸려 있으면 최신 LangChain이 설치되면서 import 에러가 날 수 있어요. 그럴 땐 이렇게 버전을 고정하는 게 빠릅니다.
pip install "langchain==0.3.7" "langchain-google-genai==2.0.4" "chromadb==0.5.18"API 키는 환경변수로 넣습니다. Streamlit은 .streamlit/secrets.toml도 지원하지만, 로컬 테스트는 환경변수가 간편합니다.
export GOOGLE_API_KEY="your-key-here"
streamlit run streamlit_app.py브라우저가 자동으로 localhost:8501을 엽니다. PDF 하나 올리고 질문 던지면 끝.
코드를 뜯어볼 때는 이 흐름만 따라가면 구조가 보입니다.
# 대부분의 RAG 예제가 공유하는 5단계
loader = PyPDFLoader(file_path) # 1. 문서 로드
docs = loader.load()
splitter = RecursiveCharacterTextSplitter( # 2. 청킹
chunk_size=1000, chunk_overlap=200
)
chunks = splitter.split_documents(docs)
vectordb = Chroma.from_documents( # 3. 임베딩 + 저장
chunks, embedding=embeddings
)
retriever = vectordb.as_retriever( # 4. 검색기 생성
search_kwargs={"k": 4}
)
chain = RetrievalQA.from_chain_type( # 5. LLM 연결
llm=llm, retriever=retriever
)이 5단계가 머리에 박히면 레포에 있는 앱 절반은 코드를 안 봐도 예측이 됩니다. 나머지 절반은 여기에 Helicone 로깅이나 Pinecone 같은 외부 서비스가 하나씩 얹힌 변형이고요.
읽으면서 걸렸던 점
별 550개에 앱이 10개 넘게 들어있는데, 루트 README는 앱 이름과 한 줄 설명이 전부입니다. "어느 앱부터 보면 되는지" 가이드가 없어요. 처음 온 사람은 all-in-one부터 열어볼 텐데, 멀티페이지 앱이라 오히려 코드가 제일 복잡합니다.
순서를 정하자면 chroma-summary → gemini-chat-pdf → all-in-one 이 맞다고 봅니다. 요약 → QA → 통합 순으로 난이도가 올라가거든요.
그리고 궁금한 게 있는데, 여러분은 LangChain 예제를 볼 때 Streamlit 껍데기를 그대로 쓰시나요, 아니면 로직만 뜯어서 FastAPI로 옮기시나요? 저는 PoC까지는 Streamlit, 그 이후엔 무조건 분리하는 편인데 이 경계를 어디서 긋는지 다들 다르더라고요. (댓글로 각자 기준 좀 알려주세요.)
결론
langchain-examples는 교과서가 아니라 참조 구현 모음입니다. 개념 학습은 공식 문서에서 하고, "그래서 실제 파일은 어떻게 생겼나"가 궁금할 때 여기를 여는 게 맞는 사용법이죠.
MIT 라이선스라 회사 내부 도구에 코드를 그대로 가져다 써도 문제없습니다. 이게 생각보다 큰 장점.
저는 chroma-summary를 베이스로 팀 회의록 PDF를 자동 요약해서 Slack에 던지는 스크립트를 만들어볼 계획입니다. Streamlit UI는 걷어내고 로직만 cron으로 돌리는 형태로요.
💡 Dev Note: 실무 적용 포인트
실무에 붙일 때 첫 번째 복병은 임베딩 비용입니다. OpenAI text-embedding-3-small 기준 100만 토큰당 0.02달러라 싸 보이지만, 사내 문서 수천 건을 매일 재인덱싱하면 금액이 쌓입니다. Chroma는 로컬 영속화가 되니 persist_directory를 꼭 지정하고, 변경된 문서만 증분 업데이트하는 로직을 직접 붙여야 합니다. 두 번째는 컨텍스트 길이인데, 예제의 기본 chunk_size=1000은 한국어 문서에선 토큰 대비 글자수가 영어와 달라서 검색 정확도가 떨어질 수 있습니다. 한국어라면 500~800 사이로 줄이고 k 값을 6~8로 늘려 실험해보길 권합니다. 마지막으로 Streamlit은 세션 상태 관리가 단순해서 동시 접속 10명만 넘어가도 벡터DB 락 이슈가 생기니, 사내 배포를 염두에 둔다면 처음부터 검색 레이어를 별도 서비스로 빼두는 게 나중에 덜 고생합니다.