LLM 애플리케이션 · RAG · AI Agent 개발 가이드

LangChain 완전 가이드

LangChain으로 모델과 프롬프트를 연결하고, 구조화된 출력, Tool Calling, RAG, AI Agent, 스트리밍과 LangSmith 관측까지 구현하는 흐름을 정리합니다.

LLM
Prompt
LCEL
RAG
AI Agent
LangSmith

AI DevOps Learn에서 LangChain을 단계별로 학습하세요 원문 가이드에서는 LangChain 핵심 개념과 실습 흐름을 한 번에 확인할 수 있습니다.
LangChain 원문 가이드 열기 →

이 글의 핵심
LangChain은 모델 하나를 호출하는 라이브러리가 아니라 모델, 프롬프트, 데이터, 도구와 실행 흐름을 조합해 LLM 애플리케이션과 Agent를 만드는 프레임워크입니다. 실무에서는 편리한 추상화뿐 아니라 timeout, retry, 평가, 관측성, 권한 통제와 비용 관리까지 함께 설계해야 합니다.

1. LangChain이란?

LangChain은 LLM 기반 애플리케이션과 AI Agent를 만들기 위한 오픈소스 프레임워크입니다. 여러 모델 제공자, 외부 도구, 데이터베이스와 검색 시스템을 일관된 인터페이스로 연결할 수 있도록 도와줍니다.

구성 요소	주요 역할
Chat Model	OpenAI, Anthropic, Google 등 모델 제공자를 공통 인터페이스로 호출합니다.
Prompt	system, user 메시지와 입력 변수를 템플릿으로 관리합니다.
Runnable / LCEL	프롬프트, 모델, parser와 사용자 정의 함수를 파이프라인으로 연결합니다.
Retriever	문서와 벡터 저장소에서 질문에 관련된 내용을 검색합니다.
Tool	검색, 계산, 데이터베이스, 사내 API 등 외부 기능을 모델에 제공합니다.
Agent	모델이 상황에 따라 도구를 선택하고 여러 단계를 실행하도록 구성합니다.

사용자 입력

Prompt

LLM

Tool·RAG

최종 응답

2. 설치와 환경 변수

LangChain 코어와 모델 제공자별 integration 패키지를 분리해 설치합니다. 실제 프로젝트에서는 사용하는 모델과 vector store 패키지만 선택해서 설치하는 편이 좋습니다.

Bash

# 가상환경 생성
uv venv

# Linux / macOS
source .venv/bin/activate

# Windows PowerShell
# .venv\Scripts\Activate.ps1

# LangChain과 OpenAI integration
uv pip install langchain langchain-openai

# RAG 예제를 위한 선택 패키지
uv pip install langchain-chroma langchain-text-splitters

API Key 환경 변수

Bash

export OPENAI_API_KEY="your-api-key"

# Windows PowerShell
# $env:OPENAI_API_KEY="your-api-key"

API Key 보안
API Key를 소스 코드, Git 저장소, Docker 이미지나 블로그 예제에 직접 포함하지 마세요. 로컬에서는 환경 변수, 운영에서는 Secret Manager나 Kubernetes Secret을 사용하세요.

3. Chat Model 호출

init_chat_model을 사용하면 모델 제공자를 문자열로 지정하고 공통 인터페이스로 호출할 수 있습니다. 운영 코드에서는 모델 이름과 temperature, timeout을 설정으로 분리하는 것이 좋습니다.

Python

from langchain.chat_models import init_chat_model

model = init_chat_model(
    "openai:gpt-5.5",
    temperature=0,
)

response = model.invoke(
    "LangChain의 핵심 개념을 세 문장으로 설명해줘"
)

print(response.content)

모델 이름과 지원 옵션은 제공자와 버전에 따라 달라질 수 있습니다. 실제 배포 전에는 사용 중인 integration 패키지와 모델 제공자의 공식 문서를 확인하세요.

4. Prompt와 LCEL

LangChain Expression Language(LCEL)는 프롬프트, 모델과 출력 parser를 | 연산자로 연결하는 방식입니다. 각 단계가 Runnable 인터페이스를 따르기 때문에 invoke, batch, stream을 일관되게 사용할 수 있습니다.

Python

from langchain.chat_models import init_chat_model
from langchain_core.output_parsers import StrOutputParser
from langchain_core.prompts import ChatPromptTemplate

prompt = ChatPromptTemplate.from_messages([
    (
        "system",
        "당신은 이해하기 쉽게 설명하는 AI 개발 강사입니다.",
    ),
    (
        "human",
        "{topic}을 초보 개발자에게 설명해 주세요.",
    ),
])

model = init_chat_model(
    "openai:gpt-5.5",
    temperature=0,
)

chain = prompt | model | StrOutputParser()

result = chain.invoke({
    "topic": "RAG",
})

print(result)

여러 입력을 한 번에 처리하기

Python

results = chain.batch([
    {"topic": "Prompt Template"},
    {"topic": "Tool Calling"},
    {"topic": "Vector Store"},
])

for result in results:
    print(result)
    print("-" * 60)

5. 구조화된 출력

모델 응답을 문자열로만 받으면 JSON 형식 오류나 필드 누락을 처리하기 어렵습니다. with_structured_output을 사용하면 Pydantic 모델에 맞는 결과를 받을 수 있습니다.

Python

from pydantic import BaseModel, Field
from langchain.chat_models import init_chat_model


class ArticleSummary(BaseModel):
    title: str = Field(description="요약 제목")
    summary: str = Field(description="핵심 요약")
    keywords: list[str] = Field(
        description="핵심 키워드 목록",
    )


model = init_chat_model(
    "openai:gpt-5.5",
    temperature=0,
)

structured_model = model.with_structured_output(
    ArticleSummary
)

result = structured_model.invoke(
    "LangChain을 소개하는 블로그 글을 요약해 주세요."
)

print(result.title)
print(result.summary)
print(result.keywords)

구조화된 출력도 모델 응답에 의존하므로 입력 검증과 예외 처리는 필요합니다. 외부 시스템에 저장하거나 결제·권한 변경처럼 중요한 작업에 사용할 때는 비즈니스 규칙을 별도 코드로 다시 검증하세요.

6. Tool Calling Agent

Agent는 모델이 현재 요청에 필요한 도구를 선택하고 결과를 다시 해석하도록 구성합니다. 도구 설명은 모델이 언제 어떻게 호출해야 하는지 판단하는 기준이 되므로 입력과 반환값, 권한 범위를 명확하게 정의해야 합니다.

Python

from langchain.agents import create_agent
from langchain.tools import tool


@tool
def get_service_status(service_name: str) -> str:
    """서비스 이름으로 현재 운영 상태를 조회합니다."""
    status = {
        "api": "정상",
        "worker": "점검 중",
        "database": "정상",
    }

    return status.get(
        service_name.lower(),
        "등록되지 않은 서비스입니다.",
    )


agent = create_agent(
    model="openai:gpt-5.5",
    tools=[get_service_status],
    system_prompt=(
        "당신은 서비스 운영 도우미입니다. "
        "상태 질문에는 필요한 도구를 사용하세요."
    ),
)

result = agent.invoke({
    "messages": [
        {
            "role": "user",
            "content": "worker 서비스 상태를 확인해 줘",
        }
    ]
})

print(result["messages"][-1].content)

Tool 보안 주의
Agent에게 파일 삭제, 명령 실행, 결제, 이메일 발송과 같은 기능을 제공할 때는 허용 목록, 사용자 권한, 입력 검증, 실행 제한과 승인 절차를 적용해야 합니다. 모델의 판단만으로 중요한 작업을 바로 실행하지 마세요.

7. RAG 구현

RAG는 질문과 관련된 문서를 먼저 검색한 뒤 검색 결과를 모델의 context로 전달해 답변을 생성하는 방식입니다. 모델이 학습하지 않은 사내 문서나 최신 자료를 활용할 때 유용합니다.

Python

from langchain.chat_models import init_chat_model
from langchain_chroma import Chroma
from langchain_core.documents import Document
from langchain_core.output_parsers import StrOutputParser
from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import OpenAIEmbeddings
from langchain_text_splitters import RecursiveCharacterTextSplitter

documents = [
    Document(
        page_content=(
            "PRO 플랜은 고급 이력서 템플릿과 "
            "AI 코칭 기능을 제공합니다."
        ),
        metadata={"source": "pricing"},
    ),
    Document(
        page_content=(
            "회원은 설정 화면에서 구독을 해지할 수 있습니다."
        ),
        metadata={"source": "subscription"},
    ),
]

splitter = RecursiveCharacterTextSplitter(
    chunk_size=300,
    chunk_overlap=50,
)

chunks = splitter.split_documents(documents)

vector_store = Chroma.from_documents(
    documents=chunks,
    embedding=OpenAIEmbeddings(),
)

retriever = vector_store.as_retriever(
    search_kwargs={"k": 3},
)

prompt = ChatPromptTemplate.from_messages([
    (
        "system",
        "아래 문서에 근거해서만 답변하세요. "
        "근거가 없으면 모른다고 답하세요.\n\n{context}",
    ),
    ("human", "{question}"),
])

model = init_chat_model(
    "openai:gpt-5.5",
    temperature=0,
)


def format_documents(docs):
    return "\n\n".join(
        f"[출처: {doc.metadata.get('source')}]\n"
        f"{doc.page_content}"
        for doc in docs
    )


def answer(question: str) -> str:
    docs = retriever.invoke(question)
    context = format_documents(docs)

    chain = prompt | model | StrOutputParser()

    return chain.invoke({
        "context": context,
        "question": question,
    })


print(answer("PRO 플랜에는 어떤 기능이 있나요?"))

RAG 품질에 영향을 주는 요소

문서 파싱 과정에서 표와 제목 구조가 유지되는지 확인합니다.
chunk 크기와 overlap을 문서 특성에 맞게 조정합니다.
embedding 모델과 실제 질문 언어가 잘 맞는지 평가합니다.
검색 결과에 문서 ID, 제목, URL 같은 source metadata를 유지합니다.
검색 실패와 낮은 관련도에서 답변을 거절하는 기준을 둡니다.
인용과 근거 문장을 사용자에게 함께 제공합니다.

8. 스트리밍

긴 답변은 전체 생성이 끝날 때까지 기다리는 대신 token 또는 message chunk 단위로 사용자에게 전달할 수 있습니다.

Python

from langchain.chat_models import init_chat_model

model = init_chat_model(
    "openai:gpt-5.5",
)

for chunk in model.stream(
    "LangChain으로 AI Agent를 만드는 흐름을 설명해줘"
):
    if chunk.content:
        print(
            chunk.content,
            end="",
            flush=True,
        )

웹 서비스에서는 클라이언트 연결 종료, 생성 취소, timeout과 부분 응답 저장 여부를 함께 설계해야 합니다. SSE 또는 WebSocket 같은 전송 방식도 서비스 환경에 맞게 선택하세요.

9. LangSmith 관측

Agent와 RAG는 여러 단계의 모델 호출과 도구 실행으로 구성되므로 최종 응답만 보고 문제 원인을 찾기 어렵습니다. LangSmith tracing을 사용하면 입력, 모델 호출, tool 실행과 latency를 추적할 수 있습니다.

Bash

export LANGSMITH_TRACING="true"
export LANGSMITH_API_KEY="your-langsmith-api-key"
export LANGSMITH_PROJECT="aidevops-langchain"

관측 시 확인할 지표

요청별 전체 latency와 단계별 모델 호출 시간
입력 token, 출력 token과 요청별 비용
Tool 선택 정확도와 도구 호출 실패율
Retriever 검색 결과와 문서 관련도
timeout, retry와 fallback 발생 횟수
사용자 피드백과 평가 점수

10. LangChain 실무 설계

Prompt와 체인을 한 파일에 모두 작성하기보다 모델, prompt, tool, retriever, agent와 API 계층을 분리하는 것이 좋습니다. LangChain 의존 코드를 도메인 로직과 분리하면 모델이나 framework를 교체할 때 영향 범위를 줄일 수 있습니다.

결정 지점	확인 질문	실무 기준
모델	특정 제공자 API에 코드가 강하게 결합되어 있는가?	모델 이름과 옵션을 설정으로 분리하고 adapter 경계를 둡니다.
Prompt	Prompt 변경 이력과 평가 결과를 추적할 수 있는가?	Prompt를 버전 관리하고 변경 전후 평가를 수행합니다.
Tool	Agent가 실행 가능한 작업 범위가 명확한가?	최소 권한과 사용자 승인, 입력 검증을 적용합니다.
RAG	답변의 출처와 문서 버전을 확인할 수 있는가?	source metadata와 문서 버전을 응답까지 전달합니다.
장애	모델이나 vector store가 실패하면 어떻게 되는가?	timeout, retry, fallback과 오류 계약을 정의합니다.

권장 프로젝트 구조

11. 운영 기준

운영 전 확인 목록

모델 이름, temperature, max token과 timeout을 설정으로 관리합니다.
API Key와 데이터베이스 접근 정보는 secret으로 관리합니다.
사용자별 요청량, token과 비용 제한을 적용합니다.
Tool마다 허용 작업과 권한을 최소화합니다.
Prompt injection과 데이터 유출 방어 규칙을 적용합니다.
RAG 답변에 출처를 제공하고 근거가 없을 때는 답변을 제한합니다.
모델 호출, retriever와 tool 실행을 trace로 남깁니다.
모델 또는 외부 API 장애에 대비한 fallback을 준비합니다.

12. 검증 전략

LLM 애플리케이션은 같은 입력에도 표현이 달라질 수 있어 문자열 전체 일치만으로 테스트하기 어렵습니다. 구조 검증, 고정 평가 데이터셋, 규칙 기반 검사와 사람 평가를 조합해야 합니다.

품질 축	검증 방법	완료 기준
기능	Prompt, parser, tool과 retriever 단위 테스트	정상·경계·실패 입력이 자동화되어 있습니다.
회귀 방지	실제 장애 사례를 regression dataset으로 유지	같은 실패가 다음 버전에 재발하지 않습니다.
RAG 품질	검색 정확도, 근거 포함률과 답변 충실도 평가	문서에 없는 내용을 단정하지 않습니다.
Agent 안전성	잘못된 tool 호출, 권한 우회와 prompt injection 테스트	허가되지 않은 작업이 실행되지 않습니다.
성능	TTFT, 전체 latency, token, 동시성과 비용 측정	서비스 목표와 예산 범위를 충족합니다.
운영성	trace, metric, alert와 fallback 시나리오 검증	장애 원인 추적과 복구 경로가 존재합니다.

마무리

LangChain을 잘 활용하려면 체인이나 Agent 코드를 빠르게 만드는 것뿐 아니라 Prompt, 데이터, Tool 권한과 평가 체계를 함께 관리해야 합니다. 처음에는 단순한 모델 호출과 구조화된 출력부터 시작하고, 실제 필요가 확인된 영역에 RAG와 Agent를 단계적으로 추가하는 접근이 안정적입니다.

핵심 정리

Prompt, 모델과 parser를 LCEL 파이프라인으로 연결합니다.
중요한 결과는 구조화된 출력과 비즈니스 규칙으로 다시 검증합니다.
RAG에서는 검색 품질, 출처와 답변 거절 기준을 함께 관리합니다.
Tool Calling은 최소 권한과 사용자 승인 절차를 적용합니다.
LangSmith tracing과 고정 평가 데이터셋으로 품질 회귀를 관리합니다.

원문: AI DevOps Korea LangChain 가이드 · 참고: LangChain 공식 문서

'개발 가이드 > AI 개발' 카테고리의 다른 글

[AI 개발] 7. LI LlamaIndex 완전 가이드 (1)	2026.07.19
[AI 개발] 5. Hugging Face 완전 가이드 (0)	2026.07.19
[AI 개발] 4. JAX 완전 가이드 (0)	2026.07.19
[AI 개발] 3. PyTorch 완전 가이드 (0)	2026.07.19
[AI 개발] 2. C++와 ML/AI 완전 가이드 (0)	2026.07.19

Plog Dev Insight - 클라우드, 아키텍처, 개발 .. 블로그

[AI 개발] 6. LC LangChain 완전 가이드

LangChain 완전 가이드

1. LangChain이란?

2. 설치와 환경 변수

API Key 환경 변수

3. Chat Model 호출

4. Prompt와 LCEL

여러 입력을 한 번에 처리하기

5. 구조화된 출력

6. Tool Calling Agent

7. RAG 구현

RAG 품질에 영향을 주는 요소

8. 스트리밍

9. LangSmith 관측

관측 시 확인할 지표

10. LangChain 실무 설계

권장 프로젝트 구조

11. 운영 기준

12. 검증 전략

마무리

'개발 가이드 > AI 개발' 카테고리의 다른 글

댓글

티스토리툴바

[AI 개발] 6. LC LangChain 완전 가이드

LangChain 완전 가이드

1. LangChain이란?

2. 설치와 환경 변수

API Key 환경 변수

3. Chat Model 호출

4. Prompt와 LCEL

여러 입력을 한 번에 처리하기

5. 구조화된 출력

6. Tool Calling Agent

7. RAG 구현

RAG 품질에 영향을 주는 요소

8. 스트리밍

9. LangSmith 관측

관측 시 확인할 지표

10. LangChain 실무 설계

권장 프로젝트 구조

11. 운영 기준

12. 검증 전략

마무리

'개발 가이드 > AI 개발' 카테고리의 다른 글

관련글

댓글

티스토리툴바