> 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/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> 挑一種。平台支援以下四種，實際可選的項目以表單列出的為準：

| 類型                      | <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` schema 建立資料表與索引、讀寫與刪除資料；`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/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.