使用说明

🏥 临床试验RAG评估系统

一个全面的RAG（Retrieval-AugedGeneration）评估系统，具有实时指标、文档聊天、AI驱动的反馈系统和使用Google Gemini API的代理RAG功能。

📋 目录

特性
快速开始
部署（免费云）
MCP服务器（代理RAG）
反馈系统
Gmail电子邮件设置
技术栈
故障排除

特性

核心功能

🤖 谷歌双子座2.0 Flash Lite：最新的Gemini型号，可实现快速、准确的响应
📊 实时评估：定制RAG指标，进行全面分析
📄 文档处理：上传PDF文档并与之聊天
🧭 多页导航：单独的聊天、日志和设置部分
📈 性能分析：随着时间的推移跟踪和比较评估指标
🎯 Top-K优化：查找最佳检索参数
💬 聊天记忆：维护对话历史和上下文
📚 来源参考：显示用于答案的文档块

🚀 高级功能

🤖 带MCP服务器的代理RAG：使用6个临床试验工具进行AI驱动的查询增强
- 验证医疗查询
- 提取临床实体（药物、条件、试验阶段）
- 增强查询以实现更好的搜索
- 检查文档相关性
- 验证答案的准确性
⚡ 代币高效提示：智能提示优化，可将令牌使用量减少高达50%
🧠 LangChain内存集成：具有文档特定历史记录的持久对话记忆
📊 令牌使用分析：跟踪优化节省和效率指标
💬 反馈系统：使用电子邮件通知的人工智能情绪分析
🎛️ 功能切换控件：独立启用/禁用高级功能

快速开始

选项1：基本RAG（无MCP服务器）

# 1. Install dependencies
pip install -r requirements.txt

# 2. Run the application
streamlit run app.py

# 3. Configure in UI
# - Enter your Gemini API key in the sidebar
# - Upload PDF documents
# - Start chatting!

选项2：使用代理RAG（MCP服务器）

# Terminal 1 - Start MCP Server
python mcp_server.py

# Terminal 2 - Start Streamlit App
streamlit run app.py

# Then in the Streamlit UI:
# 1. Enter your Gemini API key in the sidebar
# 2. Enable "Agentic RAG with MCP Server" in sidebar
# 3. Go to Settings page and click "Configure API"
# 4. Upload PDF documents
# 5. Start chatting with AI-enhanced query processing!

获取Gemini API密钥

首选谷歌人工智能工作室
创建新的API密钥
在应用程序的侧边栏中输入

部署（免费云）

推荐：Streamlit Cloud⭐

为什么？ 永久免费，零配置，非常适合Streamlit应用程序，GitHub自动更新。

限制： MCP服务器无法工作（需要多个进程），但所有核心RAG功能都能完美工作。

快速部署步骤：

1.创建 .streamlit/config.toml:

[theme]
primaryColor = "#667eea"
backgroundColor = "#0f172a"
secondaryBackgroundColor = "#1e293b"
textColor = "#e2e8f0"

[server]
headless = true
port = 8501
enableCORS = false

[browser]
gatherUsageStats = false

2.创建 .gitignore:

__pycache__/
*.pyc
.streamlit/secrets.toml
*.pdf
*.csv
evaluation_logs/
uploaded_documents/
vector_db/
.vscode/
.DS_Store

3.推送到GitHub：

git init
git add .
git commit -m "Deploy Clinical Trials RAG"
git remote add origin https://github.com/YOUR_USERNAME/clinical-trials-rag.git
git push -u origin main

4.部署：

首选 https://share.streamlit.io
点击 “新应用程序”
连接GitHub
选择您的仓库
主文件： app.py
点击 “部署”

完成！您的应用程序将在以下网址上线： https://YOUR_USERNAME-clinical-trials-rag.streamlit.app

备选方案

拥抱面部空间：

免费无限公共空间
更好的资源（2个vCPU，16GB存储空间）
在huggingface.co/space上创建空间
选择Streamlit SDK
推送你的代码

铁路（如果您需要MCP服务器）：

$5学分/月（~500小时）
可以运行多个进程（MCP服务器工作！）
从GitHub部署到railway.app
创建 Procfile: web: streamlit run app.py --server.port $PORT

什么在自由层有效

✅ 核心RAG功能 ✅ 文件上传和处理 ✅ 带记忆的聊天界面 ✅ 评估指标 ✅ 带有情感分析的反馈系统 ✅ 邮件通知 ✅ 所有UI功能 ✅ 令牌优化 ✅ LangChain内存

❌ MCP服务器（仅适用于铁路或付费层）

MCP服务器（代理RAG）

什么是MCP？

模型上下文协议（MCP） 通过专门的人工智能工具赋予您的RAG系统“超能力”。把它想象成一个人工智能助手，帮助智能地处理查询。

6 MCP工具

工具	目的	功能
`configure_gemini_api`	设置	配置服务器上的Gemini API密钥
`validate_medical_query`	验证	检查查询是否为医疗/临床
`enhance_clinical_query`	增强	改进查询以获得更好的搜索
`extract_clinical_entities`	提取	查找药物、条件、试验阶段
`check_clinical_relevance`	筛选	评估文档块相关性
`validate_clinical_answer`	验证	验证答案的准确性

运作原理

无代理RAG（基础）：

User Query → Vector Search → Retrieve Chunks → Generate Response

使用代理RAG（增强型）：

User Query: "What are aspirin side effects?"
    ↓
Extract Entities: {drug: "aspirin", adverse_events: "side effects"}
    ↓
Enhance Query: "What are the documented adverse events, safety profile,
                and contraindications of aspirin in Phase II/III trials?"
    ↓
Vector Search (with enhanced query)
    ↓
Check Relevance: Filter chunks (keep 0.92, 0.88; remove 0.45)
    ↓
Generate Response (with better context)
    ↓
Validate Answer: 95% confidence, strong evidence
    ↓
Result: Precise, clinically-relevant response

建筑

Streamlit App (app.py)
    ↓ HTTP/SSE
MCP Client (mcp_client.py)
    ↓ Tool calls
MCP Server (mcp_server.py) - Port 8050
    ↓ AI processing
Gemini API

快速命令

# Start MCP Server (Terminal 1)
python mcp_server.py

# Start Streamlit (Terminal 2)
streamlit run app.py

# In UI: Enable "Agentic RAG with MCP Server"
# In Settings: Click "Configure API"

MCP故障排除

服务器未启动：

# Check if port 8050 is in use
netstat -ano | findstr :8050

# Kill process if needed
taskkill /PID <process_id> /F

连接失败：

确保MCP服务器首先运行
检查服务器URL: http://localhost:8050/sse
验证没有防火墙阻止端口8050

工具不工作：

在侧栏中输入API键
启用代理RAG
转到“设置”→ 点击“配置API”
检查服务器日志以确认

反馈系统

特性

人工智能驱动的情感分析：使用Gemini分析反馈
电子邮件通知：向利益相关者发送精美的HTML电子邮件
分析：跟踪情绪分布和评级
出口：下载JSON格式的反馈数据

设置

1.启用反馈系统：

转到设置页面
勾选“启用反馈收集”
系统自动初始化

2.配置电子邮件（可选）：

设置收件人电子邮件和姓名
展开“SMTP配置”
填写SMTP详细信息（请参阅下面的Gmail设置）
点击“保存SMTP配置”

使用反馈

对于用户：

在聊天中提问
查看回复
展开“对此响应提供反馈”
填写反馈文本和评分（1-5颗星）
点击“提交反馈”
立即查看情绪分析结果

您将获得：

情绪：阳性/阴性/中性/混合
自信: 0.0-1.0
情感：满意、沮丧、困惑等。
满意度得分: 1-5
要点：主要反馈点
提及的问题：发现的问题
建议：用户建议
紧迫性：低/中/高
类别：准确性/相关性/完整性/可用性

电子邮件格式

电子邮件包括：

情绪徽章（颜色编码）
紧急程度和优先级
完整的用户交互（查询、响应、反馈）
情绪分析详情
可操作的见解

Gmail电子邮件设置

问题

如果您看到此错误：

❌ Email failed: (535, b'5.7.8 Username and Password not accepted')

Gmail需要 应用程序密码 而不是您的常规密码。

解决方案（3个步骤）

1.获取Gmail应用程序密码：

首选https://myaccount.google.com/apppasswords
如果需要，请先启用双因素身份验证
生成应用程序密码
复制16个字符的密码（例如。， abcd efgh ijkl mnop)

2.在应用程序中配置SMTP：

📧 SMTP Configuration
├── SMTP Server: smtp.gmail.com
├── SMTP Port: 587
├── Username/Email: your.email@gmail.com
├── Password: abcdefghijklmnop  ← App Password (remove spaces)
├── ✅ Use TLS
└── From Email: your.email@gmail.com

3.保存和测试：

点击“保存SMTP配置”
提交反馈以测试电子邮件传递

其他电子邮件提供商

Outlook/Hotmail：

服务器： smtp-mail.outlook.com
端口：587
使用TLS：是

雅虎邮箱：

服务器： smtp.mail.yahoo.com
端口：587
使用TLS：是

技术栈

LLM：谷歌双子座2.0 Flash Lite
评估：定制RAG评估系统（从头开始构建）
嵌入：句子转换器/全MiniLM-L6-v2（384尺寸）
矢量数据库：FAISS（脸书人工智能相似性搜索）
框架：使用自定义CSS流式显示
文档处理：PyPDF2
MCP服务器：FastMCP用于代理RAG工具
记忆：LangChain用于对话历史记录
ML库：scikit-learn用于相似性计算
反馈：使用电子邮件通知的人工智能情绪分析

项目结构

├── app.py                    # Main Streamlit application
├── document_processor.py     # PDF processing and text extraction
├── embedding_generator.py    # Embedding generation utilities
├── vector_database.py        # FAISS vector database operations
├── custom_evaluator.py       # Custom RAG evaluation metrics
├── evaluation_fallback.py    # Fallback evaluation system
├── rate_limiter.py           # API rate limiting
│
├── Advanced Features
├── mcp_server.py             # FastMCP server with 6 clinical trial tools
├── mcp_client.py             # MCP client for server communication
├── prompt_optimizer.py       # Token-efficient prompt construction
├── memory_integration.py     # LangChain memory integration
├── token_counter.py          # Token counting and optimization utilities
├── feedback_system.py        # Feedback collection with sentiment analysis
│
├── Testing
├── test_integration.py       # Integration tests for all features
├── test_memory_history.py    # Memory feature tests
├── test_feedback_system.py   # Feedback system tests
│
└── requirements.txt          # Python dependencies

评估指标

我们定制的评估系统提供全面的RAG评估：

答案相关性：结合语义相似性和LLM判断
忠诚：根据上下文提取和核实事实主张
上下文相关性：评估检索到的块与查询的匹配程度
情境回忆：通过与预期答案进行比较来衡量完整性

评估方法

语义分析：用于嵌入相似性的句子变换器
法学硕士评判：Gemini API进行细致评估
回退方法：关键词重叠和可靠性统计指标

故障排除

常见问题

API过载（503个错误）：

等待2-3分钟，然后重试
使用更少的评估指标
在非高峰时段尝试

无效的API密钥（400个错误）：

验证侧边栏中的密钥是否正确
确保密钥具有适当的权限

速率限制（429个错误）：

内置的速率限制应该可以防止这种情况
在发出更多请求之前等待

内存不足（云部署）：

将MAX_CHUNKS减少到500
将文件大小限制为10MB
更频繁地清除缓存

电子邮件未发送：

对于Gmail：使用应用程序密码，而不是常规密码
检查SMTP配置是否已保存
验证收件人电子邮件是否已设置
检查防火墙是否允许SMTP连接

MCP服务器问题：

在Streamlit应用程序之前启动服务器
检查端口8050是否未使用
验证服务器上是否配置了API密钥
查看服务器日志中的错误

性能提示

从较少的评估指标开始测试系统
使用3-7之间的Top-K值以获得最佳性能
最初上传较小的文档以测试功能
监控评估日志页面以获取性能见解
仅启用所需的高级功能

配置

API密钥：在侧栏中输入Gemini API键
文件上传：上传PDF进行分析
评估设置：启用/禁用指标并设置阈值
Top-K设置：调整检索到的块数（1-20）
高级功能：切换MCP、内存、令牌优化
反馈系统：配置电子邮件通知和收件人

导航系统

💬 聊天和评估

带有文档问答的交互式聊天界面
实时评估指标
来源归因和块分析
可配置的Top-K检索设置
反馈收集

📊 评估日志

全面的性能分析
具有趋势的历史评估数据
Top-K性能比较
CSV导出功能
业绩建议

⚙️ 设置

系统配置概述
数据管理（清除历史记录、日志、文档）
API状态监测
反馈系统配置
系统信息和统计

安全与隐私

API密钥：仅存储在会话状态中（不持久）
反馈数据：存储在内存中（基于会话）
电子邮件：使用TLS加密，建议使用应用程序密码
文件：在本地处理，不发送到外部服务
用户数据：可选电子邮件收集，注重隐私的设计

许可证

麻省理工学院许可证-随意使用和修改您的项目！

支持

问题：在GitHub上打开一个问题
问题：检查故障排除部分
贡献：欢迎拉取请求！

内置❤️ 用于临床试验研究和RAG评估