LangChain＋ローカルLLM on JupyterLab で体験する RAG

1 はじめに
2 構成概要
- 2.1 ハンズオン環境の構成
- 2.2 RAG の仕組み
  - 2.2.1 仕組みを表したイラスト
  - 2.2.2 仕組みの流れを説明
3 事前準備
4 環境構築
5 ハンズオン実施
- 5.1 JupyterLab で教材の実施
- 5.2 ステップごとの教材内容
6 Appendix
7 まとめ

はじめに

こんにちは、サイオステクノロジーの小沼俊治です。

今回は、AIを活用した RAG アプリケーションの仕組みを無料で体験できるハンズオン環境を用意しました。

このハンズオンでは、LangChain、LLM に PC 内のローカルで動かす Open source LLM、ベクトルデータベースの Milvus といったオープンソースのプロダクトを使用します。
学習は、JupyterLab（Jupyter Notebook）の Notebook 形式でステップごとに用意した教材を使って進めます。

教材はステップ1から5までで構成しており、ステップ1から4では、外部に存在するデータの収集からデータを活用した回答生成まで、RAG を構成するモジュールを作成しながら一連の流れを学習します。集大成となるステップ5では、これまでに作成したモジュールを組み合わせて Web アプリケーションを構築し、アプリケーションの利用を通じて RAG を体験します。

LLM はローカルで動かすので、少々（PC の）スペックは必要ですが、トークン数などのコストを気にする必要はありませんので、思い存分、体験と学習に挑んで頂けると思っています。

構成概要

ハンズオン環境の構成

筆者が動かした際の主な構成要素は以下の通りです。

Windows 11 Professional
WSL 2.5.9.0
Ubuntu 24.04.3 LTS
Docker Engine 28.5.1

ハンズオンを構成する環境は以下の通りです。

教材を活用しながら学習を進める環境として、JupyterLab で LangChain を使う Python 環境を Ubuntu に構築します。
RAG の処理で必要となる Embedding や Open source LLM などのモデルは、Huggin Face からダウンロードして取得します。
拡張検索に必要となるデータを蓄積するベクトルデータベースには、Milvus を「milvus-standalone」、「milvus-etcd」、「milvus-minio」コンテナで構築します。
Milvus をビジュアル的に管理できる Web UI 管理ツールの Attu も「milvus-attu」コンテナで構築します。

環境構築や各種設定に使用するそれぞれのファイルは、以下の GitHub リポジトリで公開しています。

https://github.com/Toshiharu-Konuma-sti/hands-on-rag-with-langchain

$ tree ~/handson/hands-on-rag-with-langchain/

hands-on-keycloak/
|-- container/ …… 「環境構築」章でコンテナ作成で使う素材
|   |-- docker-compose-attu.yml
|   :
|
|-- setup/ …… 「環境構築」章でツール準備の環境準備に必要な素材
|   |-- SETUP_HANDS-ON.sh
|   :
|
`-- try-my-hand/ …… 「ハンズオン実施」章で教材を進める環境
    |-- cmd01-before_python_virtual_env.sh
    |-- cmd02-start_jupyterlab.sh
    |      
    |-- data/ …… ハンズオンでベクトル化する元データの素材
    |   `-- recurrent_navi_tyo.xlsx
    |
    |-- lesson/ …… ハンズオンで利用するステップごとの教材
    :   :

RAG の仕組み

教材でハンズオンを始める前に、教材を構成する各ステップの元となる RAG の仕組みを理解します。

仕組みを表したイラスト

仕組みの流れを説明

図中の1から2はベクトルデータベースに類似検索に利用するデータの蓄積フェーズを意味し、
図中の3から9はベクトルデータベースに蓄積されたデータを類似検索で活用する応用フェーズを意味します。

日々の経済活動を通じて、以下をはじめとするデータが企業のシステムに溜まります
- 販売する商品の在庫管理情報や売上データ
- 経済取引を記録する会計データ
- 企業に関わる人材を把握する社員情報や顧客情報
- 企画提案、商品説明、および企業説明等で作成されたドキュメントファイル
  など
企業に溜まったデータを検索に活用するために、以下をはじめとする加工を施しながらベクトル化して蓄積します
- 検索効率が向上するサイズにデータを細切れに分割するチャンキング
- ベクトルデータベースで類似検索が出来るように数値ベクトルに変換するエンベディング
- 必要に応じて検索効率を向上させるため欠損値の削除や補完、値形式を揃えるクレンジング
日々の業務活動を進めるに当たり不明点があれば質問を投げかけます
投げかけられた質問をエンベディングしてベクトルデータベースに対して類似検索します
投げかけられた質問に関連するデータを類似検索結果として戻します
LLMに回答を生成を依頼するために、依頼向けテンプレートに質問と類似検索結果を付与してプロンプトを作成します
質問に回答するためにプロンプトを用いてLLMに回答案の作成を依頼します
LLMが生成された回答案を戻します
LLMから戻された回答案を整形して質問者に回答を戻します

事前準備

Hugging Face のアカウント準備

Hugging Face より Embedding Model や Open source LLM を取得して利用します。取得には事前に、アカウント登録、Access Token 発行、および Model の利用申請を済ませておきます。

Hugging Face – The AI community building the future.

アカウント作成

Hugging Face アカウントを持っていない場合、アカウントを用意します。アカウントは無料で作成できます。

Hugging Face トップページの右上の「Sing up」から作成を開始します。

途中 CAPTCHA 認証を通り、登録するメールアドレスとパスワードを入力します。

登録完了まで画面遷移の指示に従いながら登録を進めます。

Access Token取得

Embedding Model や Open source LLM では取得に Access Token を必要とするモデルが存在します。それらを利用する際には、ハンズオン開始前に発行と値の確保を済ませておきます。

Hugging Face の右上にあるユーザアイコンをクリックすると表示するメニューから「Settings」を選択します。

左ペインの一覧から「Access Token」を選択し、新たに発行する場合には「+ Create new token」ボタンをクリックします。

モデルの利用であれば「Read」権限を選択してから「Token name」に任意の名前を入力し、「Create token」ボタンをクリックして Token を発行します。Token の値は後で確認することはできないので、発行時に必ずメモしておきます。

利用規約に同意が必要な Open source LLM の利用申請

Embedding Model や Open source LLM の中には利用規約に同意を必要とするモデルが存在します。それらを利用する際には、ハンズオンの開始前に利用申請を済ませておきます。

モデルの紹介ページで利用規約への同意が必要な場合はその旨が述べられており、「Expand to review and access」で規約の全文を展開表示をして利用規約を確認します。

規約を最後まで読み進めると、名前、所属と利用目的の入力を求められる場合はそれらを入力してから、「Agree and access repository」ボタンをクリックして同意します。

同意するとモデルの紹介ページに戻りますが、同意の受付状況を確認するために、画面右上のユーザアイコンをクリックすると表示するメニューから「Settings」を選択します。

左ペインの一覧から「Gated Repositories」を選択し、同意したモデルの一覧から「Request Status」の値を確認します。

Request Status が「ACCEPTED」になれば、該当のモデルは利用できます。

環境構築

WSL環境の構築

Windows PC の場合には、以下手順を参考に WSL と Linux ディストリビューション（Ubuntu）環境を用意します。

初期環境構築: WSL 環境 on Windows 10

Docker環境の構築

コンテナ環境を使うため、以下手順を参考に Ubuntu へ Docker Engine 環境を用意します。

初期環境構築: Docker Engine on Ubuntu

GitHub からハンズオン用のリポジトリ取得

ハンズオンを進めるための環境構築用の設定ファイル、スクリプトや教材を含んだリポジトリを GitHub からダウンロードして取得します。

本章ではコンソールを用いてハンズオンのフォルダ領域を作成して作業を実施します。

$ mkdir -p ~/handson/
$ cd ~/handson/

「$ git clone」コマンドで本ハンズオン用のリポジトリを取得します。

$ git clone https://github.com/Toshiharu-Konuma-sti/hands-on-rag-with-langchain.git
$ cd hands-on-rag-with-langchain/

コンテナ構築スクリプトの実行

本章ではコンソールを用いて以下のディレクトリで作業を実施します。

$ cd ~/handson/hands-on-rag-with-langchain/container/

コンテナ構築用に用意してあるスクリプトを実行して、ハンズオン環境の各種コンテナを構築します。

$ ./CREATE_CONTAINER.sh

コンテナが構築されてから info オプションを付けてスクリプトを実行すると、ハンズオンに必要なアプリケーションの URL などを表示することができます。

$ ./CREATE_CONTAINER.sh info

/************************************************************
 * Information:
 * - Used a material at the following URL as a reference to create Milvus containers.
 *   - https://milvus.io/docs/ja/install_standalone-docker-compose.md
 * - Access to Attu (Web admin tool for Milvus) with the URL below.
 *   - http://localhost:8000
 ***********************************************************/

Attu コンテナが稼働するのでブラウザでアクセスします。

http://localhost:8000/

なお、コンテナ構築スクリプトで実行する内容は以下を参照してください。

コンテナ構築スクリプトの解説

ツール整備スクリプトの実行

本章ではコンソールを用いて以下のディレクトリで作業を実施します。

$ cd ~/handson/hands-on-rag-with-langchain/setup/

ハンズオンで使うツールを整備するために用意してあるスクリプトを実行します。

$ ./SETUP_HANDS-ON.sh

なお、ツール整備スクリプトで実行する内容は以下を参照してください。

ツール整備スクリプトの解説

ハンズオン実施

ハンズオンは Python 言語環境で JupyterLab を使って進めます。まずは JupyterLab の実行環境を準備するため、コンソールを用いて以下のディレクトリで作業を実施します。

$ cd ~/handson/hands-on-rag-with-langchain/try-my-hand/

JupyterLab で教材の実施

Python 仮想環境のアクティベート

「.venv」名でPython 仮想環境を作成します。

$ python3 -m venv .venv

Python 仮想環境の領域にあたる「.venv/」ディレクトリができたことを確認します。

$ ls -laF

 :
drwxr-xr-x 7 hoge hoge 4096 Jan 14 12:15 .venv/
 :

source コマンドで Python 仮想環境に入ります（仮想環境をアクティブにします）。この後は、次章「JupyterLab の起動」に進みハンズオンを開始します。

$ source .venv/bin/activate
(.venv) $

仮想環境がアクティブになるとプロンプトの先頭に括弧で環境名が表示されます（例：(.venv)）

ハンズオンが終わった際は、ブラウザで JupyterLab を閉じて「deactivate」コマンドを実行して Python 仮想環境から抜けます。

(.venv) $ deactivate
$

なお、Python 仮想環境の作成は該当フォルダにある「cmd01-before_python_virtual_env.sh 」でも実行できるようにしてあります。

$ ./cmd01-before_python_virtual_env.sh

 :
* Next, enter the command below to go to the python virtual environment!!
 source .venv/bin/activate

$ source .venv/bin/activate
(.venv) $

JupyterLab の起動

Python 仮想環境がアクティブな状態で JupyterLab をインストールします。

(.venv) $ pip install jupyterlab

JupyterLab を起動するコマンドを実行します。

(.venv) $ jupyter lab

コマンドを実行するとコンソールに起動ログが流れ始めます。JupyterLab の起動準備が整うと流れていたログが止まり、起動するための URL が出力されます。

 :
[I 2025-01-14 12:34:04.899 ServerApp] Jupyter Server 2.15.0 is running at:
[I 2025-01-14 12:34:04.899 ServerApp] http://localhost:8888/lab?token=d7488a5d324a41c9685cc2e298c5f16d7def9ddf02e50a3b
[I 2025-01-14 12:34:04.899 ServerApp]     http://127.0.0.1:8888/lab?token=d7488a5d324a41c9685cc2e298c5f16d7def9ddf02e50a3b
[I 2025-01-14 12:34:04.899 ServerApp] Use Control-C to stop this server and shut down all kernels (twice to skip confirmation).
[C 2025-01-14 12:34:05.465 ServerApp]

    To access the server, open this file in a browser:
        file:///home/hoge/.local/share/jupyter/runtime/jpserver-60018-open.html
    Or copy and paste one of these URLs:
        http://localhost:8888/lab?token=d7488a5d324a41c9685cc2e298c5f16d7def9ddf02e50a3b
        http://127.0.0.1:8888/lab?token=d7488a5d324a41c9685cc2e298c5f16d7def9ddf02e50a3b

上記ログ例では
「http://localhost:8888/lab?token=d7488a5d324a41c9685cc2e298c5f16d7def9ddf02e50a3b」
が起動する URL に該当します。ただし、コマンド実行ごとに token が異なるので、必ずコンソールに出力される URL を起動に利用します。

起動ログに出力された URL にアクセスしてブラウザで JupyterLab を起動します。

なお、JupyterLab のインストールから起動は該当フォルダにある「cmd02-start_jupyterlab.sh 」でも実行できるようにしてあります。

(.venv) $ ./cmd02-start_jupyterlab.sh

 :
[I 2025-01-12 00:59:20.643 ServerApp] Use Control-C to stop this server and shut down all kernels (twice to skip confirmation).
    To access the server, open this file in a browser:
        file:///home/hoge/.local/share/jupyter/runtime/jpserver-72570-open.html
    Or copy and paste one of these URLs:
        http://localhost:8888/lab?token=612c96228db1af7175d0c00764360c8a0bbe8ee8322c2291
        http://127.0.0.1:8888/lab?token=612c96228db1af7175d0c00764360c8a0bbe8ee8322c2291
 :

JupyterLab で教材利用

これから示す JupyterLab の使い方を参考に、ステップ1から順番に用意している教材を進めます。

左ペインにあるフォルダアイコンの「File Browser」をクリックしてファイル一覧を表示し、ルート階層から「lesson/」フォルダ配下にアクセスします。

「lesson/」フォルダ配下に rag-step01 ～ rag-step05 のファイル名で始まるステップごとの教材ファイルがあるので、ハンズオンを進めるステップのファイルをダブルクリックして教材をアクティブにします。（最初の教材である「ステップ1」をアクティブにした例）

教材を表示したら左ペインにある目次アイコンの「Table of Contents」をクリックして、ステップの章構成を表示しながら教材を上から順に読み進めます。

教材を読み進めていく過程でソースコードのセルに到達したら、教材上部にある再生アイコンの「Run this cell and advance」（もしくは、セル内で[Ctrl] + [Enter]）をクリックして、セル内のソースコードを実行してハンズオンを進めます。

各教材を上から順番に進めていき最終章まで到達したら、そのステップの体験学習は終了です。次のステップに進みながら、ステップ1から5までの各教材を進めることで、RAG の仕組みを実際に体験していきます。

ステップ5の最後のセルは、Web UI の画面を実装するソースコードです。このセルを実行すると、直下のログ表示部分に RAG の Web アプリケーションを起動する URL が表示されるので、クリックしてアプリケーションを起動します。

Web アプリケーションが起動したら、ステップ1から学習してきた内容の集大成として、RAG の動作を体験してみましょう。