--- title: "LangChain 연동" slug: "clovastudio-dev-langchain" updated: 2026-09-17T09:07:14Z published: 2026-09-17T09:07:14Z canonical: "guide.ncloud-docs.com/clovastudio-dev-langchain" stale: true --- > ## Documentation Index > Fetch the complete documentation index at: https://guide.ncloud-docs.com/llms.txt > Use this file to discover all available pages before exploring further. # 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은 Python 또는 JavaScript 및 TypeScript 언어로 구현되어 있습니다. CLOVA Studio에서는 Python 기반의 LangChain을 지원하며, 이 가이드 역시 Python을 기준으로 설명합니다. - LangChain은 LangChain Inc.의 상표입니다. 상표의 권리는 LangChain Inc.에 있습니다. 네이버클라우드는 이 가이드에서 참조 목적으로만 사용하며, 이는 LangChain Inc.와 네이버클라우드 간 후원, 보증, 제휴를 의미하지 않습니다. - LangChain은 오픈 소스 소프트웨어로서 네이버클라우드는 LangChain는의 품질, 성능을 보증하거나 책임지지 않습니다. LangChain에 대한 자세한 설명은 [LangChain 공식 문서](https://python.langchain.com/docs/introduction/)를 참조해 주십시오. ## 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 연동에 활용되던 `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.ncloud-docs.com/docs/clovastudio-chatcompletions), [Chat Completions v3](https://api.ncloud-docs.com/docs/clovastudio-chatcompletionsv3), [오픈AI 호환성](https://api.ncloud-docs.com/docs/clovastudio-openaicompatibility) - 연동 예제: [HyperCLOVA X 모델 이용](/docs/clovastudio-dev-langchain#HyperCLOVAX%EB%AA%A8%EB%8D%B8%EC%9D%B4%EC%9A%A9) - CLOVA Studio **익스플로러** 메뉴의 임베딩(또는 임베딩 v2) 도구 - 모델: clir-emb-dolphin, clir-sts-dolphin, bge-m3 - 연관 API: [임베딩](https://api.ncloud-docs.com/docs/clovastudio-embedding), [임베딩v2](https://api.ncloud-docs.com/docs/clovastudio-embeddingv2), [오픈AI 호환성](https://api.ncloud-docs.com/docs/clovastudio-openaicompatibility) - 연동 예제: [임베딩 도구 이용](/docs/clovastudio-dev-langchain#%EC%9E%84%EB%B2%A0%EB%94%A9%EB%8F%84%EA%B5%AC%EC%9D%B4%EC%9A%A9) ## 연동 설정 LangChain을 통해 CLOVA Studio의 기능을 안전하게 사용할 수 있도록 API Key를 환경 변수로 등록하여 API 호출 시 필요한 인증 정보로 사용합니다. API Key는 CLOVA Studio의 **[API 키]** 메뉴에서 발급받아 확인할 수 있습니다. 서비스 앱은 실제 서비스에 적용하는 경우에 신청하여 생성합니다. 주의 서비스 앱을 이용할 경우 서비스 API Key를 환경 변수로 등록해야 합니다. 인증 정보를 환경 변수로 등록하는 방법은 다음과 같습니다. - 터미널을 통해 등록 ``` export CLOVASTUDIO_API_KEY="" ``` - Python을 통해 등록 ``` import getpass import os os.environ["CLOVASTUDIO_API_KEY"] = getpass.getpass( "CLOVA Studio API Key 입력: " ) ``` 참고 - `langchain-community`(≤ v.0.3.14) 이용 시, API Key와 API Gateway Key 2개의 인증 정보를 필요로 하며, 임베딩(v2 포함) 도구 이용 시 추가로 해당 서비스 앱의 App ID를 환경 변수로 등록해야 합니다. - 관련 정보는 CLOVA Studio 화면 좌측의 **[관리]**>**[서비스 앱 신청]** 버튼을 누르면 나타나는 서비스 앱 목록에서 해당 서비스 앱의 **[코드 보기]** 버튼을 클릭 후 [기존] 탭에서 조회할 수 있습니다. - 터미널을 통해 등록 ``` export NCP_CLOVASTUDIO_API_KEY="" export NCP_APIGW_API_KEY="" export NCP_CLOVASTUDIO_APP_ID="<임베딩 서비스 앱 ID>" ``` - 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("임베딩 서비스 ID 입력: ") ``` ## 연동 예제 LangChain과 CLOVA Studio 연동 예제 코드를 소개합니다. - [LangChain을 통해 CLOVA Studio의 HyperCLOVA X 모델을 이용하는 예제](/docs/clovastudio-dev-langchain#HyperCLOVAX%EB%AA%A8%EB%8D%B8%EC%9D%B4%EC%9A%A9) - [LangChain을 통해 CLOVA Studio의 임베딩 도구를 이용하는 예제](/docs/clovastudio-dev-langchain#%EC%9E%84%EB%B2%A0%EB%94%A9%EB%8F%84%EA%B5%AC%EC%9D%B4%EC%9A%A9) ### HyperCLOVA X 모델 이용 LangChain을 통해 CLOVA Studio의 HyperCLOVA X 모델을 이용하는 예제 코드는 다음과 같습니다. ``` from langchain_naver import ChatClovaX chat = ChatClovaX( model="HCX-005" # 모델명 입력 (기본값: HCX-005) ) ``` `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) 참조 | | `max_tokens` | Integer | Optional | 최대 생성 토큰 수 - Chat Completions 또는 Chat Completions v3의 [`maxTokens`](https://api.ncloud-docs.com/docs/clovastudio-chatcompletionsv3){target="_blank"} 참조 - `max_completion_tokens`와 동시 사용 불가 | | `max_completion_tokens` | Integer | Optional | 최대 생성 토큰 수 - Chat Completions v3의 [`maxCompletionTokens`](https://api.ncloud-docs.com/docs/clovastudio-chatcompletionsv3){target="_blank"} 참조 - `max_tokens`와 동시 사용 불가 | | `thinking` | Dict | Optional | 추론 모델 설정 정보 - Chat Completions v3의 [`thinking`](https://api.ncloud-docs.com/docs/clovastudio-chatcompletionsv3-thinking) 참조 | | `repeat_penalty` | Float | Optional | 같은 토큰을 생성하는 것에 대한 패널티 정도 - Chat Completions의 [`repeatPenalty`](https://api.ncloud-docs.com/docs/clovastudio-chatcompletions) 참조 | | `repetition_penalty` | Float | Optional | 같은 토큰을 생성하는 것에 대한 패널티 정도 - Chat Completions v3의 [`repetitionPenalty`](https://api.ncloud-docs.com/docs/clovastudio-chatcompletionsv3) 참조 | | `stop` | List [String] | Optional | 토큰 생성 중단 문자 - Chat Completions: [`stopBefore`](https://api.ncloud-docs.com/docs/clovastudio-chatcompletions) 참조 - Chat Completions v3: [`stop`](https://api.ncloud-docs.com/docs/clovastudio-chatcompletionsv3) 참조 | | `seed` | Integer | Optional | 모델 반복 실행 시 결괏값의 일관성 수준 조정 - Chat Completions 또는 Chat Completions v3의 [`seed`](https://api.ncloud-docs.com/docs/clovastudio-chatcompletionsv3) 참조 | | `top_k` | Integer | Optional | 생성 토큰 후보군에서 확률이 높은 K개를 후보로 지정하여 샘플링 - Chat Completions 또는 Chat Completions v3의 [`topK`](https://api.ncloud-docs.com/docs/clovastudio-chatcompletionsv3) 참조 | | `top_p` | Float | Optional | 생성 토큰 후보군을 누적 확률을 기반으로 샘플링 - Chat Completions 또는 Chat Completions v3의 [`topP`](https://api.ncloud-docs.com/docs/clovastudio-chatcompletionsv3) 참조 | | `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` 등을 통해 챗 모델을 실행할 수 있습니다. 예제 코드는 다음과 같습니다. - `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의 챗 모델을 이용하는 방법에 대한 자세한 설명은 [공식 문서](https://python.langchain.com/docs/integrations/chat/naver/)를 참조해 주십시오. ### 임베딩 도구 이용 LangChain을 통해 CLOVA Studio의 임베딩(임베딩 v2) 도구를 이용하는 예제 코드는 다음과 같습니다. ``` from langchain_naver import ClovaXEmbeddings embeddings = ClovaXEmbeddings( model="clir-emb-dolphin", # 모델명 (기본값: clir-emb-dolphin) ) ``` `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` 등을 통해 임베딩 도구를 실행할 수 있습니다. 예제 코드는 다음과 같습니다. - `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) ``` 참고 LangChain을 통해 CLOVA Studio의 임베딩(임베딩 v2) 도구를 이용하는 방법에 대한 자세한 설명은 [공식 문서](https://python.langchain.com/docs/integrations/text_embedding/naver/)를 참조해 주십시오.