Molayo

© 2026 Molayo

Dev.to헤드라인2026. 06. 17. 17:59

환경 설정하기: LangChain, LangGraph 및 Chat LLM

요약

LangChain, LangGraph 및 Chat LLM을 활용한 Python 개발 환경 구축 방법을 단계별로 안내합니다. 가상 환경 설정부터 필수 패키지 설치, API 키 관리까지 초보자가 겪을 수 있는 시행착오를 방지하는 데 중점을 둡니다.

핵심 포인트

  • Python 3.9 이상의 버전 설치 필요
  • 의존성 충돌 방지를 위한 가상 환경(venv) 사용 권장
  • LangChain, LangGraph, python-dotenv 등 필수 패키지 설치 방법
  • OpenAI API 키를 활용한 Chat LLM 연동 준비

제가 처음 LangChain 프로젝트를 설정하려고 했을 때, 단 하나의 누락된 환경 변수 때문에 두 시간 동안 디버깅을 하며 시간을 허비했습니다. 제 API 키는 .env 파일에 바로 있었지만, 그것을 로드하는 것을 잊어버렸던 것입니다. 두 시간이라는 시간이 그냥 날아갔습니다.

여러분에게는 그런 일이 일어나지 않도록 이 글을 작성합니다.

이 가이드를 마칠 때쯤이면, 여러분은 LangChain, LangGraph, 그리고 연결되어 실행 중인 Chat LLM이 포함된 완전히 작동하는 Python 환경을 갖게 될 것입니다. 우리는 단계별로 진행할 것이며, 저는 문제가 흔히 발생하는 모든 지점을 표시해 드릴 것입니다.

이제 시작해 봅시다.

설치할 항목

필요한 모든 항목은 다음과 같습니다:

패키지역할
langchain체인 (chains) 및 에이전트 (agents) 구축을 위한 핵심 프레임워크
...

우리는 이 시리즈 전반에 걸쳐 Chat LLM으로 OpenAI의 gpt-4o-mini를 사용할 것입니다. 이는 빠르고 저렴하며 널리 사용 가능합니다. 만약 Anthropic 또는 Google과 같은 다른 제공업체를 사용하는 것을 선호한다면, 어디에서 교체해야 하는지 알려드리겠습니다.

1단계: Python 버전 확인

LangChain은 Python 3.9 이상을 요구합니다. 터미널을 열고 다음을 실행하세요:

python --version

다음과 같은 결과가 보여야 합니다:

Python 3.11.4

만약 Python 3.8 이하 버전을 사용 중이라면, 계속 진행하기 전에 python.org로 이동하여 최신 안정 버전을 다운로드하세요.

2단계: 프로젝트 폴더 생성

처음부터 체계적으로 관리해 봅시다:

mkdir langchain-agents-series
cd langchain-agents-series

이 시리즈에서 구축할 모든 것은 이 폴더 안에 저장될 것입니다.

3단계: 가상 환경 (Virtual Environment) 설정

가상 환경 (Virtual Environment)은 프로젝트의 의존성 (dependencies)을 시스템의 나머지 부분과 격리하여 유지합니다. 이는 선택 사항이 아닙니다. 나중에 발생할 의존성 충돌을 방지해 줄 것입니다.

# 가상 환경 생성
python -m venv venv

...

활성화되면 터미널 프롬프트 시작 부분에 (venv)가 표시되도록 변경됩니다. 이는 여러분이 가상 환경 안에 있으며, 설치하는 모든 패키지가 이 프로젝트에 격리되어 유지될 것임을 의미합니다.

단계 4: 패키지 설치

가상 환경이 활성화된 상태에서 다음을 실행하세요:

pip install langchain langchain-openai langchain-core langgraph python-dotenv openai

설치에는 1~2분 정도 소요됩니다. 완료되면 모든 것이 올바르게 설치되었는지 확인하세요:

pip list | grep -E "langchain|langgraph|openai"

다음과 유사한 출력이 나타나야 합니다:

langchain                0.3.x
langchain-core           0.3.x
langchain-openai         0.2.x
...

정확한 버전 번호는 다를 수 있지만, 다섯 가지 패키지가 모두 나타난다면 문제없이 완료된 것입니다.

단계 5: OpenAI API 키 가져오기

GPT 모델을 사용하려면 OpenAI에서 제공하는 API 키가 필요합니다.

  1. platform.openai.com에 접속합니다.
  2. 회원가입 또는 로그인을 합니다.
  3. 오른쪽 상단의 프로필 아이콘을 클릭한 다음, API keys를 선택합니다.
  4. Create new secret key를 클릭합니다.
  5. 즉시 키를 복사하세요. 대화 상자를 닫으면 다시는 키를 볼 수 없습니다.

계정에 크레딧(credits)이 있는지 확인하세요. 새 계정에는 보통 소량의 무료 크레딧이 제공됩니다. 이 시리즈에서는 gpt-4o-mini 모델이 매우 저렴하여 크레딧을 오래 사용할 수 있습니다.

단계 6: API 키를 안전하게 저장하기

API 키를 Python 파일에 직접 하드코딩(hardcode)하지 마세요. 만약 키가 하드코딩된 코드를 GitHub에 푸시(push)하면, 몇 분 내에 봇(bot)들에 의해 수집되어 사용될 것입니다.

대신, .env 파일을 사용합니다.

프로젝트 루트(root) 디렉토리에 .env라는 이름의 파일을 생성하세요:

touch .env

파일을 열고 키를 추가합니다:

OPENAI_API_KEY=sk-your-actual-key-goes-here

이제 이 파일이 절대 커밋(commit)되지 않도록 .gitignore 파일을 생성합니다:

touch .gitignore

.gitignore에 다음 내용을 추가하세요:

.env
venv/
__pycache__/
...

이제 프로젝트 폴더는 다음과 같은 구조를 갖게 됩니다:

langchain-agents-series/
├── .env
├── .gitignore
...

단계 7: 첫 번째 Chat LLM 호출

이제 재미있는 부분입니다. hello_agent.py라는 이름의 새 파일을 만드세요:

# hello_agent.py

import os
...

실행하세요:

python hello_agent.py

모든 설정이 올바르게 되었다면, 다음과 같은 내용을 보게 될 것입니다:

Sending request to OpenAI...

Response:
...

방금 첫 번째 LangChain API 호출을 성공하셨습니다. 이것이 여러분의 "Hello, World" 순간입니다.

방금 일어난 일 이해하기

주요 코드 라인을 분석해 보겠습니다:

load_dotenv()

이 함수는 .env 파일을 읽어 모든 변수를 환경 변수로 로드합니다. LangChain의 OpenAI 통합 기능은 여기서 OPENAI_API_KEY를 자동으로 가져옵니다.

llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)

이 코드는 Chat LLM 인스턴스를 생성합니다. temperature=0은 모델의 출력을 일관되고 예측 가능하게 만드는데, 이는 에이전트 (agent)를 구축할 때 이상적입니다.

messages = [
    SystemMessage(content="..."),
    HumanMessage(content="...")
...

채팅 모델 (Chat models)은 단순한 문자열 대신 구조화된 메시지 리스트를 입력으로 받습니다. 이러한 메시지 유형에 대해서는 다음 글에서 심도 있게 다룰 예정입니다.

response = llm.invoke(messages)

invoke()는 체인 (chain) 또는 모델을 실행하기 위한 LangChain의 표준 메서드입니다. 이는 동기적 (synchronous) 방식으로 작동하며, 즉 전체 응답이 올 때까지 기다린 후 다음 단계로 진행합니다.

다른 LLM 제공업체 사용하기

OpenAI 대신 Anthropic의 Claude를 사용하고 싶다면, 다음과 같이 교체할 수 있습니다:

pip install langchain-anthropic

from langchain_anthropic import ChatAnthropic

llm = ChatAnthropic(
...

.env 파일에 ANTHROPIC_API_KEY=your-key를 추가하기만 하면 나머지 모든 것은 정확히 동일하게 유지됩니다. LangChain의 통합 인터페이스 덕분에 애플리케이션 로직을 다시 작성하지 않고도 제공업체를 전환할 수 있습니다.

Google Gemini의 경우:

pip install langchain-google-genai

from langchain_google_genai import ChatGoogleGenerativeAI

llm = ChatGoogleGenerativeAI(
...

.env 파일에 GOOGLE_API_KEY=your-key를 추가하세요.

응답 스트리밍 (Streaming Responses)

실제 애플리케이션에서는 전체 출력을 기다리기보다 토큰 단위로 응답을 스트리밍 (stream)하고 싶은 경우가 많습니다. 그 방법은 다음과 같습니다:

# streaming_example.py

from dotenv import load_dotenv
...

stream() 메서드는 청크 (chunks)가 생성되는 대로 반환하므로, 긴 응답에 대해 사용자에게 훨씬 더 나은 경험을 제공합니다.

에러 핸들링 (Error Handling)

프로덕션 (Production) 코드는 실패를 유연하게 처리해야 합니다. 가장 흔히 접하게 될 에러들과 그 처리 방법은 다음과 같습니다:

# error_handling_example.py

import os
...

베스트 프랙티스 (Best Practices)

첫날부터 길들여야 할 몇 가지 습관입니다:

항상 가상 환경 (virtual environment)을 사용하세요. LangChain이나 프로젝트 의존성 (dependencies)을 절대 전역 (globally)으로 설치하지 마세요. 결국 충돌이 발생하게 됩니다.

의존성 버전을 고정하세요 (Pin your dependencies). 프로젝트가 정상적으로 작동하면, 사용 중인 정확한 버전을 저장하세요:

pip freeze > requirements.txt

그러면 다른 사람(또는 미래의 당신)이 다음 명령어로 당신의 환경을 정확히 재현할 수 있습니다:

pip install -r requirements.txt

.env 파일은 절대 커밋하지 마세요. git push를 하기 전에 항상 .gitignore를 다시 확인하세요.

에이전트 (agents)에는 temperature=0을 사용하세요. 에이전트는 예측 가능해야 합니다. 높은 온도 (temperature) 값은 무작위성 (randomness)을 도입하여 에이전트가 일관성 없게 행동하게 만들 수 있습니다.

토큰 사용량 (token usage)을 로그로 남기세요. 토큰 비용은 계속 쌓입니다. 특히 개발 단계에서는 응답의 token_usage 필드를 주의 깊게 살펴보세요.

트러블슈팅 (Troubleshooting)

"OPENAI_API_KEY not found" 에러

다음 사항을 확인하세요:

  1. .env 파일이 스크립트와 동일한 디렉토리에 있는지
  2. 키에 접근하기 전에 load_dotenv()를 호출했는지
  3. .env 파일의 변수 이름이 = 주변에 공백 없이 정확히 OPENAI_API_KEY인지

"ModuleNotFoundError: No module named 'langchain'"

가상 환경이 활성화되지 않았을 가능성이 높습니다. source venv/bin/activate (Mac/Linux) 또는 venv\Scripts\activate (Windows)를 실행한 후 다시 시도하세요.

"AuthenticationError: Incorrect API key"

platform.openai.com/api-keys로 돌아가 새 키를 생성하세요. sk- 접두사를 포함한 전체 키를 복사했는지 확인하세요.

새 계정에서의 "RateLimitError"

새로운 OpenAI 계정은 결제 수단을 추가하기 전까지 속도 제한 (Rate Limit)이 매우 낮을 수 있습니다. OpenAI 결제 (billing) 설정으로 이동하여 카드를 추가하세요. 실제로 크레딧을 사용하기 전까지는 요금이 청구되지 않습니다.

응답이 매우 느린 경우

더 큰 모델을 사용 중이라면 gpt-4o-mini로 전환하세요. 이 모델은 학습 목적으로 사용하기에 여전히 매우 유능하면서도 훨씬 빠르고 저렴합니다.

지금까지의 프로젝트 구조

langchain-agents-series/
├── .env                      # API 키 (절대 커밋하지 마세요)
├── .gitignore                # Git이 .env와 venv를 무시하도록 설정
...

핵심 요약

  • 프로젝트 의존성을 격리하기 위해 항상 가상 환경 (virtual environment)을 사용하세요.
  • API 키는 .env 파일에 저장하고 python-dotenv를 사용하여 로드하세요.
  • API 키를 코드에 직접 입력 (hardcode)하거나 .env 파일을 버전 관리 시스템에 커밋하지 마세요.
  • ChatOpenAI는 OpenAI의 채팅 모델 (chat models)을 위한 LangChain의 인터페이스입니다.
  • 채팅 모델은 일반 문자열이 아닌 구조화된 메시지 (structured messages) 리스트를 받습니다.
  • 에이전트 (agents)의 동작을 예측 가능하게 유지하려면 temperature=0을 사용하세요.
  • LangChain의 통합 인터페이스를 사용하면 서로 다른 LLM 제공업체 간의 전환이 쉽습니다.
  • 프로덕션 코드에서는 LLM 호출 주변에 항상 에러 핸들링 (error handling)을 추가하세요.

다음 단계

이제 환경이 구축되었으므로, Chat LLM이 실제로 어떻게 작동하는지 이해할 차례입니다. 다음 글에서는 세 가지 메시지 유형 (SystemMessage, HumanMessage, AIMessage)을 깊이 있게 살펴보고, 다회차 대화 (multi-turn conversations)를 구조화하는 방법과 대화 기록을 추적하는 간단한 대화 루프 (conversation loop)를 구축하는 방법을 배워보겠습니다.

3편에서 만나요.

AI 자동 생성 콘텐츠

본 콘텐츠는 Dev.to AI tag의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0