公開用レポート結果(public_result.json)¶
分析の出力ディレクトリ(outputs/<dataset>/)には、結果の JSON が 2 つ並びます。
| ファイル | 役割 | 誰が読むか | 契約 |
|---|---|---|---|
hierarchical_result.json |
分析の全部入り。設定(config)を含めて再分析・複製・管理画面の編集に必要なものを持つ |
analysis-core の後続ステップ、API の複製・再実行、管理画面 | 内部形式。公開契約ではない |
public_result.json |
公開用。hierarchical_result.json から公開してよい項目だけを ホワイトリスト で写したもの |
公開 API、静的書き出し、公開ビューア、外部ツール | 公開契約(このページ) |
公開 API・静的書き出し・ビューア・外部のツールが依存してよいのは public_result.json です。hierarchical_result.json の形は、再分析や管理機能の都合で変わることがあります。
なぜ分けるか¶
hierarchical_result.json は分析・表示・説明のすべてを 1 ファイルで背負ってきました。集計ステップが設定を丸ごと書き出し、公開 API と静的書き出しがそのファイルをそのまま配布するため、設定に秘密が入ると公開ページに出ます。管理画面で入力した API キーの漏洩(GHSA-xr6j-6w48-xh62)はこの構造で起きました。
修正後の集計は非公開のキーを ブラックリスト で除いています(_public_config)。ただし新しいステップや設定項目が増えると、明示的に除かない限りそのまま公開側に出ます。public_result.json は逆向きで、ここに書いたキーしか含めません。新しい項目を公開したいときは analysis_core/public_result.py とこのページの両方を更新します。
同じ理由で、意見ごとに属性を足すステップ(意見の分類ラベル、賛否・新規性スコアなど)は arguments[].attributes に書きます。attributes の中身はホワイトリストの対象外(自由形式)なので、属性を増やすたびに契約を変える必要はありません。
いつ作られるか¶
public_result.json は hierarchical_result.json を書く(作り直す)たびに、同じ内容から作り直されます。analysis_core.public_result.write_result_files() が両方を一時ファイルに書いてから差し替えます。
- 集計ステップ(
analysis.hierarchical_aggregation) - レイアウト生成ステップ(
analysis.hierarchical_layout_generation。layoutsを書き足す) - 翻訳 CLI(
kouchou-translate --result ...で結果ファイルを上書きするとき)
管理画面でのラベル編集や再実行は集計をやり直すので、そこでも作り直されます。
古いレポート(この仕組みより前に作られたもの)には public_result.json がありません。パイプラインは「集計の出力が欠けている」と判定して次の実行時に集計をやり直し、ファイルを作ります。読む側で必要なら build_public_result(hierarchical_result) で同じ内容をその場で作れます。
公開 API が返すもの¶
公開 API の GET /reports/{slug} は、この契約の形を返します。
- 正本の
hierarchical_result.jsonから、build_public_result()で毎回作る(public_result.jsonの無い古いレポートも同じ) - 返す前に、レポートの公開範囲
visibilityと、可視化設定があればvisualizationConfigを足す
隣の public_result.json(写し)は読みません。写しが正本と食い違っていないことを確かめる手段が無いためです。2 つは同時に書かれますが、ストレージからファイル単位で復元・同期されると、古い写しの方が新しい更新日時を持つことがあります。正本から作れば、たとえば後から hidden_properties に足した属性の列が古い写しから漏れることはありません。読む量は従来(正本をそのまま返していたとき)と同じです。正本が無く写しだけがある場合は、従来どおり「レポートが無い」(404)として扱います。
写しは、正本を持たない配信先(第 3 段の分割読み込みや静的書き出し)に渡すためのものです。写しを直接配るようになったら、正本との食い違いを検出する手段(書き出し時の指紋など)をあわせて入れます。
ホワイトリストにない項目(再分析用の設定、実行状態、hidden_properties に指定した属性の列など)は返しません。公開ビューアと静的書き出し(ビルド時に公開 API から取得する)はこの応答を読みます。管理画面の JSON ダウンロード(/admin/reports/{slug}/json)は従来どおり hierarchical_result.json を返します。
形(schema_version 1)¶
{
"schema_version": 1,
"arguments": [ { "arg_id": "A1_0", "argument": "…", "comment_id": "c1", "x": 0.1, "y": 0.2, "p": 0,
"cluster_ids": ["0", "1_0", "2_3"], "attributes": { "age": "20代" }, "url": "https://…" } ],
"clusters": [ { "level": 1, "id": "1_0", "label": "…", "takeaway": "…", "value": 120, "parent": "0",
"density_rank_percentile": 0.2 } ],
"comments": { "c1": { "comment": "元コメント本文" } },
"propertyMap": { "age": { "A1_0": "20代" } },
"translations": { "en": { "overview": "…", "question": "…", "intro": "…", "clusters": { "1_0": { "label": "…", "takeaway": "…" } } } },
"overview": "…",
"comment_num": 1234,
"config": { "...": "下の表" },
"layouts": { "embedding_umap": { "kind": "point_layout", "points": { "A1_0": { "x": 0.1, "y": 0.2 } }, "meta": {} } },
"default_layout_id": "embedding_umap"
}
| キー | 型 | 説明 |
|---|---|---|
schema_version |
int | この契約の版。互換性を壊す変更のときだけ上がる |
arguments[] |
object | 意見。arg_id / argument / comment_id / x / y / p / cluster_ids / attributes / url のみ。attributes は自由形式(元データの attribute_* 列と、意見ごとの分類・スコア) |
clusters[] |
object | クラスタ。level / id / label / takeaway / value / parent / density_rank_percentile のみ |
comments |
object | comment_id → { "comment": 本文 }。レポート作成者が元コメントの公開を有効にした(config.enable_original_comments)ときだけ中身が入り、それ以外は {} |
propertyMap |
object | 属性名 → (arg_id → 値)。hierarchical_aggregation.hidden_properties に指定した属性は列ごと含めない |
translations |
object | 言語コード → 訳。各言語の overview / question / intro / clusters / arguments は省略可能。生成に使ったモデル等の meta は含めない |
overview |
string | 全体概要 |
comment_num |
int | 入力コメント数 |
config |
object | 表示に使う設定だけ(下の表) |
layouts |
object | 省略可能。レイアウト名 → { kind, points, meta }。レイアウト生成ステップを実行したときだけ |
default_layout_id |
string | 省略可能。layouts の既定 |
config に入るもの¶
公開ビューアが「問い・イントロ・使ったモデル・分析手順」の表示に使う項目だけです。
| キー | 用途 |
|---|---|
question, intro |
レポートの問いと、件数・モデルを添えた説明文 |
model, provider, is_embedded_at_local, analysis_mode |
モデル名の表示、レイアウトの既定 |
enable_source_link, enable_original_comments |
出典リンク・元コメント表示の有無 |
plan[] |
各ステップの step / run / reason |
extraction |
workers / limit / properties / categories / category_batch_size / source_code / prompt / model |
embedding |
model / source_code |
hierarchical_clustering |
cluster_nums / source_code |
hierarchical_initial_labelling, hierarchical_merge_labelling |
workers / source_code / prompt / model |
hierarchical_overview |
source_code / prompt / model |
hierarchical_aggregation, hierarchical_visualization |
source_code のみ |
opinion_classification |
enabled / labels |
入れないもの¶
- 秘密と内部情報:
user_api_key、_始まりのランタイムキー(サーバー内部パス)、local_llm_address、タイムアウト等の実行環境 - 実行状態:
status/start_time/completed_jobs/lock_until/current_job/current_job_started/previous(これらはhierarchical_status.jsonの領分。古いレポートのconfigには混ざっていることがある) - 内部の識別子:
name/input/output_dir - 「何を隠したか」と隠した属性の値:
hierarchical_aggregation.hidden_propertiesの中身(どの属性のどの値を隠す設定にしたか)と、指定した属性の列そのもの。 集計はこの設定に当たるコメントの元コメント本文をcommentsから除くが、hierarchical_result.jsonのpropertyMapには指定した属性の値を意見ごとに書いている。public_result.jsonではその属性をpropertyMapから列ごと外す。なお、当たるコメントから抽出した意見(arguments)は現状どおり残る。この設定を「本文だけを隠す」ものとするか「その値を持つコメント由来の意見ごと隠す」ものとするかは #1180 で扱う - 表示に使っていないもの:
hierarchical_visualization.replacements、翻訳のmeta
互換性の扱い¶
- 省略可能なキーを足すのは互換な変更で、
schema_versionは上げません。読む側は知らないキーを無視してください - キーを消す・意味や型を変えるときは
schema_versionを上げ、読む側(公開 API、ビューア、静的書き出し)を同時に更新します arguments[].attributesの中身はこの契約の対象外です。属性を足すステップは自由に増やせます- 公開 API は配信時に
visibility(公開範囲)を付けます。可視化設定(visualization_config.json)は別ファイルで、この artifact には含みません
検査¶
apps/api/scripts/check_report_secret_leak.py --report-dir <dir> は hierarchical_result.json と並んで public_result.json も秘密の混入を確認します。scrub_report_secrets.py は既存レポートの両方から非公開キーを取り除きます。
今後¶
この仕組みは段階的に入れています(Issue #1178)。
- 書く(済み):集計・レイアウト生成・翻訳が
public_result.jsonを書く。契約を宣言する - 読む(済み):公開 API が契約の形(正本から
build_public_result()で作ったもの)を返し、ビューアの型を契約に合わせる - 分ける:意見全件を 1 回で画面に渡す経路を分割読み込みにし、静的書き出しでも HTML の隣に JSON を置く。写しを直接配るので、正本との食い違いを検出する手段もここで入れる
hierarchical_result.json の各項目の説明は プラグイン出力データ構造 を参照してください。