多模态输入

使用 OpenAI SDK 向模型发送图片与 PDF,掌握多模态消息结构、文件数据传递和结果验证。

🎯 引言

前面我们一直通过 messages 向模型发送文字。但在实际业务中,用户可能希望 AI 描述一张商品图片,或者直接阅读一份售后说明 PDF,提取其中的关键信息。

这些场景都属于 多模态输入 :除了文字,模型还需要接收图片、文档等类型的数据。本篇继续使用 AIHubMix + OpenAI SDK + Chat Completions ,分别完成图片理解和 PDF 分析,重点学习如何组织请求内容,以及如何验证模型是否真正理解了输入材料。图片生成、语音和知识库检索不在本文范围内。


🧱 多模态消息与普通消息有什么不同?

前面的文本请求中,content 是一段字符串:

{
    role: "user",
    content: "请描述这款商品。"
}

如果需要模型结合图片回答,就不能只发送这句话,还要把图片数据一起提供。Chat Completions 支持将 content 写成 内容块数组 :

{
    role: "user",
    content: [
        { type: "text", text: "请描述这款商品。" },
        { type: "image_url", image_url: { url: "图片的 URL 或 Data URL" } }
    ]
}

这里的两块内容属于 同一条用户消息 :文本说明任务,图片提供分析对象。程序仍然只发起一次模型请求,不需要先调用“图片 API”,再调用“文本 API”。

本篇会用到三种内容块:

type用途本篇的例子
text告诉模型要完成什么任务描述图片、提取文档要点
image_url提供图片 URL 或图片数据本地 product.jpg
file提供受支持的文件数据本地 notice.pdf

需要注意, SDK 能组织这种请求,不代表每个模型都能处理全部类型 。模型本身要具备相应能力,AIHubMix 的对应接口也需要支持传递这种内容。OpenAI 的 Chat Completions 文件内容块目前支持 PDF;其他普通文件不能直接照搬本例的 file 写法。

使用支持图片和 PDF 的模型

沿用第一篇的 ai-sdk-course 项目,环境为 Node.js 24.x、openai@7.62.0 ,不需要重新安装 SDK。

前面的 .env 可能配置了 gpt-4o-mini。在 AIHubMix 当前的模型说明中,它的图像输入能力是明确的,但 PDF 支持情况不能仅凭模型名称推断。为了让下面两个示例使用同一模型,可先将 .env 的模型一项改为:

AI_MODEL=gpt-4.1-mini

AI_API_KEY 和 AI_BASE_URL 保持原样。AIHubMix 的模型目录列出了 gpt-4.1-mini 的图片与 PDF 输入能力;但 模型列表标记支持 PDF,不等于已经验证该账户通过 Chat Completions 的 file 请求一定成功 。如果平台返回不支持的错误,请以实际模型详情、接口说明及响应信息为准,不要通过反复重试消耗额度。

平台模型列表、价格和支持能力会更新。请先在 AIHubMix 模型目录 核对模型 ID、输入能力和价格,再运行带图片或 PDF 的请求。

🛠 让模型描述一张商品图片

先在项目根目录放入一张 product.jpg。建议选择内容清晰、没有隐私信息的商品照片,例如白底的保温杯;这样能够直接对照图片检查模型有没有凭空补充信息。

创建 07.image.mjs:

import OpenAI from "openai";
import { readFile } from "node:fs/promises";

const client = new OpenAI({
    apiKey: process.env.AI_API_KEY,
    baseURL: process.env.AI_BASE_URL
});

const image = await readFile("./product.jpg");
const dataUrl = `data:image/jpeg;base64,${image.toString("base64")}`;

const response = await client.chat.completions.create({
    model: process.env.AI_MODEL,
    messages: [
        {
            role: "user",
            content: [
                {
                    type: "text",
                    text: "请客观描述这张商品图片中能看到的内容,不要猜测价格、材质或其他看不清的信息。"
                },
                {
                    type: "image_url",
                    image_url: { url: dataUrl }
                }
            ]
        }
    ]
});

console.log("图片描述:", response.choices[0].message.content);

使用前面已经验证过的代理命令运行:

HTTPS_PROXY=http://127.0.0.1:7890 NODE_USE_ENV_PROXY=1 node --env-file=.env 07.image.mjs

假设你准备的是一张银色保温杯的照片,终端可能输出:

图片描述: 图片中有一个带杯盖的银色杯子,放在浅色背景上。图片没有清晰展示价格信息。

以上是 根据假设图片编写的示意结果 ,不是在线 API 的真实输出。实际回答取决于你使用的图片和模型。

本地图片为什么要转换成 Data URL?

模型服务无法直接读取你电脑上的 ./product.jpg 路径。示例先读取图片内容,再编码为 Data URL:

data:image/jpeg;base64,<图片内容的 Base64 编码>

其中 image/jpeg 声明图片格式,后面的 Base64 是图片数据。image_url.url 虽然叫 URL,但这里传入的是 包含实际图片数据的 Data URL ,不是本地文件路径,也不是公开网络链接。

本例固定使用 JPEG。若换成 PNG 图片,应同时改为正确文件名和 data:image/png;base64,,不能只改扩展名而不改真实文件格式。

对比前面的纯文本请求,这里真正新增的知识只有一点:content 中同时放入 text 和 image_url 两个内容块,模型就能结合文字问题分析图片。它能识别可见内容,但小字、遮挡和商品属性推断仍可能出错。


🛠 让模型提取 PDF 中的信息

图片理解解决的是“看图回答”,PDF 输入则用于让模型阅读用户提供的文档。这里继续使用相同的 Chat Completions 接口,不切换到 Responses API。

准备一份可以验证结果的 PDF

在项目根目录准备 notice.pdf。可以使用本课程附带的示例文件,也可以把下面的内容粘贴到任意文档编辑器中,导出为 PDF:

商品售后说明(教学示例)

  1. 收货后 7 天内,符合条件的商品可以申请退货。
  2. 商品主体出现质量问题,享有 12 个月保修服务。
  3. 申请售后时,需要提供订单号或购买凭证。

这是一份虚构的练习材料,并不是实际商家的售后政策。使用固定内容的好处是:模型返回的要点能与原文逐条核对。

创建 07.file.mjs:

import OpenAI from "openai";
import { readFile } from "node:fs/promises";

const client = new OpenAI({
    apiKey: process.env.AI_API_KEY,
    baseURL: process.env.AI_BASE_URL
});

const pdf = await readFile("./notice.pdf");
const fileData = `data:application/pdf;base64,${pdf.toString("base64")}`;

const response = await client.chat.completions.create({
    model: process.env.AI_MODEL,
    messages: [
        {
            role: "user",
            content: [
                {
                    type: "text",
                    text: "请根据这份售后说明列出三个要点,只提取文档明确写出的内容。"
                },
                {
                    type: "file",
                    file: {
                        filename: "notice.pdf",
                        file_data: fileData
                    }
                }
            ]
        }
    ]
});

console.log("文档要点:", response.choices[0].message.content);

运行:

HTTPS_PROXY=http://127.0.0.1:7890 NODE_USE_ENV_PROXY=1 node --env-file=.env 07.file.mjs

如果所选模型和 AIHubMix 的对应接口支持这种 PDF 输入,模型可能返回:

文档要点:
1. 收货后 7 天内,符合条件的商品可以申请退货。
2. 商品主体质量问题享有 12 个月保修服务。
3. 申请售后需要提供订单号或购买凭证。

这是 对应示例 PDF 内容的预期输出示意 ,并非真实请求结果。你可以把回答和 PDF 中的三条规则逐一对照,检查是否遗漏或添加了原文没有的条件。

file 内容块包含什么?

这里与图片示例最大的区别是文件内容块:

{
    type: "file",
    file: {
        filename: "notice.pdf",
        file_data: fileData
    }
}

filename 提供文件名,file_data 则携带 PDF 的实际内容。data:application/pdf;base64, 表示这些数据来自 PDF 文件。

因此, 发送文件名不等于发送文件 :真正供模型分析的是 file_data。在支持的模型和接口中,PDF 可能通过文字提取及页面图像参与理解,尤其是带有布局或表格的文档,但这也可能增加输入用量。

如果只需要分析应用已经读取到的一小段纯文本,直接把文字放入 type: "text" 就可以,不一定要先生成或上传 PDF。

⚠️ 多模态输入有哪些限制?

需要检查为什么重要
模型与接口支持图片的模型不一定支持 PDF;聚合平台是否转发 file 内容块也要实际确认
输入格式与体积MIME 类型应与文件内容匹配,并遵守所选接口的格式、大小和页数限制
结果可信度模型可能漏看图片细节、误读表格或提取出原文不存在的信息,重要业务应核对原始材料
隐私与费用文件会提交到第三方 API;图片和 PDF 的输入成本不能只按可见文字数量估算

如果 PDF 请求提示不支持文件输入,先检查模型详情和 API 返回的错误信息。对于不支持直接传 PDF 的接口,可以由 Node.js 先提取 PDF 文本,再作为普通文本消息发送 ;不过,这种方式无法自动保留图片、复杂排版等信息,属于不同的处理路线,本篇不展开 PDF 解析代码。

本篇只处理 把图片或文档作为当前请求的输入 。批量文档入库、切分、向量检索等能力将在 RAG 课程中介绍,不需要在这里提前实现知识库。


❓ 知识问答

Q1:为什么不能直接将 ./product.jpg 或 ./notice.pdf 发送给模型?

它们是你电脑上的本地路径,远程 API 无法按这个路径访问文件。本篇通过 Data URL 把文件内容放进请求;也可以在接口支持时使用公开可访问的文件 URL 或供应商的文件上传能力,但不同内容类型的支持方式可能不同。

Q2:已经用了支持 PDF 的模型,为什么 type: "file" 仍可能报错?

除了模型能力,还要看当前使用的 API 协议和 AIHubMix 对这种内容块的支持情况。一个模型支持 PDF,并不意味着它在所有兼容接口上都接受同样的字段;应根据实际报错确认支持的接入方式。


🧪 小练习

  1. 图片理解 :用一张不包含私人信息的商品图片,分别询问“图中有哪些可见物品?”和“图片是否明确标注价格?”。检查模型是否区分了可见事实与推测。
  2. PDF 分析 :修改 notice.pdf 中的保修期限(例如从 12 个月改为 6 个月)并重新导出,再运行 07.file.mjs,核对模型是否准确读取新期限,而不是继续沿用之前的内容。

验证标准: 能独立构造 text + image_url 与 text + file 的消息内容,使用真实文件完成请求,并能对照原始材料判断回答是否准确。如果平台不支持 PDF 内容块,能够从模型和接口兼容性方面定位问题,而不是把接口报错误认为 PDF 内容有误。


🎉 你已经掌握了通过 OpenAI SDK 向模型发送图片和 PDF 的基本方式。接下来学习如何通过 Express 开发 AI 服务接口。