LangChain 연동 방법은 설치, LLM API, RAG, 에이전트를 한 환경에서 맞추는 작업입니다. Python 3.10 이상을 쓰고 코어 패키지를 올린 다음 모델은 독립 provider 패키지로 연결합니다.
키는 소스에 넣지 말고 환경변수로 주입합니다. 검색은 벡터스토어의 as_retriever()로 붙이고 에이전트 호출은 LangSmith 트레이스로 경로를 확인하면 장애 지점을 빨리 찾습니다. 준비부터 오류 점검까지 같은 순서로 진행하면 서비스 반영이 안정적입니다.
LangChain 연동 전 준비와 환경 설정
연동 전에 런타임과 패키지 경계를 먼저 고정합니다. 코어 langchain과 OpenAI·Anthropic용 provider는 설치 단위가 다르므로 한 명령으로 섞지 않습니다. 가상환경을 만들고 파이썬 버전을 확인한 뒤 키와 트레이싱 변수를 준비하면 인증 오류가 줄어듭니다.
프로젝트 루트에는 비밀값을 두고 런처에서만 읽습니다. 의존성 잠금 파일을 커밋하면 다른 머신에서도 같은 조합으로 재설치할 수 있습니다. 운영 서버와 로컬의 파이썬 마이너 버전이 어긋나면 import 오류가 나므로 이미지를 통일하십시오.
CI에서는 테스트용 키 범위를 분리합니다. 프로덕션 키로 단위 테스트를 돌리면 할당량이 새므로 모의 클라이언트를 쓰는 편이 안전합니다.
패키지 설치와 버전 맞추기
공식 설치는 pip install -U langchain 또는 uv add langchain입니다. 요구 런타임은 Python 3.10 이상입니다. LLM 호출은 코어만으로 부족하고 langchain-openai, langchain-anthropic처럼 공급자 패키지를 추가합니다.
버전을 맞출 때는 코어와 provider의 메이저 라인을 같이 올립니다. 잠금 파일에 버전을 고정하면 재현 설치가 가능합니다. pip list로 langchain과 langchain-openai 버전을 같이 적어 두면 장애 때 비교가 빠릅니다.
uv를 쓰는 팀은 잠금과 가상환경 생성을 한 흐름으로 맞출 수 있습니다. pip만 쓰는 팀도 requirements.txt 해시를 검증하면 버전 어긋남을 줄입니다.
API 키·환경변수 관리
OpenAI는 OPENAI_API_KEY를 환경변수로 설정한 뒤 ChatOpenAI를 사용합니다. 셸 export나 프로세스 매니저에 넣고 저장소에는 키를 커밋하지 않습니다. Anthropic도 전용 키 변수와 langchain-anthropic을 씁니다.
로컬과 서버의 변수 이름이 갈리면 인증 실패가 납니다. 배포 전에 변수명을 동일하게 맞춰 두십시오. .env는 깃 무시 목록에 넣고 예시 파일에는 키 이름만 남깁니다.
키를 교체한 뒤에는 구 키를 폐기하고 워커 프로세스만 재시작해 캐시된 값을 비웁니다. 컨테이너라면 시크릿 마운트가 읽기 전용인지 확인하십시오.
OpenAI·Claude 등 LLM API 연결하기
(출처: 나도코딩)
OpenAI 연동은 langchain-openai를 설치한 뒤 ChatOpenAI로 모델명을 고릅니다. temperature와 timeout을 생성자에 명시하면 응답 길이와 대기 시간이 예측 가능합니다. Claude는 langchain-anthropic으로 같은 채팅 인터페이스에 맞춥니다.
스트리밍이 필요하면 스트림 메서드를 호출합니다. 실패 재시도 횟수를 제한해야 토큰 비용이 한없이 늘지 않습니다. 모델 ID는 콘솔과 문서를 기준으로 고정하고 별칭을 코드에 흩뿌리지 마십시오.
같은 프롬프트라도 모델 세대가 바뀌면 툴 호출 형식이 달라질 수 있습니다. 스테이징에서 한 세트를 회귀 질의해 응답 스키마를 확인하십시오. 호출 로그에는 프롬프트 전체가 아니라 요청 해시와 모델명만 남겨 유출을 줄입니다.
벡터 DB와 RAG 파이프라인 연동
벡터스토어는 as_retriever() 호출로 Retriever를 얻습니다. search_type은 similarity가 기본이고 mmr, similarity_score_threshold도 있습니다. search_kwargs로 k와 filter를 넘기면 상위 문서 수와 메타데이터 조건을 조절합니다.
| search_type | 역할 | 자주 쓰는 search_kwargs |
|---|---|---|
| similarity | 기본 유사도 검색 | k, filter |
| mmr | 유사도와 다양성 균형 | k, fetch_k, lambda_mult |
| similarity_score_threshold | 점수 하한으로 필터 | score_threshold, k |
청크 크기와 임베딩 모델은 문서 길이에 맞춰 고릅니다. 인덱스를 갱신한 뒤 같은 질의로 검색 결과를 비교하면 파이프라인이 맞는지 확인할 수 있습니다. 임베딩 모델을 바꾸면 인덱스를 다시 쌓아야 점수가 맞습니다.
유사도만 쓰면 비슷한 청크가 몰릴 수 있어 다양성이 필요하면 mmr을 고릅니다. 점수 하한을 두면 관련 없는 문서를 답에 섞지 않습니다.
에이전트·툴 호출로 서비스에 붙이기
create_agent 기반 에이전트는 도구 함수를 바인딩해 서비스 API를 호출합니다. LANGSMITH_TRACING=true와 LANGSMITH_API_KEY만 설정하면 코드 추가 없이 LangSmith에 트레이스를 남깁니다. 기본 프로젝트명은 default입니다.
툴 스키마에는 인자 타입과 설명을 밝힙니다. 결제나 삭제처럼 부작용이 있는 호출에는 확인 단계를 두어 오호출을 줄입니다. 트레이스에서 툴 입력과 LLM 출력을 보면 연동 위치를 특정하기 쉽습니다.
도구 이름과 설명은 모델이 고르는 기준이므로 동사를 명확히 씁니다. 타임아웃이 없는 HTTP 툴은 에이전트 전체가 멈출 수 있으니 제한 시간을 거십시오. LangSmith 프로젝트명을 서비스 단위로 나누면 원인 추적이 빨라집니다.
자주 겪는 오류와 연동 체크리스트 정리
자주 나는 오류는 키 미설정, provider 미설치, retriever 인자 누락입니다. 체크리스트로 파이썬 버전, 패키지, 환경변수, 검색 타입, LangSmith 연결을 순서대로 확인합니다. 한 항목이 빠지면 증상이 인증 실패나 빈 검색으로 갈립니다.
배포 전 스테이징에서 동일 변수와 동일 인덱스로 한 번 더 호출하십시오. 로그에 모델명과 k 값을 남기면 재현이 빠릅니다. 빈 답변은 검색 k와 점수 하한부터 점검하는 편이 안전합니다.
점검 순서를 내부 문서에 고정해 두면 담당자가 바뀌어도 같은 기준으로 확인합니다. 실패 로그에는 키 값을 넣지 말고 변수 이름과 HTTP 상태만 남기십시오.
토큰·레이트 리밋 대응
토큰 한도와 레이트 리밋에 걸리면 429와 사용량 오류가 납니다. 배치 크기를 줄이고 지수 백오프로 재시도하되 무한 반복은 막습니다. 컨텍스트가 길면 요약 후 RAG의 k를 낮춥니다.
계정에 한도 알림을 켜 두면 장애 전에 사용량을 볼 수 있습니다. 모델별로 RPM과 TPM이 다르므로 같은 키로 여러 서비스가 때리면 한도에 더 빨리 닿습니다. 피크 시간에는 동시 요청 상한을 프로세스 단위로 걸어 두십시오.
스트리밍도 토큰이 나오는 동안 과금이 쌓입니다. 최대 출력 길이를 생성자에 걸어 예상 비용을 제한하십시오. 프롬프트에 원문을 모두 붙이지 말고 검색된 청크만 넣으면 입력 토큰이 줄어듭니다.
