智能数据分析Agent-游戏问数

立项背景和目标：游戏行业中业务同学普遍不会写 SQL，数据分析师也难以记住所有表结构、字段含义、指标用纯和字段取值，若将自然语言问题直接交给大模型生成 SQL，容易出现选错字段、用错指标和 SQL 幻觉等问题，取数慢且结果不可信。本项目目标为让用户用自然语言提问，系统自动召回相关字段、指标和取值，生成并执行 SQL 后流式返回分析结果，从而降低取数门槛、提升分析准确性。

软件功能、核心功能模块的介绍：项目分为元数据知识库构建和自然语言问数两大模块。知识库构建模块使用 MySQL 和 SQLAlchemy 保存表、字段、指标及取值等权威元数据，通过文本向量化服务生成向量存入 Qdrant 支撑字段和指标的语义召回，同时用 Elasticsearch 承载字段真实取值，支持关键词与值域检索；辅助模型自动召回与 SQL 生成，安全可靠。问数模块用 LangGraph 编排关键词抽取、字段/指标/取值混合召回、合并过滤、SQL 生成、校验修正、执行等节点，并辅以 FastAPI 接口，入参返回流式数据，保证流程可追溯、结果可解释。

业务流程、功能路径描述：用户提交问题后，系统先抽取关键词，再从语义库和全文库中并行召回相关字段、指标和取值，合并后过滤无关表与指标，随后生成 SQL，进行语法与字段校验并自动修正，最后在数据仓库中执行返回查询结果，整个过程以流式方式将节点进度和结果实时展示在前端页面。

整体架构和设计思路、不同模块使用的技术栈：整体采用"存储基座、检索召回、智能体编排、接口服务、前端展示"五层设计。存储层用 MySQL（结构化元数据与游戏数仓）、Qdrant（字段与指标向量）、Elasticsearch（字段真实取值）三类库，通过业务键关联形成权威元数据体系；检索层基于 Qdrant 做语义召回、Elasticsearch 做值域与关键词召回，数据访问统一封装在 repositories 层、由 clients 管理各类客户端连接；智能体层使用 LangGraph 构建 StateGraph，以共享状态衔接抽取、召回、过滤、生成、校验、修正、执行等阶段节点；接口层由 FastAPI 提供依赖注入与生命周期管理，SSE 流式下发进度和结果；前端用 React、Vite、Tailwind CSS 提供聊天式问数界面并展示流程。

我负责的模块和结果（尽可能量化）：负责整套 Agent 工作流的设计实现，基于 LangGraph 搭建了关键词抽取、字段召回、指标召回、取值召回、合并过滤、SQL 生成、SQL 校验、SQL 修正、查询执行等 11+ 个节点，实现一句话提问到 SQL 结果的全自动链路；负责混合检索实际落地，将 Qdrant 语义检索、Elasticsearch 全文检索、MySQL 元数据校验三类信息协同召回，明显减少针对性表选错；负责元数据知识库一库构建，将字段点从、指标、取值自动写入三种存储；同时实现 FastAPI 与 SSE 流式接口，进度与结果实时回传前端，自然语言问题可真执行并展示全流程；使用 uv 管理依赖、ruff 做静态检查、Docker Compose 一键起环境，保证项目可复现、可维护。

难点、坑和解决办法：一是模型直出 SQL 时表、字段、指标常选错，为此先建元数据知识库，通过语义检索召回候选字段、指标，再对生成 SQL 做规则校验，保证引用的表和字段真实存在；二是具体取值（如地区名、区服名）用中向量检索效果差，于是引入 Elasticsearch 关键词与值域全文检索作为补充召回，明显提升准确度；三是多阶段调用链路调用上下文复杂，易出现状态遗漏和时序问题，通过 LangGraph StateGraph 统一管理共享状态并约定节点输入输出；四是请求链路与 SSE 推送进度难对交易导致排查困难，利用 ContextVar 注入请求、维持日志映射，前端按节点实时显示执行状态。