README.md

---
title: Template Final Assignment
emoji: 🕵🏻‍♂️
colorFrom: indigo
colorTo: indigo
sdk: gradio
sdk_version: 5.25.2
app_file: app.py
pinned: false
hf_oauth: true
# optional, default duration is 8 hours/480 minutes. Max duration is 30 days/43200 minutes.
hf_oauth_expiration_minutes: 480
---

# 多模态智能体系统 (Multi-Modal Agent System)

一个基于Hugging Face和LangGraph的智能多模态智能体系统，能够理解视频、图片，并使用搜索引擎回答问题。

## 🚀 功能特性

### 🎥 视频理解与分析
- **关键帧提取**: 自动提取视频关键帧进行分析
- **视频描述**: 生成视频内容的自然语言描述
- **音频分析**: 分析视频的音频信息
- **时长统计**: 获取视频的基本信息（时长、帧率、分辨率等）

### 🖼️ 图像识别与描述
- **图像描述**: 使用BLIP模型生成图像的自然语言描述
- **对象检测**: 检测图像中的物体和位置
- **图像分类**: 对图像进行分类识别
- **OCR文本提取**: 从图像中提取文字内容
- **情感分析**: 分析图像中的情感元素

### 📄 PDF文档处理
- **PDF下载**: 从URL下载PDF文档
- **文本提取**: 从PDF中提取文本内容
- **结构分析**: 分析PDF文档结构和元数据
- **内容搜索**: 在PDF中搜索特定文本
- **图像提取**: 从PDF中提取图像
- **内容总结**: 自动总结PDF文档内容

### 🌐 网页内容分析
- **网页抓取**: 获取网页内容和结构
- **文本提取**: 从网页中提取纯文本内容
- **结构分析**: 分析网页的标题、表单、表格等结构
- **内容搜索**: 在网页中搜索特定文本
- **链接提取**: 提取网页中的所有链接
- **内容总结**: 自动总结网页内容
- **可访问性检查**: 检查网页的可访问性问题

### 📺 YouTube视频处理
- **视频信息获取**: 获取YouTube视频的标题、作者、时长、观看次数等
- **视频下载**: 下载YouTube视频到本地
- **音频提取**: 从YouTube视频中提取音频
- **缩略图下载**: 下载YouTube视频缩略图
- **视频搜索**: 搜索YouTube视频
- **评论分析**: 分析YouTube视频评论
- **播放列表处理**: 获取播放列表信息和视频列表

### 📚 Wikipedia百科处理
- **页面搜索**: 搜索Wikipedia页面
- **内容获取**: 获取Wikipedia页面完整内容
- **摘要提取**: 获取页面摘要信息
- **分类获取**: 获取页面分类信息
- **链接提取**: 获取页面相关链接
- **搜索建议**: 获取搜索建议
- **英文版本**: 支持英文Wikipedia搜索
- **随机页面**: 获取随机Wikipedia页面
- **地理搜索**: 根据坐标搜索附近页面

### 🔍 智能搜索引擎
- **网络搜索**: 使用DuckDuckGo进行实时网络搜索
- **图像搜索**: 搜索相关图像资源
- **视频搜索**: 搜索相关视频内容
- **智能查询**: 根据问题自动构建搜索查询

### 🤖 LangGraph工作流编排
- **状态管理**: 使用AgentState管理智能体状态
- **工作流节点**: 媒体分类 → 媒体分析 → 信息搜索 → 工具使用 → 答案合成
- **智能路由**: 根据问题类型自动选择合适的处理路径

### 🛠️ 丰富工具集
- **文本分析**: 情感分析、关键词提取、文本摘要
- **翻译工具**: 多语言文本翻译
- **数学计算**: 安全的数学表达式计算
- **天气查询**: 实时天气信息获取

## 📋 系统架构

```
用户问题 → 媒体分类 → 媒体分析 → 信息搜索 → 工具使用 → 答案合成 → 最终答案
    ↓         ↓         ↓         ↓         ↓         ↓
  文本/图片/视频/PDF/网页/YouTube/Wikipedia  图像/视频/PDF/网页/YouTube/Wikipedia处理  网络搜索  专用工具  信息整合  自然语言回答
```

## 🛠️ 安装与配置

### 1. 环境要求
- Python 3.8+
- CUDA支持（可选，用于GPU加速）

### 2. 安装依赖
```bash
pip install -r requirements.txt
```

### 3. 环境变量配置
创建 `.env` 文件并配置以下变量：
```env
# OpenAI API配置
OPENAI_API_KEY=your_openai_api_key_here

# Hugging Face配置（可选）
HUGGINGFACE_API_KEY=your_huggingface_api_key_here

# 搜索引擎配置（可选）
SERPER_API_KEY=your_serper_api_key_here

# 调试配置
DEBUG=True
LOG_LEVEL=INFO
```

### 4. 运行系统
```bash
python app.py
```

## 🎯 使用示例

### 基本使用
```python
from app import MultiModalAgent

# 初始化智能体
agent = MultiModalAgent()

# 文本问题
answer = agent("什么是人工智能？")

# 图像问题
answer = agent("这张图片里有什么？", "https://example.com/image.jpg")

# 视频问题
answer = agent("这个视频在讲什么？", "https://youtube.com/watch?v=example")

# 网页问题
answer = agent("这个网页的主要内容是什么？", "https://example.com")

# YouTube问题
answer = agent("这个YouTube视频的信息是什么？", "https://www.youtube.com/watch?v=example")

# Wikipedia问题
answer = agent("Wikipedia关于人工智能的信息是什么？")
```

### 高级功能
```python
# 情感分析
answer = agent("分析这段文字的情感", "这是一段需要分析的文本")

# 关键词提取
answer = agent("提取这段文字的关键词", "这是一段需要提取关键词的文本")

# 文本摘要
answer = agent("总结这段文字", "这是一段很长的文字需要总结...")
```

## 📊 支持的模型

### 图像处理模型
- **BLIP**: Salesforce/blip-image-captioning-base
- **ResNet**: microsoft/resnet-50
- **DETR**: facebook/detr-resnet-50
- **GIT**: microsoft/git-base

### 文本处理模型
- **情感分析**: cardiffnlp/twitter-roberta-base-sentiment-latest
- **命名实体识别**: dbmdz/bert-large-cased-finetuned-conll03-english
- **文本摘要**: facebook/bart-large-cnn
- **翻译**: Helsinki-NLP/opus-mt-en-zh

### 视频处理
- **MoviePy**: 视频编辑和处理
- **OpenCV**: 计算机视觉处理
- **PyTube**: YouTube视频下载

## 🔧 自定义扩展

### 添加新工具
```python
from tools import ToolManager

class CustomTools:
    @staticmethod
    @tool
    def custom_function(input_text: str) -> str:
        """自定义工具函数"""
        # 实现你的逻辑
        return "处理结果"

# 注册工具
tool_manager = ToolManager()
tool_manager.tools["custom_function"] = CustomTools.custom_function
```

### 修改工作流
```python
def _build_workflow(self) -> StateGraph:
    workflow = StateGraph(AgentState)
    
    # 添加自定义节点
    workflow.add_node("custom_node", self._custom_processing)
    
    # 修改工作流路径
    workflow.add_edge("analyze_media", "custom_node")
    workflow.add_edge("custom_node", "search_info")
    
    return workflow.compile()
```

## 📈 性能优化

### GPU加速
系统会自动检测CUDA可用性并使用GPU加速：
```python
device = 0 if torch.cuda.is_available() else -1
```

### 缓存机制
- 模型缓存：自动缓存下载的模型
- 结果缓存：缓存分析结果避免重复计算

### 内存优化
- 图像尺寸限制：自动调整大图像尺寸
- 视频帧采样：智能选择关键帧进行分析

## 🐛 故障排除

### 常见问题

1. **OpenAI API错误**
   - 检查API密钥是否正确
   - 确认账户余额充足

2. **模型下载失败**
   - 检查网络连接
   - 尝试使用镜像源

3. **内存不足**
   - 减少批处理大小
   - 使用CPU模式运行

4. **视频处理失败**
   - 检查视频格式是否支持
   - 确认视频文件完整性

### 调试模式
设置环境变量启用调试模式：
```env
DEBUG=True
LOG_LEVEL=DEBUG
```

## 🤝 贡献指南

欢迎提交Issue和Pull Request来改进这个项目！

### 开发环境设置
1. Fork项目
2. 创建功能分支
3. 提交更改
4. 创建Pull Request

## 📄 许可证

本项目采用MIT许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 🙏 致谢

- [Hugging Face](https://huggingface.co/) - 提供优秀的预训练模型
- [LangGraph](https://github.com/langchain-ai/langgraph) - 工作流编排框架
- [LangChain](https://langchain.com/) - LLM应用开发框架
- [Gradio](https://gradio.app/) - 快速构建Web界面

---

**注意**: 这是一个教育项目，请确保遵守相关API的使用条款和隐私政策。