# Doris 自然语言查询助手

用自然语言查询 Doris `ods` 库,基于 [openai-agents-python](https://github.com/openai/openai-agents-python) + 百炼 glm-5 + Gradio WebUI。

## 工作原理

```
用户提问 → 单个 Agent
            ├─ list_tables(keyword)      # 在 ods 库找相关表
            ├─ get_table_schema(table)   # 看列定义和注释
            └─ execute_sql(sql)          # 只读 SELECT,≤200 行(SQL 报错自动重试)
          → 用中文总结结果 + 附最终 SQL
```

- **安全**:只用只读账号 `readonly_yfkj`;`execute_sql` 拒绝非 SELECT,并把 SQL 包进子查询 + LIMIT 200。
- **多轮**:对话历史由 Gradio 管理(每用户/标签页独立)。
- **schema 缓存**:表/列/注释抓一次存 `schema.json`,不每轮查。

## 安装

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

填好 `.env`(参考 `.env.example`):百炼 key、glm-5、Doris 只读账号。

## 运行

```bash
# 1) (首次)抓取表结构到 schema.json —— 需能连通 Doris
python app.py --build-schema

# 2) (可选)验证 LLM 接线,不连 Doris
python app.py --selftest

# 3) 启动 WebUI
python app.py
# 打开 http://localhost:7860
```

## 部署为服务

`python app.py` 默认监听 `0.0.0.0:7860`,用 supervisor / systemd / docker 守护即可。
要对外暴露,建议加反向代理 + 鉴权(Gradio 支持 `auth=(user, pwd)`,在 `build_ui` 里加)。

## 常见问题

- **glm-5 是推理模型**:回答前会先"思考",稍慢、消耗更多 token,属正常。
- **schema 变了**:重跑 `--build-schema`。
- **想加 token 级流式**:把 `_run` 改成 generator,用 `Runner.run_streamed()` + `ResponseTextDeltaEvent` 逐字 yield。v1 没做,Gradio 自带 loading 动画够用。
- **想限制可查的表范围**:在 `load_schema` / `build_schema` 里按表名前缀过滤,别把几百张表全给 agent。
- **密钥安全**:`.env` 已 gitignore。大模型信息.md / 数据库连接信息.md 里是明文,建议从仓库移走。