--- title: "LangChain 연동" slug: "clovastudio-dev-langchain" updated: 2026-05-21T09:01:22Z published: 2026-05-21T09:03:03Z canonical: "guide-gov.ncloud-docs.com/clovastudio-dev-langchain" --- > ## Documentation Index > Fetch the complete documentation index at: https://guide-gov.ncloud-docs.com/llms.txt > Use this file to discover all available pages before exploring further. # 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 도구를 이용하는 예제 코드를 제공하여 실제 개발에 참고할 수 있도록 안내합니다. :::(Info) (참고) * LangChain은 Python 또는 JavaScript 및 TypeScript 언어로 구현되어 있습니다. CLOVA Studio에서는 Python 기반의 LangChain을 지원하며, 이 가이드 역시 Python을 기준으로 설명합니다. * LangChain은 LangChain Inc.의 상표입니다. 상표의 권리는 LangChain Inc.에 있습니다. 네이버클라우드는 이 가이드에서 참조 목적으로만 사용하며, 이는 LangChain과 네이버클라우드 간 후원, 보증, 제휴를 의미하지 않습니다. * LangChain은 오픈 소스 소프트웨어로서 네이버클라우드는 LangChain의 품질, 성능을 보증하거나 책임지지 않습니다. LangChain에 대한 자세한 설명은 [공식 문서](https://python.langchain.com/docs/introduction/){target="_blank"}를 참조해 주십시오. ::: ## LangChain 설치 및 확인 CLOVA Studio에 연동하여 LangChain을 사용하려면 버전 3.9 이상의 Python 설치가 필요합니다. Python 설치를 완료한 후에는 다음 명령어를 사용하여 LangChain을 설치한 후 연동에 필요한 `langchain-naver` 패키지를 설치해 주십시오. ```shell pip install -U langchain # install LangChain pip install -U langchain-naver # install LangChain-NAVER integration package ``` :::(Info) (참고) * 기존 LangChain 연동에 활용되던 `langchain-community`(≥ v.0.3.4) 패키지는 계속하여 이용 가능하나, 2025년 4월 17일 기준으로 기술지원이 중단되어 아래 모델 및 API 외에는 연동이 불가합니다. * `langchain-community` 지원 모델 및 API: HCX-003 및 HCX-DASH-001 (튜닝 모델 포함), 임베딩(v2 포함) ::: ## 연동 범위 확인 LangChain을 통해 이용 가능한 CLOVA Studio의 기능은 다음과 같습니다. * CLOVA Studio **플레이그라운드** 메뉴의 **챗 모드** 기본 모델 및 튜닝 모델 * 모델: 기본 모델(<예시> HCX-005), 기본 모델을 튜닝한 모델 * 연관 API: [Chat Completions](https://api-gov.ncloud-docs.com/docs/clovastudio-chatcompletions){target="_blank"}, [Chat Completions v3](https://api-gov.ncloud-docs.com/docs/clovastudio-chatcompletionsv3){target="_blank"}, [오픈AI 호환성](https://api-gov.ncloud-docs.com/docs/clovastudio-openaicompatibility){target="_blank"} * 연동 예제: [HyperCLOVA X 모델 이용](#HyperCLOVAX모델이용) * CLOVA Studio **익스플로러** 메뉴의 임베딩 v2 도구 * 모델: bge-m3 * 연관 API: [임베딩v2](https://api-gov.ncloud-docs.com/docs/clovastudio-embeddingv2){target="_blank"} * 연동 예제: [임베딩 v2 도구 이용](#임베딩v2도구이용) ## 연동 설정 LangChain을 통해 CLOVA Studio의 기능을 안전하게 사용할 수 있도록 API Key를 환경 변수로 등록하여 API 호출 시 필요한 인증 정보로 사용합니다. API Key는 CLOVA Studio의 **API 키** 메뉴에서 발급받아 확인할 수 있습니다. 서비스 앱은 실제 서비스에 적용하는 경우에 신청하여 생성합니다. :::(warning) (주의) 테스트 앱을 이용할 경우 테스트 API Key를, 서비스 앱을 이용할 경우 서비스 API Key를 환경 변수로 등록해야 합니다. ::: 인증 정보를 환경 변수로 등록하는 방법은 다음과 같습니다. * 터미널을 통해 등록 ```shell export CLOVASTUDIO_API_KEY="" ``` * Python을 통해 등록 ```python import getpass import os os.environ["CLOVASTUDIO_API_KEY"] = getpass.getpass( "CLOVA Studio API Key 입력: " ) ``` :::(Info) (참고) * `langchain-community`(≤ v.0.3.14) 이용 시, API Key와 API Gateway Key 2개의 인증 정보를 필요로 하며, 임베딩(v2 포함) 도구 이용 시 추가로 해당 테스트 앱(서비스 앱)의 App ID를 환경 변수로 등록해야 합니다. * 관련 정보는 CLOVA Studio의 오른쪽 상단에 있는 사용자명을 클릭한 후 앱 신청 현황 메뉴를 클릭하여 나타나는 화면에서 테스트 앱(서비스 앱)의 **[자세히]** 버튼을 클릭하여 조회할 수 있습니다. * 터미널을 통해 등록 ```shell export NCP_CLOVASTUDIO_API_KEY="" export NCP_APIGW_API_KEY="" export NCP_CLOVASTUDIO_APP_ID="<임베딩 테스트/서비스 App ID>" ``` * Python을 통해 등록 ```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 입력: ") ``` ::: ## 연동 예제 LangChain과 CLOVA Studio 연동 예제 코드를 소개합니다. * [LangChain을 통해 CLOVA Studio의 HyperCLOVA X 모델을 이용하는 예제](#HyperCLOVAX모델이용) * [LangChain을 통해 CLOVA Studio의 임베딩 v2 도구를 이용하는 예제](#임베딩v2도구이용) ### HyperCLOVA X 모델 이용 LangChain을 통해 CLOVA Studio의 HyperCLOVA X 모델을 이용하는 예제 코드는 다음과 같습니다. ```python 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) ) ``` :::(Info) (참고) 공공기관용 네이버 클라우드 플랫폼을 통해 이용하는 경우, 반드시 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`](https://api.ncloud-docs.com/docs/clovastudio-chatcompletionsv3){target="_blank"} 참조
| | `max_tokens` | Integer | Optional | 최대 생성 토큰 수
  • Chat Completions 또는 Chat Completions v3의 [`maxTokens`](https://api.ncloud-docs.com/docs/clovastudio-chatcompletionsv3){target="_blank"} 참조
| | `repeat_penalty` | Float | Optional | 같은 토큰을 생성하는 것에 대한 패널티 정도
  • Chat Completions의 [`repeatPenalty`](https://api.ncloud-docs.com/docs/clovastudio-chatcompletions){target="_blank"} 참조
| | `repetition_penalty` | Float | Optional | 같은 토큰을 생성하는 것에 대한 패널티 정도
  • Chat Completions v3의 [`repetitionPenalty`](https://api.ncloud-docs.com/docs/clovastudio-chatcompletionsv3){target="_blank"} 참조
| | `stop` | List [String] | Optional | 토큰 생성 중단 문자
  • Chat Completions: [ `stopBefore` ](https://api.ncloud-docs.com/docs/clovastudio-chatcompletions){target="_blank"} 참조
  • Chat Completions v3: [`stop`](https://api.ncloud-docs.com/docs/clovastudio-chatcompletionsv3){target="_blank"} 참조
| | `seed` | Integer | Optional | 모델 반복 실행 시 결괏값의 일관성 수준 조정
  • Chat Completions 또는 Chat Completions v3의 [`seed`](https://api.ncloud-docs.com/docs/clovastudio-chatcompletionsv3){target="_blank"} 참조
| | `top_k` | Integer | Optional | 생성 토큰 후보군에서 확률이 높은 K개를 후보로 지정하여 샘플링
  • Chat Completions 또는 Chat Completions v3의 [`topK`](https://api.ncloud-docs.com/docs/clovastudio-chatcompletionsv3){target="_blank"} 참조
| | `top_p` | Float | Optional | 생성 토큰 후보군을 누적 확률을 기반으로 샘플링
  • Chat Completions 또는 Chat Completions v3의 [`topP`](https://api.ncloud-docs.com/docs/clovastudio-chatcompletionsv3){target="_blank"} 참조
| | `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` ```python messages = [ ( "system", "CLOVA Studio는 HyperCLOVA X 언어 모델을 활용하여 AI 서비스를 손쉽게 만들 수 있는 개발 도구입니다.", ), ("human", "CLOVA Studio가 무엇인가요?"), ] ai_msg = chat.invoke(messages) ai_msg ``` * `stream` ```python messages = [ ( "system", "CLOVA Studio는 HyperCLOVA X 언어 모델을 활용하여 AI 서비스를 손쉽게 만들 수 있는 개발 도구입니다.", ), ("human", "CLOVA Studio가 무엇인가요?"), ] for chunk in chat.stream(messages): print(chunk.content, end="", flush=True) ``` 또한, `bind_tools` 메서드를 통해 LangChain의 Tool calling 기능을 구현할 수 있습니다. 예제 코드는 다음과 같습니다. ```python 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 ``` :::(Info) (참고) LangChain을 통해 CLOVA Studio의 HyperCLOVA X 모델을 이용하는 방법에 대한 자세한 설명은 [공식 문서](https://python.langchain.com/docs/integrations/chat/naver/){target="_blank"}를 참조해 주십시오. ::: ### 임베딩 v2 도구 이용 LangChain을 통해 CLOVA Studio의 임베딩 v2 도구를 이용하는 예제 코드는 다음과 같습니다. ```python 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를 환경 변수로 설정하지 않고 이용하려면 직접 입력 ) ``` :::(Info) (참고) `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>" ``` * Python을 통해 등록 ```python import os os.environ["NCP_CLOVASTUDIO_APP_ID"] = input("테스트/서비스 App ID 입력: ") ``` ::: `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` ```python query = "CLOVA Studio는 HyperCLOVA X 언어 모델을 활용하여 AI 서비스를 손쉽게 만들 수 있는 개발 도구입니다." single_vector = embeddings.embed_query(query) ``` * `embed_documents` ```python text1 = "CLOVA Studio는 HyperCLOVA X 언어 모델을 활용하여 AI 서비스를 손쉽게 만들 수 있는 개발 도구입니다." text2 = "LangChain은 언어 모델 기반 애플리케이션 개발을 지원하는 오픈소스 프레임워크입니다." document = [text1, text2] multiple_vector = embeddings.embed_documents(document) ``` :::(Info) (참고) LangChain을 통해 CLOVA Studio의 임베딩 v2 도구를 이용하는 방법에 대한 자세한 설명은 [공식 문서](https://python.langchain.com/docs/integrations/text_embedding/naver/){target="_blank"}를 참조해 주십시오. :::