多模态 API 调用实践
文本模型接起来相对简单，多模态真正难的是输入链路。
一旦接入图片、语音、PDF 或截图，前端要面对的就不只是一个 prompt，而是：
- 文件体积和上传时长。
- 预览与重试体验。
- 失败时如何告诉用户“哪里错了”。
- 隐私与敏感数据是否应该进模型。
所以多模态接入，重点不在“模型支持什么格式”，而在“你的产品链路能不能消化这些输入”。
1. 先按输入类型拆链路，不要用一个上传框打天下
多模态输入至少可以拆成三类：
| 输入类型 | 典型场景 | 前端重点 |
|---|---|---|
| 图片 | 截图分析、UI 检查、商品识别 | 压缩、裁剪、预览 |
| 音频 | 录音转写、会议摘要 | 分片上传、进度反馈 |
| 文档 | PDF 提取、合同分析 | 页数限制、结构抽取 |
如果你把这些都塞进同一条上传流程，用户体验和错误提示都会很混乱。
2. 多模态产品的第一原则：浏览器负责采集，服务端负责理解
前端适合做的事：
- 获取文件。
- 做基础预处理，如压缩、截取、格式检查。
- 展示上传与分析状态。
服务端更适合做的事：
- 鉴权与速率限制。
- 调用多模态模型。
- 把结果转成结构化输出。
- 记录请求、成本与错误。
示意代码：
const formData = new FormData()
formData.append('file', file)
formData.append('task', 'extract_ui_issues')
await $fetch('/api/ai/vision', {
method: 'POST',
body: formData,
})
前端不需要知道模型细节，它只需要知道任务名、状态和结果结构。
3. 结构化输出比“长篇解释”更适合多模态场景
图片识别、语音转写、PDF 分析最怕结果只有一段散文式回答。因为前端很难继续渲染、筛选和二次处理。
更实用的设计是要求返回结构化结果：
{
"summary": "检测到 3 个主要问题",
"issues": [
{
"type": "contrast",
"severity": "medium",
"description": "按钮文字与背景对比不足"
}
]
}
这样你才能把识别结果渲染成卡片、表格、标注或下一步工作流。
4. 一个常见失败案例：把原图直接丢给模型，结果慢、贵、还不稳定
很多团队接图片识别时，会让用户上传一张 8MB 原图，然后直接把原图转发给模型。
结果通常是：
- 上传慢。
- 处理贵。
- 出错难排查。
- 移动端体验很差。
更稳的方式是：
- 浏览器端先压缩到合理尺寸。
- 如果任务是“看局部”，先引导裁剪。
- 只上传任务需要的内容，而不是整包原始素材。
5. 隐私边界要在产品层先说清，而不是法务上线前补文案
多模态最敏感的不是模型本身，而是输入内容可能包含：
- 用户截图中的账号信息。
- 录音中的个人隐私。
- 文档中的合同、地址、手机号。
所以至少要做三件事：
- 上传前说明用途。
- 明确文件保留时长。
- 让用户知道哪些内容不要上传。
6. 适合落地的前端场景，不是“什么都识别”，而是“结果可执行”
多模态最有价值的场景，通常不是泛识别，而是和具体流程绑定：
- 截图审查后生成 UI 问题列表。
- 录音转写后生成会议纪要与待办。
- PDF 提取后生成字段摘要和风险标注。
如果识别结果不能进入后续动作，这个能力很容易变成一次性演示。
7. 上线前 Checklist
- 不同输入类型已经拆成独立链路。
- 图片、音频、文档都有明确的体积与格式限制。
- 浏览器端已做基础预处理，而不是无脑传原文件。
- 结果输出已结构化，前端可直接渲染。
- 敏感信息、存储时长和使用范围已明示。
- 已对失败场景区分上传失败、解析失败、模型失败。
- 已评估单次处理成本与平均时长。
- 已定义哪些场景可以自动化，哪些场景需要人工复核。
FAQ
多模态 API 适合直接在浏览器里调吗？
不适合。和文本调用一样，服务端代理仍然是默认方案，尤其是上传文件和计费场景。
图片越清晰越好吗？
不一定。关键是任务相关信息是否足够清晰，而不是原图越大越好。
语音转写为什么要做分片？
因为长音频上传和重试成本很高。分片能提高稳定性，也更利于断点续传。
