多模态输入
🎯 引言
前面我们一直通过 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 请求一定成功 。如果平台返回不支持的错误,请以实际模型详情、接口说明及响应信息为准,不要通过反复重试消耗额度。
🛠 让模型描述一张商品图片
先在项目根目录放入一张 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:
商品售后说明(教学示例)
- 收货后 7 天内,符合条件的商品可以申请退货。
- 商品主体出现质量问题,享有 12 个月保修服务。
- 申请售后时,需要提供订单号或购买凭证。
这是一份虚构的练习材料,并不是实际商家的售后政策。使用固定内容的好处是:模型返回的要点能与原文逐条核对。
创建 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,并不意味着它在所有兼容接口上都接受同样的字段;应根据实际报错确认支持的接入方式。
🧪 小练习
- 图片理解 :用一张不包含私人信息的商品图片,分别询问“图中有哪些可见物品?”和“图片是否明确标注价格?”。检查模型是否区分了可见事实与推测。
- PDF 分析 :修改
notice.pdf中的保修期限(例如从 12 个月改为 6 个月)并重新导出,再运行07.file.mjs,核对模型是否准确读取新期限,而不是继续沿用之前的内容。
验证标准: 能独立构造 text + image_url 与 text + file 的消息内容,使用真实文件完成请求,并能对照原始材料判断回答是否准确。如果平台不支持 PDF 内容块,能够从模型和接口兼容性方面定位问题,而不是把接口报错误认为 PDF 内容有误。
🎉 你已经掌握了通过 OpenAI SDK 向模型发送图片和 PDF 的基本方式。接下来学习如何通过 Express 开发 AI 服务接口。
