pguso/rag-from-scratch レビュー: ローカルLLMでRAGの内部構造を組み立てる教材
Demystify RAG by building it from scratch. Local LLMs, no black boxes - real understanding of embeddings, vector search, retrieval, and context-augmented generation.
ひと目でわかる
- これは何？
- RAGをクラウドAPIやフレームワークに隠さず、埋め込み・ベクトル検索・再ランキングまでをJavaScriptで順に実装する教育リポジトリ。採用判断の観点から、向く読者と向かない読者を切り分ける。
- 誰に向いている？
- RAGの各段階を自分の手で書き、ベクトル検索やRRFの挙動を確認したい開発者には向く。逆に、本番品質の検索基盤や運用機能をすぐ必要とするチームには向かない。
- 商用利用できる？
- できます。MIT は寛容なライセンスで、著作権表示とライセンス表示を残せば、使用・改変・販売が可能です。
- 今もメンテナンスされている？
- 活動が鈍っています。最後のコミットは 6 か月前です。
- 何の言語で書かれている？
- 主に JavaScript です（GitHub の言語統計による）。
回答はプロジェクトの GitHub データ（最終同期：2026年9月15日）と当サイトの分析に基づくもので、法的助言ではありません。
オープンソース詳細解説
ブラックボックスを避けたい開発者向けの教材という位置づけ
このリポジトリが解こうとしている問題は、RAGの動作を説明できるようになることではなく、自分で組み立てられるようになることだ。READMEは「No black boxes. No cloud APIs.」と明言しており、埋め込みの生成からベクトル検索、検索結果の再ランキングまでを、外部のマネージドサービスに委ねずに書く方針を取っている。対象読者は、LangChainなどの抽象化レイヤーを使ったことはあるが、中で何が起きているか説明できないJavaScript開発者だ。トピックに educational と tutorial が並んでいることからも、ライブラリとしての利用ではなく読解と写経を前提とした構成だと分かる。姉妹プロジェクトとして pguso/ai-agents-from-scratch が挙げられ、同じ思想、つまり最小限で説明の行き届いた実コードで高度なAI概念を扱うという方針を共有している。
10段階のパイプラインをexample.js単位で分割する構成
READMEが示すパイプラインは、知識要件の定義、データ読み込み、チャンク分割、埋め込み、ベクトルストア、検索、検索後の再ランキング、クエリ前処理と埋め込み正規化、拡張、生成という10段階だ。これに対し、examples/ 以下に番号付きのディレクトリが並ぶ。各ディレクトリは example.js、CODE.md、CONCEPT.md の三点セットで構成され、コードと解説と概念説明が分離されている。注目したいのは番号の飛び方で、00_how_rag_works の次が 02_data_loading、その次が 03_text_splitting_and_chunking となっており、01が存在しない。また 04_intro_to_embeddings は配下に 02_generate_embeddings というサブディレクトリを持つ入れ子構造で、05_building_vector_store も 01_in_memory_store を挟む。学習パスの番号とディレクトリ番号が一致していない点は、順に追う読者にとって紛らわしい。READMEの見出し番号も 5 の次が 7 に飛んでおり、6 に対応する章が省略されている。教材としては各段階が独立して読めることを優先した結果だろうが、初見では迷う。
70行から始めて検索戦略まで積み上げる学習順序
最初の 00_how_rag_works は、retrieval、generation、context injection、similarity search という要素を70行未満で通す。ここで全体像を掴ませ、以降の章で各要素を分解していく設計だ。02_data_loading でファイル入出力と前処理、03_text_splitting_and_chunking でチャンクの重複と境界の扱い、04_intro_to_embeddings でベクトル表現と類似度、05_building_vector_store でインメモリの最近傍探索を扱う。06_retrieval_strategies はさらに4つに分かれ、01_basic_retrieval でtop-k検索とスコアリング、02_query_preprocessing でストップワード除去や正規化、03_hybrid_search でBM25と埋め込みの重み付き統合、04_multi_query_retrieval でクエリ分解と並列検索、RRFや重み付き融合、重複排除を扱う。単純な類似度検索から始めて、なぜそれだけでは足りないのかを順に体験させる構成になっている。01_basic_retrieval には showcase.js が用意され、そこまでの内容をまとめて動かせるようだ。
node-llama-cpp によるローカル実行とセットアップの勘所
実行基盤は node-llama-cpp で、トピックにも明示されている。クラウドAPIを使わないという方針は、この依存によって成立している。READMEには具体的なインストールコマンドや設定キーの記載が含まれていないため、実際の手順は各 example.js と CODE.md を読む必要がある。ここは採用判断の前に必ず確認したい点だ。ローカル実行はモデルファイルの入手と配置が前提になり、GGUF形式のモデルをどこから取得するか、どのサイズを選ぶかは環境のメモリ量に直結する。埋め込み生成用のモデルと生成用のLLMで別々のファイルが必要になる可能性が高く、初回はダウンロードとロードに時間がかかる。GPUを使わない場合はなおさらだ。READMEが「No cloud APIs」と書いている以上、ネットワーク越しの推論は想定されていない。手元のマシンで動かす前提が満たせないなら、この教材の中心的な価値は得られない。
後半の再ランキングと生成に関する記述の薄さ
パイプラインの7番と9番、10番にあたる再ランキング、拡張、生成については、READMEの学習パスに独立した章が見当たらない。提供された範囲では、06_retrieval_strategies の4章までが明示されており、その後の記述は途切れている。再ランキングは検索精度に効く工程であり、クエリ前処理や埋め込み正規化と並んでREADMEの概念一覧には挙げられているものの、対応するexampleのパスが確認できない。同様に生成段階についても、00_how_rag_works で最小例に触れられている以外の説明は読み取れない。これはリポジトリの欠落を意味するのではなく、提供されたREADMEが途中で切れているためだ。採用を検討する立場では、リポジトリを直接開いて examples/ の実際のディレクトリ一覧を確認し、再ランキングと生成の章が存在するかどうかを確かめるべきである。
本番利用には向かない設計と、代替となるアプローチ
このリポジトリは教材であり、検索基盤ではない。ベクトルストアは 01_in_memory_store という名前が示す通りインメモリで、プロセスを再起動すれば索引は消える。永続化、差分更新、複数プロセスからの同時アクセス、障害時の再構築といった運用上の要件は扱われていない。代替として挙げられるのは、たとえばLangChainやLlamaIndexのようなフレームワークで、これらはベクトルストアの抽象化を提供し、FAISS、Chroma、Qdrantといった永続化可能なバックエンドに差し替えられる。違いは抽象化の位置だ。フレームワークは検索の詳細を設定とクラスに隠すため、動くものは早く手に入るが、スコアの計算方法やチャンク境界の扱いを自分で決める場面では挙動が見えにくい。rag-from-scratch はその逆で、インメモリの配列と距離計算を自分で書くため、小規模なデータでは何が起きているか完全に追えるが、数百万件のベクトルを扱うスケールにはそのままでは進めない。学習後にフレームワークへ移るか、自作の検索部分だけを残すかは、扱うデータ量で決まる。
MITライセンスと、依存関係が持ち込む別の条件
リポジトリ自体はMITライセンスで、コードの利用、改変、再配布、商用利用が許される。帰属表示は必要だが、教材のコードを自社のプロトタイプに取り込むことにライセンス上の障害はない。ただし注意すべきは依存とモデルの側だ。node-llama-cpp はllama.cppをNode.jsから扱うバインディングであり、その配布条件はMITとは別に確認が必要になる。さらに、ローカルで動かすLLMと埋め込みモデルにはそれぞれ独自のライセンスが設定されていることが多く、商用利用の可否や再配布の条件はモデルごとに異なる。MITライセンスだからといって、生成される出力や使用する重みファイルまで自由に使えるわけではない。ここで法的な助言はできないが、社内導入を検討する場合は、採用するモデルのライセンス条項を別途確認する作業が発生する。
メンテナンス状況と、読む前に確認したい三つの点
最終更新は2026年3月11日で、アーカイブはされておらず、リリースは取得できていない。バージョン番号による安定版の提供はなく、mainブランチを追う形になる。教育用リポジトリとしては、依存するnode-llama-cppのAPI変更がそのままexampleの動作に影響する点に注意したい。フレームワークのように後方互換を保証するリリースサイクルは期待できない。読む前に確認すべきは三つある。第一に、examples/04_intro_to_embeddings/02_generate_embeddings/ の CODE.md に書かれたモデルの取得手順とファイル配置。第二に、node-llama-cpp が自分のOSとCPU、あるいはGPUでビルドできるか。第三に、README末尾が省略されているため、再ランキングと生成の章が examples/ に実在するかどうか。この三点が満たせれば、RAGの各工程を自分の言葉で説明できる状態に近づける。満たせない場合は、クラウドAPIを使う別の入門記事のほうが短時間で目的に到達する。
編集部の結論
RAGの各段階を自分の手で書き、ベクトル検索やRRFの挙動を確認したい開発者には向く。逆に、本番品質の検索基盤や運用機能をすぐ必要とするチームには向かない。着手前に確認すべきは、examples/04_intro_to_embeddings/02_generate_embeddings/ が要求する埋め込みモデルの取得手順、node-llama-cpp が対応するプラットフォーム、そしてREADME末尾が省略されている以上、後半の再ランキングや生成の章が実際にどこまで書かれているかである。
コミュニティノート