VisionAgent 实战指南：用自然语言提示词自动生成可运行的视觉 AI 代码

VisionAgent 实战指南：用自然语言提示词自动生成可运行的视觉 AI 代码

【免费下载链接】vision-agentThis tool has been deprecated. Use Agentic Document Extraction instead.项目地址: https://gitcode.com/GitHub_Trending/vi/vision-agent

VisionAgent 是 LandingAI 出品的"视觉 AI 驾驶员"（Visual AI pilot）类 Agent 工具：给它一段自然语言提示词和一张图片，它会自动挑选合适的视觉模型并输出可直接运行的代码，让开发者几分钟内就能构建出具备视觉能力的应用。本文以仓库根目录 README.md 为骨架，结合 vision_agent 包内源码，完整讲解 API Key 准备、安装、快速上手、Agent 生成代码的底层流程、视觉工具的独立调用，以及如何切换 Anthropic / Google / OpenAI 等不同 LLM 提供方。

注意：根据当前仓库的元数据信息，该工具已被标记为弃用（deprecated），官方建议改用 Agentic Document Extraction 方案。不过其"提示词 → 规划 → 生成代码 → 自动测试"的 Agent 架构、视觉工具的组织方式与多 LLM 切换机制仍然具备很高的参考与学习价值，本文内容均以当前仓库实际代码与文档为准。

VisionAgent 是什么：一次提示词换取一段可运行代码

VisionAgent 的核心工作流可以概括为：Prompt with an image/video → Get runnable vision code → Build Visual AI App in minutes。用户不再需要手动挑选检测、分割、跟踪模型，也不需要手工拼装推理管线，只需把任务（例如"统计图中人数""描述这张图片"）连同图片一起交给 Agent，VisionAgent 就会：

1. 生成一份针对代码生成任务的计划（开启 verbose 输出时，计划的编号步骤会显示在终端）；
2. 基于计划生成代码和对应的测试用例；
3. 用测试用例实际运行生成的代码，如果测试失败，Agent 会反复迭代，直到测试通过为止。

这一流程并非黑盒，在 vision_agent/agent/vision_agent_coder_v2.py 中有完整实现：VisionAgentCoderV2内部依次串联了planner（规划器）、coder（代码生成器）、tester（测试生成器）和debugger（调试器）四个角色，下文"源码视角"一节会详细展开。

前置准备：三类 API Key 缺一不可

获取 VisionAgent API Key

最重要的一步是在 LandingAI 的 VisionAgent 平台创建账号并获取 API Key，它是访问 VisionAgent 服务（模型托管、工具调用等）的身份凭证。

为什么还需要 Anthropic 与 Google 的 API Key

VisionAgent 使用 Anthropic 和 Google 的模型来响应提示词并生成代码。当你运行 VisionAgent 时，应用需要调用你的 API Key 来访问这些模型，这样做的目的在于：

• 你的项目不会受到 LandingAI 账号自带限流（rate limits）的约束；
• 避免大量用户同时挤占 LandingAI 的公共限流额度。

Anthropic 与 Google 各自有独立的限流策略和付费层级，具体可参考其官方文档与定价。

版本说明：在 VisionAgent v1.0.2 及更早版本中，VisionAgent 由 Anthropic Claude-3.5 和 OpenAI o1 驱动。如果你使用的是这些早期版本，则需要获取 OpenAI API Key 并设置为环境变量。

获取 Anthropic API Key 的步骤

1. 在 Anthropic Console 注册账号；
2. 进入 Console 的 API Keys 页面；
3. 生成一个 API Key。

获取 Google API Key 的步骤

1. 在 Google AI Studio 注册账号；
2. 进入 AI Studio 的 Get API Key 页面；
3. 生成一个 API Key。

在 vision_agent/lmm/lmm.py 中可以印证：AnthropicLMM通过anthropic.Anthropic客户端调用 Claude 系列模型，GoogleLMM通过 Google GenAI 客户端调用 Gemini 系列模型（默认从环境变量GOOGLE_API_KEY读取 Key），OpenAILMM则通过OpenAI客户端调用 GPT 系列模型。这三类 LMM 均实现了统一的抽象基类LMM（generate/chat/__call__三个抽象方法），这也是后文"切换 LLM 提供方"能够一键生效的根本原因。

安装 VisionAgent

推荐使用 uv（一种高速 Python 包管理器）：

uv add vision-agent

也可以使用 pip：

pip install vision-agent

仓库根目录同时提供了 pyproject.toml、poetry.lock 与 uv.lock，说明该项目同时支持 poetry 与 uv 两种依赖管理方式。

快速上手：让 VisionAgent 替你写视觉代码

完整操作步骤

1. 获取 Anthropic、Google 和 VisionAgent 三个 API Key；
2. 将三个 API Key 设置为环境变量；
3. 安装 VisionAgent；
4. 新建一个名为quickstart的文件夹；
5. 找一张想要分析的图片，保存到quickstart文件夹；
6. 把下面的示例脚本复制为source.py并保存到quickstart文件夹；
7. 运行source.py；
8. VisionAgent 会生成一个名为generated_code.py的文件，把生成好的代码保存在其中。

设置环境变量

不同操作系统设置环境变量的方式不同，Linux/macOS 下的 bash 写法如下：

export VISION_AGENT_API_KEY="your-api-key" export ANTHROPIC_API_KEY="your-api-key" export GOOGLE_API_KEY="your-api-key"

示例脚本：提示 VisionAgent

# 从 VisionAgent 包导入所需类 from vision_agent.agent import VisionAgentCoderV2 from vision_agent.models import AgentMessage # 开启 verbose 输出，便于观察 Agent 的规划与迭代过程 agent = VisionAgentCoderV2(verbose=True) # 传入你的提示词（content）与图片文件（media） code_context = agent.generate_code( [ AgentMessage( role="user", content="Describe the image", media=["friends.jpg"] ) ] ) # 将输出写入文件 with open("generated_code.py", "w") as f: f.write(code_context.code + "\n" + code_context.test)

这段脚本用到了两个关键对象，它们在 vision_agent/models/agent_types.py 中有明确定义：

• AgentMessage：Agentic 系统中流转的消息载体，role可以是user、assistant、observation、interaction、planner、coder等类型，content是文本内容，media是可选的图片/视频路径列表；
• CodeContext：generate_code的返回值，包含四个字段——code（最终生成的代码）、test（生成的测试用例）、success（代码是否通过测试）、test_result（测试运行的执行结果）。

此外generate_code还可能在交互式（Human-in-the-loop）场景下返回InteractionContext，或在规划阶段出错时返回ErrorContext（例如模型输出了不合规格式的消息）。从 vision_agent_coder_v2.py 的实现看，VisionAgentCoderV2.__call__会对这三种返回类型分别处理，最终统一输出可用的代码字符串。

源码视角：一次代码生成任务在内部发生了什么

如果你好奇"提示词到代码"的完整旅程，可以从VisionAgentCoderV2.generate_code（见 vision_agent/agent/vision_agent_coder_v2.py）追到以下调用链：

1. 规划（Planning）：self.planner.generate_plan(...)调用VisionAgentPlannerV2生成PlanContext（包含整体计划plan、分步指令instructions和规划期间的代码片段code）；
2. 工具检索（Tool Retrieval）：retrieve_tools使用工具推荐器（Sim，语义检索模型）对计划中的每一条指令做top_k检索，取出最相关的工具文档拼接到提示词中；
3. 写代码（Write Code）：write_code将工具文档、用户请求和格式化后的计划填入CODE提示词模板，交给coder模型，再从响应中解析出<code>标签内的 Python 代码；
4. 写测试（Write Test）：write_test基于工具工具类文档、用户请求和已生成的代码，让tester模型生成测试用例；
5. 执行与调试（Test & Debug）：test_code通过CodeInterpreter在隔离沙箱中运行"默认导入 + 代码 + 测试"，若执行失败或没有日志输出，则进入最多3 次的调试循环：debug_code把执行结果（取最近 50 行）与调试历史打包给debugger模型，让其返回"思路（thoughts）+ 修复后的代码 + 修复后的测试"，然后重新执行，直到通过或达到迭代上限。

这个"生成 → 测试 → 失败 → 修复"的闭环正是 README 中"如果测试失败，VisionAgent 会迭代代码生成过程直到测试通过"这句话的源码级落地，也解释了为什么verbose=True时终端会依次打印计划、代码、测试和执行结果。

实战示例：统计图片中的易拉罐

README 提供了一个完整可运行的 Jupyter Notebook——examples/notebooks/counting_cans.ipynb，演示如何使用 VisionAgent 统计一张图片中易拉罐的数量。它是理解"提示词驱动视觉任务"的最佳入门材料：核心思路是让 Agent 自动选择合适的检测/计数工具组合来完成"数数"这一需要细粒度识别的任务。

此外，README 还提到仓库自带一个本地 Web 应用，位于 examples/chat，其运行方式（Python 后端 + React 前端的启动、端口修改、Human-in-the-loop 模式等）记录在 examples/chat/README.md 中，适合在图形界面里体验完整的 Agent 对话与结果可视化。

直接调用 VisionAgent 的视觉工具

除了通过提示词驱动 Agent，VisionAgent 库还内置了一批独立工具（tools）——它们是完成特定任务的独立模型或函数，位于 vision_agent/tools 目录（统一通过vision_agent.toolsAPI 暴露）。当你提示 VisionAgent 时，它会从这批工具中挑选一个或多个来完成任务。

例如，提示"数一数图片里有几只狗"，VisionAgent 可能先用florence2_object_detection检测出所有狗，再用countgd_object_detection统计检测到的狗的数量。安装库之后，你完全可以在自己的脚本里直接调用这些工具，例如写视频目标跟踪脚本时直接调用owlv2_sam2_video_tracking，也就是说，视觉工具可以脱离 Agent 独立使用。

图片工具示例：统计图片中的人数

# 导入 VisionAgent Tools 库；导入 Matplotlib 用于可视化结果 import vision_agent.tools as T import matplotlib.pyplot as plt # 加载图片 image = T.load_image("people.png") # 调用计数函数，指定要统计的对象是 person（人） dets = T.countgd_object_detection("person", image) # 在图片上叠加 countgd 检测出的边界框 viz = T.overlay_bounding_boxes(image, dets) # 把可视化结果保存到文件 T.save_image(viz, "people_detected.png") # 显示可视化结果 plt.imshow(viz) plt.show()

从 vision_agent/tools/tools.py 的源码（countgd_object_detection，第 966 行起）可以看到更多实现细节：

• 该函数签名是countgd_object_detection(prompt: str, image: np.ndarray, box_threshold: float = 0.23)，返回一组包含score、label、bbox的字典列表，其中bbox是归一化坐标(xmin, ymin, xmax, ymax)；
• 支持用逗号分隔多个物体类别名，例如"flower, car"；
• box_threshold是检测置信度阈值，默认 0.23；内部还会对候选框做 IoU 阈值为 0.80 的 NMS 去重；
• 配套的可视化与文件函数包括load_image（读图）、overlay_bounding_boxes（叠加边界框）、save_image（存图）等。

视频工具示例：在视频中跟踪并统计人数

# 导入 VisionAgent Tools 库 import vision_agent.tools as T # 抽取视频帧及其时间戳 frames_and_ts = T.extract_frames_and_timestamps("people.mp4") # 从 frames_and_ts 列表中取出帧 frames = [f["frame"] for f in frames_and_ts] # 调用目标跟踪函数，指定要跟踪 person（人） tracks = T.countgd_sam2_video_tracking("person", frames) # 在帧上叠加分割掩码，并保存为视频 viz = T.overlay_segmentation_masks(frames, tracks) T.save_video(viz, "people_detected.mp4")

对应的源码要点如下：

• countgd_sam2_video_tracking（tools.py 第 1077 行起）的签名为(prompt, frames, box_threshold=0.23, chunk_length=25)，返回"每个帧对应一个实体列表"的嵌套结构，每个实体包含label、bbox和mask（二值分割掩码），label会以"0: person"这样的 ID 前缀标识每个独立目标，从而避免重复计数；
• 同类的还有owlv2_sam2_video_tracking（第 537 行起），区别在于使用 OWLv2 作为检测器，其默认box_threshold为 0.10；chunk_length表示每隔多少帧重新运行一次检测器以发现新目标（默认 25）；
• extract_frames_and_timestamps（第 2950 行起）默认按fps=5抽帧，返回[{"frame": np.ndarray, "timestamp": 秒}, ...]列表，并且支持三种输入：本地视频文件路径、普通 HTTP(S) 视频 URL、以及 YouTube 链接（后者通过 yt-dlp 自动下载）。

切换 LLM 提供方：从 Claude 换到 GPT-4o 等模型

VisionAgent 默认使用Anthropic Claude 3.7 Sonnet（模型名claude-3-7-sonnet-20250219）和Gemini Flash 2.0 Experimental（gemini-2.0-flash-exp）来响应提示词并生成代码。README 说明这两个模型在当时提供方的免费层级（有限流）内可用，且表现最佳。

如果你只想使用其中某一个模型，或希望换用其他模型组合，可以修改 vision_agent/configs/config.py 中的配置，同时必须把对应提供方的 API Key 设置为环境变量。

方式一：直接覆盖配置文件

如果想只使用 Anthropic 模型，可以直接用仓库预置的完整 Anthropic 配置替换默认配置：

cp vision_agent/configs/anthropic_config.py vision_agent/configs/config.py

仓库的 vision_agent/configs 目录下预置了三份配置：

• config.py：默认配置，全部角色使用AnthropicLMM+claude-3-7-sonnet-20250219，仅vqa（视觉问答）角色默认使用GoogleLMM+gemini-2.0-flash-exp；
• anthropic_config.py：纯 Anthropic 配置，注意其中suggester角色仍使用OpenAILMM+o1模型；
• openai_config.py：全 OpenAI 配置，主力模型为gpt-4o-2024-11-20，并附带image_detail: "low"参数。

Config是一个 PydanticBaseModel（见 config.py），为每个 Agent 角色都定义了一个 LMM 类型字段和一份 kwargs 字典，并通过create_agent()、create_planner()、create_coder()、create_tester()、create_debugger()等一系列工厂方法实例化对应模型。这些角色包括：agent（对话 Agent）、planner（规划器）、summarizer（总结器）、critic（评审器）、coder（代码生成器）、tester（测试生成器）、debugger（调试器）、tool_tester/tool_chooser（工具测试与选择）、od_judge（检测结果裁判）、suggester（建议模块）和vqa（视觉问答）。不同角色的temperature也有差异：大部分角色为 0.0（追求确定性输出），而summarizer、tool_chooser、suggester为 1.0（追求多样性与创造性）。

方式二：手动修改某个角色的模型

也可以直接在config.py中手动填写模型细节。例如，想把规划器（planner）从 Anthropic 换成 OpenAI，将下面这段代码：

planner: Type[LMM] = Field(default=AnthropicLMM) planner_kwargs: dict = Field( default_factory=lambda: { "model_name": "claude-3-7-sonnet-20250219", "temperature": 0.0, "image_size": 768, } )

替换为：

planner: Type[LMM] = Field(default=OpenAILMM) planner_kwargs: dict = Field( default_factory=lambda: { "model_name": "gpt-4o-2024-11-20", "temperature": 0.0, "image_size": 768, "image_detail": "low", } )

注意 OpenAI 配置中多出的image_detail参数：它控制送入模型的图片分辨率档位，可取值通常为low/high等，low能降低 token 消耗与延迟。这一参数在 vision_agent/lmm/lmm.py 的OpenAILMM中被读取并透传给图片消息。

深入阅读指引

• 官方文档（仓库自带）：docs/index.md 及其 docs/api 下的 Agent、配置、LMM、模型、模拟器与工具等 API 说明；
• Agent 层实现：vision_agent/agent（含 v2/v3 两代 Planner 与 Coder 实现、提示词模板）；
• 工具层实现与可视化函数：vision_agent/tools/tools.py；
• 数据模型（消息、计划、代码上下文等）：vision_agent/models/agent_types.py；
• LMM 抽象与各提供方实现：vision_agent/lmm/lmm.py；
• 单元与集成测试（可参考其了解工具与 Agent 的预期行为）：tests/unit 与 tests/integ。

综上，VisionAgent 把"选模型、写代码、跑测试、修 bug"这条原本高度依赖人工经验的链路自动化，同时通过统一的Config与LMM抽象保持了对多家 LLM 提供方的可插拔性；其"规划 → 工具检索 → 编码 → 测试 → 调试"的 Agent 流水线设计，对任何想要构建视觉代码生成系统的开发者都有直接的借鉴意义。

【免费下载链接】vision-agentThis tool has been deprecated. Use Agentic Document Extraction instead.项目地址: https://gitcode.com/GitHub_Trending/vi/vision-agent