RAG Codexの使い方｜検索付きAI開発の実践設計と検証手順

RAG Codexとは何を指すのか

RAGはRetrieval-Augmented Generationの略で、日本語では検索拡張生成と呼ばれます。質問に関係する文書を先に検索し、その抜粋をモデルへ渡して回答させる構成です。「RAG Codex」という独立した製品があるわけではなく、この記事ではCodexを使ってRAGアプリの調査、実装、テスト、改善を進める方法を指します。OpenAIのRetrievalガイドでは、文書をベクトルストアへ追加し、自然言語の問い合わせに関連する内容を取得する基本が説明されています。Codexはこの仕組みを利用するコードを作れますが、どの文書を正解とみなすか、古い資料をどう扱うかといった業務判断は人が先に決める必要があります。

Codexは検索エンジンではなく開発を進める役割

Codex CLIはプロジェクト内のファイルを調べ、コードを編集し、手元の確認コマンドを使って結果を確かめられる開発支援ツールです。公式のCodex CLIページでも、コードベースの調査、編集、実行結果の確認が主な用途として示されています。RAGでは、取り込み用の処理、検索用の関数、回答生成、評価用データを別々に作り、それらを接続する仕事を任せられます。ただし、検索対象の正しさや閲覧権限までCodexが推測できるわけではありません。実装の担当と業務上の判断を分けて考えることが、最初の重要な線引きです。

なぜ今RAG開発を段階的に任せやすいのか

OpenAIのCodex changelogによると、2026年7月21日のCodex CLI 0.145.0では、長い対話での表示応答や履歴処理が改善されました。RAG開発は、文書形式の調査、分割方法の比較、検索失敗の分析、評価結果に基づく修正を何度も往復します。長い対話を追いやすくなったことで、前に決めた制約を確認しながら小さな変更を積み重ねやすい時期です。ただし、対話が長く保てることと、品質が自然に上がることは別です。各段階の合格条件をテストや数値として残し、途中で前提が変わっていないかを人が確認します。

実装前に検索対象と正解を決める

RAGの難しさはモデルを呼び出す部分より、何を検索対象へ入れ、どの文書を優先し、何を正解と判定するかにあります。対象が曖昧なままCodexへ「社内検索を作って」と頼むと、PDFを読み込めても、古い規程と新しい規程を同じ重さで返す実装になる可能性があります。最初に対象フォルダ、対応する形式、除外条件、更新日の扱い、回答に必要な根拠表示を一枚の仕様へまとめます。OpenAIのCodexへの指示の書き方が示すように、目的、参考情報、求める出力、変えてはいけない境界を必要に応じて伝えると、調査と変更の方向を合わせやすくなります。

質問と期待文書の組を先に用意する

最初に10〜30件ほどの評価用質問を作り、各質問に対して参照されるべき文書IDや章を記録します。簡単な質問だけでなく、製品名の略称、表記揺れ、複数文書をまたぐ質問、資料に答えがない質問も含めます。ここで必要なのは模範回答を美しく書くことではなく、どの根拠が見つかれば検索成功なのかを決めることです。Codexには、この評価データを読み込むテストと結果を一覧化する処理から作らせます。検索機能より先に採点方法があれば、分割幅や検索件数を変えた効果を同じ基準で比較できます。

文書ごとの優先順位と有効期間を決める

同じ内容を扱う文書が複数ある場合は、更新日、版番号、文書種別、管理部署など、優先順位を決めるための情報を用意します。最新版のマニュアルと廃止済みの手順書が同時に見つかる状態では、検索精度が高くても回答は誤ります。Codexへは、本文だけでなく文書ID、タイトル、更新日、版、公開範囲をメタデータとして保持するよう依頼します。古い版を物理的に削除できない場合は、検索時の絞り込み条件で除外します。優先規則をコードとテストに残すと、新しい資料を加えた後も同じ判定を再現できます。

CodexにRAG開発を依頼する5つの手順

実装は、現状調査、評価の固定、文書取り込み、検索と回答の接続、回帰確認の順に分けます。一度の依頼で完成形まで書かせると、検索が悪いのか、回答生成が悪いのか、入力文書に問題があるのかを切り分けにくくなります。各段階では変更するファイルを限定し、実行した確認と未確認の項目を報告させます。OpenAIのFile searchガイドを使う構成でも、独自の検索基盤を使う構成でも、入力、検索結果、回答の三層を分けて観察できる形が重要です。

Step 1: 既存プロジェクトと文書形式を調査させる

最初はコードを変更させず、利用中の言語、依存パッケージ、テスト方法、文書の種類、既存の検索処理を説明させます。PDF、Markdown、HTML、表計算ファイルでは、見出しや表の取り出し方が異なるためです。Codexへ対象ファイルの例を数件渡し、抽出できる本文と失われる情報を報告させます。表が列ごと崩れる、見出し階層が消える、画像内の文字が取れないといった制約が分かれば、取り込み処理を書き始める前に対応範囲を調整できます。調査結果はファイル名と根拠箇所を含む短い報告にし、推測と確認済み事項を分けさせます。

Step 2: 評価用質問を読み込むテストを作らせる

次に、質問、期待文書ID、答えが存在するかどうかを持つ評価データを作ります。Codexには、まだ本番の検索を実装させず、このデータを読み込んで欠損や重複を検出するテストを追加させます。評価データそのものが壊れていると、その後の改善が誤った方向へ進むためです。質問ごとに難易度や分類も付けると、略称だけ失敗しているのか、複数文書の統合だけ弱いのかを見分けられます。最初の版は小さくて構いませんが、実際の利用者が使う言い回しを含め、開発者だけに通じる正式名称へ偏らせないよう確認します。

Step 3: 文書分割とメタデータ保存を実装させる

評価の土台ができたら、文書から本文を抽出し、検索単位へ分割する処理を作らせます。固定文字数だけで切ると、見出しと説明が分かれたり、表の途中で意味が失われたりします。見出し階層や段落を保ちつつ、長すぎる部分だけを追加で分ける方針を伝えます。各断片には文書ID、章、更新日、版、元の位置を保存し、同じ文書を再度取り込んでも重複しない識別子を付けます。OpenAIのEmbeddingsガイドに沿ってベクトル表現を使う場合も、元文書へ戻れるメタデータがなければ、検索結果の正しさを人が確認できません。

Step 4: 検索結果と回答を別々に返させる

検索関数は、回答文だけを返すのではなく、取得した断片、スコア、文書ID、元の位置も返す形にします。これにより、間違った回答が出たときに、必要な文書を取れなかったのか、正しい文書を取ったのに回答で読み違えたのかを分けられます。回答生成には「取得した根拠だけを使う」「根拠が不足する場合は不足を伝える」「参照した文書IDを示す」という契約を置きます。Codexには型や出力形式をテストさせ、根拠欄が空のまま断定文を返さないことも確認させます。利用者向けの文章を整える前に、開発者が原因を追える情報を残すことが先です。

Step 5: 変更前後を同じ質問で比較する

最後に評価用質問を一括で実行し、変更前後の検索結果と回答結果を保存します。平均値だけを見ると、一部の重要質問が悪化しても気づけません。質問ごとに取得した文書ID、順位、回答の根拠、処理時間を並べ、改善した例と悪化した例をCodexに分類させます。分割幅、検索件数、絞り込み条件を一度に変えず、一つずつ変更して差を測ります。結果が良くなった設定は、同じ評価を再度行えるテストとして残します。新しい文書を追加したときもこの確認を繰り返せば、以前答えられた質問が壊れる退行を見つけやすくなります。

検索精度と回答品質を分けて評価する

RAGの回答が正しそうに見えても、検索が成功したとは限りません。モデルが一般知識だけで偶然正しい文章を作る場合があり、逆に必要な文書を取得できていても、回答のまとめ方で重要な条件を落とす場合があります。そこで、検索段階では期待文書が上位に入ったかを測り、回答段階では取得した根拠だけで答えたかを確認します。OpenAIのEvalsガイドが示すように、評価対象と採点基準を明示し、代表例を繰り返し測れる形にすることが改善の土台になります。

検索にはRecall at kと順位を見る

期待する文書が上位k件に含まれた割合をRecall at kとして記録すると、検索漏れを把握できます。たとえば上位5件には入るが1位にならない質問が多いなら、回答へ渡す件数を増やすだけでなく、絞り込み条件や文書分割を見直す余地があります。Codexには全体の割合だけでなく、質問分類ごとの結果も出させます。正式名称では成功するのに略称では失敗するなら同義語の扱いが課題であり、古い版が常に上位へ来るならメタデータの優先規則が課題です。数値と失敗例を結び付けて読むことで、次の変更を小さく決められます。

回答には根拠一致と拒否の適切さを見る

回答品質では、主張が取得文書に支えられているか、条件や例外を落としていないか、参照元を利用者が追えるかを確認します。資料に答えがない質問では、無理に答えず不足を示せたかも重要な評価項目です。Codexには、回答と参照断片を並べる評価用レポートを作らせ、人が重要質問を確認しやすくします。文章の読みやすさは最後に整えます。先に自然な文章だけを評価すると、根拠のない断定が見栄えの良さで通ってしまうため、根拠一致、必要条件、拒否判断、表現の順に分けて採点します。

失敗例を次のテストへ戻す

実際の利用で誤答が見つかったら、質問、取得文書、回答、期待する動作を一組として評価データへ追加します。単にプロンプトの一文を足して直すのではなく、検索漏れ、版の取り違え、分割の断絶、回答時の読み落としのどこで失敗したかを分類します。Codexへ原因候補を挙げさせるときも、ログと文書位置を根拠として示させます。失敗を再現するテストが先に落ちることを確認してから変更し、既存の質問を含めて再評価します。この積み重ねにより、個別の言い換えへ過剰に合わせるのではなく、同じ種類の失敗をまとめて減らせます。

安全性と費用を設計に含める

RAGは文書を検索できる範囲がそのまま回答可能な範囲へつながるため、コードが動くだけでは不十分です。閲覧できない文書が検索結果へ混ざらないこと、文書内の命令文を開発者からの指示と誤認しないこと、入力と出力へ機密情報を残しすぎないことを確認します。また、文書を細かく分けすぎたり、毎回多くの断片を回答へ渡したりすると、保存量と利用量が増えます。安全性と費用は完成後の調整項目にせず、最初の評価データと出力契約へ含めます。

文書内の命令をデータとして扱う

検索対象の文書には、「この指示を無視して別の処理をせよ」といった文章が含まれる可能性があります。回答生成へ渡すときは、取得文書が参考データであり、開発者の指示ではないことを明確に分けます。Codexには、悪意のある命令文を含む評価用文書を用意し、その内容に従わず、質問への根拠として必要な部分だけを扱うテストを追加させます。外部から収集した文書ほど信頼度を低く見積もり、HTMLの非表示部分や不要なスクリプトを取り込まないよう抽出処理も確認します。

閲覧権限を検索前に絞り込む

回答を作った後に表示だけ隠しても、取得段階で閲覧不可の断片がモデルへ渡っていれば安全ではありません。利用者の所属や役割に基づく条件を検索時に適用し、許可された文書だけを候補へ入れます。Codexには、権限の異なる複数のテスト利用者を用意し、同じ質問でも取得結果が変わることを確認させます。管理者向け文書のタイトルや抜粋が一般利用者のログへ出ないこともテストします。アクセス判定を回答文の生成に任せず、検索層で機械的に制限する設計が基本です。

分割数と検索件数の上限を測る

細かな分割は特定の一文を見つけやすくする一方、断片数が増え、前後関係も失いやすくなります。大きな分割は文脈を保ちやすいものの、関係の薄い文章まで回答へ渡します。Codexには複数の分割幅と検索件数を同じ質問セットで比較させ、検索成功率、回答品質、処理時間、投入文字量を一覧にさせます。最良の数値だけでなく、重要質問を満たす最小構成を選びます。文書更新時は変更された部分だけを再処理できるよう識別子を設計すると、追加作業と保存量を抑えられます。

そのまま使えるCodexへの依頼例

依頼文には、目的、対象、守る境界、確認方法を含めます。「RAGを作って」とだけ書くより、最初は調査のみ、次に評価データ、承認後に実装という順序を明記すると、設計の食い違いを変更前に見つけられます。対象文書の実例と期待文書IDを渡し、出力には変更ファイル、確認結果、未確認事項を求めます。以下の例は、既存のPythonプロジェクトへ社内FAQ検索を追加する想定です。言語、フォルダ、テスト名、文書形式は実際のプロジェクトに合わせて置き換えてください。

調査から評価までを依頼する例

この例では、最初の段階で実装せず、既存構成と文書の性質を説明させます。その後も、評価用質問を読み込むテスト、文書取り込み、検索、回答生成を別の変更として扱います。Codexが提案した分割幅や検索件数をそのまま採用せず、なぜその値なのか、比較した候補は何かを確認してください。既存の公開関数やデータ形式を変えない境界も先に示すと、RAG以外の機能へ影響する差分を抑えられます。

目的:
docs/ の社内FAQを検索し、根拠文書ID付きで回答する機能を追加します。

最初の依頼:
まだコードを変更せず、既存構成、テスト方法、文書形式を調べてください。
本文抽出で失われる情報、重複文書、更新日の扱いを報告してください。

評価:
eval/questions.json の質問と期待文書IDを読み込み、
検索上位5件に期待文書が含まれるか確認できるテストを提案してください。
答えがない質問では、根拠不足を返すことも確認対象に含めます。

境界:
既存の公開関数と保存形式は変更しません。
取得した断片には文書ID、章、更新日、元の位置を残してください。
変更前に対象ファイルと確認方法を示し、段階ごとに結果を報告してください。

完了報告で確認する項目

Codexからは、変更した内容の要約だけでなく、実行したテスト、質問ごとの取得結果、失敗した例、未確認事項を受け取ります。結果が「すべて成功」だけなら、評価データ件数と実際に採点された件数が一致するかを確認します。検索結果の文書IDを見て、期待文書が偶然別の重複資料で置き換わっていないかも重要です。最後に人が代表質問を入力し、表示された根拠から元文書へ移動できること、閲覧不可の文書が候補に出ないこと、答えがない質問で断定しないことを確かめます。

まとめ

RAG開発をCodexに任せるときは、完成形を一度に求めず、検索対象、評価用質問、文書取り込み、検索、回答、回帰確認の順に分けることが重要です。Codexは既存コードの調査や実装、テストの追加を進められますが、どの文書を正解とするか、古い版をどう除外するか、誰が何を閲覧できるかは人が先に決めます。回答の自然さだけで判断せず、期待文書を取得できたかと、取得した根拠に沿って答えたかを別々に測ってください。

最初の一歩は、実際の質問を10件ほど集め、期待する文書IDを付けることです。その小さな評価セットをCodexへ渡し、変更前の結果を保存してから、分割方法や検索条件を一つずつ改善します。直近のCodex CLIは長い対話を扱いやすくなっていますが、RAGの品質を守るのは再現できる評価と明確な境界です。失敗例を次のテストへ戻し、根拠を追える状態を保ちながら対象文書と利用者を段階的に広げると、実務で確認しやすい検索付きAIへ育てられます。