この記事では、商品資料・操作手順・FAQという3つの分類を選んで質問できる、小さなAI検索アプリを完成させます。
準備からCodexへの依頼、動作確認、失敗時の直し方まで、画面操作付きで一歩ずつ進みます。
この回のゴール
- できること：複数の資料を登録し、資料タイプ（商品資料／操作手順／FAQ）で絞ってRAG検索できる最小アプリを作る。
- 用意するもの：VS Code、OpenAIアカウント、Codex拡張、Node.jsまたはPythonの実行環境、Webブラウザ。
- 大切な約束：APIキーは環境変数で管理し、画面やコードに直書きしない。学習用の架空資料のみを使う。料金や仕様はOpenAI公式で確認する。
最初に知っておきたい用語
- RAG：質問に関係する資料を先に探し、その内容を見せてからAIが答える仕組み。
- File Search：OpenAIが提供する資料検索の道具。登録したファイルを意味でもキーワードでも探せる。
- ベクトルストア：資料を意味で探せるように並べて保存する場所。図書館の「索引」のような役目。
- Retrieval：必要な情報を資料から取り出す手順やAPIの考え方。
- Responses API：質問に対して、検索ツールなども使いながら回答を作るAPI。
- 環境変数：パソコン内に秘密をしまう引き出しのような設定。アプリの外から値を渡せる。
- フィルター：検索する範囲を「この条件だけ」にしぼる指定。例えば資料タイプ=FAQだけ、のように使う。
この記事でできること
シリーズ第4回の目的は、「複数の資料を分類して検索する」ことです。
前回（#3）で作った「参照元を表示する」機能はそのまま残し、今回は資料にタイプ属性を付け、選んだタイプだけを検索する仕組みを足します。
家の本棚を「漫画」「図鑑」「レシピ」に分けて探すと早いのと同じで、必要な棚だけを見るイメージです。
完成イメージ
- 画面に「質問欄」と「資料タイプ選択（商品資料／操作手順／FAQ）」がある。
- 選んだタイプに属する資料だけをFile Searchで探し、回答と参照元ファイル名を表示する。
- 学習用として端末ローカルで起動し、サーバーからResponses APIを呼び出す。
最初に知っておきたいこと
RAG（Retrieval-Augmented Generation）は、図書館の係が質問に合うページを探し、そのページを見ながら案内するような流れです。
実際には、AIがFile Searchで関連ページを拾い、その内容を参照して回答を作ります。
File SearchはOpenAIの検索ツールで、登録先としてベクトルストアを使います。ベクトルストアは資料を「意味」で近いもの同士に整理する棚です。
今回はこの棚に「タイプ」というラベル（属性）を付け、フィルターで棚の一部だけを調べます。料理のレシピ本からデザートだけを抜き出す感じです。
注意点として、File SearchやRAGは便利ですが、常に正しい答えを保証するものではありません。
モデル名、対応ファイル、上限、料金は変わり得ます。最新情報はOpenAIの公式ドキュメントとOpenAI Platformの画面で確認してください。
本記事は学習用で、匿名の一般公開は前提にしません。利用者ごとのデータ分離や厳密な権限管理は次回以降の話題です。
対象読者
- 1つのPDF対応アプリを、複数資料に拡張したい人。
- VS CodeとCodexをこれから使う人。
- 中高生・非エンジニアでもOK。
必要なものと入れ方
VS Code
- これは何？：ノートに下書きをまとめる机のようなアプリ。ファイルを並べて作業しやすくします。
- 用意するもの：パソコン、インターネット、Webブラウザ。
- 入れ方・開き方：公式サイト（https://code.visualstudio.com/）を開き、Windowsは「Download for Windows」、macOSは「Download for macOS」を押します。インストーラーの案内に従って進め、完了後にVS Codeを起動します。
- 最初の設定：左下の歯車→Settingsで日本語表示にしたい場合は拡張機能で「Japanese Language Pack」を検索して追加します。
- できたか確認：左上に「Explorer」、中央が空の編集エリア、左下に歯車アイコンが見えればOKです。
OpenAIアカウント
- これは何？：OpenAIのサービスを使うための会員証のようなもの。
- 用意するもの：メールアドレスとパスワード、または対応するログイン方法。
- 入れ方・開き方：OpenAI Platform（https://platform.openai.com/）を開き、Sign upまたはLog inを押して案内に従います。
- 最初の設定：ダッシュボードに入れたら、BillingやUsage画面で利用状況の確認方法を覚えておきます。
- できたか確認：右上にアカウント名が表示され、APIキーを作成できる状態なら準備完了です。
OpenAI Codex拡張（VS Code）
- これは何？：一緒に作業してくれるコーディングの相棒。指示文を渡すとコードや設定を作ってくれます。
- 用意するもの：VS CodeとOpenAIのアカウント。
- 入れ方・開き方：VS Code左の四角いアイコン「Extensions」を押し、検索欄に「Codex」と入力。OpenAIのCodex拡張を選び、「Install」を押します。
- 最初の設定：拡張の「Sign in」ボタンを押し、画面の案内でサインイン。サインイン後、左側や下部にCodexのチャット欄を開くボタンが現れます。
- できたか確認：「Codex」と書かれたチャット欄が開け、入力欄に文章を打てるならOKです。
Node.jsまたはPython
- これは何？：アプリを動かすためのエンジン。車のエンジンのように、コードを動かします。
- 用意するもの：インターネットと管理者権限。
- 入れ方・開き方：Node.jsは公式（https://nodejs.org/）からLTS版を入手。Pythonは公式（https://www.python.org/）から安定版を入手。インストーラーの指示に従います。
- 最初の設定：VS Codeで新しいフォルダを作り、開きます。以降の操作はこのフォルダ内で進めます。
- できたか確認：VS Codeのターミナルや出力パネルで、プロジェクトが起動したときにエラーが出なければOKです。
APIキーの安全管理
- これは何？：OpenAI APIを使う鍵。誰にも見せない合鍵です。
- 用意するもの：OpenAI Platformにログインできる状態。
- 入れ方・開き方：APIキーは環境変数で管理します。鍵の文字列をコードや画面に直書きしません。
- 最初の設定：環境変数から読み取る仕組みをCodexに実装してもらいます。
- できたか確認：アプリの画面やリポジトリに鍵の文字が見えないことを確認します。
エージェントと作るものの全体像
作るのは、ブラウザから質問できる小さなWebアプリ（またはシンプルなCLI）です。
流れは「ファイル登録→タイプ属性を付与→フィルターで検索→回答と参照元を表示」。
安全のため、アップロードできる拡張子と容量をサーバー側で制限し、Responses APIの呼び出しはサーバー側だけで行います。家の外（ブラウザ）に鍵（APIキー）を持ち出さない考え方です。
手順1: ツールを準備する
目的と流れ
VS CodeとCodexを使える状態にし、今回の作業フォルダを開きます。必要ならNode.jsかPythonのどちらかを選び、SDK導入はCodexに任せます。
画面操作
- VS Codeを起動し、左上のFile→Open Folderで新しい作業フォルダを選びます。
- 左のExtensionsで「Codex」を検索し、OpenAIのCodex拡張が入っているかを確認。未導入ならInstall、導入済みならEnable。
- Codexのチャット欄ボタンを押して開きます。
終えたら確認
- 作業フォルダ名がVS Codeの上部に表示される。
- Codexチャットに文字を入力できる。
手順2: APIキーを安全に用意する
目的
APIキーを環境変数に保存し、アプリから安全に読み取れるようにします。
画面操作
- OpenAI Platform（https://platform.openai.com/）にログインし、API Keysの画面を開きます。
- 新しいキーを作るときは、名前を付けて発行します。金額や制限は同画面やPricingから最新を確認してください。
- キーの値はその場でしか全体が見えない場合があります。画面を閉じる前に安全な場所に一時保存し、すぐに環境変数へ設定するようCodexに実装を依頼します。
終えたら確認
- コードやブラウザ画面にキーの文字列が出ていない。
- サーバー側からのみ参照できる。
手順3: エージェントにアプリを作ってもらう
目的
Codexに、複数資料をタイプで分類して検索できる最小アプリの作成を依頼します。Responses APIとFile Searchを使い、参照元のファイル名を表示します。前回（#3）の参照表示は壊さないよう明記します。今回は匿名公開を想定しません。
このボックスをコピーして、VS Code内のCodexチャットに送ります
Codexに送るプロンプト
目的：学習用の小さなWebアプリを、複数ファイルの分類検索に拡張してください。Responses APIとFile Searchを使い、資料タイプ別フィルター（type=product|manual|faq）で検索範囲を絞ります。前回（#3）の「回答に参照元ファイル名を表示する」機能は維持してください。
前提：
- VS Codeのこのフォルダで新規プロジェクトを作成。
- 言語はNode.jsまたはPythonのどちらでもOK。あなたが適切と考える方を提案し、理由をひと言で示してから作業を始めてください。
- OpenAI APIキーは環境変数から安全に読み込み、コード・HTML・ログに実値を出さないこと。dotenv等を使う場合は設定と.gitignoreを自動で用意。
- ブラウザ側は簡単なUI（質問入力欄＋資料タイプ選択：商品資料／操作手順／FAQ＋送信ボタン＋回答欄＋参照元一覧）。
- サーバー側でResponses APIを呼び、File Searchツールで検索。ブラウザへAPIキーや生レスポンス全体を送らない。
- アップロードは今回サンプルのみ（匿名公開なし）。将来のためにサーバー側で許可する拡張子（PDF/TXT/Markdown/DOCX）とサイズ上限のチェック関数だけ用意し、今は架空の少数サンプルをあなたが生成して登録する。
- ベクトルストアに登録する際、各ファイルにtype属性（product|manual|faq）を付与。登録・更新・同期の手順をスクリプト化。
- 検索時、UIで選んだタイプだけにフィルターをかけてFile Searchを実行。該当がなければ「登録した資料の中では確認できません」と返す。
- 回答には参照元として取得できたファイル名だけを表示（ページ番号やURLを作らない）。
- 料金やモデル名・上限は変わる可能性があるため、公式ドキュメント（RetrievalとFile Searchのガイド）を参照し、依存する定数は設定ファイルにまとめる。
- 実装前に不明点があれば、作業を始める前に私へ質問してください。
作ってほしいもの：
1) 最小構成のサーバーとフロント（CLIでもよいが、可能なら簡易Web UI）。
2) サンプル資料3種の自動生成スクリプト（商品資料/操作手順/FAQを各1～2本）。安全のため、実在の社名や個人情報は使わず、あなたが架空テキストを生成して登録する。
3) File Search用のベクトルストア作成・ファイル登録・type属性付与・同期スクリプト。
4) タイプ別フィルター検索＋Responses API連携のエンドポイント。
5) 参照元ファイル名の表示まで含むUI。
6) .env.sampleとREADME（起動方法、動作確認手順、注意点）。
動作確認：
- UIでタイプ=商品資料を選び、「価格は？」などの質問→商品資料だけから回答と参照元が出る。
- タイプ=操作手順を選び、「初期化の手順は？」→操作手順だけから回答と参照元が出る。
- タイプ=FAQを選び、「返品できる？」→FAQだけから回答と参照元が出る。
- 関連がない場合は「登録した資料の中では確認できません」を返す。
出力：
- 生成したファイル一覧、主要ファイルの説明、起動と停止の方法、テストの手順を最後にまとめて表示。
- 実装中に疑問があれば必ず質問してから進めること。Codexが作るものと、あなたが確認する点
- UIにタイプ選択があるか。
- File Searchへの登録スクリプトと、type属性が付いたか。
- 回答に参照元ファイル名が並ぶか（余計な推測をしない）。
- 環境変数の読み取りと.gitignoreが設定されているか。
手順4: 動かして確認する
起動方法
CodexがREADMEに書いた起動手順を実行します。ブラウザで指定のURLを開き、質問欄とタイプ選択が表示されれば成功への第一歩です。
チェックリスト
- タイプ=商品資料で「価格」「特徴」「型番」など→商品資料の参照元だけが出る。
- タイプ=操作手順で「初期化」「リセット」「組み立て」→操作手順の参照元だけが出る。
- タイプ=FAQで「返品」「保証」「問い合わせ」→FAQの参照元だけが出る。
- 関連なし→「登録した資料の中では確認できません」。
ログとデバッグ
- サーバーのログで、File Searchのフィルターがtype=選択値になっているかを確認。
- エラー時はCodexのチャットに症状を貼り、原因推定と修正提案を依頼。
手順5: エージェントと直す
ヒットしない時の改善
キーワードが少なすぎると見つからないことがあります。検索クエリのリライト（言い換え）や、分割サイズの調整をCodexに相談します。買い物で店員さんに「もう少し広い言い方」で聞き直すのと同じです。
誤答時の根拠表示
回答と一緒に、File Searchが返したファイル名を参照元として必ず表示。本文を画面に出す必要がある場合は、Responses APIの仕組みに沿ってCodexに実装させ、APIの生データをそのまま見せないようにします。
複数選択への拡張
タイプを複数選べるチェックボックスに変える拡張は、CodexにUI変更とフィルター条件（OR指定）の実装を依頼します。次へ進む前に、単一選択の動作が安定しているかを確認してください。
よくあるエラー
- APIキー未設定
見える症状：起動直後に認証エラー。
原因：環境変数が読めていない。
最初に見る場所：.envや環境設定、サーバー起動ログ。
Codexへの質問：「環境変数からAPIキーを読む設定を再確認し、ログに鍵を出さずに接続テストできる方法を教えて。」 - 権限・レート制限
見える症状：一時的な失敗や429/403など。
原因：呼び出し過多や権限不足。
最初に見る場所：OpenAI PlatformのUsage/Billing。
Codexへの質問：「429/403対策として再試行やバックオフ、上限超過時のユーザーメッセージを入れて。」 - ファイル形式・容量エラー
見える症状：登録スクリプトで失敗。
原因：許可外の拡張子や容量超過。
最初に見る場所：サーバー側の拡張子とサイズの検証コード、エラーメッセージ。
Codexへの質問：「許可拡張子と上限を設定ファイルへまとめ、エラー時の案内文を改善して。」 - フィルター構文ミス
見える症状：検索結果がゼロ、または全件。
原因：typeの指定名や演算子の誤り。
最初に見る場所：File Search呼び出し部分とログ。
Codexへの質問：「type属性フィルターの正しい指定例をガイドに沿って直して。」 - 索引未作成/同期漏れ
見える症状：古い内容が返る、登録直後に見つからない。
原因：ベクトルストアの同期待ちやスクリプト未実行。
最初に見る場所：登録・同期スクリプトの実行ログ。
Codexへの質問：「登録〜同期の順序と待機処理を追加し、完了の合図をログに出して。」
次に試すこと
- ユーザーごとの権限分離（概要）：匿名公開の前に、認証とデータ分離、容量・回数制限、削除機能を計画する。
- 埋め込みのカスタム設定：分割サイズや検索の重み付けを設定ファイルで調整できるようにする。
- 検索ログの簡易ダッシュボード：質問数、タイプ別ヒット率を可視化し、改善に役立てる。
まとめ
資料タイプで検索範囲をしぼると、ノイズが減って答えが見つかりやすくなります。
APIキーを環境変数で守り、参照元を表示する方針を続けることで、誤解を減らしながら学べます。
前回（#3）をまだ終えていない人は、シリーズの前回記事も参考にしてください：中学生にも分かる 自分の資料に答えるAI検索アプリの作り方 #3。
次は、より細かな管理や運用の工夫に進みます。
参考文献・公式情報
- OpenAI Retrieval guide：Retrievalの基本、ファイル入力、検索ワークフロー、ベストプラクティス。
- OpenAI File Search guide：File Searchの概念、インデックス、フィルタリング、検索対象の指定方法。
- OpenAI API safety best practices：APIキー保護、入力検証、レート制御、利用者データの扱い。
