知識庫與文件問答
知識庫是 Aivory 的長期文件倉庫:把一組文件上傳一次,之後任何對話都可以掛載它做檢索問答,回答自動帶來源引用。本頁覆蓋知識庫的建立、文件入庫、對話中的使用方式、檢索原理,以及「檢索結果為空」的完整排查清單。
與知識庫並行的還有兩種文件作用域,三者共用同一套解析與檢索引擎:
| 作用域 | 存放位置 | 檢索範圍 | 典型用途 |
|---|---|---|---|
| 對話臨時檔案 | 上傳它的那個對話 | 僅該對話 | 單檔案問答,「幫我讀一下這份 PDF」 |
| 知識庫 | 獨立的知識庫頁面 | 任何掛載了它的對話 | 長期複用的資料集 |
| 專案知識庫 | 專案 | 該專案下的全部對話 | 團隊/主題資料,見團隊工作空間與專案功能 |
前置條件
知識庫依賴三類後端能力,缺哪一項會退化成什麼行為,先了解清楚:
| 依賴 | 作用 | 未配置時的行為 |
|---|---|---|
嵌入模型(kind='embedding' 的模型條目,或環境變數兜底) | 文件向量化與查詢向量化 | 無法完成嵌入,大文件不可檢索;小文件仍可全文注入 |
Qdrant(QDRANT_URL) | 稠密向量檢索 | 向量檢索停用,RAG 走全文上下文回退 |
| MinerU + 物件儲存(S3 / 阿里雲 OSS) | 掃描件 PDF、Office 文件、圖片的雲端解析與 OCR | 非純文本文件解析失敗,知識庫文件標記為失敗 |
- 生產 Docker Compose 已內建 Qdrant 容器,見Docker Compose 部署。
- 嵌入模型在管理後臺「渠道 / 模型」裡配置:掛在某個 OpenAI 型別渠道下,填寫請求模型名與維度,任何暴露 OpenAI
/v1/embeddings格式的服務(OpenAI、Voyage、自部署 BGE-M3 等)都能接。詳見渠道與模型與核心配置。 - MinerU 的 API 地址、token 與物件儲存憑據在管理後臺「文件」頁配置,儲存即生效,無需重啟。
同一個知識庫的所有向量(包括提問時的查詢向量)必須來自同一個嵌入模型,不同模型的向量空間互不相容。因此嵌入模型在建庫時選定、建庫後不可更換,更換等於全量重新嵌入。
建立知識庫
入口:側欄底部頭像選單裡的「知識庫」,進入知識庫列表頁,點「新建知識庫」。
建立對話方塊欄位:
| 欄位 | 必填 | 說明 |
|---|---|---|
| 名稱 | 是 | 同一賬號(同一空間)內不可重名 |
| 描述 | 否 | 幫助你和查詢路由理解這個庫裝的是什麼 |
| 嵌入模型 | 是 | 從管理員已啟用的嵌入模型中選擇,下拉里每項顯示模型名與維度(如 dim 1536) |
維度自動確定:向量維度由所選嵌入模型的配置決定,不需要也不能手工填寫。建立後列表卡片會顯示「N 維向量」。同維度的知識庫在 Qdrant 中共用一個 collection,靠 payload 隔離租戶。
上傳第一個文件後嵌入模型即鎖定,它決定了整個庫的向量空間。選錯了只能刪庫重建。多個知識庫如果打算在同一個對話裡同時掛載,請使用同一個嵌入模型(原因見下文排查清單第 5 條)。
普通使用者可建立的知識庫數量受使用者組限制(管理員在使用者組編輯頁的「最大知識庫數」設定,0 表示不限),見使用者與配額。
上傳文件
進入知識庫詳情頁,點「上傳文件」。上傳對話方塊有兩個標籤頁:
- 上傳檔案:點選選擇本地檔案;
- 貼上文本:直接貼上一段文字作為文件入庫,適合零散筆記。
支援的檔案型別與解析路徑
| 型別 | 解析方式 | 速度 |
|---|---|---|
| 純文本(txt / md / csv / log / json / yaml / xml / html) | 本地直接讀取,原樣作為 Markdown 進入切塊 | 毫秒級 |
| PDF(有文字層) | 本地即時提取文字層,含圖也不送 OCR | 秒級 |
| PDF(掃描件 / 無文字層) | MinerU 雲端 OCR | 分鐘級,取決於頁數 |
| DOC / DOCX / PPT / PPTX / XLS / XLSX / 圖片 | MinerU 雲端解析(含表格與公式識別) | 分鐘級 |
掃描件的判定規則:文件含圖片且文字密度低於每頁 200 字元時視作掃描件,走 MinerU OCR;否則一律本地提取,該花的 OCR 時間只花在真正需要的地方。
實際可上傳的副檔名受管理員的上傳白名單與大小上限控制(管理後臺「文件」頁),超限檔案在上傳時即被拒絕並提示具體上限。
非純文本文件解析時,原檔案先落到你自己配置的 S3 / OSS 桶,MinerU 只拿到一條 1 小時有效期的預簽名 URL,你的儲存憑據不出域;解析完成後原始檔自動從桶裡清除。
狀態流轉
上傳後文檔進入非同步流水線,詳情頁文件表格即時顯示狀態徽章:
| 狀態 | 顯示 | 含義 |
|---|---|---|
| pending | 排隊中 | 已入隊,等待處理 |
| parsing | 解析中 | 提取文本,掃描件此階段走 OCR |
| embedding | 嵌入中 | 結構化切塊後分批呼叫嵌入模型(每批最多 128 條) |
| ready | 就緒 | 已可被檢索,表格同時顯示切片數 |
| failed | 失敗 | 流水線自動重試 3 次後仍失敗,記錄失敗原因 |
文件表格列:檔案、狀態、切片數、新增時間。
失敗與重試
- 流水線內部對每個文件自動重試 3 次;重試時已解析的內容會被快取,只重跑失敗的嵌入階段,不會重複呼叫計費的 MinerU OCR。
- 3 次仍失敗則置為「失敗」並記錄原因(例如 MinerU 未配置、物件儲存不可用、嵌入模型報錯)。介面提示「索引失敗。請移除該文件後重新上傳」:排除根因後,刪除該文件並重新上傳即可重新走一遍流水線。
- 解析失敗的文件不會被向量化入庫,不會用佔位內容汙染檢索結果。
- 重複上傳同名文件或失敗後重入是冪等的,不會在庫裡疊加陳舊切片。
在對話中使用
掛載知識庫
聊天輸入框工具欄有一個書本圖示的「知識庫」選擇器:
- 點開後勾選一個或多個知識庫,掛載狀態繫結到當前對話並持久化,換對話不影響;
- 圖示旁顯示已掛載的數量;
- 窄屏(手機)上該入口收在輸入框的「+」選單裡;
- 還沒有知識庫時顯示「還沒有知識庫」。
掛載後,每條提問都會按下文的檢索流程自動查庫,不需要任何特殊指令。回答下方出現「來源」角標,點開可檢視命中的文件名、頁碼、章節路徑與原文片段。
在團隊工作空間內,只能掛載該空間的知識庫;個人空間的知識庫與工作空間互相隔離,詳見團隊工作空間。
單檔案問答(對話臨時檔案)
不建庫、直接把檔案拖進聊天輸入框也能問答:
- 上傳後附件晶片顯示「索引中…」,解析入庫完成後才能傳送;有文字層的 PDF 通常幾秒完成。
- 小文件(不超過管理員設定的全文注入閾值,預設約 8000 token)直接全文注入本輪提問,不做向量化,即使沒有配置 Qdrant 和嵌入模型也能用。
- 大文件走完整的「查詢路由 + 檢索」流程(見下節)。
- 解析失敗時晶片顯示「無法讀取此檔案」並提供「重試」按鈕。
- 已完成索引的 PDF 不會再整份內聯發給模型,避免模型端重複解析拖慢首字。
對話臨時檔案只在該對話內可檢索。如果對話在專案裡,可以把臨時檔案「加入專案知識庫」一鍵提升為專案共享文件,無需重新嵌入。
訊息裡的檢索狀態
每輪迴答的頂部會用小卡片標註本輪的文件處理方式,常見幾種:
| 提示 | 含義 |
|---|---|
| 已檢索來源 | 走了向量 + 關鍵詞混合檢索,注入了命中片段 |
| 已注入完整文件 | 文件足夠小,整篇進入上下文 |
| 全文件上下文 | 查詢路由判定為全域性類問題(總結 / 概括),按全文處理 |
| 跳過檢索 | 查詢路由判定本句與文件無關,零檢索開銷 |
| 文件解析中 | 文件還沒到就緒狀態,本輪未使用 |
工具式檢索(可選)
除了預設的自動注入,平臺還有一個 search_knowledge_base 工具:支援原生 function calling 的模型可以在一段回答裡自主發起多次、多跳檢索。文件問答的主路徑不依賴它,對不支援工具呼叫的模型同樣可用。
檢索原理
瞭解流水線有助於判斷「為什麼沒檢索到」。
入庫:解析,切塊,嵌入
上傳 → 解析(本地 / MinerU) → 結構感知切塊 → 批次嵌入 → 向量寫 Qdrant,文本與後設資料寫資料庫
切塊不是按固定字數硬切:
- 遞迴按標題、段落、句子邊界切,目標每塊 400 到 800 token,絕不從句子、表格、程式碼塊中間切斷;相鄰塊保留約 10% 到 15% 重疊。
- 每塊開頭拼上標題麵包屑(如「第3章 > 3.2 營收分析」)再嵌入,孤立的數字片段也能帶上上下文。
- 父子結構(small-to-big):用小塊建向量索引保證定位精準,命中後返回它所在的父級大段給模型,兼顧精度與上下文完整。
提問:查詢路由
掛載文件的對話裡,每條提問先經過一次廉價的任務模型呼叫(增加約 300 到 800 毫秒),同時完成兩件事:
- 意圖分類:
retrieve(問具體點,走檢索)、full_doc(總結概括類,按全文處理)、none(與文件無關,跳過); - 查詢改寫:把口語問題拆成多個精準檢索詞,並結合最近幾輪歷史消解「它 / 這個文件」之類的指代。
路由解析失敗或超時的兜底是 retrieve,寧可多檢索也不漏掉文件上下文。
檢索:稠密 + 關鍵詞混合
查詢向量化 → Qdrant 向量檢索 top-30
∥ 資料庫關鍵詞全文檢索 top-30(中文分詞)
→ RRF 融合排序 → 取 top-K → 回表取完整父級片段 → 注入上下文
- 兩路融合顯著提升專有名詞、編號類查詢("案例98"、"條款 4.2")的命中率,這是純向量檢索的弱項。
- Top-K 預設 8,管理員可改;開啟動態 Top-K 後不再取固定數量,而是把餘弦相似度達到閾值的片段全部注入。
- 相關檢索引數(全文注入閾值
rag_full_text_threshold、rag_top_k、rag_dynamic_topk、rag_similarity_threshold)在管理後臺「文件」頁調整,儲存即生效。
引用溯源
注入模型的片段帶統一編號與來源後設資料:
[1] 《2025年度報告.pdf》第12頁 · 第3章 > 3.2 營收分析
營收同比增長23%,主要來自……
模型按編號引用,前端渲染為來源角標,與聯網搜尋的引用共用同一套 UI。注入內容用明確的邊界標記包裹,並在系統提示中宣告其為參考資料而非使用者指令,降低文件內容裡的提示詞注入風險。
管理知識庫
| 操作 | 位置 | 行為 |
|---|---|---|
| 重新命名 | 詳情頁選單「重新命名」 | 僅改名,不影響文件與向量 |
| 移除單個文件 | 詳情頁文件行的刪除按鈕 | 確認後刪除該文件及其全部切片與向量 |
| 刪除知識庫 | 列表行尾部懸停「⋯」選單,或詳情頁頭部「⋯」選單 | 見下 |
刪除知識庫是級聯清理:確認彈窗明確提示「將永久刪除該庫及其全部文件與向量,引用它的對話會自動取消引用,此操作不可恢復」。具體包括:
- 庫內全部文件記錄與切片;
- Qdrant 中對應的向量;
- 磁碟上的原始檔案;
- 掛載過該庫的對話自動解除引用,對話本身不受影響。
管理員可以在管理後臺使用者列表的更多選單裡進入某使用者的資料庫頁,只讀檢視其知識庫與每個文件的狀態、切片數、大小,詳見使用者與配額。
檢索為空排查清單
掛載了知識庫但回答裡沒有任何來源、或模型說「找不到相關內容」時,按順序檢查:
- 文件狀態是否為「就緒」:知識庫詳情頁檢視狀態徽章,排隊中 / 解析中 / 嵌入中 / 失敗的文件都不參與檢索。失敗的文件點開失敗原因。
- Qdrant 是否配置:
QDRANT_URL為空時向量檢索被整體停用,只剩全文注入回退,小文件可用、大文件檢索不到。生產 Compose 預設已帶 Qdrant;自定義部署檢查該環境變數與容器狀態,見核心配置。 - 嵌入模型是否可用:知識庫繫結的嵌入模型被停用、所在渠道 key 失效或服務不可達時,新文件會卡在嵌入階段或標為失敗,查詢向量化也會失敗。到管理後臺確認該模型及其渠道狀態。
- 維度是否匹配:Qdrant collection 按維度命名(
aivory_c<維度>)。如果更換過輸出維度不同的嵌入模型而沒有同步維度配置,向量會寫進錯誤的 collection,表現為寫入正常但永遠檢索不到。修正維度後,到管理後臺「備份與遷移」的向量維護裡重建向量:系統從資料庫裡儲存的切片文本重新嵌入,不需要原始檔案,但會消耗嵌入 API 呼叫。詳見備份與遷移。 - 多庫嵌入模型是否一致:同一對話掛載多個知識庫時,系統會校驗它們的嵌入模型一致性,不一致會明確報錯而不是靜默返回錯誤結果。把不同模型的庫分開在不同對話裡用,或統一重建。
- 掃描版 PDF 是否配了 MinerU:沒有 MinerU + 物件儲存時,掃描件解析不出內容,文件會標為失敗。
以上第 2、4、6 條在常見問題裡有對應條目("為什麼知識庫檢索結果為空"、"EMBEDDING_DIM 與嵌入模型不匹配怎麼辦"、"掃描版 PDF 上傳後解析不出內容"),包含更完整的配置示例。
最快的驗證方法:傳一個幾 KB 的純文本小檔案到對話裡直接提問。小檔案走全文注入、不依賴 Qdrant 和嵌入模型,如果連它都答不對,問題在模型側而不在檢索鏈路;如果小檔案正常、大檔案不行,按上面清單查向量鏈路。