# jintian

**Repository Path**: dailycreatebug/jintian

## Basic Information

- **Project Name**: jintian
- **Description**: python chatbi
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-15
- **Last Updated**: 2026-06-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ChatBI Backend - LangGraph Text-to-SQL

## ✅ 已实现功能

### 核心架构
- ✅ **LangGraph工作流**：固定流程的状态机
  - 问题输入 → RAG检索 → Prompt组装 → SQL生成 → 查询执行 → 答案返回
- ✅ **异常不吞没**：所有异常都会抛出并返回500错误
- ✅ **详细日志**：每一步都有日志记录，方便调试

### 服务组件
- ✅ **RAG检索**：TF-IDF相似度匹配
- ✅ **Prompt组装**：模板 + Few-shot示例
- ✅ **SQL生成**：通义千问LLM
- ✅ **数据库执行**：MySQL查询

---

## 🚀 快速开始

### 1. 安装依赖
```bash
cd backend
pip install -r requirements.txt
```

### 2. 配置环境变量
已配置 `.env` 文件，包含：
- 通义千问 API Key
- 数据库连接信息（jintian_sales）

### 3. 启动服务
```bash
python main.py
```

服务将在 http://localhost:8000 启动

### 4. 测试接口

**Text-to-SQL查询：**
```bash
curl -X POST "http://localhost:8000/api/v1/text2sql/query" \
  -H "Content-Type: application/json" \
  -d '{"question": "总销售额是多少？"}'
```

**健康检查：**
```bash
curl http://localhost:8000/health
```

---

## 📊 API文档
启动服务后访问：
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc

---

## 🔍 调试指南

### 查看日志
启动时会看到详细日志：
```
INFO - 🚀 启动 ChatBI v1.0.0
INFO - 📦 默认LLM Provider: tongyi
INFO - 💾 数据库: localhost:3306/jintian_sales
INFO - ✅ 数据库连接成功
INFO - Text-to-SQL 工作流初始化完成
```

### 处理请求时的日志
```
INFO - 收到问题: 总销售额是多少？
INFO - [retrieve] 开始检索相似问题
INFO - [retrieve] 检索到 3 个相似问题
INFO - [build_prompt] 开始组装Prompt
INFO - [build_prompt] Prompt组装完成，长度: 1234
INFO - [generate_sql] 开始生成SQL
INFO - [generate_sql] SQL生成完成: SELECT SUM(SALES_AMOUNT)...
INFO - [execute_query] 开始执行查询
INFO - [execute_query] 查询执行成功，返回 1 行
INFO - [generate_answer] 开始生成答案
INFO - [generate_answer] 答案生成完成
```

### 错误处理
任何错误都会：
1. 记录详细日志（包括堆栈）
2. 返回HTTP 500错误
3. 包含错误详情

示例错误响应：
```json
{
  "detail": {
    "message": "处理问题时发生错误",
    "error": "具体的错误信息",
    "question": "总销售额是多少？"
  }
}
```

---

## 📁 项目结构
```
backend/
├── app/
│   ├── api/
│   │   ├── test.py              # 测试接口
│   │   └── text2sql.py          # Text-to-SQL接口
│   ├── core/
│   │   ├── config.py            # 配置管理
│   │   ├── llm_config.py        # LLM工厂
│   │   └── database.py         # 数据库连接
│   ├── services/
│   │   ├── rag_retriever.py    # RAG检索
│   │   ├── prompt_builder.py   # Prompt组装
│   │   ├── sql_generator.py    # SQL生成
│   │   └── db_executor.py      # 数据库执行
│   ├── workflow/
│   │   ├── text2sql_state.py   # 工作流状态
│   │   └── text2sql_graph.py  # LangGraph工作流
│   ├── data/
│   │   └── test_questions.json # 测试问题集
│   └── prompts/
│       └── system_prompt.txt  # System Prompt模板
├── main.py                     # FastAPI入口
└── requirements.txt            # 依赖清单
```

---

## 🧪 测试问题

当前有3个测试问题（`app/data/test_questions.json`）：

1. **简单查询**：总销售额是多少？
2. **带条件查询**：2023年的总销售额是多少？
3. **分组查询**：各业务员的销售额排名是多少？

---

## ⚠️ 注意事项

### 异常处理原则
- **绝不吞异常**：所有异常都会抛出
- **详细日志**：每个节点都有日志记录
- **错误传递**：通过workflow state传递错误状态

### 调试重点
1. 检查每个步骤的输出
2. 查看日志中的错误信息
3. 验证数据加载是否成功
4. 确认LLM API调用是否正常

---

## 📝 下一步优化

1. **增加更多测试问题**
2. **优化Prompt模板**
3. **改进答案生成**（用LLM生成自然语言）
4. **添加SQL验证**（执行前检查）
5. **可视化工作流图**