# Qwen3-VL 视觉语言模型示例

使用阿里云百炼 DashScope API 调用 Qwen3-VL 多模态大模型进行图片理解。

## 模型简介

Qwen3-VL 是通义千问系列中最强大的视觉语言模型，具备以下能力：

- 🎯 高精度物体识别与定位（包括 3D 定位）
- 🤖 Agent 工具调用
- 📄 文档和网页解析
- 🧠 复杂题目解答
- 🎬 长视频理解

## 模型选型

| 模型 | 特点 | 适用场景 |
|------|------|----------|
| **qwen3-vl-plus** | 性能最强 | 高精度识别、Agent 调用、复杂任务 |
| **qwen3-vl-flash** | 速度快、成本低 | 对响应速度敏感的场景 |

## 快速开始

### 1. 安装依赖

```bash
uv sync
```

### 2. 配置 API Key

在 [阿里云百炼控制台](https://help.aliyun.com/zh/model-studio/get-api-key) 获取 API Key，然后创建 `.env` 文件：

```bash
cp .env-example .env
# 编辑 .env 文件，填入你的 API Key
```

`.env` 文件内容：

```
DASHSCOPE_API_KEY=sk-your-api-key-here
```

### 3. 运行示例

```bash
uv run python qwen3_vl_example.py
```

## 示例说明

### 输入图片

示例使用以下测试图片：

![示例图片](https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241022/emyrja/dog_and_girl.jpeg)

### 提问

> 图中描绘的是什么景象？请详细描述。

### 模型输出

```
这张图片描绘了一幅温馨、宁静且充满情感的海边黄昏景象，核心是人与宠物之间亲密互动的美好瞬间。

**主要人物与动物：**
- 一位年轻女性坐在沙滩上，她留着深色长发，身穿一件黑白格子衬衫和深色裤子，赤脚踩在沙地上。
  她面带灿烂而温暖的笑容，目光温柔地注视着面前的狗狗，神情愉悦放松。
- 一只浅黄色的拉布拉多犬正端坐在她面前，身体微微前倾，抬起右前爪，与女子的手掌轻轻相触，
  仿佛在"击掌"或"握手"。狗狗戴着一条带有彩色小花图案的蓝色胸背带，脖子上还系着红色牵引绳。

**环境与背景：**
- 场景位于一片开阔的沙滩上，细软的沙粒在阳光下呈现出柔和的质感。
- 背景是平静辽阔的大海，海浪轻柔地拍打着岸边。
- 天空呈现出日落时分特有的暖色调——金黄、橙红与淡白交织，营造出梦幻般的"黄金时刻"氛围。

**整体氛围：**
这是一幅捕捉生活中小确幸的温情画面，传达了陪伴、信任与纯粹快乐的主题，
令人感受到人与动物之间无言的默契与爱意。
```

## API 使用方式

本示例使用 OpenAI 兼容接口调用 DashScope：

```python
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

completion = client.chat.completions.create(
    model="qwen3-vl-plus",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {"url": "https://example.com/image.jpg"},
                },
                {"type": "text", "text": "描述这张图片"},
            ],
        },
    ],
)
```

## 地域说明

- **北京地域**: `https://dashscope.aliyuncs.com/compatible-mode/v1`
- **新加坡地域**: `https://dashscope-intl.aliyuncs.com/compatible-mode/v1`