第 0 节：快速开始指南
阅读时间：约 3 分钟
实践时间：约 10 分钟
难度级别：入门
前置知识：基本的命令行操作
本节概要
通过本节学习，你将能够：
- 在 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: venv\Scripts\activate
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
访问应用
打开浏览器访问：http://localhost:5173
🎯 快速测试
测试 AI 聊天
- 点击"AI 聊天"
- 输入："你好，介绍一下你自己"
- 查看 AI 响应
测试数据分析
- 点击"AI 数据分析"
- 输入："统计员工总数"
- 查看查询结果和分析
更多查询示例
✅ "按性别统计员工数量"
✅ "显示各部门的员工分布"
✅ "查询女性员工数量"
✅ "统计每个部门的平均工资"
📚 深入学习
完成快速体验后，建议按顺序阅读完整教程：
-
Vibe Coding 基础 (第1-4篇)
- 理解 Vibe Coding 的理念和方法
-
项目架构 (第5-6篇)
- 了解系统设计思路
-
后端开发 (第7-12篇)
- 学习 FastAPI + Agno 开发
-
前端开发 (第13-16篇)
- 掌握 Vue 3 + TypeScript
-
部署总结 (第17-18篇)
- 完整部署和项目总结
🐛 遇到问题？
常见问题
Q1: 后端启动失败？
# 检查虚拟环境
source venv/bin/activate # macOS/Linux
# 或
venv\Scripts\activate # Windows
pip list | grep fastapi
Q2: CubeJS 连接失败？
# 检查 Docker
docker-compose ps
docker-compose logs
# 重启服务
docker-compose restart
Q3: 前端无法连接？
# 检查后端
curl http://localhost:8000/health
# 检查环境变量
cat frontend/.env
Q4: DeepSeek API 错误？
- 检查 API Key 是否正确
- 确认账户余额充足
- 查看 API 调用限制
获取帮助
- 📖 查看完整文档：目录
- 🐛 提交 Issue：GitHub Issues
- 💬 技术讨论：查看项目 Discussions
本节小结
通过本节的快速开始，你已经：
- 完成环境搭建：安装了 Python、Node.js、Docker 等必需软件
- 成功启动系统：后端、前端、CubeJS 三个服务全部运行
- 体验核心功能：测试了 AI 聊天和数据分析功能
- 掌握排查方法：了解了常见问题的解决方案
- 准备深入学习：为后续章节的学习打下基础
思考与练习
思考题
- 在启动过程中，你遇到了哪些问题？是如何解决的？
- 体验了系统功能后，你觉得哪些地方可以改进？
- 这个系统的架构设计有什么特点？为什么要分为三个服务？
实践练习
-
功能测试：
- 尝试 5 个不同的自然语言查询
- 观察系统的响应时间和准确性
- 记录哪些查询效果好，哪些不理想
-
环境熟悉：
- 访问 FastAPI 文档页面（http://localhost:8000/docs）
- 查看 CubeJS Playground（http://localhost:4000）
- 使用浏览器开发者工具观察网络请求
-
问题排查：
- 故意停止某个服务，观察系统表现
- 练习使用日志排查问题
- 尝试修改配置文件并重启服务
