インストール - Hazkey
概要
Hazkeyは、Fcitx5向けの高精度日本語入力エンジンである。
スローガンは「思考を止めない日本語入力」であり、入力作業を妨げないUI/UXの実装を目指して設計されている。
iOS/MacOS向けアプリであるazooKeyと同じ高精度変換技術 (AzooKeyKanaKanjiConverter) を採用しており、Linux環境での日本語入力を効率化する。
ビルドにはSwift 6.1以上が必要であり、RHEL および SUSE環境ではビルド環境の構築に一定の手順を要する。
主な特徴は以下の通りである。
| 機能 | 説明 |
|---|---|
| 高精度変換エンジン | iOS/MacOS向けアプリであるazooKeyと同じ変換技術を採用し、高い変換精度を実現する。 |
| 自動変換機能 | 入力すると即座に自動で変換され、変換操作に妨げられることなく長文を入力できる。 |
| Zenzaiニューラル変換 | GPT-2ベースのAIによるプロフィールや文脈を考慮した高度な変換に対応する。(オプション) |
| GGMLサポート | GPU対応バックエンド (Vulkan) を利用した高速処理が可能である。 |
公式情報は以下を参照する。
- 公式サイト
- GitHubリポジトリ
動作要件
Hazkeyのビルドおよび動作に必要なソフトウェアを以下に示す。
| ソフトウェア | 必要バージョン | 備考 |
|---|---|---|
| Swift | 6.1 以上 | Swiftlyによるインストールを推奨 |
| fcitx5 | 5.0.4 以上 | 入力フレームワーク本体 |
| Qt | 6.7推奨 (6.2以降で可) | 6.7未満では表示に問題が発生する場合がある。 |
| CMake | 3.21以上 (4.x以降推奨) | ビルドシステム |
| Protobuf | 3.12以上 | プロトコルバッファライブラリ |
| Ninja | 最新版推奨 | ビルドツール |
| Gettext | 最新版推奨 | 国際化対応ライブラリ |
| Vulkan headers | 最新版推奨 | GPU対応バックエンド用 (オプション、無効化可能) |
Swiftのインストール
Hazkey のビルドには Swift 6.1以上が必要である。
現在の推奨インストール方法は、公式ツールの Swiftly (rustup 相当) を使用する方法である。
公式サポート状況
ディストリビューションごとの公式サポート状況を以下に示す。
| ディストリビューション | 公式サポート |
|---|---|
| RHEL 9 | 公式サポート |
| RHEL 10 | 未公式 (RHEL 9ツールチェインで動作可) |
| SUSE 15 / 16 | 未公式 (RHEL 9ツールチェインで動作可) |
RHEL
RHEL 10は、Swiftの公式サポートリストに未掲載だが、RHEL 9と非常に近い構成のため、同ツールチェインで動作する。
まず、依存パッケージをインストールする。
sudo dnf install pkg-config binutils gcc git glibc-static libbsd-devel libcurl-devel libedit-devel libicu-devel libstdc++-static \
python3 sqlite-devel zlib-devel ncurses-devel
Swiftlyをダウンロードして初期化する。
curl -O https://download.swift.org/swiftly/linux/swiftly-$(uname -m).tar.gz tar xf swiftly-$(uname -m).tar.gz cd swiftly-$(uname -m) ./swiftly init --quiet-shell-followup
init実行時に RHEL 10は未公式プラットフォームです と表示された場合は、プロンプトでRHEL 9を選択する。
環境変数を設定する。
# Bash / Zsh
. "${SWIFTLY_HOME_DIR:-$HOME/.local/share/swiftly}/env.sh"
# Fish
source (set -q SWIFTLY_HOME_DIR; and echo $SWIFTLY_HOME_DIR; or echo $HOME/.local/share/swiftly)/env.fish
最新のSwiftをインストールする。
swiftly install latest
正常にインストールされているかどうかを確認する。
swift --version
SUSE
SUSEでは、Swiftlyが非公式プラットフォームと検出するため、手動でRHEL 9ツールチェインを選択する。
まず、依存パッケージをインストールする。
# SUSE 16
sudo zypper install pkg-config binutils gcc gcc-c++ git gzip glibc-static libbsd-devel libedit-devel libicu-devel \
libcurl-devel ncurses-devel sqlite3-devel zlib-devel python3
# SUSE 15.6
sudo zypper install pkg-config binutils binutils-gold gcc gcc-c++ git gzip glibc-static libbsd-devel libedit-devel libicu-devel \
libcurl-devel ncurses-devel sqlite3-devel zlib-devel python3
Swiftlyをダウンロードして初期化する。
curl -O https://download.swift.org/swiftly/linux/swiftly-$(uname -m).tar.gz tar xf swiftly-$(uname -m).tar.gz cd swiftly-$(uname -m) ./swiftly init --quiet-shell-followup
./swiftly init --quiet-shell-followup コマンドを実行した時、以下に示すエラーが出力される場合がある。
Error: The ca-certificates package is not installed. Swiftly won't be able to trust the sites to perform its downloads. You can install the ca-certificates package on your system to fix this.
これは、Swiftlyは特定のLinuxディストリビューション (Debian系) のファイルパス (/etc/ssl/certs/ca-certificates.crt )を探しているためである。
SUSEにおいてはパスが異なるため、所定のパスにシンボリックリンクを貼る必要がある。
sudo ln -s /var/lib/ca-certificates/ca-bundle.pem \
/etc/ssl/certs/ca-certificates.crt
再度、./swiftly init --quiet-shell-followup コマンドを実行する。
初期化中に以下のプロンプトが表示されるので、6 を入力して、RHEL 9を選択する。
SUSE Linux Enterprise 15 SP 6 is not an officially supported platform, but the toolchains for another platform may still work on it. Please select the platform to use for toolchain downloads: 0) Cancel 1) Ubuntu 24.04 2) Ubuntu 22.04 3) Ubuntu 20.04 4) Ubuntu 18.04 5) Fedora Linux 39 6) RHEL 9 7) Amazon Linux 2 8) Debian GNU/Linux 12
環境変数を設定する。
# Bash / Zsh
. "${SWIFTLY_HOME_DIR:-$HOME/.local/share/swiftly}/env.sh"
# Fish
# Fishの場合は、~/.config/fish/conf.d/swiftly.fish にパスが追加される
source (set -q SWIFTLY_HOME_DIR; and echo $SWIFTLY_HOME_DIR; or echo $HOME/.local/share/swiftly)/env.fish
最新のSwiftをインストールする。
swiftly install latest
正常にインストールされているかどうかを確認する。
swift --version
Swiftlyの主なコマンド
下表に、Swiftlyの主なコマンドを示す。
| コマンド | 説明 |
|---|---|
| swiftly list-available | インストール可能なバージョンの一覧を表示する。 |
| swiftly install 6.2.3 | 特定バージョンをインストールする。 |
| swiftly use 6.2.3 | 使用するバージョンを切り替える。 |
| swiftly uninstall 5.10 | 指定バージョンを削除する。 |
| swiftly self-update | Swiftly自体を更新する。 |
| swiftly install main-snapshot | 開発スナップショットをインストールする。 |
Dockerを使用する方法
RHEL / SUSEの環境構築に問題が生じる場合は、公式コンテナイメージを使用する方法が最も確実である。
Docker および Podman のどちらでも使用可能である。
# バージョン確認 podman run -it --rm swift:latest swift --version # プロジェクトのビルド podman run -it --rm \ -v $(pwd):/workspace -w /workspace \ swift:latest swift build
Swiftのアンインストール
Swiftlyでインストールした場合は、Swiftly経由で削除する。
ツールチェーンの確認と削除
まず、インストール済みのツールチェーンを確認する。
swiftly list
表示されたバージョンをアンインストールする。
複数バージョンがある場合は、それぞれに対して実行する。
swiftly uninstall <バージョン 例: 6.2.3>
Swiftly本体の削除
Swiftly本体と全てのツールチェーンを削除する。
rm -rf ~/.local/share/swiftly rm -f ~/.local/bin/swiftly
シェル設定のクリーンアップ
Swiftlyインストール時に追加された環境変数の設定を削除する。
Fishの場合は、以下のコマンドで該当する設定を確認する。
grep -rn "swiftly\|SWIFT" ~/.config/fish/
該当する行があれば、エディタで削除する。
依存関係のライブラリのインストール
Hazkeyのビルドに必要な依存パッケージをインストールする。
RHEL
Vulkanを使用しない場合は、vulkan-headersのインストールを省略できる。
sudo dnf install cmake ninja-build gettext protobuf-devel protobuf-compiler fcitx5-devel \
qt6-qtbase-devel qt6-qttools-devel vulkan-headers
SUSE
Vulkanを使用しない場合は、vulkan-headersのインストールを省略できる。
sudo zypper install cmake ninja gettext-tools protobuf-devel fcitx5-devel \
qt6-base-devel qt6-tools-devel qt6-linguist-devel vulkan-headers
shaderc glslang-devel # Vulkanを有効にする場合
ビルドとインストール
ソースコードの取得
Gitを使用して、Hazkeyのソースコードを再帰的にクローンする。
--recursive オプションはサブモジュールも含めて取得するために必要である。
git clone --recursive https://github.com/7ka-Hiira/fcitx5-hazkey.git -b 0.2.1
ビルド
Hazkeyをビルドおよびインストールする。
Vulkanを無効にしてビルドする場合は、-DGGML_VULKAN=OFF を設定する。
cd fcitx5-hazkey
mkdir build && cd build
cmake -G Ninja \
-DCMAKE_C_COMPILER=<GCC 8以降のGCC> \
-DCMAKE_CXX_COMPILER=<GCC 8以降のG++> \
-DSWIFT_LINK_PATH=$HOME/.local/share/swiftly/toolchains/<バージョン>/usr/lib/swift/linux \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX=/usr \
-DGGML_VULKAN=ON \ # Vulkanを有効にする場合
..
ninja -j $(nproc)
sudo ninja install
インストール完了後、Fcitx5を再起動して、Hazkeyを入力メソッドとして選択する。
Zenzaiのインストール
Zenzaiは、ニューラル変換用のモデルとGGMLバックエンドを使用するオプション機能である。
GPUバックエンドを使用する場合は、Hazkeyを -DGGML_VULKAN=ON でビルドする。
なお、CPUバックエンドのみでもZenzaiは使用可能である。
Vulkanドライバのインストール
NVIDIA GPU
NVIDIA GPUでVulkanバックエンドを使用する場合は、NVIDIAプロプライエタリドライバとVulkan ICDをインストールする。
NVIDIA CUDAリポジトリを追加して、ドライバと確認ツールをインストールする。
# RHEL # NVIDIA CUDAリポジトリを追加して、ドライバと確認ツールをインストールする sudo dnf config-manager --add-repo https://developer.download.nvidia.com/compute/cuda/repos/rhel10/x86_64/cuda-rhel10.repo sudo dnf install cuda-drivers vulkan-tools ## GeForce GT 1030を含むPascal世代以前のGPUは、NVIDIAオープンカーネルモジュールとG07系列に対応していないため、 ## CUDAリポジトリで提供される580系列を指定する sudo dnf install 'cuda-drivers-580*' vulkan-tools # SUSE # nvidia-gl-G07パッケージは、Vulkan ICDを含むユーザ空間ライブラリである sudo zypper addrepo --refresh 'https://download.nvidia.com/opensuse/leap/$releasever/' NVIDIA sudo zypper refresh sudo zypper install nvidia-driver-G07-kmp-meta nvidia-gl-G07 vulkan-tools ## GeForce GT 1030を含むPascal世代以前のGPUは、NVIDIAオープンカーネルモジュールとG07系列に対応していないため、 ## プロプライエタリの580系列を使用する sudo zypper install nvidia-driver-G06-kmp-meta nvidia-gl-G06 vulkan-tools
cuda-drivers は、Vulkan ICDを含む nvidia-driver-libs を依存関係としてインストールする。
PCを再起動して、NVIDIAドライバとVulkanを確認する。
nvidia-smi vulkaninfo --summary
vulkaninfo --summary コマンドの出力にNVIDIA GPUが表示されれば、Vulkanバックエンドは利用可能である。
AMD GPU
AMD GPUでVulkanバックエンドを使用する場合は、Vulkan loaderとRADVドライバをインストールする。
# RHEL sudo dnf install mesa-vulkan-drivers vulkan-tools # SUSE sudo zypper install libvulkan_radeon vulkan-tools
vulkaninfo --summary コマンドの出力にAMD Radeon GPUが表示されれば、Vulkanドライバは利用可能である。
vulkaninfo --summary
モデルのダウンロードと有効化
- hazkey-settingsを起動して、[AI]タブを開く。
- 黄色の警告欄にある [モデルをダウンロード]ボタンを押下する。
- Zenzai v3.1 smallモデルが自動的にダウンロードされて、SHA-256を検証した後に以下に示すディレクトリへ保存される。
~/.local/share/hazkey/zenzai/zenzai.gguf
- ダウンロード完了後に[再読み込み]ボタンを押下する。
- [Zenzaiを有効化]チェックボックスにチェックを入力して、[適用]ボタン または [OK]ボタンを押下する。
- Vulkan GPUがバックエンドの選択肢に表示されない場合は、Fcitx5を再起動する。
fcitx5-remote -r
トラブルシューティング
下表に、ビルドおよびインストール時に発生する可能性がある問題と対処法を示す。
| 問題 | 発生環境 | 対処法 |
|---|---|---|
| 三角関数の再定義エラーが発生する | 全環境 | Swiftのシムヘッダファイル /<swiftのインストール場所>/lib/swift_static/_FoundationCShims/_CStdlib.h の 約50行目にある3行をコメントアウトする。 |
_mm256_set_m128 が未定義のエラーが発生する |
SUSE 15 | SUSE 15付属のGCC 7では _mm256_set_m128 が未定義のため、GCC 8以降を使用する。 |
三角関数の再定義エラーへの対処
Swift のシムヘッダーファイルに含まれる三角関数の定義が競合する場合がある。
以下に示す手順でエラーを解消する。
対象ファイルを開いて、該当ファイルの約 50 行目付近にある三角関数の定義に関する3行をコメントアウトする。
nano /<swiftのインストール場所>/lib/swift_static/_FoundationCShims/_CStdlib.h
GCCバージョン問題への対処
_mm256_set_m128 というAVX intrinsic関数は、GCC 8 以降のimmintrin.hファイルで追加されたため、GCC 7以前ではビルドできない。
cmake -G Ninja \ -DCMAKE_C_COMPILER=<GCC 8以降のGCC> \ -DCMAKE_CXX_COMPILER=<GCC 8以降のG++> \ -DCMAKE_BUILD_TYPE=Release \ -DCMAKE_INSTALL_PREFIX=/usr \ -DGGML_VULKAN=OFF \ ..
