使用说明
AI医疗诊所助理-RAG聊天机器人
用于医疗诊所常见问题的全栈人工智能聊天机器人应用程序，由 检索增强生成（RAG） 使用LangChain、Pinecone和Groq LLM。
部署链接：(http://52.91.160.51:8080/)
两种部署选项：
- 🚀 Flask应用程序 （生产）
- 💻 Next.js+快速API （发展）
📋 目录
✨ 特性
核心RAG能力
- 🤖 检索增强生成（RAG） -来自诊所常见问题知识库的准确答案
- 🔍 语义搜索 -基于Google Generative AI嵌入的松果矢量数据库
- 💬 流媒体响应 -使用Groq的Llama 3.3 70B进行实时LLM响应
- 🛡️ 稳健的错误处理 -全面的异常处理和日志记录
- ⚡ 优化性能 -单例服务、连接池和缓存
（Flask应用程序）或（Next.js+FastAPI）
- 💬 多会话管理 -创建、切换和管理多个聊天对话
- 📌 固定重要聊天 -固定常用对话以快速访问
- 🔄 自动保存对话 -自动持久化到本地存储
- 🎨 现代UI/UX -简洁、灵敏的设计，支持暗/亮主题
- ⚡ 实时流媒体 -使用打字指示器实时流式传输人工智能响应
- �🔍 搜索功能 -搜索对话历史记录
🎥 演示
Flask应用程序界面（生产）
Next.js+FastAPI接口（开发）
聊天界面功能
- 首次加载时自动创建聊天
- 实时流媒体响应
- 侧边栏中的对话历史记录
- 固定/取消固定对话
- 暗/亮主题切换
关键能力
- 回答诊所的具体问题（时间、定价、服务）
- 从FAQ知识库中提供准确的信息
- 根据上下文处理后续问题
- 实时流式响应
🏗️ 建筑
生产（Flask应用程序）
┌─────────────────────────────┐
│ Flask Application │
│ (UI + API on Port 8080) │
│ │
│ ┌──────────┐ ┌─────────┐ │
│ │Templates │ │ API │ │
│ │ (HTML) │ │Endpoints│ │
│ └──────────┘ └─────────┘ │
└──────────────┬──────────────┘
│
┌──────────┴────┬──────────┬──────────┐
▼ ▼ ▼ ▼
┌────────┐ ┌─────┐ ┌──────┐ ┌──────┐
│Pinecone│ │Groq │ │Google│ │ FAQ │
│Vector │ │ LLM │ │Embed │ │ JSON │
│ DB │ │ │ │ │ │ │
└────────┘ └─────┘ └──────┘ └──────┘
开发（Next.js+FastAPI-可选）
┌─────────────────┐
│ Next.js UI │
│ (Port 3000) │
└────────┬────────┘
│ HTTP/SSE
▼
┌─────────────────┐
│ FastAPI Server │
│ (Port 8000) │
└────────┬────────┘
│
┌────┴────┬──────────┬──────────┐
▼ ▼ ▼ ▼
┌────────┐ ┌─────┐ ┌──────┐ ┌──────┐
│Pinecone│ │Groq │ │Google│ │ FAQ │
│Vector │ │ LLM │ │Embed │ │ JSON │
│ DB │ │ │ │ │ │ │
└────────┘ └─────┘ └──────┘ └──────┘
RAG管道：
- 用户查询→ 使用Google Generative AI嵌入
- Pinecone矢量数据库中的语义搜索
- 检索到Top-K相关FAQ块
- 上下文+查询发送给Groq LLM（Llama 3.3 70B）
- 将响应流式传输回前端
🎯 架构决策：为什么选择Flask？
优先考虑快速交付和简单性
该项目最初是由 Next.js+快速API 架构，提供现代、解耦的前端后端设置。然而在评估了项目需求和部署目标之后， Flask被选为主要生产部署选项.
做出这一决定的主要原因
1.关注核心功能
- 主要目标是快速有效地交付一个可用的RAG聊天机器人
- Flask的单片架构允许更快的迭代和部署
- 降低复杂性意味着将更多时间花在RAG质量、快速工程和用户体验上
2.简化部署和操作
- 单容器部署 -一个Docker镜像，而不是协调多个服务
- 降低基础设施的复杂性 -无需管理单独的前端/后端服务
- 降低运营开销 -更容易监控、记录和调试
- 更快的CI/CD管道 -单一构建和部署过程
3.适合项目规模
- 对于医疗诊所常见问题聊天机器人，Flask的功能绰绰有余
- 使用Jinja2模板的服务器端渲染提供了出色的性能
- 无需复杂的客户端状态管理或路由
4.开发效率
- Flask的简单性允许快速原型制作和功能开发
- 更少的移动部件意味着更快的调试和迭代周期
- 用于UI和API的单个代码库减少了上下文切换
Next.js+FastAPI：仍可开发
这 Next.js+快速API 安装程序作为 可选开发路径 但只能在本地运行：
- 基于React的现代UI开发
- 解耦的前端/后端架构
- TypeScript和Tailwind CSS工作流程
- 高级客户端功能
实用工程方法
这一决定反映了 实用工程哲学:
- ✅ 船舶工作软件快速
- ✅ 选择符合要求的最简单解决方案
- ✅ 优化可维护性和操作简单性
- ✅ 避免对假设的未来需求进行过度设计
基于Flask的架构提供了所有核心功能——RAG检索、流式响应、对话管理和干净的UI——同时保持了部署的简单性和易用性。
🛠️ 技术栈
生产堆栈（Flask应用程序）
- 框架： Flask 3.0+（Python 3.11+）
- UI： HTML5、CSS3、普通JavaScript
- LLM Groq（火焰3.3 70b多功能）
- 嵌入： 谷歌生成人工智能（模型/嵌入-001768维）
- 矢量数据库： 松果（无服务器，us-east-1）
- RAG框架： LangChain
- 配置： Pydantic设置
- 登录中： 洛古鲁
- 部署： Docker、GitHub操作、AWS ECR/EC2
开发栈（Next.js+FastAPI-可选）
- 后端框架： FastAPI（Python 3.11+）
- 前端框架： Next.js 15.2（React 19）
- 语言： TypeScript
- 造型： 顺风CSS 4
- 动画： 帧运动
- 图标： Lucide反应
- HTTP客户端： 获取具有SSE支持的API
📦 先决条件
在开始之前，请确保已安装以下内容：
所需软件
必需的API密钥
您需要注册以下服务（所有服务都有免费等级）：
-
谷歌人工智能工作室 （用于嵌入）
- 注册：https://makersuite.google.com/app/apikey
- 从仪表板获取API密钥
-
Groq （法学硕士）
- 注册：https://console.groq.com/
- 在仪表板中创建API键
-
松果 （用于矢量数据库）
- 注册：https://www.pinecone.io/
- 注意API密钥和环境
-
职员 （可选，用于身份验证）
- 注册：https://clerk.com/
- 创建新应用程序
- 获取您的可发布密钥和密钥
🚀 安装
1.克隆存储库
git clone https://github.com/yourusername/mcp-rag-chatbot.git
cd mcp-rag
2.后端设置
# Navigate to server directory
cd server
# Create virtual environment
python -m venv venv
# Activate virtual environment
source venv/bin/activate
# using uv:
uv pip install -r requirements.txt
3.前端设置
# Navigate to frontend directory
cd client/mcp_rag
# Install dependencies using pnpm
pnpm install
⚙️ 配置
1.后端环境变量
创建一个 .env 文件在 server/ 目录：
cd server
cp .env.example .env
编辑 server/.env 使用API密钥：
# Required API Keys
GOOGLE_API_KEY=your_google_ai_studio_api_key_here
GROQ_API_KEY=your_groq_api_key_here
PINECONE_API_KEY=your_pinecone_api_key_here
# Pinecone Configuration
PINECONE_INDEX_NAME=clinic-faqs
PINECONE_ENV=us-east-1
# Optional: Model Configuration (defaults shown)
# EMBEDDING_MODEL=models/embedding-001
# EMBEDDING_DIMENSION=768
# LLM_MODEL=llama-3.3-70b-versatile
# CHUNK_SIZE=500
# CHUNK_OVERLAP=100
2.前端环境变量（可选）
如果使用Clerk身份验证，请创建 client/mcp_rag/.env.local:
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=your_clerk_publishable_key
CLERK_SECRET_KEY=your_clerk_secret_key
🏃 运行应用程序
选项1：Flask应用程序（推荐-简单快速）
需要单个终端：
cd server
# Activate virtual environment if not already activated
source venv/bin/activate # macOS/Linux
# Start Flask application
python flask_app.py
预期产量：
* Serving Flask app 'flask_app'
* Debug mode: on
* Running on http://0.0.0.0:3000
申请可在以下网址获得： http://localhost:3000
选项2:Next.js+FastAPI（完整开发设置）
需要两个终端窗口：
终端1：启动后端服务器
cd server
# Activate virtual environment if not already activated
source venv/bin/activate # macOS/Linux
# Start FastAPI server
uvicorn main:app --reload
预期产量：
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO: Started reloader process
INFO: Started server process
INFO: Waiting for application startup.
INFO: Application startup complete.
后端将在以下网址提供： http://localhost:8000
终端2：启动前端服务器
cd client/mcp_rag
# Start Next.js development server
pnpm dev
预期产量：
▲ Next.js 15.2.4
- Local: http://localhost:3000
- Turbopack: enabled
✓ Ready in 2.5s
前端将在以下网址提供： http://localhost:3000
特征：
- ✅ 完整的Next.js开发经验
- ✅ 多对话管理
- ✅ 固定/取消固定对话
- ✅ 搜索功能
Flask应用程序（生产）
注： 生产Docker部署使用端口8080（而开发使用端口3000）。
🚀 CI/CD部署
使用GitHub Actions自动部署到AWS EC2。
快速CI/CD设置
先决条件：
- 具有ECR和EC2访问权限的AWS帐户
- EC2实例配置为GitHub自托管运行器
- 已配置GitHub存储库机密
工作流程：
- 将代码推送到
main或master分支（或手动触发） - GitHub Actions自动构建Flask Docker镜像
- 图片推送到亚马逊ECR
- 使用部署到EC2
docker run
访问已部署的应用程序：
http://YOUR_EC2_IP:8080
📁 项目结构
mcp-rag-chatbot/
├── server/ # Backend
│ ├── flask_app.py # 🚀 Flask application (PRODUCTION)
│ ├── main.py # FastAPI application (development only)
│ ├── config.py # Centralized configuration (Pydantic)
│ ├── logger.py # Logging configuration
│ ├── prompts.py # LLM prompt templates
│ ├── requirements.txt # Python dependencies
│ ├── .env.example # Environment variables template
│ │
│ ├── templates/ # Flask HTML templates
│ │ └── index.html # Chat interface UI
│ │
│ ├── static/ # Flask static files
│ │ └── chat.js # Chat JavaScript
│ │
│ ├── data/
│ │ └── clinic_faqs.json # FAQ knowledge base
│ │
│ ├── services/
│ │ ├── vectorstore_service.py # Pinecone vector store
│ │ └── llm_service.py # LLM service factory
│ │
│ ├── routes/ # FastAPI routes (development only)
│ │ ├── ask_question.py # POST /ask/ - RAG query endpoint
│ │ └── groq_stream.py # POST /groq_stream/ - Streaming endpoint
│ │
│ ├── modules/
│ │ ├── faq_loader.py # Load FAQs from JSON
│ │ ├── query_handlers.py # Query processing logic
│ │ └── load_vectorstore.py # Vector store initialization
│ │
│ ├── middlewares/ # FastAPI middleware (development only)
│ │ └── exception_handlers.py # Global exception handling
│ │
│ └── tests/
│ ├── test_rag_retrieval.py # RAG system tests
│ └── test_results.json # Test results
│
├── client/mcp_rag/ # Frontend (Next.js - development only)
│ ├── app/
│ │ ├── layout.tsx # Root layout with Clerk provider
│ │ ├── page.tsx # Home page
│ │ └── globals.css # Global styles
│ │
│ ├── components/
│ │ ├── AIAssistantUI.jsx # Main chat interface
│ │ ├── Sidebar.jsx # Conversation sidebar
│ │ ├── ChatPane.jsx # Chat message display
│ │ ├── Composer.jsx # Message input component
│ │ ├── Message.jsx # Individual message component
│ │ ├── ConversationRow.jsx # Sidebar conversation item
│ │ ├── Header.jsx # Chat header
│ │ ├── SearchModal.jsx # Search conversations
│ │ ├── SettingsPopover.jsx # Settings menu
│ │ └── ThemeToggle.jsx # Dark/light theme toggle
│ │
│ ├── lib/
│ │ └── api.ts # API client functions
│ │
│ ├── package.json # Node.js dependencies
│ └── next.config.ts # Next.js configuration
│
├── .github/
│ └── workflows/
│ └── deploy.yml # GitHub Actions CI/CD workflow
│
├── Dockerfile # Docker configuration for Flask app
├── .gitignore # Git ignore rules
└── README.md # This file
关键文件：
- 🚀
server/flask_app.py-生产Flask应用程序（已部署） - 📄
server/templates/index.html-聊天UI模板 - 📜
server/static/chat.js-客户端聊天逻辑 - 🐳
Dockerfile-Flask应用程序的单个容器 - ⚙️
.github/workflows/deploy.yml-CI/CD管道
🔌 API 文档
基本URL
Flask应用程序（生产）：
Local: http://localhost:3000
Production: http://YOUR_EC2_IP:8080
FastAPI（开发）：
http://localhost:8000
端点
Flask应用程序端点
得到/ -聊天界面
- 返回HTML聊天界面
- 通过浏览器访问
GET/健康 -健康检查
curl http://localhost:3000/health
POST/groq_stream -流媒体聊天
curl -X POST "http://localhost:3000/groq_stream" \
-F "question=Tell me about your services" \
-F "thread_id=my-conversation"
- 返回：服务器发送事件（SSE）流
- 参数：
question（必填）：用户提问thread_id（可选）：上下文的对话线程ID
FastAPI端点（仅限开发）
POST/ask -RAG查询
curl -X POST "http://localhost:8000/ask" \
-F "question=What are your hours?"
- 返回：带响应和源的JSON
POST/groq_stream -流媒体聊天
curl -X POST "http://localhost:8000/groq_stream" \
-F "question=Tell me about your services" \
-F "thread_id=my-conversation"
- 返回：服务器发送事件（SSE）流
📚 知识库
FAQ结构
知识库存储在 server/data/clinic_faqs.json 具有以下结构：
{
"faqs": [
{
"id": "faq_001",
"question": "What are your operating hours?",
"answer": "Our clinic is open Monday through Friday...",
"category": "General Information",
"tags": ["hours", "schedule", "availability"]
}
]
}
当前常见问题类别
- 一般信息 -时间、地点、联系方式
- 预约 -预订、预约、日程安排
- 账单和付款 -付款方式、融资
- 设施 -停车场、无障碍设施
- 治疗 -激光脱毛、肉毒杆菌毒素等。
- 安全和证书 -认证、安全
- 咨询 -免费咨询、评估
- 初次访问 -准备，带什么
- 政策 -取消、重新安排
嵌入策略
每个常见问题解答都作为一个完整的单元嵌入：
Question: {question}
Answer: {answer}
Category: {category}
这确保了：
- 每个块中的完整上下文
- 检索精度高
- 用户查询的相关答案
🐛 故障排除
常见问题
1.“找不到模块”错误
问题： 未安装Python依赖项
解决方案：
cd server
uv pip install -r requirements.txt
2.“找不到GOOGLE_API_KEY”
问题： 未设置环境变量
解决方案：
# Check if .env file exists
ls server/.env
# If not, create it from template
cp server/.env.example server/.env
# Edit with your API keys
nano server/.env
4.前端无法连接到后端
问题： CORS或后端未运行
解决方案：
# Check backend is running on port 8000
curl http://localhost:8000
# Check CORS settings in server/config.py
# Ensure http://localhost:3000 is in CORS_ORIGINS
5.“超出速率限制”错误
问题： 达到API利率限制
解决方案：
- 请等待几分钟，然后重试
- 在相应的仪表板中检查您的API配额
- 考虑升级到付费级别以获得更高的限额
6.对话没有持续
问题： 本地存储不工作
解决方案：
- 检查浏览器控制台是否有错误
- 清除浏览器缓存并重新加载
- 确保在浏览器设置中启用了localStorage
