> ## 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 兼容接口处理图像理解、视觉问答、多模态对话和视觉输入计费。

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

代表模型包括：

* `Qwen/Qwen2.5-VL-72B-Instruct`
* `google/gemma-4-31B-it`

完整模型列表和价格，请以 [模型广场](https://console.siflow.cn/model-inference/models) 为准。

## 核心能力

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

## 图像消息格式

发送图像时，需要将 `messages` 中的 `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",
                },
            },
        ],
    }
]
```

## 关键参数

* **参数**

  * `temperature`：控制输出随机性。

  * `max_completion_tokens`：限制生成长度 ，避免输出被截断。

  * `stream=True`：流式返回 。对于长回复推荐使用，可降低超时风险。

* **上下文**

  不同模型支持的最大上下文长度可通过 [模型广场](https://console.siflow.cn/model-inference/models) 查看。

* **图像限制**

  支持的图像格式和大小限制因模型而异，具体可通过 [模型广场](https://console.siflow.cn/model-inference/models) 查看。

## 计费

* **公式**：总费用 =（输入 tokens × 输入单价）+（输出 tokens × 输出单价）

* **价格**：视觉模型的输入单价（按 token）可能与纯文本模型不同，请在 [模型广场](https://console.siflow.cn/model-inference/models) 的模型详情页了解视觉输入的具体价格，以及是否存在按图像计费的上限或下限。

* **tokens 计算说明**
  总输入 tokens = 文本 tokens + 图像 tokens。

  * 图像及其他视觉输入在计费时会折算为输入 tokens。不同模型对像素到 token 的映射方式不同：分辨率越高、图片越多，输入 token 通常也越多。
  * 同一请求中的文本仍按常规方式计算。
  * 如果有多张图像，每张图像都会单独计算 tokens。

* **tokens 计算示例**
  以代表模型为例，说明视觉内容如何转换为 tokens：

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

## 调用示例

示例使用环境变量读取 API Key，避免将密钥写入代码。

```bash theme={null}
export API_KEY="YOUR_API_KEY"
```

### 图像描述

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

client = OpenAI(
    api_key=os.environ["API_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)
```

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

```python theme={null}
import os
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=os.environ["API_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)
```

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

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

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

client = OpenAI(
    api_key=os.environ["API_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)
```