> ## Documentation Index
> Fetch the complete documentation index at: https://docs.siflow.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Vision And Multimodal

## 视觉 / 多模态模型

这类模型可以同时理解文本和图像。它们通过统一的、兼容 OpenAI 的 Chat Completions API 提供能力，适用于图像描述、视觉问答、图文协同等视觉语言任务。

**代表性模型：** `Qwen/Qwen2.5-VL-72B-Instruct`、`google/gemma-4-31B-it`。完整列表和价格请参见 [模型广场](https://console.siflow.cn/maas-api/model_plaza)。

***

### 1. 使用场景

* **图像理解**：描述图像、提取文本（OCR）并回答有关视觉内容的问题。
* **视觉问答**：对图表、截图或产品图片进行追问。
* **多模态对话**：在一次对话中混合文本和图像（例如"对比这两张图表"）。
* **内容审核**：使用自然语言指令对图像内容进行分类或标记。

***

### 2. 图像消息格式

发送图像时，需要将消息中的 `content` 设为数组，数组项类型可以是 `text` 或 `image_url`。其中 `image_url` 既可以是公网可访问的图片 URL，也可以是 `data:` URL（即 base64 编码的图片）。

示例结构：

```python theme={null}
messages = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "What is shown in this image?"},
            {"type": "image_url", "image_url": {"url": "https://images.unsplash.com/photo-1506748686214-e9df14d4d9d0"}}
        ]
    }
]
```

***

### 3. 关键参数

* **参数**：常用参数包括 `temperature`、`max_completion_tokens`；如果输出较长，建议启用 `stream=True`。不同模型对上下文长度和图像尺寸的限制不同，请参见 [模型广场](https://console.siflow.cn/maas-api/model_plaza)。
* **截断**：合理设置 `max_completion_tokens` 并增大客户端超时时间；启用流式传输以降低超时风险。

***

### 4. 视觉输入的计费

总费用 = （输入 tokens × 输入单价）+ （输出 tokens × 输出单价）

图像及其他视觉输入在计费时会**折算为输入 tokens**。不同模型对像素到 token 的映射方式不同：分辨率越高、图片越多，输入 token 通常也越多，费用随之升高。同一请求中的文本仍按常规方式计数；文本 tokens 与图像 tokens 相加后，就是计费公式中的总输入 tokens。

**视觉内容如何转换为 tokens（代表性模型）：**

| 模型                               | 视觉分词（简述）                                                                                |
| -------------------------------- | --------------------------------------------------------------------------------------- |
| **Qwen/Qwen2.5-VL-72B-Instruct** | 图像被划分为若干 patch/tile；每个 tile 被编码为 tokens。图像 token 总数取决于分辨率及模型允许的最大尺寸（例如 1280×1280 或类似值）。 |
| **google/gemma-4-31B-it**        | 视觉编码器将图像映射为一段 token 序列（基于 patch）；长度取决于输入分辨率和模型配置。                                       |

* **多张图像**：每张图像都会单独计算 token；总输入 tokens = 文本 tokens + 请求中所有图像 tokens 之和。
* **价格**：视觉模型的输入单价（按 token）可能与纯文本模型不同；请查看 [模型广场](https://console.siflow.cn/maas-api/model_plaza) → 模型详情，了解视觉输入的具体价格，以及是否存在按图像计费的上限或下限。

***

### 5. 示例

#### 5.1 图像描述

```python theme={null}
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_KEY",
    base_url="https://api.siflow.cn/model-api"
)

response = client.chat.completions.create(
    model="Qwen/Qwen2.5-VL-72B-Instruct",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Describe this image in one or two sentences."},
                {"type": "image_url", "image_url": {"url": "https://images.unsplash.com/photo-1506748686214-e9df14d4d9d0"}}
            ]
        }
    ],
    max_completion_tokens=256
)

print(response.choices[0].message.content)
```

#### 5.2 使用 Base64 图像的视觉问答

```python theme={null}
import base64
from openai import OpenAI

def image_to_data_url(path: str) -> str:
    with open(path, "rb") as f:
        b64 = base64.standard_b64encode(f.read()).decode()
    return f"data:image/jpeg;base64,{b64}"

client = OpenAI(
    api_key="YOUR_KEY",
    base_url="https://api.siflow.cn/model-api"
)

url = image_to_data_url("myphoto.jpeg")

response = client.chat.completions.create(
    model="Qwen/Qwen2.5-VL-72B-Instruct",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "What is the main message or call-to-action on this screen?"},
                {"type": "image_url", "image_url": {"url": url}}
            ]
        }
    ],
    max_completion_tokens=512
)

print(response.choices[0].message.content)
```

#### 5.3 单次请求中包含多张图像

如果要在一次请求中发送多张图像，只需在同一个 `content` 数组中继续添加 `image_url` 条目。模型会同时接收这些图像，并据此完成对比、归纳等任务。

```python theme={null}
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_KEY",
    base_url="https://api.siflow.cn/model-api"
)

response = client.chat.completions.create(
    model="Qwen/Qwen2.5-VL-72B-Instruct",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Compare these two images in one or two sentences. What do they have in common or how do they differ?"},
                {"type": "image_url", "image_url": {"url": "https://images.unsplash.com/photo-1551963831-b3b1ca40c98e"}},
                {"type": "image_url", "image_url": {"url": "https://images.unsplash.com/photo-1472214103451-9374bd1c798e"}}
            ]
        }
    ],
    max_completion_tokens=512
)

print(response.choices[0].message.content)
```

***

* 支持的图像格式和大小限制因模型而异；请参见 [模型广场](https://console.siflow.cn/maas-api/model_plaza) → 模型详情。