Semantic Insights Agent：用语义层和LangGraph实现自然语言到SQL的智能转换

一个企业级语义分析原型，通过语义层、LangGraph编排、PostgreSQL和LLM，将自然语言业务问题转换为受治理的SQL查询。

• 原作者/维护者: hmandadi
• 来源平台: GitHub
• 原项目名: semantic-insights-agent
• 项目地址: https://github.com/hmandadi/semantic-insights-agent
• 发布时间: 2026年6月4日

---

在企业数据分析领域，一个长期存在的矛盾是：业务人员需要数据洞察，但SQL查询的技术门槛让大多数人望而却步。传统的解决方案是BI工具或预定义报表，但这往往无法满足灵活多变的业务需求。

hmandadi开发的Semantic Insights Agent，试图通过AI技术弥合这一鸿沟。它不是一个简单的"文本转SQL"工具，而是一个企业级语义分析系统，强调治理、可解释性和架构的严谨性。

---

语义层（Semantic Layer）是这个项目的核心创新点。它位于原始数据库和业务用户之间，定义了：

• 业务概念：将技术性的表名、字段名映射为业务术语
• 治理规则：定义谁可以访问什么数据，如何计算指标
• 标准化指标：确保全公司使用一致的KPI定义

这种设计的价值在于，当业务人员问"上季度华东区的销售额是多少"时，系统不仅知道要查询哪个表，还知道"销售额"应该如何计算、"华东区"包含哪些省份。

---

项目的架构设计体现了清晰的分层思想：

轻量级的Web界面，让用户可以用自然语言输入问题并查看结果。这种选择体现了MVP（最小可行产品）的设计理念——在验证核心概念之前，不投入过多资源在UI开发上。

这是系统的"大脑"。LangGraph负责编排LLM驱动的推理步骤，将复杂的自然语言到SQL的转换过程分解为可管理的节点：

• 意图理解节点：解析用户的真实需求
• 语义映射节点：将业务术语映射到数据模型
• SQL生成节点：构建可执行的查询语句
• 结果验证节点：检查查询的合理性和安全性

使用OpenAI的模型进行自然语言到SQL的翻译。项目通过精心设计的提示模板（prompts.py）来引导模型生成高质量、符合企业治理要求的SQL。