自帶向量資料庫

建立知識庫時改用組織自有的向量資料庫：支援的類型、要填的欄位、版本與網路需求，以及建立後的限制

知識庫預設把向量存在 MaiAgent 提供的向量資料庫。組織若要求索引資料留在自己管理的環境，可以在建立知識庫時改接組織自有的向量資料庫：檔案的解析、切塊與向量化仍由 MaiAgent 處理，產生的向量與段落寫進您的資料庫，檢索時也從您的資料庫讀取。本頁寫給要準備資料庫、開網路與帳號的客戶 IT、DBA 與 SI 夥伴。

和「資料庫」功能不同：後台的資料庫功能接的是 Text to SQL 要查詢的關聯式資料庫（PostgreSQL、MySQL、SQL Server、Oracle、SynxDB），讓 Agent 查資料；本頁的自帶向量資料庫是知識庫存放向量與段落的位置，兩者分開設定、互不影響。

和使用者手冊的分工：建立知識庫的一般步驟（名稱、解析器、Embedding 模型等）見使用者手冊如何建立知識庫：基本設置；功能開通狀態可在組織概覽：進階功能查看。本頁只寫向量資料庫的規格與整合要求。

開通條件

條件	說明
組織已開通「自訂向量資料庫連線」	企業版功能。SaaS 需由 MaiAgent 為組織開通，請聯繫業務窗口；地端與私有雲安裝後新建的組織預設開啟
建立者的角色權限	需要「知識庫權限」才能建立知識庫

開通後，建立知識庫的視窗會多出 向量資料庫 分頁；未開通的組織看不到這個分頁，用 API 帶自訂連線也會被拒絕（This organization is not authorized to use custom vector database endpoints.）。

支援的資料庫類型

在 向量資料庫 分頁選 使用自定義向量資料庫，再從 選擇向量資料庫類型 挑一種。平台支援以下四種，實際可選的項目以表單列出的為準：

類型	Endpoint URL 格式	認證欄位	RRF 混合檢索
Elasticsearch	URL，例如 https://es.acme.com:9200	API Key（選填，叢集不需認證時可留空）	可開可關；需要 Enterprise、Platinum 或 Trial 授權
OpenSearch	URL，必須是 https://	使用者名稱、密碼（必填）	必須開啟
Oracle AI Database 26ai	DSN，例如 oracle.acme.com:1521/ORCLPDB1，也接受 TNS 描述字串	使用者名稱、密碼（必填）	不支援，系統自動關閉
SynxDB	synxdb.acme.com:5432/vectors，或 postgresql://synxdb.acme.com:5432/vectors	使用者名稱、密碼（必填）	不支援，系統自動關閉

RRF（Reciprocal Rank Fusion）把關鍵字檢索與語意向量檢索的結果合併排序。關閉 RRF 或不支援 RRF 的資料庫，仍可正常做向量檢索。

版本、帳號與網路需求

建立前請先按 測試連接。送出建立時，平台會再從伺服器端連線驗證一次（逾時 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 主機到資料庫的路由與防火牆已開通即可。

OpenSearch 只接受 https://，因為帳號密碼會隨每個請求送出。Elasticsearch 也建議使用 https://。

資料怎麼放

• MaiAgent 會在您的資料庫建立名稱含 agent_、依 Embedding 模型命名的索引（Elasticsearch／OpenSearch）或資料表（Oracle、SynxDB）。同一個資料庫上、使用相同 Embedding 模型的知識庫會共用同一個索引或資料表，以知識庫區分資料。

• 請不要手動改名、刪除或重建這些索引與資料表，也不要直接修改裡面的資料；檔案的新增、刪除與重新解析都請透過 MaiAgent 操作。

• 刪除知識庫時，平台會排程清除這個知識庫在您資料庫裡的向量資料，請在清除完成前保持連線可用。

• 計費項目見使用者手冊Credits 計費制度。

建立後的限制

項目	規則
更換向量資料庫	不行。建立後 向量資料庫 分頁顯示「向量資料庫配置在知識庫建立後已鎖定，無法修改」。要換資料庫或改回系統預設，請建立新的知識庫並重新上傳檔案
調整 RRF	Elasticsearch 可在編輯時切換；授權升級後可按 重新檢查 再開啟
搬移檔案到其他知識庫	目標知識庫必須使用相同的向量設定，見使用者手冊知識庫檔案搬移
資料庫暫時無法連線	這段期間該知識庫的檢索與檔案處理會失敗；連線資訊保留在知識庫上，恢復連線後不需重新設定

以 API 建立

POST /api/v1/knowledge-bases/ 帶以下欄位即可建立自帶向量資料庫的知識庫，完整欄位見 API 文件站知識庫（新版）：

欄位	說明
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/{類型}/ 單獨測試連線，這也是後台 測試連接 使用的端點。

常見問題

建立知識庫時看不到「向量資料庫」分頁？

組織尚未開通「自訂向量資料庫連線」。這是企業版功能，請聯繫業務窗口開通。

Elasticsearch 連線成功，但 RRF 被自動關閉？

RRF 需要 Enterprise、Platinum 或 Trial 授權。沒有這些授權時請維持關閉，否則叢集會拒絕檢索請求。升級授權後到知識庫編輯畫面按 重新檢查。

OpenSearch 連線測試說版本太舊？

MaiAgent 用 OpenSearch 的 search pipeline 做 RRF，需要 2.19.0 以上，請先升級叢集。