在建立聊天式问答程序时常见痛点包括： 1️⃣ 前后端耦合导致一次请求就等待数秒甚至数十秒才能看到结果；怎么说呢，2️⃣ 传统 HTTP 请求一次性返回。无法实时展示进度、字段召回等信息；3️⃣ 对 SQL 不熟悉的业务同事难以快速验证查询结果；4️⃣ 开发者在调试接口时频繁切换工具、重新启动器，效率低下。

项目概览

这篇文章演示如何用 FastAPI + Vue 搭建一个 RAG 范式的 Text-to-SQL 智能体。老实说，使用者只需自然语言提问。即可在浏览器中看到每一步进度，并最终获得表格结果。

. 初始化项目

uv init n2sql-agent
cd n2sql-agent
uv run main.py
# 终端输出 "Hello from n2sql-agent!" 说明成功

再看目录结构。

.
├── README.md
├── main.py
├── pyproject.toml
└── uv.lock

痛点对策

• 快速启动uv 一键创建项目+依赖，无需手动创建虚拟环境。
• 即时反馈运行后立即验证 “Hello” 接口是否可用。

. 添加前端页面

将仓库中的 frontend/ 复制到根目录：

frontend/
├── index.html
├── package.json
├── pnpm-lock.yaml
├── vite.config.js
├── public/
│ └── vite.svg
└── src/
├── App.vue # 主页面：聊天 + SSE + 表格
├── main.js
├── style.css
└── assets/
└── vue.svg

安装并启动这方面。

cd frontend && pnpm install && pnpm dev
# 浏览器访问 http://localhost:5173/ 查看页面界面
# 注意此时后端未启动，发送消息无响应

• SSE 支持跨域请求 — 前后端分离时需配置 CORS，否则浏览器会拦截。
• SSE 流式体验不足时及时排查代理缓存问题。

. FastAPI 启动后端接口

from fastapi import FastAPI
app = FastAPI
@app.get
async def hello:
return {"msg": "Hello FastAPI + uv"}

启动这方面，

uv run fastapi dev main.py # 默认 http://localhost:8000/
curl http://localhost:8000/hello # 返回 {"msg":"Hello FastAPI + uv"}

• `StreamingResponse` 的误区方法： 确保 `media_type` 为 `text/event-stream` 并加上 `Cache-Control: no-cache`。

. 添加 SSE 流式查询接口

SSE 接口位于 /api/query POST 请求模式,用于逐步推送 NLP→SQL 的执行过程。

from fastapi import FastAPI,Request
from fastapi.middleware.cors import CORSMiddleware
from fastapi.responses import StreamingResponse
import json,asyncio
app = FastAPI
app.add_middleware(
CORSMiddleware,allow_origins=,allow_credentials=True,allow_methods=,allow_headers=,)
@app.get
async def hello:
return {"msg": "Hello FastAPI + uv"}
async def sse_stream:
texts = },{"type":"progress","step":"执行 SQL","status":"success"}。]
for text in texts:
yield f"data: {json.dumps}
"
await asyncio.sleep # 模拟耗时
@app.post
async def query:
return StreamingResponse(
sse_stream,media_type="text/event-stream",headers={"Cache-Control":"no-cache","Connection":"keep-alive"}
)

# 调试 Sse 接口:

curl -N -X POST http://localhost:8000/api/query \
-H 'Content-Type: application/json' \
-d '{"query":"测试"}'
# 输出每行进度与结果
data:{...}…

User Pain Point & Solution 


SSE 不支持 GET / POST 混合？- 在前端使用 fetch+ReadableStream 而非 EventSource；EventSource 只支持 GET。话说回来，
.

CORS 跨域导致报错？- 后端已开启 CORS 中间件；如果仍报错，请检查前端代理配置。
.

MIME 类型错误导致浏览器忽略流？- 必须设置 `media_type="text/event-stream"` 和 `headers={"Connection":"keep-alive"}`。
.

"" 无法触发结束事件？
- 前端需自行判定 `data:` 或监听 `reader.read` 的 done 标志。
.

- 在请求头加 `Cache-Control:no-cache` 并关闭 Nginx 等代理缓冲功能。
.
.

. 前后端联调


① 确认后端跑在 8000 端口，前端跑在 5173 端口。② 打开 http://localhost:5173/。输入问题，如“男女性别销售额分别是多少”，点击发送。③ 页面会显示进度条和结果表格。④ 若步骤卡住请检查浏览器控制台是否有跨域或网络错误。④ 若出现“”但未停止流，请确认前后段均已正确实现 SSE 协议解析。⑥ 完成，✅
​






架构小结

* 前段：Vue + fetch+ReadableStream 消费 SSE
* 后段：FastAPI+StreamingResponse+Async generator
* 一次请求持续推送 — 主要价值
* 单向流——不需要 WebSocket 双向握手成本
* 可插拔 AI 模型、数据库查询等






关键技术拆解

StreamingResponse: 告诉浏览器这是一个持续推送；说起来，async generator: 每个 yield 输出一条事件块；双换行
必须满足协议，ensure_ascii=False: 保持中文可读；CORS 与 Cache‑Control 防止代理缓存阻断流；前台通过 ReadableStream 手动解析事件并更新 UI。 可
至 AI 对话、实时监控等场景。






常见踩坑 & 调试技巧

CORS – 在后端添加 CORSMiddleware。怎么说呢，缓存 – 加 Cache‑Control:no-cache 或关闭 Nginx proxybuffering。JSON 转义 – 使用 ensureascii=False。按理说，EventSource仅支持 GET – 使用 fetch+ReadableStream。缓冲区 – TextDecoder 与 split 保证完整事件。SSE “PING/PONG” 心跳 —— 如代理超时可自行加入 ping 消息保持连接活跃。)





FAQ


"为什么要用 Sse 而不是 Polling?" → 避免频繁请求、减少网络负担、能即时展示进度和中间结果，而 Polling 会造成延迟和重复数据传输。

"Postman 能否测试 Sse?" → Postman 支持 WebSocket 与 SSE。但只能查看 raw 数据，需要手工解析。

"如何让多个使用者同时发起查询?" → SSE 是单向流，每个连接独立，服务器可以并发处理多条异步任务。• ""
​
​