トラブルシューティング

このページでは、Quiraで発生する一般的な問題とその解決策を説明します。ここに記載されていない問題については、GitHub Issuesを確認するか、Discordでお問い合わせください。

インストールの問題

macOS:「Quiraは開発元が不明なため開けません」

問題: アルファビルドにはまだApple Developer証明書で署名されていないため、macOSのGatekeeperがQuiraをブロックします。

解決策:

1. FinderでQuiraアプリケーションを右クリック（またはControlクリック）
2. コンテキストメニューから「開く」を選択
3. 確認ダイアログで「開く」をクリック

または、システム設定 > プライバシーとセキュリティ > セキュリティでQuiraを許可できます。

macOS: 起動時にクラッシュ（Apple Silicon）

問題: AIモデルランタイムにはAccelerateフレームワークが必要で、Xcode Command Line Toolsがインストールされていないと失敗する場合があります。

解決策:

xcode-select --install

Linux: 共有ライブラリが見つからない

問題: QuiraはGTK4、WebKitGTK、その他のシステムライブラリに依存していますが、デフォルトでインストールされていない場合があります。

解決策（Ubuntu/Debian）:

sudo apt install libgtk-4-dev libwebkitgtk-6.0-dev libssl-dev pkg-config

解決策（Fedora）:

sudo dnf install gtk4-devel webkitgtk6.0-devel openssl-devel pkg-config

解決策（Arch）:

sudo pacman -S gtk4 webkitgtk-6.0 openssl pkg-config

AIモデルのダウンロード失敗

モデルのダウンロードが途中で停止または失敗する

問題: 初回のAIモデルダウンロード（モデルによって約2〜4 GB）が遅い接続や不安定な接続で失敗する場合があります。

解決策:

1. インターネット接続の安定性を確認
2. ダウンロードを再試行 — Quiraは最後のチェックポイントからの再開をサポート
3. ダウンロードが繰り返し失敗する場合、モデルを手動でダウンロード:

   # モデルファイルを直接ダウンロード
   curl -L -o ~/.quira/models/phi-3-mini-4k.gguf \
     https://models.quira.dev/phi-3-mini-4k-instruct-q4_k_m.gguf

モデルの読み込み失敗:「メモリ不足」

問題: デフォルトモデル（Phi-3 Mini、4ビット量子化）は約3 GBのRAMが必要です。メモリが限られたシステムではモデルの読み込みに失敗する場合があります。

解決策:

• 他のメモリを多用するアプリケーションを閉じる
• quira://settings/ai/modelでより小さいモデルに切り替える
• Apple Silicon Macでは、ユニファイドメモリが他のアプリで大量に消費されていないことを確認

Context Graphが構築されない

ページがContext Graphに表示されない

問題: ブラウジングしているのに、新しいページがグラフに追加されない。

解決策: 以下の一般的な原因を確認してください:

• Incognitoモード — Context GraphはIncognito/プライベートウィンドウでは設計上無効です。通常のウィンドウに切り替えてください。
• ドメイン除外 — ページのドメインが除外リストに含まれている可能性があります。quira://settings/security/exclusionsを確認してください。銀行、メール、医療サイトはデフォルトで除外されています（コンテンツフィルタリング参照）。
• Context Spaceが一時停止 — 現在のContext Spaceが一時停止している可能性があります。ツールバーのSpaceインジケーターを確認してください。
• ページが一時的すぎる — 3秒未満しか表示されていないページはデフォルトでグラフに追加されません。このしきい値は設定で調整できます。

Context Graphクエリが結果を返さない

問題: ブラウジング履歴があるのに、自然言語クエリが空の結果を返す。

解決策:

• インデクサーの完了を待つ — 再起動後、再インデックスに数分かかる場合があります
• quira://settings/aiでAIモデルのステータスを確認 — セマンティック検索にはモデルのロードが必要です
• まず簡単なクエリや正確なキーワードを試して、データベースにアクセスできることを確認

パフォーマンスの問題

メモリ使用量が高い

問題: 特に多くのタブを開いている場合、Quiraが予想以上のメモリを使用する。

解決策:

• 開いているタブを減らす — 各タブはページとそのコンテキスト用にメモリを消費します。Context Spacesを使って非アクティブなタブを整理・閉じてください。
• グラフの自動レンダリングを無効化 — リアルタイムグラフ可視化は大量のメモリを消費する可能性があります。quira://settings/graph/auto-renderで無効にし、必要に応じて開いてください。
• より小さいAIモデルを使用 — 小さい量子化モデルは精度がわずかに低下しますが、メモリ使用量が少なくなります。

グラフレンダリングが遅い

問題: 大きなグラフでグラフビジュアライゼーションが遅い、または応答しない。

解決策:

• WebGPUアクセラレーションを有効化 — quira://settings/graph/rendererでWebGPUが有効になっていることを確認。GPUがWebGPUをサポートしていない場合はWebGL2にフォールバック。
• グラフスコープを縮小 — 時間範囲やContext Spaceでフィルタリングして、表示ノード数を減らす
• フォースレイアウトのタイムアウトを増加 — 大きなグラフはより多くのシミュレーションステップが必要な場合があります。quira://settings/graph/layout-iterationsで調整

ソースからのビルドエラー

Rustコンパイル失敗:「error[E0658]: use of unstable library feature」

問題: Gecko統合レイヤーで使用されるいくつかの不安定な機能のため、QuiraにはRust nightlyが必要です。

解決策:

rustup toolchain install nightly
rustup override set nightly

Node.jsビルドステップが失敗

問題: UIレイヤーにはNode.js 20+と特定のnpmパッケージが必要です。

解決策:

# Node.jsバージョンを確認（20以上が必要）
node --version

# 依存関係をクリーンして再インストール
rm -rf node_modules
npm install

# ビルドを再試行
just build

Geckoビルド失敗: ディスク容量不足

問題: Geckoのソースからのビルドには、中間ビルドアーティファクト用に約30 GBのディスク容量が必要です。

解決策:

• ビルド開始前に少なくとも40 GBの空きディスク容量を確保
• デバッグビルドの代わりにjust build --releaseを使用してアーティファクトサイズを削減
• ホームディレクトリの容量が制限されている場合、CARGO_TARGET_DIRをより容量のあるドライブに設定