🦙 LangChain + Ollama 연동 완전 정복: 인터넷 없이 내 PC에서 돌아가는 로컬 AI 챗봇 만들기

둘의 역할을 식당에 비유하면 깔끔해. Ollama는 주방장이야. 실제로 요리(텍스트 생성)를 하는 LLM을 내 컴퓨터에서 돌려주는 실행 엔진이지. LangChain은 홀 매니저야. 손님 주문(질문)을 받아서 주방이 알아듣기 좋게 정리하고, 이전 대화를 기억하고, 필요하면 창고(문서 DB)에서 재료를 꺼내 주방에 넘겨줘.

로컬 챗봇, 장단점 솔직하게

그러니까 사내 문서 Q&A, 개인 노트 비서, 민감 데이터 처리, 학습용 실험엔 로컬이 딱이고, 최고 수준의 추론이 꼭 필요한 일엔 클라우드가 낫다는 거. 둘 중 하나만 고를 필요도 없어. LangChain 덕분에 섞어 쓰기도 쉽거든.

설치는 진짜 허무할 만큼 간단해. 공식 사이트(ollama.com)에서 macOS·Windows용 설치 파일을 받아 실행하면 끝. 리눅스는 공식 설치 스크립트 한 줄이면 돼.

# Linux
curl -fsSL https://ollama.com/install.sh | sh

# 설치 확인
ollama --version

설치하면 Ollama 서버가 백그라운드에서 자동으로 떠. 만약 안 떠 있으면 ollama serve로 직접 켜면 되고. 이제 모델을 받아보자.

# 모델 다운로드
ollama pull llama3.1:8b
ollama pull qwen2.5:7b

# 터미널에서 바로 대화
ollama run qwen2.5:7b

# 받아둔 모델 목록 / 현재 메모리에 올라간 모델
ollama list
ollama ps

# 필요 없는 모델 삭제
ollama rm llama3.1:8b

내 PC엔 어떤 모델이 맞을까?

로컬 LLM의 핵심 고민은 결국 메모리야. Ollama 라이브러리의 기본 태그는 보통 4비트 양자화(Q4 계열) 버전이라 원본보다 훨씬 가벼워. 대략적인 감을 잡아보면 이래 (컨텍스트 길이·양자화 방식에 따라 달라지는 어림값이야).

한국어 챗봇이라면 qwen2.5, gemma2/gemma3, LG AI연구원의 exaone3.5 같은 모델이 한국어를 꽤 자연스럽게 다뤄. 임베딩 용도로는 nomic-embed-text, 다국어에 강한 bge-m3 같은 전용 임베딩 모델을 따로 받아두면 좋아. 모델 라인업은 정말 빠르게 바뀌니까 ollama.com의 라이브러리 페이지에서 최신 목록을 한 번 훑어보는 습관을 들이자.

여기서 많은 사람이 첫 삽부터 삐끗해. 옛날 블로그 글을 보면 from langchain.llms import Ollama나

from langchain_community.chat_models import ChatOllama

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

# 필수 패키지
pip install -U langchain langchain-ollama

# RAG와 UI까지 하려면
pip install -U langchain-community langchain-chroma langchain-text-splitters pypdf streamlit

자, 대망의 첫 코드. 딱 몇 줄이야.

from langchain_ollama import ChatOllama

llm = ChatOllama(
    model="qwen2.5:7b",   # ollama list에 있는 이름 그대로
    temperature=0.7,      # 창의성 정도 (0이면 일관적, 높을수록 다양)
)

response = llm.invoke("로컬 LLM의 장점을 세 줄로 알려줘.")
print(response.content)

invoke()의 결과는 그냥 문자열이 아니라 AIMessage 객체야. 그래서 본문은 .content로 꺼내야 해. 이 객체엔 토큰 사용량 같은 메타데이터도 같이 들어 있어서 response.usage_metadata로 입력·출력 토큰 수를 확인할 수 있어.

자주 만지는 파라미터

매번 질문 문자열을 손으로 조립하는 건 비효율적이잖아. LangChain은 ChatPromptTemplate으로 "시스템 역할 + 사용자 질문" 틀을 만들고, LCEL(LangChain Expression Language)이라는 문법으로 부품을 | 기호로 이어 붙여. 리눅스 파이프처럼 왼쪽 결과가 오른쪽 입력으로 흘러가는 구조야.

from langchain_ollama import ChatOllama
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

llm = ChatOllama(model="qwen2.5:7b", temperature=0.3)

prompt = ChatPromptTemplate.from_messages([
    ("system", "너는 친절한 {role}야. 반드시 한국어로, 쉽게 설명해."),
    ("human", "{question}"),
])

chain = prompt | llm | StrOutputParser()

answer = chain.invoke({
    "role": "파이썬 선생님",
    "question": "리스트 컴프리헨션이 뭐야?",
})
print(answer)

StrOutputParser()가 AIMessage에서 텍스트만 쏙 뽑아주니까 결과가 바로 문자열로 나와. 이렇게 만든 chain은 Runnable이라는 공통 인터페이스를 따르기 때문에 invoke()(한 번), stream()(실시간), batch()(여러 개 동시) 메서드를 똑같이 쓸 수 있어. 비동기 버전인 ainvoke(), astream()도 있고.

로컬 모델은 클라우드보다 느린 경우가 많아서, 답이 다 완성될 때까지 멍하니 기다리면 체감이 별로야. 그래서 스트리밍은 로컬 챗봇의 필수 옵션이야.

for chunk in chain.stream({"role": "여행 가이드", "question": "제주도 2박3일 코스 추천해줘"}):
    print(chunk, end="", flush=True)

체인 끝에 StrOutputParser가 있으니까 chunk가 문자열 조각으로 들어와. 같은 시간이 걸려도 첫 글자가 바로 보이니까 사용자가 느끼는 속도는 완전히 달라져.

LLM은 기본적으로 무상태(stateless)야. "내 이름은 민수야" 하고 다음 질문에 "내 이름 뭐게?" 하면 모른다고 해. 기억은 모델이 하는 게 아니라 우리가 이전 대화를 매번 같이 보내줘서 생기는 거거든. LangChain에선 MessagesPlaceholder로 대화 기록이 들어갈 자리를 만들고, RunnableWithMessageHistory로 세션별 기록을 자동 관리해.

from langchain_ollama import ChatOllama
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
from langchain_core.output_parsers import StrOutputParser
from langchain_core.chat_history import InMemoryChatMessageHistory
from langchain_core.runnables.history import RunnableWithMessageHistory

llm = ChatOllama(model="qwen2.5:7b", temperature=0.5)

prompt = ChatPromptTemplate.from_messages([
    ("system", "너는 유쾌한 한국어 AI 친구야. 짧고 재미있게 답해."),
    MessagesPlaceholder(variable_name="history"),
    ("human", "{input}"),
])

chain = prompt | llm | StrOutputParser()

store = {}  # 세션 ID별 대화 기록 저장소

def get_history(session_id: str):
    if session_id not in store:
        store[session_id] = InMemoryChatMessageHistory()
    return store[session_id]

chatbot = RunnableWithMessageHistory(
    chain,
    get_history,
    input_messages_key="input",
    history_messages_key="history",
)

config = {"configurable": {"session_id": "minsu"}}

while True:
    user = input("\n나: ")
    if user.strip() in ("exit", "quit", "종료"):
        break
    print("AI: ", end="")
    for chunk in chatbot.stream({"input": user}, config=config):
        print(chunk, end="", flush=True)

이제 터미널에서 진짜 대화가 이어져! session_id를 다르게 주면 사용자별로 기억이 분리되니까 여러 명이 쓰는 서비스로 확장하기도 쉬워.

참고로 LangChain 쪽에서는 더 복잡한 상태 관리(멀티턴 에이전트, 체크포인트 저장 등)엔 자매 프로젝트인 LangGraph 사용을 권하는 추세야. 단순 챗봇이라면 위 방식으로 충분해.

로컬 챗봇의 진짜 꽃은 RAG(Retrieval-Augmented Generation, 검색 증강 생성)야. 모델은 우리 회사 규정집이나 내 강의 노트를 학습한 적이 없잖아? 그래서 질문이 들어오면 관련 문서 조각을 먼저 찾아서 프롬프트에 끼워 넣고, 그걸 근거로 답하게 만드는 거야. 오픈북 시험이라고 생각하면 딱이야.

임베딩이 뭐냐면

임베딩은 문장을 숫자 벡터(좌표)로 바꾸는 거야. 뜻이 비슷한 문장은 좌표 공간에서 가까이 모이게 돼. "휴가 신청 방법"과 "연차 쓰는 법"은 단어가 달라도 벡터가 가깝지. 그래서 키워드 검색보다 훨씬 똑똑하게 관련 내용을 찾아내. 이 변환도 Ollama의 임베딩 모델로 로컬에서 처리하니까 문서가 밖으로 나갈 일이 없어.

ollama pull nomic-embed-text   # 또는 다국어 강점의 bge-m3

전체 RAG 코드

from langchain_ollama import ChatOllama, OllamaEmbeddings
from langchain_community.document_loaders import PyPDFLoader
from langchain_text_splitters import RecursiveCharacterTextSplitter
from langchain_chroma import Chroma
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser
from langchain_core.runnables import RunnablePassthrough

# 1) 문서 로드
docs = PyPDFLoader("company_rules.pdf").load()

# 2) 청크 분할
splitter = RecursiveCharacterTextSplitter(chunk_size=800, chunk_overlap=100)
chunks = splitter.split_documents(docs)

# 3) 임베딩 + 벡터DB 저장 (디스크에 영구 보관)
embeddings = OllamaEmbeddings(model="nomic-embed-text")
vectordb = Chroma.from_documents(
    documents=chunks,
    embedding=embeddings,
    persist_directory="./chroma_db",
)

# 4) 검색기: 질문과 가장 비슷한 조각 4개
retriever = vectordb.as_retriever(search_kwargs={"k": 4})

def format_docs(docs):
    return "\n\n".join(d.page_content for d in docs)

prompt = ChatPromptTemplate.from_messages([
    ("system",
     "아래 [문서]만 근거로 한국어로 답해. 문서에 없으면 '문서에서 찾을 수 없어요'라고 말해.\n\n[문서]\n{context}"),
    ("human", "{question}"),
])

llm = ChatOllama(model="qwen2.5:7b", temperature=0, num_ctx=8192)

rag_chain = (
    {"context": retriever | format_docs, "question": RunnablePassthrough()}
    | prompt
    | llm
    | StrOutputParser()
)

print(rag_chain.invoke("연차는 며칠 전에 신청해야 해?"))

포인트를 짚어볼게. 체인 맨 앞의 딕셔너리가 핵심이야. 질문 문자열이 들어오면 RunnablePassthrough()는 질문을 그대로 question에 넣고, 동시에 retriever가 그 질문으로 문서를 검색해서 format_docs로 합친 뒤 context에 넣어줘. 두 갈래가 병렬로 흘러가서 프롬프트에서 만나는 구조지.

한 번 만든 DB는 다음 실행 때 다시 임베딩할 필요 없이 이렇게 불러오면 돼.

vectordb = Chroma(persist_directory="./chroma_db", embedding_function=embeddings)

친구나 팀원한테 보여주려면 화면이 있어야지. Streamlit은 파이썬만으로 채팅 UI를 뚝딱 만들 수 있게 st.chat_input, st.chat_message 같은 채팅 전용 컴포넌트를 제공해. 게다가 st.write_stream에 제너레이터를 넘기면 스트리밍 출력도 알아서 해줘.

# app.py
import streamlit as st
from langchain_ollama import ChatOllama
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
from langchain_core.output_parsers import StrOutputParser
from langchain_core.messages import HumanMessage, AIMessage

st.set_page_config(page_title="로컬 AI 챗봇", page_icon="🦙")
st.title("🦙 내 PC 안의 AI 친구")

model_name = st.sidebar.selectbox("모델 선택", ["qwen2.5:7b", "llama3.1:8b", "gemma2:9b"])
temp = st.sidebar.slider("temperature", 0.0, 1.0, 0.5)

llm = ChatOllama(model=model_name, temperature=temp)
prompt = ChatPromptTemplate.from_messages([
    ("system", "너는 다정한 한국어 AI 친구야."),
    MessagesPlaceholder("history"),
    ("human", "{input}"),
])
chain = prompt | llm | StrOutputParser()

if "messages" not in st.session_state:
    st.session_state.messages = []

for msg in st.session_state.messages:
    role = "user" if isinstance(msg, HumanMessage) else "assistant"
    with st.chat_message(role):
        st.markdown(msg.content)

if user_input := st.chat_input("무엇이든 물어봐!"):
    with st.chat_message("user"):
        st.markdown(user_input)

    with st.chat_message("assistant"):
        answer = st.write_stream(
            chain.stream({"input": user_input, "history": st.session_state.messages})
        )

    st.session_state.messages.append(HumanMessage(user_input))
    st.session_state.messages.append(AIMessage(answer))

streamlit run app.py

브라우저가 열리면서 ChatGPT 비슷한 채팅 화면이 짠 하고 나타나. 사이드바에서 모델을 바꿔가며 비교해보는 재미가 쏠쏠해. Streamlit은 사용자 입력이 있을 때마다 스크립트를 처음부터 다시 실행하는 구조라서, 대화 기록은 꼭 st.session_state에 넣어둬야 날아가지 않아.

Ollama엔 도커파일처럼 생긴 Modelfile이 있어. 기본 모델에 시스템 프롬프트와 파라미터를 박아 넣어서 새 이름의 모델로 저장하는 기능이야.

# Modelfile
FROM qwen2.5:7b
PARAMETER temperature 0.4
PARAMETER num_ctx 8192
SYSTEM """너는 사내 IT 헬프데스크 직원 '라마봇'이야. 항상 존댓말로, 단계별로 해결 방법을 안내해."""

ollama create llamabot -f Modelfile
ollama run llamabot

이렇게 만든 llamabot은 LangChain에서도 ChatOllama(model="llamabot")로 그대로 불러 쓸 수 있어. 여러 앱에서 같은 설정을 공유할 때 편하지.

최근 Ollama는 도구 호출을 지원하는 모델(예: llama3.1, qwen2.5 등)에 대해 function calling을 지원해. LangChain에선 bind_tools()로 파이썬 함수를 모델에 연결할 수 있어. 모델이 "이 질문엔 계산기가 필요하겠다" 판단하면 함수 이름과 인자를 만들어 돌려주는 방식이야.

from langchain_core.tools import tool
from langchain_ollama import ChatOllama

@tool
def add(a: int, b: int) -> int:
    """두 정수를 더한다."""
    return a + b

llm = ChatOllama(model="qwen2.5:7b", temperature=0)
llm_with_tools = llm.bind_tools([add])

msg = llm_with_tools.invoke("1234 더하기 5678은?")
print(msg.tool_calls)
# 예: [{'name': 'add', 'args': {'a': 1234, 'b': 5678}, ...}]

중요한 건, 모델은 함수를 직접 실행하지 않고 "이렇게 호출해줘"라는 요청만 만든다는 거야. 실제 실행과 결과 전달은 우리 코드(또는 LangGraph 같은 에이전트 프레임워크)가 맡아. 작은 로컬 모델은 도구 선택이 가끔 엉뚱할 수 있으니 temperature를 낮추고 함수 설명(docstring)을 명확하게 써주는 게 좋아.

또 with_structured_output()을 쓰면 Pydantic 스키마에 맞춘 구조화된 결과를 받을 수도 있어. 리뷰 감성 분석 결과를 {"감정": "긍정", "점수": 0.9} 형태로 받아서 DB에 바로 넣는 식으로 활용하면 꿀이야.

Ollama는 http://localhost:11434/v1 경로로 OpenAI 호환 API도 제공해. 그래서 기존에 OpenAI SDK로 짠 코드가 있다면 base_url만 바꿔서 로컬 모델로 돌려볼 수 있어. LangChain에서도

ChatOpenAI(base_url="http://localhost:11434/v1", api_key="ollama", model="qwen2.5:7b")

이런 로컬 AI 구축 역량은 요즘 프리랜서 시장에서도 꽤 수요가 있어. 실제로 재능넷 같은 재능 공유 플랫폼에선 사내 문서 챗봇 구축, RAG 파이프라인 세팅 같은 AI 개발 의뢰가 꾸준히 올라오고 있으니, 오늘 만든 걸 포트폴리오로 다듬어 두면 쓸모가 꽤 많을 거야.

※ LangChain과 Ollama는 업데이트가 매우 빠른 프로젝트라 클래스 이름·기본값·지원 모델이 바뀔 수 있어. 실제 적용 전엔 LangChain 공식 문서(python.langchain.com)의 Ollama 통합 페이지와 Ollama 공식 GitHub(github.com/ollama/ollama) 문서를 함께 확인하는 걸 추천해.