# finance-nl2sql

**Repository Path**: codercraftman/finance-nl2sql

## Basic Information

- **Project Name**: finance-nl2sql
- **Description**: 金融nl2sql
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-19
- **Last Updated**: 2026-08-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 信贷智能问数 Demo

本项目是一个面向信贷业务的自然语言问数 MVP。用户输入中文问题后，系统调用 Qwen 理解问题并生成逻辑查询计划，再生成 PostgreSQL 只读 SQL；SQL 经过 SQLGlot 安全校验后执行，最终返回指标、表格、趋势图和口径说明。

当前覆盖贷款申请、审批、合同、放款、还款和逾期主题。项目仅使用模拟数据，不参与真实授信、审批或其他信贷决策。

## 一、主要技术栈

- Python 3.12
- uv：Python 版本、虚拟环境和依赖同步
- FastAPI：后端接口
- Streamlit：演示页面
- qwen-plus：问题理解和 SQL 生成
- PostgreSQL 16：信贷模拟数据
- SQLAlchemy 2：数据库访问
- SQLGlot：SQL AST 安全校验
- Plotly：结果图表
- pytest：自动化测试

## 二、项目目录

```text
finance-nlp2sql/
├── app/                       后端应用
├── ui/                        Streamlit 页面
├── semantic/                  信贷语义配置
├── scripts/                   数据初始化与回归测试脚本
├── tests/                     自动化测试
├── docs/                      项目文档
├── docker-compose.yml         PostgreSQL 容器配置
├── pyproject.toml             Python 依赖和工具配置
├── .env.example               环境变量模板
└── README.md                  使用说明
```

## 三、运行环境

运行前请准备：

- Windows 10/11
- PowerShell 7 或 Windows PowerShell
- uv 0.11 或更高版本
- Docker Desktop
- 可访问的 Qwen OpenAI-compatible API

检查版本：

```powershell
uv --version
docker --version
docker compose version
```

## 四、首次安装

### 4.1 进入工程目录

```powershell
cd D:\Projects\finance-nlp2sql
```

### 4.2 同步 Python 和依赖环境

```powershell
uv sync
```

`uv sync` 会根据 `.python-version` 准备 Python 3.12，根据 `uv.lock` 创建 `.venv`，并安装运行依赖和开发测试依赖。其他开发人员克隆项目后执行同一命令即可获得一致环境。

检查环境：

```powershell
uv run python --version
uv run python -c "import fastapi, streamlit, sqlglot; print('环境正常')"
```

### 4.3 锁定依赖

日常使用只需要执行 `uv sync`，不要手工修改 `uv.lock`。修改 `pyproject.toml` 中的依赖后，维护人员执行以下命令更新锁文件：

```powershell
uv lock
uv sync
```

### 4.4 创建配置文件

```powershell
Copy-Item .env.example .env
```

打开 `.env`，填写 Qwen 地址和密钥：

```env
LLM_MODEL=qwen-plus
LLM_BASE_URL=
LLM_API_KEY=
LLM_TRUST_ENV=false
LLM_TIMEOUT_SECONDS=30
LLM_MAX_RETRIES=0

DATABASE_URL=postgresql+psycopg://nlp2sql:nlp2sql@localhost:5432/finance_demo
DATABASE_READONLY_URL=postgresql+psycopg://credit_reader:credit_reader@localhost:5432/finance_demo
QUERY_MAX_ROWS=200
QUERY_TIMEOUT_MS=10000
SHOW_DEBUG=true
```

说明：

- `LLM_BASE_URL` 应填写 OpenAI-compatible API 的基础地址。
- `LLM_API_KEY` 只保存在本地 `.env`，不要提交到 Git。
- `LLM_TRUST_ENV=false` 用于避免本机异常代理干扰 DashScope 连接。
- `DATABASE_URL` 用于初始化和维护演示数据。
- `DATABASE_READONLY_URL` 是问数时使用的只读数据库账号。

## 五、数据库启动和初始化

### 5.1 启动 Docker Desktop

先确认 Docker Desktop 已运行：

```powershell
docker info
```

### 5.2 启动 PostgreSQL

```powershell
docker compose up -d postgres
```

检查容器：

```powershell
docker compose ps
docker exec finance-nlp2sql-postgres pg_isready -U nlp2sql -d finance_demo
```

### 5.3 首次初始化模拟数据

```powershell
uv run python scripts/setup_database.py
```

初始化脚本会重新生成确定性的模拟数据，当前包括约 500 笔贷款申请，以及相应的审批、合同、放款、还款计划、还款流水和逾期快照。

检查各表记录数：

```powershell
docker exec finance-nlp2sql-postgres psql -U nlp2sql -d finance_demo -c "SELECT COUNT(*) FROM credit_data.loan_application;"
```

注意：再次执行初始化脚本会清空并重建信贷模拟数据。

## 六、启动系统

后端、前端需要在两个独立终端中运行。两个终端都应进入工程目录，命令统一通过 `uv run` 使用项目锁定环境，无需手工激活虚拟环境。

### 6.1 启动 FastAPI 后端

终端一：

```powershell
cd D:\Projects\finance-nlp2sql
uv run uvicorn app.main:app --reload --host 127.0.0.1 --port 8000
```

启动后访问：

- 健康检查：http://localhost:8000/api/v1/health
- Swagger 接口页面：http://localhost:8000/docs
- ReDoc 接口页面：http://localhost:8000/redoc

健康检查中 `llm_configured` 应为 `true`。如果为 `false`，说明 Qwen 地址或密钥未正确读取。

### 6.2 启动 Streamlit 前端

终端二：

```powershell
cd D:\Projects\finance-nlp2sql
uv run streamlit run ui/streamlit_app.py
```

浏览器访问：http://localhost:8501

Streamlit 首次运行可能询问电子邮箱。该信息不是项目要求，可以直接按回车跳过。

### 6.3 推荐启动顺序

1. 启动 Docker Desktop。
2. 启动 PostgreSQL 容器。
3. 启动 FastAPI 后端。
4. 确认健康检查正常。
5. 启动 Streamlit 前端。

## 七、测试命令

### 7.1 运行全部本地自动化测试

```powershell
uv run pytest -q
```

测试覆盖配置、API、语义注册、逻辑计划归一化、SQL 安全校验、错误处理和结果中文展示。当前共 17 项测试。

### 7.2 运行 SQL 安全测试

```powershell
uv run pytest -q tests/test_sql_validator.py
```

### 7.3 运行真实端到端回归

端到端回归会真实调用 Qwen 并查询 PostgreSQL，因此必须先启动数据库并正确填写 `.env`：

```powershell
uv run python scripts/run_smoke_tests.py
```

当前回归集包含 10 条问题，覆盖申请、审批、放款、贷款余额、还款、逾期、趋势、排名和对比。数值型问题会与人工参考 SQL 结果比对。

分批执行：

```powershell
uv run python scripts/run_smoke_tests.py 0 3
uv run python scripts/run_smoke_tests.py 3 3
uv run python scripts/run_smoke_tests.py 6 4
```

完整结果保存在工程根目录的 `smoke_test_results_0_10.json`。

### 7.4 手工测试后端接口

```powershell
$body = @{ question = "本月贷款申请数是多少？"; debug = $true } | ConvertTo-Json
Invoke-RestMethod `
  -Uri "http://127.0.0.1:8000/api/v1/query" `
  -Method Post `
  -ContentType "application/json; charset=utf-8" `
  -Body ([Text.Encoding]::UTF8.GetBytes($body))
```

## 八、停止系统

### 8.1 停止前端和后端

在运行 Streamlit 和 Uvicorn 的终端中分别按：

```text
Ctrl+C
```

### 8.2 停止 PostgreSQL 容器

停止容器但保留数据卷：

```powershell
docker compose stop postgres
```

停止并删除容器和网络，但保留数据卷：

```powershell
docker compose down
```

停止并删除容器、网络和数据卷：

```powershell
docker compose down -v
```

警告：`docker compose down -v` 会删除 PostgreSQL 数据。下次启动后必须重新执行数据库初始化脚本。

### 8.3 清理本地 Python 环境

一般无需手工退出环境，因为 `uv run` 不要求激活虚拟环境。如果需要重新创建本地环境，可删除 `.venv` 后再次同步：

```powershell
Remove-Item -Recurse -Force .venv
uv sync
```

## 九、演示问题

- 本月贷款申请数是多少？
- 本月贷款申请金额是多少？
- 本月审批通过率是多少？
- 最近六个月放款金额趋势如何？
- 哪个贷款产品申请最多？
- 各分行当前贷款余额排名如何？
- 当前逾期余额是多少？
- 不同逾期阶段的金额分布如何？
- 本月和上月放款金额对比如何？
- 最近 30 天实际还款金额是多少？

## 十、安全边界

- 问数使用独立 PostgreSQL 只读账号。
- SQLGlot 解析 SQL AST，不只使用字符串或正则判断。
- 只允许一条 SELECT/CTE 查询。
- 拦截写入、DDL、未授权表、投影通配符和高风险函数。
- 自动添加或收紧最大返回行数。
- 数据库事务设置为只读，并设置查询执行超时和连接超时。
- Qwen 只生成候选逻辑计划和 SQL，不能绕过校验器直接访问数据库。
- 所有数据均为模拟数据，系统不参与任何信贷决策。

## 十一、常见问题

### 11.1 页面提示无法连接后端

检查 FastAPI 是否运行：

```powershell
Invoke-RestMethod http://127.0.0.1:8000/api/v1/health
```

如果无法访问，请重新启动 Uvicorn，并保持后端终端窗口处于运行状态。

### 11.2 Qwen 连接失败

检查 `.env` 中的地址和密钥，并确认：

```env
LLM_TRUST_ENV=false
```

修改 `.env` 后需要重新启动 FastAPI。

### 11.3 数据库连接超时

检查 Docker Desktop 和容器：

```powershell
docker info
docker compose ps
docker compose up -d postgres
```

### 11.4 Streamlit 询问电子邮箱

这是 Streamlit 自身的首次运行提示，与本项目无关，直接按回车跳过即可。

### 11.5 修改代码后页面没有更新

FastAPI 使用 `--reload` 时会自动重载。Streamlit 通常也会检测文件变化；如果没有更新，分别按 `Ctrl+C` 后重新启动。

## 十二、相关文档

- `docs/接口文档.md`：独立后端接口说明
- `docs/NVIDIA服务器部署指南.md`：单机容器部署、企业 Kubernetes 演进和本地 GPU 模型说明
- `docs/Qwen-vLLM私有化部署指南.md`：Qwen 私有模型选型、显存规划、vLLM 容器部署、接入和验收
- `信贷NLP2SQL技术架构与实施计划.md`：技术架构、需求和实施计划

## 十三、当前限制

- 只支持信贷业务和 PostgreSQL 方言。
- 当前语义检索以 YAML 配置为主，pgvector 尚未进入主流程。
- 结果说明主要使用确定性模板。
- 尚未实现企业 SSO、行列权限、动态脱敏和多租户。