使用说明
MCP+RAG+AI代理架构
在谷歌云平台上结合模型上下文协议、检索增强生成和人工智能代理的生产级实现
🎯 这是什么？
该项目提供了 完整的、企业就绪的实施 现代人工智能系统结合了：
- 🔌 MCP（模型上下文协议）：LLM的标准化工具访问
- 📚 RAG（检索增强生成）：知识增强的人工智能响应
- 🤖 AI代理：使用Gemini进行自主任务编排
全部部署在 谷歌云平台 遵循安全性、可扩展性和可观察性的最佳实践。
✨ 主要特点
- ✅ 生产就绪：企业级架构
- ✅ 经过全面测试：全面的测试覆盖率
- ✅ 有据可查的：详细的指南和图表
- ✅ GCP最佳实践：安全性、可扩展性、可观察性
- ✅ 现代堆栈：最新技术和框架
- ✅ 可扩展：易于添加新工具和功能
- ✅ 成本优化：无服务器、按使用付费模式
- ✅ DevOps就绪：GitHub操作、云构建、IaC，包括监控
🚀 快速开始
1.验证项目结构
./validate_structure.sh
这确保了所有必需的文件都已就绪。
2.地方发展
# Set up environment
cp .env.example .env
# Edit .env with your GCP project details
# Start all services
./quickstart.sh
# Access the application
# Web App: http://localhost:3000
# Agent Service: http://localhost:8000
# MCP Server: http://localhost:8080
3.运行测试
# Unit tests
./run_tests.sh
# Integration tests
./test_integration.sh
4.部署到GCP
# Option 1: Cloud Build (Recommended)
gcloud builds submit --config cloudbuild.yaml .
# Option 2: Terraform
cd infrastructure
terraform init
terraform apply
📁 项目结构
mcp-rag-ai-agent/
├── src/
│ ├── agent-service/ # AI Agent orchestrator (FastAPI + Gemini)
│ ├── mcp-server/ # MCP tool server (FastAPI)
│ ├── rag-pipeline/ # RAG ingestion pipeline (Vertex AI)
│ └── web-app/ # Next.js frontend
├── infrastructure/ # Terraform IaC for GCP
│ ├── modules/
│ │ ├── networking/ # VPC, subnets, connectors
│ │ ├── compute/ # Cloud Run services
│ │ └── ai-platform/ # Vertex AI setup
│ ├── main.tf
│ ├── variables.tf
│ └── outputs.tf
├── docs/
│ ├── ARCHITECTURE.md # System architecture details
│ ├── DEPLOYMENT.md # Deployment guide
│ ├── TESTING.md # Testing guide
│ └── DIAGRAMS.md # Visual diagrams
├── docker-compose.yml # Local development
├── cloudbuild.yaml # CI/CD pipeline
├── quickstart.sh # Quick start script
├── run_tests.sh # Test runner
├── test_integration.sh # Integration tests
└── validate_structure.sh # Structure validator
🏗️ 架构概述
┌─────────────────────────────────────────────────────────────────┐
│ User Interface │
│ (Next.js Web App) │
└────────────────────────┬────────────────────────────────────────┘
│ HTTPS
▼
┌─────────────────────────────────────────────────────────────────┐
│ AI Agent Service │
│ (FastAPI + Gemini) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Query │ │ RAG │ │ MCP │ │
│ │ Processor │ │ Retrieval │ │ Client │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└───────┬────────────────────┬────────────────────┬──────────────┘
│ │ │
▼ ▼ ▼
┌──────────────┐ ┌──────────────────┐ ┌──────────────┐
│ Gemini │ │ Vertex AI │ │ MCP Server │
│ 3.0 Pro │ │ Vector Search │ │ (Tools) │
└──────────────┘ └──────────────────┘ └──────────────┘
看 文档/图表.md 查看详细的可视化图表。
🛠️ 技术栈
| 组件 | 技术 | 目的 |
|---|---|---|
| LLM | Gemini 3.0 Pro | 推理与生成 |
| 向量数据库 | 顶点AI矢量搜索 | 语义搜索 |
| 嵌入 | textembedding-gecko@003 | 文档编码 |
| 代理框架 | FastAPI+顶点AI SDK | 编排 |
| 主控程序 | FastAPI | 工具协议 |
| 前端 | Next.js 14+TypeScript | 用户界面 |
| 基础设施 | 地形 | IaC |
| CI/CD | GitHub操作/云构建 | 自动化 |
| 计算 | 云运行 | 无服务器 |
| 存储 | 云存储 | 文档 |
| 网络 | VPC+连接器 | 安全 |
📚 文档
- 建筑.md：详细的系统架构和设计决策
- 部署.md：分步部署指南
- 测试.md：测试策略和示例
- 图表.md：可视化架构图
- 项目_ SUMMARY.md：完整的项目总结
🧪 测试
单元测试
./run_tests.sh
测试单个组件：
- MCP服务器端点
- 代理服务逻辑
- 工具执行
- 请求/响应验证
集成测试
./test_integration.sh
测试整个系统：
- 服务通信
- 端到端工作流
- Docker编写设置
手动测试
# Test MCP Server
curl http://localhost:8080/mcp/list_tools
# Test Agent Service
curl -X POST http://localhost:8000/agent/chat \
-H "Content-Type: application/json" \
-d '{"query": "What tools are available?"}'
🔐 安全
- VPC隔离：服务专用网络
- 身份和访问管理：最低权限服务帐户
- 秘密经理：安全的凭据存储
- 加密：休息和过境
- 审计日志：完整的审计跟踪
- 云甲：DDoS和WAF保护
📈 可扩展性
- 云运行：自动从0扩展到N个实例
- 向量搜索：处理数百万个嵌入
- 无状态设计：已启用水平缩放
- 多区域：跨区域部署
- 内容分发网络：用于静态资产的云CDN
💰 成本优化
- 缩放到零：Cloud Run仅对活动请求收费
- 高效嵌入：批量处理
- 资源限制：防止成本失控
- 区域部署：降低出口费用
🎓 了解更多
了解组件
GCP资源
🤝 贡献
- 遵循现有的代码结构
- 为新功能添加测试
- 更新文档
- 提交前运行测试
- 使用常规提交
📝 许可证
MIT许可证-有关详细信息，请参阅许可证文件
🙋 支持
内置于❤️ 使用GCP最佳实践
