SmolVLA入门编程教学用Python入门项目实践多模态AI调用想学Python但又觉得对着枯燥的语法和练习题提不起劲今天咱们换个玩法用一个真正“看得见、摸得着”的AI项目来驱动学习。这个项目就是调用SmolVLA——一个能看懂图片、和你聊天的多模态大模型。你不需要任何AI背景只需要一点Python基础甚至零基础跟着走也行。我们会从最基础的“Hello World”式调用开始一步步带你上传图片、解析结果最后亲手搭建一个能自动描述图片内容的小工具。整个过程你不仅是在写代码更是在和前沿的AI技术互动这种成就感可比单纯打印“Hello World”强多了。准备好了吗让我们用代码让AI“看见”世界。1. 环境准备搭建你的第一个AI编程空间在开始和AI对话之前我们需要一个干净、好用的编程环境。别担心步骤很简单就像安装一个手机App。1.1 安装Python给你的电脑装上“引擎”Python是我们的编程语言就像汽车的引擎。首先确认你的电脑是否已经安装了Python。打开你的命令行工具Windows上是“命令提示符”或PowerShellMac上是“终端”输入下面的命令并按回车python --version或者python3 --version如果屏幕上显示了类似Python 3.8.10这样的版本号恭喜你已经安装好了。如果提示“命令未找到”就需要去安装。安装建议新手首选直接访问 Python官网下载最新的稳定版比如Python 3.11或3.12。安装时务必勾选“Add Python to PATH”这个选项这能省去后面很多配置的麻烦。安装验证安装完成后重新打开命令行再次输入python --version看到版本号就成功了。1.2 安装必要的工具库准备好“工具箱”Python本身很强大但我们需要一些专门的“工具”来和AI模型通信。主要就是两个库requests用来发送网络请求Pillow用来处理图片。在命令行中输入以下命令来安装它们pip install requests Pillowpip是Python自带的包管理工具你可以把它想象成手机的应用商店。这条命令就是在“商店”里下载并安装requests和Pillow这两个“应用”。如果安装速度慢可以尝试使用国内的镜像源比如清华的源pip install requests Pillow -i https://pypi.tuna.tsinghua.edu.cn/simple看到一堆下载和安装成功的提示后工具箱就备齐了。1.3 获取API密钥拿到与AI对话的“通行证”要调用像SmolVLA这样的云端AI服务你需要一个API密钥。这就像你登录某个网站需要的用户名和密码是服务方识别你身份、进行计费的凭证。如何获取 通常你需要去提供该AI模型的平台例如阿里云、百度智能云、或模型提供方的官网注册一个账号。在账号的管理后台找到“API密钥”、“Access Key”或类似名称的页面创建一个新的密钥。这个过程通常是免费的并且会提供一定的免费调用额度供你体验。重要安全提示 这个API密钥非常重要千万不要直接写在你要分享或上传到公开网站的代码里一旦泄露别人可能会用你的密钥疯狂调用导致你账户欠费。我们接下来会学习如何安全地使用它。2. 初识SmolVLA从“Hello World”开始万事俱备让我们写下第一行能与AI“对话”的代码。我们从最简单的任务开始让AI描述一张网络上的图片。2.1 你的第一个API调用让AI看一张网络图片假设我们想让AI看看这张可爱的猫咪图片https://example.com/cat.jpg这是一个示例URL你需要替换成真实的、可公开访问的图片链接。创建一个新的Python文件比如叫做first_call.py用任何文本编辑器推荐VS Code、PyCharm或记事本打开输入以下代码import requests import json # 第一步准备好你的API密钥和服务地址这里需要替换成真实的 API_KEY YOUR_API_KEY_HERE # 请替换成你在平台上获取的真实密钥 API_URL https://api.example.com/v1/chat/completions # 请替换成真实的API端点地址 # 第二步告诉AI我们要做什么构建请求消息 headers { Authorization: fBearer {API_KEY}, Content-Type: application/json } # 第三步构造请求内容。我们给AI一张图片的URL并问它“描述这张图片” payload { model: smolvla, # 指定使用SmolVLA模型 messages: [ { role: user, content: [ {type: text, text: 请描述这张图片里有什么。}, { type: image_url, image_url: { url: https://example.com/cat.jpg # 替换成你的图片URL } } ] } ], max_tokens: 300 # 限制AI回复的最大长度 } # 第四步发送请求并等待AI的回复 response requests.post(API_URL, headersheaders, jsonpayload) # 第五步检查请求是否成功并打印AI的回答 if response.status_code 200: result response.json() # 从复杂的返回结果中提取出AI生成的文本内容 ai_reply result[choices][0][message][content] print(AI的描述) print(ai_reply) else: print(f请求失败状态码{response.status_code}) print(f错误信息{response.text})代码逐行解读import引入我们安装好的requests和json库。API_KEY和API_URL这是你需要修改的地方填入真实信息。headers在HTTP请求的“头部”带上我们的授权信息和数据格式。payload这是请求的“身体”核心部分。我们以“消息”列表的形式与AI对话。这里只有一条用户消息role: user消息内容包含一段文字和一个图片URL。requests.post用POST方法将我们的请求发送到API服务器。response.status_code检查服务器返回的状态码200代表成功。response.json()将服务器返回的JSON格式数据转换成Python的字典方便我们提取信息。运行一下将代码中的YOUR_API_KEY_HERE和https://api.example.com/v1/chat/completions替换成你从平台获取的真实信息。将https://example.com/cat.jpg替换成一个真实的图片URL例如在浏览器中打开一张图片复制地址栏的链接。在命令行中进入到你的代码文件所在目录运行python first_call.py如果一切顺利你将在命令行中看到AI对那张图片的描述这就是你的“Hello AI World”。2.2 处理本地图片上传你电脑里的照片让AI看网络图片很方便但更多时候我们想分析自己手机或电脑里的照片。这需要多一个步骤将图片文件编码后上传。创建一个新文件local_image.py代码如下import requests import json import base64 from PIL import Image import io # 你的API信息同样需要替换 API_KEY YOUR_API_KEY_HERE API_URL https://api.example.com/v1/chat/completions # 1. 读取并编码本地图片 def encode_image(image_path): with open(image_path, rb) as image_file: # 读取图片的二进制数据 image_data image_file.read() # 将二进制数据转换为base64编码的字符串 base64_image base64.b64encode(image_data).decode(utf-8) return base64_image # 指定你的本地图片路径例如./my_cat.jpg image_path ./my_cat.jpg base64_image encode_image(image_path) # 2. 构建请求与之前类似但图片数据格式不同 headers { Authorization: fBearer {API_KEY}, Content-Type: application/json } # 注意这里的图片格式不再是image_url而是image并且数据以base64字符串形式提供 payload { model: smolvla, messages: [ { role: user, content: [ {type: text, text: 请详细描述这张图片。}, { type: image_url, image_url: { # 这里拼接成Data URL格式 url: fdata:image/jpeg;base64,{base64_image} } } ] } ], max_tokens: 500 } # 3. 发送请求并打印结果 response requests.post(API_URL, headersheaders, jsonpayload) if response.status_code 200: result response.json() ai_reply result[choices][0][message][content] print(AI对本地图片的描述) print(ai_reply) else: print(f请求失败{response.status_code}) print(response.text)关键点解析encode_image函数它的工作是把一张图片比如JPG、PNG转换成一段长长的、由字母和数字组成的字符串base64编码。这样图片信息就可以像普通文本一样被放在JSON数据里通过网络发送。data:image/jpeg;base64,...这是一种特殊的URL格式直接在链接里包含了完整的图片数据省去了AI服务器再去下载的步骤。运行前请确保替换API密钥和地址。将./my_cat.jpg替换成你电脑上真实图片的路径例如C:/Users/YourName/Pictures/cat.jpg或/Users/YourName/Desktop/photo.png。图片文件确实存在。运行后AI就能“看到”并描述你电脑里的照片了。3. 项目实战构建简易图片描述生成器现在让我们把前面学到的知识组合起来做一个有点实用价值的小项目一个可以批量或交互式地为图片生成描述的脚本。3.1 设计程序功能我们希望这个程序能做两件事单张图片模式输入一张图片路径程序输出AI生成的描述并保存到文本文件。批量处理模式输入一个包含多张图片的文件夹路径程序为每张图片生成描述并分别保存。我们还会把API密钥等配置信息单独存放让代码更清晰、更安全。3.2 代码实现模块化与功能整合我们创建三个文件来组织代码文件一config.py(存放配置)# config.py # 将你的敏感信息和配置放在这里 API_KEY YOUR_API_KEY_HERE # 替换为你的真实密钥 API_URL https://api.example.com/v1/chat/completions MODEL_NAME smolvla文件二smolvla_client.py(核心调用客户端)# smolvla_client.py import requests import base64 from config import API_KEY, API_URL, MODEL_NAME class SmolVLAClient: def __init__(self): self.api_key API_KEY self.api_url API_URL self.headers { Authorization: fBearer {self.api_key}, Content-Type: application/json } def encode_image_to_base64(self, image_path): 将本地图片编码为base64字符串 with open(image_path, rb) as f: return base64.b64encode(f.read()).decode(utf-8) def describe_image(self, image_path, prompt请描述这张图片。, max_tokens300): 核心函数请求AI描述一张图片 :param image_path: 本地图片路径 :param prompt: 给AI的提示词 :param max_tokens: 回复的最大长度 :return: AI生成的描述文本如果失败则返回None try: # 1. 编码图片 base64_image self.encode_image_to_base64(image_path) # 2. 构建请求 payload { model: MODEL_NAME, messages: [ { role: user, content: [ {type: text, text: prompt}, { type: image_url, image_url: { url: fdata:image/jpeg;base64,{base64_image} } } ] } ], max_tokens: max_tokens } # 3. 发送请求 response requests.post(self.api_url, headersself.headers, jsonpayload, timeout30) response.raise_for_status() # 如果状态码不是200会抛出异常 # 4. 解析结果 result response.json() description result[choices][0][message][content] return description.strip() # 去掉首尾空格后返回 except FileNotFoundError: print(f错误找不到图片文件 {image_path}) return None except requests.exceptions.RequestException as e: print(f网络请求错误{e}) return None except (KeyError, IndexError) as e: print(f解析AI返回结果时出错{e}) print(f原始返回{response.text[:200]}...) # 打印前200字符便于调试 return None文件三main.py(主程序提供交互)# main.py import os from smolvla_client import SmolVLAClient def save_description(image_name, description, output_dir./descriptions): 将描述保存到文本文件 # 如果输出目录不存在则创建 if not os.path.exists(output_dir): os.makedirs(output_dir) # 根据图片名生成文本文件名例如my_cat.jpg - my_cat.txt txt_filename os.path.splitext(os.path.basename(image_name))[0] .txt txt_path os.path.join(output_dir, txt_filename) with open(txt_path, w, encodingutf-8) as f: f.write(description) print(f描述已保存至{txt_path}) def process_single_image(): 处理单张图片 client SmolVLAClient() image_path input(请输入单张图片的完整路径例如./photos/cat.jpg: ).strip() if not os.path.isfile(image_path): print(错误这不是一个有效的文件路径。) return custom_prompt input(请输入给AI的提示词直接回车使用默认提示: ).strip() if not custom_prompt: custom_prompt 请详细描述这张图片的内容包括主体、场景、颜色、氛围等。 print(正在请求AI分析图片请稍候...) description client.describe_image(image_path, promptcustom_prompt, max_tokens500) if description: print(\n *50) print(AI生成的描述) print(*50) print(description) print(*50) # 询问是否保存 save_choice input(\n是否将描述保存为文本文件(y/n): ).lower() if save_choice y: save_description(image_path, description) print(保存完成) else: print(未能获取图片描述。) def process_batch_images(): 批量处理一个文件夹内的图片 client SmolVLAClient() folder_path input(请输入包含图片的文件夹路径: ).strip() if not os.path.isdir(folder_path): print(错误这不是一个有效的文件夹路径。) return # 支持常见的图片格式 valid_extensions (.jpg, .jpeg, .png, .bmp, .gif) image_files [ f for f in os.listdir(folder_path) if os.path.isfile(os.path.join(folder_path, f)) and f.lower().endswith(valid_extensions) ] if not image_files: print(该文件夹内未找到支持的图片文件支持.jpg, .png, .bmp, .gif。) return print(f在文件夹中找到 {len(image_files)} 张图片。) custom_prompt input(请输入给AI的批量处理提示词直接回车使用默认提示: ).strip() if not custom_prompt: custom_prompt 请描述这张图片。 for idx, img_file in enumerate(image_files, 1): img_path os.path.join(folder_path, img_file) print(f\n正在处理 [{idx}/{len(image_files)}]: {img_file}) description client.describe_image(img_path, promptcustom_prompt) if description: # 自动保存 save_description(img_path, description) print(f - 已完成) else: print(f - 处理失败) print(f\n批量处理完成所有描述文件保存在 ./descriptions 目录下。) def main(): 主函数 print(欢迎使用简易图片描述生成器 (基于SmolVLA)) print(*50) while True: print(\n请选择模式) print( 1. 处理单张图片) print( 2. 批量处理文件夹内图片) print( 3. 退出程序) choice input(请输入选项 (1/2/3): ).strip() if choice 1: process_single_image() elif choice 2: process_batch_images() elif choice 3: print(感谢使用再见) break else: print(无效选项请重新输入。) if __name__ __main__: main()3.3 运行你的项目确保config.py中的API_KEY和API_URL已正确配置。将三份代码文件config.py,smolvla_client.py,main.py放在同一个文件夹下。在这个文件夹打开命令行运行python main.py根据屏幕提示选择模式单张或批量输入图片路径就可以体验你自己搭建的AI图片描述工具了这个项目虽然简单但你已经实现了一个完整的工作流读取配置、封装API调用、处理用户交互、文件操作、错误处理。这些都是Python编程中非常实用的技能。4. 进阶技巧与问题排查掌握了基本调用后我们来看看如何用得更好以及遇到问题怎么办。4.1 编写更有效的提示词给AI的“提示词”Prompt就像你给助手下达的指令指令越清晰结果越符合预期。基础描述“描述这张图片。”过于宽泛改进版“请用中文详细描述这张图片中的主体对象、背景环境、颜色构成以及整体氛围。”更具体限定了语言和描述维度带风格的描述“请用生动、富有文学性的语言描述这张风景照片重点突出光影和色彩。”问答形式“图片中有几个人他们大概在做什么天气看起来怎么样”提取特定信息“识别图片中的文字内容。”或“图片中的商品是什么品牌”在你的main.py程序中尝试输入不同的提示词看看AI生成的描述有何变化。4.2 常见错误与解决方法在调用过程中你可能会遇到一些错误。别慌大部分都有解决办法。错误现象可能原因解决方法401 UnauthorizedAPI密钥错误或过期检查config.py中的API_KEY是否正确并去平台确认密钥是否有效。404 Not FoundAPI地址错误检查config.py中的API_URL是否与平台提供的文档一致。400 Bad Request请求格式错误检查payload结构如图片格式、消息角色是否符合API文档要求。图片文件可能损坏或格式不支持。429 Too Many Requests请求频率超限平台通常有调用频率限制。等待一会儿再试或查看平台的配额说明。500 Internal Server Error服务器内部错误通常是服务提供方的问题。稍后重试或检查服务状态公告。程序报错FileNotFoundError图片路径错误检查输入的图片路径是否正确注意使用绝对路径或相对于程序运行目录的相对路径。返回结果解析出错 (KeyError)API返回格式变化打印出response.text查看实际返回的JSON结构调整代码中的解析逻辑。调试小技巧在smolvla_client.py的describe_image函数中我们用了try...except来捕获异常并打印了有用的错误信息。在开发时你可以在关键步骤后添加print语句例如打印payload的一部分来观察数据是否正确。4.3 下一步可以尝试什么这个入门项目为你打开了一扇门。掌握了基础调用后你可以尝试更多有趣的方向结合其他Python库用tkinter或PyQt给程序做个图形界面GUI实现拖拽上传图片。用openpyxl把生成的描述自动填入Excel表格。探索更多模型能力SmolVLA不仅能描述图片还能回答关于图片的问题、从图片中提取文本OCR、比较图片差异等。查阅官方API文档尝试不同的messages组合。加入工作流把它变成你日常的小助手。写个脚本自动监控某个文件夹一旦有新图片就调用AI生成描述并归档。学习更优的代码结构研究如何用logging模块替代print来记录日志如何用配置文件如config.ini或.env文件更安全地管理密钥如何用异步请求aiohttp来提升批量处理的速度。5. 总结与回顾走完这个教程你完成了一件很酷的事用Python代码让一个强大的多模态AI模型为你“看图说话”。我们从零开始搭建环境学习如何发送一个携带图片的HTTP请求解析AI返回的JSON数据最后把这些知识点整合成一个有模有样、具备交互和批量处理功能的小工具。这个过程里你实践了Python中文件操作、网络请求requests、数据编码base64、JSON处理、错误捕获try-except等多个核心概念。更重要的是你体验了如何将一个复杂的AI能力通过清晰的步骤和代码封装变成一个可以轻松使用的功能。这种“化繁为简”和“动手实现”的能力是编程学习中最宝贵的部分。代码本身还有很大的优化和扩展空间比如增加进度条、支持更多图片格式、缓存处理结果等等。但最重要的是你已经拿到了钥匙打开了这扇门。接下来是把它集成到更大的项目中还是探索其他AI模型的能力选择权就在你手里了。编程的学习之路就是在这样一个个有趣的项目实践中越走越稳越走越远。获取更多AI镜像想探索更多AI镜像和应用场景访问 CSDN星图镜像广场提供丰富的预置镜像覆盖大模型推理、图像生成、视频生成、模型微调等多个领域支持一键部署。
SmolVLA入门编程教学：用Python入门项目实践多模态AI调用
SmolVLA入门编程教学用Python入门项目实践多模态AI调用想学Python但又觉得对着枯燥的语法和练习题提不起劲今天咱们换个玩法用一个真正“看得见、摸得着”的AI项目来驱动学习。这个项目就是调用SmolVLA——一个能看懂图片、和你聊天的多模态大模型。你不需要任何AI背景只需要一点Python基础甚至零基础跟着走也行。我们会从最基础的“Hello World”式调用开始一步步带你上传图片、解析结果最后亲手搭建一个能自动描述图片内容的小工具。整个过程你不仅是在写代码更是在和前沿的AI技术互动这种成就感可比单纯打印“Hello World”强多了。准备好了吗让我们用代码让AI“看见”世界。1. 环境准备搭建你的第一个AI编程空间在开始和AI对话之前我们需要一个干净、好用的编程环境。别担心步骤很简单就像安装一个手机App。1.1 安装Python给你的电脑装上“引擎”Python是我们的编程语言就像汽车的引擎。首先确认你的电脑是否已经安装了Python。打开你的命令行工具Windows上是“命令提示符”或PowerShellMac上是“终端”输入下面的命令并按回车python --version或者python3 --version如果屏幕上显示了类似Python 3.8.10这样的版本号恭喜你已经安装好了。如果提示“命令未找到”就需要去安装。安装建议新手首选直接访问 Python官网下载最新的稳定版比如Python 3.11或3.12。安装时务必勾选“Add Python to PATH”这个选项这能省去后面很多配置的麻烦。安装验证安装完成后重新打开命令行再次输入python --version看到版本号就成功了。1.2 安装必要的工具库准备好“工具箱”Python本身很强大但我们需要一些专门的“工具”来和AI模型通信。主要就是两个库requests用来发送网络请求Pillow用来处理图片。在命令行中输入以下命令来安装它们pip install requests Pillowpip是Python自带的包管理工具你可以把它想象成手机的应用商店。这条命令就是在“商店”里下载并安装requests和Pillow这两个“应用”。如果安装速度慢可以尝试使用国内的镜像源比如清华的源pip install requests Pillow -i https://pypi.tuna.tsinghua.edu.cn/simple看到一堆下载和安装成功的提示后工具箱就备齐了。1.3 获取API密钥拿到与AI对话的“通行证”要调用像SmolVLA这样的云端AI服务你需要一个API密钥。这就像你登录某个网站需要的用户名和密码是服务方识别你身份、进行计费的凭证。如何获取 通常你需要去提供该AI模型的平台例如阿里云、百度智能云、或模型提供方的官网注册一个账号。在账号的管理后台找到“API密钥”、“Access Key”或类似名称的页面创建一个新的密钥。这个过程通常是免费的并且会提供一定的免费调用额度供你体验。重要安全提示 这个API密钥非常重要千万不要直接写在你要分享或上传到公开网站的代码里一旦泄露别人可能会用你的密钥疯狂调用导致你账户欠费。我们接下来会学习如何安全地使用它。2. 初识SmolVLA从“Hello World”开始万事俱备让我们写下第一行能与AI“对话”的代码。我们从最简单的任务开始让AI描述一张网络上的图片。2.1 你的第一个API调用让AI看一张网络图片假设我们想让AI看看这张可爱的猫咪图片https://example.com/cat.jpg这是一个示例URL你需要替换成真实的、可公开访问的图片链接。创建一个新的Python文件比如叫做first_call.py用任何文本编辑器推荐VS Code、PyCharm或记事本打开输入以下代码import requests import json # 第一步准备好你的API密钥和服务地址这里需要替换成真实的 API_KEY YOUR_API_KEY_HERE # 请替换成你在平台上获取的真实密钥 API_URL https://api.example.com/v1/chat/completions # 请替换成真实的API端点地址 # 第二步告诉AI我们要做什么构建请求消息 headers { Authorization: fBearer {API_KEY}, Content-Type: application/json } # 第三步构造请求内容。我们给AI一张图片的URL并问它“描述这张图片” payload { model: smolvla, # 指定使用SmolVLA模型 messages: [ { role: user, content: [ {type: text, text: 请描述这张图片里有什么。}, { type: image_url, image_url: { url: https://example.com/cat.jpg # 替换成你的图片URL } } ] } ], max_tokens: 300 # 限制AI回复的最大长度 } # 第四步发送请求并等待AI的回复 response requests.post(API_URL, headersheaders, jsonpayload) # 第五步检查请求是否成功并打印AI的回答 if response.status_code 200: result response.json() # 从复杂的返回结果中提取出AI生成的文本内容 ai_reply result[choices][0][message][content] print(AI的描述) print(ai_reply) else: print(f请求失败状态码{response.status_code}) print(f错误信息{response.text})代码逐行解读import引入我们安装好的requests和json库。API_KEY和API_URL这是你需要修改的地方填入真实信息。headers在HTTP请求的“头部”带上我们的授权信息和数据格式。payload这是请求的“身体”核心部分。我们以“消息”列表的形式与AI对话。这里只有一条用户消息role: user消息内容包含一段文字和一个图片URL。requests.post用POST方法将我们的请求发送到API服务器。response.status_code检查服务器返回的状态码200代表成功。response.json()将服务器返回的JSON格式数据转换成Python的字典方便我们提取信息。运行一下将代码中的YOUR_API_KEY_HERE和https://api.example.com/v1/chat/completions替换成你从平台获取的真实信息。将https://example.com/cat.jpg替换成一个真实的图片URL例如在浏览器中打开一张图片复制地址栏的链接。在命令行中进入到你的代码文件所在目录运行python first_call.py如果一切顺利你将在命令行中看到AI对那张图片的描述这就是你的“Hello AI World”。2.2 处理本地图片上传你电脑里的照片让AI看网络图片很方便但更多时候我们想分析自己手机或电脑里的照片。这需要多一个步骤将图片文件编码后上传。创建一个新文件local_image.py代码如下import requests import json import base64 from PIL import Image import io # 你的API信息同样需要替换 API_KEY YOUR_API_KEY_HERE API_URL https://api.example.com/v1/chat/completions # 1. 读取并编码本地图片 def encode_image(image_path): with open(image_path, rb) as image_file: # 读取图片的二进制数据 image_data image_file.read() # 将二进制数据转换为base64编码的字符串 base64_image base64.b64encode(image_data).decode(utf-8) return base64_image # 指定你的本地图片路径例如./my_cat.jpg image_path ./my_cat.jpg base64_image encode_image(image_path) # 2. 构建请求与之前类似但图片数据格式不同 headers { Authorization: fBearer {API_KEY}, Content-Type: application/json } # 注意这里的图片格式不再是image_url而是image并且数据以base64字符串形式提供 payload { model: smolvla, messages: [ { role: user, content: [ {type: text, text: 请详细描述这张图片。}, { type: image_url, image_url: { # 这里拼接成Data URL格式 url: fdata:image/jpeg;base64,{base64_image} } } ] } ], max_tokens: 500 } # 3. 发送请求并打印结果 response requests.post(API_URL, headersheaders, jsonpayload) if response.status_code 200: result response.json() ai_reply result[choices][0][message][content] print(AI对本地图片的描述) print(ai_reply) else: print(f请求失败{response.status_code}) print(response.text)关键点解析encode_image函数它的工作是把一张图片比如JPG、PNG转换成一段长长的、由字母和数字组成的字符串base64编码。这样图片信息就可以像普通文本一样被放在JSON数据里通过网络发送。data:image/jpeg;base64,...这是一种特殊的URL格式直接在链接里包含了完整的图片数据省去了AI服务器再去下载的步骤。运行前请确保替换API密钥和地址。将./my_cat.jpg替换成你电脑上真实图片的路径例如C:/Users/YourName/Pictures/cat.jpg或/Users/YourName/Desktop/photo.png。图片文件确实存在。运行后AI就能“看到”并描述你电脑里的照片了。3. 项目实战构建简易图片描述生成器现在让我们把前面学到的知识组合起来做一个有点实用价值的小项目一个可以批量或交互式地为图片生成描述的脚本。3.1 设计程序功能我们希望这个程序能做两件事单张图片模式输入一张图片路径程序输出AI生成的描述并保存到文本文件。批量处理模式输入一个包含多张图片的文件夹路径程序为每张图片生成描述并分别保存。我们还会把API密钥等配置信息单独存放让代码更清晰、更安全。3.2 代码实现模块化与功能整合我们创建三个文件来组织代码文件一config.py(存放配置)# config.py # 将你的敏感信息和配置放在这里 API_KEY YOUR_API_KEY_HERE # 替换为你的真实密钥 API_URL https://api.example.com/v1/chat/completions MODEL_NAME smolvla文件二smolvla_client.py(核心调用客户端)# smolvla_client.py import requests import base64 from config import API_KEY, API_URL, MODEL_NAME class SmolVLAClient: def __init__(self): self.api_key API_KEY self.api_url API_URL self.headers { Authorization: fBearer {self.api_key}, Content-Type: application/json } def encode_image_to_base64(self, image_path): 将本地图片编码为base64字符串 with open(image_path, rb) as f: return base64.b64encode(f.read()).decode(utf-8) def describe_image(self, image_path, prompt请描述这张图片。, max_tokens300): 核心函数请求AI描述一张图片 :param image_path: 本地图片路径 :param prompt: 给AI的提示词 :param max_tokens: 回复的最大长度 :return: AI生成的描述文本如果失败则返回None try: # 1. 编码图片 base64_image self.encode_image_to_base64(image_path) # 2. 构建请求 payload { model: MODEL_NAME, messages: [ { role: user, content: [ {type: text, text: prompt}, { type: image_url, image_url: { url: fdata:image/jpeg;base64,{base64_image} } } ] } ], max_tokens: max_tokens } # 3. 发送请求 response requests.post(self.api_url, headersself.headers, jsonpayload, timeout30) response.raise_for_status() # 如果状态码不是200会抛出异常 # 4. 解析结果 result response.json() description result[choices][0][message][content] return description.strip() # 去掉首尾空格后返回 except FileNotFoundError: print(f错误找不到图片文件 {image_path}) return None except requests.exceptions.RequestException as e: print(f网络请求错误{e}) return None except (KeyError, IndexError) as e: print(f解析AI返回结果时出错{e}) print(f原始返回{response.text[:200]}...) # 打印前200字符便于调试 return None文件三main.py(主程序提供交互)# main.py import os from smolvla_client import SmolVLAClient def save_description(image_name, description, output_dir./descriptions): 将描述保存到文本文件 # 如果输出目录不存在则创建 if not os.path.exists(output_dir): os.makedirs(output_dir) # 根据图片名生成文本文件名例如my_cat.jpg - my_cat.txt txt_filename os.path.splitext(os.path.basename(image_name))[0] .txt txt_path os.path.join(output_dir, txt_filename) with open(txt_path, w, encodingutf-8) as f: f.write(description) print(f描述已保存至{txt_path}) def process_single_image(): 处理单张图片 client SmolVLAClient() image_path input(请输入单张图片的完整路径例如./photos/cat.jpg: ).strip() if not os.path.isfile(image_path): print(错误这不是一个有效的文件路径。) return custom_prompt input(请输入给AI的提示词直接回车使用默认提示: ).strip() if not custom_prompt: custom_prompt 请详细描述这张图片的内容包括主体、场景、颜色、氛围等。 print(正在请求AI分析图片请稍候...) description client.describe_image(image_path, promptcustom_prompt, max_tokens500) if description: print(\n *50) print(AI生成的描述) print(*50) print(description) print(*50) # 询问是否保存 save_choice input(\n是否将描述保存为文本文件(y/n): ).lower() if save_choice y: save_description(image_path, description) print(保存完成) else: print(未能获取图片描述。) def process_batch_images(): 批量处理一个文件夹内的图片 client SmolVLAClient() folder_path input(请输入包含图片的文件夹路径: ).strip() if not os.path.isdir(folder_path): print(错误这不是一个有效的文件夹路径。) return # 支持常见的图片格式 valid_extensions (.jpg, .jpeg, .png, .bmp, .gif) image_files [ f for f in os.listdir(folder_path) if os.path.isfile(os.path.join(folder_path, f)) and f.lower().endswith(valid_extensions) ] if not image_files: print(该文件夹内未找到支持的图片文件支持.jpg, .png, .bmp, .gif。) return print(f在文件夹中找到 {len(image_files)} 张图片。) custom_prompt input(请输入给AI的批量处理提示词直接回车使用默认提示: ).strip() if not custom_prompt: custom_prompt 请描述这张图片。 for idx, img_file in enumerate(image_files, 1): img_path os.path.join(folder_path, img_file) print(f\n正在处理 [{idx}/{len(image_files)}]: {img_file}) description client.describe_image(img_path, promptcustom_prompt) if description: # 自动保存 save_description(img_path, description) print(f - 已完成) else: print(f - 处理失败) print(f\n批量处理完成所有描述文件保存在 ./descriptions 目录下。) def main(): 主函数 print(欢迎使用简易图片描述生成器 (基于SmolVLA)) print(*50) while True: print(\n请选择模式) print( 1. 处理单张图片) print( 2. 批量处理文件夹内图片) print( 3. 退出程序) choice input(请输入选项 (1/2/3): ).strip() if choice 1: process_single_image() elif choice 2: process_batch_images() elif choice 3: print(感谢使用再见) break else: print(无效选项请重新输入。) if __name__ __main__: main()3.3 运行你的项目确保config.py中的API_KEY和API_URL已正确配置。将三份代码文件config.py,smolvla_client.py,main.py放在同一个文件夹下。在这个文件夹打开命令行运行python main.py根据屏幕提示选择模式单张或批量输入图片路径就可以体验你自己搭建的AI图片描述工具了这个项目虽然简单但你已经实现了一个完整的工作流读取配置、封装API调用、处理用户交互、文件操作、错误处理。这些都是Python编程中非常实用的技能。4. 进阶技巧与问题排查掌握了基本调用后我们来看看如何用得更好以及遇到问题怎么办。4.1 编写更有效的提示词给AI的“提示词”Prompt就像你给助手下达的指令指令越清晰结果越符合预期。基础描述“描述这张图片。”过于宽泛改进版“请用中文详细描述这张图片中的主体对象、背景环境、颜色构成以及整体氛围。”更具体限定了语言和描述维度带风格的描述“请用生动、富有文学性的语言描述这张风景照片重点突出光影和色彩。”问答形式“图片中有几个人他们大概在做什么天气看起来怎么样”提取特定信息“识别图片中的文字内容。”或“图片中的商品是什么品牌”在你的main.py程序中尝试输入不同的提示词看看AI生成的描述有何变化。4.2 常见错误与解决方法在调用过程中你可能会遇到一些错误。别慌大部分都有解决办法。错误现象可能原因解决方法401 UnauthorizedAPI密钥错误或过期检查config.py中的API_KEY是否正确并去平台确认密钥是否有效。404 Not FoundAPI地址错误检查config.py中的API_URL是否与平台提供的文档一致。400 Bad Request请求格式错误检查payload结构如图片格式、消息角色是否符合API文档要求。图片文件可能损坏或格式不支持。429 Too Many Requests请求频率超限平台通常有调用频率限制。等待一会儿再试或查看平台的配额说明。500 Internal Server Error服务器内部错误通常是服务提供方的问题。稍后重试或检查服务状态公告。程序报错FileNotFoundError图片路径错误检查输入的图片路径是否正确注意使用绝对路径或相对于程序运行目录的相对路径。返回结果解析出错 (KeyError)API返回格式变化打印出response.text查看实际返回的JSON结构调整代码中的解析逻辑。调试小技巧在smolvla_client.py的describe_image函数中我们用了try...except来捕获异常并打印了有用的错误信息。在开发时你可以在关键步骤后添加print语句例如打印payload的一部分来观察数据是否正确。4.3 下一步可以尝试什么这个入门项目为你打开了一扇门。掌握了基础调用后你可以尝试更多有趣的方向结合其他Python库用tkinter或PyQt给程序做个图形界面GUI实现拖拽上传图片。用openpyxl把生成的描述自动填入Excel表格。探索更多模型能力SmolVLA不仅能描述图片还能回答关于图片的问题、从图片中提取文本OCR、比较图片差异等。查阅官方API文档尝试不同的messages组合。加入工作流把它变成你日常的小助手。写个脚本自动监控某个文件夹一旦有新图片就调用AI生成描述并归档。学习更优的代码结构研究如何用logging模块替代print来记录日志如何用配置文件如config.ini或.env文件更安全地管理密钥如何用异步请求aiohttp来提升批量处理的速度。5. 总结与回顾走完这个教程你完成了一件很酷的事用Python代码让一个强大的多模态AI模型为你“看图说话”。我们从零开始搭建环境学习如何发送一个携带图片的HTTP请求解析AI返回的JSON数据最后把这些知识点整合成一个有模有样、具备交互和批量处理功能的小工具。这个过程里你实践了Python中文件操作、网络请求requests、数据编码base64、JSON处理、错误捕获try-except等多个核心概念。更重要的是你体验了如何将一个复杂的AI能力通过清晰的步骤和代码封装变成一个可以轻松使用的功能。这种“化繁为简”和“动手实现”的能力是编程学习中最宝贵的部分。代码本身还有很大的优化和扩展空间比如增加进度条、支持更多图片格式、缓存处理结果等等。但最重要的是你已经拿到了钥匙打开了这扇门。接下来是把它集成到更大的项目中还是探索其他AI模型的能力选择权就在你手里了。编程的学习之路就是在这样一个个有趣的项目实践中越走越稳越走越远。获取更多AI镜像想探索更多AI镜像和应用场景访问 CSDN星图镜像广场提供丰富的预置镜像覆盖大模型推理、图像生成、视频生成、模型微调等多个领域支持一键部署。
