🔐 権限付きRAGを支える構造とデータモデル - PipesHub

PipesHub は、企業内に散在するデータを権限付きで検索し、引用可能なコンテキストとして AI エージェントへ渡すためのオープンソース基盤です。本記事では、全体アーキテクチャ、権限とブロックを中心にしたデータモデル、Docker Compose・Kubernetes での導入、利用と運用上の要点までを一続きで解説します。

一般的な Enterprise RAG の認可論ではなく、PipesHub 固有の「コネクタから ACL を取り込み、Record / Block へ構造化し、検索結果と citation を返す」経路に焦点を当てます。API、Compose、内部モデルの例は 2026 年 8 月 17 日時点の 097295c を基準に確認しています。

この記事の全体像。以下、順に解説します。

概要

PipesHub は、企業内に分散する膨大な業務データソースを統合し、正確な引用（Citation）を伴うエンタープライズ検索と自律型 AI エージェントの実行基盤を提供するオープンソース（Apache 2.0）の AI Context Layer です。

従来のエンタープライズ検索や汎用 RAG（Retrieval-Augmented Generation）システムでは、データソース元の権限モデル（ACL: Access Control List）の維持や、ドキュメント内のどの段落・テーブル・画像に基づいた回答であるかの根拠提示が困難でした。PipesHub は、50 種類以上のエンタープライズコネクタ（Google Workspace、Microsoft 365、Slack、Notion、Jira、Confluence、GitHub 等）からデータを同期し、対応コネクタで ID・メールアドレスなどの対応付け条件を満たす範囲でソース権限を検索へ反映します。

権限同期はコネクタ固有の制約を受けます。たとえば外部サービスと PipesHub のメールアドレスが一致しない場合や、Confluence 側でユーザーのメールアドレスが非公開の場合は、正しい主体へ ACL を割り当てられないことがあります。導入時は同期件数だけでなく、代表ユーザーごとの検索可視性を必ず確認します。

さらに、ベクトル検索（Qdrant / OpenSearch / Redis）とナレッジグラフ（ArangoDB / Neo4j）を融合したハイブリッド検索エンジンを内包しています。これにより、意味的な類似度検索に加えて、組織・人・プロジェクト・ドキュメント間の関係性を辿るグラフ走査を行い、精度の高いコンテキストを LLM に供給します。完全セルフホスト可能であり、プライベートクラウドやオンプレミス環境においてデータ主権を維持しながら導入できます。

関連技術との位置づけと詳細比較

PipesHub は「検索 UI」だけでなく、コネクタ、ACL、ブロック構造、検索、引用、エージェント実行を一体でセルフホストする設計です。関連製品とは提供形態と拡張境界が異なるため、単純な機能数やメモリ量ではなく、次の軸で見ると位置づけが分かりやすくなります。表は 2026 年 8 月 17 日時点の各公式情報を基準にしています。

Onyx は公式 README で 50 種類以上のインデックス型コネクタを案内しています。各製品は Lite 構成、標準構成、SaaS で計測条件が揃わないため、必要メモリの横並び比較は行いません。

ユースケース別の推奨技術

特徴

PipesHub の中核的な技術的特徴は以下のとおりです。

• 50 種以上のエンタープライズコネクタによる包括的データ統合

  • Google Workspace（Drive, Gmail, Calendar）、Microsoft 365（OneDrive, SharePoint, Outlook, Teams）、Atlassian（Confluence, Jira）、Slack、Notion、GitHub、GitLab、Salesforce、ServiceNow、各種 RDBMS/DWH（PostgreSQL, Snowflake, MariaDB）およびオブジェクトストレージ（S3, Azure Blob, GCS, MinIO）に対応します。
  • 定期ポーリング同期および Webhook / イベント駆動型のリアルタイム差分同期をサポートします。

• ソースレベルの厳密なパーミッション制御（Permission-Aware Search）

  • 元データソースのユーザー、グループ、組織階層、リンク公開設定を同期・マッピングします。
  • 検索時および RAG 実行時にユーザーのコンテキストに基づいた認可フィルタリングを適用し、閲覧権限のない情報の漏洩を防止します。

• ベクトル検索とナレッジグラフのハイブリッド RAG

  • 高速な高次元ベクトル検索（Qdrant / OpenSearch / Redis）により意味的な関連文書を抽出します。
  • グラフデータベース（ArangoDB / Neo4j）を活用し、文書間の親子・参照関係、起票者・担当者・メンション、プロジェクト・コンテナのトポロジー構造を走査して高度なコンテキストを構築します。

• ブロック単位の精密かつ説明可能な引用（Explainable Block Citations）

  • ドキュメントを段落、テーブル、コード、リスト、画像などの「Block」単位に構造化してインデックスします。
  • LLM の回答生成時に参照元の特定ブロックをハイライトし、根拠となるソースを正確に追跡できます。

• 高度なマルチモーダル解析と文書パースエンジン

  • PDF パーサーの既定は pdfplumber です。Docling は PARSER_BACKEND で選択でき、複雑なレイアウト、表、画像を扱う構成に切り替えられます。
  • VLM（Vision-Language Model）との連携による OCR 処理および画像内容のセマンティック抽出に対応します。

• BYOM（Bring Your Own Model）とマルチ LLM オーケストレーション

  • LiteLLM および LangChain / LangGraph をベースとし、OpenAI、Anthropic、Google Gemini、AWS Bedrock、Azure OpenAI、Ollama、vLLM 等の多様なプロバイダを切り替え可能です。
  • ローカル Embedding サーバー（SentenceTransformers / HuggingFace）を内包し、外部通信不要の完全オフライン運用にも対応します。

• ノーコード Agent Builder と MCP（Model Context Protocol）ネイティブ対応

  • GUI 上で業務特化エージェントを視覚的に構築し、企業データとツール（Toolset / Skill）を連携できます。
  • MCP Server および Client 機能を備え、外部の AI エージェント（Claude Code, Cursor 等）から PipesHub のナレッジをツールとして呼び出すことが可能です。

• クラウドネイティブかつ高可用性なマイクロサービスアーキテクチャ

  • Python FastAPI（5 サービス）と Node.js API、Next.js フロントエンドで構成され、Kafka / Redis Streams による非同期分散メッセージングを採用しています。
  • Docker Compose によるシングルノード展開から、Kubernetes（Helm Chart）による高可用性マルチレプリカ構成まで柔軟にスケーリング可能です。

構造

PipesHub のシステム構造を C4 モデルの 3 段階（システムコンテキスト、コンテナ、コンポーネント）で図解します。

システムコンテキスト図

システムコンテキスト図は、エンドユーザー、外部の各種エンタープライズデータソース、外部 LLM プロバイダ、外部 MCP クライアントと PipesHub の全体的な相互関係を示します。

コンテナ図

コンテナ図は、PipesHub プラットフォームを構成する Web フロントエンド、API ゲートウェイ、マイクロサービス群、および各種バックエンドデータストアの連携構成を示します。

コンポーネント図

主要な 3 つのマイクロサービス（Query Service、Indexing Service、Connectors Service）の内部コンポーネント構成を図解します。

1. Query Service 内部コンポーネント

2. Indexing Service 内部コンポーネント

3. Connectors Service 内部コンポーネント

データ

PipesHub におけるデータ構造を「概念モデル」と「情報モデル」の 2 つの側面から詳細に定義します。

概念モデル

概念モデルは、組織・権限、データコンテナ（RecordGroup）、個別アイテム（Record）、コンテンツを構成するブロック構造（BlocksContainer / BlockGroup / Block）、およびベクトル・グラフインデックスの論理的な関係を示します。

情報モデル

次の図は、現行ソースの Pydantic モデルから検索と引用に関係するフィールドだけを抜き出した簡略図です。永続化先では一部が camelCase に変換されるため、API のレスポンス型と Python 内部モデルを混同しないでください。

この構造では、ACL は allowedUserIds のような単一配列へ押し込められていません。コネクタが取得した主体と権限種別を正規化し、Record とグラフ上の関係へ反映します。検索レスポンスはさらに別の公開スキーマへ変換され、metadata.recordName や metadata.score などを返します。

構築方法

PipesHub の環境構築手順、前提条件、デプロイ方法（Docker Compose および Kubernetes / Helm）、および初期セットアップについて説明します。

前提条件とシステム要件

公式 Quickstart が Compose 実行の前提として挙げるのは Git と Docker Compose v2 です。CPU、メモリ、ストレージは、有効にする parser、Embedding、グラフ DB、メッセージブローカー、対象データ量で大きく変わるため、一律の最小値とはしません。APP_MEMORY_LIMIT は予約量ではなく OOM cap です。

ソースコードからコネクタを開発する場合は、実行環境とは要件を分けて考えます。現行の Connector Integration Playbook は Python 3.12 と Node.js 22.15 を案内しています。Kubernetes / Helm の対応版は、利用する chart とクラスタのリリースノートで確認してください。

# Docker および Docker Compose バージョンの確認
docker --version
docker compose version

# 公式 Compose がホストへ公開するポート 3000 の空き確認
nc -z -v -w5 localhost 3000 2>&1 || echo "Port 3000 is available"

Docker Compose によるクイックデプロイ

Docker Compose を使用して、最も手軽に PipesHub 環境を起動する手順です。PipesHub はプロファイル駆動型の構成を採用しています。

• リポジトリのクローンと対話型インストーラーの実行
  • install.sh は SECRET_KEY だけでなく、MongoDB、Qdrant、ArangoDB など選択した構成に必要な credential を生成します。既知の placeholder を残さないため、これを基本手順にします。

# リポジトリのクローン
git clone https://github.com/pipeshub-ai/pipeshub-ai.git
cd pipeshub-ai/deployment/docker-compose

# 対話に沿って構成を選び、安全な .env を生成して起動
./install.sh

手動で env.template を使う場合は、少なくとも SECRET_KEY、MONGO_PASSWORD、QDRANT_API_KEY、選択したグラフ DB の password をランダム値へ置換し、your_... の placeholder が残っていないことを起動前に確認します。

プロファイル別 Docker Compose 構成

PipesHub は、用途やリソース規模に応じてプロファイルを切り替えて起動できます。ただし、COMPOSE_PROFILES はコンテナを起動するだけです。アプリケーションが利用するバックエンドは DATA_STORE、MESSAGE_BROKER、KV_STORE_TYPE も合わせて指定します。

• 軽量構成（Neo4j + Redis Streams）の起動
  • メモリ消費を抑え、Kafka や Zookeeper を起動せずに Redis Streams をメッセージブローカーとして利用します。

# Neo4j + Redis Streams。Redis は KV store と broker を兼用
DATA_STORE=neo4j \
MESSAGE_BROKER=redis \
KV_STORE_TYPE=redis \
COMPOSE_PROFILES=graph-neo4j \
docker compose -p pipeshub-ai up -d

# 起動ログの確認
docker compose -p pipeshub-ai logs -f pipeshub-ai

• ArangoDB + etcd + Kafka を使う単一ノード構成の起動
  • 各 backend の組み合わせをローカルで検証する Compose 例です。各サービスは単一インスタンスで、HA や本番可用性を意味しません。本番は後述の Helm 構成を基準にします。

# ArangoDB + etcd + Kafka
DATA_STORE=arangodb \
MESSAGE_BROKER=kafka \
KV_STORE_TYPE=etcd \
COMPOSE_PROFILES=graph-arango,kv-etcd,broker-kafka \
docker compose -p pipeshub-ai up -d

• 対話型インストールスクリプトの再実行
  • 構成を選び直す場合も deployment/docker-compose/install.sh を使い、profile と選択変数の組み合わせを揃えます。

# インストールスクリプトの実行
./install.sh

Kubernetes (Helm) による本番デプロイ

大規模組織や高可用性（HA）が求められる本番環境では、公式 Helm チャートを使用して Kubernetes クラスタへ展開します。

• Helm リポジトリの準備と設定調整
  • deployment/helm/pipeshub-ai ディレクトリの値（values-cloud.yaml）をカスタマイズします。

cd deployment/helm/pipeshub-ai

# Helm チャートの依存関係更新
helm dependency update .

# クラウド本番用 values を適用したデプロイ
helm upgrade --install pipeshub-ai . \
  --namespace pipeshub \
  --create-namespace \
  -f values-cloud.yaml \
  --set global.secretKey="your-production-secret-key" \
  --set global.frontendPublicUrl="https://pipeshub.example.com"

• Kubernetes Pod 起動状態の検証

# Pod の稼働状態確認
kubectl get pods -n pipeshub -o wide

# Ingress およびサービスエンドポイントの確認
kubectl get ingress,svc -n pipeshub

初期セットアップと管理者アカウント作成

コンテナが起動した後、Web ブラウザから初期管理者のセットアップを行います。

• 初期ウィザードの完了
  • ブラウザで http://localhost:3000（または設定した FRONTEND_PUBLIC_URL）を開きます。
  • 初期管理者メールアドレス、パスワード、組織名（テナント名）を入力して管理者アカウントを作成します。
  • 設定画面から LLM プロバイダの API キー（OpenAI, Anthropic 等）を登録します。

# API 経由でのヘルスチェックによる起動完了確認
curl -f http://localhost:3000/api/v1/health/services || echo "Waiting for services..."

利用方法

PipesHub の主要機能（認証、コネクタ同期、検索 API、チャットボット、SDK 利用、MCP 連携、No-Code Agent）の利用手順を解説します。

必須パラメータと API 認証仕様

PipesHub の REST API を呼び出す際は、Bearer トークン認証が必要です。

• Personal Access Token（PAT）の発行
  • Web UI の「Workspace → Developer settings → Personal Access Tokens」から有効期限を指定してトークンを生成します。

# 環境変数に API トークンとエンドポイントを設定
export PIPESHUB_API_URL="http://localhost:3000"
export PIPESHUB_TOKEN="your_personal_access_token_here"

コネクタの登録とデータ同期

コネクタごとに OAuth、サービスアカウント、同期フィルタのスキーマが異なるため、最初の接続は Web UI から作成するのが安全です。現行バックエンドでは、作成したコネクタを ID で管理します。

これらのリクエスト本文はコネクタ種別によって変わります。固定の connectorType と folderId を全コネクタ共通の公開スキーマとして扱わず、デプロイしたバージョンの OpenAPI または Connector Manager 画面で確認してください。

エンタープライズ検索 API の実行

権限を考慮したハイブリッド検索を実行し、関連ドキュメントおよびブロックを取得します。

• 検索リクエストの送信

curl -X POST "${PIPESHUB_API_URL}/api/v1/search" \
  -H "Authorization: Bearer ${PIPESHUB_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "2026年度 Q3 セキュリティ監査報告書",
    "limit": 5
  }'

検索範囲を絞る場合は、filters.apps にコネクタアプリの ID、filters.kb に Knowledge Base / RecordGroup の ID を指定します。名前やレコード種別を渡すフィールドではありません。

• 検索レスポンスの例（抜粋）

{
  "searchId": "68a000000000000000000001",
  "searchResponse": {
    "searchResults": [
      {
        "content": "SOC2 Type II 監査における指摘事項はゼロ件であり...",
        "chunkIndex": 0,
        "citationType": "text",
        "metadata": {
          "recordId": "rec_789abc",
          "recordName": "Q3_Security_Audit_Report_2026.pdf",
          "webUrl": "https://drive.google.com/file/d/xxx/view",
          "blockType": "text",
          "pageNum": [4],
          "score": 0.942
        }
      }
    ],
    "records": [],
    "status": "success",
    "status_code": 200,
    "message": "Search completed"
  }
}

文書名とスコアはトップレベルではなく、それぞれ metadata.recordName、metadata.score にあります。searchResults はブロックまたはレコード要約のヒットで、グラフ側のレコードは searchResponse.records に分離されます。

上の形は対象コミットに含まれる OpenAPI を優先しています。この版では records は配列で、status、status_code、message も必須です。ホスト済みドキュメントには records を ID キーの map とする旧例が残っているため、異なる版を使う場合は、そのインスタンスが配布する OpenAPI と SDK の生成版を揃えてください。

チャットボット・Q&A API（ストリーミングと引用）

引用付きの回答を Server-Sent Events（SSE）で受信します。新しい会話をストリームで開始する公開 API は /api/v1/conversations/stream です。

• チャット対話リクエスト（Server-Sent Events: SSE）

curl -N -X POST "${PIPESHUB_API_URL}/api/v1/conversations/stream" \
  -H "Authorization: Bearer ${PIPESHUB_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "新しいオンボーディング手順について教えてください",
    "chatMode": "internal_search"
  }'

ストリームは AG-UI のイベント語彙を使い、最初に conversation_created、成功時に RUN_FINISHED、失敗時に RUN_ERROR を返します。既存会話への追加ターンは POST /api/v1/conversations/{conversationId}/messages/stream を使います。

ホスト済みドキュメントや一部 SDK 説明には connected、chunk、citation、complete、error という旧イベント名も残っています。対象コミットの gateway OpenAPI と route 実装は AG-UI を正本としているため、client と server の版がずれる場合はイベント名を固定せず、未知イベントを無視できる実装にします。

Python SDK による連携実装

公式 Python SDK（pipeshub-sdk）を利用したセマンティック検索の例です。

• SDK のインストール

pip install pipeshub-sdk

• Python スクリプト例

import os
from pipeshub_sdk import Pipeshub, models

with Pipeshub(
    server_idx=0,
    instance_url="http://localhost:3000",
    security=models.Security(
        bearer_auth=os.getenv("PIPESHUB_BEARER_AUTH", ""),
    ),
) as pipeshub:
    result = pipeshub.semantic_search.search(
        query="リモートワーク規定",
        limit=3,
    )
    print(result)

SDK のレスポンス型は SemanticSearchExecuteResponse です。enterprise_search や .results ではなく、semantic_search.search() の戻り値として扱います。

TypeScript SDK による連携実装

公式 TypeScript SDK（@pipeshub-ai/sdk）を利用した Node.js 連携です。

• SDK のインストール

npm install @pipeshub-ai/sdk

• TypeScript 実装例

import { Pipeshub } from "@pipeshub-ai/sdk";

const pipeshub = new Pipeshub({
  serverIdx: 0,
  instanceUrl: "http://localhost:3000",
  security: {
    bearerAuth: process.env.PIPESHUB_TOKEN ?? "",
  },
});

async function run() {
  const result = await pipeshub.semanticSearch.search({
    query: "AWS コスト最適化ガイドライン",
    limit: 5,
  });
  console.log(result);
}

run().catch(console.error);

Model Context Protocol (MCP) サーバー連携

PipesHub は /mcp に Streamable HTTP の Remote MCP Server を公開します。Claude Code や Cursor は MCP client としてこの URL へ直接接続でき、ローカル npm プロセスは必須ではありません。

• Claude Code から OAuth で接続する例

claude mcp add --transport http \
  --client-id YOUR_CLIENT_ID \
  --client-secret \
  --callback-port 8080 \
  pipeshub http://localhost:3000/mcp

--client-secret に値を付けないとマスク入力が開きます。PipesHub の Developer Settings で OAuth App を作成し、コールバック URL と公開される MCP_SCOPES をクライアント設定に合わせます。Bearer token を扱えるクライアントでは、同じ http://localhost:3000/mcp に JWT を付けて接続できます。

No-Code Agent Builder と Toolsets の作成

PipesHub の GUI 上で自律エージェントを構築し、特定のワークフローを実行する手順です。

• エージェントの作成手順
  • Web UI の「Agents → New Agent」を開きます。
  • システムプロンプト、使用する LLM モデル、アクセス可能なナレッジベース（KB）を選択します。
  • Toolsets（Slack 投稿、Jira チケット作成、Web 検索等）をエージェントに割り当てます。
  • 作成したエージェントは Web UI 上で対話でき、安定した agentKey を使って API からも実行できます。

# Agent との新しい会話を作成し、応答を SSE で受信
curl -N -X POST "${PIPESHUB_API_URL}/api/v1/agents/agent_456/conversations/stream" \
  -H "Authorization: Bearer ${PIPESHUB_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "先週オープンしたバグチケットのサマリを作成してください",
    "chatMode": "quick"
  }'

続きのメッセージは POST /api/v1/agents/{agentKey}/conversations/{conversationId}/messages/stream へ送ります。Agent のストリームでも AG-UI が使われ、OAuth token では agent:execute scope が必要です。

運用

稼働中における PipesHub のライフサイクル管理、監視、ヘルスチェック、ログ管理、およびデータバックアップ手順を説明します。

サービスの起動・停止・再起動

Docker Compose または Kubernetes 上で各マイクロサービスの状態を安全に制御します。

• Docker Compose での操作コマンド

# 全コンテナの起動
docker compose -p pipeshub-ai up -d

# 稼働ステータスとヘルスチェック状態の確認
docker compose -p pipeshub-ai ps

# サービスの安全な停止
docker compose -p pipeshub-ai stop

# コンテナの破棄とボリュームの維持
docker compose -p pipeshub-ai down

ヘルスチェックと健全性監視

公式 Docker Compose はホストへアプリの 3000 番ポートだけを公開します。内部サービスの 8000、8088、8091 番などをホストの localhost へ直接問い合わせる構成ではありません。

• 集約ヘルスチェックの実行

# Compose が公開する集約エンドポイント
curl -fsS http://localhost:3000/api/v1/health/services | jq .

ログ収集とローテーション管理

PipesHub は Docker のローカルログドライバによるローテーションを設定ファイルで制御しています。

• ログの監視とフィルタリング

# 特定サービスのログをリアルタイム追跡
docker compose -p pipeshub-ai logs -f --tail=100 pipeshub-ai

# エラーログの抽出
docker compose -p pipeshub-ai logs pipeshub-ai 2>&1 | grep -i "error"

• Docker デーモン側のログローテーション設定（docker-compose.yml での指定）

logging:
  driver: local
  options:
    max-size: "20m"
    max-file: "15"
    compress: "true"

メトリクス監視と Telemetry (OpenTelemetry)

PipesHub は OpenTelemetry を組み込んでいますが、公式 Compose はホストの localhost:3001/metrics を公開しません。Telemetry を有効化するときは OTLP の送信先を構成し、Collector、Prometheus、Jaeger 側で受信を確認します。内部ポートをホストへ追加公開する場合は、Compose override とネットワーク境界を明示し、認証なしのメトリクス endpoint を外部へ露出させないでください。

データベースのバックアップとリストア

MongoDB、ArangoDB / Neo4j、Qdrant の定期バックアップはシステムの事業継続性に不可欠です。

• 各データストアのバックアップ実行例

# MongoDB の archive をホスト側へ保存
mkdir -p backups
docker compose -p pipeshub-ai exec -T mongodb mongodump \
  --username admin --password your_mongodb_password \
  --authenticationDatabase admin --archive \
  > backups/mongodb-$(date +%Y%m%d).archive

# Qdrant snapshot を作成。レスポンスに含まれる snapshot 名を控える
docker compose -p pipeshub-ai exec -T pipeshub-ai \
  curl -fsS -X POST "http://qdrant:6333/collections/<collection_name>/snapshots" \
  -H "api-key: ${QDRANT_API_KEY}"

# snapshot を Compose volume 外のホストへダウンロード
docker compose -p pipeshub-ai exec -T pipeshub-ai \
  curl -fsS "http://qdrant:6333/collections/<collection_name>/snapshots/<snapshot_name>" \
  -H "api-key: ${QDRANT_API_KEY}" \
  > backups/qdrant-<snapshot_name>

ArangoDB / Neo4j も利用中の backend に応じて別媒体へ退避します。バックアップは作成だけで完了とせず、暗号化したオブジェクトストレージなど別障害ドメインへ転送し、定期的に隔離環境でリストアを確認します。

ワーカー並列度とスケーリングチューニング

ドキュメントのインデックス流量に応じて、環境変数でワーカー数を調整します。

# .env での並列度チューニング例
INDEXING_UVICORN_WORKERS=2
PARSING_UVICORN_WORKERS=2
MAX_CONCURRENT_PARSING=8
MAX_CONCURRENT_INDEXING=10
MAX_PENDING_INDEXING_TASKS=50

ベストプラクティス

PipesHub を安全かつ高パフォーマンスに運用するための推奨構成および設計指針です。

ゼロトラストセキュリティと権限設計

• 厳格なトークン管理
  • Personal Access Token は必要最小限の有効期限（30日または90日）を設定し、不要になったトークンは直ちに失効させます。
• HTTPS の強制
  • クラウドや社内ネットワークに公開する際は必ずリバースプロキシ（Nginx / Traefik / ALB）で TLS 終端を行い、FRONTEND_PUBLIC_URL に https:// を指定します。

インデックスと検索エンジンの最適化

• ハイブリッド検索のパラメータ調整
  • 高精度な検索を実現するため、ベクトル類似度の閾値とグラフ探索ホップ数（推奨: 1〜2ホップ）をデータ規模に応じてチューニングします。
• Qdrant の HNSW インデックスチューニング
  • 大規模データ（100万件以上）を扱う場合は、Qdrant の m（リンク数）および ef_construct パラメータを調整して検索レイテンシと精度のバランスを取ります。

CI/CD パイプライン連携と自動化

• インフラのコード化（IaC）
  • Helm チャートまたは Terraform を使用して、PipesHub のクラスタ設定やコネクタのシークレットをバージョン管理下で自動デプロイします。

# GitHub Actions ワークフロー例 (抜粋)
name: Deploy PipesHub to Staging
on:
  push:
    branches: [ main ]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Deploy via Helm
        run: |
          helm upgrade --install pipeshub ./deployment/helm/pipeshub-ai \
            --namespace staging -f values-staging.yaml

リソース割り当てと OOM 対策

• コンテナメモリ上限の明確な設定
  • 巨大な PDF や Office 文書の一括パース時は、メモリ使用量が一時的に増えます。env.template の APP_MEMORY_LIMIT、MONGO_MEMORY_LIMIT、MONGO_CACHE_GB は予約量ではなく上限・cache 設定です。ホスト容量、同時パース数、実データの観測値を基に調整し、固定値を全環境へ流用しないでください。

トラブルシューティング

PipesHub の運用中に発生しやすい障害事象、その原因、および具体的な対処手順をまとめます。

障害切り分けとログ調査の基本手順

トラブルシューティング時の迅速な原因特定のための基本方針です。

• ログレベルの一時的引き上げ: 問題が発生しているコンポーネントの LOG_LEVEL=debug に設定し、詳細なリクエスト/レスポンスログを取得します。
• コンテナ健全性ステータスの確認: docker compose ps または kubectl get pods で各サービスの再起動回数（Restarts）と終了コード（Exit Code）を確認します。
• データストア接続性の個別疎通確認: Redis と MongoDB は各コンテナ内の client を使います。Qdrant はホストへ公開されないため、docker compose -p pipeshub-ai exec -T pipeshub-ai curl -fsS http://qdrant:6333/healthz のように Compose network 内から確認します。
• メッセージブローカーキューの滞留確認: Kafka または Redis Streams のコンシューマー遅延（Lag）および未処理タスク数を確認します。

トラブルシューティング一覧

まとめ

PipesHub の特徴は、コネクタの多さだけではありません。Record と Block を中心に文書構造を保持し、ユーザー・グループ・組織の権限情報を検索経路へ組み込むことで、企業データを AI に渡す際の「検索精度」「根拠提示」「情報漏えい防止」を同じ設計上で扱えます。

一方で、Query・Indexing・Connectors・Docling・Embedding の各サービスと、ベクトル DB、グラフ DB、メタデータストア、メッセージブローカーを運用するため、軽量な個人向け RAG よりインフラ負荷は高くなります。まず Docker Compose の軽量プロファイルで対象コネクタ、ACL、引用表示を検証し、必要なデータ量と可用性が見えてから Kubernetes や Kafka を含む構成へ進むのが現実的です。

この記事が少しでも参考になった、あるいは改善点などがあれば、ぜひリアクションやコメント、SNSでのシェアをいただけると励みになります！

参考リンク

公式ドキュメント・ポータル

• PipesHub Official Website
• PipesHub Official Documentation
• PipesHub Quickstart Guide
• PipesHub Connector Overview
• PipesHub Enterprise Search API
• PipesHub Troubleshooting Guide
• PipesHub Product Roadmap (Notion)

ソースコードリポジトリ・SDK

• PipesHub Main GitHub Repository
• PipesHub OpenAPI at 097295c
• PipesHub Permission Model at 097295c
• PipesHub Record Model at 097295c
• PipesHub Block Model at 097295c
• PipesHub Python SDK Repository
• PipesHub TypeScript SDK Repository
• PipesHub Go SDK Repository
• PipesHub MCP Server Repository
• Onyx Repository
• Onyx License

コミュニティ・エコシステム

• PipesHub Discord Community
• PipesHub GitHub Issues