AI导哈

图像研究助手

一个结合视觉分析和维基百科搜索功能的智能研究助手，能够识别上传的图像并提供详细的维基百科研究结果。

  • by aruc-dev
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 aruc-dev/Image-research-assistant

使用说明

图像研究助理

一款智能研究助手，结合视觉分析和维基百科搜索功能，回答有关图像的问题。上传地标、艺术品或任何物体的图像，助手将识别它并提供维基百科的详细研究。

特性

  • 视觉分析：使用Google Gemini 2.0 Flash进行深度图像分析，以识别地标、艺术品和物体
  • 智能研究：基于图像内容的维基百科自动搜索
  • 流线型工具管道：优化单步图像分析，实现快速可靠的结果
  • web界面：干净的Gradio web UI，便于交互
  • 多工具架构：基于模型上下文协议（MCP）构建，用于模块化、可扩展的工具集成
  • 稳健的错误处理：妥善处理边缘情况和格式错误的请求

运作原理

  1. 上传图片 并问一个问题（例如，“这个地标是什么，告诉我它的历史？”）
  2. AI代理 分析图像 确定它包含什么
  3. 它自动 搜索维基百科 使用已识别的内容
  4. 你收到一个 全面的回答 视觉理解与研究相结合

先决条件

  • Python 3.11+（推荐使用：Python 3.11.14）
  • Gemini模型的Google API密钥(在这里买一个)

安装

  1. 克隆存储库：
git clone <repository-url>
cd Image-research-assistant
  1. 创建并激活Python虚拟环境：
# Create virtual environment with Python 3.11
python3.11 -m venv venv

# Or use your default Python if it's 3.11+
python -m venv venv

# Activate virtual environment (macOS/Linux)
source venv/bin/activate

# Or on Windows
# venv\Scripts\activate
  1. 安装所需的依赖项：
pip install -r requirements.txt
  1. 设置环境变量： 创建一个 .env 项目根目录中的文件：
# Google Gemini Configuration
GOOGLE_API_KEY=your-actual-google-api-key-here
GEMINI_MODEL=gemini-2.0-flash

从获取您的Google API密钥 谷歌AI工作室.

用法

启动web界面：

# Activate virtual environment
source venv/bin/activate

# Launch web interface
python mcp_client.py

Gradio界面将于 http://localhost:7860。在浏览器中打开此URL以开始使用助手。

查询示例

  • 上传一张埃菲尔铁塔的图片，然后问：“这是什么，什么时候建造的？”
  • 上传一幅画，问：“这是谁画的，是什么风格？”
  • 上传一张建筑物的照片，然后问：“这个在哪里？”
  • 在没有图像的情况下问研究问题：“告诉我罗马斗兽场的情况”

建筑

该应用程序使用三个组件架构：

1.MCP客户端(mcp_client.py)

  • 使用LangGraph编排代理工作流
  • 管理Gradio web界面
  • 连接到多个MCP服务器以访问工具

2.可视化分析服务器(visual_analysis_server.py)

  • 提供图像分析工具的MCP服务器
  • analyze_image_from_path：使用Gemini Vision在一步中加载和分析图像的组合工具
  • load_image_from_path：将图像加载并编码为Base64（传统支持）
  • get_image_description：使用Gemini Vision分析Base64编码图像（传统支持）

3.维基百科服务器(wikipedia_server.py)

  • 提供维基百科搜索的MCP服务器
  • fetch_wikipedia_info：搜索和检索文章摘要

技术栈

  • LangGraph：具有条件工具路由的代理工作流编排
  • MCP（模型上下文协议）：标准化工具集成
  • 谷歌双子座：用于推理和视觉的AI模型
  • Gradio：Web界面框架
  • LangChain：LLM框架和集成

项目结构

Image-research-assistant/
├── mcp_client.py              # Main application and Gradio UI
├── visual_analysis_server.py  # Image analysis MCP server
├── wikipedia_server.py        # Wikipedia search MCP server
├── CLAUDE.md                  # AI assistant documentation
└── README.md                  # This file

代理人如何工作

系统使用LangGraph创建一个智能代理，该代理：

  1. 接收用户输入（文本+可选图像）
  2. 根据查询决定使用哪些工具
  3. 高效执行工具（简化单步图像分析）
  4. 根据需要链接其他工具（例如图像分析→ 维基百科搜索）
  5. 将信息合成为连贯的响应

代理自动确定最佳工具执行策略，而无需硬编码工作流。

最近的改进

  • 优化工具管道：替换了两步图像处理（加载→ 分析）与单一流线型 analyze_image_from_path 提高可靠性的工具
  • 固定事件循环处理：解决了Gradio回调中的异步冲突，以实现稳定的并发请求处理
  • 增强的错误处理：添加了对格式错误的函数调用和空响应的优雅处理

扩展系统

要添加新功能，请执行以下操作：

  1. 使用FastMCP创建新的MCP服务器
  2. 使用工具 @mcp.tool() 装饰器
  3. 将服务器配置添加到 server_configs 在 mcp_client.py
  4. 代理将自动发现并使用新工具

环境变量

应用程序使用环境变量进行配置。所有敏感凭据都存储在 .env 文件（从版本控制中排除）。

所需变量：

  • GOOGLE_API_KEY：访问Gemini模型的Google API密钥

这 .env.example 该文件提供了一个配置模板。

故障排除

服务器无法启动:

  • 确保安装了所有依赖项： pip install -r requirements.txt
  • 验证 .env 文件是用您的API密钥配置的
  • 检查端口7860是否尚未使用

“找不到API密钥”错误:

  • 确保您已创建 .env 文件并添加您的Google API密钥
  • 验证密钥在以下位置有效 谷歌AI工作室

图像上传显示无响应:

  • 此问题已在最新版本中通过优化的工具管道和事件循环处理得到修复
  • 如果仍然遇到问题，请尝试刷新页面并上传其他图像格式（JPEG/PNG）

图像分析失败:

  • 验证您的Google API密钥是否可以访问Gemini模型
  • 检查图像文件是否损坏
  • 尝试使用较小的图像大小（处理较大的图像可能需要更长的时间）

维基百科搜索失败:

  • 检查您的互联网连接
  • 确保 wikipedia 软件包已安装： pip install wikipedia

UI出现卡住或冻结:

  • 刷新浏览器页面
  • 重启服务器：停止Python进程并运行 python mcp_client.py 再次
  • 检查终端是否有任何错误消息

许可证

[在此处指定您的许可证]

贡献

欢迎投稿！请随时提交问题或拉取请求。

相关 MCP