# Web担当者向け実装指示書: 分散生成シミュレーションの生成管理ページ
## 目的
AIsimの大規模住民反応シミュレーションについて、研究方法としての「生成管理」を可視化して公開する。単なるシステム構成図ではなく、研究データの作り方、再開可能性、コスト制御、プロンプト設計、データ保全を読者が理解できるページにする。
## ページ仮タイトル
候補:
- 分散生成による住民反応シミュレーションの生成管理
- How We Run Large-Scale Resident Reaction Simulations
- AIsim Distributed Simulation Pipeline
## 掲載する中心図
使用ファイル:
```text
analysis/experiment_management_methodology_20260712/figures/distributed_generation_architecture.svg
```
Webで再描画したい場合:
```text
analysis/experiment_management_methodology_20260712/figures/distributed_generation_architecture.mmd
analysis/experiment_management_methodology_20260712/data/distributed_generation_architecture.json
```
図のトーン:
- 研究インフラだが、無骨すぎない。
- 色は落ち着いた青緑、墨色、薄い琥珀色を基調にする。
- 矢印を太くしすぎず、データの流れは左から右へ。
- 「Prompt cache」「Resumable shards」「Master database」を視覚的に強調する。
## 公開用説明文の案
### 短いリード文
本研究では、自治体の評価報告書を多数の仮想住民ペルソナに読ませ、理解、納得、信頼、反発、政策支持などの反応を構造化データとして生成している。生成は単一端末ではなく、複数OSの端末に分散し、非重複シャード、個別キャッシュ、検証report、外付け大容量ストレージ上の基盤データベースによって管理している。
### 方法論説明
評価報告書とペルソナの組み合わせは、まずprompt input JSONLとして構造化される。各行は、固定プロンプト、評価報告書ケースパック、ペルソナ情報、prompt hash、cache keyを持つ。大規模生成では、このJSONLを複数の非重複シャードに分割し、各ワーカー端末が独立に処理する。
各ワーカーは、出力JSONL、検証report、cache directoryを個別に持つ。これにより、API rate limit、ネットワーク停止、端末停止が起きても、同じshard/output/report/cacheを指定して再起動すれば、完了済みレコードを再利用しながら続行できる。最終的に全ワーカーの出力を集約し、schema validationと重複検査を行う。
### プロンプト設計説明
プロンプトはcache hitを得やすいよう、共通指示、出力スキーマ、評価報告書ケースパックを先に置き、可変のペルソナ情報を最後に配置している。大規模出力は長文自由記述ではなく、10個の5段階スコア、行動選好、反応モード、短い理由文、ペルソナとの接続文に限定する。これにより、数十万から百万件規模でも分析可能な粒度とコストのバランスを保つ。
### ペルソナ構造説明
ペルソナは単一の長文プロフィールではなく、4つのレイヤーで管理している。
```text
01 nucleus -> 基本設計セル
02 expanded -> 生活史・世界観・情報環境・語り口
03 extension -> 分析用構造化属性
04 geo -> 実在自治体・座標
```
説明には以下を使う。
```text
analysis/experiment_management_methodology_20260712/persona_data_structure.md
analysis/experiment_management_methodology_20260712/data/persona_data_layers.json
```
Webでは、`expanded` は人間らしさを作る文章レイヤー、`extension` は統計・可視化・層別分析のための構造化レイヤー、`geo` は架空地名や曖昧表現を避けて実在自治体に寄せるGISレイヤーとして説明する。シミュレーションpromptには全フィールドをそのまま長く入れるのではなく、必要項目を要約して渡す。
## 図中の端末表記
実端末名は公開しない。以下の表記にする。
| 公開名 | OS | 役割 |
|---|---|---|
| Worker A | macOS | 据置機。外付け大容量ディスクを持つ主ストレージ兼ワーカー |
| Worker B | Linux | 研究室ワークステーション |
| Worker C | Linux | ThinkPad系モバイルワークステーション |
| Control Laptop | macOS | 指示・監視・軽量作業用。大規模生成の主力からは外す |
## データ所在
基盤データベース:
```text
/Volumes/Data4T/lab/AIsim/data/
```
バックアップ:
```text
/Volumes/Data4T/lab/AIsim/backups/generated_20260704_live/
```
実行スクリプト:
```text
/Users/mmikami/lab/AIsim/scripts/
```
公開用コードコピー:
```text
/Users/mmikami/lab/AIsim/analysis/experiment_management_methodology_20260712/public_code/
```
プロンプト仕様:
```text
/Users/mmikami/lab/AIsim/docs/simulation_prompt_and_output_v1_1.md
/Users/mmikami/lab/AIsim/analysis/experiment_management_methodology_20260712/prompt_appendix.md
```
## 公開コードへのリンク案
`public_code/` に置いたコードをGitHubまたはWebページの添付ファイルとして公開する。
主要ファイル:
- `run_simulation_batch_v1.py`: 1 shardを処理するOpenAI-compatible API実行スクリプト
- `start_simulation_worker_v1.sh`: workerをnohupで起動する薄いラッパー
- `supervise_generic_simulation_workers_v1.py`: workerの停止・staleを検出し、再起動する監督スクリプト
- `merge_simulation_shards_v1.py`: 分散出力をmergeし、重複・schemaを検査する
- `build_pending_shards_example.py`: 完了済みpairを除外し、未処理分を分割する例
- `simulation_output_schema_v1_1.json`: 出力JSON schema
## Web実装メモ
- SVGはそのまま `![]()
` または `