Skip to Content

07c - 多模态能力实战

本文是《AI Agent 实战手册》第 7 章第 3 节。 上一节:百万 Token 上下文实战 | 下一节:API 集成指南

概述

Gemini 从架构层面就是原生多模态模型——文本、图像、视频、音频和 PDF 在同一个推理核心中统一处理,而非通过独立模块拼接。从 Gemini 2.5 Pro 到 3 Pro 再到 3.1 Pro,多模态能力经历了质的飞跃:MMMU-Pro(图文推理)从 68.0% 跃升至 81.0%,ScreenSpot-Pro(屏幕理解)从 11.4% 飙升至 72.7%,Video-MMMU(视频理解)达到 87.6%。本节将系统讲解如何在实际项目中利用 Gemini 的多模态能力,覆盖图像理解、视频分析、音频处理和 PDF 解析四大核心场景,每个场景均提供 Python 和 TypeScript 双语言代码示例。


1. 多模态能力演进(2.5 → 3 → 3.1)

1.1 多模态基准成绩对比

基准测试Gemini 2.5 ProGemini 3 ProGemini 3.1 Pro竞品最佳说明
MMMU-Pro(图文推理)68.0%81.0%≥81.0%GPT-5.2: 76.0%多学科图文混合推理
Video-MMMU(视频理解)83.6%87.6%≥87.6%GPT-5.2: 80.4%视频内容深度理解
ScreenSpot-Pro(屏幕理解)11.4%72.7%≥72.7%Claude: 36.2%UI 截图元素定位与理解
OCR(OmniDocBench)0.1450.115≤0.115文档 OCR 错误率(越低越好)
MMMU(多模态理解)82.0%87.5%≥87.5%GPT-5.2: 86.7%多模态综合理解

💡 关键洞察:ScreenSpot-Pro 的跃升最为惊人——从 2.5 Pro 的 11.4% 到 3 Pro 的 72.7%,提升超过 6 倍。这意味着 Gemini 3 Pro 能够精确理解 UI 截图中的按钮、输入框、菜单等元素位置,为 Computer Use(自动化 GUI 操作)奠定了基础。

1.2 各代多模态能力对比

Gemini 2.5 Pro Gemini 3 Pro Gemini 3.1 Pro ┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐ │ 图像理解(基础) │ │ 图像理解(精确) │ │ 图像理解(精确+) │ │ 视频分析(基础) │ │ 视频分析(深度) │ │ 视频分析(深度+) │ │ 音频处理(转录) │ ──→ │ 音频处理(理解+情感) │ ──→ │ 音频处理(理解+情感+)│ │ PDF 解析(文本提取) │ │ PDF 解析(版面保持) │ │ PDF 解析(版面保持+) │ │ OCR: 0.145 │ │ OCR: 0.115 │ │ OCR: ≤0.115 │ │ ScreenSpot: 11.4% │ │ ScreenSpot: 72.7% │ │ ScreenSpot: ≥72.7% │ │ 无 Computer Use │ │ ✅ Computer Use │ │ ✅ Computer Use │ └─────────────────────┘ └─────────────────────┘ └─────────────────────┘

1.3 支持的输入格式

模态支持格式大小限制Token 消耗
图像JPEG, PNG, WebP, HEIC, HEIF内联 <20MB;File API 最大 2GB258 tokens(≤384px);大图按 768×768 分块,每块 258 tokens
视频MP4, MPEG, MOV, AVI, FLV, WebM, 3GPPFile API 最大 2GB每秒约 263 tokens(图像帧 + 音频)
音频MP3, WAV, AIFF, AAC, OGG, FLACFile API 最大 2GB每秒约 32 tokens
PDFPDF内联 <20MB;File API 最大 2GB每页约 258-770 tokens(取决于页面复杂度)

1.4 工具推荐

工具用途价格适用场景
Google AI Studio 在线多模态测试免费快速上传图片/视频/音频测试,可视化结果
Gemini API(Developer) 开发者 API免费层 + 付费层应用集成、自动化多模态工作流
Vertex AI 企业级 AI 平台按用量计费生产部署、合规需求
Gemini CLI 终端 AI 助手免费(开源)命令行快速分析图片/文件
NotebookLM 文档交互式问答免费PDF 文档的交互式多模态分析

1.5 多模态 Token 价格

多模态输入与文本输入使用相同的 token 计费体系,无额外多模态附加费:

模型输入(≤200K)输入(>200K)输出音频输入
Gemini 3.1 Pro / 3 Pro$2.00/1M$4.00/1M$12.00/1M$2.00/1M
Gemini 3 Flash$0.50/1M$3.00/1M$0.50/1M
Gemini 2.5 Flash$0.30/1M$2.50/1M$0.30/1M

⚠️ 成本提示:一张高分辨率图片(如 4K 截图)可能消耗 1,000-2,000 tokens;一段 10 分钟视频约消耗 158,000 tokens(接近 200K 价格阶梯)。处理大量多模态内容时,务必先用 count_tokens 预估成本。


2. 图像理解

Gemini 的图像理解能力覆盖图表分析、OCR 文字识别、UI 截图解读、物体检测与分割等场景。

操作步骤

步骤 1:基础图像分析(Python)

from google import genai from google.genai import types import os client = genai.Client(api_key=os.environ["GEMINI_API_KEY"]) # 方式 1:从本地文件读取(适合 <20MB 的图片) with open("./chart.png", "rb") as f: image_bytes = f.read() response = client.models.generate_content( model="gemini-3-pro", contents=[ types.Part.from_bytes(data=image_bytes, mime_type="image/png"), "请分析这张图表,提取关键数据点,描述趋势,并给出业务洞察。" ] ) print(response.text) # 方式 2:通过 File API 上传(适合大文件或重复使用) uploaded = client.files.upload(file="./dashboard_screenshot.png") response = client.models.generate_content( model="gemini-3-pro", contents=[uploaded, "请描述这个仪表盘中的所有指标和它们的当前状态。"] ) print(response.text)

步骤 2:基础图像分析(TypeScript)

import { GoogleGenAI, createUserContent, createPartFromUri } from "@google/genai"; import * as fs from "node:fs"; const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY }); // 方式 1:内联 Base64 数据 const imageBuffer = fs.readFileSync("./chart.png"); const base64Image = imageBuffer.toString("base64"); const response = await ai.models.generateContent({ model: "gemini-3-pro", contents: [ { inlineData: { mimeType: "image/png", data: base64Image } }, { text: "请分析这张图表,提取关键数据点,描述趋势,并给出业务洞察。" }, ], }); console.log(response.text); // 方式 2:通过 File API 上传 const uploaded = await ai.files.upload({ file: "./dashboard_screenshot.png", config: { mimeType: "image/png" }, }); const response2 = await ai.models.generateContent({ model: "gemini-3-pro", contents: createUserContent([ createPartFromUri(uploaded.uri!, uploaded.mimeType!), "请描述这个仪表盘中的所有指标和它们的当前状态。", ]), }); console.log(response2.text);

步骤 3:OCR 文字识别(Python)

from google import genai from google.genai import types import os, json client = genai.Client(api_key=os.environ["GEMINI_API_KEY"]) with open("./receipt.jpg", "rb") as f: image_bytes = f.read() # 结构化 OCR 提取 response = client.models.generate_content( model="gemini-3-pro", contents=[ types.Part.from_bytes(data=image_bytes, mime_type="image/jpeg"), """请对这张收据/发票进行 OCR 识别,提取以下信息并以 JSON 格式返回: { "merchant_name": "商家名称", "date": "日期", "items": [{"name": "商品名", "quantity": 数量, "price": 单价}], "subtotal": 小计, "tax": 税额, "total": 总计, "payment_method": "支付方式" }""" ], config={"response_mime_type": "application/json"} ) receipt_data = json.loads(response.text) print(json.dumps(receipt_data, ensure_ascii=False, indent=2))

步骤 4:OCR 文字识别(TypeScript)

import { GoogleGenAI } from "@google/genai"; import * as fs from "node:fs"; const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY }); const imageBuffer = fs.readFileSync("./receipt.jpg"); const base64Image = imageBuffer.toString("base64"); const response = await ai.models.generateContent({ model: "gemini-3-pro", contents: [ { inlineData: { mimeType: "image/jpeg", data: base64Image } }, { text: `请对这张收据/发票进行 OCR 识别,提取以下信息并以 JSON 格式返回: { "merchant_name": "商家名称", "date": "日期", "items": [{"name": "商品名", "quantity": "数量", "price": "单价"}], "subtotal": "小计", "tax": "税额", "total": "总计", "payment_method": "支付方式" }`, }, ], config: { responseMimeType: "application/json" }, }); const receiptData = JSON.parse(response.text!); console.log(JSON.stringify(receiptData, null, 2));

步骤 5:UI 截图解读与 Computer Use

Gemini 3 Pro 在 ScreenSpot-Pro 基准上达到 72.7%,能够精确理解 UI 截图中的元素位置,这是 Computer Use 功能的基础。

from google import genai from google.genai import types import os client = genai.Client(api_key=os.environ["GEMINI_API_KEY"]) with open("./app_screenshot.png", "rb") as f: screenshot_bytes = f.read() # UI 截图分析:识别元素和交互建议 response = client.models.generate_content( model="gemini-3-pro", contents=[ types.Part.from_bytes(data=screenshot_bytes, mime_type="image/png"), """请分析这个应用截图: 1. 识别所有可交互的 UI 元素(按钮、输入框、链接、菜单等) 2. 描述当前页面的功能和状态 3. 指出可能的 UX 问题(对比度不足、按钮太小、布局混乱等) 4. 给出改进建议""" ] ) print(response.text)

步骤 6:物体检测(Python)

Gemini 3 Pro 支持返回物体的边界框坐标(归一化到 0-1000),可用于精确定位图像中的物体。

from google import genai from google.genai import types import os, json client = genai.Client(api_key=os.environ["GEMINI_API_KEY"]) with open("./product_photo.jpg", "rb") as f: image_bytes = f.read() response = client.models.generate_content( model="gemini-3-pro", contents=[ types.Part.from_bytes(data=image_bytes, mime_type="image/jpeg"), "检测图像中所有物体,返回 JSON 格式,每个物体包含 label 和 box_2d([ymin, xmin, ymax, xmax],归一化到 0-1000)。" ], config={"response_mime_type": "application/json"} ) objects = json.loads(response.text) for obj in objects: print(f"物体: {obj['label']}, 位置: {obj['box_2d']}")

提示词模板

你是一位专业的 [图像分析/OCR/UI 审查] 专家。 请分析上传的图像,完成以下任务: 1. [具体分析任务,如:提取图表中的所有数据点] 2. [具体分析任务,如:识别图中的文字内容] 3. [具体分析任务,如:评估 UI 设计的可用性] 输出要求: - 使用中文 - 结构化输出(表格或 JSON) - 标注置信度(高/中/低) - 如有不确定的内容,明确标注

3. 视频分析

Gemini 可处理长达约 3 小时的视频内容(取决于分辨率和帧率),支持内容理解、时间线标注、关键帧提取等任务。视频需通过 File API 上传。

操作步骤

步骤 1:上传并分析视频(Python)

import os, time from google import genai client = genai.Client(api_key=os.environ["GEMINI_API_KEY"]) # 1. 上传视频文件(支持 MP4, MOV, AVI, WebM 等) video_file = client.files.upload(file="./product_demo.mp4") # 等待视频处理完成(视频需要服务端转码) while video_file.state.name == "PROCESSING": time.sleep(5) video_file = client.files.get(name=video_file.name) print(f"视频处理完成: {video_file.uri}") print(f"视频时长: {video_file.video_metadata.video_duration}") # 2. 视频内容理解 response = client.models.generate_content( model="gemini-3-pro", contents=[ video_file, """请对这段产品演示视频进行深度分析: 1. 视频摘要(100 字以内) 2. 按时间线列出关键场景(格式:[MM:SS] 场景描述) 3. 识别演示的产品功能列表 4. 评估演示的专业度和改进建议""" ] ) print(response.text)

步骤 2:上传并分析视频(TypeScript)

import { GoogleGenAI, createUserContent, createPartFromUri, } from "@google/genai"; const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY }); // 1. 上传视频文件 let videoFile = await ai.files.upload({ file: "./product_demo.mp4", config: { mimeType: "video/mp4" }, }); // 等待视频处理完成 while (videoFile.state === "PROCESSING") { await new Promise((resolve) => setTimeout(resolve, 5000)); videoFile = await ai.files.get({ name: videoFile.name! }); } console.log(`视频处理完成: ${videoFile.uri}`); // 2. 视频内容理解 const response = await ai.models.generateContent({ model: "gemini-3-pro", contents: createUserContent([ createPartFromUri(videoFile.uri!, videoFile.mimeType!), `请对这段产品演示视频进行深度分析: 1. 视频摘要(100 字以内) 2. 按时间线列出关键场景(格式:[MM:SS] 场景描述) 3. 识别演示的产品功能列表 4. 评估演示的专业度和改进建议`, ]), }); console.log(response.text);

步骤 3:视频时间线标注与关键帧分析(Python)

import os, time from google import genai client = genai.Client(api_key=os.environ["GEMINI_API_KEY"]) # 上传教程视频 video_file = client.files.upload(file="./tutorial_video.mp4") while video_file.state.name == "PROCESSING": time.sleep(5) video_file = client.files.get(name=video_file.name) # 时间线标注 + 章节划分 response = client.models.generate_content( model="gemini-3-pro", contents=[ video_file, """请为这段教程视频生成详细的时间线标注: 1. **章节划分**:将视频分成逻辑章节,每章包含: - 起止时间 [MM:SS - MM:SS] - 章节标题 - 内容摘要(1-2 句话) 2. **关键帧标注**:识别最重要的 5-10 个关键时刻: - 时间戳 [MM:SS] - 画面描述 - 为什么这个时刻重要 3. **知识点提取**:列出视频中讲解的所有知识点 4. **适合做缩略图的帧**:推荐 3 个最适合作为视频缩略图的时间点,说明原因 输出格式:使用 Markdown 表格。""" ], config={"thinking_config": {"thinking_level": "HIGH"}} ) print(response.text)

步骤 4:视频内容审核(TypeScript)

import { GoogleGenAI, createUserContent, createPartFromUri, } from "@google/genai"; const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY }); // 上传待审核视频 let videoFile = await ai.files.upload({ file: "./user_uploaded_video.mp4", config: { mimeType: "video/mp4" }, }); while (videoFile.state === "PROCESSING") { await new Promise((r) => setTimeout(r, 5000)); videoFile = await ai.files.get({ name: videoFile.name! }); } // 内容审核 const response = await ai.models.generateContent({ model: "gemini-3-pro", contents: createUserContent([ createPartFromUri(videoFile.uri!, videoFile.mimeType!), `请对这段用户上传的视频进行内容审核,检查以下维度: 1. **安全性**:是否包含暴力、危险行为、有害内容? 2. **合规性**:是否包含版权音乐、商标、敏感信息? 3. **质量评估**:画面质量、音频质量、内容连贯性(1-10 分) 4. **内容分类**:视频属于什么类别?(教育/娱乐/产品/新闻等) 5. **关键词标签**:生成 5-10 个描述性标签 输出 JSON 格式: { "safe": true/false, "safety_issues": [], "compliance_issues": [], "quality_score": 8, "category": "教育", "tags": ["标签1", "标签2"], "summary": "视频摘要" }`, ]), config: { responseMimeType: "application/json" }, }); const auditResult = JSON.parse(response.text!); console.log(JSON.stringify(auditResult, null, 2));

4. 音频处理

Gemini 原生支持音频输入,可进行语音转文字、音频内容分析、说话人识别、情感分析等任务。支持 MP3、WAV、AAC、OGG、FLAC 等格式。

操作步骤

步骤 1:语音转文字与内容分析(Python)

import os, time from google import genai client = genai.Client(api_key=os.environ["GEMINI_API_KEY"]) # 上传音频文件 audio_file = client.files.upload(file="./meeting_recording.mp3") while audio_file.state.name == "PROCESSING": time.sleep(3) audio_file = client.files.get(name=audio_file.name) # 语音转文字 + 内容分析 response = client.models.generate_content( model="gemini-3-pro", contents=[ audio_file, """请对这段音频进行以下处理: 1. **完整转录**:将语音内容转录为文字,保留说话人标记(如 Speaker A、Speaker B) 2. **内容摘要**:100 字以内的核心内容概括 3. **关键决策**:列出讨论中做出的所有决策 4. **行动项**:提取所有待办事项(含负责人和截止日期,如果提到的话) 5. **情感分析**:整体讨论氛围(积极/中性/消极),标注情绪转折点的时间戳""" ] ) print(response.text)

步骤 2:语音转文字与内容分析(TypeScript)

import { GoogleGenAI, createUserContent, createPartFromUri, } from "@google/genai"; const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY }); // 上传音频文件 let audioFile = await ai.files.upload({ file: "./meeting_recording.mp3", config: { mimeType: "audio/mp3" }, }); while (audioFile.state === "PROCESSING") { await new Promise((r) => setTimeout(r, 3000)); audioFile = await ai.files.get({ name: audioFile.name! }); } // 语音转文字 + 内容分析 const response = await ai.models.generateContent({ model: "gemini-3-pro", contents: createUserContent([ createPartFromUri(audioFile.uri!, audioFile.mimeType!), `请对这段音频进行以下处理: 1. **完整转录**:将语音内容转录为文字,保留说话人标记 2. **内容摘要**:100 字以内的核心内容概括 3. **关键决策**:列出讨论中做出的所有决策 4. **行动项**:提取所有待办事项 5. **情感分析**:整体讨论氛围和情绪转折点`, ]), }); console.log(response.text);

步骤 3:播客/长音频深度分析(Python)

import os, time from google import genai from google.genai import types client = genai.Client(api_key=os.environ["GEMINI_API_KEY"]) # 上传长音频(Gemini 支持最长约 11 小时音频) audio_file = client.files.upload(file="./podcast_episode.mp3") while audio_file.state.name == "PROCESSING": time.sleep(5) audio_file = client.files.get(name=audio_file.name) # 创建缓存以支持多轮分析 cache = client.caches.create( model="gemini-3-pro", config=types.CreateCachedContentConfig( display_name="podcast-analysis", system_instruction="你是一位专业的播客内容分析师。", contents=[audio_file], ttl="3600s", ) ) # 第一轮:整体分析 response1 = client.models.generate_content( model="gemini-3-pro", contents="请生成这期播客的完整大纲,按时间线标注每个话题的起止时间。", config=types.GenerateContentConfig(cached_content=cache.name) ) print("=== 播客大纲 ===") print(response1.text) # 第二轮:提取可引用内容 response2 = client.models.generate_content( model="gemini-3-pro", contents="请提取播客中最有价值的 5 段引用,标注时间戳,适合在社交媒体上分享。", config=types.GenerateContentConfig(cached_content=cache.name) ) print("\n=== 精彩引用 ===") print(response2.text)

步骤 4:多语言音频处理(TypeScript)

import { GoogleGenAI, createUserContent, createPartFromUri, } from "@google/genai"; const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY }); let audioFile = await ai.files.upload({ file: "./multilingual_call.wav", config: { mimeType: "audio/wav" }, }); while (audioFile.state === "PROCESSING") { await new Promise((r) => setTimeout(r, 3000)); audioFile = await ai.files.get({ name: audioFile.name! }); } // 多语言音频分析 const response = await ai.models.generateContent({ model: "gemini-3-pro", contents: createUserContent([ createPartFromUri(audioFile.uri!, audioFile.mimeType!), `这是一段可能包含多种语言的音频。请: 1. 识别音频中使用的所有语言 2. 按说话人和语言分段转录 3. 将所有非中文内容翻译为中文 4. 生成统一的中文摘要`, ]), }); console.log(response.text);

提示词模板

请对上传的 [音频/视频] 文件进行深度分析: 分析维度: 1. **内容转录**:完整转录,标注说话人和时间戳 [HH:MM:SS] 2. **主题提取**:识别 [数量] 个核心主题 3. **情感分析**:评估语气变化和关键情绪转折点 4. **[自定义维度]**:[如:提取所有提到的工具/书籍/资源] 5. **行动项提取**:列出所有待办事项和决策 输出要求: - 使用中文 - 关键引用标注时间戳(格式:[HH:MM:SS]) - 使用 Markdown 表格汇总结构化信息

5. PDF 解析

Gemini 使用原生视觉能力处理 PDF,不仅提取文本,还能理解版面布局、图表、表格和图像内容。这比传统 OCR 工具(如 Tesseract)更准确,尤其在处理复杂排版时优势明显。

操作步骤

步骤 1:PDF 内联解析(Python)

from google import genai from google.genai import types import os, httpx client = genai.Client(api_key=os.environ["GEMINI_API_KEY"]) # 方式 1:从本地文件读取 PDF with open("./technical_report.pdf", "rb") as f: pdf_bytes = f.read() response = client.models.generate_content( model="gemini-3-pro", contents=[ types.Part.from_bytes(data=pdf_bytes, mime_type="application/pdf"), """请对这份技术报告进行结构化解析: 1. 提取文档标题、作者、日期 2. 生成目录结构 3. 提取所有表格数据(保持表格格式) 4. 描述所有图表的内容和关键数据 5. 生成 500 字以内的执行摘要""" ] ) print(response.text) # 方式 2:从 URL 获取 PDF pdf_url = "https://example.com/report.pdf" pdf_data = httpx.get(pdf_url).content response = client.models.generate_content( model="gemini-3-pro", contents=[ types.Part.from_bytes(data=pdf_data, mime_type="application/pdf"), "请总结这份文档的核心内容。" ] ) print(response.text)

步骤 2:PDF 内联解析(TypeScript)

import { GoogleGenAI } from "@google/genai"; import * as fs from "node:fs"; const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY }); // 从本地文件读取 PDF const pdfBuffer = fs.readFileSync("./technical_report.pdf"); const base64Pdf = pdfBuffer.toString("base64"); const response = await ai.models.generateContent({ model: "gemini-3-pro", contents: [ { inlineData: { mimeType: "application/pdf", data: base64Pdf } }, { text: `请对这份技术报告进行结构化解析: 1. 提取文档标题、作者、日期 2. 生成目录结构 3. 提取所有表格数据(保持表格格式) 4. 描述所有图表的内容和关键数据 5. 生成 500 字以内的执行摘要`, }, ], }); console.log(response.text);

步骤 3:大型 PDF 文档集分析(Python)

import os, time from google import genai from google.genai import types client = genai.Client(api_key=os.environ["GEMINI_API_KEY"]) # 上传多个 PDF 文件 pdf_dir = "./contracts/" uploaded_pdfs = [] for fname in sorted(os.listdir(pdf_dir)): if fname.endswith(".pdf"): f = client.files.upload(file=os.path.join(pdf_dir, fname)) uploaded_pdfs.append(f) print(f"已上传: {fname}") # 等待所有文件处理完成 for f in uploaded_pdfs: while f.state.name == "PROCESSING": time.sleep(2) f = client.files.get(name=f.name) # 创建缓存以支持多轮审查 cache = client.caches.create( model="gemini-3-pro", config=types.CreateCachedContentConfig( display_name="contract-bundle", system_instruction=( "你是一位资深法律顾问。以下是一组合同文件," "请基于这些文件回答问题,引用具体合同名称和条款编号。" ), contents=uploaded_pdfs, ttl="7200s", ) ) # 多轮审查 response = client.models.generate_content( model="gemini-3-pro", contents="请对比这些合同中的关键条款差异,生成对比表格。", config=types.GenerateContentConfig( cached_content=cache.name, thinking_config=types.ThinkingConfig(thinking_level="HIGH") ) ) print(response.text)

步骤 4:PDF 转 HTML(保留版面布局)

from google import genai from google.genai import types import os client = genai.Client(api_key=os.environ["GEMINI_API_KEY"]) with open("./brochure.pdf", "rb") as f: pdf_bytes = f.read() # PDF 转 HTML,保留原始版面布局 response = client.models.generate_content( model="gemini-3-pro", contents=[ types.Part.from_bytes(data=pdf_bytes, mime_type="application/pdf"), """请将这份 PDF 文档转换为 HTML 格式: 1. 保留原始版面布局(标题层级、段落、列表) 2. 保留表格结构(使用 HTML table 标签) 3. 描述图片内容(使用 alt 文本) 4. 保留字体强调(粗体、斜体) 5. 使用语义化 HTML 标签(h1-h6, p, ul, ol, table 等) 只输出 HTML 代码,不要包含 <html>、<head>、<body> 等外层标签。""" ] ) # 保存为 HTML 文件 with open("./output.html", "w", encoding="utf-8") as f: f.write(response.text) print("PDF 已转换为 HTML")

实战案例 1:电商产品图片批量分析管线

场景

一个电商平台需要对卖家上传的产品图片进行自动化质量审核和信息提取:检查图片质量、提取产品属性、生成 SEO 描述、检测违规内容。

操作流程

import os, json from google import genai from google.genai import types client = genai.Client(api_key=os.environ["GEMINI_API_KEY"]) def analyze_product_image(image_path: str) -> dict: """分析单张产品图片,返回结构化结果""" with open(image_path, "rb") as f: image_bytes = f.read() response = client.models.generate_content( model="gemini-3-pro", contents=[ types.Part.from_bytes(data=image_bytes, mime_type="image/jpeg"), """请分析这张产品图片,返回 JSON 格式结果: { "quality": { "resolution_adequate": true/false, "lighting_quality": "good/fair/poor", "background_clean": true/false, "product_centered": true/false, "overall_score": 1-10 }, "product_info": { "category": "产品类别", "color": "颜色", "material": "材质(如果可见)", "brand_visible": true/false, "brand_name": "品牌名(如果可见)" }, "seo": { "title": "SEO 友好的产品标题(50 字以内)", "description": "产品描述(150 字以内)", "tags": ["标签1", "标签2", "标签3"] }, "compliance": { "contains_text_overlay": true/false, "contains_watermark": true/false, "contains_prohibited_content": false, "issues": [] } }""" ], config={"response_mime_type": "application/json"} ) return json.loads(response.text) # 批量处理产品图片 image_dir = "./product_images/" results = [] for fname in os.listdir(image_dir): if fname.lower().endswith((".jpg", ".jpeg", ".png", ".webp")): path = os.path.join(image_dir, fname) print(f"分析中: {fname}") result = analyze_product_image(path) result["filename"] = fname results.append(result) # 生成审核报告 passed = [r for r in results if r["quality"]["overall_score"] >= 7] failed = [r for r in results if r["quality"]["overall_score"] < 7] print(f"\n审核完成: {len(passed)} 张通过, {len(failed)} 张需修改") for r in failed: print(f" ❌ {r['filename']}: 评分 {r['quality']['overall_score']}/10") if r["compliance"]["issues"]: print(f" 问题: {', '.join(r['compliance']['issues'])}")

案例分析

  • 为什么选 Gemini 3 Pro:MMMU-Pro 81.0% 的成绩保证了图像理解的准确性;结构化 JSON 输出让结果可以直接集成到后端系统
  • 成本估算:假设每张图片约 500 tokens(中等分辨率),处理 1000 张图片的输入成本约 $0.001(1000 × 500 / 1M × $2),加上输出约 $0.012,总计不到 $0.02
  • 优化建议:对于大批量处理,使用 Batch API 可再省 50%;使用 Gemini 3 Flash 替代 Pro 可将成本降至 1/4,且图像理解质量差距不大

实战案例 2:会议录像自动生成纪要与行动项

场景

团队每周有 2-3 次线上会议(每次 30-90 分钟),需要自动生成会议纪要、提取行动项、并同步到项目管理工具。

操作流程

import os, time, json from google import genai from google.genai import types client = genai.Client(api_key=os.environ["GEMINI_API_KEY"]) def process_meeting_video(video_path: str) -> dict: """处理会议录像,生成结构化纪要""" # 1. 上传视频 video_file = client.files.upload(file=video_path) while video_file.state.name == "PROCESSING": time.sleep(5) video_file = client.files.get(name=video_file.name) # 2. 生成结构化会议纪要 response = client.models.generate_content( model="gemini-3-pro", contents=[ video_file, """请分析这段会议录像,生成结构化会议纪要,返回 JSON 格式: { "meeting_info": { "date": "会议日期(从视频内容推断)", "duration_minutes": 预估时长, "participants": ["参与者1", "参与者2"], "topic": "会议主题" }, "summary": "会议摘要(200 字以内)", "agenda_items": [ { "topic": "议题", "time_range": "MM:SS - MM:SS", "discussion_points": ["要点1", "要点2"], "decisions": ["决策1"], "open_questions": ["待解决问题"] } ], "action_items": [ { "task": "任务描述", "assignee": "负责人", "deadline": "截止日期(如果提到)", "priority": "high/medium/low" } ], "key_quotes": [ { "speaker": "说话人", "quote": "引用内容", "timestamp": "MM:SS" } ], "next_meeting": "下次会议安排(如果提到)" }""" ], config={ "response_mime_type": "application/json", "thinking_config": {"thinking_level": "HIGH"} } ) return json.loads(response.text) # 处理会议录像 meeting = process_meeting_video("./weekly_standup.mp4") # 输出会议纪要 print(f"📋 会议主题: {meeting['meeting_info']['topic']}") print(f"📝 摘要: {meeting['summary']}") print(f"\n🎯 行动项 ({len(meeting['action_items'])} 项):") for item in meeting["action_items"]: print(f" - [{item['priority']}] {item['task']}{item['assignee']}")

案例分析

  • 为什么用视频而非纯音频:视频包含屏幕共享内容(如演示的 PPT、代码、设计稿),Gemini 可以同时理解视觉和语音内容,生成更完整的纪要
  • Video-MMMU 87.6% 的实际意义:模型能准确理解视频中展示的图表、代码片段和 UI 设计,不仅仅是转录语音
  • 成本估算:一段 60 分钟会议视频约消耗 ~950K tokens(接近 1M 上下文窗口),输入成本约 $3.80(>200K 阶梯),输出约 $0.12,总计约 $3.92。使用缓存可在多轮分析时大幅降低成本

避坑指南

❌ 常见错误

  1. 视频未等待处理完成就发送请求

    • 问题:通过 File API 上传的视频需要服务端转码,状态为 PROCESSING 时发送请求会失败
    • 正确做法:轮询 file.state 直到变为 ACTIVE,再发送请求
  2. 忽略图片分辨率对 token 消耗的影响

    • 问题:一张 4K 图片可能消耗 2,000+ tokens,批量处理时成本快速累积
    • 正确做法:使用 media_resolution 参数控制分辨率;对于不需要精细分析的场景,先压缩图片再上传
  3. 将大量小图片逐个发送请求

    • 问题:每次 API 调用都有网络开销和延迟,逐个处理效率极低
    • 正确做法:Gemini 支持单次请求最多 3,600 张图片,将多张图片合并到一个请求中批量处理
  4. 音频/视频文件超过 File API 限制

    • 问题:File API 单文件最大 2GB,超长视频可能超限
    • 正确做法:将超长视频分段上传,或先用 FFmpeg 压缩;音频可降低采样率和比特率
  5. PDF 解析时忽略页面限制

    • 问题:Gemini 支持最多约 1,000 页 PDF,超长文档可能被截断
    • 正确做法:超长 PDF 先分割为多个文件,分别上传后使用缓存进行统一分析
  6. 多模态请求忽略 200K 价格阶梯

    • 问题:一段 15 分钟视频约 240K tokens,已超过 200K 阶梯,输入价格翻倍
    • 正确做法:先用 count_tokens 预估成本;对于重复分析同一视频/音频,务必使用上下文缓存

✅ 最佳实践

  1. count_tokens 预估成本:多模态内容的 token 消耗不直观,务必在发送请求前预估
  2. 善用 media_resolution 参数:Gemini 3 引入了分辨率控制,不需要精细分析时降低分辨率可显著减少 token 消耗
  3. 批量图片合并请求:利用单次请求最多 3,600 张图片的能力,减少 API 调用次数
  4. 视频/音频用缓存:大型媒体文件的 token 消耗高,多轮分析时缓存可节省 90% 输入成本
  5. 结构化输出:使用 response_mime_type: "application/json" 获取结构化结果,便于后续程序处理
  6. 分层模型策略:简单的图片分类、OCR 用 Flash($0.50/1M);复杂的图表分析、视频理解用 Pro($2.00/1M)

相关资源与延伸阅读

资源类型说明
Gemini API 图像理解文档 官方文档图像输入、物体检测、分割的完整 API 参考
Gemini API 音频理解文档 官方文档音频输入、转录、分析的完整 API 参考
Gemini API 文档处理文档 官方文档PDF 解析、结构化提取的完整 API 参考
Gemini API 视频理解文档 官方文档视频上传、分析、时间戳标注的 API 参考
Gemini API 媒体分辨率指南 官方指南media_resolution 参数详解和 token 计算
Google AI Studio 在线工具免费在线测试多模态能力,支持上传图片/视频/音频/PDF
Gemini Cookbook — 视觉示例 代码示例官方 Cookbook 中的多模态代码示例集合
@google/genai NPM 包 SDKTypeScript/JavaScript 官方 SDK

参考来源


📖 返回 总览与导航 | 上一节:百万 Token 上下文实战 | 下一节:API 集成指南

Last updated on