shopkeeper-agent
📊 電商數據倉儲智能問答 AI Agent,最適合系統學習 LangGraph 的實戰專案:基於 LangGraph、FastAPI、Qdrant、Elasticsearch、MySQL 與 React,完整實現元數據知識庫、混
shopkeeper-agent 是什麼?
📊 電商數據倉儲智能問答 AI Agent,最適合系統學習 LangGraph 的實戰專案:基於 LangGraph、FastAPI、Qdrant、Elasticsearch、MySQL 與 React,完整實現元數據知識庫、混合檢索、自然語言生成 NL2SQL 生成校驗、SQL 執行與串流查詢展示。前後端完整程式碼全棧可執行,Docker 環境一鍵部署,搭配 ai-agents-from-zero 免費教學與章節程式碼分支。適合系統學習大模型應用、數據分析 Agent 和企業級 AI 工程落地。
shopkeeper-agent 概覽
這是什麼
shopkeeper-agent 是一個開放原始碼的 AI Agent 專案,專為電商資料倉儲的自然語言查詢而設計。它被打造為最適合系統學習 LangGraph 的實戰專案,並整合了 FastAPI、Qdrant、Elasticsearch、MySQL 與 React。專案完整涵蓋從元數據知識庫建立、混合檢索,到 NL2SQL 生成、驗證、SQL 執行及前端串流顯示的完整流程。前後端程式碼完整可執行,並提供 Docker 環境一鍵部署。另附免費的系統化文字教程(ai-agents-from-zero)及對應章節的程式碼分支。
主要功能
- 混合檢索:結合 Qdrant 的語意檢索、Elasticsearch 的全文檢索,以及 MySQL 的結構化元數據,針對欄位、指標與欄位值進行協同召回。
- 多階段 LangGraph 流程:包含 SQL 生成、驗證、修正、執行,並以串流方式在前端呈現。
- 工程化後端架構:採用 FastAPI + Repository 模式 + Client Manager,實現低耦合與易維護性。
- 自動建立元數據知識庫:從教學資料倉儲中提取表格、欄位、指標定義及欄位值域,並存入 MySQL、Qdrant 與 Elasticsearch。
- 支援欄位、指標與欄位值的協同召回:在單一問數流程中同時使用三類資訊。
- 提供完整的 React + Vite + Tailwind CSS 前端,支援聊天式互動與即時流程視覺化(透過 SSE)。
- 附有免費、系統性的線上教程,可依章節逐步學習。
使用情境
- 系統學習 LangGraph,不滿足於簡單的玩具節點。
- 在單一業務場景中理解 MySQL、Qdrant、Elasticsearch 與大語言模型的整合運用。
- 建立接近真實開發的 AI Agent,實現自然語言轉 SQL(NL2SQL)。
- 開發一個可放入履歷的專案,能清楚說明資料層、檢索層、智能體層、服務層與前端層的職責。
快速開始
請參閱倉庫 README 以取得完整的快速啟動指南。以下是本地開發環境的關鍵指令:bashgit clone https://github.com/didilili/shopkeeper-agent.gitcd shopkeeper-agent# 安裝後端依賴uv sync# 設定大模型 API 金鑰cp .env.example .env# 將 Embedding 模型下載至 Docker 掛載目錄uv run hf download BAAI/bge-large-zh-v1.5 --local-dir docker/embedding/bge-large-zh-v1.5# 啟動 Docker 基礎服務docker compose -f docker/docker-compose.yaml up -d# 建立元數據知識庫uv run python -m app.scripts.build_meta_knowledge -c conf/meta_config.yaml# 啟動後端uv run fastapi dev main.py
授權與價格
本專案採用 MIT 授權條款,屬於開放原始碼。價格資訊未提供(metadata 顯示 pricing_type 為 open_source)。
內容整理自該專案公開的 README 與儲存庫資訊。