# travel-data

**Repository Path**: sssugar0310/travel-data

## Basic Information

- **Project Name**: travel-data
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-27
- **Last Updated**: 2026-06-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Travel Data — NL2SQL 智能查询系统

基于 LangGraph + RAG 架构的 NL2SQL 系统，面向旅游票务数据库，让业务人员用自然语言查询数据。

## 架构

```
用户提问
  → n01 jieba 提取关键词
  → n02 LLM 扩展关键词
  ┌── Qdrant 字段召回 ──┐
  ├── Qdrant 指标召回 ──┤  (三路并行)
  └── ES 维度值召回 ────┘
  → n06 合并召回结果（表+字段+指标+维度值）
  → n07/n08 LLM 过滤表 + 过滤指标（并行）
  → n09 补充上下文（字段详情+数据库版本+表关联）
  → n10 LLM 生成 SQL
  → n11 语法校验 → 失败 → n12 LLM 修正（最多2次）→ n11 再校验
  → n13 执行 SQL → 返回结果
```

## 技术栈

| 组件 | 技术 |
|---|---|
| 应用框架 | FastAPI + SQLAlchemy Async |
| 流程编排 | LangGraph（有向图+并行+条件分支） |
| 向量库 | Qdrant（字段/指标语义索引） |
| 全文索引 | Elasticsearch（维度值索引） |
| 大模型 | DeepSeek Chat（SQL生成+关键词扩展+过滤+修正） |
| 分词 | jieba TF-IDF |
| Embedding | BAAI/bge-large-zh-v1.5（TEI部署，1024维） |
| 元数据库 | MySQL（table_info, column_info, metric_info, column_metric）|
| 业务库 | MySQL（travel数仓，43张表，6个业务域） |

## 业务数据库（travel，43张表）

交易域：orders, order_items, payments, refund_requests, refund_records, order_coupon_usages, order_promotion_details, order_point_usages
酒店域：hotels, hotel_room_types, hotel_booking_rules, hotel_room_daily
景点域：scenic_spots, scenic_ticket_types, scenic_booking_rules, scenic_ticket_daily
交通域：flight_routes, flight_departures, flight_cabin_inventory, train_routes, train_departures, train_seat_inventory, bus_routes, bus_departures, bus_seat_inventory, transfer_services, transfer_service_area_rules, transfer_capacity_calendar
会员域：users, user_profiles, travelers, member_accounts, member_point_ledger
营销域：coupon_templates, user_coupons, promotions, promotion_rules, promotion_bindings
基础维度：areas, currencies, channels, transport_hubs, suppliers

## 元数据库（meta，4张表）

table_info — 表定义（名称/类型/描述）
column_info — 字段定义（数据类型/角色/别名/示例值）
metric_info — 指标定义（口径/依赖字段/业务别名）
column_metric — 字段-指标多对多关联

## 预定义指标（12个）

订单量 COUNT(DISTINCT orders.id) / 收入金额 SUM(paid_amount) / 商品原价总额 SUM(goods_amount)
优惠总金额 SUM(marketing+coupon+point discount) / 退款金额 SUM(refunded_amount)
退款率 SUM(refunded)/SUM(paid)*100% / 客单价 SUM(paid)/COUNT(id)
用券数量 COUNT(DISTINCT coupon_usages.id) / 券抵扣金额 SUM(coupon_usages.discount_amount)
用户数 COUNT(DISTINCT users.id) / 支付订单量 COUNT(DISTINCT orders.id) WHERE paid
目的地订单量 按城市/景点分组统计订单数

## 项目结构

```
app/
  agent/                  # 智能体核心
    graph.py              # LangGraph 图定义（13节点+条件分支）
    state.py              # 状态定义
    context.py            # 运行时上下文
    llm.py                # LLM 客户端封装
    nodes/                # 13个处理节点
      n01_extract_keywords.py   # jieba 关键词提取
      n02_expand_keywords.py    # LLM 关键词扩展
      n03_recall_column.py      # Qdrant 字段语义召回
      n04_recall_metric.py      # Qdrant 指标语义召回
      n05_recall_value.py       # ES 维度值全文检索
      n06_merge_retrieved_info.py   # 三路合并
      n07_filter_table.py       # LLM 表过滤
      n08_filter_metric.py      # LLM 指标过滤
      n09_add_extra_context.py  # 补充上下文
      n10_generate_sql.py       # LLM 生成 SQL
      n11_validate_sql.py       # SQL 语法校验
      n12_correct_sql.py        # LLM 修正（最多2次）
      n13_execute_sql.py        # 执行 SQL
  api/query_stream.py     # SSE 流式查询接口
  clients/                # 第三方客户端
    mysql_client_manager.py
    qdrant_client_manager.py
    es_client_manager.py
    embedding_client.py
  repositories/           # 数据访问层
    meta_repository.py    # meta 库 CRUD
    qdrant_repository.py  # Qdrant 操作
    es_repository.py      # ES 操作
  conf/                   # 配置
    app_config.py         # 应用配置（OmegaConf 自动加载）
    app_config.yaml       # 服务地址、LLM 密钥
    meta_config.yaml      # 元数据定义（表、字段、指标）
  models/                 # SQLAlchemy ORM 模型
  core/                   # 基础框架
    lifespan.py           # 应用生命周期
    middleware.py         # CORS/request_id/日志中间件
    log.py                # loguru 日志配置
    context.py            # 异步上下文变量
  prompts/                # LLM 提示词模板
  services/               # 业务服务
  scripts/                # 初始化脚本
    init_meta_db.py       # 初始化 meta 数据库
    build_meta_knowledge.py    # 构建元数据知识库
  static/index.html       # 前端页面
  main.py                 # FastAPI 应用入口
```
## 快速启动

### 前置依赖
- Python >= 3.12
- MySQL 8.0（业务库 travel + 元数据库 meta）
- Qdrant（字段/指标向量索引）
- Elasticsearch（维度值全文索引）
- Text Embedding Inference（BGE 模型推理）

### 初始化 & 启动

```
# 1. 安装依赖
uv sync

# 2. 构建元数据知识库（写入 meta 库、Qdrant、ES）
python -m app.scripts.build_meta_knowledge -c app/conf/meta_config.yaml

# 3. 启动服务
uvicorn app.main:app --host 0.0.0.0 --port 8000
`

访问 http://localhost:8000 进入查询页面。

## 配置

所有配置集中在 app/conf/app_config.yaml：

| 配置段 | 说明 |
|---|---|
| db_travel / db_travel_meta | MySQL 业务库和元数据库连接 |
| qdrant | Qdrant 地址（默认 192.168.10.128:6333） |
| es | Elasticsearch 地址（默认 192.168.10.128:9200） |
| embedding | Embedding 服务地址（默认 192.168.10.128:8081） |
| llm | 大模型配置（model_name、api_key、timeout） |

## 三路召回机制

用户输入「西安酒店的订单量和收入」：

jieba 提取关键词 → LLM 扩展关键词

**Qdrant 字段召回**：areas.area_full_name, hotels.hotel_name, orders.id, orders.paid_amount
**Qdrant 指标召回**：m_order_count（订单量）, m_revenue（收入金额）
**ES 维度值召回**：areas.area_full_name = "陕西省/西安市"

## 测试查询

> 西安酒店的订单量和收入金额
>
> 2026年6月杭州的酒店订单，按酒店统计订单量和退款金额
>
> App 渠道上海用户的用券订单占比和券抵扣金额