前言

本博客將介紹如何在 Windows 系統上 部署運行 KAG 項目，將使用 WSL 和 Docker 和 Vscode 幫助我們之后利用 KAG 開發個人知識庫問答項目。

KAG（Knowledge-Augmented Generation）知識增強生成系統 是一個融合知識圖譜與大語言模型能力的智能問答與內容生成平臺。該系統通過將結構化知識（如實體、關系、屬性等）與自然語言生成技術相結合，實現對復雜問題的理解與精準回答，廣泛應用于智能客服、企業知識庫、垂直領域問答助手等場景。

---

基礎環境配置

為部署 KAG 項目，需先完成：

• WSL 的部署
• Docker 的部署

WSL 安裝部署

WSL 安裝部署參考 WSL 安裝部署詳解 中的方法，寫的非常詳細，親測有效。

安裝 WSL 后，為方便我們后續的代碼開發，推薦使用 Vscode 連接 安裝的 WSL， 連接參考博客 WSL + Vscode

安裝好后，為了后續開發的環境管理，我們下載安裝 Miniconda 。參考這篇博客即可 WSL Minicona 安裝

常見問題說明

WSL 安裝完成后，可能會遇到下面的提示：

wsl: 檢測到 localhost 代理配置，但未鏡像到 WSL。NAT 模式下的 WSL 不支持 localhost 代理

如果是 Windows 11 用戶，打開 wsl settings

進入網絡欄，網絡模式選擇 修改 Nat 為 Mirrored。保存即可解決。

Docker Desktop 安裝部署

前往官網下載 Docker Desktop

安裝后需要啟用 Docker Desktop 的 WSL 集成，步驟如下：

1. 打開設置（?? 圖標）→ General

2. 確保勾選：? Use the WSL 2 based engine

3. 打開 Resources → WSL Integration

4. 看到 WSL 的發行版列表

5. ? 勾選你要使用的發行版（比如 Ubuntu-20.04）

6. 點擊 Apply & Restart

Docker 換源： 由于 KAG 的 Docker 鏡像存在阿里云的鏡像倉庫中所以需要配置鏡像源才能夠拉取，換源流程參考 博客 WSL 自定義 Docker 并換源

KAG 部署

需要提前說明，KAG 項目 與 OpenSPG 項目是二者有著緊密聯系

• OpenSPG： 螞蟻集團結合多年金融領域多元場景知識圖譜構建與應用業務經驗的總結并與OpenKG聯合推出的基于SPG框架研發的知識圖譜引擎。
• KAG： KAG（Knowledge-Augmented Generation）知識增強生成系統 是一個融合知識圖譜與大語言模型能力的智能問答與內容生成平臺。

簡單來說，KAG 是基于 OpenSPG 這一知識圖譜引擎 開發的知識增強生成系統。也就是說 KAG 是建立在 OpenSPG 上的。所以在部署 KAG 時，我們需要先 部署 OpenSPG 然后再去使用 KAG。

部署 OpenSPG

完成上述操作后，進入 WSL ，選擇一個合適的存儲位置。拉取 OpenSPG 鏡像并運行。過程大概 3-5 min 。

curl -sSL https://raw.githubusercontent.com/OpenSPG/openspg/refs/heads/master/dev/release/docker-compose.yml -o docker-compose.yml
docker compose -f docker-compose.yml up -d

拉取完成后，訪問 http://127.0.0.1:8887 即可進入 KAG 的用戶界面

初始賬密如下，登錄后需更新密碼。

Default Username: openspg
Default password: openspg@kag

登錄后如下圖所示。

后續使用時的相關配置，點擊右上角標即可自行配置。

---

KAG 使用（開發者模式）

在 官方說明文檔中，KAG 使用分為 產品模式和開發者模式，這里不對產品模式進行闡述，僅對開發者模式進行講解，原因有三：

1. 產品模式是使用 OpenSPG 的 WebUI 界面進行 知識庫，模型等的配置和使用，雖然操作簡單，但是 該項目的前后端并不完善存在許多 bug。
2. OpenSPG 的許多接口 與 WebUI 界面 的許多接口并不是一一對應的關系，拓展性差。
3. WebUI 界面的使用不易于我們去理解 KAG 與 OpenSPG的關系，及相關的運行原理等，不利于我們進行開發。

開發者模式安裝過程

拉取 KAG 的代碼庫

git clone https://github.com/OpenSPG/KAG.git

創建 conda 環境，安裝前置依賴。

# 安裝python 虛擬環境：
conda create -n kag-demo python=3.10 && conda activate kag-demo
# 進入項目根目錄即./KAG，進行KAG安裝: 
cd ./KAG && pip install -e .

驗證安裝是否成功。

# 驗證是否安裝成功
$ knext --version
$ knext --help

顯示如下所示的結果即安裝成功。

參考資料

[1] 【【KAG】1-概念講解和安裝部署】
[2] 全網最全Win10/11系統下WSL2+Ubuntu20.04的全流程安裝指南（兩種支持安裝至 D 盤方式）_win10安裝wsl2-CSDN博客
[3] (26 封私信 / 80 條消息) win11快速解決“wsl: 檢測到 localhost 代理配置，但未鏡像到 WSL。NAT 模式下的 WSL 不支持 localhost 代理” - 知乎
[4] wsl 安裝 Miniconda 和 Anaconda_wsl安裝miniconda-CSDN博客
[5] 建議立刻將 WSL + VSCode 作為你的最強生產力環境，起飛吧_wsl vscode-CSDN博客
[6] Windows子系統(WSL2)中自定義安裝docker并換源 - 悠悠明月 - 博客園