# ChatBi

**Repository Path**: ddgetget/chat-bi

## Basic Information

- **Project Name**: ChatBi
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-07
- **Last Updated**: 2026-04-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ChatBI SQL Agent Service

基于 `FastAPI + LangGraph` 实现的 SQL 智能服务，包含两个核心 Agent：

- SQL 生成 Agent：根据自然语言问题 + `data/` 中的表结构信息生成 SQL
- SQL 优化 Agent：对已有 SQL 做性能与可维护性优化

## 1. 数据格式约定

`data/*.json` 使用 JSONL（每行一个 JSON 对象）：

- key：`数据库名.表名`
- value：
  - `table_comment`: 表注释
  - `column_comments`: 字段列表（`column_name`, `column_type`, `column_comment`）

服务会启动时加载该目录，自动构建 schema 检索上下文。

## 2. 环境准备

```bash
uv sync
```

复制配置模板并填写：

```bash
cp .env.example .env
```

关键配置：

- `LLM_PROVIDER`：`openai` 或 `deepseek`（默认建议 `deepseek`）
- `OPENAI_*` / `DEEPSEEK_*`：模型调用参数
- `DATA_DIR`：schema 数据目录，默认 `data`
- 若使用 Azure OpenAI：
  - `OPENAI_API_URL` 填 Azure endpoint（如 `https://xxx.openai.azure.com/`）
  - `OPENAI_DEPLOYMENT` 填部署名（不填则使用 `OPENAI_MODEL`）
  - `OPENAI_API_VERSION` 按 Azure 版本填写

## 3. 启动

### 方式一：脚本启动（推荐）

```bash
./scripts/start.sh
```

### 方式二：手动启动

```bash
uv run uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```

启动后访问：

- Swagger: [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs)

## 4. 接口说明

统一前缀：`/api/v1`

### 4.1 健康检查

- `GET /health`
- `GET /schema/stats`

### 4.2 SQL 生成

- `POST /sql/generate`

请求示例：

```json
{
  "question": "查询近30天每个卖家的订单数",
  "provider": "openai",
  "top_k_tables": 8,
  "max_columns_per_table": 30,
  "max_context_chars": 18000,
  "dialect": "MySQL"
}
```

### 4.3 SQL 优化

- `POST /sql/optimize`

请求示例：

```json
{
  "sql": "SELECT * FROM some_table WHERE create_time >= NOW() - INTERVAL 30 DAY",
  "optimization_goal": "减少扫描行数，避免SELECT *",
  "provider": "openai"
}
```

### 4.4 一体化（生成 + 优化）

- `POST /sql/generate-optimize`

请求示例：

```json
{
  "question": "查询近30天每个卖家的订单数",
  "provider": "openai",
  "top_k_tables": 10,
  "max_columns_per_table": 30,
  "max_context_chars": 18000,
  "dialect": "MySQL",
  "optimization_goal": "优先使用索引字段并控制返回列"
}
```

## 5. 项目结构

```text
app/
  agents/
    sql_generator.py      # SQL 生成 Agent（LangGraph）
    sql_optimizer.py      # SQL 优化 Agent（LangGraph）
  api/
    routes.py             # FastAPI 路由
  core/
    config.py             # .env 配置读取
    llm_factory.py        # LLM 构造（OpenAI/DeepSeek）
    schema_loader.py      # JSONL schema 解析和检索
  models/
    schemas.py            # 请求响应模型
  main.py                 # FastAPI 应用入口
scripts/
  start.sh                # 一键启动脚本
pyproject.toml            # uv 依赖管理
```

## 6. 注意事项

- 当前实现以 schema 检索 + LLM 生成为主，不直接执行 SQL（安全默认）
- 若需要执行 SQL，可在此基础上新增数据库连接层，并做好 SQL 白名单/只读控制
- 建议在生产中增加请求审计、速率限制、结果缓存与提示词防注入策略
- 为应对大规模 schema，接口支持上下文预算与字段裁剪（`max_context_chars`、`max_columns_per_table`）
- 生成与优化结果都会做表/字段合法性校验，不合法会自动修复，必要时回退到已校验 SQL
- 默认使用 `uv sync --python 3.12`，避免 Python 3.14 与部分 LangChain 依赖兼容性问题