ライブデモ

コミュニティ Discord に参加してください: AI Stack Devs

AI Town は、AI キャラクターが生活し、チャットし、社交する仮想の町です。

このプロジェクトは、AI Town の独自のバージョンを簡単に構築およびカスタマイズするための、デプロイ可能なスターターキットです。研究論文Generative Agents: Interactive Simulacra of Human Behaviorに触発されています。

このプロジェクトの主な目標は、単なる楽しいものを作ることを超えて、拡張することが目的の強固な基盤を備えたプラットフォームを提供することです。バックエンドはネイティブに共有グローバル状態、トランザクション、およびシミュレーションエンジンをサポートし、単純なプレイプロジェクトから、スケーラブルなマルチプレイヤーゲームまで、あらゆるシナリオに適しています。二番目の目標は、このスペースのほとんどのシミュレーター（上記の元の論文を含む）が Python で書かれているため、JS/TS フレームワークを利用可能にすることです。

• 💻 スタック
• 🧠 インストール（クラウド、ローカル、Docker、自己ホスト、Fly.io など）
• 💻️ Windows の前提条件
• 🤖 選択した LLM の設定（Ollama、OpenAI、Together.ai など）
• 👤 カスタマイズ - 自分自身のシミュレートされた世界
• 👩‍💻 本番環境へのデプロイ
• 🐛 トラブルシューティング

• ゲームエンジン、データベース、およびベクトル検索: Convex
• 認証（オプション）: Clerk
• デフォルトのチャットモデルは llama3 で、埋め込みは mxbai-embed-large です。
• ローカル推論: Ollama
• 他のクラウド LLM に対応可能: Together.ai またはOpenAI API を話すすべてのもの。より多くのクラウドプロバイダーのサポートを追加する PR を歓迎します。
• 背景音楽生成: Replicate を使用してMusicGen

その他のクレジット:

• ピクセルアート生成: Replicate、Fal.ai
• プロジェクト内のコンポーネント上のすべてのインタラクション、背景音楽、およびレンダリングはPixiJS によって駆動されています。
• タイルシート:
  • https://opengameart.org/content/16x16-game-assets by George Bailey
  • https://opengameart.org/content/16x16-rpg-tileset by hilau
• このプロジェクトの元の POC のためにhttps://github.com/pierpo/phaser3-simple-rpgを使用しました。それ以来、アプリ全体を書き直しましたが、簡単な開始点を高く評価しました。
• 元のアセット by ansimuz
• UI は元のアセット by に基づいていますMounir Tohami

全体的な手順は:

1. ビルドとデプロイ
2. LLM に接続

Convex（バックエンド）の上でアプリケーションを実行するいくつかの方法があります。

1. 標準的な Convex セットアップです。ローカルまたはクラウドで開発できます。Convex アカウント（無料）が必要です。これがクラウドにデプロイして本格的に開発する最も簡単な方法です。
2. アカウントなしで試したい場合で、Docker に問題がなければ、Docker Compose セットアップは素晴らしく自己完結しています。
3. このプロジェクトのコミュニティフォークがあり、実行したいが修正したくない人向けに Pinokio でワンクリックインストールを提供しています😎。
4. また、Fly.io にデプロイすることもできます。手順については ./fly を参照してください。

注意：Windows を使用している場合は、以下を参照してください。

git clone https://github.com/a16z-infra/ai-town.git
cd ai-town
npm install

これには、Convex アカウントへのログインが必要です（まだの場合）。

実行するには：

npm run dev

http://localhost:5173 にアクセスできるようになりました。

フロントエンドとバックエンドを個別に実行することを希望する場合（バックエンド関数が保存される際に同期します）、2つのターミナルでこれらを実行できます：

npm run dev:frontend
npm run dev:backend

詳細については、package.json を参照してください。

自己ホスト型 Docker コンテナで Convex バックエンドを実行することもできます。ここでは、フロントエンド、バックエンド、ダッシュボードのすべてを docker compose で実行するように設定します。

docker compose up --build -d

-d を渡すと、コンテナはバックグラウンドで実行し続けます。1回実行後、サービスを stop および start できます。

• フロントエンドは http://localhost:5173 で実行されます。
• バックエンドは http://localhost:3210 で実行されます（HTTP API の場合は 3211）。
• ダッシュボードは http://localhost:6791 で実行されます。

ダッシュボードにログインして convex CLI からデプロイするには、管理者キーを生成する必要があります。

docker compose exec backend ./generate_admin_key.sh

これを .env.local ファイルに追加してください。注意：down と up を実行する場合は、キーを再度生成して .env.local ファイルを更新する必要があります。

# in .env.local
CONVEX_SELF_HOSTED_ADMIN_KEY="<admin-key>" # Ensure there are quotes around it
CONVEX_SELF_HOSTED_URL="http://127.0.0.1:3210"

その後、Convex バックエンドをセットアップします（1回限り）：

npm run predev

新しいコードをバックエンドに継続的にデプロイしてログを出力するには：

npm run dev:backend

ダッシュボードを表示するには、http://localhost:6791 にアクセスして、前に生成した管理者キーを提供してください。

ローカル推論に Ollama を使用する場合は、Docker をそれに接続するように構成する必要があります。

npx convex env set OLLAMA_HOST http://host.docker.internal:11434

接続をテストするには（実行した後）：

docker compose exec backend /bin/bash curl http://host.docker.internal:11434

「Ollama is running」と表示される場合は、問題ありません。そうでない場合は、トラブルシューティング セクションを確認してください。

注: バックエンドをクラウドで実行したい場合は、OpenAI や Together.ai などのクラウドベース LLM API を使用するか、クラウドからのトラフィックをローカルの Ollama にプロキシすることができます。詳しくは以下をご覧ください。

デフォルトでは、アプリは Ollama を使用してローカルで完全に実行しようとします。

1. Ollama をダウンロードしてインストールしてください。
2. アプリを開くか、ターミナルで ollama serve を実行してください。ollama serve はアプリが既に実行されている場合、警告を表示します。
3. ollama pull llama3 を実行して llama3 をダウンロードしてください。
4. ollama run llama3 でテストしてください。

Ollama モデルのオプションはここにあります。

使用するモデルをカスタマイズしたい場合は、convex/util/llm.ts を調整するか、npx convex env set OLLAMA_MODEL # model を設定してください。埋め込みモデルを編集したい場合:

1. convex/util/llm.ts の OLLAMA_EMBEDDING_DIMENSION を変更し、以下を確認してください: export const EMBEDDING_DIMENSION = OLLAMA_EMBEDDING_DIMENSION;
2. npx convex env set OLLAMA_EMBEDDING_MODEL # model を設定してください。

注: 遅さを感じた場合は、constants.ts の NUM_MEMORIES_TO_SEARCH を 1 に設定して、会話プロンプトのサイズを減らしたい場合があります。

OpenAI を使用するには、以下の手順が必要です:

// In convex/util/llm.ts change the following line:
export const EMBEDDING_DIMENSION = OPENAI_EMBEDDING_DIMENSION;

OPENAI_API_KEY 環境変数を設定してください。まだ持っていない場合は https://platform.openai.com/account/api-keys を訪問してください。

npx convex env set OPENAI_API_KEY 'your-key'

オプション: OPENAI_CHAT_MODEL と OPENAI_EMBEDDING_MODEL でモデルを選択してください。

Together.ai を使用するには、以下の手順が必要です:

// In convex/util/llm.ts change the following line:
export const EMBEDDING_DIMENSION = TOGETHER_EMBEDDING_DIMENSION;

TOGETHER_API_KEY 環境変数を設定してください。まだ持っていない場合は https://api.together.xyz/settings/api-keys を訪問してください。

npx convex env set TOGETHER_API_KEY 'your-key'

オプション: TOGETHER_CHAT_MODEL、TOGETHER_EMBEDDING_MODEL 経由でモデルを選択してください。埋め込みモデルの次元は EMBEDDING_DIMENSION と一致する必要があります。

Anthropic、Groq、Azure などの OpenAI 互換 API を使用できます。

• convex/util/llm.ts の EMBEDDING_DIMENSION を埋め込みモデルの次元に一致するよう変更してください。
• llm.ts の getLLMConfig を編集するか、環境変数を設定してください:

npx convex env set LLM_API_URL 'your-url'
npx convex env set LLM_API_KEY 'your-key'
npx convex env set LLM_MODEL 'your-chat-model'
npx convex env set LLM_EMBEDDING_MODEL 'your-embedding-model'

注: LLM_API_KEY が不要な場合は、設定しないでください。

LLM プロバイダーまたは埋め込みモデルを変更する場合は、データを削除して最初からやり直す必要があります。メモリに使用される埋め込みは、選択した埋め込みモデルに基づいており、ベクトル データベースの次元は埋め込みモデルの次元と一致する必要があります。それを行う方法については以下をご覧ください。

注意：キャラクターデータを変更するたびに、npx convex run testing:wipeAllTablesを実行してからnpm run devを実行し、すべてをConvexに再度アップロードする必要があります。これはキャラクターデータが初期ロード時にConvexに送信されるためです。ただし、npx convex run testing:wipeAllTablesはすべてのデータを削除することに注意してください。

1. 独自のキャラクターとストーリーを作成する：すべてのキャラクターとストーリー、およびそれらのspritesheet参照はcharacters.tsに保存されています。キャラクターの説明を変更することから始めることができます。

2. spritesheetsの更新：data/characters.tsでは、このコードが表示されます：

   export const characters = [
     {
       name: 'f1',
       textureUrl: '/assets/32x32folk.png',
       spritesheetData: f1SpritesheetData,
       speed: 0.1,
     },
     ...
   ];

   キャラクター用のスプライトシートを見つけ、対応するファイルでスプライトモーション/アセットを定義する必要があります（上の例では、f1SpritesheetDataはf1.tsで定義されました）。

3. 背景（環境）を更新する：マップはconvex/init.tsからdata/gentle.jsで読み込まれます。マップを更新するには、以下の手順に従ってください：

   • Tiledを使用してタイルマップをJSONファイルとしてエクスポートします（bgtiles と objmap という名前の2つのレイヤー）。
   • convertMap.jsスクリプトを使用して、JSONをエンジンが使用できる形式に変換します。

   node data/convertMap.js <mapDataPath> <assetPath> <tilesetpxw> <tilesetpxh>

   • <mapDataPath>：Tiled JSONファイルへのパス。
   • <assetPath>：タイルセット画像へのパス。
   • <tilesetpxw>：タイルセット幅（ピクセル単位）。
   • <tilesetpxh>：タイルセット高さ（ピクセル単位）。gentle.jsのように使用できるconverted-map.jsを生成します。

4. Replicateを使用してバックグラウンドミュージックを追加する（オプション）

   毎日のバックグラウンドミュージック生成のため、Replicateアカウントを作成し、プロフィールのAPI Tokenページでトークンを作成してください。npx convex env set REPLICATE_API_TOKEN # token

   これはReplicateからのwebhookを受け取ることができる場合にのみ機能します。通常のConvex cloudで実行している場合は、デフォルトで機能します。自分でホストしている場合は、アプリのURLの/httpにヒットするように設定する必要があります。Docker Composeを使用している場合はhttp://localhost:3211になりますが、トラフィックをローカルマシンにプロキシする必要があります。

   注意：ウィンドウがアイドル状態の場合、シミュレーションは5分後に一時停止します。ページを読み込むと一時停止が解除されます。また、UIのボタンで世界を手動で凍結・解凍することもできます。ブラウザなしで世界を実行したい場合は、convex/crons.tsの「stop inactive worlds」cronをコメントアウトすることができます。

   • convex/music.tsのプロンプトを変更してバックグラウンドミュージックを変更します。
   • convex/crons.tsのgenerate new background musicジョブを変更して、新しいミュージックを生成する頻度を変更します。

アクティビティが多い場合のバックエンドを停止するには

これはエンジンとエージェントの実行を停止します。デバッグするためのクエリを実行し、関数を実行することはできます。

npx convex run testing:stop

停止後にバックエンドを再起動するには

npx convex run testing:resume

ゲームエンジンまたはエージェントが実行されていない場合、エンジンをキックするには

npx convex run testing:kick

ワールドをアーカイブするには

ワールドをリセットして最初からやり直したい場合は、現在のワールドをアーカイブすることができます：

npx convex run testing:archive

その後、ダッシュボードでワールドのデータを見ることはできますが、エンジンとエージェントはもう実行されません。

その後、initで新しいワールドを作成できます。

npx convex run init

バックエンド展開を一時停止するには

ダッシュボードで展開設定にアクセスして、展開を一時停止・再開することができます。これはクライアントから呼び出された、スケジュールされた、またはcronジョブの場合など、すべての関数を停止します。上記にはより穏やかな停止方法があるため、最後の手段と見なしてください。