配备AI助手的Apache Superset
🤖 人工智能增强型数据可视化平台 -Apache Superset与智能AI助手集成，用于自然语言数据探索和可视化。
🇰🇷 韩语文档: README_KO.md | 🇺🇸 英语：README.md
🚀 新增功能
这是Apache Superset，它增强了强大的AI助手，使您能够：
- 自然语言查询：用简单的英语询问有关数据的问题
- 智能图表生成：通过对话式人工智能创建可视化
- 实时数据探索：通过流媒体响应获得即时见解
- 多LLM支持：适用于GPT-4、Claude和其他领先的AI模型
📖 Apache Superset原始文档: 原始_超级集_README.md
🎯 主要特点
AI助手功能
- 仪表板管理：通过自然语言列出、创建和管理仪表板
- 图表创建：生成带有简单描述的图表，如“按地区显示销售额”
- 数据探索：查询数据集并获取格式化的表结果
- SQL执行：在AI协助和安全验证下运行SQL查询
- 实时流媒体：通过实时工具执行更新获得渐进式响应
技术架构
- MCP协议：用于安全AI到数据连接的模型上下文协议
- 流接口：服务器发送事件的实时响应
- 多模型支持：OpenRouter集成各种AI提供商
- 类型安全实施：带有Python类型提示的完整TypeScript前端
🏗️ 架构概述
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ React UI │ │ MCP Client │ │ MCP Server │
│ (Frontend) │◄──►│ (Streaming) │◄──►│ (Superset) │
└─────────────────┘ └──────────────────┘ └─────────────────┘
│ │ │
│ │ │
┌────▼────┐ ┌────▼────┐ ┌────▼────┐
│ AiChat │ │ FastAPI │ │ Flask │
│Component│ │ Server │ │ Backend │
└─────────┘ └─────────┘ └─────────┘🛠️ 快速开始
先决条件
- Docker和Docker Compose
- OpenRouter API密钥（用于AI功能）
1.克隆和设置
git clone https://github.com/dolphina02/supersetAddAiChat.git
cd supersetAddAiChat2.配置环境
# Copy and edit environment file
cp docker/.env.example docker/.env
# Add your OpenRouter API key
echo "OPENROUTER_API_KEY=your-api-key-here" >> docker/.env3.启动服务
# Start all services
docker-compose up -d
# Check service health
curl http://localhost:8088/health # Superset
curl http://localhost:8000/health # MCP Client4.访问应用程序
- 超级设置UI: http://localhost:8088
- AI聊天：可在顶部导航栏中找到
- 默认登录：admin/admin
🔧 详细实施
MCP服务器架构
MCP（模型上下文协议）服务器在Superset容器内运行，并为数据操作提供21多种工具：
位置: superset/mcp_service/
关键组件:
核心工具
- 仪表板工具:
list_dashboards,get_dashboard_info,generate_dashboard - 图表工具:
list_charts,get_chart_data,generate_chart,update_chart - 数据集工具:
list_datasets,get_dataset_info - SQL工具:
execute_sql,open_sql_lab_with_context - 系统工具:
get_instance_info,health_check
工具注册系统
# superset/mcp_service/server.py
@mcp_server.list_tools()
async def list_tools() -> list[Tool]:
"""Dynamically discover and register all MCP tools"""
return discover_mcp_tools()
@mcp_server.call_tool()
async def call_tool(name: str, arguments: dict) -> list[TextContent]:
"""Execute tools with proper error handling and validation"""
return await execute_mcp_tool(name, arguments)架构验证
所有工具都使用Pydantic模式进行输入/输出验证：
# Example: Chart generation schema
class GenerateChartRequest(BaseModel):
dataset_id: Union[int, str]
config: Union[XYChartConfig, TableChartConfig]
chart_name: Optional[str] = None
save_chart: bool = FalseMCP客户端架构
MCP客户端是一种基于FastAPI的流媒体服务，它将AI模型与Superset数据连接起来。
位置: docker/mcp-client/
核心组件
1.流媒体客户端(main.py)
class StreamingMCPClient:
"""Handles MCP protocol communication with real-time streaming"""
async def stream_tool_execution(self, tool_name: str, arguments: Dict) -> AsyncGenerator[StreamChunk, None]:
"""Execute MCP tools with streaming progress updates"""
def _extract_mcp_content(self, mcp_result: Any) -> Any:
"""Extract clean data from MCP protocol wrappers"""
def _truncate_large_data(self, data: Any, max_rows: int = 50) -> Any:
"""Prevent context length issues with large datasets"""2.OpenAI集成
class StreamingOpenRouterClient:
"""OpenAI-compatible client with function calling support"""
async def stream_chat_with_tools(self, messages: List[Dict], tools: List[Dict]) -> AsyncGenerator[StreamChunk, None]:
"""Stream chat responses with real-time tool execution"""数据流架构
1.请求处理
User Message → System Message + Tools → OpenAI API → Tool Calls → MCP Server → Results → Formatted Response2.流媒体实现
# Server-Sent Events format
async def generate_streaming_response():
async for chunk in openai_stream:
if chunk.type == "tool_calls":
# Execute MCP tools with progress updates
for tool_call in chunk.tool_calls:
async for progress in mcp_client.stream_tool_execution():
yield f"data: {progress.json()}\n\n"错误处理和上下文管理
上下文长度保护:
def _truncate_large_data(self, data: Any, max_rows: int = 50, max_chars: int = 50000) -> Any:
"""Intelligent data truncation to prevent OpenAI context limits"""
if isinstance(data, dict) and "data" in data:
if len(data["data"]) > max_rows:
return {
**data,
"data": data["data"][:max_rows],
"_truncated": True,
"_truncation_message": f"⚠️ Showing {max_rows} of {len(data['data'])} rows"
}强大的错误恢复:
try:
# MCP tool execution
result = await session.call_tool(request)
except Exception as e:
if "context length" in str(e).lower():
yield StreamChunk(
type="error",
error="⚠️ Dataset too large. Please use more specific filters."
)前端集成
位置: superset-frontend/src/components/AiChat/
React组件架构
// AiChat/index.tsx
export const AiChat: React.FC = () => {
const [messages, setMessages] = useState([]);
const [isStreaming, setIsStreaming] = useState(false);
const handleStreamingResponse = useCallback(async (userMessage: string) => {
const eventSource = new EventSource('/api/v1/mcp-client/chat');
eventSource.onmessage = (event) => {
const chunk = JSON.parse(event.data);
switch (chunk.type) {
case 'tool_start':
// Show tool execution progress
break;
case 'content':
// Stream AI response content
break;
case 'tool_result':
// Display formatted results
break;
}
};
}, []);
};Markdown渲染
AI响应通过完整的markdown支持呈现，包括表、代码块和列表：
import ReactMarkdown from 'react-markdown';
import remarkGfm from 'remark-gfm';
import { Prism as SyntaxHighlighter } from 'react-syntax-highlighter';
// Render AI messages with markdown
{String(children).replace(/\n$/, '')}
) : (
{children}
);
},
}}
>
{message.text}
支持的Markdown功能：
- ✅ 具有适当样式的桌子
- ✅ 带有语法高亮显示的代码块
- ✅ 内联代码格式
- ✅ 列表（有序和无序）
- ✅ 标题、区块引用、链接
- ✅ 实时流媒体渲染
表格格式化系统
客户端会自动将数据响应格式化为markdown表：
def _format_tool_result_for_display(self, tool_result: Dict) -> str:
"""Convert MCP results to user-friendly markdown tables"""
if "dashboards" in content:
table_lines = ["| 제목 | ID | 상태 | 생성일 |", "|------|----|----|--------|"]
for dash in content["dashboards"]:
title = dash.get("dashboard_title", "")[:30]
status = "공개" if dash.get("published") else "비공개"
table_lines.append(f"| {title} | {dash['id']} | {status} | {dash['created_on'][:10]} |")
return "\n".join(table_lines)🔒 安全与配置
环境变量
# AI Configuration
OPENROUTER_API_KEY=your-openrouter-key
DEFAULT_MODEL=openai/gpt-4o-mini
MCP_CLIENT_URL=http://mcp-client:8000
# Development Settings
DEBUG=true # Enable detailed logging
FLASK_DEBUG=true # Flask development mode
SUPERSET_LOG_LEVEL=info # Application log level安全功能
- 输入验证：所有MCP工具都使用Pydantic模式
- SQL注入保护：参数化查询和验证
- 速率限制：内置请求限制
- 认证：超级集RBAC集成
- 数据截断：自动处理大型数据集
🧪 开发与测试
运行测试
# MCP Server tests
pytest tests/unit_tests/mcp_service/
# MCP Client tests
cd docker/mcp-client && python -m pytest
# Frontend tests
cd superset-frontend && npm test开发工作流程
# Start development environment
docker-compose -f docker-compose.yml -f docker-compose.override.yml up -d
# Watch MCP client logs
docker logs -f superset_mcp_client
# Access development tools
curl http://localhost:8000/mcp/tools # List available tools
curl http://localhost:5008/health # MCP server health📊 使用示例
自然语言查询
"Show me all dashboards created this month"
"Create a bar chart of sales by region using the sales dataset"
"What datasets are available in the examples database?"
"Execute a query to get top 10 customers by revenue"API集成
# Direct MCP tool usage
import httpx
async def call_mcp_tool():
async with httpx.AsyncClient() as client:
response = await client.post(
"http://localhost:8000/chat",
json={
"messages": [{"role": "user", "content": "List all dashboards"}],
"model": "openai/gpt-4o-mini"
}
)🤝 贡献
该项目扩展了Apache Superset的AI功能。贡献：
- AI助手功能：专注于
docker/mcp-client/和superset/mcp_service/ - 前端集成：工作在
superset-frontend/src/components/AiChat/ - 遵循Superset指南：参见 原始_超级集_README.md
代码规范
- python：需要键入提示，符合MyPy
- TypeScript：严格打字，没有
any类型 - 测试：所有新MCP工具的单元测试
- 文档：更新此README以获取新功能
📝 许可证
此项目与原始Apache Superset保持相同的Apache许可证2.0。
🔗 链接
- 原始Apache超级集: 原始_超级集_README.md
- 安装指南: AI_ASSISTANT_SETUP.md
- MCP协议: 模型上下文协议规范
- OpenRouter: OpenRouter API文档
______________________________________________________________________
内置于❤️ 在Apache Superset之上 | AI增强数据可视化