LangChain 연동

Classic/VPC 환경에서 이용 가능합니다.

CLOVA Studio의 HyperCLOVA X 모델과 임베딩 도구를 손쉽게 연동하여 사용하기 위해 LangChain을 활용할 수 있습니다.

LangChain은 언어 모델 기반 애플리케이션을 지원하는 오픈소스 프레임워크입니다. HyperCLOVA X를 포함한 여러 언어 모델과 벡터 데이터베이스, 검색 엔진 등의 여러 도구를 사슬(Chain)처럼 엮어 연결할 수 있어 기능 간 연결 및 통합 개발 과정을 간소화할 수 있습니다. LangChain 연동을 통해 AI 에이전트 개발 프레임워크인 LangGraph 역시 활용할 수 있습니다.

LangChain 연동 가이드에서는 LangChain 설치 방법과 CLOVA Studio 연동 설정 방법을 설명합니다. 또한 LangChain을 통해 CLOVA Studio의 HyperCLOVA X 모델과 임베딩 도구를 이용하는 예제 코드를 제공하여 실제 개발에 참고할 수 있도록 안내합니다.

LangChain 설치 및 확인

CLOVA Studio에 연동하여 LangChain을 사용하려면 버전 3.9 이상의 Python 설치가 필요합니다. Python 설치를 완료한 후에는 다음 명령어를 사용하여 LangChain을 설치한 후 연동에 필요한 langchain-naver 패키지를 설치해 주십시오.

pip install -qU langchain # install LangChain
pip install -qU langchain-naver # install LangChain-NAVER integration package

연동 범위 확인

LangChain을 통해 이용 가능한 CLOVA Studio의 기능은 다음과 같습니다.

• CLOVA Studio 플레이그라운드 메뉴의 챗 모드 모델
  • 모델: 기본 모델(<예시> HCX-005), 기본 모델을 튜닝한 모델
    • 연관 API: Chat Completions, Chat Completions v3, 오픈AI 호환성
  • 연동 예제: HyperCLOVA X 모델 이용
• CLOVA Studio 익스플로러 메뉴의 임베딩(또는 임베딩 v2) 도구
  • 모델: clir-emb-dolphin, clir-sts-dolphin, bge-m3
    • 연관 API: 임베딩, 임베딩v2, 오픈AI 호환성
  • 연동 예제: 임베딩 도구 이용

연동 설정

LangChain을 통해 CLOVA Studio의 기능을 안전하게 사용할 수 있도록 API Key를 환경 변수로 등록하여 API 호출 시 필요한 인증 정보로 사용합니다. API Key는 CLOVA Studio의 [API 키] 메뉴에서 발급받아 확인할 수 있습니다. 서비스 앱은 실제 서비스에 적용하는 경우에 신청하여 생성합니다.

인증 정보를 환경 변수로 등록하는 방법은 다음과 같습니다.

• 터미널을 통해 등록

  export CLOVASTUDIO_API_KEY="<CLOVA-STUDIO-API-KEY>"
  

• Python을 통해 등록

  import getpass
  import os
  
  os.environ["CLOVASTUDIO_API_KEY"] = getpass.getpass(
          "CLOVA Studio API Key 입력: "
      )
  

연동 예제

LangChain과 CLOVA Studio 연동 예제 코드를 소개합니다.

• LangChain을 통해 CLOVA Studio의 HyperCLOVA X 모델을 이용하는 예제
• LangChain을 통해 CLOVA Studio의 임베딩 도구를 이용하는 예제

HyperCLOVA X 모델 이용

LangChain을 통해 CLOVA Studio의 HyperCLOVA X 모델을 이용하는 예제 코드는 다음과 같습니다.

from langchain_naver import ChatClovaX
  
chat = ChatClovaX(
    model="HCX-005" # 모델명 입력 (기본값: HCX-005) 
)

ChatClovaX 클래스의 인스턴스 정의 시 사용할 수 있는 파라미터에 대한 설명은 다음과 같습니다.

LangChain의 Chat model 클래스 메서드인 invoke, stream 등을 통해 챗 모델을 실행할 수 있습니다. 예제 코드는 다음과 같습니다.

• invoke

  messages = [
      (
          "system",
          "CLOVA Studio는 HyperCLOVA X 모델을 활용하여 AI 서비스를 손쉽게 만들 수 있는 개발 도구입니다.",
      ),
      ("human", "CLOVA Studio가 무엇인가요?"),
  ]
  ai_msg = chat.invoke(messages)
  ai_msg
  

• stream

  messages = [
      (
          "system",
          "CLOVA Studio는 HyperCLOVA X 모델을 활용하여 AI 서비스를 손쉽게 만들 수 있는 개발 도구입니다.",
      ),
      ("human", "CLOVA Studio가 무엇인가요?"),
  ]
  
  for chunk in chat.stream(messages):
      print(chunk.content, end="", flush=True)
  

또한, bind_tools 메서드를 통해 CLOVA Studio의 Function calling 기능에 기반한 LangChain의 Tool calling 기능을 구현할 수 있습니다. 예제 코드는 다음과 같습니다.

from langchain_naver import ChatClovaX
from pydantic import BaseModel, Field

chat = ChatClovaX(
    model="HCX-005", # 모델명 입력 (기본값: HCX-005)
    max_tokens=1024 # Function calling 이용 시 1024 이상으로 설정
)

class GetWeather(BaseModel):
    '''주어진 위치의 현재 날씨를 조회합니다.'''

    location: str = Field(
        ..., description="날씨를 조회하고자 하는 위치의 시도명. 예) 경기도 성남시 분당구"
    )

chat_with_tool = chat.bind_tools(
    [GetWeather]
)
ai_msg = chat_with_tools.invoke(
    "분당과 판교 중 어디가 더 덥지?"
)
ai_msg.tool_calls

추론(Thinking) 모델을 이용할 때엔 ChatClovaX 클래스의 인스턴스 정의 시 thinking 파라미터를 통해 관련 기능을 설정하고, 아래와 같이 별도 방법을 통해 추론 과정을 확인할 수 있습니다.

from langchain_naver import ChatClovaX

chat = ChatClovaX(
    model="HCX-007",
    thinking={
        "effort": "low"  # 'none' (추론 미사용), 'low' (기본값), 'medium', or 'high'
    },
)
ai_msg = chat.invoke("3의 3승은 몇인가?")

print(ai_msg.content) # 최종 답변
print(ai_msg.additional_kwargs["thinking_content"]) # 추론 과정

임베딩 도구 이용

LangChain을 통해 CLOVA Studio의 임베딩(임베딩 v2) 도구를 이용하는 예제 코드는 다음과 같습니다.

from langchain_naver import ClovaXEmbeddings
 
embeddings = ClovaXEmbeddings(
    model="clir-emb-dolphin",  # 모델명 (기본값: clir-emb-dolphin)
)

ClovaXEmbeddings 클래스의 인스턴스 정의 시 사용할 수 있는 파라미터는 다음과 같습니다.

LangChain의 Embedding model 클래스 메서드인 embed_query, embed_documents 등을 통해 임베딩 도구를 실행할 수 있습니다. 예제 코드는 다음과 같습니다.

• embed_query

  query = "CLOVA Studio는 HyperCLOVA X 모델을 활용하여 AI 서비스를 손쉽게 만들 수 있는 개발 도구입니다."
  single_vector = embeddings.embed_query(query)
  

• embed_documents

  text1 = "CLOVA Studio는 HyperCLOVA X 모델을 활용하여 AI 서비스를 손쉽게 만들 수 있는 개발 도구입니다."
  text2 = "LangChain은 언어 모델 기반 애플리케이션 개발을 지원하는 오픈소스 프레임워크입니다."
  document = [text1, text2]
  multiple_vector = embeddings.embed_documents(document)