← 기사 목록
日本語https://zenn.dev/topics/llm/feed

RAGナレッジベース作成を簡単にしたくてツールを作った

원문 사이트로 이동 ↗

추출된 키워드

45개
mrag·5Micro RAG·5RAGナレッジベース·5Retrieval Profile·4Chunking Strategy·4Retrieval Strategy·4SKILL.md·4Ollama·4CLIツール·4Dify·4AIエージェント·3Claude Desktop·3Codex·3Gemini CLI·3Claude Code·3gemma4:e4b·3Dify外部ナレッジAPI·3Agentic RAG·3recursive·3markdown_recursive·3block_aware·3parent_child·3BM25·3形態素解析トークナイザー·3Vector·3Qdrant·3Sqlite·3Python·3sqlite-vaporetto·3bge-m3·3Embedding·3Retrieval·3hybrid·3Keyword·3sentence-transformers·3SQLite FTS5 BM25·3Parent-Child Retrieval·3Contextual Retrieval·3Contextual Augmentation·3LLM·3CrossEncoder·3Anthropic·2RAGFlow·2OpenAI Codex·2FastAPI·2

원문

9,072자
RAGナレッジベース作成を簡単にしたくてツールを作った

RAGナレッジベース作成を簡単にしたくてツールを作った

はじめに

RAGを利用したチャットボットの作成にはもっぱらDifyを利用してました。単純なRAGならドキュメントを放り込んでボタン押すだけでつくれるしチャットフローでのナレッジ設定も簡単なのでコード書くよりよっぽど楽です。

一方で最近だとClaude DesktopやCodex、Gemini CLIと対話する時間が増えてきたので彼ら向けのナレッジベースをクイックに用意したいんだけど調べてもニーズに合うツールがなかったのでmragというツールを作りました。

https://github.com/bathtimefish/mrag

個人的に小規模なナレッジベースを作ってエージェントを業務に特化させるのが簡単だったり、RAGの精度をあれこれ試したりするのに便利なのでご紹介します。

mrag（エムラグ）とは

mrag（Micro RAG）は、ローカル環境で動作する小規模RAGパイプラインを構築・運用するためのCLIツールです。

主な仕様は以下です。

  • ローカルでコンパクトに動く設計— Python + Sqlite + Qdrant + Ollama
  • Tokenizer&Embedding—sqlite-vaporettoによる形態素解析トークナイザー、bge-m3（ollama）による多言語Embedding
  • 各種 Retrieval戦略—複数の検索戦略を実装。hybrid(Keyword（SQLite FTS5 BM25）+ Vector), Keyword, vector
  • Profileファイルベースの設定— Chunking, Embedding,Retrievalの戦略を複数サポートしRetrieval Profile(YAML)で自由に組み合わせられる
  • Parent-Child Retrieval— Parent-Child Retrieval Strategyを実装
  • Contextual Retrieval—Contextual Augmentationを実装。インデックス時にLLM(Ollama)でチャンクごとにコンテキストを生成（Anthropicのcontextual retrieval）
  • ブロック認識チャンキング— 表構造・コードブロックを可能なかぎり認識して適切にチャンキングしようとする
  • Relanker — CrossEncoder（sentence-transformers）による検索後の再スコアリング
  • Dify外部ナレッジAPIサーバ—
    mrag serve
    でDify External Knowledge API仕様に準拠したFastAPIサーバーを立ち上げられる

なぜ作ったか

「手元にあるのドキュメントをナレッジベース化してエージェントを賢くしたい」という要件をRAGでやりたいと思うと意外と準備が面倒だったりします。個人的に知ってるツールの中ではDifyが一番あ簡単にはじめられるツールかなと思ってますが、Difyだと前述のようにDifyにバインディングされているナレッジベースになるので外部にその機能だけ切り出して使うようなことは難しいです。

RAGFlowなどのサービスもありますが、そこまで高度なことは求めないしできれば処理はローカルで完結させたいです（あんまりクラウドにアップしたくない文書もあるので）。

そして前述のように最近のClaude Desktop/Codex/gemini CLIなどのデスクトップで動くエージェントツールの便利さが著しく向上しているので「彼らに要件ごとの手軽にナレッジを手軽に提供したり、ナレッジベース自体を作ってもらったりできるツールはないだろうか？」と思ったのがきっかけです。調べるかぎりなさそうだったので作りました。

使ってみる

セットアップ方法

以下がセットアップ方法ですが、付属のSETUP.mdをClaude Codeなどに読ませてよろしくセットアップしてもらえます。Linux,Windows,Macで動作確認済みです。

デフォルトのセットアップではOllamaがセットアップ済みでバックエンドサーバが起動済みであることが前提です。必要に応じて(Qdrant Docker)[https://hub.docker.com/r/qdrant/qdrant]も利用可能です。

現行バージョンではセットアップ時にダウンロードするgemma4:ebのために10GB程度のディスクスペースが必要です。

git clone https://github.com/bathtimefish/mrag.git
cd mrag
uv venv --python 3.11
source .venv/bin/activate
uv pip install -e ".[vaporetto,reranker]"

Embeddingモデルを取得してOllamaを起動しておきます。

ollama pull bge-m3
ollama run gemma4:e4b # contextual augmentationを仕様する場合

使い方

以下に基本的な使い方を説明しますが、付属のAGENTS.md,SKILL.mdをClaude Codeなどに読ませることでエージェントにmragを操作してもらったり使い方を教えてもらったりもできます。

任意のディレクトリで

mrag init
を実行しナレッジベースのプロジェクトを作成します。プロジェクトを作成するとそのディレクトリにmragのタスクに必要なディレクトリ、設定ファイル等が展開されます。
# プロジェクトを作る親ディレクトリで実行する
cd myproject
mrag init --name mykb


mrag add
でドキュメントをナレッジとして追加します。現行バージョンではPDFファイル、テキストファイル(Markdown)のみに対応しています。
mrag add manual.pdf

インデックスを構築します。

mrag index

indexは処理実行中は各チャンクごとの処理状況が標準出力されます。また処理結果が

logs/
にJSONで保存されます。差分インデックス処理のため、index後に
mrag add
でドキュメントを追加したあと再度indexすると追加分だけが処理されます。

indexをいちからやり直したい場合は

mrag reindex
を実行します。

基本的にはこの

mrag add
→ 
mrag index
だけでナレッジベースが作成できます

ナレッジベースに対しては

search
こまんどで検索します。
mrag search "エラーハンドリングの方針"


search
のはヒットしたチャンクデータの他にスコア統計、ドキュメント分布に関する指標も出力します。Claude Codeなどのエージェントにはこれを参考にユーザーの要求に対して適切なナレッジが得られるまでクエリを組み替えて検索を繰り返すAgentic RAGのような動きをさせることもできます。

ナレッジベースに対してRetrieval Strategyごとの検索精度の違いを分析評価するための

mrag eval
もあります。

DifyとのAPI連携

mrag serve
を実行するとWebサーバーが起動し、Dify外部ナレッジAPI仕様に準拠したエンドポイントを提供します。
mrag serve
# Starting MRAG API server on http://127.0.0.1:8000

このエンドポイントをDifyに登録することでmragで作成したナレッジベースDify上で利用することができます。

機能特徴の紹介

mragの特徴をいくつかご紹介します。

Retrieval Profileによる柔軟な設定

RAGのチューニングはRetrieval Profileで行います。プロジェクトの

profiles/
ディレクトリのyamlファイルでChuking,Embedding,Retrievalの処理方法などを設定できます。プロファイルは複数設置することが可能です。
name: default

chunking:
  strategy: recursive
  source_format: markdown
  chunk_size: 800
  overlap: 120
  preserve_heading_path: true
  preserve_tables: true
  preserve_code_blocks: true

retrieval:
  strategy: hybrid
  top_k: 8
  dense_top_k: 20
  keyword_top_k: 20
  fusion: rrf

augmentation:
  strategy: none   # none | contextual

プロファイルを複数作成しておけば、

--profile <name>
で切り替えながらインデックスと検索を実行できます。
mrag eval
で複数プロファイルの検索品質を並べて比較することも可能です。

設定を変えたら

mrag reindex
でナレッジベースを再構築してください。

Chunking Strategy

ドキュメントをどう切り分けるかはRAGの精度に直結します。mragは4つのChunking Strategyを持っています。

Strategy用途
recursive
 テキストやPDFの汎用分割。デフォルト。
markdown_recursive
 見出し構造を優先して分割。技術ドキュメントに向く。
block_aware
 テーブル・コードブロックをアトミック単位として保護し、見出しパスをメタデータに付与。
parent_child
 小さなchild chunkで精密検索し、大きなparent chunkで文脈ごと返す。

source_format: markdown
の場合は以下のオプションでチャンキング時のブロック認識が有効になります。
preserve_heading_path: true   # 見出しパンくずをチャンクに付与（デフォルト: true）
preserve_tables: true         # テーブルをアトミック単位として保護（デフォルト: true）
preserve_code_blocks: true    # フェンスコードブロックをアトミック単位として保護（デフォルト: true）

Retrieval Strategy

検索方法はRetrieval Strategyで切り替えられます。

Strategy特性
hybrid
 BM25 + Vector Search。デフォルト。
keyword
 FTS5 BM25のみ。完全一致検索。
vector
 Qdrantコサイン類似度のみ。
parent_child
 Parent-child Retrieval利用時のみ有効

日本語ドキュメントではvaporettoによる形態素解析トークナイザーを使用して日本語テキストを適切に分解してキーワード検索の精度を高めるようにしています。

SKILL.md

mragにはSKILL.mdというドキュメントが付属しています。Claude Code、OpenAI Codex、Gemini CLIなどのコーディングエージェントがSKILL.mdを読み込むことで、mragの各コマンドを自律的に操作できるようになります。

SKILL.mdはAIエージェント向けの手順書です。

mrag init
から
mrag search
まで、各操作の前提条件・コマンド・期待される出力・確認手順をステップバイステップで記述しています。さらに、ハイブリッド検索の使い分け、コンテキスト拡張の注意点、parent-child検索のチューニング、インデックス失敗時のスキップ方法といった実運用ノウハウも盛り込んであります。

たとえばClaude Codeに「このドキュメント群でRAGナレッジベースを作って検索してみて」と依頼すると、SKILL.mdを参照しながら

mrag init
→
mrag add
→
mrag index
→
mrag search
を自律的に実行します。失敗したインデックスがあれば
--skip-list-json
でスキップしながら進める、といった判断もエージェントが行えます。

コンテキスト拡張（

augmentation.strategy: contextual
）を使ったインデックスは処理時間が長くなりますが、
tee
でコンソール出力をリアルタイムにファイルに流しておけば、エージェントがログを監視して進捗を把握したりもします。
mrag index 2>&1 | tee mrag-index-$(date +%Y%m%d-%H%M%S).log

まとめ

mragはローカルのドキュメントでRAGを手軽に試せるCLIツールです。小規模なナレッジベースをローカル環境に構築したい方はぜひ使ってみてください。

開発当初はユーザーが単純なCLIのコマンドを叩いてナレッジベースを作る想定でしたが、使っているうちにエージェントにコマンドを叩かせたほうがより便利だということに気づいたので今後はよりエージェントフレンドリーなCLIとして開発していこうと思います。

フィードバックや改善提案はIssueやPRでお待ちしています。