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のインストールと確認

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を通じて利用可能な CLOVA Studioの機能は、次の通りです。

• CLOVA Studioプレイグラウンドメニューのチャットモードモデル
  • モデル: 基本モデル(例) HCX-005)、基本モデルをチューニングしたモデル
    • 関連 API: Chat Completions、Chat Completions v3、オープン AIの互換性
  • 連携ユースケース: HyperCLOVA Xモデルの利用
• CLOVA Studioエクスプローラメニューのエンベディング(またはエンベディング v2)ツール
  • モデル: clir-emb-dolphin、clir-sts-dolphin、bge-m3
    • 関連 API: エンベディング、エンベディング v2、オープン AIの互換性
  • 連携ユースケース: エンベディングツールの利用

連携設定

LangChainを通じて CLOVA Studioの機能を安全に使用できるように、API Keyを環境変数として登録し、API呼び出し時に必要な認証情報として使用します。API Keyは CLOVA Studioの [APIキー] メニューから発行して確認できます。サービスアプリは、実際のサービスに適用する場合に申し込んで作成します。

認証情報を環境変数として登録する方法は、次の通りです。

• ターミナルから登録

  export CLOVASTUDIO_API_KEY="<CLOVA-STUDIO-API-KEY>"
  

• Pythonから登録

  import getpass
  import os
  
  os.environ["CLOVASTUDIO_API_KEY"] = getpass.getpass(
          "CLOVA Studio API Keyを入力: "
      )
  

連携ユースケース

LangChainと CLOVA Studioを連携するサンプルコードを紹介します。

• LangChainを通じて CLOVA Studioの HyperCLOVA Xモデルを利用するユースケース
• LangChainを通じて CLOVA Studioのエンベディングツールを利用するユースケース

HyperCLOVA Xモデルの利用

LangChainを通じて CLOVA Studioの HyperCLOVA Xモデルを利用するサンプルコードは、次の通りです。

from langchain_naver import ChatClovaX
  
chat = ChatClovaX(
    model="HCX-005" # モデル名を入力(デフォルト値: HCX-005) 
)

ChatClovaX クラスのインスタンス定義時に使用できるパラメータの説明は次の通りです。

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のエンベディング(エンベディング v2)ツールを利用するサンプルコードは、次の通りです。

from langchain_naver import ClovaXEmbeddings
 
embeddings = ClovaXEmbeddings(
    model="clir-emb-dolphin",  # モデル名(デフォルト値: clir-emb-dolphin)
)

ClovaXEmbeddings クラスのインスタンス定義時に使用できるパラメータは、次の通りです。

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)