didilili/shopkeeper-agent

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

해결하는 문제

이 프로젝트는 사용자가 SQL 전문 지식 없이 자연어로 데이터베이스를 쿼리해야 하는 비즈니스 데이터 분석의 일반적인 문제를 해결합니다. 단순한 직접 LLM-to-SQL 프롬프트에 의존하지 않고 구조화된 다단계 추론 파이프라인을 구현하여 '환각' 및 잘못된 데이터 검색(예: 잘못된 테이블 또는 필드 선택) 문제를 해결합니다.

작동 방식

이 시스템은 LangGraph로 구축된 정교한 에이전트 워크플로우를 사용합니다. 먼저 MySQL, Qdrant(의미론적 벡터 검색용), Elasticsearch(키워드 기반 값 검색용)의 테이블 스키마, 메트릭 및 필드 값을 인덱싱하여 메타데이터 지식 베이스를 구축합니다. 사용자가 질문하면 에이전트는 관련 컨텍스트를 수집하기 위해 다중 경로 검색을 수행하고, SQL을 생성 및 검증하고, 쿼리를 실행하고, 결과를 React 프론트엔드로 스트리밍합니다.

대상 사용자

프로덕션 등급 AI 에이전트를 구축하는 방법을 배우고자 하는 개발자를 위해 설계되었습니다. LangGraph를 마스터하고, 여러 데이터 저장소(MySQL, Qdrant, Elasticsearch)를 단일 AI 애플리케이션에 통합하고, 데이터 준비부터 프론트엔드 전달까지 에이전트 프로젝트의 전체 수명 주기를 이해하려는 개발자에게 특히 유용합니다.

주요 특징

다단계 추론: 단순한 프롬프트 엔지니어링을 넘어 LangGraph를 사용하여 검색, SQL 생성, 검증 및 수정을 조정합니다.
하이브리드 검색: 의미론적 검색(Qdrant)과 키워드 검색(Elasticsearch)을 결합하여 자연어를 데이터베이스 스키마 및 값에 정확하게 매핑합니다.
풀스택 구현: FastAPI 백엔드, React 프론트엔드 및 Docker 기반 인프라를 포함한 완전하고 실행 가능한 코드베이스를 포함합니다.
교육 중심: 실습 학습을 위해 Git 브랜치에 직접 매핑되는 포괄적인 챕터별 튜토리얼 시리즈가 함께 제공됩니다.
엔지니어링 모범 사례: 의존성 주입, 구조화된 구성 및 추적을 위한 요청 ID 로깅과 같은 전문적인 패턴을 보여줍니다.