← ガイダンス一覧へ戻る

3読解ガイド生成

元表現: 読解ガイド係 / StudyGuide ブロック詳細

本文を1文ずつに分けて、区切り・訳・語句の説明を付けて返すブロック。受け取るのは本文だけで、学習者の事情は一切渡されません。

抽象度 Lv.4(技術用語+システム上のやりとりまで/製品名・ライブラリ名は書かない)

1. 概要

本文を受け取り、1文ずつに分けて、区切り・訳・語句の説明を付けて返すブロック。 このアプリの中心的な成果物を作る場所で、外部の言語モデルを使う。

ただし、このブロックが受け取るのは本文だけ。 誰が使うのか、過去に何を出題したか、どの語を覚えたかは一切渡されない。

2. 位置づけ

2. 処理オーケストレーション → 3. 読解ガイド生成 → 2番へ返す → 6番(材料の1つとして)/7番(保存される)

3. 処理内容(Lv.4)

4. なぜこの位置にあるか(設計意図)

6番より前でなければならない。6番(単語テスト)は読解ガイドを材料の1つとして受け取る。 本文だけからでも問題は作れるが、読解ガイドがあると「その文の中でどう使われているか」を踏まえられる。

2番から本文以外を渡していないのは意図的。 過去の出題履歴や習得状態を渡せば、3番の出力も履歴に引きずられる。 3番には「この本文を、初めて読む中1に説明する」ことだけをさせ、学習者ごとの事情は4・5・6に閉じ込めている。 その結果、同じ本文からは(モデルのゆらぎを除けば)誰に対しても同じ読解ガイドが出る

2-3で真っ先に開始されるのも、ここが一番遅いから。待ち時間を他の読み出しで埋めている。

5. 詳細プロセス分解

工程主体やりとりの内容方向
3-12番本体 → 3番本体本文(それ以外は渡されない)
3-23番本体(内部)指示書・本文・受け取る書式を組み立てる
3-33番本体 → 外部モデル指示書+本文+書式の指定+利用者を表す印
3-4外部モデル → 3番本体文ごとの原文・区切り入り・訳・説明
3-53番本体(内部)書式に合っているかの点検
3-63番本体(内部)文番号を1から振り直す
3-73番本体 → 2番本体読解ガイド一式

各行を文章にすると

3-1 2番から本文だけが渡される。本のタイトルもページ番号も、利用者が誰かも渡されない。3番は「この英文を説明せよ」以上の文脈を持たない。

技術的には HTTPではなく関数呼び出し。引数は本文の文字列1つと、外部へ添えるための32桁の識別子だけ。3番には専用のパスが無いので、外から /api/... で直接呼ぶことはできない。

3-2 3番本体は、あらかじめ用意された指示書(中1向けに、どう説明するかの決め事)と、受け取った本文を組み立てる。同時に、返してほしい形も用意する。「文ごとに、原文と、区切りを入れた形と、訳と、説明を1〜6項目」という決まった枠。この組み立ては自分の中だけの処理。

技術的には 送るメッセージを2つの役割に分ける。system=前提として常に効かせる指示書user=今回の入力(本文)。分けておくと、本文の中にたまたま命令のような文が混じっていても、指示側と取り違えにくくなる。あわせて、返してほしいJSONの型を用意する。

3-3 外部モデルへ送る。2-2で作られた利用者を表す印も一緒に添える。

技術的には HTTPSでJSONをPOSTする。「推論にかける手間=中」「返す量=中」を指定。やり取りを相手側に保存しない設定にし、2番が作った32桁の識別子を添える。

3-4 モデルから、枠に沿った形で返ってくる。自由な文章ではなく、最初に指定した項目に分かれた状態で返る。

技術的には 型どおりのJSONが返る。文の配列で、各文が通し番号・原文・区切りを入れた形・訳・説明(1〜6項目)を持つ。

3-5 返ってきたものが枠に合っているかを点検する。説明が0項目だったり7項目以上だったり、訳が空だったりすれば、受け取り自体が失敗になる。3番には作り直しの仕組みがない。(6番にはある。)合わなければそのまま止まる。

技術的には 受け取ったJSONを型に当てはめて検証する。配列が空、説明が0項目または7項目以上、訳が空文字 ── どれもこの時点で例外になる。3番は作り直しをしないので、例外はそのまま2番へ上がり、最終的にブラウザへは 500 が返る。

3-6 点検を通ったら、文の番号を1から順に振り直す。モデルが付けてきた番号は使わない。地味な工程だが、これがないと後段が壊れる。

技術的には 配列の並び順に沿って、通し番号を1から付け直す。モデルが付けてきた番号は捨てる。音声の取得が GET /api/guides/{id}/speech?sentence=3 のように、番号をクエリ文字列の鍵として使うため、1から抜けなく並んでいることが前提になっている。番号が飛べば、押した文と違う音声が鳴る。

3-7 2番へ返す。2番はこれを6番の材料にし、7番に保存させる。

技術的には 関数の戻り値として2番へ返すだけ。3番はファイルに何も書かない。

主体が3つなので、この図は画面の幅に収まります

2. 本体
3. 本体
外部モデルAI利用
3-1 本文(それ以外は渡されない)
3-2 指示書・本文・受け取る書式を組み立てる
3-3 指示書+本文+書式の指定+利用者を表す印
3-4 文ごとの原文・区切り入り・訳・説明
3-5 書式に合うかの点検(合わなければ止まる)
3-6 文番号を1から振り直す
3-7 読解ガイド一式

6. この分解から見えること

  • 7工程のうち、モデルに任せているのは1つだけ(3-3/3-4)。 前後は組み立てと点検と番号の振り直しで、すべて決まった手順。
  • 文番号の振り直し(3-6)が、見た目より重い意味を持っている。 音声(8番)は「このページの◯番の文」という指定で呼ばれる。 番号が飛んでいたり重複していたりすると、押した文と違う音声が鳴る。 モデルの付けた番号を捨てて機械的に振り直すのは、後段が番号を鍵として使うから
  • 3番には作り直しがなく、6番にはある。この差は、点検で分かることの違いから来ている。 3番の点検は「枠に合っているか」しか見られない(訳の質は機械には測れない)。 6番は「本文にない語を出していないか」「禁止語が混ざっていないか」を事実として照合できる。 照合できるものにだけ作り直しを付ける、という線引きになっている。
  • 3番が学習者の事情を知らないことが、他の設計を成立させている。 もし3番が習得状態を知っていたら、「覚えた」を押すたびに読解ガイドも変わり得ることになり、 同じページを開き直すと説明が違う、という事態が起きる。 3番を文脈から切り離したことで、保存された読解ガイドはあとから変わらないものになっている。

7. 失敗時の挙動(未確認あり)

どこで失敗するか何が起きるか
3-3/3-4 のモデル呼び出し例外が上がり、2番を通って 500「英文読解ガイドを生成できませんでした」
3-5 の点検同上(500)。作り直しはしない
いずれの場合も6番も7番も走らない。ページは作られない。並行して走っていた4・5の読み出しは無駄になる

利用者の画面にどう出るか、再試行の導線があるかは未確認

8. 未確認事項

  • 説明を1〜6項目のどこに収めるかの判断はモデル任せで、こちら側の基準は無い(意図的かは未確認)
  • 本文が非常に長い場合(上限は1万6千字)に、文の数や説明の質がどう変わるか
  • 3番の失敗が、モデル側の一時的な不調によるものか、本文の内容によるものかを切り分ける手段があるか
  • 指示書の中身はLv.5相当のため、この文書では扱っていない(必要なら別途)

※ この解説は、2026年8月14日時点の studyguide のプログラムを読んで作成しました。

※ 抽象度は Lv.4 で統一しています。通信の方式・データの形式・認証のしくみ・ステータスコードまでは書き、製品名やライブラリ名、関数名までは踏み込みません(そこは Lv.5)。

※ 工程の番号は全体図の番号と対応しています。全体図はこちら

akuramochi1.com — personal tools for learning and thinking.