VisionAgent 使用指南：从环境配置到视觉 Agent 代码生成的完整实战

VisionAgent 使用指南从环境配置到视觉 Agent 代码生成的完整实战【免费下载链接】vision-agentThis tool has been deprecated. Use Agentic Document Extraction instead.项目地址: https://gitcode.com/GitHub_Trending/vi/vision-agent本篇技术指南以 vision-agent 仓库的官方文档为主体系统讲解 LandingAI 开源的VisionAgent视觉智能体Visual AI Agent的完整使用流程从 API Key 获取、库安装、快速开始脚本到直接调用内置视觉工具完成图像计数与视频目标跟踪再到切换底层 LLM 提供商的配置方法。读完本文你将能够独立搭建运行环境、用几行代码驱动 VisionAgent 生成并自动测试视觉代码也能在自有脚本中直接复用其检测、分割、跟踪等工具函数。什么是 VisionAgentVisionAgent 是 LandingAI 推出的视觉 AI 助手Visual AI pilot给它一段自然语言提示prompt和一张图片或一段视频它会自动挑选合适的视觉模型并输出可直接运行的代码让你在几分钟内构建起具备视觉能力的应用。官方文档的定位语是Prompt with an image/video → Get runnable vision code → Build Visual AI App in minutes在其核心架构中VisionAgent 并不直接输出答案而是输出程序它会先规划代码生成任务、生成代码与测试用例、在代码沙箱中执行测试并在失败时迭代修复最终交出一份通过测试的、可复用的视觉处理代码。这一生成链路可在 vision_agent/agent/vision_agent_coder_v2.py 中看到完整实现详见下文代码生成流程的源码级拆解。官方文档同时提供本地 Web 应用位于 examples/chat 目录其运行说明见 examples/chat/README.md方便你在图形界面中直接体验 VisionAgent。环境准备三类 API Key 的用途与获取使用 VisionAgent 前最关键的一步是准备 API Key。共需要三类API Key用途说明VisionAgent API Key调用 LandingAI 托管的视觉模型服务在 VisionAgent 官网注册账号后获取Anthropic API Key驱动规划、写码、测试、调试等 Agent 角色在 Anthropic Console 的 API Keys 页面生成Google API Key驱动部分视觉问答VQA等任务在 Google AI Studio 的 Get API Key 页面生成为什么需要 Anthropic 和 Google 的 Key官方文档明确说明VisionAgent 使用 Anthropic 与 Google 的模型来响应提示并生成代码。运行时应用需要使用你自己的 API Key 访问这两家模型服务这样你的项目不会受限于 LandingAI 账号自带的速率限制也避免大量用户挤占 LandingAI 的限流额度。Anthropic 与 Google 各自有独立的速率限制和付费档位具体以官方文档与定价为准。版本兼容性提示在 VisionAgent v1.0.2 及更早版本中VisionAgent 由 Anthropic Claude-3.5 和 OpenAI o1 驱动如果使用这些旧版本你需要获取 OpenAI API Key 并将其设置为环境变量。获取 Anthropic API Key 的三步若还没有账号先在 Anthropic Console 注册进入 Console 的 API Keys 页面生成一个 API Key。获取 Google API Key 的三步若还没有账号先在 Google AI Studio 注册在 Google AI Studio 的 Get API Key 页面操作生成一个 API Key。安装 VisionAgent支持两种主流的 Python 包管理方式均要求 Python 3.9 及以上版本。使用 uv 安装uv add vision-agent使用 pip 安装pip install vision-agent快速开始用一段提示词驱动 VisionAgent官方文档给出了完整的 Quickstart 流程按以下 8 步即可跑通第一个视觉代码生成任务准备好 Anthropic、Google、VisionAgent 三类 API Key将三类 Key 设置为环境变量见下文安装 vision-agent 库见上文新建一个名为quickstart的文件夹找一张你想分析的图片保存到quickstart文件夹中将下方的示例脚本保存为quickstart/source.py运行source.pyVisionAgent 会生成一个名为generated_code.py的文件将生成的代码保存其中。设置环境变量运行任何 VisionAgent 代码之前必须把三类 API Key 设置为环境变量。Linux/macOS 下使用exportexport VISION_AGENT_API_KEYyour-api-key export ANTHROPIC_API_KEYyour-api-key export GOOGLE_API_KEYyour-api-keyWindows 用户可参考官方文档使用对应的setx或系统环境变量方式原理相同。示例脚本提示 VisionAgent以下面脚本为起点向 VisionAgent 提交一个描述图片的任务# Import the classes you need from the VisionAgent package from vision_agent.agent import VisionAgentCoderV2 from vision_agent.models import AgentMessage # Enable verbose output agent VisionAgentCoderV2(verboseTrue) # Add your prompt (content) and image file (media) code_context agent.generate_code( [ AgentMessage( roleuser, contentDescribe the image, media[friends.jpg] ) ] ) # Write the output to a file with open(generated_code.py, w) as f: f.write(code_context.code \n code_context.test)几点关键说明结合源码可以帮助你更好地理解这段脚本VisionAgentCoderV2是官方文档推荐的代码生成 Agent 入口位于 vision_agent/agent/vision_agent_coder_v2.py 第 291 行。构造时它会按配置自动创建 planner、coder、tester、debugger 四个角色实例CONFIG.create_coder()等见同文件第 334-336 行因此你在示例中只需传入verboseTrue。AgentMessage是传给整个 Agentic 系统的统一消息结构定义在 vision_agent/models/agent_types.py 第 9 行。它包含role取值包括user、assistant、observation、interaction、interaction_response、planner、coder等、content文本内容和media图片/视频路径列表三个字段。agent.generate_code(...)返回CodeContext对象其code字段是最终代码、test字段是配套的测试用例、success是测试是否通过、test_result是沙箱执行结果见 agent_types.py 第 60-72 行。示例脚本将二者拼接写入generated_code.py。verboseTrue会打印规划步骤、生成的代码与测试、每次沙箱执行结果等调试信息便于观察 Agent 的内部行为。提交提示后会发生什么当你提交一个提示VisionAgent 依次执行以下任务这也是官方文档描述的默认行为生成计划为代码生成任务产出执行计划。如果开启了 verbose 输出计划中的编号步骤会直接显示在终端生成代码与测试用例基于计划写出代码和配套测试执行测试并迭代修复用测试用例验证生成的代码。如果测试失败VisionAgent 会迭代代码生成过程直到测试通过为止。代码生成流程的源码级拆解文档描述的上述流程可以在 vision_agent/agent/vision_agent_coder_v2.py 中逐段印证规划阶段generate_code首先调用self.planner.generate_plan(int_chat, ...)第 408 行产出PlanContext若规划过程需要与用户交互会返回InteractionContext提前结束若规划出错则返回ErrorContext第 412-415 行。工具推荐generate_code_from_plan中调用retrieve_tools(plan_context.instructions, self.tool_recommender)第 467 行工具推荐器Sim.top_k为计划中的每一步检索最匹配的工具文档供后续写码提示词引用。写码与写测试write_code第 64 行把工具文档、用户请求与计划拼入CODE提示模板write_test第 89 行调用TEST模板生成测试代码。执行与调试test_code第 195 行在CodeInterpreter隔离沙箱中执行默认导入 代码 测试若执行失败或 stdout 为空则进入debug_code第 116 行循环最多迭代 3 次while (not result.success or len(result.logs.stdout) 0) and count 3第 232 行每次修复后重新执行直到通过。也就是说测试失败→迭代修复→直到通过并非营销描述而是 Coder V2 中test_code/debug_code函数实实在在的 while 循环逻辑。实战示例统计图像中的罐头数量官方文档提供了一个 Jupyter Notebook 示例统计一张图片中的罐头cans数量完整可运行代码位于 examples/notebooks/counting_cans.ipynb。该 Notebook 演示了如何给 VisionAgent 一个带图片的提示让它自动选择检测/计数工具并输出代码是理解提示 → 规划 → 工具调用 → 代码产出完整链路的最佳入门素材。直接使用 VisionAgent 的特定工具VisionAgent 库内置一套工具tools它们是完成特定视觉任务的独立模型或函数全部位于 vision_agent/tools 目录对外 API 为vision_agent.tools。当你提示 VisionAgent 时它会根据任务自动选择一个或多个工具来执行提示中的目标。官方文档举例如下如果你提示统计一张图片中有多少只狗VisionAgent 可能会先用florence2_object_detection检测出所有狗再用countgd_object_detection统计检测到的狗的数量。这两个工具在 vision_agent/tools/tools.py 中均有定义分别位于第 605 行与第 966 行。安装库之后你也可以在自己的脚本中直接调用这些工具不必通过 Agent。例如写视频目标跟踪脚本时可以直接调用owlv2_sam2_video_tracking函数定义于 tools.py 第 537 行。也就是说VisionAgent 的工具可以脱离 Agent 单独复用。图像工具示例统计图中人数调用countgd_object_detection统计一张图中的人数并可视化检测框# Import the VisionAgent Tools library; import Matplotlib to visualize the results import vision_agent.tools as T import matplotlib.pyplot as plt # Load the image image T.load_image(people.png) # Call the function to count objects in an image, and specify that you want to count people dets T.countgd_object_detection(person, image) # Visualize the countgd bounding boxes on the image viz T.overlay_bounding_boxes(image, dets) # Save the visualization to a file T.save_image(viz, people_detected.png) # Display the visualization plt.imshow(viz) plt.show()从源码看countgd_object_detection(prompt, image, box_threshold0.23)接收一个文本提示要计数的目标类别、一张图像和可选的box_threshold阈值默认 0.23返回一组带score、label、bbox字段的检测结果其中边界框坐标为 0~1 之间的归一化坐标xmin, ymin, xmax, ymax见 tools.py 第 966-998 行。overlay_bounding_boxes则负责在图像上绘制带标签与置信度得分的边界框第 3206 行起。视频工具示例跟踪视频中的人调用countgd_sam2_video_tracking跟踪视频中的人并配合extract_frames_and_timestamps返回人物出现的帧与时间戳# Import the VisionAgent Tools library import vision_agent.tools as T # Call the function to get the frames and timestamps frames_and_ts T.extract_frames_and_timestamps(people.mp4) # Extract the frames from the frames_and_ts list frames [f[frame] for f in frames_and_ts] # Call the function to track objects, and specify that you want to track people tracks T.countgd_sam2_video_tracking(person, frames) # Visualize the countgd tracking results on the frames and save the video viz T.overlay_segmentation_masks(frames, tracks) T.save_video(viz, people_detected.mp4)这一组合展示了图像/视频工具链的典型用法先用extract_frames_and_timestampstools.py 第 2950 行抽取帧与时间戳再对连续帧做跨帧跟踪countgd_sam2_video_tracking位于第 1077 行最后用overlay_segmentation_masks第 3328 行叠加分割掩膜、save_video第 3143 行落盘为视频文件。使用其他 LLM 提供商VisionAgent 默认使用Anthropic Claude 3.7 Sonnet与Gemini Flash 2.0 Experimentalgemini-2.0-flash-exp来响应提示并生成代码。官方文档说明这两者在各自提供商的免费档位含速率限制上即可使用且对 VisionAgent 表现良好。默认配置集中在 vision_agent/configs/config.py其中planner、coder、tester、debugger等角色默认均为AnthropicLMM模型claude-3-7-sonnet-20250219而vqa视觉问答角色默认是GoogleLMM模型gemini-2.0-flash-exp。Config类同时暴露了create_coder()、create_tester()、create_debugger()等工厂方法供VisionAgentCoderV2在初始化时实例化对应角色。如果你只想使用其中一个模型或想换用另一组模型可以修改 vision_agent/configs/config.py 这个文件同时必须把对应提供商的 API Key 设置为环境变量。方式一直接切换配置模板。例如只想使用 Anthropic 模型可执行cp vision_agent/configs/anthropic_config.py vision_agent/configs/config.py仓库中已预置了 anthropic_config.py全角色走 Anthropic与 openai_config.py全角色走 OpenAIgpt-4o-2024-11-20视觉问答走gpt-4o-2024-11-20两套完整模板直接覆盖config.py即可一键切换。方式二手动编辑config.py中的字段。例如想把规划模型从 Anthropic 换成 OpenAI把下面这段代码planner: Type[LMM] Field(defaultAnthropicLMM) planner_kwargs: dict Field( default_factorylambda: { model_name: claude-3-7-sonnet-20250219, temperature: 0.0, image_size: 768, } )替换为planner: Type[LMM] Field(defaultOpenAILMM) planner_kwargs: dict Field( default_factorylambda: { model_name: gpt-4o-2024-11-20, temperature: 0.0, image_size: 768, image_detail: low, } )注意上例中 OpenAI 配置多出一个image_detail参数取值为low/high等控制送入模型的图像分辨率档位。LMM抽象基类及其AnthropicLMM、GoogleLMM、OpenAILMM等实现均位于 vision_agent/lmm/lmm.py例如OpenAILMM支持model_name、max_tokens默认 4096、json_mode、image_size默认 768、image_detail等构造参数并对o1/o3系列模型自动跳过max_tokens传参见该文件第 61-90 行。小结与进一步阅读至此你已掌握 VisionAgent 的完整上手路径准备三类 API Key → 安装库 → 编写 Quickstart 脚本获得自动生成的视觉代码 → 直接复用内置工具处理图像计数与视频跟踪 → 按需切换底层 LLM 提供商。官方文档还提供了本项目的完整 API 参考分布于 docs/api 目录含 agent.md、configs.md、lmm.md、models.md、sim.md、tools.md可进一步查阅各模块的详细接口说明。工具函数的权威 docstring 与示例代码可在 vision_agent/tools/tools.py 中直接阅读单元测试位于 tests/unit如 test_lmm.py、test_meta_tools.py集成测试位于 tests/integ可作为理解工具行为与调用约定的补充参考。【免费下载链接】vision-agentThis tool has been deprecated. Use Agentic Document Extraction instead.项目地址: https://gitcode.com/GitHub_Trending/vi/vision-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考