MacBook Pro にローカル RAG を構築する

前稿では、MacBook Pro でローカル LLM を実用化するには、モデルが起動するだけでなく、用途に対して十分な応答速度、記憶容量、モデル規模、運用方法が成立していなければならないことを整理した[1]。ローカル RAG の構築では、この条件に文書処理と検索の経路が加わる。Ollama、Open WebUI、Qdrant を起動し、画面上でモデルと対話できても、登録文書を根拠とする回答が生成されていなければ、完成したとはいえない。

RAG の処理は、文書から文字を取り出し、検索可能な単位へ分割し、各断片を埋め込みモデルで数値ベクトルへ変換し、ベクトルデータベースへ保存する登録経路から始まる。質問時には、質問文から同じ埋め込みモデルでベクトルを生成し、意味の近い文書断片を検索し、その断片を質問とともに生成用 LLM へ渡す。登録経路と検索経路が同じベクトル空間で接続され、取得された断片が生成入力へ組み込まれて初めて、外部文書を参照する回答が成立する。

ローカル RAG の実用性は、モデルを選択して推論を実行するだけでは成立しない。データ、権限、既存システム、評価工程へ接続する実装によって、単発の対話機能から継続的な処理基盤へ変わる[2]。RAG は、生成モデルが学習時に内部化した知識と、運用者が外部で管理する検索可能な知識を組み合わせる構成である[3]。この構成では、流暢な回答が返ることよりも、適切な文書断片が取得され、その断片から逸脱せずに回答が生成されたかを分けて評価する必要がある[4]。

本稿では、Apple Silicon 搭載 MacBook Pro 上で Ollama を直接実行し、Open WebUI と Qdrant を Docker Compose で管理する。生成用モデルには qwen3.5:9b-q4_K_M、埋め込み用モデルには embeddinggemma を使用する。Ollama を macOS 側へ置き、画面とベクトル保存層をコンテナーへ分離することで、モデル推論とサービス管理を別々に更新できる構成とする。

構築後には、一般的な学習データから推測できない架空の固有情報を文書へ登録する。Knowledge を接続しない通常対話と、登録文書を接続した対話を同じ質問で比較し、後者だけが文書内の値を回答できるかを確認する。この対照試験により、モデルが事前知識や推測から回答した場合と、検索された文書断片を根拠に回答した場合を区別する。

1. ローカル RAG の完成条件を固定する

1.1 起動成功と RAG 成功は異なる

Open WebUI の画面が表示され、Ollama の生成用モデルと対話できても、文書検索が動作しているとは限らない。通常対話は、Open WebUI から Ollama へ質問を送り、生成結果を受け取るだけで成立する。この経路では、Qdrant への接続、文書の埋め込み生成、類似検索のいずれも使われないため、RAG 側に障害があっても自然な回答が返る場合がある。

文書登録の画面表示も、処理完了の十分条件にはならない。Open WebUI にファイル名や Knowledge が表示されていても、文書形式に対応する抽出処理が失敗し、本文が空になっている可能性がある。本文を取得できても、分割結果が極端に短い、表の行と見出しが分離している、文字コードの問題で内容が崩れている場合には、質問に必要な意味単位を埋め込みへ変換できない。

Qdrant にコレクションと点が作成されていることは、登録経路が少なくとも保存段階まで進んだことを示す。ただし、保存されたベクトルが質問と同じ埋め込みモデルで作られているか、各点の付随情報に元文書の断片が含まれているか、検索結果の上位に必要な断片が入るかは別の確認事項である。保存件数だけを見ても、検索に使える内容が格納されたとは判断できない。

最終回答の正しさにも、同じ判定上の問題が残る。生成用 LLM が質問対象を学習データ内で知っている場合、文書検索を一度も行わなくても正答できる。反対に、検索自体は成功していても、取得断片に複数の値が含まれていたり、生成時の指示が曖昧だったりすれば、文書とは異なる回答を返す。回答の外形だけでは、検索と生成のどちらが成功または失敗したのかを切り分けられない。

この段階分けにより、障害の位置をサービス、文書処理、埋め込み、保存、検索、生成のいずれかへ絞り込める。たとえば、Qdrant に点が存在しない場合は登録経路を調べ、点は存在するが目的の断片が検索されない場合は分割方法と埋め込み設定を調べる。適切な断片を取得できているのに回答が異なる場合は、生成用 LLM へ渡された文脈と指示を確認する。全体を一つの「RAG の不具合」として扱わず、処理境界ごとに観測可能な事実を置くことが、再現可能な検証の前提になる。

1.2 完成条件を処理経路で定義する

ローカル RAG の完成条件は、画面上の機能数ではなく、文書登録から回答生成までの処理経路によって定義する。登録時には、原文を検索可能なベクトルと、回答時に再利用できる文字列へ変換する。質問時には、質問と文書断片を同じ基準で比較し、関連する断片を生成入力へ戻す。二つの経路は Qdrant の類似検索で接続される。

登録経路では、文書断片と埋め込みベクトルの対応関係を失ってはならない。ベクトルだけを保存しても、検索後に生成用 LLM へ渡す原文を復元できない。反対に、原文だけを保存して埋め込みベクトルを作らなければ、質問との意味的な近さを検索できない。Qdrant の各点には、類似度計算に使うベクトルと、検索後に参照する文書断片および出典情報が対応して保存される必要がある。

質問検索経路では、登録時と質問時に同じ埋め込みモデルを使う。異なるモデルは、同じ文章から異なる次元数や配置規則を持つベクトルを生成するため、登録文書と質問を同じ意味空間で比較できなくなる。モデルを途中で変更した場合は、質問側だけを切り替えるのではなく、既存文書を新しいモデルで再度埋め込み、Qdrant の保存内容を作り直す必要がある。

チャンク分割は、検索単位と生成時の根拠単位を同時に決める。チャンクが大きすぎると、一つのベクトルに複数の話題が混在し、質問に対応する箇所と無関係な箇所が同時に取得される。小さすぎると、主語、条件、数値、例外規則が別々の断片へ分かれ、単独では意味を確定できなくなる。重複部分は境界で失われる文脈を補うが、重複を増やしすぎると類似した断片が検索上位を占有し、異なる根拠を取得できる件数が減る。

生成経路では、取得成功と回答忠実性を分けて扱う。検索結果に正しい断片が含まれていても、生成用 LLM がその断片より事前知識を優先すれば、登録文書と異なる回答になる。生成時の指示では、与えられた文書を根拠とし、文書に記載がない事項を推測しないという制約を明示する必要がある。検索精度の調整だけでは、根拠から逸脱する生成を防げない。

検証用文書には、一般知識や名称から答えを推測できない情報を入れる。たとえば、架空の Argolet システムについて、「本番ポートは 47821」「緊急停止では Lapis-7 手順を使う」と記載する。名称、数値、手順名の間に一般的な関連がないため、モデルがこれらを正確に回答した場合、登録文書または会話中の入力から取得した可能性が高い。

未接続時に誤答し、接続時に正答するだけでは、検証としてはまだ弱い。未記載事項に対して回答を保留できるか、質問の言い換えでも同じ根拠を取得できるか、類似した別の数値を混在させても対象を取り違えないかを加える必要がある。正答試験、言い換え試験、情報不足試験を組み合わせることで、単なる偶然の一致ではなく、検索と生成の両方が期待どおりに機能しているかを判定できる。

1.3 本稿の構成値

構築時の値は、最適値としてではなく、再現可能な初期条件として固定する。モデル、サービス、チャンク設定を同時に変更すると、回答が変化しても原因を特定できない。最初に一つの構成で登録経路と検索経路を成立させ、その後に変更対象を一項目ずつ分離して比較する。

生成用 LLM と埋め込みモデルは、同じ「モデル」であっても交換条件が異なる。生成用 LLM を変更した場合、既存のベクトルを維持したまま、同じ検索結果に対する回答品質を比較できる。埋め込みモデルを変更した場合は、文書と質問の配置されるベクトル空間そのものが変わるため、保存済み文書を再利用してはならない。この違いを無視すると、生成能力の差と検索順位の差が同時に発生し、改善または劣化の原因を特定できなくなる。

チャンクサイズ、重複量、取得件数にも、文書を問わず通用する唯一の最適値はない。手順書では、操作名、前提条件、コマンド、警告を同じ断片へ残す必要がある。仕様一覧では、一項目が短いため、大きなチャンクにすると無関係な複数項目が混在する。初期値を固定する目的は調整を省くことではなく、検索に失敗した質問と取得断片を記録し、文書構造に応じて変更するための比較基準を作ることにある。

この構成で確認するのは、MacBook Pro 上で各サービスが起動したという事実ではない。架空情報を含む文書が分割され、embeddinggemma のベクトルとして Qdrant へ保存され、質問時に必要な断片が取得され、qwen3.5:9b-q4_K_M がその断片の範囲内で回答するところまでを一続きの処理として確かめる。ローカル RAG の完成は、構成要素の存在ではなく、文書を根拠へ変換する経路を観測可能な形で再現できることによって決まる。

2. Ollama をホスト、Open WebUI と Qdrant をコンテナーへ配置する

2.1 Apple Silicon と Docker の境界

本構成では、推論処理を担う Ollama を macOS 上で直接動かし、対話画面を提供する Open WebUI と、ベクトルを保存する Qdrant を Docker Desktop 上へ配置する。すべてをコンテナーへ収容するのではなく、計算資源を使う処理と、更新や保存を管理したいサービスを分離する。

Apple Silicon では、CPU と GPU が同じユニファイドメモリを共有する[5]。Ollama を macOS 上で直接実行すると、生成用 LLM と埋め込みモデルの推論処理から、この計算資源をホスト側の実装を通じて利用できる。Ollama の macOS 版は Apple M シリーズへ対応し、取得したモデルを利用者のローカル領域へ保存する[6]。

生成用 LLM と埋め込みモデルを同じ Ollama 上へ置くのは、両者を同一モデルとして扱うためではない。生成用 LLM は質問と取得文書から回答を組み立て、埋め込みモデルは文書と質問を検索可能なベクトルへ変換する。役割は異なるが、モデルの取得、起動、API 接続、保存場所を一つのローカル推論基盤へ集約できるため、コンテナー内へ別の推論環境を構築する必要がなくなる。

Open WebUI と Qdrant は Docker Desktop 上へ配置する。Docker Desktop には Apple Silicon 用の正式な配布物があり、Arm64 環境に対応したコンテナーを実行できる[7]。Docker Compose を使えば、使用するイメージ、サービス間ネットワーク、環境変数、ポート、保存領域を一つの構成ファイルへ固定できる[8]。

コンテナーは削除して再作成できることを前提とするため、Open WebUI の利用者情報や Knowledge の管理情報、Qdrant のベクトルデータをコンテナー内部だけへ保存してはならない。保存領域をボリュームとして分離すると、イメージを更新してコンテナーを作り直しても、運用状態を引き継げる[9]。アプリケーションの実行環境と永続データを分けることで、更新失敗時にも旧版へ戻しやすくなる。

Open WebUI はコンテナー内から、macOS 上で動作する Ollama の API へ接続する。コンテナー内の localhost は MacBook Pro ではなく、そのコンテナー自身を指す。Ollama の接続先へ http://localhost:11434 を指定すると、Open WebUI は自分自身の 11434 番ポートへ接続しようとして失敗する。

Docker Desktop では、コンテナーからホストへ接続するための名前として host.docker.internal が用意されている[10]。Open WebUI には Ollama の接続先として http://host.docker.internal:11434 を指定する。これにより、画面と文書管理はコンテナー内へ分離したまま、生成と埋め込みの要求だけを macOS 上の Ollama へ送れる。

この配置では、Ollama の障害とコンテナー側の障害を分けて判定できる。Ollama API がホスト上で応答するのに Open WebUI からモデルが見えない場合は、Docker からホストへの接続を調べる。Open WebUI から通常対話はできるが文書登録に失敗する場合は、埋め込みモデルまたは Qdrant との接続を調べる。処理の境界を実行場所と一致させることで、RAG 全体を一つの不可視な処理として扱わずに済む。

2.2 MacBook Pro の状態を確認する

導入前に、CPU アーキテクチャー、macOS の版、ユニファイドメモリ容量、SSD の空き容量を記録する。同じモデル名を使用しても、搭載メモリや同時に動作するアプリケーションが異なれば、推論速度と安定性は変わる。後からモデルや Docker の設定を変更した際に比較できるよう、構築時点の条件を残しておく。

uname -m の結果が arm64 であれば、Apple Silicon 用の実行環境であることを確認できる。sw_vers では macOS の版とビルド番号を記録する。Ollama や Docker Desktop の更新後に動作が変わった場合、OS 側の更新を含めて条件を比較できる。

system_profiler SPHardwareDataType では、Chip と Memory を確認する。ユニファイドメモリは Ollama だけが専有するものではなく、macOS、通常のアプリケーション、Docker Desktop の仮想環境と共有される。モデルファイルが SSD に収まることと、推論時にモデルを安定して実行できることは別の条件である。

qwen3.5:9b-q4_K_M は、モデルデータだけでおよそ 6.6 GB を使用する。これに Ollama の実行時領域、会話文脈、埋め込みモデル、Docker Desktop、Open WebUI、Qdrant、登録文書、ベクトル索引の使用量が加わる。SSD にはモデルファイルと Docker イメージを保存できるだけでなく、更新時に新旧データが一時的に併存できる余裕を確保する。

16 GB 機では、9B 級モデルの起動だけで直ちに使用不能になるとは限らないが、Docker Desktop や他のアプリケーションとの同時使用によって余裕が小さくなる。メモリ圧迫やスワップの増加が続く場合は、生成用 LLM を 4B 級へ下げる選択肢を残す。24 GB 以上では 9B 級を初期構成として試し、応答速度とメモリ圧力を観察したうえで維持するか判断する。

これらの容量別判断は初期設定の目安であり、機種ごとの実測性能を示すものではない。

モデル規模の判断は、読み込めたかどうかだけでは決めない。短い質問には応答できても、Knowledge から取得した複数のチャンクと長い会話履歴を同時に入力すると、必要な記憶容量が増える。RAG の実用条件は、モデル単体の起動試験ではなく、文書検索を含む実際の入力長で確認する必要がある。

2.3 Ollama と Docker Desktop を導入する

Ollama は公式の macOS 用アプリケーションをインストールし、一度起動する。初回起動によって、バックグラウンドで API を受け付ける状態を作り、ターミナルから ollama コマンドを利用できるようにする。アプリケーションを配置しただけで起動していない場合、コマンドが存在しても 11434 番ポートの API は応答しない。

Docker Desktop も公式の Apple Silicon 用インストーラーから導入し、アプリケーションを起動する。docker コマンドが存在していても、Docker Desktop の仮想環境が停止していれば、コンテナーの作成や状態確認は実行できない。コマンドの導入と実行基盤の起動を分けて確認する。

ollama –version では、利用する Ollama の版を記録する。docker version では、クライアントだけでなくサーバー側の情報が表示されることを確認する。クライアント情報だけが表示され、デーモンへの接続エラーが返る場合は、Docker Desktop が起動していないか、初期化が完了していない。

docker compose version では、Docker Compose を独立した旧コマンドではなく、Docker CLI のサブコマンドとして利用できることを確認する。本稿の操作は docker-compose ではなく docker compose を使用し、構成の起動、停止、更新手順を統一する。

Docker Desktop の Resources では、Open WebUI と Qdrant が動作できるメモリを確保する。ただし、Docker へ割り当てたメモリは、ホスト上の Ollama と無関係に増えるわけではない。両者は最終的に同じユニファイドメモリを消費するため、Docker 側の上限を過剰に広げると、文書登録や検索は安定しても、生成用 LLM の推論時にメモリ圧迫が発生する。

24 GB 機では、Docker 側を 4 GB 前後から開始し、Open WebUI の起動、Qdrant への保存、文書登録時の使用量を観察して調整する。大量の文書を一度に登録すると、文字抽出、チャンク分割、埋め込み要求、Qdrant への保存が連続するため、通常対話時より負荷が高くなる。初期値を大きく設定するのではなく、実際の文書量で不足が確認された場合にだけ増やす。

2.4 使用ポートを確認する

サービスを起動する前に、使用するポートと公開範囲を固定する。ポート番号が重複するとコンテナーは起動できず、公開先を省略すると、意図せずローカルネットワーク上の別端末から接続可能になる場合がある。ローカル RAG として一台の MacBook Pro 内で利用する限り、Open WebUI と Qdrant を外部インターフェースへ公開する必要はない。

Open WebUI の 3000 番ポートを 127.0.0.1 へ限定すると、同じ MacBook Pro 上のブラウザーからは接続できるが、同一ネットワーク上の別端末からは直接接続できない。Qdrant の 6333 番ポートも同様に限定する。Qdrant には登録文書の断片やベクトルが保存されるため、認証や外部公開の設計を行っていない段階でネットワークへ公開しない。

6334 番ポートは Qdrant の gRPC に使用されるが、本構成ではホスト上から直接利用しない。Open WebUI と Qdrant は同じ Docker Compose ネットワーク内でサービス名を使って通信できるため、コンテナー間通信に必要なポートをすべて macOS 側へ公開する必要はない。ホストへの公開は、ブラウザーや確認用コマンドから直接接続するものに限定する。

起動前に、予定しているポートを別のプロセスが待ち受けていないか確認する。

3000 番と 6333 番で出力が空であれば、現時点でそのポートを待ち受けているプロセスはない。出力がある場合は、プロセス名と PID を確認し、停止するか、Docker Compose 側のホストポートを変更する。既存サービスを確認せずに終了させてはならない。

11434 番は、Ollama を起動した後であれば待ち受けが確認できる。Ollama を起動しているにもかかわらず出力がない場合、Open WebUI の設定を進める前に Ollama 側の状態を調べる。ホスト上で API が待ち受けていなければ、host.docker.internal の指定が正しくてもコンテナーから接続できない。

ポート設計によって、利用経路と公開範囲を一致させる。生成と埋め込みは Open WebUI からホスト上の Ollama へ接続し、Open WebUI と Qdrant の確認画面は MacBook Pro 自身からだけ開く。RAG をローカルで動かすという条件には、モデルと文書を端末内へ置くだけでなく、不要なネットワーク公開を行わないことも含まれる。

3. Ollama の生成用 LLM と埋め込みモデルを個別に確認する

3.1 Ollama API の起動を確認する

Open WebUI と接続する前に、macOS 上の Ollama が単独で応答することを確認する。Open WebUI は、Ollama の HTTP API を通じて、取得済みモデルの一覧、文章生成、埋め込み生成を呼び出す[11]。この段階で API が応答しなければ、後から Open WebUI や Qdrant を起動しても RAG の処理経路は成立しない。

/api/tags は、Ollama のローカル領域へ取得済みのモデルを返す。これに対して ollama ps は、現在メモリへ読み込まれているモデルを表示する。保存済みモデルと実行中モデルは異なるため、二つの結果を同じ意味で扱わない。

curl が正常終了して JSON を返せば、11434 番ポートの Ollama API へ接続できている。モデルをまだ取得していない場合、models は空の配列になる。これは API の障害ではなく、ローカルに利用可能なモデルが存在しない状態を示す。

ollama list にモデルが表示されても、ollama ps が空になることはある。取得済みモデルは SSD に保存されるが、推論要求を受けるまではメモリへ読み込まれないためである。生成または埋め込みを一度実行した後に ollama ps を確認すると、読み込まれたモデル、使用量、処理装置、割り当てられたコンテキスト長を確認できる。

接続拒否になる場合は、Ollama アプリケーションが起動しているかを確認する。JSON ではなく HTML や別サービスの応答が返る場合は、11434 番ポートを Ollama 以外のプロセスが使用していないかを調べる。Open WebUI 側の接続設定を変更するのは、ホスト上の API が正常に応答することを確認した後である。

3.2 生成用モデルを取得する

生成用モデルには qwen3.5:9b-q4_K_M を使用する。9B はモデルのおおよその規模を示し、q4_K_M は重みを 4 ビットへ量子化した形式を示す。量子化によって保存容量と実行時の記憶使用量を抑えられるため、MacBook Pro の限られたユニファイドメモリでモデルを実行しやすくなる。

量子化は、元の重みをより少ないビット数で表現する処理である。保存容量が減るだけでなく、推論時に読み込むデータ量も小さくなる一方、元の精度を完全には保持しない。q4_K_M は、最大精度を求める構成ではなく、応答品質、記憶使用量、生成速度の均衡を取るための選択である。

Ollama のモデルライブラリーには、qwen3.5:9b-q4_K_M のタグ、量子化形式、容量、対応する最大コンテキスト長が掲載されている[12]。本稿の構築時点では、モデルファイルは約 6.6 GB である。ただし、この値は SSD 上のモデルファイル容量であり、実行時の総記憶使用量を表すものではない。

ollama pull が完了した後、ollama list でモデル名と保存容量を確認する。ollama show では、モデル系列、量子化形式、対応機能、モデルに設定されたパラメーターを確認できる。記事内ではタグを省略せず、検証した量子化形式まで含めて記録する。同じ qwen3.5:9b 系列でも、異なる量子化タグを使用すれば、容量と実行特性が変わるためである。

16 GB 機で継続的なメモリ圧迫、スワップの増加、著しい生成速度低下が起きる場合は、同じ系列の 4B 級モデルへ変更する。モデル規模を下げる際も、どの量子化形式を使用したかを固定する。単に qwen3.5:4b と記録すると、後に既定タグの内容が変わった場合、同じ構成を再現できなくなる。

生成用モデルの変更は、既存文書の再登録を必要としない。文書と質問をベクトルへ変換する埋め込みモデルを維持する限り、Qdrant 内の索引はそのまま利用できる。生成用モデルを 9B 級から 4B 級へ変更した場合に比較するのは、同じ検索結果に対する回答の忠実性、文章品質、速度、記憶使用量である。

3.3 生成 API を単体で試験する

Open WebUI を起動する前に、Ollama の生成 API へ直接要求を送り、日本語入力から回答を生成できることを確認する。ここで失敗する場合、原因は Open WebUI や Qdrant ではなく、Ollama の起動、モデル取得、モデル読み込み、または生成処理にある。

/api/generate は、モデル名と入力文を受け取り、生成結果を返す。既定では応答が逐次返されるため、検証では stream を false にして、一つの JSON として結果と計測値を取得する。思考出力に対応するモデルでは、検証対象を最終回答へ限定するため、think も false に固定する。

response に日本語の回答が入り、done が true になれば、生成要求は最後まで完了している。質問内容に対する正確さは別途評価する必要があるが、少なくとも Open WebUI を介さない生成経路が成立したことを確認できる。

Ollama の非逐次応答には、入力処理時間、生成時間、入出力トークン数などの計測値が含まれる[13]。各時間はナノ秒で返されるため、秒へ換算して記録する。出力速度は、eval_count を eval_duration の秒数で割ることで求められる。

初回要求では、モデルを SSD からユニファイドメモリへ読み込むため、load_duration が大きくなる。モデルが待機状態に残っている間に同じ要求を再実行すると、読み込み時間が短くなる場合がある。初回値と連続実行値を混在させず、少なくとも二回実行して区別する。

ollama ps では、生成後にモデルがどの処理装置へ読み込まれたかを確認する。CPU への退避が増えている場合、モデル自体は動作しても生成速度が大きく低下する可能性がある。回答文だけでなく、PROCESSOR、CONTEXT、生成速度を併記することで、MacBook Pro 上で継続利用できる構成かを判断できる。

3.4 埋め込みモデルを取得する

埋め込みは、文章を固定長の数値ベクトルへ変換する処理である。生成用 LLM が文章を出力するのに対し、埋め込みモデルは文章同士の意味的な近さを計算できる表現を出力する。得られたベクトルは、意味検索、類似文書検索、分類、ベクトルデータベース、RAG に使用される[14]。

本構成では embeddinggemma を使用する。生成用モデルと埋め込みモデルを分離することで、回答生成に必要な規模と、文書検索に必要な処理を個別に選択できる。埋め込み処理に 9B 級の生成モデルを流用せず、検索用に設計された小型モデルを使うため、文書登録と質問検索の負荷を抑えられる。

ollama list では、生成用の qwen3.5:9b-q4_K_M と埋め込み用の embeddinggemma が別々のモデルとして表示される。ollama show embeddinggemma では、モデルの詳細と埋め込み機能への対応を確認する。

Ollama の埋め込み API は、入力された文章ごとに数値配列を返す[15]。一つの文章を入力した場合も、複数の文章をまとめて入力した場合も、応答の embeddings は配列の配列となる。外側の要素数は入力文章数に対応し、内側の要素数は埋め込みベクトルの次元数に対応する。

埋め込みモデルを変更する場合、Qdrant に保存済みのベクトルをそのまま使ってはならない。モデルが変わると、ベクトルの次元数が同じであっても、各数値が表す配置規則は変わる。文書側だけが旧モデル、質問側だけが新モデルという状態では、距離計算を実行できても、意味的な類似度として解釈できない。

3.5 埋め込み API を単体で試験する

埋め込み API の単体試験では、入力数、ベクトル数、次元数を確認した後、意味の近い文章が相対的に近い値を示すかを確認する。配列が返ったという事実だけでは、選択したモデルが日本語の検索に利用できるかまでは判断できない。

次の試験では、ローカル LLM に関する二文と、話題の異なる一文を同時に埋め込む。文章埋め込みは、表面的な文字列の一致だけではなく、意味的に近い文章を近いベクトルとして比較するために設計される[16]。

vectors が 3 であり、三つの dimensions が同じ正の値であれば、各入力が同じ次元のベクトルへ変換されたことを確認できる。ただし、これは API の出力形状が正しいことを示すだけであり、意味検索の品質を示すものではない。

意味的な配置は、ベクトル間のコサイン類似度を計算して確認する。次の処理では、一文目と二文目、一文目と三文目の類似度を比較する。

local_llm_similarity が unrelated_similarity より高ければ、この三文に対しては、ローカル LLM に関する二文が、冷蔵庫に関する文より近く配置されたことになる。この一回の結果だけで検索品質全体を保証することはできないが、日本語入力、ベクトル生成、類似度計算までの最小経路を確認できる。

RAG では、文書登録時と質問時に同じ埋め込みモデルを使用するだけでなく、モデルの版とタグも固定する。埋め込みモデルを更新または変更した場合は、既存の Qdrant コレクションを新しいモデルで作成したベクトルへ置き換える。新旧ベクトルを同じコレクションへ混在させると、検索結果が不安定になっても原因を追跡できない。

3.6 コンテキスト長を必要以上に広げない

コンテキスト長は、生成用 LLM が一回の要求で参照できる入力と出力の上限である。RAG では、利用者の質問、会話履歴、システム指示、検索された文書断片が同じコンテキストを消費する。取得件数またはチャンクサイズを増やすと、モデルへ渡す根拠は増えるが、その分だけ記憶使用量と入力処理時間も増える。

モデルが対応する最大コンテキスト長と、実行時に確保されるコンテキスト長は異なる。qwen3.5:9b-q4_K_M のモデル情報に 256K と表示されていても、MacBook Pro 上で常に 256K が割り当てられるわけではない。Ollama は利用可能な計算資源と設定に応じて実行時の長さを決め、長いコンテキストほど多くの記憶領域を使用する[17]。

初期検証では、Open WebUI のモデル設定を 8192 トークンから開始する。三件の短いチャンクと質問を入力する構成で不足が確認された場合は、16384 トークンへ増やす。上限値を先に最大化するのではなく、実際に取得するチャンク数、文書断片の長さ、会話履歴に対して必要な範囲だけを割り当てる。

設定後は、生成要求を一度実行してから ollama ps を確認する。

CONTEXT には実行中モデルへ割り当てられたコンテキスト長が表示される。PROCESSOR では、モデルが GPU 側へどの程度配置され、CPU 側へ退避しているかを確認する。設定したコンテキスト長を増やした後に CPU 側への退避が増え、生成速度が大きく低下した場合、その設定はモデルの上限内であっても、その MacBook Pro における実用値ではない。

RAG の目的は、文書全体を最大コンテキストへ詰め込むことではない。質問に必要な断片を埋め込み検索で選び、生成用 LLM へ渡す入力を限定することにある。チャンクサイズ 1000 文字、重複 100 文字、取得件数 3 件という初期条件で正しい根拠を取得できるなら、256K の最大値を確保する理由はない。

この章の完了条件は、生成用モデルと埋め込みモデルの名前が ollama list に表示されることではない。生成 API が日本語回答と計測値を返し、埋め込み API が入力数と一致するベクトルを返し、意味の近い文章が相対的に近く配置され、実行時のコンテキスト長と処理装置を ollama ps で確認できるところまでである。この単体試験を先に終えることで、後続の Open WebUI 接続や Qdrant 登録で障害が起きた際に、Ollama 側を切り分け済みの前提として扱える。

4. Docker Compose で Open WebUI と Qdrant を構築する

4.1 作業ディレクトリを作る

構成ファイル、永続データ、検証文書、バックアップを一つの作業ディレクトリへまとめる。Open WebUI と Qdrant の保存領域は分離し、どのサービスがどの状態を保持しているかをディレクトリ単位で判別できるようにする。

Open WebUI の保存領域には、利用者情報、会話、Knowledge の管理情報、アプリケーション設定が含まれる。Qdrant の保存領域には、埋め込みベクトル、文書断片に対応する付随情報、コレクションの索引が置かれる。両者を同じディレクトリへ混在させると、バックアップ、復元、障害調査の対象を分離できない。

この分離により、回答生成、文書管理、ベクトル検索のどこで状態が失われたかを判断できる。たとえば、Open WebUI の画面に文書が残っているのに検索できない場合は Qdrant 側を調べ、Qdrant にコレクションが残っているのに Knowledge が表示されない場合は Open WebUI 側の管理情報を調べる。

4.2 秘密値と版を環境変数ファイルへ記録する

Qdrant の API 鍵、Open WebUI の秘密鍵、使用するイメージ版、モデル名を .env へ記録する。Qdrant は QDRANT__SERVICE__API_KEY による API 鍵認証を設定できる[18]。本構成では 6333 番ポートを 127.0.0.1 に限定したうえで、Open WebUI からの接続にも同じ API 鍵を要求する。

WEBUI_SECRET_KEY は、Open WebUI がセッションや暗号化対象の情報を継続して扱うための秘密値である。コンテナーの再作成ごとに値が変わると、既存のセッションや暗号化済み情報を利用できなくなる可能性があるため、初回構築時に生成した値を更新後も維持する。

.env を書き込む前に権限を 600 にする。書き込み後に権限を変更するだけでは、生成から chmod までの短時間、通常の umask に基づく権限でファイルが存在する可能性がある。空ファイルを先に作成して権限を制限し、その後で秘密値を書き込む。

イメージ名には latest や main を使用せず、Open WebUI 0.10.2 と Qdrant 1.18.2 を固定する。固定しない場合、同じ docker compose pull を実行しても取得される実装が変わり、環境変数、保存形式、検索処理のどこで挙動が変化したかを追跡できなくなる。

GENERATION_MODEL は、この章の Compose 構成から Open WebUI へ直接渡す値ではない。検証に使用するモデル名を構成情報と同じ場所へ記録し、後続の設定確認や試験用コマンドで再利用するために置く。これに対して EMBEDDING_MODEL は、Open WebUI の埋め込みモデル設定へ渡される。

ENABLE_SIGNUP は、初回の管理者登録を行うため、構築時には True とする。最初の利用者を登録した後、この値を False へ変更してコンテナーを再作成する。Open WebUI が初回登録後に新規登録を停止しても、環境変数を構成の正とする場合、再起動時に True が再適用されないよう明示的に固定する必要がある。

.env には認証情報が含まれるため、Git へ登録しない。Open WebUI と Qdrant の実データも、容量が大きく、実行時に更新され続けるため、通常のソースコード管理から除外する。

documents は除外していない。架空情報を含む検証文書を版管理すれば、どの原文からどの検索結果を得たかを後から再現できる。ただし、実際の業務文書や個人情報を登録する場合は、文書の機密区分に応じて documents も除外する。

4.3 compose.yaml を作成する

Open WebUI は Docker を主要な導入方法として案内し、/app/backend/data へ永続領域を割り当てる構成を提供している[19]。Open WebUI の環境変数では、Ollama の接続先、埋め込みエンジン、ベクトルデータベース、Qdrant の接続情報、検索件数、文書分割条件を指定できる[20]。

Qdrant は 6333 番ポートを HTTP API と管理画面に使用し、Docker イメージでは /qdrant/storage へ永続データを保存する[21]。スナップショットは通常の保存領域と分離し、コンテナーの再作成後も残るようにする。

docker compose config –quiet が出力なしで正常終了すれば、YAML の構文、必須変数の展開、サービス定義を読み取れる状態である。通常の docker compose config は展開後の構成を表示するため、QDRANT_API_KEY と WEBUI_SECRET_KEY も画面へ出力される。単純な構文確認では –quiet を使い、秘密値を端末のログや共有画面へ残さない。

ENABLE_PERSISTENT_CONFIG=False を指定すると、対象となる設定では環境変数が管理画面の保存値より優先される。管理画面で値を変更すると実行中の状態へ反映される場合があるが、コンテナーを再起動すると Compose に記述した値へ戻る。検索件数やチャンク条件を変更する場合は、管理画面だけで変更せず、.env または compose.yaml を更新してコンテナーを再作成する。

ENABLE_PLUGINS=False は指定していない。この設定は追加機能だけでなく、組み込みのツール呼び出し経路にも影響するため、Knowledge の取得方式まで同時に変化させる可能性がある。本稿では、外部生成 API、ウェブ検索、実験的な Knowledge 操作を個別に無効化し、標準的な文書登録とベクトル検索の経路を残す。

Docker Desktop では host.docker.internal がホスト接続用の名前として提供されるため、MacBook Pro 専用の本構成では extra_hosts を追加しない。Open WebUI から Ollama へ接続できない場合は、名前を追加する前に、ホスト上の 11434 番ポートとコンテナー内での名前解決を個別に確認する。

4.4 Qdrant を先に起動する

Compose の depends_on は、依存関係に基づくコンテナーの起動順を制御する。ただし、短い形式の depends_on は、Qdrant のプロセスが API 要求を受け付けられる状態になるまで Open WebUI の起動を待つものではない[22]。初回構築では Qdrant だけを先に起動し、認証付き API の応答を確認してから Open WebUI を起動する。

docker compose pull では、.env に固定した二つのイメージを取得する。Qdrant のログでは、設定の読み込み失敗、保存領域の権限エラー、既存データの読み込みエラー、6333 番ポートの待ち受け開始を確認する。コンテナーが running でも、起動直後の初期化に失敗して再起動を繰り返している場合があるため、状態とログの両方を見る。

次に、.env を一時的なサブシェルへ読み込み、API 鍵付きでコレクション一覧を取得する。サブシェルを使うことで、秘密値を現在のシェル環境へ残さない。

初回は collections が空でよい。HTTP 200 の JSON が返れば、Qdrant のプロセス、6333 番ポートの割り当て、API 鍵認証、REST API までが成立している。まだ Open WebUI を起動していないため、コレクションが存在しないことは異常ではない。

4.5 Open WebUI を起動する

Qdrant の API 応答を確認した後、Open WebUI を起動する。起動時には、Ollama の接続先、埋め込みモデル、Qdrant の接続情報、文書分割条件が読み込まれる。環境変数名が誤っていてもコンテナー自体は起動する場合があるため、画面が表示されることだけで設定完了とは判断しない。

Open WebUI のログでは、データベースの初期化、Ollama 接続、Qdrant 接続、起動時の例外を確認する。起動直後に Ollama への接続警告が出た場合は、macOS 上で http://localhost:11434/api/tags が応答することと、Open WebUI コンテナーから host.docker.internal を解決できることを分けて調べる。

ブラウザーで http://localhost:3000/ を開く。新規の保存領域では、最初に登録した利用者が管理者となり、その登録処理によって新規登録は停止される。ただし、本構成では環境変数を再起動時の正としているため、.env の ENABLE_SIGNUP=True を残したままコンテナーを再作成すると、新規登録が再び有効になる可能性がある。

最初の管理者としてログインできることを確認した後、.env の値を False へ変更し、Open WebUI コンテナーを再作成する。

最後のコマンドが False を表示すれば、再作成後も新規登録を無効にする環境変数がコンテナーへ渡されている。ログアウト後に新規登録画面が表示されないことも確認する。管理者アカウントの作成前に False へ変更すると、最初の利用者を登録できなくなるため、順序を逆にしてはならない。

Open WebUI の画面が応答することは、次のコマンドでも確認できる。

HTTP 200 が返れば、3000 番ポートの割り当てと Open WebUI の HTTP 応答は成立している。ただし、この確認では、Ollama のモデル一覧を取得できるか、Qdrant へ接続できるか、文書から埋め込みを生成できるかまでは分からない。それらは管理画面の設定値、コンテナーのログ、後続の文書登録試験で確認する。

ENABLE_OPENAI_API=False と ENABLE_WEB_SEARCH=False は、Open WebUI から外部生成 API とウェブ検索を利用しないための設定である。ただし、この二つだけでコンテナーからの全外向き通信が存在しないことを証明するものではない。厳密な閉域運用が必要な場合は、Docker の通信、名前解決、更新確認をネットワーク観測またはファイアウォールで検証する。

この章の完了条件は、二つのコンテナーが running と表示されることではない。版と秘密値を固定した構成を検証でき、Qdrant が API 鍵付きの要求へ HTTP 200 を返し、Open WebUI の管理者を作成し、再作成後も新規登録を閉じ、Open WebUI と Qdrant の状態をそれぞれの永続領域へ保存できるところまでである。ここまでを独立して確認することで、後続の文書登録で問題が起きた場合に、コンテナー構築と認証を切り分け済みの前提として扱える。

5. Ollama、Open WebUI、Qdrant の接続を一方向ずつ確認する

5.1 Open WebUI コンテナーから Ollama API への接続を確認する

最初に、macOS 上の Ollama が取得済みモデルを返すことを再確認する。次に、同じ API を Open WebUI コンテナー内から呼び出す。ホスト上の確認とコンテナー内の確認を分けることで、Ollama 自体の障害と、Docker Desktop をまたぐ通信の障害を区別できる。

この要求で qwen3.5:9b-q4_K_M と embeddinggemma が表示されれば、Ollama API とモデル保存状態は正常である。ただし、これは macOS 内の localhost から接続できることを示すだけであり、Open WebUI コンテナーから到達できることまでは証明しない。

Open WebUI コンテナーからは、host.docker.internal を使用して同じ API を呼び出す。

status=200 と二つのモデル名が表示されれば、Open WebUI コンテナーから macOS 上の Ollama までの通信経路は成立している。この確認は Open WebUI の画面や内部設定を介さず、Docker Desktop の名前解決、ホストへの転送、Ollama API の応答だけを検証する。

通信試験に成功した後、Open WebUI のモデル選択欄に qwen3.5:9b-q4_K_M が表示されることを確認する。コンテナーから API を直接呼び出せるのに画面へモデルが表示されない場合は、ネットワークではなく、Open WebUI が実際に読み込んだ接続設定を調べる。

OLLAMA_BASE_URL が http://host.docker.internal:11434、ENABLE_PERSISTENT_CONFIG が False であることを確認する。本構成では永続データベース内の旧設定ではなく、Compose から渡した環境変数を設定の正とするため、管理画面に保存された接続先との優先関係を個別に調整する必要はない[20]。

.env または compose.yaml を変更しただけでは、既に動作しているコンテナーの環境変数は変わらない。設定値が異なる場合は、Open WebUI コンテナーを再作成する。

環境変数、コンテナーからの直接接続、Ollama API のモデル一覧がすべて正常であるにもかかわらず、画面にモデルが表示されない場合は、Open WebUI の管理画面にある Ollama 接続設定とログを確認する。設定を無計画に追加するのではなく、Compose で指定した接続先と同じ値になっているかを比較する。

5.2 Open WebUI から Ollama の生成 API への経路を確認する

モデル一覧の取得は、Open WebUI が Ollama の読み取り API へ接続できることを示す。文章生成まで成立するかを確認するには、Open WebUI から実際に生成要求を送る必要がある。新しい会話を作成し、Knowledge、添付ファイル、ウェブ検索、追加ツールを接続しない状態で qwen3.5:9b-q4_K_M を選択する。

日本語の回答が返れば、ブラウザー、Open WebUI、Docker からホストへの通信、Ollama の生成 API、生成用モデルという経路が一続きに成立している。ただし、この試験では文書を登録しておらず、Knowledge も接続していないため、埋め込みモデルと Qdrant は使用されない。

この通常対話は、後続の RAG 試験に対する対照条件となる。通常対話で回答できる一般知識だけを RAG の試験質問に使うと、Knowledge を接続した効果を判定できない。そのため、RAG の本試験では、通常対話では知り得ない架空の固有情報を使用する。

通常対話が失敗した場合は、Qdrant や文書分割の設定を変更しない。Knowledge を接続していない対話には、それらの設定が関与しないためである。Open WebUI のログと Ollama の状態を確認し、生成経路を復旧してから文書登録へ進む。

Open WebUI のログに Ollama API の接続エラーがなく、ollama ps に qwen3.5:9b-q4_K_M が表示されれば、要求は生成用モデルまで到達している。モデルが表示されない場合は、画面上で選択したモデル名、Ollama に保存されたタグ、Open WebUI が送信した要求を照合する。

5.3 Open WebUI コンテナーから Qdrant への接続を確認する

Qdrant は http://127.0.0.1:6333/dashboard で管理画面を提供する。管理画面では、コレクションと点の確認、REST API の実行、スナップショットの操作ができる[23]。API 鍵を求められた場合は、.env に保存した QDRANT_API_KEY を入力する。

管理画面を開けることは、MacBook Pro のブラウザーから Qdrant へ接続できることを示す。ただし、Open WebUI コンテナーはホスト側の 127.0.0.1:6333 ではなく、Docker Compose ネットワーク内の qdrant:6333 へ接続する。ブラウザーからの接続とコンテナー間通信は別々に確認する必要がある。

status=200 とコレクション一覧が返れば、Open WebUI コンテナーから Qdrant までの名前解決、HTTP 接続、API 鍵認証が成立している。文書登録前には、一覧が空であっても異常ではない。接続経路の確認では、コレクション数ではなく、認証付き要求が正常終了することを判定条件とする。

文書登録前の状態を API から保存する。後続の登録後に同じ要求を実行し、コレクションの増加と点数の変化を比較する。

この基準値を残すことで、文書登録後に作成されたコレクションを既存データと区別できる。Open WebUI の版や設定によってコレクション名が変わる可能性があるため、特定の名称が作成されることを前提にせず、登録前後の差分で判定する。

5.4 ローカル処理経路として設定されていることを確認する

Open WebUI は、Ollama 以外の生成 API、外部の埋め込みサービス、ウェブ検索、複数のベクトルデータベースにも接続できる。本構成がローカル RAG になるのは、Open WebUI や Ollama という製品を使用しているためではない。生成、埋め込み、検索、文書抽出の各処理先を、MacBook Pro と Docker Desktop の内部へ明示的に配置しているためである。

実行中の Open WebUI コンテナーへ、Compose で指定した接続設定が渡されていることを確認する。

ENABLE_OPENAI_API=False と ENABLE_WEB_SEARCH=False は、Open WebUI から外部生成 API とウェブ検索を利用しないための設定である。RAG_EMBEDDING_ENGINE=ollama と VECTOR_DB=qdrant により、埋め込み生成とベクトル保存もローカルの接続先へ固定する。

ただし、これらの設定だけで、Open WebUI コンテナーと Ollama の全外向き通信が遮断されたことにはならない。Docker Desktop の通常のネットワークには外部への通信経路があり、モデル取得、イメージ取得、更新確認など、RAG の回答処理とは異なる通信が発生する可能性がある。ここで確認できるのは、質問から回答までの生成、埋め込み、検索、文書抽出の接続先がローカルへ設定されていることである。

この区別を設けないと、「ローカルモデルを選択した」「ウェブ検索を無効にした」という画面上の設定だけで、外部通信が一切ないと誤認する。ローカル RAG の構成確認では、回答を作るデータ経路と、端末全体のネットワーク隔離を別の要件として扱う必要がある。

この章の完了条件は、Open WebUI の画面に生成用モデルが表示されることだけではない。macOS から Ollama API を呼び出せること、Open WebUI コンテナーから同じ API へ到達できること、Knowledge を接続しない通常対話が成功すること、Open WebUI コンテナーから認証付きで Qdrant へ接続できること、文書登録前のコレクション状態を記録できることまでを個別に確認する。これにより、次章の文書登録で障害が起きた場合は、生成経路とデータベース接続を切り分け済みの前提として、文字抽出、チャンク分割、埋め込み生成、ベクトル保存を調べられる。

6. 文書を検索可能なチャンクへ変換する

6.1 文脈を外部化して検索対象にする

利用者固有の判断基準、運用手順、例外条件は、生成用 LLM の内部知識には含まれていない。会話のたびに説明しなければ参照できない情報を継続的に利用するには、暗黙知を文書として外部化し、検索可能な情報構造へ変換する必要がある[24]。

外部化とは、単に文章として保存することではない。対象、条件、値、例外、判断主体の対応関係を、文書を分割した後にも読み取れる形で記述する。たとえば「47821」という数値だけを記録しても、それが本番ポートなのか、障害番号なのか、時刻なのかを検索結果から確定できない。「Argolet の本番保守ポートは 47821 である」と記述することで、名称、環境、用途、値が一つの意味単位になる。

Open WebUI の Knowledge は、複数の会話から再利用する文書集合を管理する単位である。Focused Retrieval を使用すると、登録文書を質問のたびに全文投入するのではなく、質問と意味的に近いチャンクを検索して生成用 LLM へ渡す[25]。本構成では RAG_FULL_CONTEXT=False としているため、Knowledge 全文ではなく、Qdrant から取得した上位 3 件のチャンクが回答生成の候補になる。

Knowledge へ登録する情報は、回答文そのものではなく、回答を決める根拠として記述する。運用担当者が「本番ポートは何か」と質問する場合、文書にはポート番号だけでなく、本番環境と開発環境の区別を残す。緊急停止方法を尋ねる場合は、手順名だけでなく、操作順序と適用条件を残す。検索された一つのチャンクだけを読んでも判断できる記述にすることで、生成用 LLM が欠落部分を推測する余地を減らせる。

6.2 対照試験用の Markdown を作る

RAG の成立を検証するには、生成用 LLM が事前知識から正答できない文書を用意する。実在する製品、一般的なポート番号、既知の運用用語を使うと、Knowledge を参照しなくても回答できる可能性が残る。そこで、架空のシステム名、一般的な規則から導けない数値、造語による手順名を組み合わせる。

検証文書には、正答対象だけでなく、取り違えや推測を検出するための対照情報も入れる。本番ポートと開発ポートを近い値にし、質問対象の環境を識別しなければ正答できない形にする。文書に記載していない開発責任者名も明示し、情報不足の質問に対して架空の人物名を生成しないかを確認する。

短い文書であっても、名称、値、条件、例外を別々の見出しへ配置する。Markdown の見出しは文書構造を示すだけでなく、本構成ではチャンク分割の前処理にも使用される。見出し単位で話題を分離することで、本番接続の質問に対して緊急停止や復旧条件の記述が同じ検索単位へ混入しにくくなる。

作成後は、登録する原文を記録する。後から文書を書き換えて再登録した場合、旧ベクトルと新しい原文を混同すると、検索結果の差が設定変更によるものか文書変更によるものかを判定できない。

この文書では、単純な正答率だけでなく、条件識別、手順保持、情報不足時の抑制を試験できる。RAG が機能していても、取得チャンクに必要な条件が含まれなければ、生成用 LLM は部分的に正しい回答を返す。複数の失敗形式を一つの短い文書へ埋め込むことで、検索と生成のどちらに調整が必要かを判別しやすくする。

6.3 Open WebUI に Knowledge を作る

Open WebUI で Knowledge を作成し、検証文書を登録する。

1. Open WebUI へ管理者または Knowledge の編集権限を持つ利用者としてログインする。
2. Workspace を開く。
3. Knowledge を開き、新しい Knowledge を作成する。
4. 名称を Argolet Operations とする。
5. 検索方式として Focused Retrieval を使用する。
6. documents/argolet.md をアップロードする。
7. 処理中の表示が終了し、ファイルが利用可能な状態になることを確認する。

ファイルを会話へ直接添付する方法でも、その会話内で文書を参照できる。Knowledge は、同じ文書集合を複数の会話やモデル設定から再利用する場合に使う。運用手順、仕様書、規程のように継続して参照する文書は Knowledge とし、一回限りの確認資料とは管理単位を分ける。

アップロード後、Open WebUI は文書の内容を抽出し、Markdown の見出し構造を前処理し、各部分を設定した大きさへ分割する。続いて各チャンクを embeddinggemma でベクトル化し、原文断片や出典情報とともに Qdrant へ保存する。画面上でファイル名が表示された段階と、検索用データの保存が完了した段階は同じとは限らない。

処理中に失敗した場合は、同じファイルを繰り返しアップロードする前にログを確認する。再試行のたびに中途半端な登録情報や別の点が作成されると、後から点数とチャンク数の関係を追跡しにくくなる。

登録処理中または登録直後に ollama ps へ embeddinggemma が表示されれば、Open WebUI から埋め込み要求が送られたことを確認できる。ただし、モデルが読み込まれたことだけでは、すべてのチャンクが Qdrant へ保存されたとは判断できない。次章では登録前後のコレクションと点数を比較し、保存段階まで確認する。

6.4 チャンク分割の意味

Open WebUI は文書をチャンクへ分割し、各チャンクを検索と埋め込みの単位にする。現在の構成では、ENABLE_MARKDOWN_HEADER_TEXT_SPLITTER=True により、Markdown の見出しが最初の分割境界として使われる。その後、各見出し内の文章が RAG_TEXT_SPLITTER=character、CHUNK_SIZE=1000、CHUNK_OVERLAP=100 の条件で追加分割される[26]。

見出し前処理と文字数分割は、どちらか一方だけが使われるのではない。最初に「本番接続」「緊急停止」「復旧条件」という文書構造を分離し、各部分が 1000 文字を超える場合に文字分割を適用する。この順序により、異なる見出しの話題を一つの大きなチャンクへまとめにくくしながら、長い節も検索可能な大きさへ制限できる。

今回の argolet.md は短いため、各見出しの本文が 1000 文字未満に収まる可能性が高い。その場合、チャンク数は単純に文書全体の文字数を 1000 で割った値にはならない。見出し前処理、付随情報、分割器の境界判断によって、見出しごとに複数のチャンクが生成される場合がある。

チャンクサイズを小さくすれば検索精度が自動的に上がるわけではない。たとえば「復旧を開始できるのは」という文と、「15 分間連続して 0.20 未満」という条件が別々のチャンクへ分かれると、検索結果には閾値だけが残り、継続時間を欠いた回答が生成される。検索対象を細かくするほど、各断片が単独で判断根拠として成立しているかを確認しなければならない。

大きいチャンクにも別の失敗がある。本番接続、開発接続、緊急停止、復旧条件を一つのチャンクへまとめると、「本番ポート」という質問に対して 47821 と 47822 の両方が生成入力へ入る。埋め込み検索には成功していても、生成用 LLM が二つの値を取り違える可能性が高くなる。

重複量は、境界で失われる文脈を補うために使う。重複した 100 文字が、前チャンクの条件と次チャンクの操作を接続する場合には有効である。一方、短い文書で重複量を増やすと、ほぼ同じ内容のチャンクが複数作られ、取得件数 3 件のすべてを類似断片が占める場合がある。重複量は保存容量だけでなく、検索結果の多様性にも影響する。

チャンク条件を変更した場合、Qdrant に保存済みの点へ自動的に新しい境界が適用されるわけではない。登録済み文書を削除または再処理し、新しい設定で文字抽出、分割、埋め込み、保存をやり直す必要がある。設定だけを変更して同じ索引を検索すると、画面上の設定値と実際のチャンク構造が一致しない。

6.5 長いコンテキストと検索精度を区別する

生成用 LLM が長い入力を受け付けられることと、その入力内の必要情報を安定して利用できることは同義ではない。複数文書を含む長いコンテキストでは、関連情報が入力の中央付近に配置された場合、先頭または末尾にある場合より性能が低下する傾向が報告されている[27]。

この性質があるため、モデルの最大コンテキスト長を広げ、登録文書をすべて入力すれば RAG が不要になるとは限らない。全文投入では、質問と無関係な記述も入力処理の対象になり、複数の類似値や例外規則が生成用 LLM の判断を競合させる。入力可能であることは、必要な根拠を選択できることを保証しない。

RAG は、コンテキスト長の上限を回避するだけの仕組みではない。質問ごとに候補文書を絞り、回答へ使用する根拠を観察可能な単位に限定する仕組みでもある。Argolet の本番ポートを尋ねた場合は本番接続のチャンクを取得し、復旧条件を尋ねた場合は Rho-Blue の条件を含むチャンクを取得する。検索結果を限定することで、生成用 LLM が判断すべき範囲を狭められる。

初期値の 1000 文字、重複 100 文字、取得件数 3 件は、最適値ではなく比較の出発点である。質問ごとに、正しいチャンクが取得されたか、必要条件が一つのチャンクに残っているか、無関係なチャンクが生成へ混入したかを記録し、その結果に基づいて一項目ずつ変更する。

6.6 文字抽出の失敗を先に疑う

文書検索で期待する回答が得られない場合、生成用 LLM やベクトル検索の性能を調整する前に、原文から必要な文字が抽出されたかを確認する。抽出されなかった文字列はチャンクに含まれず、埋め込みベクトルにも反映されない。検索設定を変更しても、存在しない文字情報を取得することはできない。

Markdown のようなプレーンテキストでは、原文と抽出結果の差が小さいため、RAG の最小経路を確認しやすい。PDF では、画面上に文字が見えていても、内部に文字層がなく、各ページが画像として保存されている場合がある。複雑な段組み、脚注、表、縦書き、図中の文字も、読み順の崩れや欠落を起こしやすい。

Open WebUI の RAG 障害確認でも、文書取り込み、Knowledge の接続、埋め込み、検索条件、モデルへ渡されたコンテキストを分けて調べる必要がある[28]。回答が誤っているという最終結果だけでは、抽出、分割、検索、生成のどこで情報が失われたかを判定できない。

本構成では PDF_EXTRACT_IMAGES=False とし、画像 OCR を処理経路へ含めない。OCR を有効にすると、画像解析、言語判定、文字認識、読み順復元という別の処理が加わり、検索失敗の原因が増える。最初に Markdown で文字抽出から回答生成までを成立させ、その後に文字層のある HTML や PDF へ対象を広げる。

画像だけの PDF や図表中心の資料を扱う場合は、単に OCR を追加するだけでは不十分である。数値を認識できても、表のどの列に属するか、図中の矢印が何を結ぶか、注記がどの値を制約するかを保持できなければ、検索可能な根拠にはならない。位置関係に依存する内容は、判断に必要な関係を文章として明示した補助文書を用意する方が再現性を確保しやすい。

6.7 文書登録工程の完了条件を固定する

文書登録の完了は、Knowledge にファイル名が表示されたことでは判定しない。原文が再現可能な状態で保存され、固有情報が文字として存在し、Open WebUI が処理を完了し、埋め込みモデルが呼び出され、Qdrant の保存内容が登録前から変化したところまでを確認する。

この章で確立するのは、文書をアップロードする操作ではない。利用者固有の規則を検索可能な意味単位として記述し、見出しと文字数に基づいて分割し、各チャンクを embeddinggemma のベクトルへ変換できる入力を作ることである。RAG の回答品質は生成用 LLM だけでは決まらず、質問に必要な条件を一つの根拠として取り出せるよう、登録前の文書を設計した段階で大きく制約される。

7. 埋め込みと Qdrant の保存状態を確認する

7.1 文書登録前後のコレクションを比較する

Qdrant のコレクションは、検索対象となる点をまとめる名前付きの集合である。各点はベクトルと付随情報から構成され、同じコレクションの同じベクトル項目では、次元数と距離尺度をそろえる必要がある[29]。文書登録後には、Open WebUI が作成または再利用したコレクションへ、文書チャンクに対応する点が保存される。

第 5 章では、文書登録前のコレクション一覧を /tmp/qdrant-collections-before.json へ保存した。Knowledge への登録後に同じ API を呼び出し、登録後の一覧を別ファイルへ保存する。

登録前後の一覧から、追加されたコレクション名と削除されたコレクション名を比較する。

新しいコレクションが表示された場合、文書登録によって Qdrant の構成が変化したことを確認できる。ただし、新しい名前が増えなかったことだけで登録失敗とは判断しない。本構成では ENABLE_QDRANT_MULTITENANCY_MODE=True を指定しており、Open WebUI は同種のベクトルデータを共有コレクションへ集約できる[20]。既存コレクションへ点が追加された場合、コレクション名の一覧は登録前後で変化しない。

Open WebUI が使用するコレクションには既定の接頭辞があるが、名称規則は Open WebUI の版、データ種別、複数利用者モード、設定値によって変化し得る。特定のコレクション名を記事の完成条件として固定せず、実際の一覧、点数、付随情報を組み合わせて対象を特定する。

コレクション一覧は、保存処理がどこかまで進んだことを確認する入口にすぎない。共有コレクションへの追加、既存点の更新、登録失敗を一覧だけで区別することはできないため、各コレクションの点数と設定を続けて確認する。

7.2 コレクションの点数とベクトル設定を確認する

Qdrant の点は、識別子、ベクトル、任意の JSON 形式の付随情報から構成される[30]。Open WebUI は、文書チャンクから生成した埋め込みベクトルに、元文書や Knowledge、利用者、チャンク本文を識別する情報を付けて保存する。

次の処理では、すべてのコレクションについて、点数、索引済みベクトル数、区画数、ベクトル設定を一覧表示する。API 鍵は出力せず、各コレクションの状態だけを表示する。

points_count が 0 より大きければ、そのコレクションに一つ以上の点が保存されている。短い Markdown 文書であっても、見出し分割、チャンク分割、付随情報の管理方法によって複数の点が作成される場合がある。原文の段落数と点数が一致することを前提にしてはならない。

indexed_vectors_count は、検索用索引へ組み込まれたベクトル数を示す。小規模なコレクションでは、点が存在していても索引化の閾値に達せず、全走査によって検索される場合がある[31]。そのため、indexed_vectors_count が points_count より少ないことや、検証用の小さなコレクションで 0 になることだけを保存失敗とは判定しない。

対象コレクションを特定したら、名前を COLLECTION へ設定し、詳細を個別に保存する。

コレクション名に空白や URL 上で特別な意味を持つ文字が含まれる場合は、管理画面から確認するか、Python の urllib.parse.quote で符号化して要求する。通常の Open WebUI 由来の名称では問題になりにくいが、API 操作では名称を無加工で安全と仮定しない。

7.3 埋め込みモデルの出力次元とコレクション設定を照合する

Qdrant に点が保存されていても、使用した埋め込みモデルとコレクションのベクトル次元が一致していなければ、同じ空間で質問を検索できない。第 3 章では embeddinggemma の埋め込み API が返す配列の次元を確認した。ここでは、現在の Ollama の出力と Qdrant の設定を同じ処理内で比較する。

dimension_match=True になれば、現在の embeddinggemma が返す次元数と、対象コレクションの少なくとも一つのベクトル設定が一致している。ただし、次元数の一致は必要条件であり、同じ埋め込みモデルを使用したことの十分条件ではない。

異なる埋め込みモデルが偶然同じ次元数を返す場合でも、文章を配置する意味空間は一致しない。Qdrant は配列の長さを検証できるが、その数値がどのモデルから生成されたかまでは判定しない。モデル名、版、登録日時を構成記録として保持し、変更後には既存文書を再索引する必要がある。

7.4 点の付随情報から文書本文を確認する

点数と次元数が正しくても、原文が空であったり、必要な文字列が抽出されていなかったりすれば、検索可能な根拠にはならない。対象コレクションから点を取得し、ベクトル本体を除外したうえで、JSON の付随情報を確認する。

with_vector を false にすることで、長い数値配列を表示せず、点の識別子と付随情報だけを確認できる。検証用文書は短いため 100 件を上限としているが、既存文書を多数含む共有コレクションでは、一回の取得だけで対象点が含まれない場合がある。その場合は Qdrant の管理画面、付随情報による絞り込み、または next_page_offset を使った続きの取得が必要になる。

取得した JSON 全体から、検証文書に含めた固有文字列を再帰的に検索する。

すべての固有文字列が見つかれば、少なくとも取得した点の付随情報に、検証文書の主要部分が文字列として保存されている。これにより、ファイル名だけが登録され、本文が空になっている状態を除外できる。

ただし、文字列が存在することは、質問時にその点が検索上位へ入ることを保証しない。付随情報の保存は登録経路の確認であり、質問ベクトルとの類似検索は次の段階である。本文が保存されているのに回答できない場合は、文字抽出ではなく、チャンク境界、検索順位、Knowledge の接続、生成用 LLM への投入を調べる。

7.5 Open WebUI と Qdrant のログを両側から確認する

通常対話が成功していても、文書登録時だけ障害が発生する場合がある。通常対話は生成用 LLM だけで成立するが、文書登録では文字抽出、チャンク分割、埋め込み生成、Qdrant 認証、点の保存が追加されるためである。

登録操作を行った時刻に近いログを、Open WebUI と Qdrant の両方から確認する。

grep の検索語は、版によって変化するログ表現を広く拾うためのものであり、特定の文字列が必ず出力されることを前提にしていない。該当行が見つからない場合は、絞り込みを外して同じ時間範囲のログ全体を見る。

障害調査では、最後に出力された一般的なエラー行だけでなく、最初の例外を確認する。埋め込み生成の失敗が原因で Qdrant への保存処理が呼ばれず、後続処理が別の空値エラーを出す場合がある。末尾の症状だけを修正すると、最初の原因が残る。

Open WebUI の RAG 障害は、文書処理、埋め込み、ベクトルデータベース、検索、生成への投入を分けて調べる必要がある[28]。チャット画面に表示された最終回答だけを見て、Qdrant または生成用 LLM のどちらが原因かを決めてはならない。

7.6 埋め込みモデルまたはチャンク条件を変更したら再索引する

埋め込みモデルを変更すると、次元数が同じであっても、文章が配置される意味空間が変わる。旧モデルで生成した文書ベクトルと、新しいモデルで生成した質問ベクトルは互換ではない。Open WebUI でも、埋め込みモデルを変更した場合は、Knowledge に属するすべての文書を再索引する必要がある[32]。

本構成では ENABLE_PERSISTENT_CONFIG=False としているため、埋め込みモデルの変更は管理画面だけで行わず、構成の正である .env を更新する。新しいモデルを Ollama へ取得した後、Open WebUI コンテナーを再作成し、実行中の環境変数を確認する。

model-name は実際に使用する Ollama のモデルタグへ置き換える。最後のコマンドで新しいモデル名が表示されても、既存の Qdrant の点は旧モデルで生成されたままである。環境変数の変更と Knowledge の再索引は別の工程として実行する。

Open WebUI の管理画面で Admin Panel、Settings、Documents を開き、Knowledge の再索引を実行する。再索引では、既存の Knowledge 用ベクトルを削除し、現在のチャンクサイズ、重複量、文字分割方式で文書を再分割し、現在の埋め込みモデルでベクトルを作り直す[32]。

再索引は既存の検索状態を書き換えるため、実行前に Open WebUI の保存領域と Qdrant の保存領域またはスナップショットを退避する。処理中に失敗すると、一時的に Knowledge から検索できない状態になる可能性がある。更新前の状態へ戻せることを確認してから実施する。

Open WebUI の Knowledge 再索引は、Knowledge に所属する文書を対象とする。会話へ直接添付したファイルのベクトルは同じ操作では更新されないため、埋め込みモデル変更後に再利用する場合は、各ファイルを再度アップロードする必要がある[32]。

再索引後には、コレクション一覧、点数、ベクトル次元、付随情報を再度確認する。画面上で再索引が完了したと表示されても、旧次元のコレクションが残っていたり、付随情報から本文が消えていたりする場合には、検索試験へ進まない。

7.7 保存工程の完了条件を固定する

Qdrant の保存確認では、コレクションが存在するという一つの事実だけを完成条件にしない。登録前後の変化、点数、ベクトル次元、付随情報、ログを組み合わせ、文字抽出からベクトル保存までの各段階を判定する。

ここまでの確認によって、Argolet の原文がチャンクへ分割され、embeddinggemma のベクトルとして Qdrant に保存され、回答時に再利用できる文字列が付随情報へ残っていることを確認できる。ただし、保存された点が質問に対して検索されるか、取得した断片が生成用 LLM へ渡されるか、文書に忠実な回答になるかはまだ確定していない。次の対照試験では、Knowledge を接続しない状態と接続した状態を比較し、保存されたベクトルが回答経路へ実際に使われることを確認する。

8. 対照試験によって RAG の成立を確認する

8.1 試験条件を固定する

RAG の成立は、Knowledge を接続した会話で正答が一度返っただけでは確認できない。生成用 LLM が偶然正しい値を生成した可能性、直前の会話履歴から情報を保持した可能性、質問文に含まれる語から推測した可能性が残るためである。Knowledge を接続しない対照条件と、接続した試験条件を同じモデル、同じ質問、同じ生成設定で比較する。

各試験は新しい会話で実行する。一つの会話で本番ポート、緊急停止、復旧条件を順番に尋ねると、前の回答や出典が後の質問へ残り、Qdrant から新たに取得した情報と会話履歴から再利用した情報を区別できなくなる。厳密な確認では、一問ごとに会話を作り直し、Knowledge の接続状態だけを変更する。

試験前には、Open WebUI のモデル選択欄に正しい生成用モデルが表示され、Argolet Operations に argolet.md が登録されていることを確認する。Qdrant の対象コレクションに点が存在し、付随情報に 47821、Lapis-7、Rho-Blue が含まれていることも前章の手順で確認しておく。

8.2 Knowledge を接続しない状態を対照条件とする

新しい会話を作成し、qwen3.5:9b-q4_K_M を選択する。Knowledge、ファイル、ウェブ検索、追加ツールを接続せず、次の質問をそのまま入力する。

Argolet は検証用に作成した架空のシステムであり、その本番保守ポートを生成用 LLM が正当に知る経路はない。期待する応答は、「情報がない」「確認できない」「文書を提示してほしい」といった回答保留である。別の数値を返した場合は、事前知識ではなく根拠のない補完として記録する。

未接続状態で偶然 47821 と答える可能性も理論上は残る。その場合、正答したという事実だけで RAG の成立を判定できない。出典がなく、登録文書も接続していないため、その回答は文書に根拠を持たない偶然の一致として扱う。

回答全文、使用モデル、Knowledge が未接続であること、試験日時を記録する。この結果は、Knowledge 接続後の回答と比較するための基準であり、未接続時の回答品質そのものを評価する試験ではない。

8.3 Knowledge を接続して同一質問を行う

別の新しい会話を作成し、同じ qwen3.5:9b-q4_K_M を選択する。Argolet Operations だけを接続し、未接続時と同じ質問を入力する。

期待する回答は 47821 である。回答に出典が表示される場合は、単に argolet.md の名前が表示されるだけでなく、「Argolet の本番保守ポートは 47821 である」という対応箇所が検索候補として取得されていることを確認する。

同じチャンクに開発環境の 47822 も含まれている場合、生成用 LLM は二つの値から本番環境に対応する値を選ばなければならない。47821 を返しただけでなく、本番用と開発用を取り違えていないことが、この質問の判定対象になる。

未接続時には回答を保留し、接続時には正しいチャンクを出典として 47821 を回答した場合、Knowledge の有無によって回答が変化したことを確認できる。ただし、この一問だけでは、単純な名称と数値の検索が成功したことしか分からない。手順、複合条件、未記載情報についても試験する。

8.4 手順と複合条件を別々に試験する

手順と復旧条件は、それぞれ新しい会話で試験する。両方の質問を本番ポートの会話に続けて入力すると、既に取得された Argolet 文書が会話履歴へ残り、質問ごとの検索結果を判定しにくくなる。

緊急停止試験では、Lapis-7 という名称だけを回答しても完全な正答とはしない。「接続キューを停止する」「その後に書き込み処理を停止する」という二工程と順序が必要である。操作順序を逆にした場合は、関連チャンクを取得できていても、生成時に因果関係を保持できなかったと判定する。

復旧条件では、Rho-Blue と 0.20 未満だけでは不十分である。「15 分間連続して」という継続条件を欠くと、一時的な閾値低下でも復旧を開始できるという別の規則になる。回答の一部に正しい語が含まれているかではなく、運用判断を決める条件がすべて保存されているかを確認する。

8.5 言い換えによって意味検索を確認する

元文書と同じ語を含む質問だけでは、意味検索ではなく、表面的な語の一致によって関連チャンクが取得された可能性が残る。別の新しい会話で、文書にない表現へ言い換えて質問する。

文書では「復旧を開始できる監視条件」と記述しており、質問では「サービスを再開してよいと判断する基準」と表現している。期待する回答は、Rho-Blue が 15 分間連続して 0.20 未満になることである。

この質問で復旧条件のチャンクを取得できれば、完全な文字列一致ではなく、質問と文書の意味的な近さを使って検索できたと判断できる。取得できない場合は、埋め込みモデルの日本語表現への適合、チャンク本文、取得件数を確認する。

言い換え試験でも、回答だけで合否を決めない。正答していても、出典に復旧条件のチャンクが含まれていなければ、生成用 LLM が会話文脈や一般的な障害対応の知識から推測した可能性が残る。

8.6 文書に存在しない情報を質問する

別の新しい会話で Argolet Operations を接続し、文書に記載していない情報を質問する。

argolet.md には開発責任者名を記載していない。期待する回答は、「文書には記載がない」「提供された情報からは確認できない」である。特定の人物名を生成した場合、検索結果が不足しているのではなく、生成用 LLM が根拠のない情報を補完している。

この試験では、文書内の「開発責任者名を記載していない」という記述が取得されることも確認する。該当チャンクが取得され、回答も保留した場合は、検索と生成の両方が期待どおりに動作している。該当チャンクを取得できたのに人物名を生成した場合は、検索ではなく回答忠実性の問題である。

RAG の実用性は、記載された値へ正答できることだけでは決まらない。文書にない情報を「ない」と判断できなければ、利用者は正しい回答と作り出された回答を区別できない。未記載情報への回答保留は、正答試験と同じ重さで評価する。

8.7 検索結果と生成回答を分けて判定する

Qdrant は、質問から生成されたベクトルと保存済みの点を距離尺度で比較し、近い点を検索結果として返す[33]。Open WebUI は取得した文書断片を生成用 LLM の入力へ組み込み、最終回答を生成する。検索と生成は連続しているが、失敗原因は異なる。

出典表示は、文書が回答に使われた可能性を確認する手掛かりである。出典名だけでなく、表示された断片に質問への回答を決める値、条件、順序が含まれているかを見る。出典に必要な根拠が存在しないのに正答した場合は、RAG による正答とは扱わない。

検索結果が正しいのに回答が誤る場合、チャンクサイズや埋め込みモデルを先に変更してはならない。検索段階では必要な情報を取得できているため、生成用 LLM へ渡された文脈、複数チャンク間の競合、回答指示、モデル規模を確認する。反対に、必要なチャンクを取得できていない場合は、生成用 LLM を大きくしても根拠不足は解消しない。

8.8 試験結果を判定表として保存する

各試験について、回答文だけでなく、Knowledge の接続状態、取得された出典、合否、失敗段階を記録する。モデルや Open WebUI を更新した後に同じ質問を再実行し、検索結果と回答の変化を比較できるようにする。

試験記録には、次の情報を残す。

一回の成功結果だけでは、構成変更後も同じ挙動が続くことを保証できない。少なくとも T1 から T5 を再実行し、正しい出典と回答が繰り返し得られることを確認する。結果が揺れる場合は、同じ質問でも検索順位または生成結果が変化しているため、成功率と失敗形式を記録する。

8.9 RAG の完成条件を確定する

本構成における RAG の完成条件は、Open WebUI の画面で Knowledge を選択できることでも、Qdrant に点が存在することでもない。Knowledge を接続しない状態では答えられない固有情報について、接続後には質問に対応するチャンクが取得され、そのチャンクに含まれる値、手順、条件だけを使って回答できることである。

未接続時には Argolet を知らず、接続時には 47821、Lapis-7、Rho-Blue の復旧条件を文書どおりに回答し、未記載の開発責任者名について回答を保留できれば、登録経路、検索経路、生成経路が一続きに成立している。ここで確認されたのは、モデルが文書を記憶したことではない。質問のたびに必要なチャンクを Qdrant から取得し、その範囲内で回答を構成できるローカル RAG の処理経路である。

9. 検索精度を文字抽出、分割、検索、生成に分けて調整する

9.1 基準構成を固定して一項目ずつ変更する

RAG の回答が不正確な場合、生成用 LLM、埋め込みモデル、チャンクサイズ、重複量、取得件数を同時に変更してはならない。回答が改善しても、どの変更が有効だったのかを特定できず、別の文書で同じ調整を再現できないためである。

調整前に、第 8 章の T1 から T5 を基準試験として実行し、質問、取得された出典、回答、合否を保存する。そのうえで一つの設定だけを変更し、Knowledge を再処理する必要があるかを判断してから、同じ試験を繰り返す。

最初に変更するのは、最終回答から最も遠い生成設定ではなく、処理経路の上流にある文字抽出である。上流で失われた情報は、下流の埋め込みモデルや生成用 LLMを変更しても復元できない。抽出結果が正しいことを確認してから、分割、検索、生成の順に進む。

9.2 原文と抽出結果の一致を確認する

文書に答えが記載されているのに検索結果へ現れない場合、最初に必要な文字列が抽出されたかを確認する。画像だけの PDF、複雑な段組み、表、ヘッダーとフッターを持つ文書では、画面上に情報が見えていても、抽出結果から欠落したり、読み順が崩れたりする。

Open WebUI の文書表示または取得した Qdrant の付随情報から、質問への回答に必要な文字列を確認する。Argolet の検証では、少なくとも次の対応関係が文字列として残っている必要がある。

抽出結果に必要な文字列が存在しない場合は、チャンクサイズや取得件数を変更しない。同じ内容を Markdown へ移し、Markdown では検索できるかを確認する。Markdown で成功し、元の PDF で失敗する場合、RAG 全体ではなく文書抽出が原因である。

文字列が存在していても、表の列関係や手順の順序が崩れている場合は、検索用文書として十分ではない。位置関係に依存する情報は、判断対象と値の対応を文章として明示する。抽出機構の高度化より、検索に必要な関係を補助 Markdown として作成する方が再現性を確保しやすい場合もある。

9.3 検索可能なチャンク本文になっているか確認する

文字抽出が正しくても、分割後のチャンクが単独で意味を持たなければ、安定した検索はできない。Open WebUI では、Markdown 見出し分割を有効にすると見出し単位で前処理した後、文字またはトークンによる通常の分割を行う。チャンクサイズは、RAG_TEXT_SPLITTER=character の場合は文字数、token の場合はトークン数として扱われる[34]。

本構成では文字分割を使用しているため、CHUNK_SIZE=1000 は最大 1000 文字を意味する。Open WebUI の画面または Qdrant の付随情報から、取得対象となるチャンク本文を確認し、質問への回答に必要な要素が同じ意味単位へ残っているかを見る。

検索に失敗した質問について、最初に「取得されるべき理想的なチャンク」を文章として定義する。たとえば復旧条件では、次の一文が一つの根拠単位として残ることが望ましい。

理想的なチャンク本文を決めずにサイズだけを変更すると、点数の増減は観察できても、検索品質が改善したかを判断できない。各試験質問について、必要な主語、値、条件、例外が同じチャンクに含まれることを先に確認する。

9.4 チャンクサイズと重複量を段階的に調整する

短い仕様書では、1000 文字のチャンクに複数の節が入る場合がある。Argolet の本番接続、緊急停止、復旧条件が同じチャンクへ混在する場合は、チャンクサイズを段階的に縮小する。ただし、サイズと重複量を同時に変更せず、どちらの変更が検索結果へ影響したかを分ける。

C1 と C2 では重複量を 100 のまま維持し、チャンクサイズの効果だけを比較する。適切なサイズが決まった後、C3 または C4 で重複量を調整する。すべての値を試す必要はなく、前段階で失敗原因が解消した時点で変更を止める。

構成値を変更する場合は、.env や compose.yaml を構成の正として更新し、Open WebUI コンテナーを再作成する。現在の構成ではチャンク値を compose.yaml に直接記述しているため、対象値を一つだけ変更する。

チャンクサイズまたは重複量を変更しただけでは、Qdrant に保存済みの点は変化しない。Knowledge の再索引を実行し、現在の設定で文字抽出、分割、埋め込み、保存をやり直す[32]。再索引後には、点数と付随情報を確認してから T1 から T5 を再実行する。

点数が増えたこと自体は改善を意味しない。チャンクを小さくすると点数は増えやすいが、必要な条件が分断される可能性も高まる。評価対象は、点数ではなく、質問に必要なチャンクが取得され、余分なチャンクが減り、回答に必要な関係が保持されたかである。

9.5 取得件数は検索漏れを確認してから増やす

RAG_TOP_K は、質問ごとに取得する候補チャンク数の基準値である。現在の構成では 3 件を取得する。必要なチャンクが検索順位の 4 位または 5 位にある場合は、5 件へ増やすことで検索漏れを減らせる。

取得件数を増やす前に、現在の上位 3 件を確認する。正しいチャンクが既に含まれている場合、5 件へ増やしても検索失敗は解消しない。追加される無関係なチャンクによって生成用 LLM の判断が不安定になる可能性がある。

Open WebUI の RAG では、チャンクサイズと取得件数の積に近い量の文書が生成入力へ加わる。1000 トークンのチャンクを 5 件取得する構成では、検索結果だけでおよそ 5000 トークンを使用し、これにシステム指示、会話履歴、質問、回答用の領域が加わる[28]。文字分割を使用する本構成では文字数とトークン数は一致しないが、取得件数を増やすほど文脈消費が増える関係は変わらない。

RAG_TOP_K だけを変更する場合、保存済みのチャンクとベクトルは変わらないため、Knowledge の再索引は不要である。Open WebUI コンテナーを再作成し、実行中の値を確認した後、同じ質問を再実行する。

取得件数を 5 へ増やした結果、必要なチャンクが追加されて正答できるようになった場合は、検索漏れが原因だったと判断できる。正しいチャンクが増えた一方で回答が不安定になった場合は、取得件数を戻し、チャンク本文または埋め込み検索を改善する。

9.6 検索が正しい場合だけ生成設定を調整する

正しいチャンクが取得され、そのチャンクに必要な値、条件、順序が含まれているのに回答が誤る場合、検索経路は成立している。ここで初めて、RAG テンプレート、生成用 LLM、生成パラメーターを確認する。

Open WebUI の RAG テンプレートには、取得した文書断片を挿入する {{CONTEXT}} が必要である。質問文はテンプレート処理後に自動的に追加されるため、{{QUERY}} を重ねて記述すると、同じ質問が二回入力される[34]。

回答規則は、取得文書の用途と情報不足時の動作を明示する。次のように、文書以外の推測を禁止し、根拠がない場合の応答を固定する。

この規則は、正しいチャンクが取得されていることを前提とする。検索結果が誤っている状態で推測を禁止すると、誤答が回答不能へ変わるだけであり、必要な根拠を取得できるようにはならない。

温度を下げると、同じ入力に対する語句選択の変動は小さくなる。Ollama では温度が高いほど出力の多様性が増え、低いほど一貫した出力になりやすい[35]。ただし、温度を下げても、取得文書にない情報を参照できるようになるわけではなく、誤った根拠への忠実性を改善するものでもない。

回帰試験では、温度だけでなく乱数種も固定できれば、同じ入力に対する生成差を減らせる。ただし、Open WebUI から Ollama へ実際に渡された設定を確認し、画面上の表示だけで固定されたと判断しない。生成用モデルを変更した場合も、同じ取得チャンクを使い、回答忠実性と速度だけを比較する。

より大きな生成用 LLM へ変更するのは、正しい根拠を取得できているにもかかわらず、条件の対応、手順順序、回答保留を安定して処理できない場合である。検索が誤っている状態でモデルだけを大型化すると、誤った根拠をより自然な文章へ変換する結果になり得る。

9.7 症状から最初に調べる層を決める

調整では、症状に近い設定を無作為に変更するのではなく、処理経路上で最初に期待値と異なった段階へ戻る。付随情報に本文がなければ抽出、本文はあるが必要な単位に分かれていなければ分割、正しいチャンクが候補に入らなければ検索、正しいチャンクを渡しても誤るなら生成が対象になる。

9.8 調整結果を比較可能な形で記録する

各構成について、設定値だけでなく、Qdrant の点数、取得されたチャンク、最終回答を一つの記録として残す。回答だけを保存すると、改善が検索によるものか生成によるものかを後から判定できない。

一つの設定変更で T1 だけが改善し、T2 や T3 が悪化する場合、その構成を全面的な改善とは扱わない。たとえばチャンクを小さくして本番ポートの検索順位が上がっても、緊急停止の二工程が分断されたなら、単一値の検索と複合条件の検索の間で別の調整が必要である。

9.9 調整の終了条件を決める

検索精度の調整には、すべての文書へ通用する唯一の最適値はない。短い仕様書、長い手順書、表中心の資料では、必要な検索単位が異なる。構成を無期限に変更するのではなく、対象文書と質問集合に対する終了条件を先に決める。

この調整工程で決めるのは、チャンクサイズや取得件数の一般的な正解ではない。対象文書から必要な判断根拠を失わずに取り出し、MacBook Pro の限られた文脈と記憶容量の範囲で、生成用 LLM へ過不足なく渡せる構成である。検索結果を確認せずにモデルを大型化するのではなく、情報が失われた最初の段階へ戻ることが、ローカル RAG を再現可能な処理基盤として調整する条件になる。

10. 再起動、保存、更新、復元まで確認する

10.1 再起動試験を処理層ごとに行う

初回の対照試験に成功した後、再起動によって利用者情報、Knowledge、文書ベクトル、構成値が失われないことを確認する。再起動試験は、コンテナーの再起動、Docker Desktop の再起動、MacBook Pro の再起動に分ける。三つを同時に行うと、状態消失や接続失敗がどの境界で起きたかを特定できない。

最初に Qdrant コンテナーだけを再起動する。再起動後は固定時間だけ待つのではなく、認証付きのヘルスチェックが成功するまで確認する。

Qdrant が要求を受け付けられる状態になった後、Open WebUI を再起動する。Open WebUI は起動時に Qdrant と Ollama の接続設定を読み込むため、依存先の準備前に確認を始めると、一時的な接続エラーを永続的な障害と誤認する可能性がある。

再起動後には、ブラウザー画面が表示されることだけでなく、次の状態を確認する。

続いて Docker Desktop を終了し、再度起動する。Docker Desktop の起動後に同じヘルスチェック、ログイン、コレクション確認、対照試験を行う。ここでは、Docker の仮想環境が再作成されても、ホスト上のバインド先から状態を読み直せることを確認する。

最後に MacBook Pro を再起動する。再起動後は、Ollama と Docker Desktop が起動していることをそれぞれ確認する。自動起動されない場合はアプリケーションを起動してから試験を続ける。

MacBook Pro の再起動後にも T1 から T5 が成立すれば、端末の稼働中だけ保持される一時状態ではなく、Ollama のモデル保存領域、Open WebUI のバインド先、Qdrant のバインド先から必要な状態を復元できている。

10.2 コンテナーの削除と再作成を試験する

docker compose restart は既存コンテナーのプロセスを再起動するだけであり、同じ構成ファイルから環境を再現できることまでは確認しない。コンテナーを削除して作り直し、実行環境と永続データが分離されていることを確認する。

docker compose down は、既定では Compose が作成したコンテナーとネットワークを削除する。明示したバインド先はホスト上のディレクトリであり、コンテナーとは別に残る[36]。

Qdrant の起動完了をヘルスチェックで確認してから、Open WebUI を作成する。

固定秒数の sleep だけに依存すると、起動が速い機種では不要な待機が発生し、起動が遅い場合には準備前に次の処理へ進む。API の成功を条件にすることで、端末負荷や更新後の初期化時間が変わっても同じ判定を使える。

再作成後には、実行中のコンテナーへ構成値が渡されていることを確認する。

利用者、会話、Knowledge、Qdrant の点が残り、T1 から T5 が再現すれば、コンテナー自体には復元不能な状態を保持していない。反対に、画面は起動しても初回登録画面へ戻った場合は Open WebUI のバインド先、コレクションが消えた場合は Qdrant のバインド先を確認する。

10.3 Open WebUI の永続領域を停止時に保存する

Open WebUI の永続領域には、利用者、会話、Knowledge の管理情報、アップロード済みファイル、設定、SQLite データベースが含まれる。公式文書も、/app/backend/data に対応する永続領域全体をファイル単位のバックアップ対象としている[37]。

SQLite データベースを含むディレクトリを実行中に複製すると、データベース本体と関連ファイルの時点がそろわない可能性がある。本構成では Open WebUI を停止し、書き込みが止まった状態で永続領域、原文、構成ファイル、秘密値を一つのアーカイブへ保存する。

アーカイブには .env の Qdrant API 鍵と Open WebUI の秘密鍵が含まれるため、通常の文書バックアップと同じ場所へ無条件に共有してはならない。権限を 600 にし、暗号化された保存先へ置く。

このアーカイブには Qdrant のコレクションデータを含めない。Open WebUI の Knowledge 管理情報だけを復元しても、対応する Qdrant の点がなければ文書検索は成立しない。Qdrant は次節のスナップショットとして別に保存する。

10.4 Qdrant のスナップショットを作成して端末外のファイルへ保存する

Qdrant のコレクションスナップショットには、コレクション設定、点、ベクトル、付随情報、構築済み索引が含まれる。スナップショットは、再索引を行わずにコレクションを復元するために使用できる[38]。

対象コレクション名を指定し、スナップショットを作成する。

Qdrant コンテナー内のスナップショット保存先へ作成できただけでは、Qdrant の保存領域自体を失った場合に復元できない。REST API からスナップショットをダウンロードし、独立したバックアップファイルとして保存する。

Open WebUI が複数のコレクションを使用している場合は、必要なコレクションごとにスナップショットを作成する。コレクション単位のスナップショットにはコレクション別名が含まれないため、別名を使用している構成ではその定義も別途記録する[38]。

元文書もスナップショットとは別に保持する。ベクトルを復元できても、原文がなければ埋め込みモデルやチャンク条件を変更した際に正しい再索引を行えない。

10.5 Qdrant のスナップショットを一時コレクションへ復元する

スナップショットファイルが存在することと、実際に復元できることは同義ではない。元のコレクションを削除せず、一時コレクションへアップロードして、点数と付随情報を比較する。

復元先には元のコレクションと異なる名前を使用する。復元試験はスナップショット作成時と同じ Qdrant イメージ版で行い、版の非互換による失敗をバックアップ破損と混同しない。

元コレクションと復元先コレクションの点数を取得し、同じであることを確認する。

点数だけでなく、復元先の付随情報に検証用の固有文字列が残っていることを確認する。

点数と主要な付随情報が一致した後、一時コレクションを削除する。

この試験により、スナップショットの作成、ダウンロード、アップロード、コレクション作成、点と付随情報の復元までが成立したことを確認できる。元コレクションを残したまま試験するため、通常の検索環境を破壊しない。

10.6 Open WebUI のバックアップを一時環境で読み込む

Open WebUI のアーカイブも、作成後に内容を検査する。最初に一時ディレクトリへ展開し、SQLite データベースの整合性を確認する。

次に、展開したデータを本番環境とは異なる 3001 番ポートで一時的に起動する。バックアップ時に保存したイメージタグと WEBUI_SECRET_KEY を使用する。

ブラウザーで http://127.0.0.1:3001/ を開き、バックアップ時の利用者でログインする。利用者情報、会話、Knowledge の名称、登録ファイルが表示されることを確認する。この一時環境では Ollama と Qdrant を無効にしているため、RAG の検索試験ではなく、Open WebUI の管理情報とファイルを復元できることが対象になる。

確認後、一時コンテナーと展開先を削除する。

Open WebUI の一時復元試験と Qdrant の一時コレクション復元試験を組み合わせることで、管理情報と検索データをそれぞれ保存できていることを確認できる。障害時には両方を同じバックアップ時点へ戻さなければ、Knowledge の管理情報と Qdrant の点の対応がずれる可能性がある。

10.7 更新前の状態と版を記録する

Open WebUI の更新では、永続データを保存し、変更点を確認し、特定の版へ固定したうえでイメージを再作成することが推奨されている。データベース移行を伴う更新では、単に旧イメージへ戻しても旧版が更新後のデータベースを読めない可能性があるため、更新前のバックアップが必要になる[39]。

更新前に、Ollama、モデル、コンテナーイメージ、展開後の Compose 構成を記録する。

展開後の Compose 構成には秘密値が含まれるため、共有資料として扱わない。更新前記録の目的は、使用したイメージタグ、環境変数、ポート、保存先を障害発生後に再現することである。

更新前には、少なくとも次の保存物がそろっていることを確認する。

10.8 Open WebUI と Qdrant を別々に更新する

Open WebUI と Qdrant を同時に更新すると、文書登録や検索が失敗した場合に、どちらの変更が原因かを特定できない。最初に Open WebUI だけを更新し、回帰試験を完了してから Qdrant を更新する。

.env の OPEN_WEBUI_IMAGE を更新先の固定タグへ変更する。main や latest へ置き換えず、更新対象の版を明示する。

Open WebUI の更新後には、ブラウザーの古い画面資源が残る場合があるため、必要に応じて強制再読み込みする[39]。そのうえで、次の順に確認する。

1. 既存の利用者でログインできること。
2. 新規登録が無効のままであること。
3. 既存の会話と Knowledge が表示されること。
4. Ollama の生成用モデルが表示され、通常対話が成功すること。
5. 既存の Argolet 文書について T1 から T5 が成立すること。
6. 新しい検証文書を登録し、Qdrant の点数が増えること。
7. 登録した新しい情報を検索できること。

既存 Knowledge の検索だけでは、旧データを読めることしか確認できない。新しい文書登録を含めることで、文字抽出、埋め込み生成、Qdrant への新規保存まで、更新後の書き込み経路を確認する。

Open WebUI の回帰試験が完了した後に、.env の QDRANT_IMAGE を更新先の固定タグへ変更する。

Qdrant の更新後には、ヘルスチェック、コレクション一覧、点数、ベクトル次元、付随情報を確認する。続いて T1 から T5 と、新しい文書の登録試験を再実行する。

10.9 更新失敗時はイメージと保存状態を分けて戻す

更新後に障害が起きた場合、最初に変更したイメージタグを旧版へ戻す。ただし、更新時に Open WebUI のデータベース移行や Qdrant の保存形式変更が行われた場合、旧イメージへ戻すだけでは復旧しない。更新前の保存状態も同じ時点へ戻す必要がある。

Open WebUI を更新前へ戻す場合は、現在の障害状態を別名で残し、更新前アーカイブから永続領域と構成を復元する。

復元後には、利用者、会話、Knowledge が戻っていることを確認する。Open WebUI の管理情報を更新前へ戻した場合、Qdrant も対応する更新前スナップショットへ戻す必要があるかを判断する。更新後に文書の追加、削除、再索引を行っていた場合、両者の時点は一致しない。

Qdrant の元コレクションをスナップショットから戻す場合は、Open WebUI を停止し、現在のコレクション名を確認してから実行する。次の操作は既存コレクションを削除するため、復元試験済みのスナップショットを指定する。

復元後には点数、ベクトル次元、付随情報を確認し、T1 から T5 を再実行する。画面が起動したことや点数が戻ったことだけでは、Open WebUI の Knowledge と Qdrant のコレクションが再び対応したとは判断できない。

10.10 構成値の保存場所を一つずつ固定する

Open WebUI の一部の環境変数は、既定では ConfigVar として内部データベースへ保存され、後の起動では外部環境変数より優先される。本構成では ENABLE_PERSISTENT_CONFIG=False としているため、Compose から渡した環境変数を毎回読み込み、管理画面で変更した ConfigVar は再起動後に保存されない[20]。

元稿のように、初期構成を Compose で指定した後、管理画面の変更を別の設定源として併用すると、画面上の値と構成ファイルのどちらが正しいか判別できなくなる。本構成では、接続先、検索設定、文書分割条件を compose.yaml と .env へ集約する。

管理画面で設定値を試験的に変更できる場合でも、再起動後に残るとは扱わない。採用する値が決まった時点で compose.yaml または .env へ反映し、コンテナーを再作成した後に実行中の環境変数を確認する。

10.11 バックアップに含まれない実行資源を確認する

Open WebUI のアーカイブと Qdrant のスナップショットだけでは、MacBook Pro を失った場合の完全なオフライン復元にはならない。Ollama のモデルデータと Docker イメージは、この章で作成した Open WebUI アーカイブに含まれていない。

Docker イメージも端末内へ保存する場合は、固定したイメージ名を一つのアーカイブへ出力する。

復元時には次のように読み込む。

モデルやイメージを再取得できる通常運用では、容量の大きい実行資源を毎回保存する必要はない。一方、ネットワーク切断後も復旧できることを要件とするなら、データだけでなく、実行に必要なモデルとイメージも復旧対象へ含める。

10.12 運用工程の完了条件を固定する

ローカル RAG の運用条件は、構築直後に一度だけ正答することではない。MacBook Pro、Docker Desktop、コンテナーを再起動しても状態が残り、コンテナーを削除しても構成から再作成でき、更新前の Open WebUI と Qdrant を独立した復元物として保存できる必要がある。

さらに、保存物は実際に一時環境へ復元し、利用者情報、Knowledge、点数、付随情報を読み出せなければならない。バックアップファイルが存在するだけでは、復元経路が成立したことにはならない。再起動、再作成、更新、復元を同じ対照試験で検証できる状態になって初めて、この構成は一時的な実験環境ではなく、継続して運用可能なローカル RAG となる。

11. ローカル RAG は観測可能な処理経路として完成する

11.1 三つのサービスが起動しただけでは完成しない

Ollama、Open WebUI、Qdrant を同じ MacBook Pro 上で起動し、ブラウザーから生成用 LLM と対話できても、ローカル RAG が成立したとはいえない。通常対話は Ollama だけで完結するため、文書抽出、埋め込み生成、Qdrant への保存、類似検索のいずれかが停止していても、自然な回答が返る場合がある。

本構成で確認したのは、三つの製品が同時に動くことではない。文書を検索可能なチャンクへ変換し、embeddinggemma で埋め込みベクトルを生成し、Qdrant へ原文断片とともに保存し、質問時に関連チャンクを取得し、その根拠を qwen3.5:9b-q4_K_M へ渡す処理経路である。

この経路が最後まで成立していれば、生成用 LLM が学習時に知らなかった Argolet の本番保守ポートを、Knowledge 接続時にだけ 47821 と回答できる。Lapis-7 手順では接続キューを停止してから書き込み処理を停止し、復旧条件では Rho-Blue が 15 分間連続して 0.20 未満であることを欠落なく説明できる。文書に記載していない開発責任者名については、人物名を補わず、確認できないと回答する。

これらの対照試験によって、単に正しい文字列が出力されたのではなく、外部文書が質問時の根拠として使われたことを確認できる。Knowledge 未接続時の回答、接続時に取得されたチャンク、出典、最終回答を分けて記録することで、偶然の正答や会話履歴からの再利用を RAG の成功から除外できる。

11.2 誤答を処理段階へ戻せることが実用条件になる

観測可能な構成では、最終回答が誤った場合に、処理経路を上流へたどって原因を限定できる。Qdrant の付随情報に必要な文字列がなければ、生成用 LLM を変更する前に文字抽出を調べる。文字列は存在するが主語と値が別のチャンクへ分かれていれば、チャンクサイズ、重複量、原文構造を調整する。

正しい本文が保存されていても検索上位へ入らない場合は、埋め込みモデル、質問表現、取得件数を確認する。必要なチャンクが取得されているのに値、条件、工程順序を誤る場合は、生成用 LLM、競合する取得文脈、RAG テンプレートを確認する。処理段階を分けることで、誤答を一括して「モデル性能が低い」と処理せずに済む。

この切り分けができない構成では、回答品質を改善するたびに、生成用 LLM、埋め込みモデル、チャンク設定を無作為に変更することになる。改善しても原因を説明できず、別の文書や更新後の環境で再現できない。処理境界ごとに確認可能な事実を置くことが、ローカル RAG を調整可能な技術基盤へ変える。

11.3 Qdrant を分離する意味は中間状態を確認できることにある

Qdrant を独立したコンテナーとして配置した理由は、将来の文書数増加に備えるためだけではない。Open WebUI の画面の外側から、どのコレクションに何件の点が保存され、どのベクトル次元と距離尺度が使われ、各点の付随情報にどの文書断片が残っているかを確認できるためである。

生成用 LLM の回答だけを観察する構成では、検索された根拠が誤っていたのか、正しい根拠を生成時に取り違えたのかを判別できない。Qdrant のコレクション、点数、ベクトル設定、付随情報を確認できれば、文書登録から類似検索までの中間状態を生成処理から分離して評価できる。

この分離は、埋め込みモデルを変更した場合にも意味を持つ。新旧モデルの出力次元が同じであっても意味空間は互換ではないため、既存文書を再索引しなければならない。Qdrant の保存状態を観察できれば、旧モデルで作られた点が残っていないか、再索引後に点数と付随情報が変化したかを確認できる。

11.4 ローカル完結と運用可能性は別々に確認する

本構成では、生成と埋め込みを macOS 上の Ollama、文書管理を Open WebUI、ベクトル保存と検索を Qdrant が担当する。生成、埋め込み、検索、文書抽出の接続先を MacBook Pro と Docker Desktop 内へ限定することで、質問と登録文書を外部の生成 API や埋め込み APIへ送らずに回答処理を実行できる。

ただし、回答処理がローカルで完結することと、運用可能な状態が続くことは別の条件である。コンテナーの再起動、Docker Desktop の再起動、MacBook Pro の再起動、コンテナーの削除と再作成を行った後にも、利用者、Knowledge、会話、Qdrant の点、検索結果が残る必要がある。

バックアップも、ファイルを作成しただけでは完了しない。Open WebUI の停止時アーカイブは一時環境で起動し、SQLite の整合性、利用者情報、Knowledge を確認する。Qdrant のスナップショットは一時コレクションへ復元し、点数と Argolet の固有情報が戻ることを確認する。復元試験を通過して初めて、保存物を障害時の復旧手段として扱える。

11.5 完成したのはモデルではなく根拠を制御する経路である

この構成によって、生成用 LLM 自体が Argolet の運用規則を学習したわけではない。文書は Open WebUI によってチャンクへ分割され、embeddinggemma のベクトルとして Qdrant へ保存される。質問時には必要な断片だけが検索され、qwen3.5:9b-q4_K_M は、その場で渡された根拠から回答を構成する。

文書を更新した場合は再登録または再索引によって根拠を差し替えられ、埋め込みモデルを変更した場合は検索空間を作り直せる。生成用 LLM を変更しても、同じ検索結果を与えて回答忠実性と速度を比較できる。モデル、検索、文書を分離したことで、知識の更新をモデル再学習ではなく、管理可能な文書と索引の更新として扱える。

MacBook Pro 上のローカル RAG が実用段階へ達したと判断できるのは、回答が返った時点ではない。文書のどの断片が保存され、なぜその断片が検索され、生成用 LLM がどの根拠から回答し、障害や更新後に同じ状態をどう復元するかを説明できる時点である。完成したのは三つのサービスを並べた環境ではなく、利用者が根拠、失敗位置、設定、復旧手順を制御できる処理経路である。

次稿では、この推論・検索基盤を MCP、VS Code、Continue、Git の作業経路へ接続する。次の段階で問われるのは、ローカル RAG が単独で正答できるかではない。開発作業のどの時点で文書検索を実行し、どの操作をモデルへ許可し、どの変更を人間が確認し、どの状態からロールバックできるようにするかである。

参考文献

1. id774, MacBook Pro でローカル LLM を実用化する条件（2026-07-17）. https://blog.id774.net/entry/2026/07/17/5102/
2. id774, 生成 AI の競争軸は、モデルから業務実装へ移る（2026-06-25）. https://blog.id774.net/entry/2026/06/25/4922/
3. Patrick Lewis, Ethan Perez, Aleksandra Piktus, Fabio Petroni, Vladimir Karpukhin, Naman Goyal, Heinrich Küttler, Mike Lewis, Wen-tau Yih, Tim Rocktäschel, Sebastian Riedel, Douwe Kiela, Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks, Advances in Neural Information Processing Systems 33（2020）. https://proceedings.neurips.cc/paper/2020/hash/6b493230205f780e1bc26945df7481e5-Abstract.html
4. Shahul Es, Jithin James, Luis Espinosa Anke, Steven Schockaert, RAGAs: Automated Evaluation of Retrieval Augmented Generation, Proceedings of the 18th Conference of the European Chapter of the Association for Computational Linguistics: System Demonstrations（2024）. https://aclanthology.org/2024.eacl-demo.16/
5. Apple Developer, Explore the new system architecture of Apple silicon Macs, WWDC20（2020）. https://developer.apple.com/videos/play/wwdc2020/10686/
6. Ollama, macOS（n.d., 2026-07-16 参照）. https://docs.ollama.com/macos
7. Docker, Install Docker Desktop on Mac（n.d., 2026-07-16 参照）. https://docs.docker.com/desktop/setup/install/mac-install/
8. Docker, Compose file reference（n.d., 2026-07-16 参照）. https://docs.docker.com/reference/compose-file/
9. Docker, Volumes（n.d., 2026-07-16 参照）. https://docs.docker.com/engine/storage/volumes/
10. Docker, Explore networking how-tos on Docker Desktop（n.d., 2026-07-16 参照）. https://docs.docker.com/desktop/features/networking/networking-how-tos/
11. Ollama, Introduction, API Reference（n.d., 2026-07-16 参照）. https://docs.ollama.com/api/introduction
12. Ollama, qwen3.5:9b（n.d., 2026-07-16 参照）. https://ollama.com/library/qwen3.5:9b
13. Ollama, Usage, API Reference（n.d., 2026-07-16 参照）. https://docs.ollama.com/api/usage
14. Ollama, Embeddings（n.d., 2026-07-16 参照）. https://docs.ollama.com/capabilities/embeddings
15. Ollama, Generate embeddings, API Reference（n.d., 2026-07-16 参照）. https://docs.ollama.com/api/embed
16. Nils Reimers, Iryna Gurevych, Sentence-BERT: Sentence Embeddings using Siamese BERT-Networks, Proceedings of EMNLP-IJCNLP（2019）. https://aclanthology.org/D19-1410/
17. Ollama, Context length（n.d., 2026-07-16 参照）. https://docs.ollama.com/context-length
18. Qdrant, Security（n.d., 2026-07-16 参照）. https://qdrant.tech/documentation/security/
19. Open WebUI, Quick Start（n.d., 2026-07-16 参照）. https://docs.openwebui.com/getting-started/quick-start/
20. Open WebUI, Environment Variable Configuration（n.d., 2026-07-16 参照）. https://docs.openwebui.com/reference/env-configuration/
21. Qdrant, Local Quickstart（n.d., 2026-07-16 参照）. https://qdrant.tech/documentation/quickstart/
22. Docker, Control startup and shutdown order in Compose（n.d., 2026-07-16 参照）. https://docs.docker.com/compose/how-tos/startup-order/
23. Qdrant, Qdrant Web UI（n.d., 2026-07-16 参照）. https://qdrant.tech/documentation/web-ui/
24. id774, AI に自身の文脈を持ち運ぶ（2026-05-04）. https://blog.id774.net/entry/2026/05/04/4675/
25. Open WebUI, Knowledge（n.d., 2026-07-16 参照）. https://docs.openwebui.com/features/workspace/knowledge/
26. Open WebUI, Retrieval Augmented Generation (RAG)（n.d., 2026-07-16 参照）. https://docs.openwebui.com/features/chat-conversations/rag/
27. Nelson F. Liu, Kevin Lin, John Hewitt, Ashwin Paranjape, Michele Bevilacqua, Fabio Petroni, Percy Liang, Lost in the Middle: How Language Models Use Long Contexts, Transactions of the Association for Computational Linguistics 12（2024）. https://aclanthology.org/2024.tacl-1.9/
28. Open WebUI, Troubleshooting RAG（n.d., 2026-07-16 参照）. https://docs.openwebui.com/troubleshooting/rag/
29. Qdrant, Collections（n.d., 2026-07-16 参照）. https://qdrant.tech/documentation/manage-data/collections/
30. Qdrant, Points（n.d., 2026-07-16 参照）. https://qdrant.tech/documentation/manage-data/points/
31. Qdrant, Indexing Vectors in HNSW, Collections（n.d., 2026-07-16 参照）. https://qdrant.tech/documentation/manage-data/collections/#indexing-vectors-in-hnsw
32. Open WebUI, Changing the Embedding Model, Retrieval Augmented Generation (RAG)（n.d., 2026-07-16 参照）. https://docs.openwebui.com/features/chat-conversations/rag/#changing-the-embedding-model
33. Qdrant, Search（n.d., 2026-07-16 参照）. https://qdrant.tech/documentation/search/search/
34. Open WebUI, RAG Template Customization and Chunking Configuration, Retrieval Augmented Generation (RAG)（n.d., 2026-07-16 参照）. https://docs.openwebui.com/features/chat-conversations/rag/#rag-template-customization
35. Ollama, Modelfile Reference（n.d., 2026-07-16 参照）. https://docs.ollama.com/modelfile
36. Docker, docker compose down（n.d., 2026-07-16 参照）. https://docs.docker.com/reference/cli/docker/compose/down/
37. Open WebUI, Backups（n.d., 2026-07-16 参照）. https://docs.openwebui.com/tutorials/maintenance/backups/
38. Qdrant, Snapshots（n.d., 2026-07-16 参照）. https://qdrant.tech/documentation/snapshots/
39. Open WebUI, Updating Open WebUI（n.d., 2026-07-16 参照）. https://docs.openwebui.com/getting-started/updating/