尧图网页设计 
vision-agent 数据模型层全解析Agent 消息、上下文与工具请求的 Pydantic 模型指南【免费下载链接】vision-agentThis tool has been deprecated. Use Agentic Document Extraction instead.项目地址: https://gitcode.com/GitHub_Trending/vi/vision-agentvision-agent 是一个面向视觉任务的多 Agent规划、编码、对话系统。其数据模型层 docs/api/models.md 定义的 14 个 Pydantic 模型是贯穿 Agent 通信、LMM大视觉语言模型调用与工具执行的数据结构契约。本文以该 API 文档为核心骨架结合仓库源码逐一拆解这些模型的字段定义、枚举取值与真实调用场景帮助你在二次开发、调试与扩展工具时准确构造与解析数据。说明本文所引源码均来自当前仓库 vision_agent/models 目录相关文件为 agent_types.py、lmm_types.py 与 tools_types.py。另据项目说明本仓库工具已标记为 deprecated新项目请参考其替代方案 Agentic Document Extraction本文内容以当前仓库代码为准。模型层概览三个模块、三种职责vision_agent.models包由三个模块组成并通过 vision_agent/models/init.py 统一导出全部类型模块职责域包含模型agent_types.pyAgent 系统内部通信与上下文AgentMessage、PlanContext、CodeContext、InteractionContext、ErrorContextlmm_types.pyLMM 的输入输出类型TextOrImage、Messagetools_types.py工具/API 请求与响应BboxInput、BboxInputBase64、BoundingBoxes、ODResponseData、Florence2FtRequest、PromptTask、JobStatus所有结构体均继承自pydantic.BaseModel因此天然具备字段类型校验、序列化model_dump()/model_dump_json()与别名alias支持等能力可以直接用于类型注解与数据交换。Agent 通信与上下文模型多 Agent 协作的数据骨架AgentMessage统一消息载体AgentMessage是整个 Agentic 系统包括 LMM 与各子 Agent之间传递消息的统一载体定义于 agent_types.py。其字段为role消息角色取值是 11 种字面量类型的联合user用户消息assistant助手消息planner、coder、conversation 均属此类observation执行某个动作后的观察结果可由用户或助手产生final_observation最终代码输出产生的观察error_observation错误消息产生的观察interaction用户与助手之间的交互例如助手请求用户帮助interaction_response用户对交互消息的回应conversation来自对话 Agent 的消息一种助手消息planner来自规划 Agent 的消息一种助手消息planner_update规划器输出的中间进度更新coder来自编码 Agent 的消息一种助手消息。content字符串类型的消息正文media可选的多媒体资源列表元素类型为str或Path默认None。源码中大量使用该模型组织多轮对话例如 vision_agent_planner_v2.py 中规划器在执行代码后向会话追加planner与observation消息vision_agent_v2.py 则按coder、final_observation、error_observation等角色拼接上下文。角色字段的意义在于不同子 Agent 产出的消息被打上独立标签便于在汇总对话时按角色过滤见extract_conversation对coder、conversation等角色的筛选逻辑。PlanContext规划结果PlanContextagent_types.py承载一次规划任务的产物plan整体计划的文字描述instructions逐步执行指令列表List[str]code规划阶段使用的代码片段。它是create_finalize_planvision_agent_planner_v2.py的正常返回类型规划器将模型的 JSON 输出解析为{plan: ..., instructions: [...], code: ...}结构后构造PlanContext交付给上层 Agent 继续执行。CodeContext最终代码与测试结果CodeContextagent_types.py表示编码 Agent 产出的最终代码及测试情况code最终写出的代码test编写的测试用例success布尔值表示代码是否通过测试test_result运行测试的结果类型为vision_agent.utils.execute.Execution。在 vision_agent_coder_v2.py 中编码器完成代码生成与测试执行后即构造并返回CodeContext上层 vision_agent_v2.py 再将其格式化后以AgentMessage的形式送入对话。InteractionContext人机交互会话InteractionContextagent_types.py仅含一个字段chat用户与助手之间交换的AgentMessage列表。它用于封装人类介入场景例如 vision_agent_planner_v2.py 中当 Agent 需要向用户确认工具选择时将交互过程以InteractionContext(chatint_chat)形式返回。ErrorContext错误上下文ErrorContextagent_types.py表示一条错误消息字段仅error字符串。其典型触发场景是规划阶段模型未输出正确格式的响应例如模型因安全顾虑拒绝回答导致无法解析出计划 JSON。对应逻辑见 vision_agent_planner_v2.py当json.JSONDecodeError抛出时返回ErrorContext(errorplan_str)交由上层处理。LMM 输入输出类型与模型交互的数据契约TextOrImage 与 Messagevision_agent/models/lmm_types.py 定义了两个高度抽象的类型别名TextOrImage Union[str, Sequence[Union[str, Path, ImageType, np.ndarray]]] Message Dict[str, Union[TextOrImage, Execution]]TextOrImage既可以是一个纯文本字符串也可以是一系列媒体元素本地路径str/Path、PIL 图像ImageType、numpy 数组np.ndarrayMessage一条对话消息本质是键为字符串、值为TextOrImage或Execution的字典。实际使用中消息通常包含role、content、media三个键。Message被 vision_agent/lmm/lmm.py 中的LMM抽象基类广泛使用chat(chat: Sequence[Message], **kwargs)接口即接收消息序列。各厂商实现OpenAILMM、AnthropicLMM、GoogleLMM、OllamaLMM会统一把content与media转换为对应厂商 API 的格式。以OpenAILMM.chatlmm.py为例一条带图片的消息可表示为[ { role: user, content: 这张图里有什么, media: [image1.jpg, ...], }, ... ]发送前实现会把media中的每张图片经encode_media编码后附加为image_url类型的内容块。测试方面tests/unit/fixtures.py 提供了openai_lmm_mock、anthropic_lmm_mock、google_lmm_mock、chat_ollama_lmm_mock等夹具mock 了不同厂商的流式与非流式响应可用于验证消息格式的构造是否符合预期。工具与 API 数据模型目标检测、微调请求与任务状态BboxInput / BboxInputBase64检测标注输入两个模型用于向工具提交带标注的检测样本tools_types.pyBboxInputimage_path图片路径字符串labels标签列表bboxes边界框列表每个框是(x1, y1, x2, y2)形式的(int, int, int, int)四元组。BboxInputBase64与前者字段几乎一致但以imagebase64 编码字符串filename文件名代替本地路径适用于通过 HTTP/API 上传图片的场景。BoundingBoxes 与 ODResponseData检测响应结构class ODResponseData(BaseModel): label: str score: float bbox: Union[list[int], list[float]] Field(aliasbounding_box) model_config ConfigDict(populate_by_nameTrue) BoundingBoxes list[ODResponseData]ODResponseDatatools_types.py表示单条目标检测结果label类别标签、score置信度分数、bbox边界框坐标。注意bbox字段对外序列化名称为bounding_box别名alias同时通过populate_by_nameTrue允许调用方用字段名或别名任意一种传入BoundingBoxes是ODResponseData的列表类型别名代表一整张图的检测结果集合。该结构在示例前端中被直接消费如 examples/chat/chat-app/src/components/ResultImageWithBoundingBoxes.tsx 与 PreviewSection.tsx 会按label、score、bounding_box渲染检测框与置信度。PromptTaskFlorence2 任务提示词枚举class PromptTask(str, Enum): Valid task prompts options for the Florence2 model. PHRASE_GROUNDING CAPTION_TO_PHRASE_GROUNDINGPromptTasktools_types.py是字符串枚举目前定义了一项任务PHRASE_GROUNDING其值为 Florence2 模型的短语定位任务标记CAPTION_TO_PHRASE_GROUNDING。从源码结构看该枚举为后续扩展其他 Florence2 任务如检测、分割预留了接口。Florence2FtRequest微调请求体Florence2FtRequesttools_types.py封装向服务端提交 Florence2 微调任务的请求image可选图片字符串video可选视频bytestask必填PromptTask枚举指定任务类型prompt可选提示词默认空字符串chunk_length_frames可选视频按帧切块的帧数postprocessing可选后处理方式job_id可选任务 UUID别名alias为jobId对齐 JSON/HTTP 命名习惯。该模型配置了populate_by_nameTrue因此构造请求时jobId与job_id均可使用同时通过field_serializer(job_id)tools_types.py将 UUID 在序列化输出时统一转为字符串保证 JSON 可传输。JobStatus微调任务状态机JobStatustools_types.py是字符串枚举描述一个微调任务从创建到结束的完整生命周期取值含义CREATED任务已创建等待被调度执行STARTING任务开始运行但尚未进入训练阶段TRAINING任务正在训练模型EVALUATING任务正在评估模型并计算指标PUBLISHING任务正在将产物导出到外部目录s3 或本地SUCCEEDED任务已完成训练、评估、产物发布全部结束FAILED任务因内部原因失败资源问题或代码本身STOPPED任务被用户本地或云端停止该枚举覆盖了创建 → 启动 → 训练 → 评估 → 发布 → 成功/失败/停止的完整流水线可作为微调任务编排与前端状态展示的统一状态码。实战要点如何正确使用这些模型构造带图片的对话用Message字典rolecontentmedia组织输入交给任意LMM实现见 vision_agent/lmm/lmm.py实现层会完成图片编码与厂商格式转换解析规划器返回create_finalize_plan的返回值是(List[AgentMessage], Union[PlanContext, ErrorContext])元组先用isinstance判断是正常计划还是错误上下文再取用plan/instructions/code字段序列化检测结果BoundingBoxes即ODResponseData列表对外输出字段名为bounding_box前端解析时需使用别名而非 Python 字段名bbox提交微调请求Florence2FtRequest的task必填其余字段按需设置jobId/job_id均可写入序列化后统一为字符串jobId校验与调试由于所有模型都是 PydanticBaseModel可以在单元测试中直接实例化并借助校验报错快速定位字段类型或必填项问题。小结从 docs/api/models.md 列出的 14 个模型可以看出vision-agent 的数据模型层被刻意划分为三层契约面向多 Agent 协作的消息与上下文AgentMessage、PlanContext、CodeContext、InteractionContext、ErrorContext、面向 LMM 厂商差异的输入输出类型TextOrImage、Message、以及面向工具与 API 的业务数据结构BboxInput、BoundingBoxes、Florence2FtRequest、JobStatus等。理解这三层契约是阅读 vision_agent/agent 下各 Agent 实现、扩展自定义工具、以及接入检测/微调服务的前提。若需在测试中模拟 LMM 响应可参考 tests/unit/fixtures.py 中针对不同厂商实现的 mock 夹具。【免费下载链接】vision-agentThis tool has been deprecated. Use Agentic Document Extraction instead.项目地址: https://gitcode.com/GitHub_Trending/vi/vision-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 vision-agent 数据模型层全解析：Agent 消息、上下文与工具请求的 Pydantic 模型指南
vision-agent 数据模型层全解析Agent 消息、上下文与工具请求的 Pydantic 模型指南【免费下载链接】vision-agentThis tool has been deprecated. Use Agentic Document Extraction instead.项目地址: https://gitcode.com/GitHub_Trending/vi/vision-agentvision-agent 是一个面向视觉任务的多 Agent规划、编码、对话系统。其数据模型层 docs/api/models.md 定义的 14 个 Pydantic 模型是贯穿 Agent 通信、LMM大视觉语言模型调用与工具执行的数据结构契约。本文以该 API 文档为核心骨架结合仓库源码逐一拆解这些模型的字段定义、枚举取值与真实调用场景帮助你在二次开发、调试与扩展工具时准确构造与解析数据。说明本文所引源码均来自当前仓库 vision_agent/models 目录相关文件为 agent_types.py、lmm_types.py 与 tools_types.py。另据项目说明本仓库工具已标记为 deprecated新项目请参考其替代方案 Agentic Document Extraction本文内容以当前仓库代码为准。模型层概览三个模块、三种职责vision_agent.models包由三个模块组成并通过 vision_agent/models/init.py 统一导出全部类型模块职责域包含模型agent_types.pyAgent 系统内部通信与上下文AgentMessage、PlanContext、CodeContext、InteractionContext、ErrorContextlmm_types.pyLMM 的输入输出类型TextOrImage、Messagetools_types.py工具/API 请求与响应BboxInput、BboxInputBase64、BoundingBoxes、ODResponseData、Florence2FtRequest、PromptTask、JobStatus所有结构体均继承自pydantic.BaseModel因此天然具备字段类型校验、序列化model_dump()/model_dump_json()与别名alias支持等能力可以直接用于类型注解与数据交换。Agent 通信与上下文模型多 Agent 协作的数据骨架AgentMessage统一消息载体AgentMessage是整个 Agentic 系统包括 LMM 与各子 Agent之间传递消息的统一载体定义于 agent_types.py。其字段为role消息角色取值是 11 种字面量类型的联合user用户消息assistant助手消息planner、coder、conversation 均属此类observation执行某个动作后的观察结果可由用户或助手产生final_observation最终代码输出产生的观察error_observation错误消息产生的观察interaction用户与助手之间的交互例如助手请求用户帮助interaction_response用户对交互消息的回应conversation来自对话 Agent 的消息一种助手消息planner来自规划 Agent 的消息一种助手消息planner_update规划器输出的中间进度更新coder来自编码 Agent 的消息一种助手消息。content字符串类型的消息正文media可选的多媒体资源列表元素类型为str或Path默认None。源码中大量使用该模型组织多轮对话例如 vision_agent_planner_v2.py 中规划器在执行代码后向会话追加planner与observation消息vision_agent_v2.py 则按coder、final_observation、error_observation等角色拼接上下文。角色字段的意义在于不同子 Agent 产出的消息被打上独立标签便于在汇总对话时按角色过滤见extract_conversation对coder、conversation等角色的筛选逻辑。PlanContext规划结果PlanContextagent_types.py承载一次规划任务的产物plan整体计划的文字描述instructions逐步执行指令列表List[str]code规划阶段使用的代码片段。它是create_finalize_planvision_agent_planner_v2.py的正常返回类型规划器将模型的 JSON 输出解析为{plan: ..., instructions: [...], code: ...}结构后构造PlanContext交付给上层 Agent 继续执行。CodeContext最终代码与测试结果CodeContextagent_types.py表示编码 Agent 产出的最终代码及测试情况code最终写出的代码test编写的测试用例success布尔值表示代码是否通过测试test_result运行测试的结果类型为vision_agent.utils.execute.Execution。在 vision_agent_coder_v2.py 中编码器完成代码生成与测试执行后即构造并返回CodeContext上层 vision_agent_v2.py 再将其格式化后以AgentMessage的形式送入对话。InteractionContext人机交互会话InteractionContextagent_types.py仅含一个字段chat用户与助手之间交换的AgentMessage列表。它用于封装人类介入场景例如 vision_agent_planner_v2.py 中当 Agent 需要向用户确认工具选择时将交互过程以InteractionContext(chatint_chat)形式返回。ErrorContext错误上下文ErrorContextagent_types.py表示一条错误消息字段仅error字符串。其典型触发场景是规划阶段模型未输出正确格式的响应例如模型因安全顾虑拒绝回答导致无法解析出计划 JSON。对应逻辑见 vision_agent_planner_v2.py当json.JSONDecodeError抛出时返回ErrorContext(errorplan_str)交由上层处理。LMM 输入输出类型与模型交互的数据契约TextOrImage 与 Messagevision_agent/models/lmm_types.py 定义了两个高度抽象的类型别名TextOrImage Union[str, Sequence[Union[str, Path, ImageType, np.ndarray]]] Message Dict[str, Union[TextOrImage, Execution]]TextOrImage既可以是一个纯文本字符串也可以是一系列媒体元素本地路径str/Path、PIL 图像ImageType、numpy 数组np.ndarrayMessage一条对话消息本质是键为字符串、值为TextOrImage或Execution的字典。实际使用中消息通常包含role、content、media三个键。Message被 vision_agent/lmm/lmm.py 中的LMM抽象基类广泛使用chat(chat: Sequence[Message], **kwargs)接口即接收消息序列。各厂商实现OpenAILMM、AnthropicLMM、GoogleLMM、OllamaLMM会统一把content与media转换为对应厂商 API 的格式。以OpenAILMM.chatlmm.py为例一条带图片的消息可表示为[ { role: user, content: 这张图里有什么, media: [image1.jpg, ...], }, ... ]发送前实现会把media中的每张图片经encode_media编码后附加为image_url类型的内容块。测试方面tests/unit/fixtures.py 提供了openai_lmm_mock、anthropic_lmm_mock、google_lmm_mock、chat_ollama_lmm_mock等夹具mock 了不同厂商的流式与非流式响应可用于验证消息格式的构造是否符合预期。工具与 API 数据模型目标检测、微调请求与任务状态BboxInput / BboxInputBase64检测标注输入两个模型用于向工具提交带标注的检测样本tools_types.pyBboxInputimage_path图片路径字符串labels标签列表bboxes边界框列表每个框是(x1, y1, x2, y2)形式的(int, int, int, int)四元组。BboxInputBase64与前者字段几乎一致但以imagebase64 编码字符串filename文件名代替本地路径适用于通过 HTTP/API 上传图片的场景。BoundingBoxes 与 ODResponseData检测响应结构class ODResponseData(BaseModel): label: str score: float bbox: Union[list[int], list[float]] Field(aliasbounding_box) model_config ConfigDict(populate_by_nameTrue) BoundingBoxes list[ODResponseData]ODResponseDatatools_types.py表示单条目标检测结果label类别标签、score置信度分数、bbox边界框坐标。注意bbox字段对外序列化名称为bounding_box别名alias同时通过populate_by_nameTrue允许调用方用字段名或别名任意一种传入BoundingBoxes是ODResponseData的列表类型别名代表一整张图的检测结果集合。该结构在示例前端中被直接消费如 examples/chat/chat-app/src/components/ResultImageWithBoundingBoxes.tsx 与 PreviewSection.tsx 会按label、score、bounding_box渲染检测框与置信度。PromptTaskFlorence2 任务提示词枚举class PromptTask(str, Enum): Valid task prompts options for the Florence2 model. PHRASE_GROUNDING CAPTION_TO_PHRASE_GROUNDINGPromptTasktools_types.py是字符串枚举目前定义了一项任务PHRASE_GROUNDING其值为 Florence2 模型的短语定位任务标记CAPTION_TO_PHRASE_GROUNDING。从源码结构看该枚举为后续扩展其他 Florence2 任务如检测、分割预留了接口。Florence2FtRequest微调请求体Florence2FtRequesttools_types.py封装向服务端提交 Florence2 微调任务的请求image可选图片字符串video可选视频bytestask必填PromptTask枚举指定任务类型prompt可选提示词默认空字符串chunk_length_frames可选视频按帧切块的帧数postprocessing可选后处理方式job_id可选任务 UUID别名alias为jobId对齐 JSON/HTTP 命名习惯。该模型配置了populate_by_nameTrue因此构造请求时jobId与job_id均可使用同时通过field_serializer(job_id)tools_types.py将 UUID 在序列化输出时统一转为字符串保证 JSON 可传输。JobStatus微调任务状态机JobStatustools_types.py是字符串枚举描述一个微调任务从创建到结束的完整生命周期取值含义CREATED任务已创建等待被调度执行STARTING任务开始运行但尚未进入训练阶段TRAINING任务正在训练模型EVALUATING任务正在评估模型并计算指标PUBLISHING任务正在将产物导出到外部目录s3 或本地SUCCEEDED任务已完成训练、评估、产物发布全部结束FAILED任务因内部原因失败资源问题或代码本身STOPPED任务被用户本地或云端停止该枚举覆盖了创建 → 启动 → 训练 → 评估 → 发布 → 成功/失败/停止的完整流水线可作为微调任务编排与前端状态展示的统一状态码。实战要点如何正确使用这些模型构造带图片的对话用Message字典rolecontentmedia组织输入交给任意LMM实现见 vision_agent/lmm/lmm.py实现层会完成图片编码与厂商格式转换解析规划器返回create_finalize_plan的返回值是(List[AgentMessage], Union[PlanContext, ErrorContext])元组先用isinstance判断是正常计划还是错误上下文再取用plan/instructions/code字段序列化检测结果BoundingBoxes即ODResponseData列表对外输出字段名为bounding_box前端解析时需使用别名而非 Python 字段名bbox提交微调请求Florence2FtRequest的task必填其余字段按需设置jobId/job_id均可写入序列化后统一为字符串jobId校验与调试由于所有模型都是 PydanticBaseModel可以在单元测试中直接实例化并借助校验报错快速定位字段类型或必填项问题。小结从 docs/api/models.md 列出的 14 个模型可以看出vision-agent 的数据模型层被刻意划分为三层契约面向多 Agent 协作的消息与上下文AgentMessage、PlanContext、CodeContext、InteractionContext、ErrorContext、面向 LMM 厂商差异的输入输出类型TextOrImage、Message、以及面向工具与 API 的业务数据结构BboxInput、BoundingBoxes、Florence2FtRequest、JobStatus等。理解这三层契约是阅读 vision_agent/agent 下各 Agent 实现、扩展自定义工具、以及接入检测/微调服务的前提。若需在测试中模拟 LMM 响应可参考 tests/unit/fixtures.py 中针对不同厂商实现的 mock 夹具。【免费下载链接】vision-agentThis tool has been deprecated. Use Agentic Document Extraction instead.项目地址: https://gitcode.com/GitHub_Trending/vi/vision-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考