# Gemini 3 Pro 多模态输入处理使用 Gemini 3 Pro 处理多模式输入的综合指南，包括图像理解、视频分析、音频处理和 PDF 文档提取。该技能侧重于输入处理（分析媒体） - 有关输出（生成图像），请参阅“gemini-3-image- Generation”。 ## 概述 **Gemini 3 Pro** 提供原生多模式功能，用于理解和分析各种媒体类型。该技能涵盖所有输入处理操作，并对质量、性能和令牌消耗进行精细控制。 ### 关键功能 * **图像理解：** 物体检测、OCR、视觉问答、屏幕截图中的代码 * **视频处理：** 长达 1 小时的视频、帧分析、OCR * **音频处理：** 长达 9.5 小时的音频、语音理解 * **PDF 文档：** 本机 PDF 支持、多页分析、文本提取 * **媒体分辨率控制：** 低/中/高分辨率用于令牌优化 * **代币优化：** 对处理成本进行精细控制 ### 何时使用此技能 * 分析图像、照片或屏幕截图 * 处理视频内容以获取见解 * 转录或理解音频/语音 * 从PDF文档中提取信息 * 构建多式联运应用程序 * 优化媒体处理成本 ** ** ## 快速入门 ### 先决条件 * **Gemini API 设置**（参见 `gemini-3-pro-api` 技巧） * **支持格式的媒体文件** ### Python 快速入门将 google.generativeai 导入为 genai 从 pathlib 导入路径 genai.configure(api_key="YOUR_API_KEY") 模型 = genai.GenerativeModel("gemini-3-pro-preview") # 上传并分析图像 image_file = genai.upload_file(Path("照片.jpg")) 响应 = model.generate_content([ “这张图片里有什么？”，图像文件 ]）打印（响应.文本） ### Node.js 快速入门从“@google/generative-ai”导入 { GoogleGenerativeAI }；从“@google/generative-ai/server”导入 { GoogleAIFileManager }；从“fs”导入 fs； const genAI = new GoogleGenerativeAI("YOUR_API_KEY"); const fileManager = new GoogleAIFileManager("YOUR_API_KEY"); // 上传并分析图像 const uploadResult = 等待 fileManager.uploadFile("photo.jpg", { mimeType：“图像/jpeg” }); const model = genAI.getGenerativeModel({ model: "gemini-3-pro-preview" }); const 结果 = 等待 model.generateContent([ “这张图片里有什么？”， { fileData: { fileUri: uploadResult.file.uri, mimeType: uploadResult.file.mimeType } } ]); console.log(结果.response.text()); ** ** ## 核心任务 ### 任务 1：分析图像内容 **目标：** 从图像中提取信息、对象、文本或见解。 **使用案例：** * 物体检测与识别 * OCR（从图像中提取文本） * 视觉问答 * 从 UI 屏幕截图生成代码 * 图表/图表分析 * 产品标识 **Python 示例：** 将 google.generativeai 导入为 genai 从 pathlib 导入路径 genai.configure(api_key="YOUR_API_KEY") # 配置高分辨率模型以获得最佳质量模型 = genai.GenerativeModel( “gemini-3-pro-预览”，一代配置={ "thinking_level": "高", "media_resolution": "high" # 每个图像 1,120 个标记 } ） # 上传图片 image_path = Path("截图.png") image_file = genai.upload_file(image_path) # 根据具体提示进行分析响应 = model.generate_content([ """分析该图像并提供： 1、主要对象及其位置 2.任何可见文本（OCR） 3. 总体背景和目的 4. 如果代码/UI：描述功能 """, 图像文件 ]）打印（响应.文本） # 检查令牌使用情况 print(f"使用的令牌：{response.usage_metadata.total_token_count}") **Node.js 示例：** 从“@google/generative-ai”导入 { GoogleGenerativeAI }；从“@google/generative-ai/server”导入 { GoogleAIFileManager }； const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY!); const fileManager = new GoogleAIFileManager(process.env.GEMINI_API_KEY!); // 上传图片 const uploadResult =等待 fileManager.uploadFile("screenshot.png", { mimeType：“图像/png” }); // 配置高分辨率模型 const 模型 = genAI.getGenerativeModel({ 型号：“gemini-3-pro-preview”，生成配置：{ Thinking_level：“高”， media_resolution: "high" // OCR 的最佳质量 } }); const 结果 = 等待 model.generateContent([ `分析此图像并提供： 1、主要对象及其位置 2.任何可见文本（OCR） 3. 总体背景和目的`, { fileData: { fileUri: uploadResult.file.uri, mimeType: uploadResult.file.mimeType } } ]); console.log(结果.response.text()); **分辨率选项：** 分辨率|每个图像的令牌 |最适合 ---|---|--- `低` | 280 个代币 |快速分析，低细节 `中` | 560 个代币 |平衡的质量/成本 `高` | 1,120 个代币 | OCR、精细细节、小文本 **支持的格式：** JPEG、PNG、WEBP、HEIC、HEIF **请参阅：** `references/image-understanding.md` 了解高级模式 ** ** ### 任务 2：处理视频内容 **目标：** 分析视频内容，提取见解，执行逐帧分析。 **使用案例：** * 视频摘要 * 物体追踪 * 场景检测 * 视频OCR * 内容审核 * 教育视频分析 **Python 示例：** 将 google.generativeai 导入为 genai 从 pathlib 导入路径 genai.configure(api_key="YOUR_API_KEY") # 配置视频处理模型 = genai.GenerativeModel( “gemini-3-pro-预览”，一代配置={ "thinking_level": "高", "media_resolution": "medium" # 70 个令牌/帧（平衡） } ） # 上传视频（最长支持1小时） video_path = Path("教程.mp4") video_file = genai.upload_file(video_path) # 等待处理导入时间 while video_file.state.name == "处理中": 时间.睡眠(5) video_file = genai.get_file(video_file.name) 如果 video_file.state.name == "失败": raise ValueError("视频处理失败") # 分析视频响应 = model.generate_content([ """分析该视频并提供：一、内容总体概括 2. 关键场景和时间戳 3. 涵盖的主要议题 4. 整个视频中任何可见的文字 """, 视频文件 ]）打印（响应.文本） print(f"使用的令牌：{response.usage_metadata.total_token_count}") **Node.js 示例：** 从“@google/generative-ai”导入 { GoogleGenerativeAI }；从“@google/generative-ai/server”导入 { GoogleAIFileManager, FileState }； const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY!); const fileManager = new GoogleAIFileManager(process.env.GEMINI_API_KEY!); // 上传视频 const uploadResult =等待 fileManager.uploadFile("tutorial.mp4", { mimeType：“视频/mp4” }); // 等待处理让文件=等待fileManager.getFile(uploadResult.file.name); while (file.state === FileState.PROCESSING) { 等待新的 Promise(resolve => setTimeout(resolve, 5000)); 文件=等待fileManager.getFile(uploadResult.file.name); } if (file.state === FileState.FAILED) { throw new Error("视频处理失败"); } // 分析视频 const 模型 = genAI.getGenerativeModel({ 型号：“gemini-3-pro-preview”，生成配置：{ 媒体分辨率：“中” } }); const 结果 = 等待 model.generateContent([ `分析该视频并提供：一、总体总结 2. 关键场景和时间戳 3. 涵盖的主要主题`, { fileData: { fileUri: file.uri, mimeType: file.mimeType } } ]); console.log(结果.response.text()); **视频规格：** * **最长持续时间：** 1 小时 * **格式：** MP4、MOV、AVI 等。 * **分辨率选项：** 低（70 个令牌/帧）、中（70 个令牌/帧）、高（280 个令牌/帧） * **OCR：** 提供高分辨率 **请参阅：** `references/video-processing.md` 了解高级模式 ** ** ### 任务 3：处理音频/语音 **目标：** 转录和理解音频内容，处理语音。 **使用案例：** * 音频转录 * 语音分析 * 播客摘要 * 会议记录 * 语言理解 * 音频分类 **Python 示例：** 将 google.generativeai 导入为 genai 从 pathlib 导入路径 genai.configure(api_key="YOUR_API_KEY") 模型 = genai.GenerativeModel("gemini-3-pro-preview") # 上传音频文件（最长支持9.5小时） audio_path = 路径("podcast.mp3") 音频文件 = genai.upload_file(音频路径) # 等待处理导入时间而audio_file.state.name ==“处理中”：时间.睡眠(5) 音频文件 = genai.get_file(音频文件.名称) # 处理音频响应 = model.generate_content([ """处理此音频并提供： 1. 完整转录 2.要点总结 3. 主要发言人（如果有多位） 4. 重要时间戳 5. 行动项目或结论 """, 音频文件 ]）打印（响应.文本） print(f"使用的令牌：{response.usage_metadata.total_token_count}") **Node.js 示例：** 从“@google/generative-ai”导入 { GoogleGenerativeAI }；从“@google/generative-ai/server”导入 { GoogleAIFileManager, FileState }； const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY!); const fileManager = new GoogleAIFileManager(process.env.GEMINI_API_KEY!); // 上传音频 const uploadResult = 等待 fileManager.uploadFile("podcast.mp3", { mimeType：“音频/mp3” }); // 等待处理让文件=等待fileManager.getFile(uploadResult.file.name); while (file.state === FileState.PROCESSING) { 等待新的 Promise(resolve => setTimeout(resolve, 5000)); 文件=等待fileManager.getFile(uploadResult.file.name); } const model = genAI.getGenerativeModel({ model: "gemini-3-pro-preview" }); const 结果 = 等待 model.generateContent([ `处理该音频并提供： 1. 完整转录 2.要点总结 3.关键时间戳`, { fileData: { fileUri: file.uri, mimeType: file.mimeType } } ]); console.log(结果.response.text()); **音频规格：** * **最长持续时间：** 9.5 小时 * **格式：** WAV、MP3、FLAC、AAC 等。 * **语言：** 支持多种语言 **请参阅：** `references/audio-processing.md` 了解高级模式 ** ** ### 任务 4：处理 PDF 文档 **目标：** 从 PDF 文档中提取并分析内容。 **使用案例：** * 文档分析 * 信息提取 * 表格处理 * 研究论文分析 * 合同审查 * 多页文档理解 **Python 示例：** 将 google.generativeai 导入为 genai 从 pathlib 导入路径 genai.configure(api_key="YOUR_API_KEY") # 配置为中等分辨率（推荐用于 PDF）模型 = genai.GenerativeModel( “gemini-3-pro-预览”，一代配置={ "thinking_level": "高", "media_resolution": "medium" # 560 个令牌/页（饱和点） } ） # 上传 PDF pdf_path = 路径("research_paper.pdf") pdf_file = genai.upload_file(pdf_path) # 等待处理导入时间而 pdf_file.state.name ==“处理中”：时间.睡眠(5) pdf_file = genai.get_file(pdf_file.name) # 分析 PDF 响应 = model.generate_content([ """分析此 PDF 文档并提供： 1. 文件类型和用途 2、主要部分及结构 3. 主要发现或论点 4. 重要数据或统计数据 5.结论或建议 """, pdf_文件 ]）打印（响应.文本） print(f"使用的令牌：{response.usage_metadata.total_token_count}") **Node.js 示例：** 从“@google/generative-ai”导入 { GoogleGenerativeAI }；从“@google/generative-ai/server”导入 { GoogleAIFileManager, FileState }； const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY!); const fileManager = new GoogleAIFileManager(process.env.GEMINI_API_KEY!); // 上传PDF const uploadResult =等待 fileManager.uploadFile("research_paper.pdf", { mimeType：“应用程序/pdf” }); // 等待处理让文件=等待fileManager.getFile(uploadResult.file.name); while (file.state === FileState.PROCESSING) { 等待新的 Promise(resolve => setTimeout(resolve, 5000)); 文件=等待fileManager.getFile(uploadResult.file.name); } // 使用中等分辨率进行分析（推荐） const 模型 = genAI.getGenerativeModel({ 型号：“gemini-3-pro-preview”，生成配置：{ 媒体分辨率：“中” } }); const 结果 = 等待 model.generateContent([ `分析此 PDF 并提取： 1. 主要部分 2. 主要发现 3.重要数据`, { fileData: { fileUri: file.uri, mimeType: file.mimeType } } ]); console.log(结果.response.text()); **PDF 处理技巧：** * **推荐分辨率：** `中`（560 个令牌/页）- 质量饱和点 * **多页：** 自动处理所有页面 * **本机支持：** 无需转换为图像 * **文本提取：** 内置高质量文本提取 **请参阅：** `references/document-processing.md` 了解高级模式 ** ** ### 任务 5：优化媒体处理成本 **目标：** 根据用例平衡质量和代币消耗。 **战略：** 媒体类型 |分辨率|代币 |使用案例 ---|---|---|--- **图像** | `低` | 280 | 280快速扫描、缩略图 **图像** | `中` | 560 | 560一般分析 **图像** | `高` | 1,120 | 1,120 OCR、细节、代码 **PDF** | `中` | 560/页 | **推荐**（饱和点） **PDF** | `高` | 1,120/页 |收益递减 **视频** | `低`/`中` | 70/帧|大多数用例 **视频** | `高` | 280/帧|视频中的 OCR **Python优化示例：** 将 google.generativeai 导入为 genai genai.configure(api_key="YOUR_API_KEY") # 不同的用例有不同的分辨率 defanalyze_image_optimized(image_path, need_ocr=False): """以适当的分辨率分析图像""" 如果 need_ocr 则分辨率 =“高”，否则“中” 模型 = genai.GenerativeModel( “gemini-3-pro-预览”，一代配置={ “媒体分辨率”：分辨率 } ） image_file = genai.upload_file(image_path) 响应 = model.generate_content([ “描述此图像”如果不需要 need_ocr else“从该图像中提取所有文本”，图像文件 ]） # 记录令牌使用情况以进行成本跟踪令牌 = response.usage_metadata.total_token_count 成本 = (代币 / 1_000_000) * 2.00 # 输入定价 print(f"分辨率：{分辨率}，令牌：{tokens}，成本：${cost:.6f}") 返回响应.文本 # 使用适当的分辨率 analyze_image_optimized("photo.jpg", need_ocr=False) # 中等 analyze_image_optimized("document.png", need_ocr=True) # 高 **每项分辨率控制：** # 在同一个请求中为不同的媒体设置不同的分辨率响应 = model.generate_content([ “比较这些图像”， {"file": image1, "media_resolution": "high"}, # 高细节 {"file": image2, "media_resolution": "low"}, # 低细节 OK ]） **成本监控：** def log_media_costs（响应）： """记录媒体处理费用""" 用法 = 响应.usage_metadata # ≤200k 上下文的定价 input_cost = (usage.prompt_token_count / 1_000_000) * 2.00 输出成本 = (usage.candidates_token_count / 1_000_000) * 12.00 print(f"输入令牌：{usage.prompt_token_count} (${input_cost:.6f})") print(f"输出令牌：{usage.candidates_token_count} (${output_cost:.6f})") print(f"总成本：${input_cost + output_cost:.6f}") **参见：** `references/token-optimization.md` 了解综合策略 ** ** ## 媒体分辨率控制 ### 分辨率选项设置|图片 | PDF |视频（每帧）|推荐 ---|---|---|---|--- `低` | 280 个代币 | 280 个代币 | 70 个代币 |快速分析，低细节 `中` | 560 个代币 | 560 个代币 | 70 个代币 |平衡的质量/成本 `高` | 1,120 个代币 | 1,120 个代币 | 280 个代币 | OCR、精细文本、细节 ### 配置 **全局设置（所有媒体）：** 模型 = genai.GenerativeModel( “gemini-3-pro-预览”，一代配置={ "media_resolution": "high" # 适用于所有媒体 } ） **每项设置（混合分辨率）：** 响应 = model.generate_content([ “分析这些文件”， {“文件”：high_detail_image，“媒体分辨率”：“高”}， {“文件”：low_detail_image，“媒体分辨率”：“低”} ]） ### 最佳实践 1. **图像：** 使用 `high` 进行 OCR/文本提取，使用 `medium` 进行一般分析 2. **PDF：** 使用“中”（饱和点 - 较高的分辨率显示收益递减） 3. **视频：** 使用“低”或“中”，除非需要 OCR 4. **成本控制：** 从‘低’开始，质量不够才增加 **请参阅：** `references/media-resolution.md` 了解详细指南 ** ** ## 文件管理 ### 上传文件将 google.generativeai 导入为 genai # 上传文件 file = genai.upload_file("path/to/file.jpg") print(f"已上传：{文件名}") # 检查处理状态 while file.state.name == "处理中": 时间.睡眠(5) file = genai.get_file(文件名) print(f"状态：{file.state.name}") ### 列出已上传的文件 # 列出所有文件对于 genai.list_files() 中的文件： print(f"{file.name} - {file.display_name}") ### 删除文件 # 删除特定文件 genai.delete_file(文件名) # 删除所有文件对于 genai.list_files() 中的文件： genai.delete_file(文件名) print(f"已删除：{file.name}") ### 文件生命周期 * **上传：** 立即 * **处理：** 异步（特别是视频/音频） * **存储：** 文件将持续存在直至删除 * **过期：** 文件可能会在期限后过期（检查文档） ** ** ## 多文件处理 ### 处理多个图像 # 上传多张图片图像 = [ genai.upload_file("照片1.jpg"), genai.upload_file("照片2.jpg"), genai.upload_file("photo3.jpg") ] #一起分析响应 = model.generate_content([ “比较这些图像并识别共同元素”， *图片 ]）打印（响应.文本） ### 混合媒体类型 # 组合不同的媒体类型图片 = genai.upload_file("chart.png") pdf = genai.upload_file("报告.pdf") 响应 = model.generate_content([ “图表与报告中的数据相符吗？”, 图像， pdf ]） ** ** ## 参考文献 **核心指南** * [图像理解]() \- 完整的图像分析模式 * [视频处理]() \- 视频分析和帧提取 * [音频处理]() \- 音频转录和分析 * [文档处理]() \- PDF 和文档提取 **优化** * [媒体分辨率]() \- 分辨率控制和质量调整 * [OCR 提取]() \- 文本提取最佳实践 * [Token优化]() \- 成本控制和效率 **脚本** * [分析图像脚本]() \- 生产就绪的图像分析 * [处理视频脚本]() \- 视频处理自动化 * [处理音频脚本]() \- 音频转录 * [处理 PDF 脚本]() \- PDF 提取 **官方资源** * [视觉能力]() * [媒体提示]() * [文件 API]() ** ** ## 相关技能 * **gemini-3-pro-api** \- 基本设置、身份验证、文本生成 * **gemini-3-image- Generation** \- 图像输出（生成图像） * **gemini-3-advanced** \- 函数调用、工具、缓存、批处理 ** ** ## 常见用例 ### 视觉问答应用将图像理解与聊天结合起来：模型 = genai.GenerativeModel("gemini-3-pro-preview") 聊天 = model.start_chat() # 上传图片图片 = genai.upload_file("产品.jpg") # 提出相关问题 response1 = chat.send_message(["这是什么产品？", image]) response2 = chat.send_message("它的主要特点是什么？") response3 = chat.send_message("类似产品的价格范围是多少？") ### 文档分析管道处理多个 PDF 并提取见解：将 google.generativeai 导入为 genai 从 pathlib 导入路径 genai.configure(api_key="YOUR_API_KEY") 模型 = genai.GenerativeModel( “gemini-3-pro-预览”， Generation_config={"media_resolution": "medium"} ） # 处理目录中的所有PDF pdf_dir = 路径(“文档/”) 结果={} 对于 pdf_dir.glob("*.pdf") 中的 pdf_path： pdf_file = genai.upload_file(pdf_path) # 等待处理而 pdf_file.state.name ==“处理中”：时间.睡眠(5) pdf_file = genai.get_file(pdf_file.name) # 提取关键信息响应 = model.generate_content([ “摘录：1) 文件类型，2) 关键日期，3) 重要数字，4) 摘要”, pdf_文件 ]）结果[pdf_path.name] = 响应.text # 清理 genai.delete_file(pdf_file.name) # 保存结果导入 json 打开（“analysis_results.json”，“w”）作为f： json.dump(结果，f，缩进=2) ### 视频内容审核分析视频的特定内容：视频 = genai.upload_file("user_upload.mp4") # 等待处理 while video.state.name == "处理中": 时间.睡眠(10) 视频 = genai.get_file(视频.名称) 响应 = model.generate_content([ """分析该视频： 1. 不当内容（是/否） 2. 暴力或有害内容（是/否） 3. 总体内容分级（G/PG/PG-13/R） 4. 简要理由提供结构化响应。 """, 视频 ]）打印（响应.文本） ** ** ## 故障排除 ### 问题：文件处理停留在“处理中” **解决方案：** 大文件（尤其是视频）可能需要时间。检查之间等待 30-60 秒。如果卡住超过 5 分钟，文件可能已失败。 ### 问题：OCR 结果质量低 **解决方案：** 对带有文本的图像使用 `media_resolution: "high"`。确保图像清晰且高分辨率。 ### 问题：代币成本高 **解决方案：** 使用适当的媒体分辨率。从“低”开始，仅在需要时增加。对于 PDF，“medium”通常就足够了。 ### 问题：视频分析缺少细节 **解决方案：** 使用 `media_resolution: "high"` 进行更好的帧分析，或提供有关要查找的内容的更具体提示。 ### 问题：音频转录不准确 **解决方案：** 确保音频质量良好（没有过多的背景噪音）。在提示中提供有关口音、语言或领域的上下文。 ** ** ## 总结该技能提供全面的多模式输入处理能力： ✅ 使用 OCR 和对象检测进行图像分析 ✅ 视频处理长达 1 小时 ✅ 音频转录长达 9.5 小时 ✅ 原生 PDF 文档处理 ✅ 精细媒体分辨率控制 ✅ 令牌优化策略 ✅ 多文件处理 ✅ 生产就绪示例 **准备好分析多模式内容了吗？** 从上面与您的用例匹配的任务开始！

Gemini 3 多式联运

包含技能