Step3-VL-10B实战教程Python API调用方式requestsbase64图片传参示例1. 引言如果你已经体验过Step3-VL-10B的Web界面可能会想能不能用代码直接调用这个强大的视觉语言模型答案是肯定的通过Python API你可以把图像理解能力集成到自己的应用中实现批量处理、自动化分析等高级功能。今天我就带你从零开始学习如何用Python的requests库调用Step3-VL-10B的API。我会用最简单的方式讲解即使你是编程新手也能跟着一步步实现。我们将重点学习如何把图片转换成base64格式进行传输这是调用视觉模型API的关键技巧。学完这篇教程你将掌握如何准备Python环境如何把图片转换成API能识别的格式如何发送请求并解析模型的回答如何处理常见的错误和问题2. 环境准备2.1 确保服务正常运行在开始写代码之前首先要确认Step3-VL-10B的Web服务已经启动并运行。打开终端执行以下命令# 检查服务状态 supervisorctl status step3vl-webui如果看到类似RUNNING的状态说明服务正常。如果服务没有运行先启动它# 启动服务 supervisorctl start step3vl-webui # 等待几秒钟再次检查状态 supervisorctl status step3vl-webui2.2 安装必要的Python库我们需要两个主要的Python库requests用于发送HTTP请求Pillow用于处理图片。打开终端执行安装命令pip install requests pillow如果你使用的是Python 3可能需要用pip3pip3 install requests pillow安装完成后可以验证一下# 在Python交互环境中测试 import requests from PIL import Image print(库安装成功)3. 理解API接口3.1 API地址和端口Step3-VL-10B的WebUI默认运行在7860端口对应的API地址是http://localhost:7860/api/predict如果你在远程服务器上部署需要把localhost换成服务器的IP地址http://你的服务器IP:7860/api/predict3.2 请求参数详解API需要接收一个JSON格式的请求主要包含以下参数参数名类型说明示例imagestringbase64编码的图片数据data:image/jpeg;base64,/9j/4AAQSkZJRg...questionstring要问的问题请描述这张图片的内容max_new_tokensint最大生成长度512temperaturefloat温度参数控制随机性0.7top_pfloatTop-P采样参数0.9关键点说明image参数必须是base64编码的字符串并且要加上数据前缀question是你想问的问题越具体越好其他参数都有默认值可以不传3.3 响应格式API会返回一个JSON格式的响应结构如下{ data: [ 模型的回答内容 ] }我们主要关注data数组中的第一个元素这就是模型生成的回答。4. 图片处理base64编码详解4.1 什么是base64编码简单来说base64是一种把二进制数据比如图片转换成文本字符串的方法。因为HTTP协议主要传输文本所以我们需要把图片转换成文本格式才能通过API发送。想象一下你要通过短信发送一张图片但短信只能发文字怎么办你可以把图片的每个像素点用字母和数字表示出来接收方再把这些字母数字还原成图片。base64就是做这个转换的。4.2 如何将图片转换为base64下面是一个完整的函数可以把任意图片文件转换成base64字符串import base64 import os def image_to_base64(image_path): 将图片文件转换为base64编码字符串 参数 image_path: 图片文件的路径 返回 base64编码的字符串包含数据前缀 # 检查文件是否存在 if not os.path.exists(image_path): raise FileNotFoundError(f图片文件不存在: {image_path}) # 检查文件格式 valid_extensions [.jpg, .jpeg, .png, .bmp, .gif] file_ext os.path.splitext(image_path)[1].lower() if file_ext not in valid_extensions: raise ValueError(f不支持的图片格式: {file_ext}支持格式: {valid_extensions}) # 读取图片文件 with open(image_path, rb) as image_file: # 读取二进制数据 image_data image_file.read() # 进行base64编码 base64_encoded base64.b64encode(image_data).decode(utf-8) # 根据文件类型添加数据前缀 if file_ext in [.jpg, .jpeg]: mime_type image/jpeg elif file_ext .png: mime_type image/png elif file_ext .bmp: mime_type image/bmp elif file_ext .gif: mime_type image/gif else: mime_type image/jpeg # 默认使用jpeg # 组合成完整的数据URL data_url fdata:{mime_type};base64,{base64_encoded} return data_url # 使用示例 if __name__ __main__: # 测试转换 base64_str image_to_base64(test.jpg) print(f转换成功base64字符串长度: {len(base64_str)}) print(f前100个字符: {base64_str[:100]}...)4.3 处理不同格式的图片在实际使用中你可能会遇到各种格式的图片。下面的代码展示了如何处理常见的图片格式from PIL import Image import io def process_image_for_api(image_path, max_size(728, 728)): 处理图片确保符合API要求 参数 image_path: 图片路径 max_size: 最大尺寸Step3-VL-10B支持最高728x728 返回 处理后的base64字符串 try: # 用PIL打开图片 img Image.open(image_path) # 获取原始尺寸 original_size img.size print(f原始图片尺寸: {original_size}) # 如果图片太大进行缩放 if img.size[0] max_size[0] or img.size[1] max_size[1]: img.thumbnail(max_size, Image.Resampling.LANCZOS) print(f缩放后尺寸: {img.size}) # 转换图片模式确保是RGB if img.mode ! RGB: img img.convert(RGB) print(f转换图片模式为RGB) # 保存到内存中 buffer io.BytesIO() img.save(buffer, formatJPEG, quality95) # 转换为base64 base64_encoded base64.b64encode(buffer.getvalue()).decode(utf-8) data_url fdata:image/jpeg;base64,{base64_encoded} return data_url except Exception as e: print(f处理图片时出错: {e}) # 如果PIL处理失败回退到简单方法 return image_to_base64(image_path)5. 完整的API调用示例5.1 基础调用单张图片分析让我们从一个最简单的例子开始分析一张图片的内容import requests import json import time def analyze_single_image(image_path, question, api_urlhttp://localhost:7860/api/predict): 分析单张图片 参数 image_path: 图片路径 question: 要问的问题 api_url: API地址 返回 模型的回答 # 1. 将图片转换为base64 print(正在处理图片...) image_base64 image_to_base64(image_path) print(图片处理完成) # 2. 准备请求数据 payload { data: [ image_base64, # 图片数据 question, # 问题 512, # max_new_tokens 0.7, # temperature 0.9 # top_p ] } # 3. 设置请求头 headers { Content-Type: application/json } # 4. 发送请求 print(f正在发送请求到: {api_url}) print(f问题: {question}) try: start_time time.time() response requests.post(api_url, jsonpayload, headersheaders, timeout60) end_time time.time() print(f请求完成耗时: {end_time - start_time:.2f}秒) print(f状态码: {response.status_code}) # 5. 检查响应 if response.status_code 200: result response.json() answer result[data][0] print(f模型回答: {answer}) return answer else: print(f请求失败: {response.status_code}) print(f响应内容: {response.text}) return None except requests.exceptions.Timeout: print(请求超时请检查服务是否正常运行) return None except requests.exceptions.ConnectionError: print(连接失败请检查API地址是否正确) return None except Exception as e: print(f发生错误: {e}) return None # 使用示例 if __name__ __main__: # 示例1描述图片内容 result analyze_single_image( image_pathexample.jpg, question请详细描述这张图片的内容, api_urlhttp://localhost:7860/api/predict ) if result: print(\n *50) print(分析结果:) print(*50) print(result)5.2 进阶示例批量图片处理在实际应用中我们经常需要处理多张图片。下面的代码展示了如何批量处理import os from concurrent.futures import ThreadPoolExecutor, as_completed def batch_process_images(image_folder, questions, output_fileresults.txt, max_workers3): 批量处理图片文件夹 参数 image_folder: 图片文件夹路径 questions: 问题列表或单个问题如果是单个问题所有图片都问同样的问题 output_file: 结果输出文件 max_workers: 最大并发数 # 获取所有图片文件 image_files [] valid_extensions [.jpg, .jpeg, .png, .bmp, .gif] for file in os.listdir(image_folder): file_ext os.path.splitext(file)[1].lower() if file_ext in valid_extensions: image_files.append(os.path.join(image_folder, file)) if not image_files: print(f在文件夹 {image_folder} 中没有找到图片文件) return print(f找到 {len(image_files)} 张图片) # 准备问题 if isinstance(questions, str): # 如果是单个问题所有图片都用同一个问题 questions_list [questions] * len(image_files) else: # 如果是问题列表确保长度匹配 if len(questions) ! len(image_files): print(f警告问题数量({len(questions)})与图片数量({len(image_files)})不匹配) questions_list questions else: questions_list questions # 准备结果存储 results [] # 使用线程池并发处理 with ThreadPoolExecutor(max_workersmax_workers) as executor: # 提交所有任务 future_to_image { executor.submit(analyze_single_image, img_path, question): (img_path, question) for img_path, question in zip(image_files, questions_list) } # 处理完成的任务 for future in as_completed(future_to_image): img_path, question future_to_image[future] try: result future.result(timeout120) # 设置超时时间 if result: results.append({ image: os.path.basename(img_path), question: question, answer: result }) print(f✓ 完成: {os.path.basename(img_path)}) else: print(f✗ 失败: {os.path.basename(img_path)}) except Exception as e: print(f✗ 处理出错 {os.path.basename(img_path)}: {e}) # 保存结果到文件 with open(output_file, w, encodingutf-8) as f: for item in results: f.write(f图片: {item[image]}\n) f.write(f问题: {item[question]}\n) f.write(f回答: {item[answer]}\n) f.write(- * 50 \n) print(f\n处理完成结果已保存到: {output_file}) print(f成功处理: {len(results)}/{len(image_files)} 张图片) # 使用示例 if __name__ __main__: # 示例批量处理图片 batch_process_images( image_folder./images, questions这张图片的主要内容是什么, output_filebatch_results.txt, max_workers2 # 根据服务器性能调整 )5.3 实用工具类封装常用功能为了更方便地使用我们可以创建一个工具类来封装所有功能class Step3VLClient: Step3-VL-10B API客户端 def __init__(self, api_urlhttp://localhost:7860/api/predict): 初始化客户端 参数 api_url: API地址 self.api_url api_url self.session requests.Session() self.session.headers.update({ Content-Type: application/json, User-Agent: Step3-VL-Python-Client/1.0 }) def analyze_image(self, image_path, question, max_tokens512, temperature0.7, top_p0.9): 分析单张图片 参数 image_path: 图片路径 question: 问题 max_tokens: 最大生成长度 temperature: 温度参数 top_p: Top-P采样参数 返回 分析结果字典 # 处理图片 image_base64 image_to_base64(image_path) # 准备请求数据 payload { data: [ image_base64, question, max_tokens, temperature, top_p ] } try: response self.session.post(self.api_url, jsonpayload, timeout60) response.raise_for_status() result response.json() return { success: True, answer: result[data][0], image: os.path.basename(image_path), question: question } except requests.exceptions.RequestException as e: return { success: False, error: str(e), image: os.path.basename(image_path), question: question } def analyze_images(self, image_paths, questions, **kwargs): 分析多张图片 参数 image_paths: 图片路径列表 questions: 问题列表或单个问题 **kwargs: 其他参数传递给analyze_image 返回 结果列表 if isinstance(questions, str): questions [questions] * len(image_paths) results [] for img_path, question in zip(image_paths, questions): result self.analyze_image(img_path, question, **kwargs) results.append(result) # 添加延迟避免请求过快 time.sleep(0.5) return results def describe_image(self, image_path, detail_level详细): 描述图片内容快捷方法 参数 image_path: 图片路径 detail_level: 详细程度可选简要、详细、非常详细 prompts { 简要: 请简要描述这张图片的内容, 详细: 请详细描述这张图片的内容, 非常详细: 请非常详细地描述这张图片的内容包括场景、物体、颜色、构图等所有细节 } question prompts.get(detail_level, prompts[详细]) return self.analyze_image(image_path, question) def extract_text(self, image_path): 提取图片中的文字OCR功能 参数 image_path: 图片路径 返回 文字提取结果 question 图片中有哪些文字请提取所有文本 return self.analyze_image(image_path, question) def count_objects(self, image_path, object_type): 统计图片中特定物体的数量 参数 image_path: 图片路径 object_type: 物体类型如人、车、树等 返回 统计结果 question f图片中有多少个{object_type}请列出它们的数量和位置 return self.analyze_image(image_path, question) # 使用示例 if __name__ __main__: # 创建客户端 client Step3VLClient() # 示例1描述图片 print(示例1描述图片内容) result client.describe_image(example.jpg, detail_level详细) if result[success]: print(f描述结果: {result[answer]}) # 示例2提取文字 print(\n示例2提取图片中的文字) result client.extract_text(document.jpg) if result[success]: print(f提取的文字: {result[answer]}) # 示例3统计物体数量 print(\n示例3统计图片中的人数) result client.count_objects(group_photo.jpg, 人) if result[success]: print(f统计结果: {result[answer]})6. 常见问题与解决方案6.1 连接问题问题连接被拒绝或超时# 解决方案检查服务状态和网络连接 def check_service_status(api_urlhttp://localhost:7860/api/predict, timeout5): 检查服务是否可用 try: # 尝试发送一个简单的请求 response requests.get(api_url.replace(/api/predict, ), timeouttimeout) if response.status_code 200: print(✅ 服务正常运行) return True else: print(f⚠️ 服务返回异常状态码: {response.status_code}) return False except requests.exceptions.ConnectionError: print(❌ 无法连接到服务请检查) print(1. 服务是否启动supervisorctl status step3vl-webui) print(2. 端口是否正确默认是7860) print(3. 防火墙设置确保端口可访问) return False except requests.exceptions.Timeout: print(⏰ 连接超时服务可能正在启动或负载过高) return False # 使用检查函数 if check_service_status(): print(可以开始调用API) else: print(请先解决问题再继续)6.2 图片处理问题问题图片太大或格式不支持def validate_image(image_path, max_size_mb10): 验证图片是否适合处理 参数 image_path: 图片路径 max_size_mb: 最大文件大小MB 返回 (是否有效, 错误信息) # 检查文件是否存在 if not os.path.exists(image_path): return False, 文件不存在 # 检查文件大小 file_size_mb os.path.getsize(image_path) / (1024 * 1024) if file_size_mb max_size_mb: return False, f文件太大 ({file_size_mb:.1f}MB {max_size_mb}MB) # 检查文件格式 valid_extensions [.jpg, .jpeg, .png, .bmp, .gif] file_ext os.path.splitext(image_path)[1].lower() if file_ext not in valid_extensions: return False, f不支持的文件格式: {file_ext} # 尝试用PIL打开图片 try: with Image.open(image_path) as img: img.verify() # 验证图片完整性 return True, 图片有效 except Exception as e: return False, f图片损坏或无法读取: {str(e)} # 使用验证函数 image_path test.jpg is_valid, message validate_image(image_path) if is_valid: print(f✅ {message}) else: print(f❌ {message})6.3 性能优化建议建议1批量处理时控制并发数# 根据服务器性能调整并发数 CONCURRENT_LIMITS { low: 1, # 低性能服务器 medium: 3, # 中等性能服务器 high: 5 # 高性能服务器 } def get_optimal_concurrent(server_performancemedium): 获取最优并发数 return CONCURRENT_LIMITS.get(server_performance, 2)建议2添加请求重试机制import time from functools import wraps def retry_on_failure(max_retries3, delay2): 重试装饰器 def decorator(func): wraps(func) def wrapper(*args, **kwargs): for attempt in range(max_retries): try: return func(*args, **kwargs) except Exception as e: if attempt max_retries - 1: raise print(f第{attempt 1}次尝试失败: {e}, {delay}秒后重试...) time.sleep(delay) return None return wrapper return decorator # 使用重试机制 retry_on_failure(max_retries3, delay2) def robust_api_call(image_path, question): 带重试的API调用 client Step3VLClient() return client.analyze_image(image_path, question)7. 实际应用案例7.1 案例1电商商品图片分析def analyze_ecommerce_product(image_path): 分析电商商品图片 client Step3VLClient() # 多角度分析 analyses [] # 1. 商品描述 print(正在分析商品描述...) desc_result client.analyze_image( image_path, 请详细描述这个商品的外观、颜色、材质和特点 ) if desc_result[success]: analyses.append((商品描述, desc_result[answer])) # 2. 使用场景 print(正在分析使用场景...) scene_result client.analyze_image( image_path, 这个商品适合在什么场景下使用请列举3-5个使用场景 ) if scene_result[success]: analyses.append((使用场景, scene_result[answer])) # 3. 目标用户 print(正在分析目标用户...) user_result client.analyze_image( image_path, 这个商品的目标用户是什么人群请描述用户特征 ) if user_result[success]: analyses.append((目标用户, user_result[answer])) # 4. 卖点提炼 print(正在提炼商品卖点...) selling_result client.analyze_image( image_path, 请提炼这个商品的3个主要卖点 ) if selling_result[success]: analyses.append((商品卖点, selling_result[answer])) return analyses # 使用示例 product_analyses analyze_ecommerce_product(product.jpg) for title, content in product_analyses: print(f\n{title}:) print(- * 40) print(content)7.2 案例2文档图片信息提取def extract_document_info(image_path): 提取文档图片中的信息 client Step3VLClient() print(正在提取文档信息...) # 1. 提取所有文字 text_result client.extract_text(image_path) extracted_text text_result[answer] if text_result[success] else # 2. 分析文档类型 type_result client.analyze_image( image_path, 这是一份什么类型的文档可能是合同、发票、报告、简历等 ) doc_type type_result[answer] if type_result[success] else 未知 # 3. 提取关键信息 key_info_result client.analyze_image( image_path, 请提取文档中的关键信息如日期、金额、姓名、公司名称等 ) key_info key_info_result[answer] if key_info_result[success] else return { document_type: doc_type, extracted_text: extracted_text, key_information: key_info } # 使用示例 doc_info extract_document_info(invoice.jpg) print(f文档类型: {doc_info[document_type]}) print(f\n提取的文字:) print(doc_info[extracted_text]) print(f\n关键信息:) print(doc_info[key_information])7.3 案例3社交媒体图片分析def analyze_social_media_image(image_path): 分析社交媒体图片 client Step3VLClient() questions [ 这张图片的主要内容和主题是什么, 图片传达了什么样的情感或氛围, 这张图片适合配什么样的文案请提供3个不同风格的文案建议, 根据图片内容推荐3个相关的热门话题标签hashtag, 这张图片可能吸引什么类型的受众 ] results [] for i, question in enumerate(questions, 1): print(f正在分析第{i}/{len(questions)}个问题...) result client.analyze_image(image_path, question) if result[success]: results.append((question, result[answer])) time.sleep(1) # 避免请求过快 return results # 使用示例 social_results analyze_social_media_image(social_image.jpg) for question, answer in social_results: print(f\nQ: {question}) print(fA: {answer}) print(- * 60)8. 总结通过这篇教程你已经掌握了使用Python调用Step3-VL-10B API的核心技能。让我们回顾一下重点8.1 关键知识点总结图片处理是基础学会用base64编码将图片转换成API能接受的格式这是调用视觉模型API的第一步。API调用很简单本质上就是发送一个HTTP POST请求包含图片数据和问题文本。错误处理很重要网络问题、服务状态、图片格式等都可能出错好的错误处理能让程序更健壮。批量处理提高效率使用多线程或异步处理可以大幅提升处理多张图片的效率。参数调整影响结果temperature、max_tokens等参数会影响生成结果的质量和风格。8.2 实用建议从简单开始先用单张图片测试确保基础功能正常再尝试复杂功能。注意性能根据服务器性能调整并发数避免同时发送太多请求导致服务崩溃。保存中间结果处理大量图片时定期保存结果到文件防止程序意外中断导致数据丢失。合理设置超时根据图片复杂度和问题难度适当调整请求超时时间。监控服务状态定期检查服务是否正常运行特别是长时间运行批量任务时。8.3 下一步学习方向掌握了基础API调用后你可以进一步探索集成到实际应用将视觉理解能力集成到你的网站、APP或自动化流程中。结合其他AI服务把Step3-VL-10B的图像理解能力与其他AI服务如文本生成、语音合成结合创造更强大的应用。优化用户体验为你的应用添加图片预览、进度显示、结果导出等友好功能。探索高级功能尝试更复杂的问题如数学推理、逻辑分析、创意写作等。记住技术学习的核心是实践。多写代码多尝试不同的图片和问题你会越来越熟练。如果在使用过程中遇到问题记得查看服务日志那里面通常有解决问题的线索。获取更多AI镜像想探索更多AI镜像和应用场景访问 CSDN星图镜像广场提供丰富的预置镜像覆盖大模型推理、图像生成、视频生成、模型微调等多个领域支持一键部署。 Step3-VL-10B实战教程：Python API调用方式（requests+base64图片传参示例）
Step3-VL-10B实战教程Python API调用方式requestsbase64图片传参示例1. 引言如果你已经体验过Step3-VL-10B的Web界面可能会想能不能用代码直接调用这个强大的视觉语言模型答案是肯定的通过Python API你可以把图像理解能力集成到自己的应用中实现批量处理、自动化分析等高级功能。今天我就带你从零开始学习如何用Python的requests库调用Step3-VL-10B的API。我会用最简单的方式讲解即使你是编程新手也能跟着一步步实现。我们将重点学习如何把图片转换成base64格式进行传输这是调用视觉模型API的关键技巧。学完这篇教程你将掌握如何准备Python环境如何把图片转换成API能识别的格式如何发送请求并解析模型的回答如何处理常见的错误和问题2. 环境准备2.1 确保服务正常运行在开始写代码之前首先要确认Step3-VL-10B的Web服务已经启动并运行。打开终端执行以下命令# 检查服务状态 supervisorctl status step3vl-webui如果看到类似RUNNING的状态说明服务正常。如果服务没有运行先启动它# 启动服务 supervisorctl start step3vl-webui # 等待几秒钟再次检查状态 supervisorctl status step3vl-webui2.2 安装必要的Python库我们需要两个主要的Python库requests用于发送HTTP请求Pillow用于处理图片。打开终端执行安装命令pip install requests pillow如果你使用的是Python 3可能需要用pip3pip3 install requests pillow安装完成后可以验证一下# 在Python交互环境中测试 import requests from PIL import Image print(库安装成功)3. 理解API接口3.1 API地址和端口Step3-VL-10B的WebUI默认运行在7860端口对应的API地址是http://localhost:7860/api/predict如果你在远程服务器上部署需要把localhost换成服务器的IP地址http://你的服务器IP:7860/api/predict3.2 请求参数详解API需要接收一个JSON格式的请求主要包含以下参数参数名类型说明示例imagestringbase64编码的图片数据data:image/jpeg;base64,/9j/4AAQSkZJRg...questionstring要问的问题请描述这张图片的内容max_new_tokensint最大生成长度512temperaturefloat温度参数控制随机性0.7top_pfloatTop-P采样参数0.9关键点说明image参数必须是base64编码的字符串并且要加上数据前缀question是你想问的问题越具体越好其他参数都有默认值可以不传3.3 响应格式API会返回一个JSON格式的响应结构如下{ data: [ 模型的回答内容 ] }我们主要关注data数组中的第一个元素这就是模型生成的回答。4. 图片处理base64编码详解4.1 什么是base64编码简单来说base64是一种把二进制数据比如图片转换成文本字符串的方法。因为HTTP协议主要传输文本所以我们需要把图片转换成文本格式才能通过API发送。想象一下你要通过短信发送一张图片但短信只能发文字怎么办你可以把图片的每个像素点用字母和数字表示出来接收方再把这些字母数字还原成图片。base64就是做这个转换的。4.2 如何将图片转换为base64下面是一个完整的函数可以把任意图片文件转换成base64字符串import base64 import os def image_to_base64(image_path): 将图片文件转换为base64编码字符串 参数 image_path: 图片文件的路径 返回 base64编码的字符串包含数据前缀 # 检查文件是否存在 if not os.path.exists(image_path): raise FileNotFoundError(f图片文件不存在: {image_path}) # 检查文件格式 valid_extensions [.jpg, .jpeg, .png, .bmp, .gif] file_ext os.path.splitext(image_path)[1].lower() if file_ext not in valid_extensions: raise ValueError(f不支持的图片格式: {file_ext}支持格式: {valid_extensions}) # 读取图片文件 with open(image_path, rb) as image_file: # 读取二进制数据 image_data image_file.read() # 进行base64编码 base64_encoded base64.b64encode(image_data).decode(utf-8) # 根据文件类型添加数据前缀 if file_ext in [.jpg, .jpeg]: mime_type image/jpeg elif file_ext .png: mime_type image/png elif file_ext .bmp: mime_type image/bmp elif file_ext .gif: mime_type image/gif else: mime_type image/jpeg # 默认使用jpeg # 组合成完整的数据URL data_url fdata:{mime_type};base64,{base64_encoded} return data_url # 使用示例 if __name__ __main__: # 测试转换 base64_str image_to_base64(test.jpg) print(f转换成功base64字符串长度: {len(base64_str)}) print(f前100个字符: {base64_str[:100]}...)4.3 处理不同格式的图片在实际使用中你可能会遇到各种格式的图片。下面的代码展示了如何处理常见的图片格式from PIL import Image import io def process_image_for_api(image_path, max_size(728, 728)): 处理图片确保符合API要求 参数 image_path: 图片路径 max_size: 最大尺寸Step3-VL-10B支持最高728x728 返回 处理后的base64字符串 try: # 用PIL打开图片 img Image.open(image_path) # 获取原始尺寸 original_size img.size print(f原始图片尺寸: {original_size}) # 如果图片太大进行缩放 if img.size[0] max_size[0] or img.size[1] max_size[1]: img.thumbnail(max_size, Image.Resampling.LANCZOS) print(f缩放后尺寸: {img.size}) # 转换图片模式确保是RGB if img.mode ! RGB: img img.convert(RGB) print(f转换图片模式为RGB) # 保存到内存中 buffer io.BytesIO() img.save(buffer, formatJPEG, quality95) # 转换为base64 base64_encoded base64.b64encode(buffer.getvalue()).decode(utf-8) data_url fdata:image/jpeg;base64,{base64_encoded} return data_url except Exception as e: print(f处理图片时出错: {e}) # 如果PIL处理失败回退到简单方法 return image_to_base64(image_path)5. 完整的API调用示例5.1 基础调用单张图片分析让我们从一个最简单的例子开始分析一张图片的内容import requests import json import time def analyze_single_image(image_path, question, api_urlhttp://localhost:7860/api/predict): 分析单张图片 参数 image_path: 图片路径 question: 要问的问题 api_url: API地址 返回 模型的回答 # 1. 将图片转换为base64 print(正在处理图片...) image_base64 image_to_base64(image_path) print(图片处理完成) # 2. 准备请求数据 payload { data: [ image_base64, # 图片数据 question, # 问题 512, # max_new_tokens 0.7, # temperature 0.9 # top_p ] } # 3. 设置请求头 headers { Content-Type: application/json } # 4. 发送请求 print(f正在发送请求到: {api_url}) print(f问题: {question}) try: start_time time.time() response requests.post(api_url, jsonpayload, headersheaders, timeout60) end_time time.time() print(f请求完成耗时: {end_time - start_time:.2f}秒) print(f状态码: {response.status_code}) # 5. 检查响应 if response.status_code 200: result response.json() answer result[data][0] print(f模型回答: {answer}) return answer else: print(f请求失败: {response.status_code}) print(f响应内容: {response.text}) return None except requests.exceptions.Timeout: print(请求超时请检查服务是否正常运行) return None except requests.exceptions.ConnectionError: print(连接失败请检查API地址是否正确) return None except Exception as e: print(f发生错误: {e}) return None # 使用示例 if __name__ __main__: # 示例1描述图片内容 result analyze_single_image( image_pathexample.jpg, question请详细描述这张图片的内容, api_urlhttp://localhost:7860/api/predict ) if result: print(\n *50) print(分析结果:) print(*50) print(result)5.2 进阶示例批量图片处理在实际应用中我们经常需要处理多张图片。下面的代码展示了如何批量处理import os from concurrent.futures import ThreadPoolExecutor, as_completed def batch_process_images(image_folder, questions, output_fileresults.txt, max_workers3): 批量处理图片文件夹 参数 image_folder: 图片文件夹路径 questions: 问题列表或单个问题如果是单个问题所有图片都问同样的问题 output_file: 结果输出文件 max_workers: 最大并发数 # 获取所有图片文件 image_files [] valid_extensions [.jpg, .jpeg, .png, .bmp, .gif] for file in os.listdir(image_folder): file_ext os.path.splitext(file)[1].lower() if file_ext in valid_extensions: image_files.append(os.path.join(image_folder, file)) if not image_files: print(f在文件夹 {image_folder} 中没有找到图片文件) return print(f找到 {len(image_files)} 张图片) # 准备问题 if isinstance(questions, str): # 如果是单个问题所有图片都用同一个问题 questions_list [questions] * len(image_files) else: # 如果是问题列表确保长度匹配 if len(questions) ! len(image_files): print(f警告问题数量({len(questions)})与图片数量({len(image_files)})不匹配) questions_list questions else: questions_list questions # 准备结果存储 results [] # 使用线程池并发处理 with ThreadPoolExecutor(max_workersmax_workers) as executor: # 提交所有任务 future_to_image { executor.submit(analyze_single_image, img_path, question): (img_path, question) for img_path, question in zip(image_files, questions_list) } # 处理完成的任务 for future in as_completed(future_to_image): img_path, question future_to_image[future] try: result future.result(timeout120) # 设置超时时间 if result: results.append({ image: os.path.basename(img_path), question: question, answer: result }) print(f✓ 完成: {os.path.basename(img_path)}) else: print(f✗ 失败: {os.path.basename(img_path)}) except Exception as e: print(f✗ 处理出错 {os.path.basename(img_path)}: {e}) # 保存结果到文件 with open(output_file, w, encodingutf-8) as f: for item in results: f.write(f图片: {item[image]}\n) f.write(f问题: {item[question]}\n) f.write(f回答: {item[answer]}\n) f.write(- * 50 \n) print(f\n处理完成结果已保存到: {output_file}) print(f成功处理: {len(results)}/{len(image_files)} 张图片) # 使用示例 if __name__ __main__: # 示例批量处理图片 batch_process_images( image_folder./images, questions这张图片的主要内容是什么, output_filebatch_results.txt, max_workers2 # 根据服务器性能调整 )5.3 实用工具类封装常用功能为了更方便地使用我们可以创建一个工具类来封装所有功能class Step3VLClient: Step3-VL-10B API客户端 def __init__(self, api_urlhttp://localhost:7860/api/predict): 初始化客户端 参数 api_url: API地址 self.api_url api_url self.session requests.Session() self.session.headers.update({ Content-Type: application/json, User-Agent: Step3-VL-Python-Client/1.0 }) def analyze_image(self, image_path, question, max_tokens512, temperature0.7, top_p0.9): 分析单张图片 参数 image_path: 图片路径 question: 问题 max_tokens: 最大生成长度 temperature: 温度参数 top_p: Top-P采样参数 返回 分析结果字典 # 处理图片 image_base64 image_to_base64(image_path) # 准备请求数据 payload { data: [ image_base64, question, max_tokens, temperature, top_p ] } try: response self.session.post(self.api_url, jsonpayload, timeout60) response.raise_for_status() result response.json() return { success: True, answer: result[data][0], image: os.path.basename(image_path), question: question } except requests.exceptions.RequestException as e: return { success: False, error: str(e), image: os.path.basename(image_path), question: question } def analyze_images(self, image_paths, questions, **kwargs): 分析多张图片 参数 image_paths: 图片路径列表 questions: 问题列表或单个问题 **kwargs: 其他参数传递给analyze_image 返回 结果列表 if isinstance(questions, str): questions [questions] * len(image_paths) results [] for img_path, question in zip(image_paths, questions): result self.analyze_image(img_path, question, **kwargs) results.append(result) # 添加延迟避免请求过快 time.sleep(0.5) return results def describe_image(self, image_path, detail_level详细): 描述图片内容快捷方法 参数 image_path: 图片路径 detail_level: 详细程度可选简要、详细、非常详细 prompts { 简要: 请简要描述这张图片的内容, 详细: 请详细描述这张图片的内容, 非常详细: 请非常详细地描述这张图片的内容包括场景、物体、颜色、构图等所有细节 } question prompts.get(detail_level, prompts[详细]) return self.analyze_image(image_path, question) def extract_text(self, image_path): 提取图片中的文字OCR功能 参数 image_path: 图片路径 返回 文字提取结果 question 图片中有哪些文字请提取所有文本 return self.analyze_image(image_path, question) def count_objects(self, image_path, object_type): 统计图片中特定物体的数量 参数 image_path: 图片路径 object_type: 物体类型如人、车、树等 返回 统计结果 question f图片中有多少个{object_type}请列出它们的数量和位置 return self.analyze_image(image_path, question) # 使用示例 if __name__ __main__: # 创建客户端 client Step3VLClient() # 示例1描述图片 print(示例1描述图片内容) result client.describe_image(example.jpg, detail_level详细) if result[success]: print(f描述结果: {result[answer]}) # 示例2提取文字 print(\n示例2提取图片中的文字) result client.extract_text(document.jpg) if result[success]: print(f提取的文字: {result[answer]}) # 示例3统计物体数量 print(\n示例3统计图片中的人数) result client.count_objects(group_photo.jpg, 人) if result[success]: print(f统计结果: {result[answer]})6. 常见问题与解决方案6.1 连接问题问题连接被拒绝或超时# 解决方案检查服务状态和网络连接 def check_service_status(api_urlhttp://localhost:7860/api/predict, timeout5): 检查服务是否可用 try: # 尝试发送一个简单的请求 response requests.get(api_url.replace(/api/predict, ), timeouttimeout) if response.status_code 200: print(✅ 服务正常运行) return True else: print(f⚠️ 服务返回异常状态码: {response.status_code}) return False except requests.exceptions.ConnectionError: print(❌ 无法连接到服务请检查) print(1. 服务是否启动supervisorctl status step3vl-webui) print(2. 端口是否正确默认是7860) print(3. 防火墙设置确保端口可访问) return False except requests.exceptions.Timeout: print(⏰ 连接超时服务可能正在启动或负载过高) return False # 使用检查函数 if check_service_status(): print(可以开始调用API) else: print(请先解决问题再继续)6.2 图片处理问题问题图片太大或格式不支持def validate_image(image_path, max_size_mb10): 验证图片是否适合处理 参数 image_path: 图片路径 max_size_mb: 最大文件大小MB 返回 (是否有效, 错误信息) # 检查文件是否存在 if not os.path.exists(image_path): return False, 文件不存在 # 检查文件大小 file_size_mb os.path.getsize(image_path) / (1024 * 1024) if file_size_mb max_size_mb: return False, f文件太大 ({file_size_mb:.1f}MB {max_size_mb}MB) # 检查文件格式 valid_extensions [.jpg, .jpeg, .png, .bmp, .gif] file_ext os.path.splitext(image_path)[1].lower() if file_ext not in valid_extensions: return False, f不支持的文件格式: {file_ext} # 尝试用PIL打开图片 try: with Image.open(image_path) as img: img.verify() # 验证图片完整性 return True, 图片有效 except Exception as e: return False, f图片损坏或无法读取: {str(e)} # 使用验证函数 image_path test.jpg is_valid, message validate_image(image_path) if is_valid: print(f✅ {message}) else: print(f❌ {message})6.3 性能优化建议建议1批量处理时控制并发数# 根据服务器性能调整并发数 CONCURRENT_LIMITS { low: 1, # 低性能服务器 medium: 3, # 中等性能服务器 high: 5 # 高性能服务器 } def get_optimal_concurrent(server_performancemedium): 获取最优并发数 return CONCURRENT_LIMITS.get(server_performance, 2)建议2添加请求重试机制import time from functools import wraps def retry_on_failure(max_retries3, delay2): 重试装饰器 def decorator(func): wraps(func) def wrapper(*args, **kwargs): for attempt in range(max_retries): try: return func(*args, **kwargs) except Exception as e: if attempt max_retries - 1: raise print(f第{attempt 1}次尝试失败: {e}, {delay}秒后重试...) time.sleep(delay) return None return wrapper return decorator # 使用重试机制 retry_on_failure(max_retries3, delay2) def robust_api_call(image_path, question): 带重试的API调用 client Step3VLClient() return client.analyze_image(image_path, question)7. 实际应用案例7.1 案例1电商商品图片分析def analyze_ecommerce_product(image_path): 分析电商商品图片 client Step3VLClient() # 多角度分析 analyses [] # 1. 商品描述 print(正在分析商品描述...) desc_result client.analyze_image( image_path, 请详细描述这个商品的外观、颜色、材质和特点 ) if desc_result[success]: analyses.append((商品描述, desc_result[answer])) # 2. 使用场景 print(正在分析使用场景...) scene_result client.analyze_image( image_path, 这个商品适合在什么场景下使用请列举3-5个使用场景 ) if scene_result[success]: analyses.append((使用场景, scene_result[answer])) # 3. 目标用户 print(正在分析目标用户...) user_result client.analyze_image( image_path, 这个商品的目标用户是什么人群请描述用户特征 ) if user_result[success]: analyses.append((目标用户, user_result[answer])) # 4. 卖点提炼 print(正在提炼商品卖点...) selling_result client.analyze_image( image_path, 请提炼这个商品的3个主要卖点 ) if selling_result[success]: analyses.append((商品卖点, selling_result[answer])) return analyses # 使用示例 product_analyses analyze_ecommerce_product(product.jpg) for title, content in product_analyses: print(f\n{title}:) print(- * 40) print(content)7.2 案例2文档图片信息提取def extract_document_info(image_path): 提取文档图片中的信息 client Step3VLClient() print(正在提取文档信息...) # 1. 提取所有文字 text_result client.extract_text(image_path) extracted_text text_result[answer] if text_result[success] else # 2. 分析文档类型 type_result client.analyze_image( image_path, 这是一份什么类型的文档可能是合同、发票、报告、简历等 ) doc_type type_result[answer] if type_result[success] else 未知 # 3. 提取关键信息 key_info_result client.analyze_image( image_path, 请提取文档中的关键信息如日期、金额、姓名、公司名称等 ) key_info key_info_result[answer] if key_info_result[success] else return { document_type: doc_type, extracted_text: extracted_text, key_information: key_info } # 使用示例 doc_info extract_document_info(invoice.jpg) print(f文档类型: {doc_info[document_type]}) print(f\n提取的文字:) print(doc_info[extracted_text]) print(f\n关键信息:) print(doc_info[key_information])7.3 案例3社交媒体图片分析def analyze_social_media_image(image_path): 分析社交媒体图片 client Step3VLClient() questions [ 这张图片的主要内容和主题是什么, 图片传达了什么样的情感或氛围, 这张图片适合配什么样的文案请提供3个不同风格的文案建议, 根据图片内容推荐3个相关的热门话题标签hashtag, 这张图片可能吸引什么类型的受众 ] results [] for i, question in enumerate(questions, 1): print(f正在分析第{i}/{len(questions)}个问题...) result client.analyze_image(image_path, question) if result[success]: results.append((question, result[answer])) time.sleep(1) # 避免请求过快 return results # 使用示例 social_results analyze_social_media_image(social_image.jpg) for question, answer in social_results: print(f\nQ: {question}) print(fA: {answer}) print(- * 60)8. 总结通过这篇教程你已经掌握了使用Python调用Step3-VL-10B API的核心技能。让我们回顾一下重点8.1 关键知识点总结图片处理是基础学会用base64编码将图片转换成API能接受的格式这是调用视觉模型API的第一步。API调用很简单本质上就是发送一个HTTP POST请求包含图片数据和问题文本。错误处理很重要网络问题、服务状态、图片格式等都可能出错好的错误处理能让程序更健壮。批量处理提高效率使用多线程或异步处理可以大幅提升处理多张图片的效率。参数调整影响结果temperature、max_tokens等参数会影响生成结果的质量和风格。8.2 实用建议从简单开始先用单张图片测试确保基础功能正常再尝试复杂功能。注意性能根据服务器性能调整并发数避免同时发送太多请求导致服务崩溃。保存中间结果处理大量图片时定期保存结果到文件防止程序意外中断导致数据丢失。合理设置超时根据图片复杂度和问题难度适当调整请求超时时间。监控服务状态定期检查服务是否正常运行特别是长时间运行批量任务时。8.3 下一步学习方向掌握了基础API调用后你可以进一步探索集成到实际应用将视觉理解能力集成到你的网站、APP或自动化流程中。结合其他AI服务把Step3-VL-10B的图像理解能力与其他AI服务如文本生成、语音合成结合创造更强大的应用。优化用户体验为你的应用添加图片预览、进度显示、结果导出等友好功能。探索高级功能尝试更复杂的问题如数学推理、逻辑分析、创意写作等。记住技术学习的核心是实践。多写代码多尝试不同的图片和问题你会越来越熟练。如果在使用过程中遇到问题记得查看服务日志那里面通常有解决问题的线索。获取更多AI镜像想探索更多AI镜像和应用场景访问 CSDN星图镜像广场提供丰富的预置镜像覆盖大模型推理、图像生成、视频生成、模型微调等多个领域支持一键部署。