LLM grouping の2モード

広聴AI の分析方式 analysis_mode には、既定の階層クラスタリングのほかに LLM grouping(LLM 直接グルーピング) がある。LLM grouping は意見をトップレベルのグループへ分類する方式で、散布図の座標は従来どおり embedding から計算するためビューアはそのまま使える。

LLM grouping には枠の決め方で2つのモードがある。

  1. 自動グルーピング: 意見のサンプルから LLM が分類の枠自体を発見し、各意見を割り当てる。枠を事前に決めなくてよい。
  2. 指定カテゴリ分類(supervised): 分類の枠は人間が与え、LLM は各意見の割り当てだけを行う。あらかじめ決まった観点で意見を整理したいときに使う。

用語について:LLM が直接分類・グルーピングする方式の一般名は LLM grouping / LLM 直接グルーピング と呼ぶ。Jigsaw Sensemaker はこの一例の固有名詞であり、LLM grouping 全体を Jigsaw と呼ぶと一般カテゴリと特定ツールが混ざって混乱するので避ける(jigsaw-sensemaker)。

指定カテゴリ分類(supervised)

あらかじめ決めた分類枠に意見を割り当てたいケースは実運用でしばしばある(例: ワークショップで既定のカテゴリに意見を整理したい)。この用途が自動グルーピングと別に必要になる。

設定は analysis_mode を llm_grouping にし、llm_grouping.predefined_groups にカテゴリを与える(下は該当部分の抜粋。実行には input / question など通常の必須項目も要る)。

{
  "analysis_mode": "llm_grouping",
  "llm_grouping": {
    "predefined_groups": [
      { "label": "交通", "description": "公共交通に関する意見" },
      { "id": "park", "label": "公園・緑地", "description": "公園整備に関する意見" }
    ]
  }
}
  • 各カテゴリは label(必須)と description(任意だが推奨。割当精度が上がる)を持つ。id 省略時は g1, g2, … を自動採番。
  • predefined_groups を与えると枠の自動発見をスキップし、割り当てだけを行う。与えない(または空)場合は従来どおり自動グルーピング。

「その他」受け皿を必ず用意する

指定カテゴリ分類では、どのカテゴリにも当てはまらない意見のための「その他」カテゴリを必ず用意する。これは設計上の必須要件で、システムが自動付与する(ユーザ指定不要・削除不可)。

理由は、指定カテゴリのどれにも当てはまらない意見を無理に押し込めると、

  • 分類の品質が落ちる(関係ない枠に意見が混ざる)
  • 分類枠の過不足が見えなくなる

の2点が起きるため。「その他」に意見が多く集まることは、むしろ分類枠に抜けがあるシグナルとして読める。ラベルは llm_grouping.other_group_label(既定「その他」)で変更でき、ユーザが自分で同等の枠(id: "other" または同ラベル)を定義していればそれが受け皿として使われ二重には追加されない。

実装とスコープ

  • engine は packages/analysis-core/src/analysis_core/steps/llm_grouping.py。内部は「枠の発見(_discover_groups)→ 各意見の割り当て(_assign_groups)」の2段で、指定カテゴリ分類は発見段をスキップして固定枠を割り当て段へ渡す。非該当・無効応答は先頭枠ではなく「その他」へ寄せる。
  • 現状は CLI 専用(kouchou-analyze --config config.json)。PyPI の 0.1.3(2026-10-12 公開)には入っておらず、predefined_groups を渡すと config の検証で Unknown option 'predefined_groups' for step 'llm_grouping' として止まった。0.2.0(2026-10-26)以降の PyPI 版には入っている(2026-11-03 時点の最新は 0.3.0)。古い版を入れている場合は上げる(cli の「PyPI 版は main より遅れる」)。
  • 作成 UI(管理画面)からの指定カテゴリ分類は未対応で、WebUI 統合は Issue #997 で扱う(カテゴリ入力フォーム・「その他」固定表示・config の prune/round-trip 整合が論点)。
  • 由来は Issue #176(LLM ベース分類の2方向)。自動グルーピングの作成 UI + API + engine は #987、指定カテゴリ分類の CLI 実装は #994 / PR #996 で main 入り。

Open Questions

  • 「その他」が過大になっていないか(=枠が不適切でないか)を可視化・警告する仕組みは未実装。
  • 階層的な所与タクソノミ(2階層以上の指定枠)は未対応(現状は単層)。
  • 実 LLM を伴うフルパイプラインでの大規模な割当品質の評価は未実施。割当品質の評価はラベル品質評価(faithful-aggregation-vs-deliberation-dynamics 周辺の忠実性評価)とは別軸で設計する。

Updates

  • 2026-10-21: PyPI の 0.1.3(2026-10-12 公開)には指定カテゴリ分類が入っておらず、PyPI 版では config の検証で止まること、使うときは main から入れることを追記。設定例が抜粋であることを明記
  • 2026-11-03: PyPI 0.2.0 / 0.3.0 の公開を反映し、「PyPI 版には入っていない」を「0.1.3 には無く、0.2.0 以降には入っている」に更新(タグ analysis-core-v0.2.0 は PR #1016 の commit を含み、analysis-core-v0.3.0 の llm_grouping_specs.json に predefined_groups がある)
  • 2026-11-07: 「main の version 表記も 0.1.3 のまま」は 2026-10-21 時点の記録。保存済み upstream/main@085366779 では analysis-core の版は 0.3.0 で、analysis-core-v0.3.0 タグも同commitを指す。0.1.3への未収録という当時の観測と、mainの現在の版を分けて読む。今回はネットワークを使っておらず、PyPIへの公開成功や公開版の現状は再確認していない(根拠: kouchou-ai commit 085366779(2026-10-29、#1172)、packages/analysis-core/pyproject.toml:3、analysis-core-v0.3.0 タグ)。
  • 2026-11-20: #994 の残件だった実際の LLM での end-to-end 確認をした(サンプル意見 400 件、指定カテゴリ 5 つ、OpenAI 互換の API の gemma-4-31B-it、埋め込みはローカル)。main のままでは llm_grouping だけが全体の model を使わず gpt-4o-mini を送って失敗した。spec の既定値に model が入っていて、全体の model の引き継ぎより先に埋まるため。管理画面から LLM 直接グルーピングを選んだ場合も同じ経路(コードからの読み取り、画面での再現はしていない)。修正は PR #1219(未 merge)。修正後は全件がちょうど 1 つのカテゴリに入り、「その他」は 136 件(34%)で、自動運転・環境・国際競争力など 5 つの枠に入らない意見が集まった。一次記録は raw/experiments/2026-11-20-issue994-predefined-groups/
  • 2026-11-20: PR #1219 を main に merge した(600479b7)。LLM 直接グルーピングの段も全体の model を使うようになり、段ごとに model を書けばそちらが優先される。#994 も close。管理画面から選んだ場合の動きは、コードの読み取りでは同じ経路で直るはずだが、画面ではまだ確かめていない