> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/tech/ja/platform-development/bring-your-own-vector-db.md).

# 独自のベクトルデータベースの利用

ナレッジベース作成時に組織独自のベクトルデータベースを使用する方法：サポートする種類、入力項目、バージョンとネットワークの要件、作成後の制限

ナレッジベースはデフォルトで MaiAgent が提供するベクトルデータベースにベクトルを保存します。組織が管理する環境内にインデックスデータを保持する必要がある場合は、ナレッジベースの作成時に組織独自のベクトルデータベースに接続できます。ファイルの解析、チャンク分割、ベクトル化は引き続き MaiAgent が処理し、生成したベクトルとパッセージをお客様のデータベースに書き込み、検索時もそのデータベースから読み取ります。このページは、データベース、ネットワーク接続、アカウントを準備するお客様の IT 担当者、DBA、SI パートナー向けです。

{% hint style="info" %}
**「データベース」機能との違い**：管理画面の[データベース](https://docs.maiagent.ai/build/database/create-database)機能は、Text to SQL がクエリを実行するリレーショナルデータベース（PostgreSQL、MySQL、SQL Server、Oracle、SynxDB）に接続し、Agent がデータを検索できるようにします。このページの独自のベクトルデータベースは、ナレッジベースのベクトルとパッセージの保存先です。両者は個別に設定し、互いに影響しません。

**ユーザーマニュアルとの役割分担**：ナレッジベース作成の一般的な手順（名前、パーサー、Embedding モデルなど）は、ユーザーマニュアルの[ナレッジベースの作成方法：基本設定](https://docs.maiagent.ai/build/knowledge-base/km-basic-settings)をご覧ください。機能の有効化状況は[組織概要：高度な機能](https://docs.maiagent.ai/org/overview/organization-overview#advanced-features)で確認できます。このページでは、ベクトルデータベースの仕様と連携要件のみを説明します。
{% endhint %}

## 利用条件 <a href="#availability" id="availability"></a>

| 条件                               | 説明                                                                                                              |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| 組織で「カスタムベクトルデータベース接続」が有効になっていること | エンタープライズ版の機能です。SaaS では MaiAgent による組織への有効化が必要なため、営業窓口にお問い合わせください。オンプレミスやプライベートクラウドへのインストール後に作成した組織では、デフォルトで有効です |
| 作成者のロール権限                        | ナレッジベースを作成するには「ナレッジベース権限」が必要です                                                                                  |

有効化すると、ナレッジベース作成ダイアログに <mark style="color:blue;">ベクトルデータベース</mark> タブが追加されます。有効化されていない組織ではこのタブは表示されず、API でカスタム接続を指定しても拒否されます（`This organization is not authorized to use custom vector database endpoints.`）。

## サポートするデータベースの種類 <a href="#supported-databases" id="supported-databases"></a>

<mark style="color:blue;">ベクトルデータベース</mark> タブで <mark style="color:blue;">カスタムベクトルデータベースを使用</mark> を選択し、<mark style="color:blue;">ベクトルデータベースの種類を選択</mark> から種類を選びます。プラットフォームは以下の 4 種類をサポートします。実際に選択できる項目はフォームの表示に従ってください：

| 種類                      | <mark style="color:blue;">Endpoint URL</mark> の形式                              | 認証項目                                                                              | RRF ハイブリッド検索                                              |
| ----------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- | --------------------------------------------------------- |
| Elasticsearch           | URL（例：`https://es.acme.com:9200`）                                              | <mark style="color:blue;">API Key</mark>（任意です。クラスターが認証不要の場合は空欄にできます）              | 有効／無効を切り替えられます。Enterprise、Platinum、Trial のいずれかのライセンスが必要です |
| OpenSearch              | URL。**`https://` が必須です**                                                       | <mark style="color:blue;">ユーザー名</mark>、<mark style="color:blue;">パスワード</mark>（必須） | 有効化が必須です                                                  |
| Oracle AI Database 26ai | DSN（例：`oracle.acme.com:1521/ORCLPDB1`）。TNS 記述文字列も使用できます                        | <mark style="color:blue;">ユーザー名</mark>、<mark style="color:blue;">パスワード</mark>（必須） | 非対応のため、自動で無効になります                                         |
| SynxDB                  | `synxdb.acme.com:5432/vectors`、または `postgresql://synxdb.acme.com:5432/vectors` | <mark style="color:blue;">ユーザー名</mark>、<mark style="color:blue;">パスワード</mark>（必須） | 非対応のため、自動で無効になります                                         |

RRF（Reciprocal Rank Fusion）は、キーワード検索と意味ベクトル検索の結果を統合して順位付けします。RRF を無効にした場合や、RRF 非対応のデータベースでも、ベクトル検索は通常どおり利用できます。

## バージョン、アカウント、ネットワークの要件 <a href="#requirements" id="requirements"></a>

作成前に <mark style="color:blue;">接続テスト</mark> をクリックしてください。作成リクエストの送信時に、プラットフォームはサーバー側から再度接続を検証します（タイムアウトは 10 秒です）。接続できない場合は作成せず、`Vector database connection failed. Please check if the database is running.` を返します。

| 種類                      | バージョン                                                  | アカウントに必要な権限                                                                                                    |
| ----------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
| Elasticsearch           | 接続テストではバージョンを確認しません。ライセンスの種類を読み取り、RRF が利用できるか判断します     | インデックスの作成、ドキュメントの書き込み・検索・削除、ライセンス情報の読み取り（読み取れない場合は RRF 非対応と見なします）                                              |
| OpenSearch              | **2.19.0 以上**。これより古いバージョンでは接続テストが即座に失敗します              | インデックスの作成、ドキュメントの書き込み・検索・削除、search pipeline の作成（プラットフォームが `maiagent-rrf-pipeline` という名前の RRF pipeline を作成します）  |
| Oracle AI Database 26ai | **23.4 以上**（Oracle 23ai から AI Vector Search が提供されています） | テーブルとベクトルインデックスの作成、データの読み取り・書き込み・削除                                                                            |
| SynxDB                  | サーバーに pgvector（`vector` 拡張機能）がインストールされている必要があります       | `public` スキーマでのテーブルとインデックスの作成、データの読み取り・書き込み・削除。`vector` 拡張機能が未有効の場合は、それを有効化する権限も必要です。あるいは DBA に事前の有効化を依頼してください |

**ネットワーク**：接続はすべて MaiAgent のサーバーから開始します。お客様のデータベースでは MaiAgent サーバーからの接続を許可してください（一般的なポート：Elasticsearch／OpenSearch は 9200、Oracle は 1521、SynxDB は 5432）。

* **SaaS**：MaiAgent のクラウドサービスからデータベースに接続できる必要があります。接続元 IP をファイアウォールの許可リストに追加する場合は、MaiAgent の窓口にお問い合わせください。
* **オンプレミスとプライベートクラウド**：MaiAgent ホストからデータベースへのルーティングとファイアウォールの許可を確認してください。

{% hint style="warning" %}
OpenSearch はリクエストごとにアカウントの認証情報を送信するため、`https://` のみを受け付けます。Elasticsearch でも `https://` を推奨します。
{% endhint %}

## データの配置 <a href="#data-layout" id="data-layout"></a>

* MaiAgent は、お客様のデータベースに、`agent_` を含み Embedding モデルに基づく名前のインデックス（Elasticsearch／OpenSearch）またはテーブル（Oracle、SynxDB）を作成します。同じデータベースで同じ Embedding モデルを使用するナレッジベースは、同じインデックスまたはテーブルを共有し、ナレッジベースごとにデータを区別します。
* これらのインデックスやテーブルを手動で改名、削除、再作成したり、内部データを直接変更したりしないでください。ファイルの追加、削除、再解析は MaiAgent を通じて操作してください。
* ナレッジベースを削除すると、プラットフォームはお客様のデータベース内にある、そのナレッジベースのベクトルデータのクリーンアップをスケジュールします。完了するまで接続を維持してください。
* 課金項目は、ユーザーマニュアルの[Credits 課金制度](https://docs.maiagent.ai/others/credits)をご覧ください。

## 作成後の制限 <a href="#limitations" id="limitations"></a>

| 項目                  | ルール                                                                                                                                                                           |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ベクトルデータベースの変更       | **変更できません**。作成後の <mark style="color:blue;">ベクトルデータベース</mark> タブには「ベクトルデータベースの設定はナレッジベース作成後にロックされ、変更できません」と表示されます。別のデータベースやシステムのデフォルトに変更するには、新しいナレッジベースを作成し、ファイルを再アップロードしてください |
| RRF の調整             | Elasticsearch では編集時に切り替えられます。ライセンスをアップグレードした後、<mark style="color:blue;">再確認</mark> をクリックして有効化できます                                                                             |
| 別のナレッジベースへのファイル移動   | 移動先のナレッジベースは同じベクトル設定を使用する必要があります。ユーザーマニュアルの[ナレッジベースのファイル移動](https://docs.maiagent.ai/build/knowledge-base/km-file-move)をご覧ください                                                |
| データベースに一時的に接続できない場合 | その間は、このナレッジベースの検索とファイル処理が失敗します。接続情報はナレッジベースに保持されるため、接続復旧後の再設定は不要です                                                                                                            |

## API による作成 <a href="#create-via-api" id="create-via-api"></a>

`POST /api/v1/knowledge-bases/` に以下の項目を指定すると、独自のベクトルデータベースを使用するナレッジベースを作成できます。すべての項目は、API ドキュメントサイトの[ナレッジベース（新版）](https://docs.maiagent.ai/api/api-reference/zhi-shi-ku-xin-ban)をご覧ください：

| 項目                                        | 説明                                                                           |
| ----------------------------------------- | ---------------------------------------------------------------------------- |
| `vectorDatabaseType`                      | `elasticsearch`、`opensearch`、`oracle`、または `synxdb`                           |
| `vectorDatabaseUrl`                       | Endpoint URL または DSN。空欄の場合はシステムのデフォルトを使用します                                  |
| `vectorDatabaseApiKey`                    | Elasticsearch の API Key                                                      |
| `opensearchUsername`、`opensearchPassword` | OpenSearch の認証情報                                                             |
| `oracleUser`、`oraclePassword`             | Oracle の認証情報                                                                 |
| `synxdbUser`、`synxdbPassword`             | SynxDB の認証情報                                                                 |
| `enableRrf`                               | RRF を有効にするかどうかを指定します。Oracle と SynxDB では常に `false`、OpenSearch では `true` が必須です |

ナレッジベースの読み取り時にパスワード項目は返されません。Elasticsearch と OpenSearch の URL と API Key はマスキングして返されます。作成前に `POST /api/v1/validate-credentials/vector-database/{類型}/` を呼び出し、接続だけを個別にテストすることもできます。これは管理画面の <mark style="color:blue;">接続テスト</mark> が使用するエンドポイントでもあります。

## よくある質問 <a href="#faq" id="faq"></a>

<details>

<summary>ナレッジベース作成時に「ベクトルデータベース」タブが表示されない場合は？</summary>

組織で「カスタムベクトルデータベース接続」が有効になっていません。これはエンタープライズ版の機能です。営業窓口に有効化を依頼してください。

</details>

<details>

<summary>Elasticsearch への接続は成功するのに、RRF が自動で無効になる場合は？</summary>

RRF には Enterprise、Platinum、Trial のいずれかのライセンスが必要です。これらがない場合は無効のままにしてください。有効にするとクラスターが検索リクエストを拒否します。ライセンスのアップグレード後、ナレッジベースの編集画面で <mark style="color:blue;">再確認</mark> をクリックしてください。

</details>

<details>

<summary>OpenSearch の接続テストでバージョンが古すぎると表示される場合は？</summary>

MaiAgent は OpenSearch の search pipeline で RRF を実行するため、2.19.0 以上が必要です。先にクラスターをアップグレードしてください。

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/tech/ja/platform-development/bring-your-own-vector-db.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.