Open WebUI:フォルダーを次と同期する oikb

Open WebUI のナレッジベースへドキュメントを手動でインポートする方法は、フォルダーの内容が変わらないうちは機能します。しかし、フォルダーが変化し始めると(手順書の更新、メモの追加、ファイルの削除など)、ベースは次第に食い違い、モデルは古いバージョンに基づいて回答するようになります。公式ドキュメントの Ecosystem セクションで紹介されているツール oikb を使って Open WebUI とフォルダーを同期することは、この食い違いを解消するためのものです。このガイドでは、増分同期の仕組み、それによって削除される可能性があるもの、そしてバックアップ、限定した対象範囲、テスト用ベースを用いた慎重な手順を説明します。編集部ではテストしていません。
#フォルダーを Open WebUI と同期する理由
Open WebUI のナレッジベース(Knowledge)は、パッセージに分割され、埋め込みとしてインデックス化されたファイルの集合です。このナレッジベースをモデルに関連付けるか、チャットで # を使って参照すると、Open WebUI は質問に近いパッセージを検索し、コンテキストに追加します。インターフェース側でのこの仕組みについては、「コーディング不要で Ollama を使うローカル RAG」ガイドで詳しく説明しています。
問題は時間が経つにつれて表面化します。ディスク上で変更したファイルは、ベース内では変更されません。Open WebUI はインポートされたバージョンを保持し続けます。フォルダーから削除したファイルも、引き続き検索対象になります。新しいファイルは、誰かがインポートするまで存在しないのと同じです。ドキュメントが数件程度のフォルダーなら、再インポートで対処できます。しかし、毎週変わる社内手順書やメモのフォルダーでは手動の再インポートは忘れられがちで、アシスタントは廃止された手順を自信満々に引用してしまいます。
同期ツールはこの作業を自動化します。フォルダーと送信済みの内容を比較し、差分だけを送信します。これを増分同期と呼びます。その代償として、自動的に追加や置き換えを行うツールは、自動的に削除することもできます。これが最も注意を要する点です。
#増分同期:ソース、宛先、状態
私たちの経験とガイド付きルートを活かして、ローカルアシスタントを作り、AIを毎日の作業に取り入れましょう。
- 永久に利用できるオンラインスペース
- PDF + ファイル
- 30日間返金対応
どのツールを使う場合でも、この種の同期は三つの要素に基づいています。これらを理解しておくと、適切な疑問を持って oikb のドキュメントを読むことができます。
- ソース
- 内容の正となるローカル(またはマウントされた)フォルダーです。選択した範囲内にあるものはすべて、最終的にベースへ取り込まれることになります。そのため、範囲を慎重に定める必要があります。中に個人用のサブフォルダーを置き忘れると、それがインデックス化され、ベースにアクセスできる全員が検索できるようになります。
- 宛先
- 特定のインスタンス(URL)上にある、Open WebUI の特定のナレッジベースです。ナレッジベースの ID を間違えると、二つのコーパスが混在したり、さらに悪い場合には、誤ったナレッジベースに削除が適用されたりする可能性があります。
- L'authentification
- このツールは、アカウントに紐づいたキーを使って Open WebUI の API 経由で動作します。ツールはそのアカウントの権限を引き継ぎます。つまり、アカウントが読み取り、変更、削除できるものは、ツールも同じように扱えます。
- 状態
- 何が変更されたかを把握するために、ツールはすでに送信した内容の記録(コンテンツのハッシュ、更新日時、ローカルファイルと Open WebUI 側のファイルとの対応関係)を保持するか、ナレッジベースに問い合わせてその記録を再構築する必要があります。この状態が失われたりずれたりすると、ツールがすべてを再送信したり、重複を作成したり、ファイルが存在しないことを誤って解釈したりする可能性があります。
これらの情報をもとに、各実行ではファイルを四つのケースに分類します。新規(送信する)、変更あり(置き換える)、変更なし(無視する)、ソースから消えた(設定に応じてベースから削除する、または残す)です。oikb を実行する前に、そのドキュメントで次の四つの問いへの答えを確認してください。変更をどのように検出するか、状態をどこに保存するか、消えたファイルを削除するかどうか、またどのオプションで削除するか、そしてアクションを実行せずに表示するシミュレーションモードがあるかどうかです。
#本当のリスク:ミラーリングによる削除
ソースに存在しないファイルをナレッジベースから削除する同期は便利です。廃止された手順書を消してくれるのはこの機能です。しかし、ソース側のあらゆるミスが、ナレッジベース側でのデータ損失につながります。現実的なシナリオをいくつか挙げます。
- マウントされていないディスク
- フォルダーが、実行時に存在しないネットワーク共有や外付けディスクを指しています。マウントポイントが空になっているため、ツールからはすべてのファイルが消えたように見えます。
- 誤ったパス
- 入力ミスや作業ディレクトリの変更により、ソースが空のフォルダーや別のフォルダーを指してしまいます。
- フォルダー構成の変更
- サブフォルダーの名前変更や移動は、「すべて削除してからすべて再作成する」と見なされる場合があります。最終的な結果は正しいかもしれませんが、ナレッジベース全体が再インデックスされ、旧ファイルへのリンクがあれば失われます。
- 共有ナレッジベース
- 同じナレッジベースに他の人が手動でファイルを追加している場合、厳密なミラーリングを行うツールは、それらのファイルをソースに存在しないものと見なして削除する可能性があります。oikb が自身で送信したファイルのみを扱うかどうかを、ドキュメントで確認してください。
ここから二つのルールが導かれます。まず、同期対象のナレッジベースは同期専用にしてください。手動でファイルを追加してはいけません。次に、テスト用のナレッジベースでツールの挙動を確認するまでは、日常的に使っているナレッジベースで削除を有効にしないでください。
#前提条件
- 正常に動作する Open WebUI
- Ollama に接続された最新のインスタンス(デフォルトでは http://localhost:11434)で、埋め込みモデルが設定されていること。インストールについては「Open WebUI と Ollama:完全ガイド」で説明しています。
- 専用アカウント
- 理想的には、管理者アカウントではなく、同期用に作成し、ナレッジベースの所有者とした一般ユーザーアカウントを使用します。そうすれば、キーの権限範囲をそのアカウントに必要なものだけに限定できます。
- 許可された API キー
- バージョンによっては、ユーザーが「設定 > アカウント」から API キーを生成できるようにするには、管理者が管理設定で API キーを有効にする必要があります。正確な項目名は異なるため、お使いのバージョンを参照してください。
- 最新のバックアップ
- Open WebUI の Docker ボリュームの検証済みアーカイブ。誤ってベースが空になった場合に、本当に元に戻せる唯一の手段です。
- oikb 固有の前提条件
- 言語、バージョン、インストール方法は公式ページに記載されています。推測しないでください。
#Open WebUI とフォルダーを同期する:5つのステップの手順
- 011. インスタンスをバックアップするコンテナーを停止し、ボリュームをアーカイブし、再起動して、ハッシュ値を計算します。復元を含む完全な手順は、ガイド「障害後に Open WebUI と Ollama を復元する」に記載しています。一度も復元したことのないバックアップは仮定にすぎません。検証用インスタンスで少なくとも一度はテストしてください。
- 022. 対象範囲を決めるoikb を「ドキュメント」フォルダー全体に向けないでください。ベースに入れるファイルだけを含む公開用フォルダーを用意し、Open WebUI が抽出できる形式(テキスト、Markdown、テキスト PDF など)にしてください。その中身を一覧化しておきます。これが、後でベースに何が取り込まれたかを確認するための基準になります。
- 033. テスト用ベースとキーを作成する「ワークスペース > ナレッジ」で、たとえば「essai-sync」という名前のベースを作成します。その ID はベースのページのアドレスに表示されます。同期用アカウントの API キーを生成し、自分だけが読み取れるファイルに保存したうえで、簡単な呼び出しで動作することを確認してください。
- 044. テスト用ベースでの初回実行公式ページに従って oikb をインストールし、実行します。同期先はテスト用ベースとし、削除は行わず、ツールにシミュレーションモードがあればそれを使用してください。実際の実行を始める前に、予定されているアクションの一覧を確認します。その後、ベース内のファイル数をインベントリと照合してください。
- 055. 境界ケースを検証してから本番に切り替えるテスト用ベースで、ファイルを一つ変更し、一つ追加し、一つ削除してから、もう一度実行します。変更したファイルだけが置き換えられ、削除したファイルがドキュメントの説明どおりに処理されることを確認してください。次に、ソースを一時的に空にし(フォルダー名を変更します)、ツールが何を実行しようとするかを確認します。これはディスクがマウントされていない場合のテストです。そのあとで初めて、oikb を本番のベースに向けてください。
ステップ 2 では、rsync を使って作業フォルダーから公開用フォルダーを作成し、特定の拡張子のファイルだけを残すことができます。以下の例では、Markdown ファイルと PDF ファイルをコピーし、ディレクトリ構造を保持して、それ以外はすべて無視します。--delete は使用していません。作業フォルダーから削除したファイルは、ご自身で削除するまで公開用フォルダーに残ります。これにより、ナレッジベース側で削除が行われる前に、人による判断を挟むことができます。
ステップ3では、何も変更せずにキーをテストできます。Open WebUI のAPIは、Authorization: Bearer ヘッダーでキーを受け付けます。以下の呼び出しは、アカウントから参照可能なモデルを一覧表示します。JSONレスポンスが返ればURLとキーが正しいことが確認できます。401または403エラーの場合は、キーが無効であるか、管理者によってAPIキーが許可されていないことを示します。
ポート 3000 は、最も一般的な Docker コマンド(-p 3000:8080)に対応しています。ご自身の環境に合わせて変更してください。oikb がキーを読み取る方法(環境変数、オプション、設定ファイル)はドキュメントに記載されています。コマンドラインオプションはプロセス一覧や履歴に残ってしまうため、環境変数またはファイルを使用することをおすすめします。
#リスクを負わずに同期を自動化する
テスト用のナレッジベースで挙動を確認すると、毎時の実行をスケジュールしたくなるかもしれません。その前に、ツールに依存しない安全策をいくつか追加してください。
- 各実行の前にソースを確認する
- 公開用フォルダーが空の場合や、ファイル数が前回のインベントリと比べて急激に減少した場合に、同期の実行を拒否するスクリプトです。マウントされていないディスクに対する最も簡単な保護策です。
- ログを残す
- 各実行の出力を日付付きのファイルにリダイレクトします。アシスタントが予想外の応答を返した場合、ログを見れば、いつファイルがナレッジベースに追加または削除されたかがわかります。
- 実行間隔を空ける
- 週に数回変更される程度のドキュメントであれば、毎日の実行で十分であり、埋め込みを計算するマシンのインデックス処理の負荷も軽減できます。
- 後だけでなく、事前にバックアップする
- 同期とは独立した、ボリュームの定期的なバックアップ。実行によってベースが空になっても、復元すれば埋め込みも戻るため、すべてを再インデックスする必要はありません。
このスクリプトには、意図的に oikb コマンドを含めていません。公式ページからコマンドを取得し、指定された箇所に貼り付けてください。MIN のしきい値は任意の値です。より精密なチェックでは、ファイル数を前回のインベントリと比較し、一定の割合を超えて減少している場合は実行を拒否します。
#トラブルシューティング
- API で 401 または 403
- キーが期限切れ、失効済み、またはスペースを含んだままコピーされています。また、管理者が API キーを許可していること、およびアカウントが対象のナレッジベースにアクセスできることも確認してください。
- 送信したのにチャットで見つからないファイル
- 送信とインデックス化は別々の段階です。テキストレイヤーのないスキャン PDF は、受け付けられても利用可能なパッセージを生成しない場合があります。ベース内でファイルを開いて抽出されたテキストを確認し、スキャン文書は公開前に OCR にかけてください。
- ナレッジベース内の重複
- 状態情報が失われたか、同じファイルを手動でインポート済みのベースに対して初回実行を行った場合によく見られる兆候です。同期専用の空のベースからやり直してください。
- 長時間かかる再インデックス
- Open WebUI の設定で埋め込みモデルを変更すると、ドキュメントの再インデックスが必要になります。この設定の変更と同期を同時に行うのは避けてください。差異が生じた場合に、どちらが原因なのか判断できなくなります。
- 回答が古いまま
- ナレッジベース内で、旧バージョンが追加ではなく確実に置き換えられていることを確認してください。新しい会話を開始してください。既存の会話で引用されたパッセージは、その会話の履歴に残ります。
#検証済みの内容と、検証していない内容
本ガイドのために oikb の試用は一切行っていません。インストール、実行、所要時間やデータ量の測定は行っていません。公式ドキュメントのページは、テーマの準備中の 30/10/2026 に参照しましたが、18/11/2026 には再確認できませんでした。バックアップコマンドは、当サイトの復元ガイドのものを流用しています。キーのテストには Bearer ヘッダーと Open WebUI の API の /api/models ルートを使用していますが、ご使用のバージョンで確認してください。ドキュメントで確認すべき点(変更の検出、状態、削除、シミュレーション)は一般的な基準であり、oikb の動作を説明したものではありません。
#さらに詳しく
- Ollamaでコーディング不要のローカルRAG
- Open WebUI のナレッジベースがインターフェース側でどのように機能するか、またどのような場合に AnythingLLM を選ぶべきか:https://quelllm.fr/guide/rag-local-ollama-sans-coder
- 障害発生後に Open WebUI と Ollama を復元する
- ボリュームのバックアップ、復元、検証用インスタンス(ステップ1の前提条件):https://quelllm.fr/guide/restaurer-open-webui-ollama-sauvegarde
- Open WebUIとOllama:完全ガイド
- インターフェースのインストールと基本設定:https://quelllm.fr/guide/open-webui-ollama-tutoriel
- 一次情報源
- Open WebUI、Ecosystem ドキュメント、Knowledge Base Sync:https://docs.openwebui.com/ecosystem/knowledge-base-sync/(2026年10月30日に参照、2026年11月18日時点で再確認していません)。
ご意見、誤りのご指摘、補足はありますか?ぜひお知らせください。皆さんにとってより良いガイドにするために役立ちます。