QAnything 本地知識庫完整架設指南：雙階段檢索 RAG 架構解析與環境依賴安裝教學

QAnything 官方網站：https://qanything.ai/

什麼是 qanything？本地 AI 知識庫問答系統概述

qanything（意即 Question Anything）是一款專為高隱私與離線環境打造的本地 AI 知識庫問答系統（RAG）。該系統支援多種非結構化與半結構化文件格式，包括 PDF、DOCX、PPTX、XLSX 與 Markdown 等，並具備優秀的中英跨語言問答能力。對於金融、法律、醫療或內部研發等對資料安全極度敏感的企業機構，qanything 提供了無需連網即可運行的私有化部署方案，從根源杜絕機密資料外洩風險。

為什麼選擇 qanything 作為企業級 RAG 解決方案？

在生成式 AI 落地應用中，檢索增強生成（RAG, Retrieval-Augmented Generation）技術是克服大語言模型（LLM）「產生幻覺」與「知識時效過期」的核心方案。由網易有道開源的 qanything，其核心優勢在於創新的兩階段檢索機制與專屬雙語模型架構：

  • 第一階段（Embedding 向量檢索）：系統將上傳的文件進行語意切分（Chunking）並向量化。當使用者提問時，qanything 會在向量資料庫中進行語意近似度計算，快速挑選出數十個候選文本區塊。
  • 第二階段（Reranking 深度重排）：這是 qanything 檢索準確度超越傳統 RAG 的關鍵技術。系統搭載專為中英雙語設計的 Reranker 重排模型，對初篩的候選片段進行交叉注意力運算，篩選出真正切題的高關聯文本，再送入 LLM 進行摘要與回答生成。

技術深度解析：BCEmbedding 與版面分析（Layout Analysis）核心優勢

許多開源 RAG 工具在處理真實企業文件時常面臨失敗，主因在於「表格解析變形」與「多語言語意失真」。qanything 之所以能具備高抗幻覺能力，關鍵在於其整合了網易有道開源的 BCEmbedding（Bilingual and Crosslingual Embedding） 雙語特化模型，以及先進的文件 Layout 解析器：

  • 跨語言語意對齊：傳統模型在「中文提問、英文技術手冊」或「台港繁體中文文件」中常出現檢索斷層。BCEmbedding 經過龐大的中英對照語料與繁簡平行語料預訓練，使 qanything 在語義表示評估中具備領先的召回率與 MRR（平均倒數排名）。
  • 精準圖表與版面識別：qanything 整合了 shapely 與 pyclipper 等幾何版面分析演算法，能辨識多欄排版、頁首頁尾濾除以及跨頁表格的結構連續性，避免將零散的表格欄位暴力切碎，顯著提升了工程圖表與財務報表的問答準確度。

部署 qanything 的最低與建議硬體規格需求

在正式部署 qanything 之前，請務必先確認您的伺服器或本機硬體規格配置：

處理器（CPU）：

  • 支援 x86 架構的處理器（建議多核心、高主頻以提升 OCR 與多格式文件的解析吞吐量）。

記憶體（RAM）：

  • 至少 16GB（若要於本地同時加載向量資料庫、Embedding 與本地 LLM，強烈建議 32GB 以上）。

顯示卡（GPU）：

  • 若使用本地離線大模型，建議配備 NVIDIA 顯示卡，顯示記憶體（VRAM）至少 10GB 以上（如 RTX 3060/4060 級別以上），並配置相對應的 CUDA 驅動與 TensorRT 加速環境。

儲存空間：

  • 至少 100GB 的可用空間（強烈建議使用 NVMe SSD），以容納大模型權重檔案與 Milvus / FAISS 向量資料庫。

作業系統：

  • 支援 Linux（Ubuntu 20.04/22.04 LTS 最佳）、Windows（需配置 WSL2）或 macOS（Apple Silicon 晶片部分支援）。

基礎環境軟體：

  • 需安裝 Docker 與 NVIDIA Container Toolkit 以支援 GPU 容器化運行。

手把手安裝 qanything 本地知識庫的詳細步驟

1. 系統需求確認

在開始安裝前，請確認系統符合以下基礎條件：

  • 作業系統：Linux（推薦）或 Windows Subsystem for Linux (WSL2)
  • Python 版本：3.8 或以上（推薦 3.10）
  • Docker：建議預先安裝並配置好 Docker 與 Docker-compose
  • 確保網路可順暢訪問 Hugging Face、ModelScope 等模型權重存放庫

2. 安裝 Python 及 pip

在 Ubuntu 系統下，執行以下指令安裝 Python 核心環境：

sudo apt-get update
sudo apt-get install python3.10 python3-pip

3. 建立獨立虛擬環境

為確保 qanything 的依賴套件不與系統其他應用衝突，建議建立獨立的 Python 虛擬環境：

python3 -m venv qanything-env
source qanything-env/bin/activate

4. 安裝 qanything 的核心依賴套件

安裝專案基本依賴庫：

pip install -r requirements.txt

若在安裝過程中出現遺漏 OpenCV 函式庫報錯（如 No module named 'cv2'），請手動安裝輕量無介面版本：

pip install opencv-python-headless

另外，依據環境需求，請透過以下指令確認基礎相依套件皆已就緒：

pip install transformers sentencepiece langchain python-dotenv

5. 配置 qanything 系統環境與 API 金鑰

在 qanything 根目錄下檢查設定檔，設定需要使用的 LLM 引擎（本地開源模型如 Qwen、Llama，或是串接外部 API 如 OpenAI、DeepSeek）。您可以在 .env 檔案中指定 API 金鑰與端點位址。

6. 啟動並運行 qanything 服務

完成參數設定後，可透過啟動腳本快速運行 qanything 服務：

bash scripts/run_for_openai_api_with_cpu_in_Linux_or_WSL.sh

伺服器啟動成功後，終端機將會印出 API 端點與 Web UI 位址，例如 http://0.0.0.0:8777/qanything/。以瀏覽器開啟該連結即可開始建立知識庫並上傳文件進行 RAG 測試。

qanything 常見安裝與運行問題排除 (FAQ)

1. 遇到 ModuleNotFoundError 錯誤

  • 請確認當前終端機是否已成功啟動虛擬環境（提示符應出現 (qanything-env)），並針對缺失的模組獨立執行 pip install [模組名稱]。

2. Docker 權限問題與 NVIDIA GPU 無法調度

  • 若出現 permission denied 報錯，請將當前使用者加入 Docker 使用者群組：
sudo usermod -aG docker $USER

若容器無法辨識顯卡，請確認宿主機已正確配置 nvidia-container-toolkit 並重新啟動 Docker 守護進程。

3. 瀏覽器無法開啟 qanything 本地管理介面

  • 請確認伺服器防火牆（如 ufw）已放行 8777 埠口，並確保監聽位址為 0.0.0.0 而非侷限於 127.0.0.1。

qanything 核心相依套件與環境依賴完整清單

深入理解 qanything 底層所使用的依賴項目，能讓系統維運與性能微調更得心應手。以下是 qanything 運行的核心套件解析：

Python 核心依賴庫

  1. python-dotenv：用於讀取 .env 環境變數設定。
  2. nltk：自然語言處理工具庫，負責文本分句與斷詞處理。
  3. opencv-python-headless：處理文件影像預處理與文字區域定位。
  4. transformers：載入 Hugging Face 格式之 Embedding 與 Reranker 模型的核心工具。
  5. langchain：構建 RAG Pipeline 與鏈式調用的骨幹模組。
  6. onnxruntime：高效率 ONNX 格式模型推論引擎，大幅加速嵌入運算。
  7. uvicorn：高效能非同步 ASGI 伺服器，負責驅動 qanything 的後端 RESTful API。
  8. aiofiles：提供非同步檔案 I/O 操作，防止大量文檔並發上傳造成阻塞。
  9. faiss-cpu / faiss-gpu：Facebook 開源的超高速高維度向量相似度檢索函式庫。
  10. pdfplumber：高精確度 PDF 文本與表格解析庫。
  11. PyPDF2：PDF 頁面萃取與基礎結構解析工具。
  12. markdownify：快速將網頁與富文本轉化為結構化的 Markdown 格式。
  13. faster-whisper：基於 CTranslate2 的高效語音轉文字模型，擴展 qanything 支援影音文檔問答能力。
  14. hanziconv：繁體與簡體中文高精度轉換工具，強化兩岸跨語境語意檢索召回率。
  15. datrie：雙陣列 Trie 樹實作，提供高速關鍵字匹配與自定義詞庫過濾。
  16. shapely：提供平面幾何形狀運算，用於版面分析中多邊形文本框的重疊計算。
  17. fitz (PyMuPDF)：極速的 PDF 文件渲染與頁面解析工具。
  18. pyclipper：文字排版輪廓擴展運算，輔助 OCR 準確鎖定排版區塊。

系統層級核心依賴

  • Docker & Docker-compose：一鍵部署整合型向量庫、快取服務與模型容器。
  • sentencepiece：支援多語言分詞（Subword Tokenization）不可或缺的編譯依賴。

如何快速完整地安裝 qanything 的所有依賴項？（實戰指令）

以下整理出最精簡流暢的終端機實戰流程，協助您一次搞定所有 qanything 環境相依：

1. 建立專屬虛擬環境

python3 -m venv qanything-env
source qanything-env/bin/activate

2. 升級基礎建構工具鏈

pip install --upgrade pip setuptools wheel

3. 批次安裝 requirements.txt 清單

在專案目錄下新增 requirements.txt，並貼入以下套件清單：

python-dotenv
nltk
opencv-python-headless
transformers
langchain
onnxruntime
uvicorn
aiofiles
faiss-cpu
pdfplumber
PyPDF2
markdownify
faster-whisper
hanziconv
datrie
shapely
fitz
pyclipper
sentencepiece

執行批次安裝：

pip install -r requirements.txt

4. 驗證 qanything 服務啟動狀態

安裝完畢後，執行 API 模組測試連通性（此處示範使用 OpenAI 兼職模型驗證後端管線）：

python3 -m qanything_kernel.qanything_server.sanic_api --host 0.0.0.0 --port 8777 --model_size 7B --use_openai_api --openai_api_base "https://api.openai.com/v1" --openai_api_key "YOUR_OPENAI_API_KEY" --openai_api_model_name "gpt-4o-mini" --openai_api_context_length 4096 --workers 4

透過本篇安裝與技術架構教學，您已掌握了 qanything 的雙階段檢索原理與環境部署方法。在企業資安要求日益嚴格的時代，qanything 是建構安全、可私有化運行之企業級本地 RAG 知識庫的絕佳選擇。

QAnything 本地知識庫介面
QAnything RAG問答測試
QAnything 部署成功畫面

蔡正信-數位教練

我是一位專精於數位轉型與AI應用的教練，致力於協助中高齡族群與企業主有效運用科技工具提升生產力。

蔡教練聯繫方式：https://rdcoach.pse.is/62uqz2

手機：0988-515-413

Line官方帳號2.0 : @rd.coach https://lin.ee/n4T9CGA
群英企業管理顧問股份有限公司
資訊顧問電子郵件：[email protected]

跨代際溝通 × AI賦能教學：
結合AI應用、數位工具教學與熟齡學習經驗，專注於中高齡與中小企業的數位轉型輔導，擅長從0到1建構數位素養。

實戰導向 × 客製培訓：
15年數位教學經驗，服務鴻海、1111人力銀行、台南大學、瓦城集團等，設計實用導向的教學模組，強調易學、可複製。

工具整合 × 工作流設計：
善用Evernote、Heptabase、Telegram等多款工具，打造AI第二大腦與一元筆記系統，協助學員從資訊收集到知識轉化。

行動導向 × 教學有感：
500+場講座與工作坊，專注學員實作與成果回報，推動「數位生活力」與「AI生活實驗室」教學風格。

預見未來 × 實踐智慧：
關注生成式AI與數位倫理發展，推動AI工具於科研、商業、教育場域的實作應用，擘劃AI助理與智慧工作未來藍圖。

Share:

More Posts

傳給蔡教練一個訊息