Onyx導入ガイド：企業向け社内ドキュメントAI検索基盤をDocker Composeで構築・運用する

社内ドキュメントが散在する課題に対して、RAG（Retrieval Augmented Generation）ベースのAI検索基盤を構築する選択肢が増えている。OnyxはGitHubスター22,000超のオープンソースプロジェクトで、Docker Composeによるセルフホスティングに対応する企業向けRAGプラットフォームだ。この記事では、Onyxのインストールからデータソース接続、API活用、運用時のチューニングまで、導入に必要な実践的な手順を解説する。Onyxの機能概要や競合との全体比較については、Onyx：企業向けAIチャットボットの概要記事を参照してほしい。

この記事ではRAGに特化して解説します。RAG全般は RAGとは？仕組み・構築・ベクトルDB選定まで【2026年完全ガイド】 をご覧ください。

Docker Composeによる社内ドキュメントAI検索環境のセットアップ

Onyxはdocker composeでの構築が公式に推奨されている。公式リポジトリにはワンラインのインストールスクリプトが用意されているが、本番運用を見据える場合はdocker-compose.ymlを直接扱う方がカスタマイズしやすい。

まずリポジトリをクローンし、環境変数を設定する。

# リポジトリのクローン
git clone https://github.com/onyx-dot-app/onyx.git
cd onyx/deployment/docker_compose

# 環境変数ファイルの作成
cp .env.example .env

.envファイルで最低限設定が必要な項目は以下の通り。

# LLMプロバイダの設定（OpenAIの場合）
GEN_AI_MODEL_PROVIDER=openai
GEN_AI_MODEL_VERSION=gpt-4
GEN_AI_API_KEY=sk-xxxxxxxxxxxxxxxx

# Anthropic Claudeを使う場合
# GEN_AI_MODEL_PROVIDER=anthropic
# GEN_AI_MODEL_VERSION=claude-sonnet-4-20250514
# GEN_AI_API_KEY=sk-ant-xxxxxxxxxxxxxxxx

# PostgreSQL設定
POSTGRES_USER=onyx
POSTGRES_PASSWORD=your_secure_password_here

# セキュリティ設定
AUTH_TYPE=basic
SECRET_KEY=$(openssl rand -hex 32)

設定完了後、docker composeで起動する。

# 全サービスの起動（バックグラウンド）
docker compose -f docker-compose.dev.yml -p onyx-stack up -d

# 起動状態の確認
docker compose -f docker-compose.dev.yml -p onyx-stack ps

初回起動時には、PostgreSQL、Vespa（検索エンジン）、バックエンドAPI、フロントエンドのコンテナがそれぞれ立ち上がる。全サービスがhealthyになるまで数分待つ。起動完了後、http://localhost:3000でWeb UIにアクセスできる。

公式推奨スペックはCPU 4コア以上、メモリ16GB以上、ストレージ50GB以上。大規模環境ではVespaのインデックスに応じてメモリの増強が必要になる。

RAGパイプラインの処理フローを理解する

Onyxを運用するにあたり、内部のRAGパイプラインがどう動いているかを把握しておくとトラブルシューティングが効率的になる。以下はOnyxのデータ取り込みからユーザーへの回答生成までの全体フローだ。

ポイントは、Onyxがベクトル検索（意味的な類似度）とBM25（キーワードベースの全文検索）のハイブリッド検索を採用している点だ。これにより、「有給休暇の申請方法」のような自然文の質問にも、「有給 申請 フォーム」のようなキーワード的な検索にも対応する。RAGFlowが同様にハイブリッド検索を採用しているように、企業向けRAGでは単一の検索手法では精度が不足するケースが多い。

コネクタ設定：Slack・Confluence・Google Driveの接続手順

Onyxは50以上のデータソースコネクタを提供している。管理画面のGUIから設定できるが、本番環境ではAPIを通じたプログラマティックな設定も可能だ。

主要コネクタの設定要件

Slackコネクタを例に設定手順を説明する。まずSlack APIでBot Tokenを発行し、対象チャンネルにボットを招待する。その後、OnyxのAPIを通じてコネクタを登録する。

# Slackコネクタの作成（API経由）
curl -X POST http://localhost:8080/api/manage/connector \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ONYX_API_KEY" \
  -d '{
    "name": "company-slack",
    "source": "slack",
    "connector_specific_config": {
      "workspace": "your-workspace",
      "channels": ["general", "engineering", "product"],
      "channel_regex_enabled": false
    },
    "refresh_freq": 600,
    "credential_ids": [1]
  }'

refresh_freqはデータの再同期間隔（秒）で、デフォルトの600秒（10分）を組織の要件に合わせて調整する。リアルタイム性が求められる場合は短縮可能だが、APIレート制限とサーバー負荷のバランスに注意が必要だ。

Confluenceの場合はAtlassian APIトークン、Google DriveはGCPサービスアカウントのJSON鍵ファイルを登録する。いずれも管理画面の「Connectors」タブからGUIで追加可能だ。

初回のインデックス作成はデータ量に応じて数時間かかる場合がある。管理画面の「Indexing Status」で進捗を確認しながら待つ。

Onyx APIの活用：外部アプリケーションとの連携

OnyxはREST APIを提供しており、Web UIだけでなく外部アプリケーションやSlackボットからの利用にも対応している。ここでは実際のAPIエンドポイントを使った質問応答と、ドキュメント検索の例を示す。

質問応答API

import requests

ONYX_URL = "http://localhost:8080"
API_KEY = "your_onyx_api_key"

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {API_KEY}"
}

# チャットセッションの作成
session_response = requests.post(
    f"{ONYX_URL}/api/chat/create-chat-session",
    headers=headers,
    json={
        "persona_id": 0,
        "description": "API経由の質問"
    }
)
session_id = session_response.json()["chat_session_id"]

# 質問の送信
query_response = requests.post(
    f"{ONYX_URL}/api/chat/send-message",
    headers=headers,
    json={
        "chat_session_id": session_id,
        "parent_message_id": None,
        "message": "社内のデプロイ手順を教えてください",
        "prompt_id": 0,
        "search_doc_ids": None,
        "retrieval_options": {
            "run_search": "auto",
            "real_time": True
        }
    }
)

# ストリーミングレスポンスの処理
for line in query_response.iter_lines():
    if line:
        print(line.decode("utf-8"))

APIレスポンスはストリーミング形式で返却される。各チャンクには回答テキストに加え、引用元ドキュメントのメタデータ（タイトル、ソース、リンク）が含まれる。このAPIを活用すれば、LangChainのチェーン構造と組み合わせた高度なワークフローも構築可能だ。

ドキュメント検索API

質問応答ではなく、単純なドキュメント検索だけを行いたい場合は、検索APIを直接叩く方法もある。

# ドキュメント検索のみ（LLMを使わない）
search_response = requests.post(
    f"{ONYX_URL}/api/direct-qa",
    headers=headers,
    json={
        "messages": [
            {
                "message": "Kubernetes デプロイ 本番環境",
                "sender": "user"
            }
        ],
        "retrieval_options": {
            "run_search": "always",
            "real_time": True,
            "filters": {
                "source_type": ["confluence", "google_drive"]
            }
        }
    }
)

results = search_response.json()
for doc in results.get("top_documents", []):
    print(f"[{doc['source_type']}] {doc['semantic_identifier']}")
    print(f"  Score: {doc['score']:.3f}")
    print(f"  Link: {doc['link']}")

filtersパラメータで検索対象をソースタイプ別に絞り込める。たとえば「Confluenceだけ」「Google Driveだけ」という指定が可能で、ノイズの多い環境では精度向上に効果がある。

企業向けRAG基盤の比較：Onyx vs Dify vs RAGFlow

社内ドキュメントのAI検索基盤を構築するツールは複数ある。Onyxを含む主要な3つのOSSツールを、導入・運用の観点で比較する。

Onyxの強みは、社内で使われている既存ツール（Slack、Confluence、Google Drive等）との接続が管理画面からGUIで完了する点だ。コネクタの豊富さでは他のツールを上回る。一方、Difyはワークフロービルダーが充実しており、RAG以外の用途（チャットボット構築、業務自動化）にも広く使える。RAGFlowはDeepDocパーサーによるPDFや表データの高精度な構造解析に強みがある。

既存SaaSからドキュメント集約ならOnyx、ノーコードワークフローならDify、PDF・表データの高精度解析ならRAGFlow、という使い分けが目安になる。

運用時のチューニングとパフォーマンス最適化

Onyxを本番環境で安定運用するには、いくつかの設定項目を環境に合わせて調整する必要がある。

インデックスの最適化

初期インデックス作成後、検索精度が期待に達しない場合は以下の項目を確認する。

• チャンクサイズ: デフォルトのチャンクサイズ（512トークン前後）が短すぎる場合、文脈が分断されて回答品質が落ちる。技術文書では1024トークン程度に拡大すると改善する場合がある
• 埋め込みモデルの選択: デフォルトの埋め込みモデルで精度が不足する場合、環境変数でモデルを切り替えられる。多言語対応が必要な環境ではmultilingual-e5-large等の多言語モデルが有効
• 同期間隔の調整: ドキュメント更新頻度が低いソースの同期間隔を延ばし、サーバー負荷を軽減する

リソースモニタリング

本番運用では、以下のメトリクスを定期的に監視する。

# コンテナごとのリソース使用量確認
docker stats --format "table \t\t\t"

# Vespa（検索エンジン）のインデックスサイズ確認
curl -s http://localhost:19071/application/v2/tenant/default/application/default/environment/prod/region/default/instance/default/content/search/status | python3 -m json.tool

# PostgreSQLの接続数確認
docker exec onyx-stack-relational_db-1 psql -U onyx -c "SELECT count(*) FROM pg_stat_activity;"

Vespaのメモリ使用量が70%を超えたら、早めのスケールアップを検討する。

セキュリティ設定

社内の機密情報を扱う以上、認証・認可の設定は必須だ。

• 認証方式: .envのAUTH_TYPEでbasic（ID/パスワード）、google_oauth（Google OAuth）、saml（SAML SSO）を選択可能
• アクセス制御: ユーザーグループを作成し、コネクタごとにアクセス可能なグループを制限する。Slackのプライベートチャンネル等の権限がOnyxにも反映される
• ネットワーク: 本番環境ではリバースプロキシ（nginx等）の背後に配置し、HTTPS通信を強制する。ポート8080を外部に直接公開しない

バックアップとアップデートの運用手順

Onyxのデータは主にPostgreSQL（メタデータ、ユーザー情報）とVespa（ドキュメントインデックス）に保存される。障害復旧に備えて、定期的なバックアップを設定しておく。

# PostgreSQLのバックアップ
docker exec onyx-stack-relational_db-1 \
  pg_dump -U onyx -d onyx > backup_$(date +%Y%m%d).sql

# バックアップのリストア
docker exec -i onyx-stack-relational_db-1 \
  psql -U onyx -d onyx < backup_20260401.sql

バージョンアップデートの手順は以下の通り。

# 最新版の取得
cd onyx
git pull origin main

# サービスの再起動（ダウンタイムあり）
cd deployment/docker_compose
docker compose -f docker-compose.dev.yml -p onyx-stack down
docker compose -f docker-compose.dev.yml -p onyx-stack pull
docker compose -f docker-compose.dev.yml -p onyx-stack up -d

アップデート時にはデータベースのマイグレーションが自動実行される。メジャーバージョン間のアップデートではリリースノートを事前に確認し、Vespaの再インデックスが必要かどうかを確認する。

関連記事: RAGとは？仕組み・構築・ベクトルDB選定まで【2026年完全ガイド】

まとめ：社内ドキュメントAI検索基盤の導入判断

Onyxは、Docker Composeで構築できるセルフホスティング型の企業向けRAG基盤だ。50以上のコネクタにより既存ツールとの接続がスムーズで、REST APIを通じた外部連携にも対応している。

導入を検討する際のチェックポイントをまとめる。

• サーバーリソース: 最低4コア/16GB RAM。ドキュメント規模が大きい場合は32GB以上を推奨
• LLM選定: 外部API（OpenAI、Claude等）を使う場合はAPIコストが発生。ローカルLLMを使う場合はGPUサーバーが必要
• 運用体制: コネクタの設定やアクセス制御の管理に、ITインフラを理解するメンバーが最低1名は必要
• データ機密性: セルフホスティングのためデータが外部に流出しない設計だが、ネットワーク設定とアクセス制御は組織の責任で運用する

LangChainベースで独自のRAGパイプラインを構築する方法と比較して、Onyxはインフラの構築・運用コストが低く、非エンジニアでも検索インターフェースを利用できる点が利点だ。一方で、検索ロジックの細かなカスタマイズには限界があるため、高度なRAGパイプラインが必要な場合はRAGFlowも検討する価値がある。

参照ソース

• Onyx GitHub Repository
• Onyx Official Documentation
• Onyx Docker Compose Deployment Guide
• Vespa Search Engine Documentation