第 0 节：快速开始指南

第 0 节：快速开始指南

本节概要

通过本节学习，你将能够：

• 在 10 分钟内快速部署 Text-to-BI 系统
• 了解系统的基本运行环境要求
• 体验 AI 聊天和数据分析两大核心功能
• 掌握常见问题的排查和解决方法
• 为后续深入学习做好准备

引言

如果你想快速体验 Text-to-BI 系统，按照本指南 10 分钟内即可运行起来。本节将带你完成从环境准备到系统运行的完整流程。

快速部署

前置要求

# 确保已安装
- Python 3.11+
- Node.js 18+
- Docker & Docker Compose

一键启动

# 1. 克隆项目
git clone <your-repo-url>
cd ask-sql

# 2. 配置后端
cd backend
python -m venv venv
source venv/bin/activate  # Windows: venvScriptsactivate
pip install -r requirements.txt

# 3. 配置环境变量
cp .env.example .env
# 编辑 .env，添加你的 DeepSeek API Key
nano .env

# 4. 启动 CubeJS
cd cubejs
docker-compose up -d
cd ..

# 5. 启动后端
python main.py &

# 6. 启动前端
cd ../frontend
npm install
npm run dev

访问应用

打开浏览器访问：

快速测试

测试 AI 聊天

1. 点击"AI 聊天"
2. 输入："你好，介绍一下你自己"
3. 查看 AI 响应

测试数据分析

1. 点击"AI 数据分析"
2. 输入："统计员工总数"
3. 查看查询结果和分析

更多查询示例

 "按性别统计员工数量"
 "显示各部门的员工分布"
 "查询女性员工数量"
 "统计每个部门的平均工资"

深入学习

完成快速体验后，建议按顺序阅读完整教程：

1. Vibe Coding 基础 (第1-4篇)

   • 理解 Vibe Coding 的理念和方法

2. 项目架构 (第5-6篇)

   • 了解系统设计思路

3. 后端开发 (第7-12篇)

   • 学习 FastAPI + Agno 开发

4. 前端开发 (第13-16篇)

   • 掌握 Vue 3 + TypeScript

5. 部署总结 (第17-18篇)

   • 完整部署和项目总结

遇到问题？

常见问题

Q1: 后端启动失败？

# 检查虚拟环境
source venv/bin/activate  # macOS/Linux
# 或
venvScriptsactivate     # Windows

pip list | grep fastapi

Q2: CubeJS 连接失败？

# 检查 Docker
docker-compose ps
docker-compose logs

# 重启服务
docker-compose restart

Q3: 前端无法连接？

# 检查后端
curl 

# 检查环境变量
cat frontend/.env

Q4: DeepSeek API 错误？

• 检查 API Key 是否正确
• 确认账户余额充足
• 查看 API 调用限制

获取帮助

• 查看完整文档：目录
• 提交 Issue：GitHub Issues
• 技术讨论：查看项目 Discussions

本节小结

通过本节的快速开始，你已经：

1. 完成环境搭建：安装了 Python、Node.js、Docker 等必需软件
2. 成功启动系统：后端、前端、CubeJS 三个服务全部运行
3. 体验核心功能：测试了 AI 聊天和数据分析功能
4. 掌握排查方法：了解了常见问题的解决方案
5. 准备深入学习：为后续章节的学习打下基础

思考与练习

思考题

1. 在启动过程中，你遇到了哪些问题？是如何解决的？
2. 体验了系统功能后，你觉得哪些地方可以改进？
3. 这个系统的架构设计有什么特点？为什么要分为三个服务？

实践练习

1. 功能测试：

   • 尝试 5 个不同的自然语言查询
   • 观察系统的响应时间和准确性
   • 记录哪些查询效果好，哪些不理想

2. 环境熟悉：

   • 访问 FastAPI 文档页面（）
   • 查看 CubeJS Playground（）
   • 使用浏览器开发者工具观察网络请求

3. 问题排查：

   • 故意停止某个服务，观察系统表现
   • 练习使用日志排查问题
   • 尝试修改配置文件并重启服务

下一节：第 1 节：什么是 Vibe Coding