FastAPI 人工智能预订系统
一个完整的基于人工智能的餐厅预订系统，包含两个FastAPI服务：
- MCP 服务器： 餐厅预订API
- MCP 客户端： 使用OpenAI函数调用的AI聊天界面
🏗️ 建筑学
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ User/Client │─────▶│ MCP Client │─────▶│ MCP Server │
│ │ │ (AI Chat API) │ │ (Booking API) │
│ │ │ Port: 8001 │ │ Port: 8000 │
│ │◀─────│ + OpenAI GPT-4 │◀─────│ Clean Arch │
└─────────────────┘ └──────────────────┘ └─────────────────┘
│
▼
┌──────────┐
│ OpenAI │
│ API │
└──────────┘🚀 快速入门
先决条件
- Python 3.12及以上版本
- OpenAI API密钥
- Docker（可选，用于可观测性堆栈）
1. 设置MCP服务器（预订API）
# Navigate to server directory
cd mcp-server
# Create virtual environment
python3 -m venv venv
source venv/bin/activate
# Install dependencies
pip install -r requirements.txt
# Run server on port 8000
uvicorn main:app --reload --port 8000服务器将在以下地址可用：http://localhost:8000
2. 设置MCP客户端（AI聊天API）
# Open a new terminal
cd mcp-client
# Create virtual environment
python3 -m venv venv
source venv/bin/activate
# Install dependencies
pip install -r requirements.txt
# Create .env file with your OpenAI API key
echo "OPENAI_API_KEY=your_openai_api_key_here" > .env
echo "MCP_SERVER_URL=http://localhost:8000" >> .env
echo "OPENAI_MODEL=gpt-4o-mini" >> .env
# Run client on port 8001
uvicorn main:app --reload --port 8001客户端将可通过以下地址访问：http://localhost:8001
📖 使用方法
选项1：使用API文档（最简单）
- 打开 http://localhost:8001/docs
- 试试这个
POST /api/chat终端节点 - 发送一条类似这样的信息：
{
"message": "I want to book a table at Luigi's Pizza today at 7pm for 4 people, my name is John Doe, phone is 555-1234",
"conversation_history": []
}选项2：使用cURL
curl -X POST "http://localhost:8001/api/chat" \
-H "Content-Type: application/json" \
-d '{
"message": "Book a table at La Bella tomorrow at 6pm for 2 people",
"conversation_history": []
}'选项3：使用Python
import requests
response = requests.post(
"http://localhost:8001/api/chat",
json={
"message": "I need a reservation at Pizza Palace today at 5pm for 3 people, I'm Jane Smith, 555-9876",
"conversation_history": []
}
)
print(response.json()["message"])💬 示例对话
完整信息（直接预订）
你： “请帮我预订明天晚上7点在路易吉餐厅的两人桌，姓名约翰·多伊，电话555-1234。”
人工智能（AI）: “✅ 太好了！我已成功预订了Luigi's餐厅2024年10月13日19:00的座位，共2位客人。预订编号：abc-123...”
部分信息（人工智能提问）
你： “我想预订一家餐厅”
人工智能（AI）： “我很乐意帮忙！您想预订哪家餐厅？”
你： “La Bella”（拉贝拉）
人工智能： “很好的选择！您希望选择哪一天和时间呢？”
你： “今天下午6点，4人份”
人工智能（AI）： “太好了！能告诉我您的姓名和电话号码吗？”
你： “约翰·史密斯，555-1234”
人工智能： ✅ 太好了！我已经成功预订了桌子。.."
🔧 它的工作原理
- 用户发送消息 到MCP客户端聊天终端
- OpenAI GPT-4 使用函数调用分析信息
- AI决定 如果预订信息完整：
- ❌ 缺少信息 → 提问以澄清 - ✅ 完成 → 预约通话功能
- MCP客户端 调用MCP服务器API以创建预订
- 确认 返回给用户
📊 可观测性堆栈（新功能！）
使用Grafana堆栈实现全面的监控、记录和追踪！
快速入门可观测性
# Start Grafana, Prometheus, Loki, Tempo
docker-compose up -d
# Access Grafana
open http://localhost:3000
# Login: admin/admin你将获得什么
- 📈 指标 (Prometheus) - 请求速率、延迟、错误率
- 📝 日志 (Loki) - 带搜索功能的集中式日志记录
- 🔍 迹象/痕迹 (Tempo) - 跨服务的分布式追踪
- 📊 仪表板 (Grafana) - 预构建的 FastAPI 仪表板
服务
| 服务 | URL | 用途 |
|---|---|---|
| Grafana | http://localhost:3000 | 可视化与仪表板 |
| Prometheus | http://localhost:9090 | 指标收集 |
| MCP 服务器指标 | http://localhost:8000/metrics | 服务器指标端点 |
| MCP 客户端指标 | http://localhost:8001/metrics | 客户端指标端点 |
📖 完整文档： 看 \OBSERVABILITY.md\ 翻译成中文为：\可观测性.md\
📁 项目结构
fastapi-project/
├── mcp-server/ # Booking API (Clean Architecture)
│ ├── app/
│ │ ├── domain/ # Business entities
│ │ ├── application/ # Use cases & interfaces
│ │ ├── infrastructure/ # Repositories
│ │ └── api/ # Routes & schemas
│ ├── main.py
│ ├── requirements.txt
│ └── README.md
│
├── mcp-client/ # AI Chat API
│ ├── app/
│ │ ├── core/ # Config
│ │ ├── services/ # OpenAI & HTTP clients
│ │ ├── routes/ # Chat endpoint
│ │ └── schemas/ # Request/response models
│ ├── main.py
│ ├── requirements.txt
│ ├── .env.example
│ └── README.md
│
└── .cursorrules # AI assistant rules🎯 API 端点
MCP服务器（端口8000）
| 方法 | 终点 | 描述 | ||||
|---|---|---|---|---|---|---|
| POST | （在中文中，这通常直接保留为“POST”，因为它是HTTP协议中的一个动词，表示“提交”或“发送”数据到服务器，无需翻译） /api/bookings | 创建预订 | ||||
| GET | （可翻译为） | 获取 | /api/bookings/{id} | 按ID获取预订信息 | ||
| GET | （可翻译为） | 获取 | 或 | 请求获取 | /api/bookings | 列出所有预订 |
MCP 客户端（端口 8001）
| 方法 | 结束点 | 描述 |
|---|---|---|
| 帖子 | /api/chat 发送聊天信息 |
🔐 环境变量
创建 mcp-client/.env:
OPENAI_API_KEY=sk-proj-...your-key-here...
MCP_SERVER_URL=http://localhost:8000
OPENAI_MODEL=gpt-4o-mini⚠️ 安全： 永远不要承诺 .env 将文件提交到Git！
🧪 测试
直接测试MCP服务器
curl -X POST "http://localhost:8000/api/bookings" \
-H "Content-Type: application/json" \
-d '{
"restaurant": "Test Restaurant",
"date": "2024-12-25",
"time": "18:00",
"guests": 2,
"customer_name": "Test User",
"customer_phone": "555-0000"
}'测试MCP客户端聊天功能
curl -X POST "http://localhost:8001/api/chat" \
-H "Content-Type: application/json" \
-d '{
"message": "I want to book a table",
"conversation_history": []
}'📚 文档说明
- MCP 服务器文档：http://localhost:8000/docs
- MCP 客户端文档：http://localhost:8001/docs
🏛️ 清洁架构
MCP服务器遵循清洁架构原则：
- 领域层： 纯粹的业务逻辑（实体、规则）
- 应用层： 用例和接口
- 基础设施层： 外部实现（存储库）
- API 层： FastAPI 路由和模式（或“架构”）
好处：
- ✅ 可测试
- ✅ 可维护性
- ✅ 与框架无关
- ✅ 易于扩展
🛠️ 技术
- FastAPI - 现代Python网络框架
- OpenAI GPT-4o-mini（可译为“OpenAI的GPT-4o迷你版”或根据具体语境简化为“OpenAI迷你版GPT-4o”，但需注意的是，“GPT-4o”并非官方已知的命名，可能是特定语境或假设下的称呼，实际翻译时可能需要根据具体背景调整） - 人工智能语言模型
- Pydantic - 数据验证
- httpx（注：这是一个专有名词或特定技术的名称，在中文中通常直接保留原样，不进行翻译，但如果需要解释其含义或用途，可以在此基础上进行说明，但在此处仅提供直接翻译） - 异步HTTP客户端
- Uvicorn（注：Uvicorn是一个用于构建ASGI服务器的Python库，常用于运行ASGI应用程序，如FastAPI等框架） - ASGI 服务器
📝 笔记
- 预订信息已保存 内存中的 （重启服务器会清除数据）
- 非常适合开发和测试
- 为了增加持久性，使用数据库实现仓库
- MCP客户端需要OpenAI API密钥
🤝 贡献
遵循 .cursorrules 文件包含代码风格和架构指南。
📄 许可证
这个项目旨在用于教育目的。