Local GraphRAG | llama.cpp: 使用地端 LLM

Local GraphRAG | llama.cpp: 使用地端 LLM

在現今的企業應用中，GraphRAG 已成為許多 LLM 應用中的重要功能。然而，Microsoft 的 GraphRAG 需要付費，且必須將資料上傳至商業 LLM 平台，這對於一些企業而言可能並不理想。因此，如何利用自有的 LLM 模型來建立 Microsoft GraphRAG，成為越來越多人關注的解決方案。

Microsoft GraphRAG 主要是設計給使用者選擇 OpenAI 或 Azure OpenAI 的 LLM 來執行，若你對此技術還不熟悉，可以先參考我先前的 教學文章 了解基礎概念。如今，有不少開發者在 GitHub 上提供了開源的 Local GraphRAG 方法，讓大家能夠透過地端的 LLM 來實現相似的效果。以下是兩個值得參考的 repo：

• GraphRAG-Local-UI ：提供了使用者友好的圖形介面（UI），方便操作。
• graphrag-local-ollama ：較早期的教學資源，指導如何在地端 LLM 上進行 GraphRAG 的應用。

上述兩個 repo 都依賴於一個名為 ollama 的工具來創建與 OpenAI API 相容的接口。ollama 的底層架構是基於 llama.cpp，並進行了一些調整，最終提供了一個較為便捷的操作介面。簡單來說，ollama 使用 Go 語言包裹了 llama.cpp，讓使用者可以輕鬆安裝和管理模型。

然而，由於 ollama 進行了特定調整，其所建立的伺服器無法直接用於 Microsoft GraphRAG，還需要修改 GraphRAG 的部分原始碼才能運行。

因此，若希望更直接地在地端啟動 OpenAI API 相容伺服器，建議直接使用 llama.cpp，使用 llama.cpp 不僅簡單直觀，也避免了不必要的中間層，大幅提升靈活性和控制性，同時也能更清晰地了解如何使用地端 LLM 來取代 OpenAI 或 Azure OpenAI 的 LLM，並無縫地整合到 Microsoft GraphRAG。

這篇文章便是希望帶大家一起操作，如何在 Microsoft GraphRAG 中使用llama.cpp 架設的地端 LLM 伺服器，主要會分成兩步驟：

A. 啟動 llama.cpp 伺服器 B. Microsoft GraphRAG

A. 啟動 llama.cpp 伺服器

這步驟需要啟動 2 個伺服器，一個用於 completion，另一個用於 embedding，架設伺服器的細節可以參考我之前的 文章 ，這邊帶大家快速操作。

A-1. clone llama.cpp 專案

把 llama.cpp 的 repo clone 下來

git clone https://github.com/ggerganov/llama.cpp.git

A-2. 使用 Makefile 進行編譯

使用 make 對 llama.cpp 專案進行編譯，如果你有 GPU 要使用，需看 llama.cpp文件 找到符合你環境的指令。

我這邊是使用 CUDA，因此加上 GGML_CUDA=1 。

make GGML_CUDA=1 # 看你的環境為何

A-3. 準備環境

建議使用 conda 來管理

conda create --name llamaCpp python=3.9
conda activate llamaCpp
python3 -m pip install -r requirements.txt

A-4. 轉檔與量化模型

Hugging Face 上可以下載到很多轉檔或量化後的 GGUF 模型，建議大家可以直接下載操作，我將下載後的模型放在 ./models/ 中。

需要更多細節的朋友可以參考之前的 文章 。

A-5. 啟動 Completion API Server

執行以下指令在 8080 port 開啟 Completion API Server，你可以在 http://127.0.0.1:8080 看到啟動的 Server。

./llama-server --host 0.0.0.0 --port 8080 \
  --threads 8 \
  --parallel 1 \
  --gpu-layers 999 \
  --ctx-size 0 \
  --n-predict -1 \
  --defrag-thold 1 \
  --model ./models/qwen2-7b-instruct-fp16.gguf

A-6. 啟動 Embeddings API Server

接著執行以下指令在 8081 port 開啟 Embeddings API Server，你可以找你喜歡的 Embeddings 模型，不過記得 llama.cpp 的 GitHub 看下現在支援的項目， 如最近很紅的 jina-embeddings-v3，llama.cpp 便還沒支援。

./llama-server --host 0.0.0.0 --port 8081 \
  --threads 8 \
  --parallel 1 \
  --gpu-layers 999 \
  --ctx-size 0 \
  --n-predict -1 \
  --defrag-thold 1 \
  --embeddings \
  --pooling mean \
  --batch-size 8192 \
  --ubatch-size 4096 \
  --model ./models/qwen2-7b-instruct-fp16.gguf

如此便架設好 2 個 API server，啟動時需花點時間，確定完成後便可繼續下面的步驟。

B. Microsoft GraphRAG

啟動好伺服器後，我們接著要來使用 Microsoft GraphRAG，對 Microsoft GraphRAG 不熟或想看更多細節可以參考我之前的 文章 ，這邊一樣帶大家快速操作。

B-1. 環境設置

版本要求是 Python 3.10 到 3.12，我使用 conda 建立環境。

conda create -n GraphRAG python=3.10
conda activate GraphRAG
pip install graphrag

B-2. 準備資料夾與文件

我們將官方的參考文件下載下來。

mkdir -p ./ragtest/input
curl https://www.gutenberg.org/cache/epub/24022/pg24022.txt > ./ragtest/input/book.txt

B-3. Workspace 初始化設置

python -m graphrag.index --init --root ./ragtest

B-4. 修改 settings.yaml

接著修改 ./ragtest/settings.yaml，將前面 llama.cpp 啟動的 Completion API Server 與 Embeddings API Server 的 API 路徑輸入在這邊，用以取代 OpenAI API。

llm:
  api_key: ${GRAPHRAG_API_KEY}
  type: openai_chat # or azure_openai_chat
  model: qwen2-7b-instruct
  model_supports_json: true # recommended if this is available for your model.
  max_tokens: 512
  # request_timeout: 180.0
  api_base: http://localhost:8080
  api_version: v1

embeddings:
  ## parallelization: override the global parallelization settings for embeddings
  async_mode: threaded # or asyncio
  llm:
    api_key: ${GRAPHRAG_API_KEY}
    type: openai_embedding # or azure_openai_embedding
    model: qwen2-7b-instruct
    api_base: http://localhost:8081
    api_version: v1

B-5. 執行 Indexing pipeline

修好完後就可以執行以下指令，開始進行 Indexing pipeline。

python -m graphrag.index --root ./ragtest

大約會跑 1 小時左右，主要看你的 input.txt 大小與電腦速度，這步驟可能會遇到問題，我蒐集了一些我遇到以及常見的問題放在下面，如果你也遇到可以試試看。

都順利運行完成後，會看到：🚀 ALL workflows completed successfully

B-6. 進行問答

使用 Global Search 的方式提出進階問題的範例，其他方式請參考 官方文件 。：

python -m graphrag.query \
--root ./ragtest \
--method global \
"What are the top themes in this story?"

常見問題：

1. ❌create_base_entity_graph

最常見的問題，大多可透過修改 ./ragtest/settings.yaml 中的 llm 的 max_tokens 與 chunks 的 size 和 overlap 解決。

有時候模型壓縮太多，會影響到模型跟隨指令的能力，也會出現這個問題，這時可以換別的模型再測試。

細節參考：Github Issue437 、 Issue951

llm:
  max_tokens: 512

chunks:
  size: 600
  overlap: 150

2. ValueError(“Columns must be same length as key”)

如果查看 logs 中的有這個問題，一樣也是可以透過修改 chunks 來修正

chunks:
  size: 600
  overlap: 150

細節參考：Github Issue362

3. ❌create_final_community_reports

這這步驟需要 Context window 比較長的 LLM，因此若你是使用 llama3.1 ，會無法完成這步驟，因為 llama3.1 的 context window 只有 8k。

細節參考：Github Issue374

Follow me on Medium

---