QAnything 完整安裝教學：打造專屬本地 RAG AI 知識庫（附依賴清單與常見問題解決方案）

QAnything官網 https://qanything.ai/

概述
QAnything（意即 Question Anything）是一款強大的本地 AI 知識庫問答系統，專為需要在離線環境下進行資料查詢和文件處理的用戶設計。該系統支持多種文件格式，包括PDF、DOCX、PPTX、XLSX、MD等，並且具備跨語言問答能力，允許用戶在中文和英文之間自由切換進行查詢。QAnything 在數據隱私和高安全性環境中尤為適用，例如沒有穩定網路連接或對機密性要求極高的企業級工作場所。

為什麼選擇 qanything 作為您的 RAG 解決方案？
在當前的 AI 應用中，檢索增強生成（RAG, Retrieval-Augmented Generation）技術是解決大語言模型（LLM）「幻覺」問題的最佳方案。qanything 作為網易有道開源的傑出代表，其核心優勢在於其精準的兩階段檢索機制：

• **第一階段（Embedding 檢索）：**系統會預先將您上傳的文件分塊並向量化，當您提出問題時，qanything 會在向量資料庫中進行語意相似度計算，快速篩選出最相關的候選文本片段。
• **第二階段（Reranking 重排）：**這是 qanything 準確度領先同類產品的關鍵。系統會使用專門的重排模型（Reranker）對第一階段篩選出的候選片段進行深度語意評估與精準二次排序，只將關聯度最高、最精準的上下文提供給大語言模型進行回答生成。

這種創新的雙階段檢索架構，配合強大的 PDF Layout 解析能力（即使是複雜的表格、公式也能精準提取），使得 qanything 在中文與跨語言的語意表示評估中表現優異，能快速、安全且無失真地處理高達數百萬字的大規模本地數據。

---

在正式部署之前，請先確認您的硬體規格。qanything 的最低硬體需求如下：

處理器（CPU）：

• 支援 x86 架構的處理器（建議多核心、高主頻處理器以提升文件解析速度）。

記憶體（RAM）：

• 至少 16GB（若要同時運行大型 Embedding 模型與 LLM，建議 32GB 以上）。

顯示卡（GPU）：

• 若使用本地大模型，建議配備 NVIDIA 顯示卡，顯示記憶體（VRAM）至少 10GB（如 RTX 3060/4060 級別以上），並確保安裝了相容的 CUDA 驅動。

儲存空間：

• 至少 100GB 的可用空間（強烈建議使用 NVMe SSD），以存放模型權重和向量資料庫。

作業系統：

• 支援 Linux（Ubuntu 20.04+ 最佳）、Windows（需透過 WSL2）或 macOS（部分功能受限，建議使用 M 系列晶片）。

其他需求：

• 安裝 Docker 與 NVIDIA Container Toolkit 以支援 GPU 容器化部署。

請注意，實際需求可能因使用的模型大小（如 7B、13B 等）和資料量而有所不同。為獲得最佳 RAG 檢索性能，建議使用更高規格的硬體配置。

手把手安裝 qanything 的詳細步驟

1. 系統需求

在開始安裝之前，請確保你的系統符合以下要求：

• 作業系統：Linux 或 Windows Subsystem for Linux (WSL)
• Python 版本：3.8 或以上
• Docker：建議安裝並配置好 Docker-compose
• 必須具備網路訪問權限來下載所需的開源模型、軟體包和相依性

2. 安裝Python及pip

確保你的系統已安裝 Python 和 pip。如果尚未安裝，請使用以下指令進行安裝：

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 的依賴

安裝所需的 Python 核心庫：

pip install -r requirements.txt

如果安裝過程中出現缺少部分相依套件的錯誤，如 No module named 'cv2'，請分別安裝這些依賴。例如：

pip install opencv-python-headless

另外，根據不同的系統環境與錯誤提示，可能還需要手動安裝以下核心庫：

• transformers
• sentencepiece
• langchain
• python-dotenv

這些庫可以通過如下命令一次性安裝：

pip install transformers sentencepiece langchain python-dotenv

5. 配置 qanything 環境

在 qanything 的配置文件中，設置你需要使用的 LLM 大模型、Embedding 模型與其他參數（如 API 金鑰與模型名稱）。這通常可以在 config 文件中找到，或者您需要自己創建一個 .env 文件來安全地存儲 API 金鑰。

6. 運行 qanything 服務

配置完成後，可以使用以下命令啟動 qanything 的 CPU 或 API 服務：

bash scripts/run_for_openai_api_with_cpu_in_Linux_or_WSL.sh

如果成功啟動，終端機將會顯示一個本地伺服器的 API 地址，例如 http://0.0.0.0:8777/qanything/，您可以將此網址複製到瀏覽器中打開，即可開始體驗本地 RAG 知識庫問答。

---

常見問題與解決方法

1. 遇到 ModuleNotFoundError 錯誤

• 確保所有的相依套件都已安裝並正確配置。如果某些庫無法找到，請確認您已激活了對應的虛擬環境，並嘗試單獨 pip install 該缺失包。

2. Docker 相關權限與 GPU 掛載問題

• 如果在使用 Docker 啟動 qanything 時遇到 permission denied 錯誤，嘗試使用以下命令賦予當前用戶 Docker 權限：

  sudo usermod -aG docker $USER

此外，若要使用 GPU 加速，請務必安裝 nvidia-container-toolkit 並重啟 Docker 服務。

3. 無法訪問本地伺服器網頁

• 請確保服務已正確啟動（查看日誌無報錯），並且防火牆設置（如 ufw）允許相關埠口（例如 8777）的內部網路訪問。

---

通過這篇教學文章，你應該能夠成功安裝並配置 qanything 系統。如果遇到其他深入的技術問題，建議檢查錯誤日誌或訪問 qanything 官方 GitHub 倉庫以獲取更多社區支持與最新更新。

整理出 qanything 系統所需要依賴的完整清單：

要成功安裝和運行 qanything，你需要確保系統中安裝了一些必要的依賴項。以下是 qanything 的關鍵相依套件清單，了解這些有助於您調優 RAG 效能：

Python 基本依賴包

1. python-dotenv：管理本地環境變量。
2. nltk：自然語言處理工具包，用於文本切分（Text Splitting）。
3. opencv-python：用於處理文件中的圖像、OCR 區域定位。
4. transformers：來自 Hugging Face 的自然語言處理模型庫，載入 Embedding 模型必備。
5. langchain：RAG 架構的核心工具，用於連接 LLM 與向量檢索。
6. onnxruntime：運行 ONNX 格式的輕量化、高效深度學習模型。
7. uvicorn：快速的 ASGI 伺服器，用於運行 qanything 的後端 API。
8. aiofiles：實現非同步文件讀寫操作。
9. faiss-cpu / faiss-gpu：用於高效相似性搜索與向量檢索的底層庫。
10. pdfplumber：用於提取和處理 PDF 文件的強大解析工具。
11. PyPDF2：PDF 文件的基礎操作與合併工具。
12. markdownify：將 HTML / 網頁內容轉換為 Markdown 格式進行切分。
13. faster-whisper：高效率的語音識別工具，支援多媒體文件的 RAG 問答。
14. hanziconv：繁簡中文轉換工具，保證兩岸語意檢索不漏失。
15. datrie：實現雙陣列 Trie 結構的高效字符串檢索工具。
16. shapely：處理文件版面分析（Layout Analysis）幾何計算的庫。
17. fitz (PyMuPDF)：高效的 PDF 圖像渲染與文本提取庫。
18. pyclipper：計算多邊形布林運算，用於 OCR 文字排版識別。

其他核心相依套件

• Docker & Docker-compose：用於一鍵拉取集成環境，簡化部署難度。
• sentencepiece：LLM 與 Embedding 模型分詞（Tokenization）必備的外部依賴。

這些依賴項可能會隨着 qanything 的版本升級進行調整。確保您的 Python 環境潔淨，能大幅減少依賴衝突的機率。

如何快速完整地安裝 qanything 的所有依賴項？

要快速完整地安裝 qanything 的所有依賴項，您可以遵循以下最佳實踐。這些步驟假設您使用的是主流的 Linux（如 Ubuntu）或 macOS 系統，並且具有基礎的終端機操作知識。

1. 創建專屬虛擬環境

首先，強烈建議您在乾淨的虛擬環境中安裝所有依賴，以避免污染系統全域配置。

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

2. 升級 pip 與套件管理工具

確保 pip 是最新版本，以避免在編譯 C++ 擴充套件（如 faiss、pyclipper）時遇到安裝失敗的問題。

pip install --upgrade pip setuptools wheel

3. 批次安裝基本相依套件

您可以將 qanything 的所有 Python 依賴包寫入一個 requirements.txt 文件中，然後利用 pip 一鍵下載。

首先，在您的專案根目錄下創建 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

然後，在虛擬環境激活狀態下運行：

pip install -r requirements.txt

4. 安裝 Docker 容器環境（可選）

qanything 的部分進階功能與多模型調度預設在 Docker 容器中運行最為穩定。若您尚未安裝 Docker，可使用以下指令進行部署：

• Linux (Ubuntu):

  sudo apt-get update
  sudo apt-get install docker-ce docker-ce-cli containerd.io

• macOS:
  直接下載並安裝官方桌面版：Docker Desktop for Mac

5. 安裝 sentencepiece 分詞器

這通常是 Hugging Face transformers 模型進行 Tokenize 時不可或缺的依賴：

pip install sentencepiece

6. 測試 qanything 安裝狀態

完成所有相依套件安裝後，您可以使用以下測試命令連接 OpenAI API 或本地 API，確認 qanything 連接埠與服務是否能順暢運行：

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

7. 常見安裝故障排除

如果在執行上述步驟時遇到編譯或運行錯誤，請嘗試以下方法：

• **C++ 編譯失敗：**若安裝 pyclipper 或 faiss 報錯，請先確認系統已安裝編譯工具鏈（Ubuntu 下執行 sudo apt-get install build-essential）。
• **網路超時：**在國內或受限網路環境下，可加上鏡像源加速下載，例如：pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.tw/simple。
• **權限不足：**避免使用 sudo pip，這會破壞系統自帶的 Python 環境，請務必在剛才建立的 qanything-env 虛擬環境中操作。

透過這套完整的安裝指引，您將能夠高效率地為 qanything 構建強大、穩定的運行環境，開啟安全、私密的本地 RAG AI 知識庫體驗！

---

漫遊數位 ‧ 大腦算力注能

我持續探索，與您共享 AI 時代的實戰洞察

如果這篇文章或工具為您帶來了啟發，歡迎請我喝杯咖啡。您的支持將 100% 轉化為大阿爪的 API 算力與技術研發基金，讓我們一同在數位時代漫遊！

☕NT$100一杯咖啡 (注能 6 天)🍱NT$300一頓午餐 (注能 18 天)⚡NT$500一週能量 (注能 1 個月)💖NT$1000無限進化 (終極注能)