# MAESS_FLOW **Repository Path**: memory00800528/maess_-flow ## Basic Information - **Project Name**: MAESS_FLOW - **Description**: 个人练习 - **Primary Language**: Python - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-11-07 - **Last Updated**: 2025-11-22 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # MAESS智能体系统 MAESS (Multi-Agent Expert System Suite) 是一个基于LangGraph的多智能体协同工作系统，集成了PostgreSQL数据持久化、LangSmith监控、Celery分布式任务队列、Circuit Breaker熔断机制和MCP爬虫实时搜索等核心功能。 ## 🚀 功能特性 ### 核心功能 - **多智能体协同**: 基于LangGraph的工作流引擎，支持智能体间的复杂协作 - **数据持久化**: PostgreSQL数据库，支持向量检索和全文搜索 - **实时监控**: LangSmith集成，提供完整的链路追踪和性能监控 - **分布式任务**: Celery任务队列，支持异步任务处理和负载均衡 - **熔断保护**: Circuit Breaker机制，防止系统雪崩 - **分布式锁**: Redis分布式锁，确保并发操作的安全性 - **智能搜索**: MCP爬虫和Whoosh全文检索引擎 ### 智能体类型 - **文档问答智能体**: 处理文档相关的问答任务 - **文本问答智能体**: 处理纯文本问答任务 - **多模态智能体**: 处理图像、文本等多模态数据 - **文档分段智能体**: 文档内容分段和处理 - **工具调用智能体**: 外部工具调用和管理 - **编排器智能体**: 任务编排和协调 ## 🏗️ 系统架构 ``` ┌─────────────────────────────────────────────────────────────┐ │ MAESS智能体系统 │ ├─────────────────────────────────────────────────────────────┤ │ API层 (FastAPI) │ │ ├── 健康检查: /health │ │ ├── 系统指标: /metrics │ │ ├── 监控面板: /monitor/* │ │ ├── 工作流: /workflow/* │ │ └── 任务管理: /task/* │ ├─────────────────────────────────────────────────────────────┤ │ 智能体层 │ │ ├── 编排器智能体 (OrchestratorAgent) │ │ ├── 文档问答智能体 (DocQAAgent) │ │ ├── 文本问答智能体 (TextQAAgent) │ │ ├── 多模态智能体 (MultiModalAgent) │ │ ├── 文档分段智能体 (DocSegmentAgent) │ │ └── 工具调用智能体 (ToolCallAgent) │ ├─────────────────────────────────────────────────────────────┤ │ 核心组件层 │ │ ├── LangGraph工作流引擎 │ │ ├── LangSmith监控和链路追踪 │ │ ├── Celery分布式任务队列 │ │ ├── PostgreSQL数据持久化 │ │ ├── Circuit Breaker熔断机制 │ │ ├── 分布式锁管理器 │ │ └── MCP爬虫搜索引擎 │ ├─────────────────────────────────────────────────────────────┤ │ 基础设施层 │ │ ├── Redis (缓存和消息队列) │ │ ├── PostgreSQL (主数据库) │ │ ├── Elasticsearch (搜索引擎) │ │ ├── Prometheus (监控) │ │ ├── Grafana (可视化) │ │ ├── Jaeger (链路追踪) │ │ └── Nginx (负载均衡) │ └─────────────────────────────────────────────────────────────┘ ``` ## 📦 快速开始 ### 环境要求 - Python 3.11+ - Docker 和 Docker Compose - PostgreSQL 14+ - Redis 6+ ### 安装依赖 ```bash pip install -r requirements.txt ``` ### 配置环境变量 ```bash cp .env.example .env # 编辑 .env 文件，配置数据库、Redis等连接信息 ``` ### 数据库初始化 ```bash python scripts/init_database.py ``` ### 启动服务 ```bash # 开发模式 python main.py # 或使用Docker Compose docker-compose -f deploy/docker-compose.yml up -d ``` ### 验证安装 ```bash curl http://localhost:8000/health ``` ## 📊 监控面板 ### 系统监控 - **健康检查**: `http://localhost:8000/health` - **系统指标**: `http://localhost:8000/metrics` - **监控面板**: `http://localhost:8000/monitor/system` ### 外部监控 - **Prometheus**: `http://localhost:9090` - **Grafana**: `http://localhost:3000` - **Jaeger**: `http://localhost:16686` ## 🔍 API文档 ### 交互式文档 - **Swagger UI**: `http://localhost:8000/docs` - **ReDoc**: `http://localhost:8000/redoc` ### 主要API端点 #### 健康检查 ```http GET /health ``` #### 系统指标 ```http GET /metrics ``` #### 工作流执行 ```http POST /workflow/execute Content-Type: application/json { "workflow_type": "doc_qa", "input_data": { "question": "文档内容相关问题", "document_id": "doc_123" } } ``` #### 任务提交 ```http POST /task/submit Content-Type: application/json { "task_type": "text_processing", "priority": "high", "data": { "text": "需要处理的文本内容" } } ``` ## 🐳 Docker部署 ### 启动命令 ```bash docker-compose -f deploy/docker-compose.yml up -d ``` ## 🔧 开发指南 ### 项目结构 ``` maess_-flow/ ├── main.py # 主应用入口 ├── requirements.txt # Python依赖 ├── deploy/ # 部署配置 │ ├── docker-compose.yml # Docker Compose配置 │ ├── Dockerfile # 应用容器镜像 │ ├── nginx.conf # Nginx配置 │ ├── redis.conf # Redis配置 │ └── supervisord.conf # 进程管理配置 ├── states/ # 核心状态管理 │ ├── database_manager.py # 数据库管理器 │ ├── langsmith_monitor.py # LangSmith监控 │ ├── langgraph_workflow.py # 工作流引擎 │ ├── celery_manager.py # Celery管理器 │ └── circuit_breaker_manager.py # 熔断器管理 ├── apps/ # 应用模块 │ ├── monitor/ # 监控智能体 │ └── agents/ # 智能体实现 ├── utils/ # 工具模块 │ ├── logger.py # 日志配置 │ ├── config.py # 配置管理 │ └── exceptions.py # 异常定义 └── tests/ # 测试模块 ``` ### 添加新的智能体 1. 在 `apps/agents/` 目录下创建新的智能体文件 2. 继承基础智能体类并实现必要方法 3. 在 `main.py` 中注册智能体 4. 添加相应的API端点 ## 📈 性能优化 ### 数据库优化 - 使用连接池管理数据库连接 - 为常用查询添加索引 - 使用向量检索优化相似性搜索 ### 缓存策略 - Redis缓存热点数据 - 智能体结果缓存 - 查询结果缓存 ### 异步处理 - 使用Celery处理耗时任务 - 异步API响应 - 并发智能体执行 ## 🔒 安全配置 ### 认证授权 - JWT Token认证 - API Key管理 - 角色权限控制 ### 数据安全 - 数据库连接加密 - 敏感数据脱敏 - 审计日志记录 ### 网络安全 - API限流 - CORS配置 - HTTPS支持 ## 🐛 故障排查 ### 日志查看 ```bash # 查看应用日志 tail -f logs/app.log # 查看Celery日志 tail -f logs/celery.log # 查看系统日志 journalctl -u maess -f ``` ### 常见问题 #### 数据库连接失败 - 检查数据库服务状态 - 验证连接配置 - 检查网络连通性 #### Redis连接失败 - 检查Redis服务状态 - 验证连接配置 - 检查内存使用情况 #### Celery任务失败 - 检查Worker状态 - 查看任务日志 - 验证任务参数 ## 🤝 贡献指南 ### 开发流程 1. Fork项目仓库 2. 创建特性分支 3. 提交代码更改 4. 创建Pull Request ### 代码规范 - 遵循PEP 8编码规范 - 添加类型注解 - 编写单元测试 - 更新文档 ### 测试 ```bash # 运行单元测试 pytest tests/ # 运行集成测试 pytest tests/integration/ # 代码覆盖率 pytest --cov=maess tests/ ``` ## 📄 许可证 本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。 ## 🆘 支持 如有问题或建议，请提交 Issue 或联系维护团队。 --- **MAESS智能体系统** - 让多智能体协同工作更简单！