ZundaGPT2 Lite を ラズパイ・Linux Mint / Ubuntu で動かそう！
🚀 はじめに
ZundaGPT2 Lite は OpenAI や Google Gemini、Anthropic Claude などが提供している API を使用してAIとチャットするチャットクライアントアプリです。姉妹アプリに ZundaGPT2 がありますが、ZundaGPT2 Lite は ZundaGPT2 から音声出力機能を省いた軽量バージョンとなっています。
2024年3月より ZundaGPT2 Lite はWindows用アプリとしてGitHubで公開してきましたが、v1.21.0 からRaspberry Pi OS Bookworm と Linux Mint/Ubuntu にも対応しました。そこで、この記事ではラズパイ版、Linux版の利用手順について記載したいと思います。
🍉 事前準備
🪴 APIキーの登録
~/.bashrc、~/.profile、~/.xsessionrcファイルなどに、APIキーの環境変数を登録しておきます。
# API Keys
export OPENAI_API_KEY="xxx"
export GEMINI_API_KEY="yyy"
export ANTHROPIC_API_KEY="zzz"
ファイルの使い分けは以下を参考にしてください。
| ファイル | 用途 |
|---|---|
| ~/.bashrc | ターミナルから起動する場合、SSH接続する場合 |
| ~/.profile | デスクトップ環境にローカルログインする場合 |
| ~/.xsessionrc | RDP接続する場合 |
🪴 pyenv + Python 3.12.0
実行ファイルではなくPythonで実行する場合は、pyenv を使うと便利です。
pyenv は必ずしも必要ではありませんが、本記事のコード例はpyenvを利用することを前提に記載されています。pyenv を利用する場合は、次のコマンドで Python 3.12.0 をインストールしておいてください。
# Python 3.12.0をインストール
pyenv install 3.12.0
pyenv を利用されない場合は、以降のコード例の python 部分を python3 など、ご自分の環境に合わせて読み替えてください。
pyenv のインストール方法については、拙著「pyenv の導入手順と使い方ガイド」もご参考になさってください。
🪴 フォントのインストール（オプション）
ZundaGPT2 Lite ではいくつかの画面で絵文字を使用しています。画面の表示がおかしい場合は、追加のフォントをインストールしておくよいでしょう。
# 日本語フォントのインストール
sudo apt install fonts-noto fonts-noto-cjk fonts-noto-cjk-extra fonts-noto-color-emoji
🎈 Raspberry Pi
環境: Raspberry Pi OS Bookworm 64bit, X11/LXDE
制限: 日本語入力したい場合はIBus限定、印刷機能は使えない
🎬 実行ファイルを使う場合
1. ダウンロード
GitHubのリリースページから ZundaGPT2Lite_x.x.x_raspberrypi_arm64.zip をダウンロードし、適当なディレクトリに展開します。
2. 実行
ZundaGPT2Liteをダブルクリックすれば起動します。
実行権限が不足している場合は chmod +x ZundaGPT2Lite を実行し、実行権限を付与してください。
🎬 Pythonで実行する場合
初回（インストールと起動）
# リポジトリをクローンする
git clone https://github.com/led-mirage/ZundaGPT2Lite.git
# プロジェクトディレクトリに移動
cd ZundaGPT2Lite
# Python仮想環境を作成
python -m venv venv
# Python仮想環境をアクティベート
. venv/bin/activate
# 依存パッケージをインストール
pip install -r requirements_linux.txt
# X11関連パッケージのインストール
sudo apt install libxcb-xinerama0 libxcb-cursor0
# シンボリックリンクの作成
sudo ln -s /usr/lib/aarch64-linux-gnu/libwebp.so.7 /usr/lib/aarch64-linux-gnu/libwebp.so.6
sudo ln -s /usr/lib/aarch64-linux-gnu/libtiff.so.6 /usr/lib/aarch64-linux-gnu/libtiff.so.5
# 起動
python app/main.py
２回目以降
# プロジェクトディレクトリに移動
cd ZundaGPT2Lite
# Python仮想環境をアクティベート
. venv/bin/activate
# 起動
python app/main.py
ビルド（実行ファイルの作成）
# プロジェクトディレクトリに移動
cd ZundaGPT2Lite
# Python仮想環境をアクティベート
. venv/bin/activate
# PyInstallerをインストール
pip install pyinstaller
# ビルドスクリプトに実行権限を付与
chmod +x build.sh
# ビルド実行（distディレクトリにZundaGPT2Liteファイルが作成される）
./build.sh
🎈 Linux Mint / Ubuntu
環境1: Linux Mint 22.1 Cinnamon Edition
環境2: Linux Ubuntu 24.04.2 Desktop
制限: 日本語入力したい場合はIBus限定、印刷機能は使えない
🎬 実行ファイルを使う場合
1. ダウンロード
GitHubのリリースページから ZundaGPT2Lite_x.x.x_linux_x64.zip をダウンロードし、適当なディレクトリに展開します。
2. 実行
ZundaGPT2Liteをダブルクリックすれば起動します。
実行権限が不足している場合は chmod +x ZundaGPT2Lite を実行し、実行権限を付与してください。
🎬 Pythonで実行する場合
初回（インストールと起動）
# リポジトリをクローンする
git clone https://github.com/led-mirage/ZundaGPT2Lite.git
# プロジェクトディレクトリに移動
cd ZundaGPT2Lite
# Python仮想環境を作成
python -m venv venv
# Python仮想環境をアクティベート
. venv/bin/activate
# 依存パッケージをインストール
pip install -r requirements_linux.txt
# X11関連パッケージのインストール
sudo apt install libxcb-xinerama0 libxcb-cursor0
# 起動
python app/main.py
２回目以降
# プロジェクトディレクトリに移動
cd ZundaGPT2Lite
# Python仮想環境をアクティベート
. venv/bin/activate
# 起動
python app/main.py
ビルド（実行ファイルの作成）
# プロジェクトディレクトリに移動
cd ZundaGPT2Lite
# Python仮想環境をアクティベート
. venv/bin/activate
# PyInstallerをインストール
pip install pyinstaller
# ビルドスクリプトに実行権限を付与
chmod +x build.sh
# ビルド実行（distディレクトリにZundaGPT2Liteファイルが作成される）
./build.sh
🎈 WSL2
環境: Ubuntu 24.04.2 LTS
制限: 日本語入力はできない、印刷機能は使えない
🎬 Pythonで実行する場合
初回（インストールと起動）
# リポジトリをクローンする
git clone https://github.com/led-mirage/ZundaGPT2Lite.git
# プロジェクトディレクトリに移動
cd ZundaGPT2Lite
# Python仮想環境を作成
python -m venv venv
# Python仮想環境をアクティベート
. venv/bin/activate
# 依存パッケージをインストール
pip install -r requirements_linux.txt
# ソフトウェアレンダリングするように設定
export QT_QUICK_BACKEND=software
# 起動
python app/main.py
２回目以降
# プロジェクトディレクトリに移動
cd ZundaGPT2Lite
# Python仮想環境をアクティベート
. venv/bin/activate
# ソフトウェアレンダリングするように設定
export QT_QUICK_BACKEND=software
# 起動
python app/main.py
🗨️ 余談：Raspberry Pi で動作させるときに苦労した点
🖊️ UIツールキットの選択
ZundaGPT2/LiteではGUIを構築するライブラリとして PyWebView を採用しています。そのPyWebViewもまた内部的に別のUIツールキットを使用するよう設計されており、Linuxの場合それは QT または GTK となり、どちらかを別途インストールする必要があります。
PyWebViewのドキュメントでは、以下のようなインストール方法が記載されていますが、ラズパイではpip install中に行われるソースビルドでエラーが発生しインストールできませんでした。
pip install pywebview[gtk] # GTKを使用する方法
pip install pywebview[qt] # PyQt6を使用する方法
ビルドエラー解消のために各種パッケージを追加するなど試みましたが、どちらも環境依存の問題が大きく、インストールすることはできませんでした。
そこで代替案として PySide6 を選択しました。
PySide6はQT本家が公式に管理・バイナリ配布しているため、ラズパイを含む多くの環境でビルド不要で利用可能です。PyWebViewもPySide6をQTバックエンドとして自動認識してくれるので、特に問題なく動作します。
PyWebViewとPySide6をまとめてインストールするには、以下のコマンドを実行します。
pip install pywebview[pyside6] # PySide6を使用する方法
あるいはPySide6単独でインストールする場合は、次のコマンドを実行すればOKです。
pip install pyside6 qtpy
🖊️ シンボリックリンクについて
現時点（2025/06/27）のおいて、pipでインストールできるPySide6の最新バージョンは 6.8.0.2 ですが、このバージョンは Debian12 Bookworm と互換性がありません。PySide6は内部で libwebp と libtiff というライブラリを使っているのですが、これらのライブラリがBookwormにはないため実行時にエラーになってしまいます。
この問題を解消するために、ここでは上記の手順ではシンボリックリンクを作成し対応しています。PySide6がlibwebpのバージョン6を要求したとき、Bookwormがサポートしてるlibwebpのバージョン7に要求を転送し処理するようにしています。libtiffについても同様です。
ただ、PySide6の次のバージョン 6.8.1 ではArm版Bookwormにも対応しているようなので、いずれシンボリックリンクを使用しなくても動作するようになると思われます。
作成したシンボリックリンクを削除するには次のコマンドを実行します（参考）。
# シンボリックリンクの削除
sudo rm /usr/lib/aarch64-linux-gnu/libwebp.so.6
sudo rm /usr/lib/aarch64-linux-gnu/libtiff.so.5
🖊️ 日本語入力について
日本語入力用のフレームワークは主に IBus と Fcitx5 がありますが、最近は Fcitx5 が使われることが多くなってきたようです。
私も最初 Fcitx5 を使おうとしたのですが、テキストボックスに日本語を入力しようとしても、どうしても日本語入力モードに切り替わりません。そして長時間にわたる試行錯誤の末、IBus であれば普通に日本語入力できることを発見しました。この時点で、私は Fcitx5 を使うことを諦めました。
Fcitx5 で日本語入力ができないのは、おそらく QT との相性問題だと思うのですが、正確なところは分かっていません。とりあえず IBus を採用すれば動作するため、私は IBus を使うことにしました。
📝 まとめ
本記事では ZundaGPT2 Lite を Linux系のOSで動作させる手順について記載しました。
ZundaGPT2 Lite は音声出力機能を省いた軽量バージョンですが、キャラクター設定機能やログ管理機能、Markdownレンダリングなどの機能は ZundaGPT2 と同様に備わっています。遊びだけではなく、学習や仕事などにも広くお使いいただけると思いますので、是非使ってみてください。
それでは今回はこの辺で。またネット空間のどこかでお会いしましょう。
じゃあね、バイバイ😊
Discussion