shopkeeper-agent

📊 电商数仓智能问数 AI Agent,最适合用于系统学习 LangGraph 的实战项目:基于 LangGraph、FastAPI、Qdrant、Elasticsearch、MySQL 与 React,完整实现元数据知识库、混

What is shopkeeper-agent?

📊 电商数仓智能问数 AI Agent,最适合用于系统学习 LangGraph 的实战项目:基于 LangGraph、FastAPI、Qdrant、Elasticsearch、MySQL 与 React,完整实现元数据知识库、混合检索、自然语言生成 NL2SQL 生成校验、SQL 执行与流式查询展示。前后端完整代码全栈可跑,Docker 环境一键部署,配套 ai-agents-from-zero 免费教程与章节代码分支。适合系统学习大模型应用、数据分析 Agent 和企业级 AI 工程落地。

Overview of shopkeeper-agent

What it is

shopkeeper-agent is an open-source AI Agent project designed for natural language querying of an e-commerce data warehouse. It is built to serve as a hands-on learning resource for LangGraph, FastAPI, Qdrant, Elasticsearch, MySQL, and React. The project covers the full pipeline from metadata knowledge base construction and hybrid retrieval to NL2SQL generation, validation, SQL execution, and streaming query display. The complete frontend and backend code is runnable, and a Docker environment is provided for one-click deployment. It is accompanied by a free tutorial series (ai-agents-from-zero) and chapter-specific code branches.

Key features

  • Hybrid retrieval combining semantic search (Qdrant), full-text search (Elasticsearch), and structured metadata (MySQL) for fields, metrics, and field values.
  • Multi-stage LangGraph workflow: SQL generation, validation, correction, execution, and front-end streaming display.
  • Engineering-grade backend structure using FastAPI, Repository pattern, and Client Manager for loose coupling and maintainability.
  • Automatically builds a metadata knowledge base from a teaching data warehouse, including table schemas, field definitions, metric definitions, and field value ranges.
  • Supports cooperative recall of fields, metrics, and field values in a single question-answering flow.
  • Provides a complete React + Vite + Tailwind CSS frontend for chat-style interaction and real-time process visualization via SSE.
  • Comes with a free, systematic online tutorial that walks through the entire project chapter by chapter.

Use cases

  • Systematically learning LangGraph with a real-world project beyond simple toy examples.
  • Understanding how to combine MySQL, Qdrant, Elasticsearch, and a large language model in a single business scenario.
  • Building an AI Agent for natural language to SQL (NL2SQL) in enterprise analytics.
  • Creating a portfolio-worthy project that covers data layer, retrieval layer, agent layer, service layer, and frontend layer.

Getting started

See the repository README for the full quick start guide. The following are the key commands for a local development setup:bashgit clone https://github.com/didilili/shopkeeper-agent.gitcd shopkeeper-agent# Install backend dependenciesuv sync# Configure LLM API keycp .env.example .env# Download Embedding model to Docker mount directoryuv run hf download BAAI/bge-large-zh-v1.5 --local-dir docker/embedding/bge-large-zh-v1.5# Start Docker servicesdocker compose -f docker/docker-compose.yaml up -d# Build metadata knowledge baseuv run python -m app.scripts.build_meta_knowledge -c conf/meta_config.yaml# Start the backenduv run fastapi dev main.py

License and pricing

The project is open-source under the MIT license. Pricing is not stated; the metadata indicates it is open-source (pricing_type: open_source).

Based on the project's public README and repository metadata.

Add this badge to your README

Featured on YunoDB Badge styles & help

Maintain this project? Show that it is featured on YunoDB.

Markdown[![Featured on YunoDB](https://yunodb.com/badge/didililishopkeeper-agent.svg)](https://yunodb.com/tools/didililishopkeeper-agent?utm_source=github&utm_medium=badge)
HTML<a href="https://yunodb.com/tools/didililishopkeeper-agent?utm_source=github&utm_medium=badge"><img src="https://yunodb.com/badge/didililishopkeeper-agent.svg" alt="Featured on YunoDB" height="20"></a>