この回では、架空のサンプルPDFをOpenAIのベクトルストアに登録し、Responses APIとFile Searchで探してから答える“最初の回答”をブラウザに表示します。
準備から安全なAPIキー管理、Codexへの依頼、動作確認、直し方までを順に進めます。
この回のゴール
- できること：PDFを1つ登録し、File Searchの根拠を使ってResponses APIが作る回答をブラウザに表示。
- 用意するもの：VS Code、OpenAI Codex、OpenAIアカウントとAPIキー、Node.js LTS、普段使うブラウザ。
- 大切な約束：APIキーやベクトルストアIDはサーバーだけで扱い、画面やコード例に実値を書かない。
最初に知っておきたい用語
- RAG：質問に答える前に、関連する資料を探してから文章を作る仕組み。
- File Search：OpenAIが用意する資料検索の道具。登録先としてベクトルストアを使う。
- ベクトルストア：資料を“意味”で探せるように整理して置く保管場所。
- Responses API：見つけた資料の断片を根拠に、回答文を作るAPI。
- APIキー：サービスを使うための秘密の鍵。人目に出さない。
- VS Code：コードを書く編集アプリ。拡張機能で機能を足せる。
- Codex：VS Code内でコード作成を手伝うAI。日本語で依頼できる。
1. この記事でできること
この回では、1つのPDFを登録して、File Searchで根拠を取り出し、Responses APIで作った回答をブラウザに表示します。
たとえるなら、1冊のノートにしおりを付け、質問に合うページを開いて、その内容を見ながら説明する流れです。技術的には、PDF→ベクトルストア→検索→回答生成→表示を最短距離で通します。
- PDFを1つ登録し、File Searchで根拠を引いて最初の回答を画面に表示
- Codexに指示して最小アプリを自動生成
- 安全なAPIキー管理（環境変数）とサーバー側保護
2. 完成イメージ
完成後は、机の上に「質問メモ」「答えの紙」「参照したページの付せん」を並べるイメージです。アプリでは次のように見えます。
- ブラウザに質問欄と回答欄
- 回答の下に「根拠（PDFの該当ページ/抜粋）」と「処理中/利用可能」の表示
- 1ファイル・1ストア・最初の質問に答えるミニRAG
3. 最初に知っておきたいこと
ベクトルストアは、本棚のしおりの束のようなものです。似た内容を素早く見つけます。正確には、文章を数の並び（ベクトル）に変えて、近い意味を探す仕組みです。
File Searchは、PDFから必要な部分を探す係。Responses APIは、見つけた根拠を元に文章を作る係です。
APIキーは金庫の鍵。コードや画面に直接置かず、サーバーの環境変数だけで使います。料金・対応モデル・上限は変わる可能性があるため、OpenAIの公式ドキュメントとPlatformの画面で都度確認してください（本記事末の出典参照）。
4. 対象読者
RAGの準備を終え、まず1つのPDFで動く形にしたい人向けです。VS CodeでCodexを試したい初心者を想定し、約60分で到達を目指します。
前回の準備がまだの人は、こちらを先に読んでください：中学生にも分かる 自分の資料に答えるAI検索アプリの作り方 #1。
5. 必要なものと入れ方
ここでは、今回使う道具を、何のためか→用意するもの→入れ方→最初の設定→できたか確認、の順で説明します。家に新しい家電を置くときに、場所と配線を決めて電源を入れるのと同じ流れです。
VS Code
- これは何？：ノートと鉛筆が一つになった作業机。ファイルを並べて編集できます。
- 用意するもの：インターネット接続、Windows/macOSのPC、メールで受け取れるアカウント。
- 入れ方・開き方：公式のダウンロードページからインストールし、案内に従って起動します。
- 最初の設定：日本語表示やテーマは好みでOK。作業用の空フォルダを1つ作り、VS Codeで「フォルダを開く」を選びます。
- できたか確認：「エクスプローラー」に開いたフォルダ名が表示され、左右に編集画面が見えればOK。
OpenAI Codex（VS Code拡張）
- これは何？：隣で相談に乗ってコードを書いてくれる家庭教師。
- 用意するもの：ブラウザ、OpenAIアカウント（ChatGPTアカウントでも可）、サインイン用のメール。
- 入れ方・開き方：
- VS Code左側の四角いアイコン「拡張機能」を開く。
- 検索欄に「Codex」と入力する。
- OpenAIのCodex拡張を選び、「インストール」を押す。
- 画面の案内に従ってサインインする。
- 左側または下部に現れる「Codex」のチャット欄を開く。
- 最初の設定：作業フォルダを開いた状態で、Codexの設定に「対象フォルダ」が合っているか確認します。
- できたか確認：チャット欄に「こんにちは」と送って、応答が返れば有効です。
OpenAI Platform（Responses API＋File Search）
- これは何？：AIに質問して答えを作るキッチンと、材料の棚（ベクトルストア）。
- 用意するもの：OpenAIアカウント、APIキー。
- 入れ方・開き方：ブラウザでアカウントにサインインし、必要に応じてAPIキーを発行します（発行手順は出典「OpenAI API keys」を参照）。
- 最初の設定：料金・モデル・上限は必ずPlatformの画面で最新を確認。利用には費用が発生する場合があります。
- できたか確認：APIキーが作成され、控えを安全に保存できていれば準備完了。
Node.js LTS
- これは何？：アプリを手元で動かすコンロ。サーバーの動作に使います。
- 用意するもの：Windows/macOSに合うインストーラーを公式から入手。
- 入れ方・開き方：インストーラーの案内に従ってインストールし、VS Codeの統合ターミナルを開けることを確認します。
- 最初の設定：特になし。プロジェクト作成はCodexに任せます。
- できたか確認：VS CodeのターミナルにNode.jsとnpmのバージョンが表示されればOK（表示方法はCodexに聞きます）。
ブラウザ
- これは何？：出来上がった料理を盛り付けて見るお皿。アプリの画面を開きます。
- 用意するもの：普段使っているChrome/Edge/Safari等。
- 入れ方・開き方：特になし。後でURLを開きます。
- 最初の設定：ポップアップブロックや拡張は今回は不要です。
- できたか確認：URLを開いて画面が表示されればOK。
6. エージェントと作るものの全体像
家の間取りを先に決めると片付けやすいのと同じで、構成を先に共有します。
- 構成：フロント（質問UI）／サーバー（APIキー保護・ベクトルストア作成）
- データ流れ：PDF→ベクトルストア→検索（File Search）→回答生成（Responses API）→表示
- 秘匿情報：APIキー・ベクトルストアIDはサーバーにのみ保持。ブラウザへは返さない。
7. 手順1: ツールを準備する
目的と流れ
作業机（VS Code）と家庭教師（Codex）を使える状態にします。ここが整うと、以降はプロンプト中心で進められます。
読者が行う操作
- VS Codeを開く。
- 拡張機能で「Codex」を検索し、OpenAIのCodex拡張をインストール。
- 指示に従ってサインインし、Codexのチャット欄を開く。
- Node.jsが使えるかは、後でCodexに確認方法を聞きます。
終えたら確認
- Codexに挨拶して応答が返る。
- 作業用フォルダがVS Codeで開けている。
つまずいたら
拡張が見つからない、応答がない場合は、ネット接続やサインイン状態を見直し、Codexのエラーメッセージを確認してください。
8. 手順2: APIキーを安全に用意する
目的と流れ
APIキーをサーバーだけで読めるようにします。合い鍵を家の外に置かないのと同じ考え方です。
読者が行う操作
- OpenAIのAPIキー発行手順を開き、キーを作成します（出典「OpenAI API keys」を参照）。
- キーは画面で一度しか見られないことがあるので、安全な場所へ控えます。
Codexに頼むこと
.envに保存し、gitignoreで保護し、サーバー側だけで読み込む設計を実装するよう後の手順で依頼します。フロントへは送らない方針です。
終えたら確認
- 実際のキー文字列をアプリやチャットに貼らない。
- 後でCodexが環境変数から読むコードを書く前提にできる。
9. 手順3: エージェントにアプリを作ってもらう
ここからが本番。Codexに、今回の回だけの要件をまとめて依頼します。家づくりの設計図を手渡すイメージです。下のボックスをコピーして、VS Code内のCodexチャットに送ります。
Codexに送るプロンプト
今回の回「#2: PDFを登録して最初の質問に答える」の最小アプリを、前回の構成を壊さずに作ってください。次を満たしてください。
- 目的：架空のサンプルPDFを1つサーバー側で自動生成し、OpenAIのベクトルストアに登録。Responses API＋File Searchで検索して根拠付きの“最初の回答”をブラウザに表示。
- 技術：Node.js（Express 等）でサーバー、フロントはシンプルなHTML/JS。OpenAI公式SDKを使い、Responses APIのtoolsでFile Searchを有効化。Assistants APIは使わず、Responses APIを主実装にする。
- 安全：APIキーとベクトルストアIDはサーバーの環境変数で管理。.envに保存し、gitignoreで保護。ブラウザへ返さない。APIの生レスポンスやキーを画面に出さない。
- サンプルPDF：サーバー起動時または初回アクセス時に、サンプル内容（会社名や個人情報に依らない架空の文章）でPDFを自動生成し、ベクトルストアに登録。登録が「処理中」「利用可能」を判別できる状態管理を実装。
- エンドポイント：
1) /api/status ベクトルストアの状態（未作成/処理中/利用可能）を返す（秘密情報は返さない）。
2) /api/ask 質問文字列を受け取り、Responses API＋File Searchで回答を生成。回答文と引用のメタ情報（File Searchが返す参照ファイル名等）だけを返す。根拠本文の扱いは公式ガイドに従い、過度な生データを返さない。
- フロント：
- 入力欄、送信ボタン、回答欄、「処理中/利用可能」の表示。「最初の回答」までの最小UI。
- 回答の下に参照元（File Searchが返すファイル名）を一覧表示。ページ番号などAPIが返さない情報は推測で作らない。
- モデル・上限：固定値にせず、設定ファイルで変更できるように。最新版はOpenAI公式ドキュメントで確認する注記をコードコメントに。
- 依頼：必要なファイル一覧、実装手順、起動・確認方法、失敗時のチェックリストをREADMEにまとめる。ユーザーに手入力のコマンドやIDを求めず、VS Codeのタスクやnpm scriptを用意。疑問点があれば作業前に質問してから進めてください。Codexが作るものと、あなたが確認する点：
- サーバーとフロントの最小構成が生成される。
- .envの読み込みとgitignoreの設定が含まれる（APIキーは自分で入れる。実値は貼らない）。
- サンプルPDFの自動生成と、ベクトルストア登録→処理中→利用可能の状態が見える。
- 質問→回答→参照元（ファイル名）の表示ができる。
10. 手順4: 動かして確認する
目的と流れ
アプリを起動し、PDF登録の完了を待ってから質問して、根拠付きの最初の回答を表示します。炊飯器の「炊飯中」から「保温」に変わるのを待ってよそう感覚です。
読者が行う操作
- Codexの指示に従い、用意されたタスクやスクリプトでアプリを起動。
- ブラウザでフロントのURLを開く。
- 画面の状態表示が「処理中」から「利用可能」になったことを確認。
- 質問を1つ入力して送信。「回答」と「参照元（ファイル名）」が表示されるか確認。
ログの見方
CodexがREADMEに書いた「起動ログで見るべき行」を参考に、ベクトルストア作成・ファイル登録・索引化完了の順でメッセージを確認します。
終えたら確認
- 最初の回答が、登録PDFに基づいていると分かる。
- APIキーやベクトルストアIDがブラウザに露出していない（ネットワークタブにも出ない）。
11. 手順5: エージェントと直す
目的と流れ
回答が浅い、遅い、根拠が足りない場合に、Codexへ改善を依頼します。料理の塩加減を少しずつ調整するイメージです。
追加プロンプト例
- 「回答に『登録資料内で確認できない場合はそう書く』ルールを厳守して。」
- 「File Searchの検索件数kとスコア閾値を設定できるようにして。根拠が弱いときはkを増やす提案も。」
- 「UIに『参照元が空のときは“資料内では未確認”と表示』を追加して。」
- 「タイムアウトとリトライの設定をREADMEに追記して。」
12. よくあるエラー
- 症状：画面に「APIキーが無効」や401/403エラー。
原因：APIキー未設定・権限不足。
最初に確認：サーバーの環境変数の読み込み、.envのファイル名・場所、gitignoreでコミットしていないか。
Codexへの質問：「サーバーが環境変数からOpenAIのキーを読み取れているかログで確認するコードを追加して。」 - 症状：「ファイル処理中」のまま進まない。
原因：索引化に時間がかかっている、登録手順の抜け、モデルや上限の不一致。
最初に確認：/api/statusの返り値、サーバーログ、公式ガイドの手順。
Codexへの質問：「File Searchの処理完了をポーリングで待つ関数と、タイムアウト時の案内を追加して。」 - 症状：ブラウザでCORSエラーやポート競合。
原因：フロントとサーバーのポート設定の衝突、CORS未設定。
最初に確認：READMEの起動URL、サーバーのCORS設定。
Codexへの質問：「ローカル開発用にCORSを最小権限で許可し、競合ポートを自動で空き番号に変える設定を入れて。」 - 症状：参照元が空で、回答だけが出る。
原因：File Searchの有効化漏れ、返却データの取り出し方の誤り。
最初に確認：Responses API呼び出し時にtoolsでFile Searchが指定されているか、返信に含まれる参照メタ情報のパス。
Codexへの質問：「Responses APIのFile Search結果からファイル名だけを安全に取り出し、UIに表示する処理を見直して。」 - 症状：ベクトルストアIDの扱いミス。
原因：IDをフロントへ返してしまう、または保存場所が不適切。
最初に確認：サーバーの環境変数と安全な保管方法。
Codexへの質問：「ベクトルストアIDをサーバーだけで保持し、フロントに出さない設計になっているか点検して。」
13. 次に試すこと
- PDFを2つに増やす前に、今の品質を測る（同じ質問を言い換えても似た結果か）。
- 簡単な評価プロンプトで再現性を確認。
- 回答に引用（citation）番号を付けるUIを検討。
14. まとめ
最小構成で、根拠付きの“最初の回答”まで到達しました。ここまでの設計は、安全に拡張できます。次回以降は、登録や表示の精度と体験を少しずつ育てます。
次は、より丁寧な参照表示や操作性を整える回へ進みます。
