Coomia DataGPT技术实现详解

🚀 项目概述

每个数据驱动团队都面临相同的挑战：拥有存储在PostgreSQL、MySQL、Trino或Doris中的丰富数据，但将这些数据转化为洞察仍需要SQL专业知识、仪表板和手动查询调整。我们构建了Coomia DataGPT来改变这一现状。

这是一个自托管的AI助手，可直接连接到您的数据库，理解纯英语问题，自动编写SQL并即时可视化结果。本文将分享其内部工作原理、背后的技术栈以及构建过程中学到的经验。

🧩 系统架构概览

从高层次看，Coomia DataGPT包含三个主要组件：

1
2
3
4
5
6
7
8
9


+------------------+      +---------------------+      +-------------------+
|  前端(React)     | ---> |  FastAPI后端        | ---> |  数据库引擎       |
|  聊天界面        |      |  查询+AI引擎        |      | (PostgreSQL等)    |
+------------------+      +---------------------+      +-------------------+
                                |
                                v
                        +------------------+
                        |  可视化界面      |
                        +------------------+

前端 - 使用React + TypeScript构建，提供类似聊天的界面，用户可以用自然语言提问
后端(FastAPI) - 处理用户请求，与LLM交互并管理SQL执行
数据库层 - 使用SQLAlchemy适配器连接PostgreSQL、MySQL、Trino和Doris
可视化 - 使用自动生成的Vega-Lite规范和轻量级图表渲染器实现即时图表

🧠 工作原理

自然语言理解

当用户提问类似"哪些电影类别产生了最高的总收入？“时，Coomia DataGPT将提示发送到LLM（OpenAI或配置的本地模型）。LLM将请求转换为结构化意图，包括：

SQL表及涉及字段
过滤器和聚合条件
输出类型（图表、表格、指标）

SQL生成

AI模块基于模式自省动态生成SQL代码：

1
2
3
4
5
6
7
8
9


SELECT c.name AS category,
       SUM(p.amount) AS total_revenue
FROM category c
JOIN film_category fc ON fc.category_id = c.category_id
JOIN inventory i ON i.film_id = fc.film_id
JOIN rental r ON r.inventory_id = i.inventory_id
JOIN payment p ON p.rental_id = r.rental_id
GROUP BY c.name
ORDER BY total_revenue DESC;

执行与可视化

SQL通过SQLAlchemy或直接驱动程序（Trino客户端、Doris连接器）异步执行。结果转换为统一数据框架，并通过自动图表推断进行可视化：

数值+分类 → 条形图
时间戳+数值 → 折线图
聚合数据 → 饼图或摘要卡片

图表使用React + Plotly在前端即时渲染。

🧰 技术栈

层级	技术	用途
前端	React, TypeScript, TailwindCSS	现代响应式UI
后端	FastAPI, Python	异步API + 编排
AI引擎	OpenAI API / 本地LLM(通过Agno)	NL→SQL翻译
数据库集成	SQLAlchemy, Trino-Python, Doris客户端	多数据库连接
可视化	Vega-Lite, Plotly	自动生成图表
缓存	Redis	查询和嵌入缓存
部署	Docker + Docker Compose	简易自托管
日志	Loguru	结构化日志记录
身份验证	JWT / OAuth2	安全的API访问

🔒 为何选择自托管？

大多数AI分析工具需要将数据发送到外部服务器。我们想要的是私密、安全且可控的方案。因此Coomia DataGPT完全在您的基础设施内运行，无需第三方存储，除非您选择使用OpenAI，否则没有外部API调用。这对于有严格数据治理需求的组织来说是理想选择。

🧠 解决的技术挑战

跨不同SQL方言的模式适配
确保SQL生成保持安全（无破坏性查询）
管理LLM与模式元数据之间的上下文
通过缓存和异步数据库执行减少延迟

🧭 技术路线图

自动化数据治理 - 内置数据质量检查、谱系跟踪和模式演进监控，保持分析可信且合规
更多数据源集成 - 扩展到PostgreSQL、MySQL、Trino和Doris之外，包括ClickHouse、DuckDB、BigQuery和Snowflake
高级可视化库 - 支持多维图表、相关图、交互式仪表板和AI生成的数据故事
多用户协作 - 共享工作空间、团队权限和保存的查询历史
领域特定AI模型 - 针对金融、电子商务和SaaS分析的微调LLM

💬 实践指南

快速开始

从GitHub克隆最新版本：

1

git clone https://github.com/coomia-ai/datagpt.git

运行前请确保已准备好：

拥有通义千问或ChatGPT账号用于大模型调用
已配置PostgreSQL、数据源和大模型
已准备好用于导入的许可证文件license.json

配置说明

将.env.example复制为.env并根据环境修改参数：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


###########################################################
#                     数据库配置                           #
###########################################################
# DataGPT的主要元数据数据库
DB_DRIVER=postgresql
DB_HOST=postgres
DB_USER=postgres
DB_PASS=postgresql123
DB_PORT=5432
DB_NAME=datagpt

###########################################################
#                     LLM大模型配置                        #
###########################################################
# 支持的LLM提供商：
#   openai     → OpenAIChat
#   claude     → Claude / Anthropic
#   deepseek   → DeepSeek
#   qwen       → DashScope(阿里)
#   kimi       → Kimi
#   doubao     → Doubao(字节)

MODEL_PROVIDER=qwen
MODEL_ID=qwen-flash-2025-07-28
MODEL_API_KEY=your_api_key_here

运行DataGPT

使用Docker Compose启动系统：

1

docker-compose up -d

访问系统：

Web界面 → http://localhost:3000
API接口 → http://localhost:8000

系统配置推荐

数据量	CPU	内存	用途
<1百万行	2核	8GB	开发测试
1–1亿行	4-8核	16-32GB	生产环境
>1亿行	8+核	64+GB	分布式模式

✨ 总结

Coomia DataGPT是我们让人机数据交互更加人性化的尝试，让任何人无论技术技能如何，都能通过提问探索数据。虽然仍在早期阶段，但它已经帮助团队更快地行动、保持隐私并更智能地工作。

您的AI数据助手 - 私密、快速、智能。

揭秘Coomia DataGPT：自托管AI数据分析助手的技术架构与实现

本文详细介绍Coomia DataGPT的技术实现，这是一个自托管的AI数据分析助手，可将自然语言问题自动转换为SQL查询并可视化结果，支持PostgreSQL、MySQL等多种数据库，采用React、FastAPI等技术栈构建。