# lian_ask_data

**Repository Path**: ppcirgo/lian_ask_data

## Basic Information

- **Project Name**: lian_ask_data
- **Description**: 一款现代化的智能问数应用。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-08
- **Last Updated**: 2026-09-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Harness, DataAgent

## README



# 问数 (Lian Ask Data)

## 项目简介

问数是一个基于 AI Agent 的智能数据查询系统，旨在通过自然语言处理技术，帮助用户以自然语言的方式完成数据查询与分析。该系统采用 Multi-Agent 架构，整合了意图识别、查询规划、指标计算、明细查询等多个子代理，实现了从用户问题到可执行 SQL 的完整闭环。

## 核心特性

- **自然语言查询**：用户可以使用日常语言描述数据需求，系统自动转换为结构化查询
- **Multi-Agent 协作**：采用 ReAct 模式，由多个专业化子 Agent 协同完成复杂查询任务
- **指标与明细双引擎**：支持指标查询（聚合统计）和明细查询（详细数据）两种模式
- **多 SQL 方言支持**：内置 MySQL、PostgreSQL、DuckDB 等多种 SQL 方言渲染器
- **确定性编译**：查询编译过程具有确定性，便于测试和验证
- **完善的质检机制**：内置查询质量检查，确保输出 SQL 的正确性

## 技术栈

- **模型运行时**：阿里云 Qwen 3.6 27B
- **开发语言**：Java
- **构建工具**：Maven
- **AI 框架**：AgentScope 2.x https://java.agentscope.io/v2/zh/docs/index.html#
- **SQL 渲染**：支持 MySQL、PostgreSQL、DuckDB

## 模块说明

### ask_data_common

公共模块，提供核心数据结构和协议定义：

- **Condition 接口体系**：支持 AndCondition、OrCondition、NotCondition、LeafCondition 四种条件类型，实现结构化 WHERE 子句的灵活组合
- **LianQL**：统一的查询 DSL，包含指标、过滤条件、排序、时间范围等定义
- **CompileResult**：编译结果封装，包含 SQL、错误码、错误信息等
- **Agent 协议**：定义意图决策（IntentDecision）、DAG 计划（DagPlan）、问题状态（QuestionState）等代理交互协议

### ask_data_harness

编排引擎，负责多代理的调度与协作：

- **AskOrchestrator**：核心编排器，协调各子代理工作流，处理重试和修订逻辑
- **子代理接口**：
  - IntentClassifier（意图识别）：判断用户查询类型（指标/明细/澄清）
  - Planner（查询规划）：生成查询执行计划（DAG 结构）
  - MetricAnswerer（指标回答）：处理聚合统计类查询
  - DetailAnswerer（明细回答）：处理详细数据查询
  - QualityChecker（质检）：验证查询结果的正确性
- **运行时**：DashScopeQwenModel，基于阿里云 DashScope 的 Qwen 模型集成
- **本体库**：InMemoryOntologyDirectory，管理实体、字段、指标的元信息

### ask_detail_engine

明细查询引擎，负责将 DetailSpec 编译为可执行 SQL：

- **DetailCompiler**：核心编译器，实现查询逻辑到 SQL 的转换
- **JoinPlanner**：自动规划多表关联路径，支持深度控制的 JOIN 编译
- **ConditionRenderer**：条件表达式渲染器，支持多层嵌套的条件树
- **DialectRenderers**：SQL 方言渲染器，支持 MySQL、PostgreSQL、DuckDB
- **语义存储**：DetailSemanticStore，管理表结构、外键关系等元数据

### ask_data_web

Web 前端界面，提供可视化的查询交互界面。

## 快速开始

### 环境要求

- JDK 17+
- Maven 3.6+
- 阿里云 DashScope API Key（用于调用 Qwen 模型）

### 构建项目

```bash
# 克隆项目
git clone https://gitee.com/ppcirgo/lian_ask_data.git
cd lian_ask_data

# 构建所有模块
mvn clean install -DskipTests

# 运行测试
mvn test
```

### 配置说明

项目根目录提供 `llm-config.example.yml` 配置文件模板，配置模型调用参数：

```yaml
llm:
  provider: DASH_SCOPE
  modelId: qwen-turbo
  baseUrl: https://dashscope.aliyuncs.com/compatible-mode/v1
  apiKey: ${DASHSCOPE_API_KEY}
```

### 示例代码

```java
// 初始化本体库
OntologyDirectory directory = InMemoryOntologyDirectory.sampleDomain();

// 初始化各组件
IntentClassifier intentClassifier = new ReActIntentClassifier(model);
Planner planner = new ReActPlanner(model);
DetailAnswerer detailAnswerer = new RuleDetailAnswerer(compiler);
MetricAnswerer metricAnswerer = new StubMetricAnswerer();
QualityChecker qualityChecker = new SimpleQualityChecker();

// 创建编排器
AskOrchestrator orchestrator = new AskOrchestrator(
    intentClassifier, planner, 
    metricAnswerer, detailAnswerer, 
    qualityChecker
);

// 执行查询
QuestionState state = QuestionState.of("查询近30天的订单总数");
AskOutcome outcome = orchestrator.ask(state);

if (outcome instanceof AskOutcome.Compiled compiled) {
    System.out.println("生成的 SQL: " + compiled.result().getSql());
}
```

## 查询语法

### LianQL 结构

```java
LianQL lianQL = new LianQL();
lianQL.setMetric(List.of("order_count", "total_amount"));
lianQL.setWhere("status = 'COMPLETED'");
lianQL.setStartTime("2024-01-01");
lianQL.setEndTime("2024-01-31");
lianQL.setLimit(100);
```

### Condition 结构

```java
// 单条件
LeafCondition condition = new LeafCondition("status", Operator.EQ, "COMPLETED");

// 复合条件
AndCondition andCondition = new AndCondition(List.of(
    new LeafCondition("amount", Operator.GT, 100),
    new LeafCondition("status", Operator.EQ, "PENDING")
));
```

## 测试策略

项目采用确定性测试策略，确保编译结果的稳定性和一致性：

- **单元测试**：覆盖各模块的核心功能
- **集成测试**：验证多代理协作流程
- **编译确定性测试**：确保相同输入产生相同输出

## 扩展指南

### 添加新的 SQL 方言

1. 实现 `SqlDialectRenderer` 接口
2. 在 `DialectRenderers` 中注册新方言
3. 添加对应的测试用例

### 新增查询类型

1. 在 `QueryType` 枚举中添加新类型
2. 实现对应的 Answerer 接口
3. 在 Planner 中添加规划逻辑

## 许可证

本项目遵循 [LICENSE](LICENSE) 文件中规定的许可协议。

## 贡献指南

欢迎提交 Issue 和 Pull Request。在提交代码前，请确保：

1. 遵循项目代码规范
2. 添加充分的测试用例
3. 更新相关文档

## 后续规划

- 支持更多数据源（ElasticSearch、MongoDB 等）
- 优化查询性能，支持查询缓存
- 增强质检能力，支持更多规则
- 提供可视化查询计划展示