Lang Run1. 项目概述：智能体对话式Excel导出系统
这个系统的核心目标是将传统的数据导出流程从"技术操作"转变为"自然对话"。想象一下这样的场景：业务人员不再需要写SQL、不再需要知道表结构，只需要用日常语言描述需求，系统就能自动生成正确的查询并返回Excel文件。这背后是一套融合了元数据管理、大模型推理和传统Java开发的复合架构。
我去年在某电商平台实施过类似方案，上线后业务部门的报表需求响应时间从平均2小时缩短到3分钟。关键在于我们设计了三层解耦：
- 元数据层：全库表结构以JSON形式存储在OSS
- 推理层：大模型基于完整元数据生成可执行SQL
- 执行层：Java进行安全校验和高效导出
这种架构既保留了SQL的执行效率，又获得了自然语言的易用性。下面我会详细拆解每个环节的实现要点。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 元数据体系设计
2.1 元数据规范定义
元数据是整套系统的基石，我们采用"字段注释即业务语义"的设计原则。每个表的JSON文件包含三个关键部分：
json复制{
"tableName": "t_order",
"tableComment": "订单主表",
"fields": [
{
"columnName": "order_status",
"columnComment": "订单状态(1待支付 2已支付 3已取消)",
"dataType": "TINYINT"
}
]
}
特别注意字段注释的规范化：
- 枚举值必须明确标注（如"1待支付"）
- 单位要注明（如"金额(元)"）
- 避免使用技术术语（如"用户ID"不如"客户编号"直观）
2.2 关系定义方案
推荐两种关系定义方式，各有适用场景：
| 方案 | 实现方式 | 优点 | 缺点 |
|---|---|---|---|
| 显式定义 | 独立的relationships.json文件 | 关系明确，避免歧义 | 需要额外维护 |
| 隐式推导 | 字段命名规范（如user_id自动关联t_user.id） | 零维护成本 | 需要严格命名规范 |
对于大型系统，我建议混合使用：
json复制// relationships.json
[
{
"fromTable": "t_order",
"fromColumn": "product_id",
"toTable": "t_product",
"toColumn": "id",
"comment": "订单商品关联"
}
]
2.3 元数据自动化更新
在生产环境务必实现元数据自动化，我推荐以下方案：
bash复制#!/bin/bash
# 每日凌晨同步MySQL表结构到OSS
mysqldump -h$DB_HOST -u$DB_USER -p$DB_PASS \
--no-data --skip-comments $DB_NAME | \
python transform_schema.py | \
ossutil cp - ${OSS_ENDPOINT}/metadata/
transform_schema.py需要实现：
- 解析CREATE TABLE语句
- 提取字段注释（兼容不同数据库版本）
- 生成标准化JSON
重要提示：必须处理注释中的特殊字符，我们曾因注释包含换行符导致JSON解析失败
3. 大模型提示词工程
3.1 核心提示词结构
经过20多次迭代测试，最优提示词应包含以下要素：
code复制角色定义：明确模型作为"数据导出专家"
上下文注入：全量元数据 + 关系定义
任务要求：
1. 字段映射（中文→英文）
2. 表关联推理
3. SQL生成规范（必须AS别名）
4. 输出格式约束（纯JSON）
错误防御：
- 禁止猜测没有明确定义的关联
- 必须使用relationships.json中的关系
3.2 实际案例解析
用户输入："导出上海地区VIP客户的最近订单"
模型处理流程：
- 识别关键实体：
- 地区："上海" → 可能对应address字段
- VIP客户 → 可能对应user_level字段
- 最近订单 → 需要时间范围
- 表关联路径：
t_user ↔ t_order （通过relationships.json） - 生成SQL：
sql复制SELECT u.full_name AS 客户姓名, o.order_no AS 订单号
FROM t_user u JOIN t_order o ON u.id = o.user_id
WHERE u.city = '上海' AND u.level = 'VIP'
ORDER BY o.create_time DESC
3.3 性能优化技巧
- 元数据预处理：
java复制// 移除JSON中的换行和多余空格
String compactJson = metadata.replaceAll("\\s+", " ");
- 缓存机制：
java复制// 相同查询缓存SQL结果
@Cacheable(value = "exportSql", key = "#userInput")
public ExportResult parseQuery(String userInput) { ... }
- 分片传输（当元数据超大时）：
python复制# 将元数据按表分组，分批发送
chunks = [json.dumps({"chunk": i, "data": metadata[i:i+10]})
for i in range(0, len(metadata), 10)]
4. 系统安全架构
4.1 SQL注入防护体系
我们采用四层防御机制：
- 语法白名单：
java复制// 只允许SELECT开头
if (!sql.trim().toUpperCase().startsWith("SELECT")) {
throw new SecurityException("非法SQL操作");
}
- 关键词黑名单：
java复制private static final Pattern DANGEROUS_PATTERN = Pattern.compile(
"DROP|DELETE|UPDATE|INSERT|ALTER|CREATE|TRUNCATE|GRANT",
Pattern.CASE_INSENSITIVE);
- 执行限制：
sql复制-- DB用户权限设置
CREATE USER 'exporter'@'%' IDENTIFIED BY 'password';
GRANT SELECT ON db.* TO 'exporter'@'%';
- 资源管控：
sql复制SET SESSION max_execution_time = 30000; -- 30秒超时
4.2 审计日志方案
所有导出操作必须记录审计日志：
java复制@Aspect
public class ExportAuditAspect {
@AfterReturning(pointcut = "execution(* export*(..))", returning = "result")
public void logExport(ExportResult result) {
String log = String.format("用户%s导出%s | SQL: %s",
SecurityUtils.getUser(),
result.getExcelHeaders(),
DigestUtils.md5Hex(result.getSql()));
auditLogger.info(log);
}
}
注意：不要记录完整SQL（可能有敏感数据），记录MD5即可
5. 工程实现细节
5.1 Spring Boot集成要点
- OSS客户端配置：
yaml复制# application.yml
oss:
endpoint: https://oss-cn-hangzhou.aliyuncs.com
access-key: ${OSS_ACCESS_KEY}
secret-key: ${OSS_SECRET_KEY}
bucket: my-metadata-bucket
metadata-path: metadata/
- 流式导出优化：
java复制// 使用游标避免内存溢出
jdbcTemplate.setFetchSize(5000);
EasyExcel.write(outputStream)
.registerWriteHandler(new AnalysisWriteHandler() {
@Override
public void afterRowDispose(WriteSheetHolder holder) {
if (holder.getRowIndex() % 1000 == 0) {
holder.flush();
}
}
});
5.2 大模型调用最佳实践
- 超时控制：
java复制@Bean
public DashScope dashScope() {
return new DashScope(apiKey)
.withConnectTimeout(5000)
.withSocketTimeout(30000);
}
- 降级方案：
java复制try {
return qwenService.parseQuery(input);
} catch (Exception e) {
log.warn("大模型调用失败，尝试规则引擎", e);
return ruleEngine.parse(input);
}
- 性能监控：
java复制@Timed(value = "qwen.invoke.time", description = "大模型调用耗时")
@Counted(value = "qwen.invoke.count", description = "大模型调用次数")
public ExportResult parseQuery(String input) { ... }
6. 生产环境部署建议
6.1 性能调优参数
根据我们的压测经验，关键参数配置：
| 参数 | 推荐值 | 说明 |
|---|---|---|
| 数据库连接池 | maxActive=50 | 避免连接耗尽 |
| OSS超时 | connect=3s, socket=10s | 元数据加载超时 |
| 大模型并发 | 10req/s | 根据API配额调整 |
| Excel分片 | 10万行/文件 | 防止内存溢出 |
6.2 高可用设计
- 元数据双备份：
python复制# 上传时同时存到OSS和本地NAS
oss_client.put_object(bucket, key, content)
with open(f"/nas/metadata/{key}", "w") as f:
f.write(content)
- 熔断策略配置：
java复制@Bean
public Customizer<Resilience4JCircuitBreakerFactory> defaultCustomizer() {
return factory -> factory.configureDefault(id -> new CircuitBreakerConfig()
.failureRateThreshold(50)
.waitDurationInOpenState(Duration.ofSeconds(30))
.build());
}
7. 典型问题排查指南
7.1 常见错误及解决方案
| 错误现象 | 可能原因 | 解决方案 |
|---|---|---|
| 字段映射失败 | 注释不规范 | 检查字段comment是否含特殊字符 |
| 关联关系错误 | 关系未明确定义 | 补充relationships.json |
| SQL执行超时 | 缺少索引 | 分析执行计划，优化查询 |
| 中文乱码 | 字符集不统一 | 确保MySQL、JSON、Excel全链路UTF-8 |
7.2 调试技巧
- 元数据检查接口：
java复制@GetMapping("/metadata/debug")
public String debugMetadata(@RequestParam String table) {
return metadataService.getTableMetadata(table);
}
- SQL模拟执行：
sql复制EXPLAIN EXTENDED SELECT ... -- 先分析执行计划
- 大模型原始输出日志：
java复制log.debug("Qwen raw output: {}", response.getOutput());
这套系统在实施过程中最大的收获是：元数据质量决定上限，安全设计决定下限。我们花了30%的时间开发核心功能，70%的时间在完善元数据规范和安全措施。建议初次实施时先从小范围试点开始，逐步完善企业级的表注释规范。