AB
AiBoss站
教程

Watsonx.ai

教程

用 watsonx.ai 的 Llama 3.2 视觉模型做图像描述与视觉问答

在 watsonx.ai 上调用 meta-llama/llama-3-2-90b-vision-instruct,用 Python 把图片编码成 base64 后送入模型,完成图像描述、目标计数、损伤评估与标签读数等视觉问答任务。本文给出从创建项目、配置运行时与 API 密钥,到封装请求体、批量处理多张图片的完整步骤与可运行代码。

多模态模型能同时接收文字与图片,把「看图说话」变成一次普通的 API 调用。本文要解决的问题是:在 watsonx.ai 上使用 meta-llama/llama-3-2-90b-vision-instruct 模型,通过 Python 把本地或网络图片编码后送入模型,完成图像描述(image captioning)与视觉问答(visual question answering)两类任务。适合已经会用 Python 发请求、希望把视觉能力接进自己流程的开发者;如果你只需要纯文本对话,用单模态模型即可,不必走这套流程。站内也有对应的工具条目可供参考:watsonx.ai。

在动手之前,先理解多模态模型与单模态模型的差别。单模态大语言模型只处理文本输入,聊天机器人就是典型例子:它理解你的问题并实时生成回答,但输入类型被限制在文字。多模态模型建立在神经网络之上,能够处理和整合多种数据类型,输入可以是文本、图像、视频与音频。它的优势正在于「同时吃下不同形态的数据」,因此可以覆盖从医学影像判读到翻译场景语音识别等用途。

从结构上看,多模态系统通常包含三个部分:输入模块负责用多个单模态神经网络对不同数据类型做预处理;融合模块负责把各路数据合并、对齐与加工,常见做法有早期融合(把各输入类型的原始数据直接合并)、中期融合(在不同预处理阶段对模态编码)和晚期融合(各模态先由对应模型处理,再合并结果);输出模块则把融合后的结果整理成目标格式,可能是文本、图像,也可能是两者的组合。理解这三段结构,有助于判断自己的任务该在哪一步做文章。

准备工作

账号与项目

第一步是准备访问入口。使用 IBM Cloud 账号登录 watsonx.ai,然后创建一个 watsonx.ai 项目。项目 ID 是后续代码必需的参数,获取方式如下:进入项目后点击 Manage 标签页,在 General 页面的 Details 区域复制项目 ID。请把这个 ID 与后面的 API 密钥一起保存好。

运行时实例与 API 密钥

接着创建一个 watsonx.ai Runtime 服务实例,选择适合你的区域,并选用 Lite 计划(免费实例)。然后生成一个 API Key,并把该 Runtime 服务实例关联到前面创建的项目。这一步做完,代码才有权限调用模型推理接口。

关于计划类型、可用区域、配额与计费方式,各账户情况不同且会调整,请以 watsonx.ai 官网当前信息为准。

笔记本环境

本文的代码适合在 Jupyter Notebook 中运行。Notebook 能把代码与文本、图片、可视化结果放在一起,便于逐段调试。在 watsonx.ai 项目中新建一个 Jupyter Notebook,即可获得可执行环境;也可以把笔记本下载到本地,再作为资产上传回项目。

为避免 Python 包依赖冲突,建议先建立虚拟环境再安装依赖。素材中的示例图片与笔记本文件托管在 GitHub 上,需要时自行获取;本文不提供外部链接,按名称检索即可。

操作步骤

步骤一:安装并导入依赖库

需要的库不多:处理图片的 Pillow、watsonx.ai 的 Python SDK、读取环境变量的 python-dotenv,以及标准库中的 requests、base64、os。如果环境里没有,用 pip 安装。下面这段在 Notebook 单元格中执行:

%pip install image | tail -n 1
%pip install -U "ibm_watsonx_ai>=1.1.14" | tail -n 1
%pip install python-dotenv | tail -n 1

随后导入模块:

import requests
import base64
import os
from PIL import Image
from ibm_watsonx_ai import Credentials
from ibm_watsonx_ai.foundation_models import ModelInference
from dotenv import load_dotenv

load_dotenv(os.getcwd()+"/.env", override=True)

这里的 load_dotenv 会从当前目录的 .env 文件读取配置,并把已有环境变量覆盖掉。如果你不想用 .env,也可以直接在代码里替换占位符。

步骤二:配置凭据与接口地址

把上一步拿到的 API 密钥与项目 ID 填进去,同时设置 API 端点 URL。用 Credentials 类把地址与密钥封装起来,后续实例化模型时直接传入:

WATSONX_APIKEY = os.getenv('WATSONX_APIKEY', "<YOUR_WATSONX_APIKEY_HERE>")
WATSONX_PROJECT_ID = os.getenv('WATSONX_PROJECT_ID', "<YOUR_WATSONX_PROJECT_ID_HERE>")
URL = "<YOUR_WATSONX_URL_HERE>"

credentials = Credentials(
    url=URL,
    api_key=WATSONX_APIKEY
)

端点 URL 取决于你实例所在的区域,请从控制台确认后填入,不要照抄别人的地址。

步骤三:把图片编码成模型可读的形式

模型不能直接接收图片文件,需要先转成字节,再解码为 UTF-8 字符串。准备一个图片 URL 列表,循环下载并编码:

url_image_1 = '<IMAGE_URL_1>'
url_image_2 = '<IMAGE_URL_2>'
url_image_3 = '<IMAGE_URL_3>'
url_image_4 = '<IMAGE_URL_4>'

image_urls = [url_image_1, url_image_2, url_image_3, url_image_4]

encoded_images = []
for url in image_urls:
    encoded_images.append(
        base64.b64encode(requests.get(url).content).decode("utf-8")
    )

编码前建议先把图片显示出来,确认自己拿到的是预期内容,避免后面把错误归因于模型:

for idx, url in enumerate(image_urls):
    print(f'url_image_{idx}')
    display(Image.open(requests.get(url, stream=True).raw))

步骤四:封装请求体

多模态请求的 messages 结构与纯文本不同:content 是一个列表,里面既有文本块也有图片块。写一个函数,把用户问题和 base64 图片拼成标准结构,后面每次调用都复用它:

def augment_api_request_body(user_query, image):
    messages = [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": 'You are a helpful assistant. Answer the following user query in 1 or 2 sentences: ' + user_query
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": f"data:image/jpeg;base64,{image}",
                    }
                }
            ]
        }
    ]
    return messages

注意两点:一是图片以 data URL 形式内嵌,前缀写明 data:image/jpeg;base64,;二是系统提示里限定了「用一到两句话回答」,这能有效控制输出长度,避免模型展开长篇描述。如果任务需要更详细的输出,可以改这句提示,同时相应调大 max_tokens。

步骤五:实例化模型

用 ModelInference 指定模型 ID、凭据、项目 ID 与生成参数。示例中把 max_tokens 设为 200:

model = ModelInference(
    model_id="meta-llama/llama-3-2-90b-vision-instruct",
    credentials=credentials,
    project_id=WATSONX_PROJECT_ID,
    params={
        "max_tokens": 200
    }
)

模型 ID 必须与平台上可用的标识一致,写错会直接报错。若你改用其他支持多模态的模型,接口与参数结构可能不同,需要按对应模型的文档调整,不能直接套用本文代码。

步骤六:批量生成图像描述

把编码后的图片逐张送入模型,统一提问「这张图里发生了什么」,打印返回内容。响应结构为 response['choices'][0]['message']['content']:

for i in range(len(encoded_images)):
    image = encoded_images[i]
    user_query = "What is happening in this image?"
    messages = augment_api_request_body(user_query, image)
    response = model.chat(messages=messages)
    print(response['choices'][0]['message']['content'])

四张示例图分别对应城市街景、户外跑步的女性、洪水淹没的房屋、营养成分标签。模型给出的描述覆盖了建筑、车辆、行人、红绿灯、树木等要素,也识别出人物的穿着(黄色连帽衫、黑色紧身裤、运动鞋)与动作,对洪水图则指出水位已接近部分建筑屋顶。对营养标签,模型以结构化方式列出热量、脂肪、钠、碳水化合物等信息。这说明同一套调用方式可以适配差异很大的图像内容。

步骤七:用提问做目标检测与信息抽取

图像描述只是起点。把问题换成需要定位或计数的形式,就能做轻量的目标检测。例如针对第二张跑步图,问「图里有几辆车」:

image = encoded_images[1]
user_query = "How many cars are in this image?"
messages = augment_api_request_body(user_query, image)
response = model.chat(messages=messages)
print(response['choices'][0]['message']['content'])

模型回答图中有一辆车,停在建筑右侧的街道上,并给出了位置描述。接着针对洪水图询问损伤严重程度:

image = encoded_images[2]
user_query = "How severe is the damage in this image?"
messages = augment_api_request_body(user_query, image)
response = model.chat(messages=messages)
print(response['choices'][0]['message']['content'])

模型判断损伤严重,洪水覆盖了大片土地,水位至少齐腰深,可能对建筑与农作物造成较大损失。这类输出在保险理赔场景中有实际价值:先由模型给出初步的受损程度判断,可以缩短人工初筛时间。

最后针对营养标签图做数值抽取,问「这个产品含多少钠」:

image = encoded_images[3]
user_query = "How much sodium is in this product?"
messages = augment_api_request_body(user_query, image)
response = model.chat(messages=messages)
print(response['choices'][0]['message']['content'])

模型返回钠含量为 640 毫克。可见模型不仅能描述画面,还能从图像中读出具体字段值。

一个完整示例

把上面的片段串起来,就是一个从零跑通的最小流程。以下代码假设依赖已安装、.env 中已写入 WATSONX_APIKEY 与 WATSONX_PROJECT_ID:

import requests
import base64
import os
from ibm_watsonx_ai import Credentials
from ibm_watsonx_ai.foundation_models import ModelInference
from dotenv import load_dotenv

load_dotenv(os.getcwd()+"/.env", override=True)

WATSONX_APIKEY = os.getenv('WATSONX_APIKEY', "<YOUR_WATSONX_APIKEY_HERE>")
WATSONX_PROJECT_ID = os.getenv('WATSONX_PROJECT_ID', "<YOUR_WATSONX_PROJECT_ID_HERE>")
URL = "<YOUR_WATSONX_URL_HERE>"

credentials = Credentials(url=URL, api_key=WATSONX_APIKEY)

model = ModelInference(
    model_id="meta-llama/llama-3-2-90b-vision-instruct",
    credentials=credentials,
    project_id=WATSONX_PROJECT_ID,
    params={"max_tokens": 200}
)

def augment_api_request_body(user_query, image):
    return [{
        "role": "user",
        "content": [
            {"type": "text",
             "text": 'You are a helpful assistant. Answer the following user query in 1 or 2 sentences: ' + user_query},
            {"type": "image_url",
             "image_url": {"url": f"data:image/jpeg;base64,{image}"}}
        ]
    }]

image_urls = ['<IMAGE_URL_1>', '<IMAGE_URL_2>']
encoded_images = [
    base64.b64encode(requests.get(u).content).decode("utf-8")
    for u in image_urls
]

for image in encoded_images:
    messages = augment_api_request_body("What is happening in this image?", image)
    response = model.chat(messages=messages)
    print(response['choices'][0]['message']['content'])
    print('---')

运行后应看到每张图对应一段一到两句话的描述,段与段之间用分隔线隔开。若某张图返回空内容或报错,先检查图片 URL 是否可访问、base64 字符串是否完整,再检查模型 ID 与项目 ID 是否正确。

注意事项

  • 模型 ID 要精确匹配。 meta-llama/llama-3-2-90b-vision-instruct 是本文使用的标识,平台上的可用模型会变化,调用前确认当前可用的模型标识。
  • 换模型就要换接口。 本文代码针对 watsonx.ai 设计。若改用其他厂商的多模态模型,请求体结构、鉴权方式与返回字段都可能不同,不能直接复用。
  • 输出长度受 max_tokens 约束。 示例设为 200,配合「一到两句话」的提示词足够。需要长描述时同时调整提示词与上限,否则回答会被截断。
  • 图片以 base64 内嵌会放大请求体。 图片越大,编码后的字符串越长,请求耗时与失败概率都会上升。批量处理时建议控制图片尺寸与数量。
  • 依赖版本有下限。 示例要求 ibm_watsonx_ai>=1.1.14,版本过低可能缺少所需接口。建议在虚拟环境中安装,避免与其他项目冲突。
  • 凭据不要写进代码。 使用 .env 或环境变量保存 API 密钥与项目 ID,不要把明文密钥提交到版本库。
  • 视觉问答的结果需要人工复核。 计数、读数、损伤评估这类输出属于模型判断,用于理赔、医疗等场景时应保留人工确认环节。
  • 计划、配额与区域可用性以官网为准。 免费实例的额度、可用区域与计费规则会调整,本文不给出具体数字。