基于Qwen2.5-VL-7B-Instruct的Agent Skill开发指南：构建智能体技能库-智慧文博士

基于Qwen2.5-VL-7B-Instruct的Agent Skill开发指南：构建智能体技能库

最近在折腾智能体开发，发现很多朋友对如何让AI模型“动起来”特别感兴趣。不是那种简单的问答，而是让它能看懂图片、分析视频，然后根据看到的内容去执行一些具体的操作，比如帮你操作手机、分析文档，甚至控制一些外部工具。这其实就是智能体（Agent）的核心能力。

今天咱们就来聊聊怎么用Qwen2.5-VL-7B-Instruct这个视觉语言模型，从头开始搭建一套属于自己的Agent Skill（智能体技能）。这个模型有个特别厉害的地方，它天生就具备“智能体”的特性，官方文档里直接说了它能“扮演视觉智能体，进行推理并动态调用工具”，支持电脑和手机操作。这意味着我们不用从零开始教它怎么当Agent，而是可以直接在它的能力基础上，构建我们想要的技能。

如果你之前接触过一些大模型，但还没试过让它们“动手做事”，那这篇文章应该能给你一些实用的思路和代码。咱们的目标很明确：不搞复杂的理论，直接上手，让你能快速开发出几个可用的技能。

1. 先聊聊什么是Agent Skill

可能你听过“智能体”这个词，感觉挺高大上的。其实简单来说，一个具备Skill的智能体，就像是一个配备了多种专业工具的助手。它不仅能听懂你的话（文本理解），还能看懂你给它的图片或视频（视觉理解），然后根据这些信息，决定调用哪个工具（技能）来帮你解决问题。

举个例子，你拍了一张发票的照片发给它，它不仅能识别出上面的文字（OCR），还能提取出关键信息如金额、日期、商品名称（信息抽取），然后自动帮你整理成结构化的数据（比如JSON），甚至填入你的报销系统。这一整套流程，就可以封装成一个“发票处理”技能。

Qwen2.5-VL-7B-Instruct在这个场景下就很有优势。它本身支持：

视觉理解：识别图片里的物体、文字、图表。
结构化输出：能稳定地输出JSON格式，这对于技能间传递数据至关重要。
工具调用倾向：模型设计时考虑了智能体场景，更容易引导它去“使用工具”。

我们的开发工作，就是定义好这些“技能”的规范，教会模型在什么情况下该调用哪个技能，并处理好技能执行前后的逻辑。

2. 环境准备与模型快速上手

在开始构建技能库之前，我们得先把模型跑起来。这里提供两种简单的方式，你可以根据自己的情况选择。

2.1 使用Ollama快速体验（推荐新手）

如果你只是想快速体验模型的能力，Ollama是最省事的方法。确保你安装了0.7.0或更高版本的Ollama。

打开终端，一行命令就能拉取并运行模型：

ollama run qwen2.5vl:7b

运行后，你就进入了交互模式。你可以直接输入文字提问，或者按照Ollama的API方式，上传图片进行多轮对话。这对于测试模型的基础视觉和推理能力非常方便。

2.2 使用Hugging Face Transformers进行开发

如果我们想要更灵活地控制模型，集成到自己的Python项目中，或者需要实现复杂的技能调度逻辑，那么使用Hugging Face的transformers库是更专业的选择。

首先，安装必要的库：

pip install transformers torch accelerate pillow

然后，我们可以用下面这段代码快速测试一下模型的基本图文对话能力：

from transformers import Qwen2_5VLForConditionalGeneration, AutoTokenizer, AutoProcessor from PIL import Image import torch # 加载模型、tokenizer和processor model_name = "Qwen/Qwen2.5-VL-7B-Instruct" model = Qwen2_5VLForConditionalGeneration.from_pretrained( model_name, torch_dtype=torch.float16, # 使用半精度节省显存 device_map="auto" # 自动分配模型层到GPU/CPU ) tokenizer = AutoTokenizer.from_pretrained(model_name) processor = AutoProcessor.from_pretrained(model_name) # 准备输入：一段文本和一张图片 text = "请描述这张图片里的主要内容。" # 假设我们有一张名为‘test_image.jpg’的图片 image = Image.open("test_image.jpg").convert("RGB") # 使用processor处理多模态输入 inputs = processor( text=[text], images=[image], padding=True, return_tensors="pt" ).to(model.device) # 生成回复 with torch.no_grad(): generated_ids = model.generate(**inputs, max_new_tokens=512) generated_text = tokenizer.batch_decode(generated_ids, skip_special_tokens=True)[0] print("模型回复：", generated_text)

这段代码做了几件事：加载模型、处理图文混合输入、让模型生成描述。跑通这个，就证明你的基础环境没问题了。

3. 设计你的第一个Agent Skill：图片信息提取器

好了，环境搭好了，模型也能跑了。现在我们来设计一个实实在在的技能。我们从一个相对简单但实用的技能开始：图片信息提取器。

这个技能的目标是：用户上传一张图片，并说明想提取什么信息（比如“找出所有商品的价格”），技能会调用模型进行分析，并返回结构化的结果。

3.1 定义技能规范

一个技能至少需要包含以下几个部分：

技能名称（Skill Name）：唯一标识，比如image_info_extractor。
技能描述（Description）：告诉模型这个技能是干什么用的。
触发意图（Intent）：用户说什么话时，应该调用这个技能。我们可以用关键词或意图分类器来识别。
输入参数（Input Parameters）：技能需要什么，比如图片路径、用户的具体问题文本。
执行函数（Execution Function）：技能具体的执行逻辑，这里就是调用模型并解析输出。
输出格式（Output Format）：技能返回的数据结构，比如JSON。

下面我们用代码来定义这个技能：

import json import re from typing import Dict, Any, Optional class ImageInfoExtractorSkill: """技能：图片信息提取器""" def __init__(self, model, tokenizer, processor): self.model = model self.tokenizer = tokenizer self.processor = processor self.name = "image_info_extractor" self.description = "从图片中提取指定信息，如文字、物体、价格等，并返回结构化数据。" # 简单的意图关键词匹配 self.trigger_keywords = ["提取", "找出", "识别", "图片里有什么", "信息是什么"] def should_trigger(self, user_input: str) -> bool: """判断是否触发此技能""" user_input_lower = user_input.lower() return any(keyword in user_input_lower for keyword in self.trigger_keywords) def build_prompt(self, user_input: str) -> str: """构建给模型的提示词，引导其结构化输出""" # 这是关键：通过系统提示词引导模型以JSON格式思考和工作 system_prompt = """你是一个信息提取助手。请根据用户的要求，分析图片，并将提取到的信息以规范的JSON格式输出。 例如，如果用户问“图片中有哪些商品和价格？”，你应该输出类似： { "items": [ {"name": "商品A", "price": "100元"}, {"name": "商品B", "price": "200元"} ] } 请确保只输出JSON，不要有其他解释性文字。""" # 将系统提示和用户问题结合。Qwen2.5-VL使用特定的对话格式 # 根据模型的实际对话模板调整，这里是一个通用示例 full_prompt = f"<|im_start|>system\n{system_prompt}<|im_end|>\n<|im_start|>user\n{user_input}<|im_end|>\n<|im_start|>assistant\n" return full_prompt def execute(self, image_path: str, user_input: str) -> Dict[str, Any]: """执行技能：分析图片并提取信息""" try: # 1. 加载图片 image = Image.open(image_path).convert("RGB") # 2. 构建引导模型结构化输出的提示词 prompt = self.build_prompt(user_input) # 3. 处理输入 inputs = self.processor( text=[prompt], images=[image], padding=True, return_tensors="pt" ).to(self.model.device) # 4. 生成回复。为了获得更稳定的JSON，可以降低temperature with torch.no_grad(): generated_ids = self.model.generate( **inputs, max_new_tokens=1024, temperature=0.1, # 低温度使输出更确定，有利于JSON格式 do_sample=False # 贪婪解码，进一步稳定输出 ) raw_output = self.tokenizer.batch_decode(generated_ids, skip_special_tokens=True)[0] # 5. 从模型输出中剥离我们添加的提示词部分，只获取助手的回复 assistant_response = raw_output.split("<|im_start|>assistant\n")[-1].strip() # 6. 尝试从回复中解析JSON # 模型可能不会100%精确输出纯JSON，可能会有些前后文字，这里尝试提取 json_match = re.search(r'\{.*\}', assistant_response, re.DOTALL) if json_match: json_str = json_match.group() extracted_info = json.loads(json_str) return { "success": True, "skill_name": self.name, "data": extracted_info, "raw_response": assistant_response # 保留原始响应供调试 } else: # 如果没解析出JSON，返回原始文本 return { "success": False, "skill_name": self.name, "error": "未能解析出结构化JSON数据。", "raw_response": assistant_response } except Exception as e: return { "success": False, "skill_name": self.name, "error": f"技能执行失败: {str(e)}" }

3.2 测试技能

让我们写个简单的测试脚本来看看这个技能的效果。假设你有一张包含商品和价格的截图receipt.jpg。

# 初始化技能（使用之前加载的model, tokenizer, processor） info_extractor_skill = ImageInfoExtractorSkill(model, tokenizer, processor) # 测试用例 image_path = "receipt.jpg" user_query = "请提取这张小票上的所有商品名称和对应的价格。" if info_extractor_skill.should_trigger(user_query): result = info_extractor_skill.execute(image_path, user_query) print(json.dumps(result, indent=2, ensure_ascii=False)) else: print("未触发图片信息提取技能。")

如果一切顺利，result里的data字段就会包含一个JSON对象，里面是提取到的商品和价格列表。这就是你的第一个Agent Skill产出的结构化结果！

4. 构建技能库与意图路由器

单个技能用处有限，智能体得有多样化的技能才能应对复杂场景。所以我们需要一个技能库（Skill Library）和一个意图路由器（Intent Router）。

技能库负责管理所有注册的技能。意图路由器的任务是根据用户的输入，决定调用哪个技能最合适。

4.1 实现简单的技能管理器

class SkillManager: """管理所有技能并路由用户请求""" def __init__(self): self.skills = {} # name -> skill_object # 可以在这里添加一个更复杂的意图识别模型（例如用一个小型文本分类模型）， # 但为了教程简单，我们先用关键词匹配。 def register_skill(self, skill): """注册一个技能""" self.skills[skill.name] = skill print(f"技能已注册: {skill.name} - {skill.description}") def route_and_execute(self, image_path: Optional[str], user_input: str) -> Dict[str, Any]: """路由用户请求到合适的技能并执行""" if not self.skills: return {"error": "技能库为空"} # 第一步：遍历所有技能，看哪个被触发 triggered_skills = [] for skill_name, skill in self.skills.items(): if hasattr(skill, 'should_trigger') and skill.should_trigger(user_input): triggered_skills.append(skill) # 第二步：选择优先级最高的技能（这里简单取第一个） if triggered_skills: selected_skill = triggered_skills[0] print(f"路由到技能: {selected_skill.name}") # 执行选中的技能 if image_path: return selected_skill.execute(image_path, user_input) else: # 有些技能可能不需要图片 return {"error": "该技能需要图片输入，但未提供。"} else: # 没有技能被触发，返回默认回复或调用通用对话模型 return { "skill_name": "fallback", "response": "抱歉，我暂时无法处理这个请求。您可以尝试更清晰地描述您的需求，例如‘提取图片中的文字’或‘描述这张图片’。" }

4.2 组装你的智能体

现在，我们把技能管理器和具体的技能组装起来，形成一个可用的智能体原型。

# 初始化技能管理器 manager = SkillManager() # 创建并注册技能（需要传入之前加载的model, tokenizer, processor） skill1 = ImageInfoExtractorSkill(model, tokenizer, processor) manager.register_skill(skill1) # 你可以在这里创建并注册更多技能，例如： # skill2 = DocumentQASkill(model, tokenizer, processor) # 文档问答技能 # manager.register_skill(skill2) # skill3 = ObjectCounterSkill(model, tokenizer, processor) # 物体计数技能 # manager.register_skill(skill3) # 模拟用户交互 def chat_with_agent(image_path=None): print("智能体已就绪。输入‘退出’来结束对话。") while True: user_input = input("\n您: ") if user_input.lower() in ['退出', 'exit', 'quit']: break if not user_input.strip(): continue # 将请求路由并执行 result = manager.route_and_execute(image_path, user_input) # 展示结果 if result.get("success"): print(f"\n智能体 ({result['skill_name']}): 信息提取成功！") print("结构化数据:", json.dumps(result["data"], indent=2, ensure_ascii=False)) else: # 执行失败或触发了fallback print(f"\n智能体: {result.get('response', result.get('error', '未知错误'))}") # 开始聊天（如果本次对话有图片，传入图片路径） # chat_with_agent("conversation_image.jpg") chat_with_agent() # 如果不传路径，技能需要图片时会提示

这样，一个具备基础技能路由和执行能力的智能体框架就搭建起来了。当你输入“帮我提取这张图片里的价格”时，它应该能自动调用ImageInfoExtractorSkill并返回JSON结果。

5. 进阶技能示例：视觉定位与坐标输出

Qwen2.5-VL有一个强大的功能是视觉定位（Visual Grounding），能输出图中物体的边界框（bbox）或关键点坐标。我们可以利用这个能力，开发一个“物体定位”技能。

这个技能在安防、零售、自动驾驶等领域都有应用场景，比如“找出图中所有的汽车并标出位置”。

class VisualGroundingSkill: """技能：视觉定位 - 识别并定位图片中的特定物体""" def __init__(self, model, tokenizer, processor): self.model = model self.tokenizer = tokenizer self.processor = processor self.name = "visual_grounding" self.description = "识别图片中的特定物体，并返回它们的边界框坐标或关键点。" self.trigger_keywords = ["定位", "在哪里", "框出", "标出", "坐标", "bbox", "边界框"] def should_trigger(self, user_input: str) -> bool: user_input_lower = user_input.lower() return any(keyword in user_input_lower for keyword in self.trigger_keywords) def execute(self, image_path: str, user_input: str) -> Dict[str, Any]: try: image = Image.open(image_path).convert("RGB") # 构建非常具体的提示词，要求模型输出标准JSON # Qwen2.5-VL在训练时接触过大量类似的定位指令，效果很好 system_prompt = """你是一个视觉定位系统。用户会描述他想在图片中定位的物体。 你必须以严格的JSON数组格式输出结果，每个对象包含'bbox_2d'和'label'字段。 'bbox_2d'格式是[x1, y1, x2, y2]，代表左上角和右下角的坐标。 例如：[{"bbox_2d": [100, 150, 200, 300], "label": "dog"}, ...] 只输出JSON，不要有任何其他文字。""" prompt = f"<|im_start|>system\n{system_prompt}<|im_end|>\n<|im_start|>user\n{user_input}<|im_end|>\n<|im_start|>assistant\n" inputs = self.processor( text=[prompt], images=[image], padding=True, return_tensors="pt" ).to(self.model.device) with torch.no_grad(): generated_ids = self.model.generate( **inputs, max_new_tokens=512, temperature=0.01, # 极低温度确保格式稳定 do_sample=False ) raw_output = self.tokenizer.batch_decode(generated_ids, skip_special_tokens=True)[0] assistant_response = raw_output.split("<|im_start|>assistant\n")[-1].strip() # 尝试解析JSON数组 import re json_match = re.search(r'\[.*\]', assistant_response, re.DOTALL) if json_match: json_str = json_match.group() locations = json.loads(json_str) return { "success": True, "skill_name": self.name, "data": { "locations": locations, "image_size": image.size # 返回图片尺寸，便于前端绘制 } } else: return { "success": False, "skill_name": self.name, "error": "模型未返回标准JSON格式。", "raw_response": assistant_response } except json.JSONDecodeError as e: return { "success": False, "skill_name": self.name, "error": f"JSON解析失败: {str(e)}", "raw_response": assistant_response } except Exception as e: return { "success": False, "skill_name": self.name, "error": f"技能执行失败: {str(e)}" }

把这个技能也注册到管理器里：

grounding_skill = VisualGroundingSkill(model, tokenizer, processor) manager.register_skill(grounding_skill)

现在，你的智能体就能处理像“定位图片中所有的行人”这样的请求了，并返回一串带坐标的JSON数据。你可以用这些数据在原图上绘制方框，实现一个简单的目标检测效果。

6. 让技能更实用：对话历史与工具调用

到目前为止，我们的技能还是“一次性”的。一个真正的智能体应该能记住对话上下文，并且能主动调用外部工具。

6.1 维护对话历史

我们可以修改技能管理器，让它维护一个简单的对话历史列表，并在每次调用模型时，将历史对话作为上下文传入。

class ConversationalSkillManager(SkillManager): """支持对话历史的技能管理器""" def __init__(self, max_history=5): super().__init__() self.conversation_history = [] # 存储格式: [{"role": "user", "content": "..."}, {"role": "assistant", "content": "..."}] self.max_history = max_history def add_to_history(self, role, content): self.conversation_history.append({"role": role, "content": content}) # 限制历史长度 if len(self.conversation_history) > self.max_history * 2: # 乘以2因为包含user和assistant self.conversation_history = self.conversation_history[-self.max_history*2:] def route_and_execute(self, image_path: Optional[str], user_input: str) -> Dict[str, Any]: # 将用户输入加入历史 self.add_to_history("user", user_input) # 原有的路由逻辑... result = super().route_and_execute(image_path, user_input) # 将智能体回复加入历史 if result.get("success"): response_to_remember = json.dumps(result["data"], ensure_ascii=False) else: response_to_remember = result.get("response", "技能执行完成。") self.add_to_history("assistant", response_to_remember) return result

这样，技能在执行时，可以从self.conversation_history中获取上下文，处理像“刚才你找到的那个商品，它的价格是多少？”这样的指代性问题。

6.2 集成真实工具调用

“智能体”最酷的一点是能操作真实世界的工具。Qwen2.5-VL的论文里展示了它控制手机和电脑的潜力。我们可以模拟这个流程。

假设我们有一个工具：send_email(to, subject, body)。我们可以创建一个“邮件助手”技能。

关键在于，我们不仅要让模型知道有这个工具，还要让它生成调用这个工具所需的精确参数。这通常通过**函数调用（Function Calling）**来实现。

定义工具列表：用JSON Schema描述每个工具的功能和参数。
在提示词中告知模型：让模型知道它可以“使用”这些工具。
解析模型输出：模型可能会在回复中声明它想调用哪个工具，并提供参数。
安全地执行工具：在沙箱或受控环境中执行对应的Python函数。

由于篇幅限制，这里给出一个高度简化的概念示例：

# 1. 定义工具 tools = [ { "name": "send_email", "description": "发送一封电子邮件", "parameters": { "type": "object", "properties": { "to": {"type": "string", "description": "收件人邮箱地址"}, "subject": {"type": "string", "description": "邮件主题"}, "body": {"type": "string", "description": "邮件正文"} }, "required": ["to", "subject", "body"] } }, # ... 其他工具 ] # 2. 在构建给模型的提示词时，将工具描述加入系统提示 system_prompt_with_tools = f"""你是智能助手，可以调用工具来帮助用户。 以下是你可以调用的工具： {json.dumps(tools, indent=2)} 当你需要调用工具时，请严格按照以下格式回复： <|tool_call|> {{"name": "tool_name", "arguments": {{"arg1": "value1", ...}}}} <|tool_call|> 然后我会执行工具并告诉你结果。""" # 3. 在模型的回复中，解析 <|tool_call|> 标签之间的内容 # 4. 如果解析成功，则调用对应的函数，并将结果作为下一轮对话的上下文反馈给模型。

实现完整的、安全的工具调用框架比较复杂，涉及到输出解析、参数验证、权限控制等。但核心思路就是：引导模型生成结构化的工具调用请求，然后由你的代码去安全地执行它。Qwen2.5-VL由于支持稳定的结构化输出，在这方面有天然优势。

7. 开发过程中的实用技巧与避坑指南

折腾了这么久，我也总结了一些经验和容易踩的坑，分享给你。

提示词工程是关键：想要模型稳定输出JSON，系统提示词要写得非常明确。多用“必须”、“只输出”、“格式为”等强约束词语，并给出清晰的例子。对于Qwen2.5-VL，使用其训练时的对话格式（<|im_start|>等）通常效果更好。
温度（Temperature）设置：生成结构化内容（如JSON、代码）时，将temperature设低（如0.1），甚至使用贪婪解码（do_sample=False），可以大幅提高输出格式的稳定性。普通对话时可以调高。
错误处理要健壮：模型并不总是听话。你的代码一定要能处理模型输出非JSON、格式错误、甚至胡说八道的情况。做好try...except，并给用户友好的回退提示。
技能冲突与优先级：当多个技能的关键词重叠时，需要有更精细的路由策略。可以给技能设置优先级分数，或者使用一个更小的文本分类模型来做意图识别。
注意计算资源：Qwen2.5-VL-7B对显存有一定要求。处理高分辨率图片或长视频时，注意使用max_pixels等参数控制输入尺寸，或者使用动态分块处理策略，避免OOM（内存溢出）。
从简单开始：先实现一个能跑通的简单技能，再慢慢增加复杂性。不要一开始就追求一个全能的、能调用无数工具的超级智能体。

8. 总结与展望

走完这一趟，你应该对如何用Qwen2.5-VL-7B-Instruct开发Agent Skill有了一个从概念到实践的认识。我们从一个简单的图片信息提取技能开始，逐步构建了技能库、意图路由器，甚至还探讨了视觉定位和工具调用的进阶话题。

这个模型的视觉理解能力和结构化输出特性，让它成为开发视觉类智能体的一个非常不错的起点。你完全可以基于今天介绍的框架，去扩展更多的技能，比如：

文档问答技能：上传论文或报告，让它帮你总结。
图表分析技能：识别折线图、柱状图，并描述趋势。
工作流自动化技能：结合RPA工具，实现“看到某个按钮就点击”的自动化操作。

当然，现在的框架还有很多可以优化的地方，比如引入向量数据库来管理技能描述以实现更精准的匹配，或者用更复杂的Agent框架（如LangChain、Transformers Agents）来重构。但无论如何，亲手把一个个想法变成能运行的代码，看着模型按照你的设计去理解、推理、行动，这个过程本身就充满了乐趣和成就感。

希望这篇指南能帮你打开智能体开发的大门。接下来，就大胆地去定义你自己的技能，解决你实际遇到的问题吧。先从一个小而美的技能开始，把它做深做透，你会收获更多。