LangChain 연동

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

CLOVA Studio의 HyperCLOVA X 모델과 임베딩 v2 도구를 손쉽게 연동하여 사용하기 위해 LangChain을 활용할 수 있습니다.
LangChain은 언어 모델 기반 애플리케이션 개발을 지원하는 오픈소스 프레임워크입니다. HyperCLOVA X를 포함한 여러 언어 모델과 벡터 데이터베이스, 검색 엔진 등의 여러 도구를 사슬(Chain)처럼 엮어 연결할 수 있어 기능 간 연결 및 통합 개발 과정을 간소화할 수 있습니다. 따라서 CLOVA Studio를 서드 파티 모델 및 도구와 함께 이용할 경우, LangChain을 연동하여 좀 더 간편한 애플리케이션 개발이 가능합니다.
LangChain 연동 가이드에서는 LangChain 설치 방법과 CLOVA Studio 연동 설정 방법을 설명합니다. 또한 LangChain을 통해 CLOVA Studio의 HyperCLOVA X 모델과 임베딩 v2 도구를 이용하는 예제 코드를 제공하여 실제 개발에 참고할 수 있도록 안내합니다.

LangChain 설치 및 확인

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

pip install langchain # install LangChain
pip install langchain-community # install langchain-community package

설치되어 있는 LangChain이 CLOVA Studio와 연동 가능한 버전인지 확인하려면 다음 명령어를 사용해 주십시오.

pip show langchain-community

버전 확인 결과 langchain-community 패키지가 최신 버전이 아닌 경우, 다음과 같이 연동 가능한 LangChain 최신 버전을 명시하여 설치하는 것이 필요할 수 있습니다.

pip install langchain-community~=0.3.8

연동 범위 확인

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

• CLOVA Studio 플레이그라운드 메뉴의 챗 모드 기본 모델 및 튜닝 모델
  • 모델: 기본 모델(<예시> HCX-003), 기본 모델을 튜닝한 모델
    • 연관 API: Chat Completions
  • 연동 예제: HyperCLOVA X 모델 이용
• CLOVA Studio 익스플로러 메뉴의 임베딩 v2 도구
  • 모델: bge-m3
    • 연관 API: 임베딩v2
  • 연동 예제: 임베딩 v2 도구 이용

연동 설정

LangChain을 통해 CLOVA Studio의 기능을 안전하게 사용할 수 있도록 API Key를 환경 변수로 등록하여 API 호출 시 필요한 인증 정보로 사용합니다. API Key는 CLOVA Studio의 플레이그라운드, 익스플로러 메뉴에서 테스트 앱 또는 서비스 앱을 생성하여 확인할 수 있습니다. 서비스 앱은 실제 서비스에 적용하는 경우에 신청하여 생성합니다.

API Key를 환경 변수로 등록하는 방법은 다음과 같습니다.

• 터미널을 통해 등록

  export NCP_CLOVASTUDIO_API_KEY="<NCP-CLOVASTUDIO-API-KEY>"
  

• Python을 통해 등록

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

연동 예제

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

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

HyperCLOVA X 모델 이용

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

from langchain_community.chat_models import ChatClovaX
  
chat = ChatClovaX(
    model="HCX-003", # 테스트 앱 또는 서비스 앱 인증 정보에 해당하는 모델명 입력 (기본값: HCX-003) 
    base_url="https://clovastudio.stream.gov-ntruss.com" # 공공 기관용 CLOVA Studio 공통 요청 API URL 입력
)

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

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

• 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)
  

임베딩 v2 도구 이용

LangChain을 통해 CLOVA Studio의 임베딩 v2 도구를 이용하려면 우선 해당 테스트 앱(서비스 앱)의 App ID를 환경 변수로 등록해야 합니다. 등록하는 방법은 다음과 같습니다.

• 터미널을 통해 등록

  export NCP_CLOVASTUDIO_APP_ID="<테스트/서비스 App ID>"
  

• Python을 통해 등록

  import os
  
  os.environ["NCP_CLOVASTUDIO_APP_ID"] = input("테스트/서비스 App ID 입력: ")
  

환경 변수 등록 후 LangChain을 통해 CLOVA Studio의 임베딩 v2 도구를 이용하는 예제 코드는 다음과 같습니다.

from langchain_community.embeddings import ClovaXEmbeddings
 
embeddings = ClovaXEmbeddings(
    model="bge-m3",  # 임베딩 v2 도구의 모델명 입력
    base_url="https://clovastudio.stream.gov-ntruss.com", # 공공 기관용 CLOVA Studio 공통 요청 API URL 입력 
    # app_id="..."  # App ID를 환경 변수로 설정하지 않고 이용하려면 직접 입력
)

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

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

• 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)