Marian（AIファーストのナレッジワークスペース）の設計と実装を解説するエンジニアリングブログ。リンクトノート、ナレッジグラフ、コンテキストエンジン、ハイブリッド検索、エージェント自動化などを扱います。
MarianのAsk(RAG)は、ベクトル検索と全文検索を単純に混ぜていません。ACLフィルタ→バイナリ類似度による粗探索→int8ドット積によるリランク→Reciprocal Rank Fusionという4段パイプラインで、権限リークを構造的に防ぎながら複数の検索シグナルを統合します。本記事では各段の実装、RRFの式と定数(k=60、keyword重み0.85)、そしてフラグオフ時のグレースフルデグラデーション設計を解説します。
fp32の768次元埋め込みは1本3KB。コーパスが伸びるとメモリにもインデックスにも載らなくなります。Marianは符号1bit量子化(768次元→96バイト、32分の1)とHamming距離のHNSWインデックスで粗探索し、fp32コサインでリランクする2段階検索をpgvectorだけで実装しました。量子化の式、POPCOUNTテーブル、PostgreSQLのRPC、既存埋め込みからのゼロコストバックフィルまで、実装をそのまま解説します。
チャンク単位のRAGは「このドキュメント群は全体として何を言っているか」という広い質問に弱い。MarianはRAPTOR(Recursive Abstractive Processing for Tree-Organized Retrieval)方式の要約ツリーを実装し、リーフ(チャンク)から要約ノードを再帰的に積み上げます。本記事では、葉数加重のバイナリ重心、貪欲最近傍クラスタリング(branching=4)、全階層を一括スコアリングするcollapsed-tree検索、そしてmarian_file_tree_nodesテーブルへの永続化を解説します。
ドキュメントをRAGに載せる経路は「分割→埋め込み→格納」の3手に見えますが、運用で効くのは2回目以降の再インデックスです。Marianはチャンク内容のFNV-1aデュアルハッシュをembeddingsテーブルに併置し、変更のないチャンクの再埋め込みをスキップします。チャンクサイズの実定数(1400字/256トークン)、ファイル種別ごとの分割戦略、planReindexによる差分計画の実装を解説します。
埋め込み生成や音声転写のような長時間ジョブをWebリクエストの中で実行はできません。MarianはRedisもSQSも足さず、Postgresのテーブル1枚でジョブキューを実装しました。状態機械(queued→running→retrying→succeeded/dead)、30秒リースによるクラッシュ回復、部分ユニークインデックスによる冪等性、1s→5分capの指数バックオフまで、スキーマと実装をそのまま解説します。
「全部覚える」エージェントメモリは検索ノイズと化します。Marianのメモリ基盤は、7軸のサリエンス(重要度・リスク・緊急度など)で記憶をスコアリングし、夜間ジョブで短期→長期へ昇格(consolidation)、軸ごとの半減期で減衰させて抽象度を引き上げる(distillation)、という生体記憶に似た2つのプロセスで管理します。エピソードDBスキーマ、合成サリエンスの重み、キュー索引によるO(最小ポスティングリスト)のリコールまで実装を解説します。
マルチエージェントシステムの障害調査は「どのエージェントが、何の権限で、どのリクエストを処理したか」が分からないと始まりません。Marianは全APIルートをエンベロープ(封筒)契約で包み、trace ID・発信元・宛先・座標・ケイパビリティをメタデータとして強制します。さらに各エージェントは「禁止/回避/提案のみ/再確認/許可」の5段階責任境界を宣言し、ルート実装はevaluate()で判定を受け取ります。wire format、座標系、静的検証ハーネスまで解説します。
プライバシー重視のユーザーはローカルLLM(Ollama)を、品質重視のユーザーはクラウドを選びます。Marianのチャット基盤は provider パラメータ1つでOllama・OpenAI互換サーバー・Geminiを切り替え、NDJSONとSSEという異なるストリーミング形式を共通のチャンク列へ正規化します。さらに「Ollama未インストール」から「モデル取得済み」までを導く決定的ステートマシンのブートストラップウィザード(I/Oゼロの純粋関数)を実装しました。その設計を解説します。
RAGの「どのドキュメントをどの粒度でプロンプトに入れるか」は、普通ユーザーから見えないブラックボックスです。Marianのコンテキストエンジンはこれを明示的なデータ構造にしました。スコープ(notebook/vault)×ソースごとのグレイン(full/summary/excluded)の組み合わせからトークン見積もりつきのContextPlanを構築し、8,000トークンのソフト予算に対する消費をユーザーに見せます。計画と実行を分離するこの設計は、要約プランナー(single vs map-reduce)にも貫かれています。
検索パイプラインに量子化やRAPTORのような変更を入れるとき、「壊れていないこと」をどう保証するか。LLM-as-a-judgeは遅く高くフレーキーで、CIゲートには不向きです。Marianはシード固定のシンセティックコーパス(24トピック×10チャンク、120クエリ)に対してrecall@k / MRR / nDCG / MAPを計算し、recall@10 >= 0.6を満たさなければCIを落とす決定的な評価ハーネスを実装しました。指標の実装からコーパス生成、ゲート設計までを解説します。