はじめてのKyalulu

用意するもの#

Kyaluluはキャラクター、会話、記憶を管理するアプリです。文章を生成するモデルは別の推論エンジンで動かします。まずはモデル不要のMock Echoで画面と保存を確認し、その後にエンジンを接続すると、起動の問題とモデルの問題を切り分けられます。

• Python 3.11以上、uv 0.12以上。
• Node.js 20以上、pnpm 10以上。公開workspaceの指定はpnpm 10.30.1です。
• Gitと、依存パッケージを取得できるネットワーク。

ソースを取得し、環境を設定する#

以下はWindowsのPowerShell用です。保存先は任意ですが、以降のコマンドはすべて取得したリポジトリの直下で実行してください。既存環境に上書きせず、新しい作業フォルダーで始めると安心です。

git clone https://github.com/ELRdn/Kyalulu.git
cd Kyalulu
Copy-Item .env.example .env

macOS／Linuxでは最後の行をcp .env.example .envに置き換えます。作成した.envをテキストエディターで開き、最初は次の外部接続・汎用エイリアスを空にしてください。公開のサンプルには特定の接続先やモデル名が入っており、そのまま自分の設定になるとは限りません。

OPENAI_COMPATIBLE_URL=
OPENAI_COMPATIBLE_API_KEY=
LLM_BASE_URL=
LLM_API_KEY=
LLM_MODEL=

Mock Echoの送信には外部APIキーもモデルのダウンロードも不要です。OllamaやLM StudioのローカルURLは既定値を残せます。後で接続先を変更したらAPIを再起動します。キー入りの.envを共有しないでください。接続先を選ぶ前にデータとプライバシーも確認しましょう。

workspaceの依存関係を導入する#

uv sync --frozen --all-packages --no-install-workspace
pnpm install --frozen-lockfile

Python側はルートのpyproject.tomlがruntimeをworkspaceメンバーとして指定しています。--all-packagesでruntimeの依存関係も対象にし、--no-install-workspaceでルートなどのworkspaceパッケージ自体のインストールを省きます。APIのPythonソースは次の起動コマンドで明示的に参照します。仮想環境はルートの.venvです。

--frozenは公開lockfileを使う指定です。依存解決に失敗したら、まずPython／uvの版、取得したソースとlockfile、ネットワークを確認してください。Windowsでuvキャッシュの権限エラーが出た場合は、そのシェルで$env:UV_CACHE_DIR = "$PWD/.uv-cache"を指定して再実行できます。通常チャットの初回起動にdev／remoteの追加依存は必要ありません。

APIとWebを別々のターミナルで起動する#

ターミナルA：API

.venv/Scripts/python.exe -m uvicorn python.api.main:app --app-dir runtime --host 127.0.0.1 --port 8000

macOS／Linuxでは.venv/Scripts/python.exeを.venv/bin/pythonに置き換えます。--app-dir runtimeでpython.api.mainを読み込めるようにします。ターミナルを開いたままにし、APIは同じ保存先に対して1プロセスで運用してください。

ターミナルB：Web

別のターミナルで同じリポジトリ直下へ移動してから実行します。

pnpm dev

ブラウザーでhttp://localhost:5173を開きます。Webは/apiへの通信を8000番のAPIへ中継します。画面だけ表示されて接続できない場合は、ターミナルAのエラーを確認してください。ポートが使用中なら既存プロセスを確認し、二重起動を避けます。Webを独自のポートへ変える場合、Hub取得用にはAPI側のKYALULU_TRUSTED_ORIGINSにも正確なOriginが必要です。

Mock Echoで最初の会話を確認する#

1. 新しい会話を開き、モデルとしてMock Echoを明示的に選びます。
2. 「こんにちは。これは起動確認です」と送信します。
3. 入力を反映したダミーの返事が表示され、履歴が残ることを確認します。
4. 別の画面へ移動して会話を開き直し、必要なら再読み込みして履歴を確認します。

期待する結果は、画面・API・保存がつながり、送信した内容に対応する返事が見えることです。Mockの文章はキャラクター品質や実モデルの速度の評価には使えません。モデル一覧が空ならAPIの起動ログとYAMLレジストリ同期を確認し、一覧にモデルがあっても準備完了とは考えないでください。

接続診断はStatusから確認できます。APIのGET /api/modelsとGET /api/providers/healthも切り分けに使えます。まずこの段階が安定してから、キャラクターの取り込みへ進むと設定を確認しやすくなります。

推論エンジンと任意のDesktopを使う#

実際の生成を使う準備ができたら、LE、LM Studio、Ollama、またはOpenAI互換APIを選びます。ローカルモデルはエンジン側で用意・起動し、モデルIDと接続状態を確認してからKyaluluで選択します。LEの既定接続先は127.0.0.1:8130です。LEが配信するモデルはle:<モデルID>として現れるため、通常は追加YAMLが不要です。詳しい設定はモデルと接続先を参照してください。

Desktopの開発シェルを使う場合は、依存導入後に別のターミナルから起動できます。

pnpm dev:desktop

Desktopは既存APIがあれば利用し、なければcheckoutのPython環境を使って起動を監督します。LEの自動起動は別途バイナリー指定が必要です。公開資料ではPython／LE同梱の配布版検証が未完了なので、このコマンドを完成したインストーラーの代わりとは扱いません。使い方は記憶や人物像と世界観へ、全体の入口はドキュメント一覧へ進めます。