# 直接运行，无需安装（uv 自动缓存）
uvx visual-understanding list-providers

# 如果默认镜像（如清华 TUNA）尚未同步新包，可临时指定官方索引：
uvx --default-index https://pypi.org/simple visual-understanding list-providers

cd mcp-servers/visual-understanding
pip install -e .

# 智谱（推荐——支持原生定位、视频、文件）
export ZHIPU_API_KEY="your_key"       # https://bigmodel.cn/usercenter/proj-mgmt/apikeys

# OpenAI
export OPENAI_API_KEY="your_key"      # https://platform.openai.com/api-keys

# Anthropic
export ANTHROPIC_API_KEY="your_key"   # https://console.anthropic.com/settings/keys

visual-understanding list-providers

{
  "mcpServers": {
    "visual-understanding": {
      "command": "uvx",
      "args": ["visual-understanding", "serve"]
    }
  }
}

{
  "mcpServers": {
    "visual-understanding": {
      "command": "uvx",
      "args": ["visual-understanding", "serve"],
      "env": {
        "ZHIPU_API_KEY": "你的智谱key",
        "OPENCODE_API_KEY": "你的opencode key"
      }
    }
  }
}

{
  "mcpServers": {
    "visual-understanding": {
      "command": "uvx",
      "args": ["visual-understanding", "serve"],
      "env": {
        "VISUAL_UNDERSTANDING_BASE_URL": "https://你的三方服务.com/v1",
        "VISUAL_UNDERSTANDING_API_KEY": "sk-xxx",
        "VISUAL_UNDERSTANDING_MODEL": "qwen-vl-max"
      }
    }
  }
}

providers:
  dashscope:
    type: openai_compat
    api_key: "sk-直接写在配置里"      # 不设系统变量也能用
    base_url: https://dashscope.aliyuncs.com/compatible-mode/v1
    chat_models: [qwen-vl-max]
    default_chat_model: qwen-vl-max

visual-understanding doctor

{
  "mcpServers": {
    "visual-understanding": {
      "command": "uvx",
      "args": ["visual-understanding", "serve"],
      "env": {
        "ZHIPU_API_KEY": "你的智谱key",
        "OPENCODE_API_KEY": "你的opencode key"
      }
    }
  }
}

# 描述图片
visual-understanding analyze --images photo.jpg

# OCR 文字提取
visual-understanding analyze --images scan.png --prompt "Extract all text"

# 视觉问答
visual-understanding analyze --images photo.jpg --prompt "What color is the car?"

# 目标定位 + 画框
visual-understanding ground --image photo.jpg --prompt "all people" --visualize --save-path result.png

# 使用特定提供商/模型
visual-understanding analyze --images photo.jpg --provider openai --model gpt-4o

# 方式一：环境变量指定路径
export VISUAL_UNDERSTANDING_CONFIG=/path/to/config.yaml

# 方式二：默认路径
mkdir -p ~/.config/visual-understanding
cp config.example.yaml ~/.config/visual-understanding/config.yaml

providers:
  my-vlm:
    type: openai_compat
    api_key_env: MY_API_KEY              # 环境变量名
    base_url: http://localhost:8080/v1   # API 地址
    chat_models: [qwen-vl-max]
    default_chat_model: qwen-vl-max
    max_images: 10

export MY_API_KEY="your_key_or_dummy"
visual-understanding analyze --images photo.jpg --provider my-vlm

                    ┌─────────────┐
                    │   config    │  YAML / env vars
                    └──────┬──────┘
                           │
              ┌────────────┼────────────┐
              ▼            ▼            ▼
        ┌──────────┐ ┌──────────┐ ┌──────────┐
        │ ops.py   │ │ ops.py   │ │ ops.py   │   ← 共享业务逻辑
        │ do_analyze│ │ do_ground│ │ do_list  │
        └────┬─────┘ └────┬─────┘ └──────────┘
             │             │
     ┌───────┴──────┐     │
     ▼              ▼     ▼
 ┌────────┐   ┌────────┐ ┌──────────┐
 │server.py│  │ cli.py │ │grounding │
 │ (MCP)  │   │ (CLI)  │ │  .py     │
 └───┬────┘   └────────┘ └──────────┘
     │
     ▼
 ┌──────────────────────────────────┐
 │         providers/               │
 │  ┌────────────┐ ┌────────────┐  │
 │  │openai_compat│ │ anthropic  │  │
 │  │(OpenAI/智谱)│ │ (Claude)   │  │
 │  └────────────┘ └────────────┘  │
 └──────────────────────────────────┘