README.zh-CN.md

SQLBox

以向量索引驱动的 AI SQL 代理

English README

• 自然语言生成安全的参数化 SQL
• 表与列向量索引，基于相似度检索构建上下文
• SSE 流式输出 delta 与内容块（SQL/数据/图表）
• 自动生成 ECharts 配置并支持数据占位符注入
• 兼容 SQLite / PostgreSQL / MySQL / SQL Server

仓库结构（关键文件）

• Program.cs
• EndpointRouteBuilderExtensions.cs
• SSEMessage.cs
• ChatService.cs
• SQLAgentClient.cs
• SQLAgentBuilder.cs
• SQLAgentOptions.cs
• web/vite.config.ts

关键入口

• EndpointRouteBuilderExtensions.MapAllApis()
• ChatService.CompletionAsync()

架构总览

系统由 .NET 8 Minimal API 后端与 React + Vite 前端组成。后端提供连接、提供商、设置、向量索引等 REST API 以及一个 SSE 聊天端点。SQL 生成通过 OpenAI Function Calling 调用 generate_sql 工具实现，产出参数化 SQL，并可返回带有数据占位符的 ECharts 配置。

flowchart LR
  UI[Web UI (React)] -->|SSE /api/chat/completion| API[.NET Hosting API]
  API -->|function calling| LLM[LLM Client]
  LLM -->|tool generate_sql| Agent[SQLAgentClient]
  Agent -->|search tables/schema| DB[Target Database]
  Agent -->|embed & retrieve| Vec[SQLite Vec Store]
  API -->|delta / block / done / error| UI

Loading

后端构件

• 入口与装配见 Program.cs
• 路由映射见 EndpointRouteBuilderExtensions.cs
• SSE 协议与类型见 SSEMessage.cs
• SQL 代理外观 SQLAgentClient.cs
• 向量存储与嵌入器接入在 Infrastructure 模块中

SSE 数据流

sequenceDiagram
  participant UI
  participant API
  participant LLM
  participant Agent
  UI->>API: POST /api/chat/completion (SSE)
  API->>LLM: messages + tool(generate_sql)
  LLM-->>API: tool_call(generate_sql) [stream]
  API->>Agent: Execute question
  Agent->>DB: 参数化查询
  Agent-->>API: sql + 可选 echarts option
  API-->>UI: delta 文本
  API-->>UI: block(sql/chart)
  API-->>UI: done

Loading

SSE 消息类型（见 SSEMessage.cs）

• delta：增量文本
• block：内容块（sql / data / chart / error）
• done：完成，包含 elapsedMs
• error：错误详情

示例 delta

{ "type": "delta", "delta": "Generating SQL..." }

示例 SQL block

{ "type": "block", "block": { "type": "sql", "sql": "SELECT ...", "tables": ["orders"], "dialect": "sqlite" } }

示例图表 block（ECharts option JSON 字符串）

{ "type": "block", "block": { "type": "chart", "chartType": "echarts", "echartsOption": "{ ... }" } }

快速开始

先决条件

• .NET 8 SDK
• Node.js 20+
• PNPM

后端

• 默认端口 18080（见 launchSettings.json）
• 运行：

dotnet run --project src/SQLAgent.Hosting/SQLAgent.Hosting.csproj

前端

• 开发端口默认 5173
• API 代理在 web/vite.config.ts，如修改后端端口，请同步更新或设置 VITE_API_BASE_URL
• 安装并启动：

cd web
pnpm install
pnpm dev

打开 http://localhost:5173，先在「提供商」与「连接」页面完成配置

配置

系统设置

• 后端通过 EndpointRouteBuilderExtensions.MapSettingsApis() 暴露 GET/PUT /api/settings；如存在 content root 下的 settings.json，会在读取时合并
• 推荐 settings.json：

{
  "EmbeddingProviderId": "openai",
  "EmbeddingModel": "text-embedding-3-small",
  "VectorDbPath": "Data Source=vectors.db",
  "VectorCollection": "table_vectors",
  "AutoCreateCollection": true,
  "VectorCacheExpireMinutes": 60,
  "DefaultChatProviderId": "openai",
  "DefaultChatModel": "gpt-4o-mini"
}

AI 提供商

• POST /api/providers 创建或更新你的 OpenAI（或兼容）配置，availableModels 使用数组

{
  "name": "OpenAI",
  "type": "OpenAI",
  "endpoint": "",
  "apiKey": "sk-...your key...",
  "availableModels": ["gpt-4o-mini", "text-embedding-3-small"],
  "defaultModel": "gpt-4o-mini",
  "isEnabled": true,
  "extraConfig": {}
}

• 获取可用模型：GET /api/providers/{id}/models

数据库连接

• POST /api/connections 注册数据库

{
  "name": "local-sqlite",
  "databaseType": "sqlite",
  "connectionString": "Data Source=app.db",
  "description": "local dev"
}

• 测试连接：POST /api/connections/{id}/test

向量索引

• 为连接初始化或更新（SQLite vec 存储）：

curl -X POST http://localhost:18080/api/connections/{id}/index/init
curl -X POST http://localhost:18080/api/connections/{id}/index/update

对话与 SSE

• 前端 SSE 客户端见 web/src/services/sse.ts
• 端点：POST /api/chat/completion（由 ChatService.CompletionAsync() 实现）
• 最小请求（与 CompletionInput 对齐）：

{
  "connectionId": "conn-id",
  "messages": [{ "role": "user", "content": "销量 Top 10 产品" }],
  "execute": true,
  "suggestChart": true,
  "providerId": "openai",
  "model": "gpt-4o-mini"
}

• 服务器将按序流式返回：
  • delta：解释/状态文本
  • block(sql)：生成的参数化 SQL
  • block(chart)：可选 ECharts 配置（JSON 字符串）
  • done：完成并附带 elapsedMs

安全与质量

• 始终参数化查询，禁止内联用户输入
• 可按需限制写操作，见 SQLAgentOptions
• 服务器端 SQL 风险校验与报告（规划中，可扩展）

支持矩阵

• 数据库：SQLite / PostgreSQL / MySQL / SQL Server
• 模型：OpenAI gpt-4o-mini（对话）、text-embedding-3-small（嵌入）

故障排查

• SSE 断流：检查反向代理缓冲并确保遵循 X-Accel-Buffering 头
• 向量检索/图表为空：先执行索引初始化并检查 EmbeddingProviderId / EmbeddingModel
• 开发文档：Development 环境下可访问 /scalar（见 Program.cs）

路线图

• 更多向量后端
• 更丰富的 schema 统计与关系图
• 可插拔的校验与自动修复策略
• 数据块（data）流式返回

贡献

欢迎提交 Issue 与 PR。请尽量附带测试并遵循现有代码风格。

许可

MIT