Text2SQL 智能体项目

基于 CrewAI 框架构建的自然语言转 SQL 查询系统，专门针对 ClickHouse 数据库优化，支持复杂业务场景的智能查询生成。

🚀 项目特色

• 多智能体协作：采用 CrewAI 框架，通过多个专业智能体协同工作
• ClickHouse 优化：专门针对 ClickHouse 数据库进行优化，支持复杂查询
• 丰富知识库：内置完整的数据库 Schema 和业务规则知识库
• 智能记忆：使用 BGE-M3 嵌入模型实现智能记忆功能
• 多种运行模式：支持交互式、批量处理等多种使用方式

🏗️ 系统架构

智能体团队

1. SQL 分析师 (sql_analyst)

   • 负责理解和分析自然语言查询
   • 提取查询意图和业务需求
   • 识别相关的数据实体和关系

2. ClickHouse 专家 (clickhouse_expert)

   • 生成优化的 ClickHouse SQL 查询
   • 具备完整的数据库 Schema 知识
   • 支持跨数据库查询和复杂业务逻辑

3. 质量检查员 (quality_checker)

   • 验证 SQL 查询的正确性和性能
   • 确保查询符合最佳实践
   • 提供优化建议

4. 结果解释器 (result_interpreter)

   • 执行 SQL 查询并获取结果
   • 解释查询结果的业务含义
   • 提供数据洞察和建议

核心工具

• ClickHouseTool: ClickHouse 数据库连接和查询执行工具
• KnowledgeTool: 知识库读取工具，支持 Schema 查询和业务规则检索

📊 knowledge知识库

• 项目的知识库文件，位于 knowledge/ 目录：
• 支持.md、.txt、.sql等文本
• 期望包含数据库Schema、业务规则、查询示例等

🛠️ 安装和配置

环境要求

• Python 3.13
• ClickHouse 数据库访问权限

安装依赖

# 使用 uv 安装（推荐）
uv sync

# 或使用 pip 安装
pip install -e .

环境变量配置

创建 .env 文件并配置以下环境变量：

# ModelScope API 配置
MODELSCOPE_MODEL=openai/Qwen/Qwen3-Coder-480B-A35B-Instruct
MODELSCOPE_BASE_URL=https://api-inference.modelscope.cn/v1
MODELSCOPE_API_KEY=your_api_key_here

# 数据库环境
ENVIRONMENT=clickhouse

数据库配置

在 src/text2sql/config/database.yaml 中配置 ClickHouse 连接信息：

clickhouse:
  host: your_clickhouse_host
  port: 9000
  username: your_username
  password: your_password
  database: your_database

🎯 使用方法

1. 交互式模式

python src/text2sql/main.py --interactive

进入交互式模式，可以持续输入查询并获得结果。

2. 直接查询模式

python src/text2sql/main.py "显示最近30天订单金额前10的用户"

直接执行单个查询。

3. 查看示例

python src/text2sql/main.py --examples

查看预设的查询示例。

4. 快速测试

python src/text2sql/main.py --quick-test

使用示例查询进行快速测试。

🔧 项目结构

text2sql/
├── src/text2sql/
│   ├── main.py              # 主程序入口
│   ├── crew.py              # CrewAI 智能体团队配置
│   ├── config/              # 配置文件
│   │   ├── agents.yaml      # 智能体配置
│   │   ├── tasks.yaml       # 任务配置
│   │   └── database.yaml    # 数据库配置
│   ├── tools/               # 工具模块
│   │   ├── clickhouse_tool.py  # ClickHouse 工具
│   │   └── knowledge_tool.py   # 知识库工具
│   └── memory/              # 记忆配置
├── knowledge/               # 知识库文件
├── logs/                    # 日志文件
├── data/                    # 数据文件
└── docs/                    # 文档

🎨 示例查询

系统支持各种复杂的业务查询，例如：

• "显示最近30天订单金额前10的用户"
• "统计本月各个订单状态的数量分布"
• "查询逾期超过30天的订单信息"
• "分析最近一周的审批通过率趋势"
• "显示风险等级为高的客户列表"

📈 性能优化

• 自动添加 LIMIT 子句避免大结果集
• 智能选择索引和分区键
• 支持查询缓存和结果复用
• 内置查询性能监控

🔍 日志和监控

• 所有执行日志都会记录到日志文件 logs/text2sql_crew_log_{timestamp}.log.txt
• 所有agent的查询数据都会记录到 data/query_result_{timestamp}.excel
• 支持详细的执行过程跟踪

---

扩展建议

• 目前只支持clickhouse数据库，但是可以自行对tools/clickhouse_tool.py进行扩展或者替代
• agents和tasks的prompt可以在config/agents.yaml和config/tasks.yaml中进行配置，prompt对最终效果有非常大的影响，建议多进行调试
• 知识库文件可以在knowledge/目录中添加，支持.md、.txt、.sql等文本文件，也可以在prompt中进行强调，比如
  • 可以在prompt中添加知识库文件：knowledge/，这样agent就会自动读取knowledge/目录下的所有文件
  • 可以在prompt中添加知识库文件：knowledge/aaa.md，这样agent就会自动读取knowledge/aaa.md文件

---

🤝 贡献指南

1. Fork 项目
2. 创建特性分支
3. 提交更改
4. 推送到分支
5. 创建 Pull Request

🆘 支持

如有问题或建议，请创建 Issue 或联系项目维护者。