<div align="center">

🚀 DAT (Data Ask Tool)

用自然语言与数据对话的企业级AI工具

Dating with your data

</div>

---

🇬🇧 English Version

---

🎯 项目愿景

我们正在进入生成式人工智能的新时代，语言是界面，数据是燃料。

DAT 致力于解决企业数据查询的最后一公里问题——让业务人员能够用自然语言直接与数据库对话，无需编写复杂的 SQL 查询。通过预建模的语义层，DAT 确保 AI 不仅能自信地表达，更能正确地表达。

DAT 的核心驱动力，并非完全源于大语言模型自身的又一次智力爆炸，而是源于我们为它设计的 Askdata Agent 工作流程。 我们所做的一切，本质上都是在用 “更精准且完整的知识”（目前开发的主要重心点） 、 “更多的计算步骤” 和 “更长的思考时间” ，去交换一个在真实商业世界里至关重要的东西 —— 结果的 “高质量” 与 “确定性”。

✨ 核心特性

🏗️ 企业级架构设计

• 🔌 可插拔SPI架构 - 支持多种数据库、LLM和嵌入模型的灵活扩展
• 🏭 工厂模式实现 - 标准化的组件创建和管理机制
• 📦 模块化设计 - 清晰的职责分离，便于维护和扩展

🗃️ 多数据库支持

• MySQL - 完整支持，包含连接池和方言转换
• PostgreSQL - 企业级数据库支持
• Oracle - 传统企业数据库兼容
• 更多数据库 - 通过SPI机制轻松扩展

🤖 智能语义SQL生成

• 自然语言理解 - 基于LLM的语义解析
• SQL方言转换 - 自动适配不同数据库语法
• 语义模型绑定 - 通过预定义模型确保查询准确性

📊 丰富的语义建模

• 实体(Entities) - 主键、外键关系定义
• 维度(Dimensions) - 时间、分类、枚举维度支持
• 度量(Measures) - 聚合函数、计算字段定义
• YAML配置 - 直观的模型定义方式

🔍 向量化检索增强

• 内容存储 - SQL问答对、同义词、业务知识向量化
• 语义检索 - 基于Embedding模型的智能匹配
• 多存储后端 - DuckDB、Weaviate、PGVector等存储选择

---

🏗️ 系统架构

┌─────────────────────────────────────────────────────────────┐
│                        DAT Framework                        │
├─────────────────────────────────────────────────────────────┤
│  🎯 DAT Language (创作层)                                    │
│  ├── 📝 语义模型定义 (YAML)                                  │
│  ├── 🗃️ 数据模型配置                                         │
│  └── 🤖 智能代理配置                                         │
├─────────────────────────────────────────────────────────────┤
│  ⚙️ DAT Engine (执行层)                                      │
│  ├── 🔤 自然语言理解   │  📊 语义SQL生成    │  🗄️ 数据查询执行  │
│  ├── 🧠 LLM调用管理    │  🔍 向量检索增强   │  📈 结果格式化    │
│  └── 🔌 SPI组件管理    │  🏭 工厂模式创建   │  ⚡ 缓存优化     │
└─────────────────────────────────────────────────────────────┘

• 1、DAT CLI 用于本地开发、单元测试、调试使用，它可以在本地通过IDE（vscode、idea或eclipse中）开发dat智能问数项目，将提示（上下文）工程转变成数据工程。 正因如此，DAT Project 的开发模式天然契合 AI Coding 工具（如 Cursor、Claude Code 等），助力实现更智能、自动化的智能问数开发流程。

• 2、DAT 它不是一个 platform ，而是一个 framework；二次开发者可以基于 dat-sdk 开发自己的Web UI，可以是web ide、拖拉拽的workflow、列表等交互方式；或将其对外提供 OpenAPI 或 MCP 的服务。

• 3、这种模式让数据工程师或数据分析师可以借鉴软件工程师开发应用一般来开发智能问数应用。

---

🚀 快速开始

📋 环境要求

• Java 17+ - 推荐使用OpenJDK
• 数据库 - MySQL / PostgreSQL / Oracle / DuckDB 任选其一
• LLM API - OpenAI / Anthropic / Ollama / Gemini 等

⚡ 5分钟快速体验

1️⃣ 安装DAT CLI

🐧 Linux/macOS 系统

# 下载最新版本
wget https://github.com/hexinfo/dat/releases/latest/download/dat-cli-0.7.2-full.tar.gz

# 解压并配置环境变量
tar -xzf dat-cli-x.x.x.tar.gz
mv dat-cli-x.x.x dat-cli
export PATH=$PATH:$(pwd)/dat-cli/bin

🪟 Windows 系统

1. 访问 Releases页面
2. 下载 dat-cli-x.x.x.tar.gz 文件
3. 使用WinRAR、7-Zip或Windows内置解压工具解压
4. 将解压后的 dat-cli\bin 目录添加到系统PATH环境变量中：
   • 右键"此电脑" → "属性" → "高级系统设置"
   • 点击"环境变量" → 编辑"Path"变量
   • 添加DAT CLI的bin目录路径

2️⃣ 初始化项目

# 创建新的DAT项目
dat init

# 按提示输入项目信息
# Project name: my-dat-project
# Description: 我的第一个智能问数项目
# Database type: mysql

💡 <strong style="color: orange;">提示：</strong> 如果你没有现成的数据库可以访问，或只是想对本地 CSV 数据进行问数，初始化项目时数据库可以选择duckdb，默认会在项目的 .dat 目录下创建 'duckdb' 前缀的本地内嵌数据存储。

3️⃣ 配置数据源

编辑生成的 dat_project.yaml:

version: 1
name: my-dat-project
description: 我的第一个智能问数项目

# 数据库配置
db:
  provider: mysql
  configuration:
    url: jdbc:mysql://localhost:3306/mydb
    username: your_username
    password: your_password
    timeout: 1 min

# LLM配置
llm:
  provider: openai
  configuration:
    api-key: your-openai-api-key
    model-name: gpt-4
    base-url: https://api.openai.com/v1

# 嵌入模型配置
embedding:
  provider: bge-small-zh-v15-q

💡 <strong style="color: orange;">提示：</strong> 更多项目配置，请参考项目下的 dat_project.yaml.template 。

💡 <strong style="color: orange;">提示：</strong>

如果你没有现成的数据可以使用，你可以执行seed命令加载初始化项目中示例的种子数据入库。

# 加载种子数据
dat seed -p ./my-dat-project

然后跳过第4️⃣步，使用初始化项目中示例的语义模型，进行第5️⃣步 “开始智能问数”。

4️⃣ 创建语义模型

在 models/ 目录下创建 sales.yaml:

version: 1

semantic_models:
  - name: sales_data
    description: 销售数据分析模型
    model: ref('sales_table')
    entities:
      - name: product_id
        description: 产品ID
        type: primary
    dimensions:
      - name: sale_date
        description: 销售日期
        type: time
        type_params:
          time_granularity: day
      - name: region
        description: 销售区域
        type: categorical
        enum_values:
          - value: "North"
            label: "北区"
          - value: "South"
            label: "南区"
    measures:
      - name: sales_amount
        description: 销售金额
        agg: sum
      - name: order_count
        description: 订单数量
        agg: count

💡 <strong style="color: orange;">提示：</strong> 这只是个示例，请根据你真实的数据进行配置。 更多语义模型配置说明，请查看项目下的 MODEL_GUIDE.md 手册 。

5️⃣ 开始智能问数

# 启动交互式问数
dat run -p ./my-dat-project -a default

# 或启动API服务
dat server openapi -p ./my-dat-project

现在您可以用自然语言查询数据了！

💬 请问北区上个月的销售金额是多少？
📊 正在分析您的问题...
🔍 生成语义SQL: SELECT SUM(sales_amount) FROM sales_data WHERE region='North' AND sale_date >= '2024-11-01'
✅ 查询结果: 北区上个月销售金额为 ¥1,234,567

🌐 多种使用方式

DAT 提供了多种使用方式（CLI主要用于开发与调试），满足不同场景的需求：

1️⃣ 通过 Dify 插件使用（WEB端问答）

如果您需要通过 WEB 界面进行智能问答，无需自己开发前端，可以直接使用 Dify 平台的 DAT 插件。

🔗 插件地址: https://marketplace.dify.ai/plugins/hexinfo/dat

首先 启动DAT的OpenAPI服务，然后在 Dify 中安装 DAT 插件后配置 DAT OpenAPI Base URL 与其对接，即可在 Dify 的可视化界面中创建智能问数应用，提供友好的 WEB 交互体验。

2️⃣ 集成到自己的项目（流式问答API）

如果您需要在自己的 WEB 项目中集成流式问答功能，可以 启动DAT的OpenAPI服务 进行对接。

3️⃣ 集成到Agent中（支持MCP工具）

如果您使用的是支持 MCP (Model Context Protocol) 的 Agent（如 Claude Desktop、Cline 等），可以 启动DAT的MCP服务 将智能问数能力集成到这些 Agent 中。

---

🛠️ CLI 命令详解

📖 命令概览

🎯 核心命令

🚀 dat init - 项目初始化

dat init --help

使用示例:

# 交互式初始化DAT项目到当前工作目录下
dat init

# 交互式初始化DAT项目到指定项目工作空间目录下
dat init -w ./my-workspace

🤖 dat run - 智能问数

dat run --help

使用示例:

# 当前工作目录为DAT项目目录并启动默认代理
dat run

# 当前工作目录为DAT项目目录并启动特定代理
dat run -a sales-agent

# 指定DAT项目目录并启动特定代理
dat run -p ./my-project -a sales-agent

🌐 dat server - 服务部署

dat server --help

🔌 OpenAPI 服务

dat server openapi --help

启动服务:

# 当前工作目录为DAT项目目录
dat server openapi

# 指定DAT项目目录
dat server openapi -p ./my-project

# 自定义端口
dat server openapi --port=9090

Swagger UI界面:

API调用示例:

# 流式问答API
curl -X POST http://localhost:8080/api/v1/ask/stream \
  -H "Content-Type: application/json" \
  -d '{"question": "各个国家的病例总数"}' \
  --no-buffer

🔗 MCP 服务

dat server mcp --help

启动服务:

# 当前工作目录为DAT项目目录
dat server mcp

# 指定DAT项目目录
dat server mcp -p ./my-project

# 自定义端口
dat server mcp --port=9091