中学生にも分かる 自分の資料に答えるAI検索アプリの作り方 #3

今回は、回答の横に参照元ファイル名だけを安全に表示する最小アプリを、VS CodeのOpenAI Codexと一緒に完成させます。

準備から、APIキーの安全な扱い、Codexへの依頼、動作確認、直し方までを一歩ずつ説明します。

この記事でできること

前回までで、登録した資料を使って答えが返るところまで進みました。今回は「根拠の表示」を足します。
図書館で本を紹介するとき、ただ答えるだけでなく「この本に載っていました」と本のタイトルを示すと安心できます。アプリでも同じで、回答の根拠になったファイル名を並べて表示します。

• File Searchの引用情報から、実在するファイル名だけを取り出す。
• 回答テキストの横に、参照元ファイル名の一覧を表示する。
• UIは最小構成で、読みやすさと安全性を優先する。

完成イメージ

• 質問→回答テキスト→参照元: sample.pdf, faq.docx のように並んで表示。
• 参照元はAPIが返した実在ファイル名のみ。ページ番号やURL、引用文の推測表示はしない。
• 回答と参照元を見比べ、人が「合っているか」を確認できる。

最初に知っておきたいこと

たとえ話：図書館の貸出票のように、「どの本を使ったか」だけが記録されます。ページ番号のメモがないときに、適当にページを作ってはいけません。
本文での意味：Responses APIでFile Searchを使うと、回答と一緒に引用メタが返ります。ここからファイルIDやファイル名を参照元として表示します。表示は「実在するファイル名」に限ります。
作らないもの：URL推測、ページ番号の捏造、本文のコピペはしません。APIが返していない情報は作らないのが安全です。

対象読者

• RAG入門者
• 社内資料の根拠を示したい人
• VS Code初心者

必要なものと入れ方

ここでいう「道具」は、アプリを作るためのソフトやアカウントのことです。台所でいう包丁や鍋にあたります。順番に揃えます。料金やレート、モデルや機能名は変わることがあります。最新の情報はOpenAIの公式ドキュメントと、Platformの画面で必ず確認してください（Responses API、File Search）。

VS Code

1. これは何？：文章やプログラムを書くノートのようなアプリ。いろいろな道具（拡張）を足せます。
2. 用意するもの：PC、インターネット、メールが受け取れるアカウント。
3. 入れ方・開き方：公式サイトからダウンロードし、案内に沿って入れ、アプリを開きます。
4. 最初の設定：日本語表示やテーマは好みでOK。作業用の空フォルダを1つ作り、VS Codeでそのフォルダを開きます。
5. できたか確認：「エクスプローラー」に空のフォルダ名が見えれば準備完了です。

OpenAI Codex（VS Code拡張）

1. これは何？：となりで助言するコーチのように、必要なコードを提案・作成してくれる相棒です。
2. 用意するもの：OpenAIアカウント。ブラウザでサインインできる状態。
3. 入れ方・開き方：
   • VS Code左側の四角いアイコン（拡張機能）を押す。
   • 検索窓に「Codex」と入力する。
   • OpenAIのCodex拡張を選び、「インストール」を押す。
   • 画面の案内に従ってサインインする。
   • サイドバーにCodexのチャット欄が出たら開く。
4. 最初の設定：組織やAPI利用の同意画面が出たら案内に従います。
5. できたか確認：チャット欄に「こんにちは」と送って応答が返れば準備OKです。

OpenAIアカウントとPlatform

1. これは何？：APIを使うための会員証と管理画面です。
2. 用意するもの：メールアドレス、支払い方法（必要に応じて）。
3. 入れ方・開き方：ブラウザでOpenAIにサインインし、Platformのダッシュボードを開きます。
4. 最初の設定：APIキーの作成は後で行います。料金やレート制限の画面に一度目を通します。
5. できたか確認：ダッシュボードにアクセスでき、ドキュメントが読めればOK。

Node.js（サーバー実行用）

1. これは何？：PCの上で小さなサーバーを動かすためのエンジンです。家の電源のような存在。
2. 用意するもの：インストーラーをダウンロードできる環境。
3. 入れ方・開き方：公式の案内に従ってインストールし、VS Codeからプロジェクトを開きます。
4. 最初の設定：Codexに依頼して、必要な設定ファイルを作ってもらいます。
5. できたか確認：後の手順でサーバーが起動すれば成功です。

料金とレートの確認先：機能や価格は変わることがあります。必ず公式ドキュメント（Responses API、File Search、Retrieval）で現在の条件を確認してください。

エージェントと作るものの全体像

今回作る最小アプリは、フロント（HTML/CSS/JSでもOK）＋簡単なサーバー（Node.js/Express想定）です。
Responses APIでfile_searchを有効化して質問を送り、返ってきた引用情報から「実在するファイル名のみ」を取り出し、回答の横に表示します。
たとえ話：配達（サーバー）が倉庫（ベクトルストア）に取寄せを依頼し、伝票（引用メタ）に書かれた仕入先名（ファイル名）をレシートに印字する、という流れです。

手順1: ツールを準備する

1-1 目的と流れ

VS Code、Codex拡張、OpenAIアカウントを準備し、Codexに話しかけられる状態にします。ここでつまずくと先へ進めません。

1-2 画面での操作

• VS Codeを開く→作業用の空フォルダを開く。
• 拡張機能→「Codex」を検索→OpenAIのCodex拡張→「インストール」。
• 案内に従いサインイン→Codexチャットを開く。

1-3 成功の目印

• Codexのチャット欄が表示される。
• あいさつへの返事が返る。

1-4 困ったら

拡張機能に「有効」「インストール済み」と出ているか確認。サインインのやり直しを試します。

手順2: APIキーを安全に用意する

2-1 目的

APIキーは環境変数（.env）で管理し、コードや画面に直書きしません。家の鍵を玄関に貼らないのと同じです。

2-2 Codexに任せる作業

.envを作る、.gitignoreで.envを除外する、サーバーが起動時に環境変数を読み込む設定を、Codexに依頼して実装してもらいます。

2-3 成功の目印

• Codexが.envの場所と読み込み方法を説明してくれる。
• .envの中身はあなた自身では表示しない（実値は書かない）。

2-4 うまくいかないとき

環境変数が読み込まれていない表示が出たら、.envのファイル名や配置場所、読み込みタイミングをCodexに確認します。

手順3: エージェントにアプリを作ってもらう

3-1 目的

最小の検索アプリをプロンプトだけで共同制作します。依存関係、API呼び出し、file_search設定、引用抽出、UIまでを頼みます。

3-2 このボックスをコピーして送る

このボックスをコピーして、VS Code内のCodexチャットに送ります。

目的：前回までのRAG最小アプリに「回答の参照元（実在するファイル名のみ）の表示」を追加してください。
必須条件：
- サーバーはNode.js/Expressの最小構成。フロントはシンプルなHTML/CSS/JSでOK。
- OpenAI Responses APIを使用。toolsでfile_searchを有効化。
- File Searchの引用情報から、実在するファイル名のみを抽出して配列で返し、UIに表示。
- APIキーは環境変数（.env）で管理。ブラウザにキー・モデル設定・生レスポンスを送らない。
- ベクトルストアやファイル登録は既存の練習用サンプル（個人情報や社外秘を含まないダミー）で進める。
- .gitignoreで.envを除外。サンプルのseedは安全なダミーを自動生成。
- エラーハンドリング（認証/レート/タイムアウト）とユーザー向けメッセージを実装。
- 前回の機能は壊さない（質問→回答が返ること）。
- 成功時に返すJSONは { answer: string, sources: string[] } の形で、sourcesは“実在ファイル名のみ”。
- APIが返していないページ番号・URL・引用文は表示しない。捏造しない。
- 「登録資料に根拠が見つからない」場合は、その旨を回答に明記して一般知識で補わない。
- 動作確認の手順（起動→テスト質問→レスポンス内の引用位置→UI反映）をREADMEに書く。
- 依存関係の追加、環境変数の説明、起動・停止方法はすべてREADMEにまとめる。
- 作業前に不明点があれば、私に日本語で質問してから着手する。
出力：
- 必要なファイル一覧と役割、各ファイルの中身、README、簡単なスタイル。
- Responses APIでfile_searchを使う際のモデル指定は、私に確認してから暫定の書き方にしておく。
確認観点：
- UIで回答の横に参照元ファイル名のリストが出る。
- sources配列は重複を取り除き、実在ファイル名のみ。
- APIキーやID類はサーバー側でのみ参照。ブラウザへ出さない。

3-3 Codexが作るものと確認点

• サーバーのエンドポイントが、answerとsources（ファイル名のみ）を返す。
• フロントの画面に、回答と参照元リストが並ぶ。
• READMEに起動とテスト手順、トラブル時の見方が書かれる。

手順4: 動かして確認する

4-1 目的

アプリを起動し、テスト質問で回答と参照元が表示されるかを確かめます。料理の味見にあたります。

4-2 画面での操作

• Codexの案内に従って起動。
• ブラウザでアプリを開き、短い質問を入力して送信。

4-3 どこに引用が入っているか

Responses APIのレスポンスJSON内に、File Searchの引用情報が入ります。モデルや構造は変わる可能性があるため、実際のレスポンスで「どの配列（またはメタ）にファイルIDやファイル名があるか」をCodexと一緒に確認し、UIに渡します。詳細は公式のFile SearchガイドとResponses APIで最新を確認してください。

4-4 成功の目印

• 回答が表示される。
• 参照元として、実在するファイル名が1つ以上並ぶ。
• ページ番号やURLが勝手に付かない。

4-5 うまくいかないとき

画面に何も出ない、sourcesが空などの場合は、Codexに「レスポンスの引用部分のパス」と「抽出処理のログ出力」を追加するよう依頼します。

手順5: エージェントと直す

5-1 症状別の直し方

• 参照元が出ない：File Searchが無効か、インデックス未完了かもしれません。Codexに診断ログ出力を追加依頼。
• 参照元が多すぎ：重複除去や上限数の設定を依頼。重要度順に並べます。
• UIを見やすく：回答と参照元を左右に分ける・改行・見出し追加を依頼。

5-2 人が確認するフロー

少数の質問でテストします。答えられる質問、言い換えた質問、資料にない質問、内容が食い違う質問を用意し、回答と参照元を見比べます。「登録した資料の中では確認できません」と返るケースも期待どおりか確認します。

よくあるエラー

• 認証エラー（401/403）
  画面で見えること：エラー表示やログにUnauthorized。
  原因：APIキーが無効、環境変数未読。
  最初に確認：.envの配置と読み込み。
  Codexへの質問：「サーバーの環境変数の読込確認ログと、キー未設定時のガードを追加して」
• 権限やレート制限（429）
  画面：しばらくして再試行の案内。
  原因：呼び出し頻度が多い。
  確認：待ち時間と再試行、バックオフ。
  質問：「429時の再試行ポリシーとユーザー向けメッセージを実装して」
• ファイル未インデックス・引用配列が空
  画面：sourcesが空。
  原因：File Searchが対象を見つけていない。
  確認：File登録とインデックス状態。
  質問：「File Searchの結果や引用メタの実際の構造をログに出し、見つからない理由を表示して」
• JSON構造の想定違い
  画面：抽出で例外。
  原因：レスポンス構造の変更やモデル差。
  確認：実際のレスポンスをコンソールに整形表示（機密は伏せる）。
  質問：「現行のResponses APIで引用メタの正しいパスを検出し、抽出関数を防御的に直して」
• CORSエラー
  画面：ブラウザでブロック。
  原因：サーバー側の許可設定なし。
  確認：サーバーのCORS設定を限定的に許可。
  質問：「開発環境限定でCORSを許可し、本番は閉じる設定を追加して」

次に試すこと

• 参照元クリックでモーダルに要約表示（引用文の捏造はしない）。
• 質問・回答・参照元のログを保存し、監査用にエクスポート。

まとめ

この回で、回答と一緒に「実在するファイル名だけ」を安全に表示する基本ができました。ここからは精度の検証と、人が確認する運用手順を整えましょう。なお料金や仕様は変わるため、最新は公式ドキュメントで必ず確認してください。
前回の準備がまだなら、先に中学生にも分かる 自分の資料に答えるAI検索アプリの作り方 #2を終えてから戻ってきてください。

関連記事

AIを読む人から使う人へ：CodexでChatGPT APIアプリを育てる #3（UI追加・ログ保存・使いやすさ改善）

AIを読む人から使う人へ：中学生にも分かるAI画像を使った商品プレビュー生成の考え方 #5

AIを読む人から使う人へ：中学生にも分かるCodexでChatGPT APIアプリを修正する #4

AIを読む人から使う人へ：中学生にも分かるGoogleカレンダー連携AIアプリの考え方 #4