--- title: "LangChain 連携" slug: "clovastudio-dev-langchain" updated: 2026-09-17T09:25:57Z published: 2026-09-17T09:25:57Z 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.に帰属します。NAVERクラウドは本ガイドで参照目的でのみ使用し、LangChain Inc.と NAVERクラウド間のスポンサー、保証、提携を意味するものではありません。 - LangChainはオープンソースソフトウェアであり、NAVERクラウドは 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連携に活用されていた`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/ja/clovastudio-chatcompletions)、[Chat Completions v3](https://api.ncloud-docs.com/docs/ja/clovastudio-chatcompletionsv3)、[オープン AIの互換性](https://api.ncloud-docs.com/docs/ja/clovastudio-openaicompatibility) - 連携ユースケース: [HyperCLOVA Xモデルの利用](/docs/ja/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/ja/clovastudio-embedding)、[エンベディング v2](https://api.ncloud-docs.com/docs/ja/clovastudio-embeddingv2)、[オープン AIの互換性](https://api.ncloud-docs.com/docs/ja/clovastudio-openaicompatibility) - 連携ユースケース: [エンベディングツールの利用](/docs/ja/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/ja/clovastudio-dev-langchain#HyperCLOVAX%EB%AA%A8%EB%8D%B8%EC%9D%B4%EC%9A%A9) - [LangChainを通じて CLOVA Studioのエンベディングツールを利用するユースケース](/docs/ja/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/ja/clovastudio-chatcompletionsv3) を参照 | | `max_tokens` | Integer | Optional | 最大作成トークン数 - Chat Completionsまたは Chat Completions v3の [`maxTokens`](https://api.ncloud-docs.com/docs/ja/clovastudio-chatcompletionsv3){target="_blank"}を参照 - `max_completion_tokens`と同時に使用不可 | | `max_completion_tokens` | Integer | Optional | 最大作成トークン数 - Chat Completions v3の [`maxCompletionTokens`](https://api.ncloud-docs.com/docs/ja/clovastudio-chatcompletionsv3){target="_blank"}を参照 - `max_tokens`と同時に使用不可 | | `thinking` | Dict | Optional | 推論モデルの設定情報 - Chat Completions v3の [`thinking`](https://api.ncloud-docs.com/docs/ja/clovastudio-chatcompletionsv3-thinking) を参照 | | `repeat_penalty` | Float | Optional | 同じトークンを作成することに対するペナルティの度合い - Chat Completionsの [`repeatPenalty`](https://api.ncloud-docs.com/docs/ja/clovastudio-chatcompletions) を参照 | | `repetition_penalty` | Float | Optional | 同じトークンを作成することに対するペナルティの度合い - Chat Completions v3の [`repetitionPenalty`](https://api.ncloud-docs.com/docs/ja/clovastudio-chatcompletionsv3) を参照 | | `stop` | List [String] | Optional | トークン作成停止文字 - Chat Completions: [`stopBefore`](https://api.ncloud-docs.com/docs/ja/clovastudio-chatcompletions) を参照 - Chat Completions v3: [`stop`](https://api.ncloud-docs.com/docs/ja/clovastudio-chatcompletionsv3)を参照 | | `seed` | Integer | Optional | モデルの繰り返し実行時に結果値の一貫性レベルを調整 - Chat Completionsまたは Chat Completions v3の [`seed`](https://api.ncloud-docs.com/docs/ja/clovastudio-chatcompletionsv3) を参照 | | `top_k` | Integer | Optional | 作成トークン候補群から確率の高い K個を候補に指定してサンプリング - Chat Completionsまたは Chat Completions v3の [`topK`](https://api.ncloud-docs.com/docs/ja/clovastudio-chatcompletionsv3) を参照 | | `top_p` | Float | Optional | 作成トークン候補群を累積確率に基づいてサンプリング - Chat Completionsまたは Chat Completions v3の [`topP`](https://api.ncloud-docs.com/docs/ja/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/)をご参照ください。