指南
图像理解
视觉模型可以接收文本和图像输入。您可以通过以下两种方式之一将图像传递到模型中：base64 编码的字符串或 Web URL。
在后台，图像理解共享相同的 API 路由和相同的消息正文架构，包括system/user/assistant消息。区别在于消息内容正文中使用图像而不是文本。
因为本指南中的知识是建立在对聊天功能的理解之上的。建议您在遵循本指南之前熟悉聊天功能。
先决条件
- xAI 帐户：您需要一个 xAI 帐户才能访问 API。
- API 密钥：确保您的 API 密钥有权访问视觉终端节点，并且已启用支持图像输入的模型。
如果您没有这些并且不确定如何创建一个，请按照 Hitchhiker's Guide to Grok 进行作。
在您的环境中设置 API 密钥：
bash
export XAI_API_KEY="your_api_key"
关于图像理解模型一般限制的提醒
与聊天模型相比，使用这些模型可能更容易遇到模型限制：
- 最大图像尺寸：
10MiB - 最大图像数量：无限制
- 支持的图像文件类型：
jpg/jpeg或png. - 接受任何图像/文本输入顺序（例如，文本提示可以位于图像提示之前）
构建消息正文 - 与 Chat 的区别
图像理解的请求消息类似于聊天。主要区别在于，不是文本输入：
json
[
{
"role": "user",
"content": "What is in this image ?",
}
]
我们发送content作为对象列表：
json
[
{
"role": "user",
"content": [
{
"type": "image_url",
"image_url": {
"url": "data:image/jpeg;base64,<base64_image_string>",
"detail": "high",
},
},
{
"type": "text",
"text": "What is in this image ?",
},
],
}
]
这image_url.url也可以是图像在 Internet 上的 URL。
您可以使用文本提示询问有关图像的问题，或以图像作为讨论上下文讨论的主题，等等。
Web URL 输入
该模型支持 Web URL 作为图像的输入。API 将从公共 URL 获取图像，并将其作为聊天的一部分进行处理。与 URL 集成非常简单：
import os
from openai import OpenAI
XAI_API_KEY = os.getenv("XAI_API_KEY")
image_url = (
"https://science.nasa.gov/wp-content/uploads/2023/09/web-first-images-release.png"
)
client = OpenAI(
api_key=XAI_API_KEY,
base_url="https://api.x.ai/v1",
)
messages = [
{
"role": "user",
"content": [
{
"type": "image_url",
"image_url": {
"url": image_url,
"detail": "high",
},
},
{
"type": "text",
"text": "What's in this image?",
},
],
},
]
completion = client.chat.completions.create(
model="grok-2-vision-latest",
messages=messages,
temperature=0.01,
)
print(completion.choices[0].message.content)Base64 字符串输入
您需要直接在请求中的用户消息中传入 base64 编码的图像。
下面是一个示例，说明如何加载本地图像，以 Base64 对其进行编码并将其用作对话的一部分：
import os
from openai import OpenAI
import os
import base64
XAI_API_KEY = os.getenv("XAI_API_KEY")
image_path = "..."
client = OpenAI(
api_key=XAI_API_KEY,
base_url="https://api.x.ai/v1",
)
def encode_image(image_path):
with open(image_path, "rb") as image_file:
encoded_string = base64.b64encode(image_file.read()).decode("utf-8")
return encoded_string
# Getting the base64 string
base64_image = encode_image(image_path)
messages = [
{
"role": "user",
"content": [
{
"type": "image_url",
"image_url": {
"url": f"data:image/jpeg;base64,{base64_image}",
"detail": "high",
},
},
{
"type": "text",
"text": "What's in this image?",
},
],
},
]
completion = client.chat.completions.create(
model="grok-2-vision-latest",
messages=messages,
temperature=0.01,
)
print(completion.choices[0].message.content)多张图片输入
您可以在提示符中发送多个图像，例如：
messages = [
{
"role": "user",
"content": [
{
"type": "image_url",
"image_url": {
"url": f"data:image/jpeg;base64,{base64_image1}",
"detail": "high"
}
},
{
"type": "text",
"text": "What are in these images?"
},
{
"type": "image_url",
"image_url": {
"url": f"data:image/jpeg;base64,{base64_image2}",
"detail": "high",
}
}
],
},
]图像提示可以按任意顺序与文本提示交错。
图像令牌使用情况
API 响应中提供了提示图像令牌使用情况。每张图片将自动分解为 448x448 像素的图块，每个图块将消耗 256 个令牌。最终生成将包括一个额外的图块，因此每个图像都会消耗(# of tiles + 1) * 256令 牌。最大限制为 6 个图块，因此您的输入每个图像消耗的令牌少于 1,792 个。
python
# Stream response
print(next(stream).usage.prompt_tokens_details.image_tokens)
# Non-stream response
print(response.usage.prompt_tokens_details.image_tokens)
参数
请求正文
messages
数组
必填
构成聊天对话的消息列表。不同的模型支持不同的消息类型，例如图像和文本。
model
字符串
必填
要使用的模型的模型名称。