Skip to content

IMAGE_TO_TEXT_GUIDE.md

Latest commit

 

History

History
223 lines (174 loc) · 7.3 KB

IMAGE_TO_TEXT_GUIDE.md

File metadata and controls

223 lines (174 loc) · 7.3 KB

📄 图片转文字功能指南

🎯 功能概述

图片转文字功能是 MCP Feedback Collector v2.0.9 新增的重要特性，旨在解决部分MCP客户端无法显示图片的兼容性问题。通过AI智能分析，将图片转换为详细的文字描述，确保所有用户都能获得完整的反馈信息。

✨ 主要特性

  • 🤖 AI智能分析: 使用先进的视觉AI模型分析图片内容
  • 📝 详细描述: 生成包含主要元素、颜色、布局、文字等信息的描述
  • ✏️ 可编辑内容: 用户可以修改AI生成的描述
  • 🔄 批量处理: 支持多张图片同时转换
  • 🎯 兼容性优化: 同时保留原图和文字描述，满足不同客户端需求

🔧 配置要求

环境变量配置

# 启用图片转文字功能
MCP_ENABLE_IMAGE_TO_TEXT="true"

# 自定义提示词（可选）
MCP_IMAGE_TO_TEXT_PROMPT="请详细描述这张图片的内容，包括主要元素、颜色、布局、文字等信息。"

# API配置（必需）
MCP_API_KEY="your_api_key_here"
MCP_API_BASE_URL="https://api.ssopen.top"
MCP_DEFAULT_MODEL="grok-3"  # 需要支持视觉功能的模型

MCP配置示例

{
  "mcpServers": {
    "mcp-feedback-collector": {
      "command": "npx",
      "args": ["-y", "mcp-feedback-collector@latest"],
      "env": {
        "MCP_API_KEY": "your_api_key_here",
        "MCP_API_BASE_URL": "https://api.ssopen.top",
        "MCP_DEFAULT_MODEL": "grok-3",
        "MCP_ENABLE_IMAGE_TO_TEXT": "true",
        "MCP_IMAGE_TO_TEXT_PROMPT": "请详细描述这张图片的内容，包括主要元素、颜色、布局、文字等信息。"
      }
    }
  }
}

🚀 使用流程

1. 上传图片

  • 点击"📁 选择图片"按钮选择文件
  • 或点击"📋 粘贴图片"从剪贴板粘贴
  • 支持JPG、PNG、GIF、WebP、BMP格式

2. 转换图片

  • 上传图片后，会显示"📄 图片转文本"按钮
  • 点击按钮开始AI分析过程
  • 转换过程中按钮显示"🔄 转换中..."

3. 预览和编辑

  • AI分析完成后，显示图片描述区域
  • 每张图片对应一个可编辑的文本框
  • 用户可以修改或完善AI生成的描述

4. 提交反馈

  • 点击"提交反馈"按钮
  • 系统同时提交原图和文字描述
  • MCP客户端会收到完整的反馈信息

🎨 界面设计

图片预览区域

┌─────────────────────────────────────┐
│ 📎 附加图片（可选）                  │
│ [📁 选择图片] [📋 粘贴图片]           │
│                                     │
│ [图片1] [图片2] [图片3]              │
│                                     │
│ [📄 图片转文本] 按钮                 │
└─────────────────────────────────────┘

图片描述区域

┌─────────────────────────────────────┐
│ 📄 图片描述内容                      │
│                                     │
│ 图片 1: screenshot.png              │
│ ┌─────────────────────────────────┐ │
│ │ 这是一张显示代码编辑器的截图...   │ │
│ │ [可编辑文本框]                  │ │
│ └─────────────────────────────────┘ │
│                                     │
│ 图片 2: diagram.png                 │
│ ┌─────────────────────────────────┐ │
│ │ 这是一张系统架构图...           │ │
│ │ [可编辑文本框]                  │ │
│ └─────────────────────────────────┘ │
└─────────────────────────────────────┘

🔍 技术实现

后端API

  • 端点: POST /api/convert-images
  • 请求格式: JSON，包含图片数组
  • 响应格式: JSON，包含描述数组
  • 错误处理: 完善的错误信息和状态码

前端交互

  • 异步处理: 使用fetch API调用后端
  • 状态管理: 实时更新按钮状态和提示信息
  • 用户体验: 加载动画和错误提示

AI模型调用

  • 视觉API: 调用支持图片分析的AI模型
  • 提示词优化: 可自定义的分析提示词
  • 错误恢复: 单张图片失败不影响其他图片

📊 兼容性对比

客户端类型 原图显示 文字描述 用户体验
支持图片的客户端 ✅ 显示 ✅ 显示 🌟 完美
不支持图片的客户端 ❌ 不显示 ✅ 显示 🌟 良好
传统文本客户端 ❌ 不显示 ✅ 显示 🌟 可用

🎯 使用场景

1. 代码截图反馈

用户上传代码截图 → AI识别代码内容 → 生成代码描述
"这是一段TypeScript代码，定义了一个图片转文字的服务类..."

2. 界面设计反馈

用户上传UI截图 → AI分析界面元素 → 生成界面描述
"这是一个深色主题的Web界面，包含导航栏、内容区域和按钮..."

3. 错误信息反馈

用户上传错误截图 → AI识别错误信息 → 生成错误描述
"这是一个浏览器控制台错误，显示TypeError: Cannot read property..."

⚠️ 注意事项

1. API配置

  • 确保API密钥有效且有足够余额
  • 使用支持视觉功能的AI模型
  • 检查API基础URL的可访问性

2. 图片要求

  • 文件大小不超过10MB
  • 支持的格式：JPG、PNG、GIF、WebP、BMP
  • 图片内容清晰，便于AI识别

3. 网络环境

  • 确保能访问配置的API服务
  • 转换过程需要网络连接
  • 大图片转换可能需要较长时间

🐛 故障排除

常见问题

  1. 转换按钮不显示

    • 检查是否已上传图片
    • 确认功能是否启用 (MCP_ENABLE_IMAGE_TO_TEXT=true)

  2. 转换失败

    • 检查API密钥配置
    • 确认模型支持视觉功能
    • 查看浏览器控制台错误信息

  3. 描述质量不佳

    • 调整提示词 (MCP_IMAGE_TO_TEXT_PROMPT)
    • 尝试不同的AI模型
    • 确保图片清晰度

调试方法

# 检查配置
npx mcp-feedback-collector config

# 查看详细日志
export LOG_LEVEL=debug
npx mcp-feedback-collector

# 测试API连接
curl -X POST http://localhost:5000/api/convert-images \
  -H "Content-Type: application/json" \
  -d '{"images": []}'

🔮 未来规划

  • 🎯 批量优化: 提升多图片处理性能
  • 🎨 模板支持: 预设不同类型图片的分析模板
  • 📊 统计功能: 转换成功率和质量统计
  • 🔒 隐私保护: 本地图片处理选项
  • 🌍 多语言: 支持多种语言的图片描述

📞 获取帮助

如果在使用图片转文字功能时遇到问题，请：

  1. 查看本文档的故障排除部分
  2. 检查 TROUBLESHOOTING.md 详细指南
  3. 在 GitHub Issues 中报告问题
  4. 提供详细的错误信息和配置信息

💡 提示: 图片转文字功能是可选的，即使不启用也不影响基本的反馈收集功能。