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 패키지 버전이 0.3.3 이하인 경우에는 다음과 같이 연동 가능한 LangChain 버전을 명시하여 설치하는 것이 필요할 수 있습니다.

pip install langchain-community~=0.3.4

연동 범위 확인

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를 환경 변수로 등록하는 방법은 다음과 같습니다. 추가로 공공기관용 CLOVA Studio의 경우 별도의 API Gateway Key가 없으나 LangChain 연동을 위해서는 임의의 문자열로 정의해주어야 합니다.

• 터미널을 통해 등록

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

• Python을 통해 등록

  import getpass
  import os
  
  
  os.environ["NCP_CLOVASTUDIO_API_KEY"] = getpass.getpass(
          "NCP CLOVA Studio API Key 입력: "
      )
  os.environ["NCP_APIGW_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)