하이퍼클로바 X 랭체인 프로젝트 및 서버 구축하기

 

불과 몇 주전인 10월 말 11월 초쯤 랭체인에 하이퍼클로바X를 연동할 수 있는 ChatCLOVA X가 등장했습니다. AI 생태계를 거의 지배하고 있는 랭체인 프레임워크에서 공식적으로 지원하는 한국 최초의 오픈소스 모델이 등장했다는 점은 상당히 고무적으로 다가오는 것 같습니다.

 

지난달까지만 해도 제가 랭체인 v0.3에 하이퍼클로바x 연동하기라는 포스팅을 작성했었는데요. 포스팅을 작성한 게 무색할 정도로 작성한 지 불과 며칠 만에 공식지원 모듈이 등장했습니다.

 

 따라서 이제는 커스텀모델로 직접 만들지 않아도 사용하고 계신 langchain의 버전만 맞춰주신다면 공식적으로 HyperCLOVA X 사용이 가능해졌는데요. 이번 포스팅에서는 랭체인에서 지원하는 HyperCLOVA X 연동 모듈에서는 어떤 기능들이 지원되는지 한번 알아보고 어떻게 하면 랭체인 프로젝트에서 HyperCLOVAX 모듈을 추가하여 서버로 구동시킬 수 있는지에 대해 가이드드리도록 하겠습니다.

 

---

 

🪄 ChatClovaX 무엇이 가능할까?

HyperCLOVA X의 공식 클래스명은 ChatClovaX라는 이름으로 등장했습니다. 이쁘게 잘 나온 것 같죠? ChatCLOVA X는 아래와 같이 langchain-community 패키지에 속하게 되었으며 v0.3.4 버전부터 사용 가능합니다.

 

https://github.com/langchain-ai/langchain/releases?q=tag%3A"langchain-community%3D%3D0"&expanded=true

 

ChatCLOVA X는 랭체인에서 어떤 기능들을 제공하고 있을까요? 우선, 가장 많은 기능을 지원하고 있는 openai의 ChatOpenAI 클래스와 비교해서 확인해 보도록 하겠습니다.

 

(좌) ChatClovaX (우) ChatOpenAi

 

언뜻 보았을 때 아직은 많은 기능들을 지원하고 있지는 않습니다. Tool Calling이나 구조적인 아웃풋 생성, JSON 모드, 이미지 입력등은 사용할 수 없는 것으로 보여지고 있습니다.

 

JS가 아직 지원이 안된다는 점도 사실 많이 아쉽긴 했는데요. 그럼에도 다행인 점은 AI filter기능과 테스트앱과 파인튜닝 모델들도 사용가능하도록 지원하는 점에 있어서 파이썬을 사용한다면 크게 불편한 점은 없었던 것 같습니다. 자세한 내용은 하단의 링크를 통해 확인하실 수 있습니다.

 

ChatClovaX | 🦜️🔗 LangChain

 

ChatCLOVA X는 0.3.4 버전부터 사용 가능하다고 앞서 말씀드렸었는데요. 이 포스팅을 작성한 지 불과 몇 시간 전에 0.3.8이 등장하면서 몇 가지 또 달라진 점들이 존재하네요. 기왕 이렇게 된 거 저는 전부 최신 버전으로 설치해서 진행해 보도록 하겠습니다.

 

---

 

🦜 랭체인 프로젝트 구동환경 세팅하기

이제 본격적으로 ChatClovaX를 연동하기 위한 랭체인 세팅을 진행해 보도록 하겠습니다. 랭체인 프로젝트를 처음부터 세팅하려면 많은 시간과 노력이 동반될 수 있는데요. 이럴 때는 langchain-cli를 설치하여 사용하는 것이 좋습니다.

 

lanchain-cli는 랭서브 프로젝트를 쉽게 만들어주는 보일러플레이트 명령어를 사용할 수 있는 커맨드라인 도구입니다. 프론트 개발자들이라면 react를 처음 배울 때 react-create-app으로 react 프로젝트를 손쉽게 구축하듯이 langchain도 이와 같은 개념으로 보시면 좋을 것 같습니다.

 

langchain-cli를 사용하면 LangServe 프로젝트를 손쉽게 만들어주기 때문에 편리합니다. LangServe는 랭체인 체인을 REST API로 배포할 수 있게 하는 라이브러리입니다. FastAPI 기반으로 되어있기 때문에 개발자들이 손쉽게 애플리케이션으로 구축할 수 있게 됩니다.

 

따라서 먼저 다음과 같이 전역적으로 langchain-cli를 하나 설치해 놓도록 하겠습니다.

pip install langchain-cli

 

langchain-cli가 설치되고 나면 다음과 같은 명령어로 손쉽게 프로젝트를 구축할 수 있게 됩니다.

langchain app new langserve-clova

 

위 명령어를 실행하고 나면 다음과 같이 프로젝트가 생성된 것을 볼 수 있습니다. Dockerfile부터 pyprojct.toml 파일까지 개발과 배포에 필요한 요소들을 자동으로 생성한 것을 확인할 수 있습니다. 그러면 이제 이 프로젝트를 사용하고 계신 에디터를 이용해서 오픈하여 사용하시면 됩니다.

 

lanchain-cli를 설치 후 langchain 명령어를 이용해 간단하게 langserve 프로젝트를 만들 수 있다.

 

프로젝트를 열고 가장 먼저 해야 할 일은 파이썬 버전에 맞게 가상환경을 세팅하는 것이 중요합니다. pyproject.toml 파일을 열어 필요한 파이썬 버전을 확인합니다.

 

langchain-cli로 초기셋팅시 설치된 의존성들

 

보시면 파이썬 3.11 버전 이상을 사용해야 한다고 나와있습니다. 저는 그 보다 더 낮은 버전을 사용하고 있으므로 높은 버전의 파이썬을 하나 더 설치하도록 하겠습니다. 파이썬의 경우 여러 버전들을 관리해야 되는 경우 pyenv를 사용해 주시는 것이 좋습니다.

 

pyenv도 하나 설치해 놓으시면 추후, python을 계속 바꿔가면서 사용하실 수 있기 때문에 편리합니다. 설치하는 방법은 아래 링크에 자세한 설명이 있으므로 참고하시면 좋을 것 같습니다.

 

[Python] 윈도우에서 pyenv 설치하기 (pyenv-win)

 

pyenv를 설치하고 아래 명령어를 이용하면 설치가능한 파이썬 목록이 나타납니다. 저는 stable 버전인 3.12.2를 설치하도록 하겠습니다.

 

pyenv install --list # 설치 가능한 파이썬 목록
pyenv versions # 로컬에 설치된 파이썬 목록

 

pyenv를 통해 python 설치과정

 

파이썬까지 세팅이 되었다면 이번에는 poetry를 사용해서 가상환경에 접속하도록 하겠습니다. 요즘 파이썬의 가상환경과 패키지 의존성관리 도구는 poetry가 많이 뜨고 있는 것 같습니다. Langserve 공식홈페이지 설치 가이드에서도 poetry 사용으로 가이드가 나와있는 것을 확인하실 수 있습니다.

 

poetry 역시 PC에 따로 설치가 안 돼있다면 아래 링크를 통해 미리 설치해서 준비해 주시면 좋습니다.

[Python] 윈도우에서 poetry 설치하기

 

poetry가 설치가 되었다면 다음과 같이 pyenv 명령어로 설치된 파이썬의 위치를 확인하고 poetry에 해당 버전의 파이썬을 세팅하시면 됩니다.

 

pyenv which python
poetry env use {위에서 찾은 파이썬 경로}

설치한 파이썬 버전으로 poetry 설정

 

그 이후에는 poetry shell 명령어를 입력하시면 python v3.12 환경으로 가상환경에 접속된 것을 확인하실 수 있습니다.

 

poetry shell

poetry로 python3.12 프로젝트 가상환경 접속하기

 

---

 

🍀 랭체인에서 ChatClovaX 사용하기

앞서 확인한 바로 ChatClovaX를 사용하려면 랭체인 최신 버전을 사용해야 합니다. 따라서 의존성 관리 패키지 스크립트를 그대로 사용하는 게 아니라 일부 수정해주어야 합니다. pyproject.toml 파일을 열어 아래와 같이 필요한 패키지들을 추가해 주시면 됩니다.

 

[tool.poetry.dependencies]
python = "^3.12"
pydantic = ">=2.7.4,<3.0.0"
langchain = "^0.3.8"
langchain-community = "^0.3.8"
python-dotenv = "^1.0.1"

 

python의 경우 3.12 버전으로 설치를 진행했기 때문에 다음과 같이 변경을 하였습니다. 그 외에 pydantic은 랭체인 0.3 버전부터는 pydantic 2 버전 이상을 사용해야 하기 때문에 그에 맞춰 올려주었고 기본적으로 langchain과 langchain-community가 안 깔려있기 때문에 ChatClovaX를 사용하기 위해 다음과 같이 최신버전으로 설치를 해주었습니다. 마지막으로 python-dotenv는 여러분들도 잘 알다시피 API KEY를 저장하고 불러들이기 위해 같이 설치하였습니다.

 

위에서 수정한 내용들을 반영하려면 다음과 같이 업데이트 명령어를 실행해 주시면 됩니다.

poetry update

 

그 이후에는 간단하게 프로젝트에 생성되어 있는 app/server.py를 다음과 같이 수정합니다.

 

import os

from dotenv import load_dotenv
from fastapi import FastAPI
from fastapi.responses import RedirectResponse
from langchain.prompts import ChatPromptTemplate
from langchain_community.chat_models import ChatClovaX
from langserve import add_routes

load_dotenv()  # .env 파일 로드

app = FastAPI()

# CLOVA X API 키 설정
clovastudio_api_key = os.getenv("NCP_CLOVASTUDIO_API_KEY")#.env 파일에 키 등록
apigw_api_key = os.getenv("NCP_APIGW_API_KEY") #.env 파일에 키 등록

# CLOVA X 모델 초기화
model = ChatClovaX(
    model="HCX-003",
    max_tokens=100,
    temperature=0.7,
    clovastudio_api_key=clovastudio_api_key,
    apigw_api_key=apigw_api_key,
    service_app=False,
    include_ai_filters=True
)

# 프롬프트 템플릿 생성
prompt = ChatPromptTemplate.from_messages([
    ("system", "당신은 조선의 왕입니다."),
    ("human", "{input}")
])

# CLOVA X 체인 생성
chain = prompt | model

@app.get("/")
async def redirect_root_to_docs():
    return RedirectResponse("/docs")

# CLOVA X 체인 라우트 추가
add_routes(app, chain)

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

 

먼저 가장 상단에서는 CLOVA를 사용하기 위한 API 키를 불러왔습니다. 그 이후에는 model에 필요한 설정 값들을 입력해 주었습니다. model은 HCX-003, HCX-DASH-001를 사용할 수 있는데 저는 HCX-003을 사용하였습니다.

 

그리고 사용할 하이퍼파라미터값들과 API키 값들을 매개변수로 추가로 넣어주었고, 서비스 앱이 아니다 보니 옵션을 False로 설정하고 AI 필터도 한번 적용시켜 보았습니다.

 

그 후에는 프롬프트 템플릿을 생성하였습니다. 제가 세미나 발표 때마다 자주 사용했던 예시인데요. 이제 그만 좀 사용할 법도 한 조선의 임금님 페르소나를 한번 더 꺼내보도록 하겠습니다. 시스템 메시지에 넣어주시면 됩니다.

 

마지막으로는 완성한 프롬프트와 모델을 체인으로 걸어서 라우트에 추가합니다. 이렇게 코드를 짜면 간단하게 HyperCLOVA X를 랭체인에서 사용하실 수 있게 됩니다. 한번 서버를 실행해 보도록 하겠습니다.

 

uvicorn app.server:app --host 0.0.0.0 --port 8080

 

다음과 같이 유비콘을 실행하고 나면 랭서브가 구동되는 것을 확인하실 수 있게 됩니다.

 

랭서브 구동 성공

 

랭서브로 구동하면 다음과 같이 플레이그라운드를 지원하는데요. 만들어 놓은 라우터 뒤에 /playground만 입력하시면 다음과 같이 멋진 테스트 환경이 나타납니다. langserve를 사용하면 이제 더 이상 힘들게 streamlit이나 gradio 같은 UI도구를 구현하지 않아도 된다는 장점이 있습니다.

 

랭서브 플레이그라운드에서 랭체인으로 HyperCLOVAX 호출 테스트해보기

 

추가로 랭서브를 사용하면 다음과 같이 /invoke, /batch, /stream 등 구현이 복잡한 기능들도 라우터만 선언해준다면 API로 자동으로 만들어준다는 장점이 있습니다. 자동으로 Swagger와 연동이 되어 API docs를 만들어준다는 점 또한 훌륭한 기능 중 하나인 것 같습니다.

 

랭서브에서 자동으로 만들어준 API DOCS

 

위 기능들을 잘 활용한다면 HyperCLOVA X를 한층 더 손 쉽게 활용할 수 있기 때문에 랭체인에 HyperCLOVA X 연동 시 랭서브 도입도 같이 한번 고려해 보면 좋을 것 같다는 생각이 듭니다.

 

---

 

🌠 마무리하며

랭체인에서 HyperCLOVA X를 사용해 보고 간단하게 서버로 띄워보는 작업까지 진행해 보았는데요. 요즘, 왜 그렇게까지 랭체인이 각광받고 있는지 알 수 있었던 경험이 아닌가 싶습니다. langchain을 활용한 프롬프트, 모델 체이닝부터 lanchain-cli를 통한 빠른 프로젝트 세팅, langserve를 활용한 빠른 REST API 서버 구축 등 안쓸 이유가 전혀 없는 프레임워크라는 생각이 들었습니다.

 

저는 langserve까지 같이 진행해보았지만 langserve없이 바로 langchain연동만 해보고 싶다 하시는 분들은 네이버클라우드 공식가이드 문서에서도 소개가 되어있으므로 직접 핸즈온 해보셔도 좋을것 같습니다.

 

https://guide.ncloud-docs.com/docs/clovastudio-dev-langchain

 

랭체인의 무서운 발전속도에 발맞춰 빠르게 탑승한 네이버클라우드도 인상적이었는데요. 앞으로도 랭체인에서 HyperCLOVA X를 적용한 좋은 성공 사례와 아키텍처가 많이 나오면서 국내 AI 기업의 좋은 선례가 되었으면 하는 바람이 듭니다.☺️