LangChain 연동

Prev Next

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은 Python 또는 JavaScript 및 TypeScript 언어로 구현되어 있습니다. CLOVA Studio에서는 Python 기반의 LangChain을 지원하며, 이 가이드 역시 Python을 기준으로 설명합니다.
  • LangChain은 LangChain Inc.의 상표입니다. 상표의 권리는 LangChain Inc.에 있습니다. 네이버클라우드는 이 가이드에서 참조 목적으로만 사용하며, 이는 LangChain과 네이버클라우드 간 후원, 보증, 제휴를 의미하지 않습니다.
  • LangChain은 오픈 소스 소프트웨어로서 네이버클라우드는 LangChain의 품질, 성능을 보증하거나 책임지지 않습니다. LangChain에 대한 자세한 설명은 공식 문서를 참조해 주십시오.

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

pip install -U langchain # install LangChain
pip install -U langchain-naver # install LangChain-NAVER integration package
Shell
참고
  • 기존 LangChain 연동에 활용되던 langchain-community(≥ v.0.3.4) 패키지는 계속하여 이용 가능하나, 2025년 4월 17일 기준으로 기술지원이 중단되어 아래 모델 및 API 외에는 연동이 불가합니다.
  • langchain-community 지원 모델 및 API: HCX-003 및 HCX-DASH-001 (튜닝 모델 포함), 임베딩(v2 포함)

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

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

주의

테스트 앱을 이용할 경우 테스트 API Key를, 서비스 앱을 이용할 경우 서비스 API Key를 환경 변수로 등록해야 합니다.

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

  • 터미널을 통해 등록
    export CLOVASTUDIO_API_KEY="<CLOVA-STUDIO-API-KEY>"
    
    Shell
  • Python을 통해 등록
    import getpass
    import os
    
    os.environ["CLOVASTUDIO_API_KEY"] = getpass.getpass(
            "CLOVA Studio API Key 입력: "
        )
    
    Python
참고
  • langchain-community(≤ v.0.3.14) 이용 시, API Key와 API Gateway Key 2개의 인증 정보를 필요로 하며, 임베딩(v2 포함) 도구 이용 시 추가로 해당 테스트 앱(서비스 앱)의 App ID를 환경 변수로 등록해야 합니다.
    • 관련 정보는 CLOVA Studio의 오른쪽 상단에 있는 사용자명을 클릭한 후 앱 신청 현황 메뉴를 클릭하여 나타나는 화면에서 테스트 앱(서비스 앱)의 [자세히] 버튼을 클릭하여 조회할 수 있습니다.
    • 터미널을 통해 등록
      export NCP_CLOVASTUDIO_API_KEY="<NCP-CLOVASTUDIO-API-KEY>"
      export NCP_APIGW_API_KEY="<NCP-APIGW-API-KEY>"
      export NCP_CLOVASTUDIO_APP_ID="<임베딩 테스트/서비스 App ID>"
      
      Shell
    • Python을 통해 등록
      import getpass
      import os
      
      os.environ["NCP_CLOVASTUDIO_API_KEY"] = getpass.getpass(
          "NCP CLOVA STUDIO API key 입력: "
      )
      os.environ["NCP_APIGW_API_KEY"] = getpass.getpass(
          "NCP API Gateway API key 입력: "
      )
      os.environ["NCP_CLOVASTUDIO_APP_ID"] = input("임베딩 테스트/서비스 App ID 입력: ")
      
      Python

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

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

from langchain_naver import ChatClovaX
  
chat = ChatClovaX(
    base_url="https://clovastudio.stream.gov-ntruss.com/v1/openai", # 공공기관용 CLOVA Studio 공통 요청 API URL 입력
    model="HCX-005" # 모델명 입력 (기본값: HCX-005) 
)
Python
참고

공공기관용 네이버 클라우드 플랫폼을 통해 이용하는 경우, 반드시 CLOVA Studio 공통 요청 API URL을 아래와 같이 설정해 주어야 합니다. 따라서 인스턴스를 정의할 때마다 예제 코드를 참고하여 다음과 같이 설정해 주십시오.

  • base_url: https://clovastudio.stream.gov-ntruss.com

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

필드 타입 필수 여부 설명
model String Optional 모델 이름
  • 플레이그라운드 메뉴의 챗 모드 기본 모델 | 튜닝 모델
  • 기본 모델: HCX-005 (기본값)
  • 튜닝 모델: ft:{튜닝 모델의 Task ID} (예: ft:abcd1234)
temperature Float Optional 생성 토큰에 대한 다양성 정도
  • Chat Completions 또는 Chat Completions v3의 temperature 참조
max_tokens Integer Optional 최대 생성 토큰 수
  • Chat Completions 또는 Chat Completions v3의 maxTokens 참조
repeat_penalty Float Optional 같은 토큰을 생성하는 것에 대한 패널티 정도
repetition_penalty Float Optional 같은 토큰을 생성하는 것에 대한 패널티 정도
stop List [String] Optional 토큰 생성 중단 문자
seed Integer Optional 모델 반복 실행 시 결괏값의 일관성 수준 조정
  • Chat Completions 또는 Chat Completions v3의 seed 참조
top_k Integer Optional 생성 토큰 후보군에서 확률이 높은 K개를 후보로 지정하여 샘플링
  • Chat Completions 또는 Chat Completions v3의 topK 참조
top_p Float Optional 생성 토큰 후보군을 누적 확률을 기반으로 샘플링
  • Chat Completions 또는 Chat Completions v3의 topP 참조
timeout Integer Optional 타임아웃(초)
  • 1~N (기본값: 90)
max_retries Integer Optional 재시도 처리 횟수
  • 2~N (기본값: 2)
  • 오류 발생 시 자동으로 재시도 처리
api_key String Optional API Key
  • 사전 미설정 또는 값 변경 등 별도 입력 시 이용
base_url String Optional CLOVA Studio 공통 요청 API URL
  • 기본값: https://clovastudio.stream.ntruss.com/v1/openai

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

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

from pydantic import BaseModel, Field

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

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

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

LangChain을 통해 CLOVA Studio의 HyperCLOVA X 모델을 이용하는 방법에 대한 자세한 설명은 공식 문서를 참조해 주십시오.

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

from langchain_naver import ClovaXEmbeddings
 
embeddings = ClovaXEmbeddings(
    model="bge-m3",  # 이용할 테스트 앱 또는 서비스 앱에 해당하는 모델
    base_url="https://clovastudio.stream.gov-ntruss.com/v1/openai",  # 공공기관용 CLOVA Studio 공통 요청 API URL 입력
    # app_id="..."  # App ID를 환경 변수로 설정하지 않고 이용하려면 직접 입력
)
Python
참고

langchain-naver 상의 CLOVA Studio 공통 요청 API URL과 임베딩 v2 도구 모델명은 반드시 공공기관용 URL과 모델명으로 설정해 주어야 합니다. 따라서 인스턴스를 정의할 때마다 위 예제 코드를 참고하여 다음과 같이 설정해 주십시오.

  • model: bge-m3
  • base_url: https://clovastudio.stream.gov-ntruss.com/v1/openai

langchain-community 버전이 0.3.14 이하인 경우, LangChain을 통해 CLOVA Studio의 임베딩(임베딩 v2) 도구를 이용하려면 해당 테스트 앱(서비스 앱)의 App ID를 환경 변수로 등록해야 합니다. App ID 확인 방법은 연동 설정에서의 API Gateway Key 확인 방법과 동일하며, 등록하는 방법은 다음과 같습니다.

  • 터미널을 통해 등록

    export NCP_CLOVASTUDIO_APP_ID="<테스트/서비스 App ID>"
    
    Plain text
  • Python을 통해 등록

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

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

필드 타입 필수 여부 설명
model String Optional 모델 이름
  • 익스플로러 메뉴의 임베딩(임베딩 v2) 모델
    • clir-emb-dolphin (기본값) | clir-sts-dolphin | bge-m3
api_key String Optional API Key
  • 사전 미설정 또는 값 변경 등 별도 입력 시 이용
timeout Integer Optional 타임아웃(초)
  • 1~N (기본값: 90)
base_url String Optional CLOVA Studio 공통 요청 API URL
  • 기본값: https://clovastudio.stream.ntruss.com/v1/openai

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

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

LangChain을 통해 CLOVA Studio의 임베딩 v2 도구를 이용하는 방법에 대한 자세한 설명은 공식 문서를 참조해 주십시오.