UFO Dataflow 任务实例化Instantiation全解析模板选择、Prefill 与 Filter 三阶段数据生成流水线【免费下载链接】UFOUFO³: Weaving the Digital Agent Galaxy项目地址: https://gitcode.com/GitHub_Trending/uf/UFO本文基于 UFO 仓库中的 dataflow 模块 与 任务实例化官方文档系统讲解 Instantiation实例化如何将一条抽象的初始任务Task-Plan 数据逐步转写为可执行的任务-动作数据Task-Action Data先根据指令挑选最合适的文档模板再结合真实 Word 环境截图预填充Prefill出具体任务与逐步动作计划最后由过滤FilterAgent 校验任务的可执行性与质量。读完本文你将掌握 Instantiation 三阶段的工作机制、底层源码调用链、模型与模板配置方法以及如何用命令行独立运行或批量执行实例化任务。上图展示了从初始任务Task-Plan 数据出发锚定到 Word 真实环境Grounding最终产出包含具体函数调用如select_text、click_input的 Task-Action 数据Phase 2的完整过程。该图同时存在于 assets/dataflow/instantiation.png。1. Instantiation 在 Dataflow 流水线中的定位UFO 的 dataflow 模块整体支持三种任务类型见 dataflow.py 与 dataflow/README.mdInstantiation实例化将抽象任务落地为可执行数据包含**选模板Choose Template→ 预填充Prefill→ 过滤Filter**三个关键步骤Execution执行把实例化产出的动作计划在真实应用环境中逐步执行并由评估 Agent 评估执行质量Dataflow把 Instantiation 与 Execution 串成端到端流水线一键完成从初始化到执行的全过程。实例化阶段是整条数据链路的源头它负责把任务 参考步骤Task-Plan 数据实例化为具体任务请求 逐步动作计划Task-Action 数据供后续 Execution 阶段直接消费。本文聚焦这一源头阶段。整体流水线示意可参考 assets/dataflow/overview.png。2. 三阶段总体流程根据 官方文档 的概述Instantiation 包含三个核心步骤Choose a template根据指定的应用app与指令选择最合适的模板文件Prefill the task基于当前应用的截图与 UI 状态把初始任务预填充为具体任务与动作序列Filter the established task对预填充后的任务进行质量评估判断其是否可以本地执行。从源码调用链看三个阶段由 DataFlowController.execute_instantiation 顺序编排template_copied_path self.instantiation_single_flow( ChooseTemplateFlow, choose_template, init_params[self.task_object.app_object.file_extension], execute_params[], ) if template_copied_path: self.app_env.start(template_copied_path) prefill_result self.instantiation_single_flow( PrefillFlow, prefill, init_params[self.app_env], execute_params[template_copied_path, self.task_object.task, self.task_object.refined_steps], ) self.app_env.close() if prefill_result: self.instantiation_single_flow( FilterFlow, instantiation_evaluation, init_params[], execute_params[prefill_result[instantiated_request]], ) return prefill_result[instantiated_plan]即ChooseTemplateFlow选出模板 → 用WindowsAppEnv.start()打开模板 →PrefillFlow在真实应用环境中预填充 → 关闭应用 →FilterFlow对预填充后的请求做质量评估。三阶段的产出与耗时都会写入统一的task_info结构data_flow_controller.py最终按 instantiation_schema.json 校验后落盘。3. Phase 1Choose Template File模板选择3.1 模板的组织方式模板必须按应用名组织在dataflow/templates/app目录下并配套一个description.json描述文件。以 Word 为例仓库中真实存在 dataflow/templates/word/description.json{ 1.docx: A doc with a rectangle shape, 2.docx: A doc with a line of text, 3.docx: A doc with a chart, 4.docx: A doc with a text box, 5.docx: A doc with comments and reviewer, 6.docx: A doc with a list of items, 7.docx: A doc with a table }description.json的键是模板文件名值是语义描述选择模板时会把指令与这些描述做匹配。如果description.json缺失则从模板目录中随机挑选一个文件见下文的回退逻辑。3.2 ChooseTemplateFlow 的源码实现ChooseTemplateFlow定义在 dataflow/instantiation/workflow/choose_template_flow.py。其核心流程如下读取描述文件_get_chosen_file_path()拼接TEMPLATE_PATH/app/description.json路径并加载选择模板_choose_target_template_file()根据配置项TEMPLATE_METHOD分流SemanticSimilarity语义匹配LLM使用TemplateAgent让大模型决策其他值抛ValueError复制模板_create_copied_file()把选中的模板复制到RESULT_HUBdataflow/results/{task_type}下的saved_document目录文件名默认为任务文件名缺省时用时间戳%Y-%m-%d-%H-%M-%S_generate_copied_file_path回退机制若description.json不存在_choose_random_template()从模板目录随机选取一个文件并打印提示。3.3 语义匹配SemanticSimilarity原理语义匹配实现在_choose_target_template_file_semantic()choose_template_flow.pyfile_doc_map {desc: file_name for file_name, desc in doc_files_description.items()} db FAISS.from_texts(list(doc_files_description.values()), self._embedding_model) most_similar db.similarity_search(given_task, k1) return file_doc_map[most_similar[0].page_content]用 HuggingFaceEmbeddings 对全部模板描述做向量化并借助CacheBackedEmbeddings与LocalFileStore缓存到CONTROL_EMBEDDING_CACHE_PATH用FAISS构建索引对任务文本做k1的最近邻搜索模型名来自配置项CONTROL_FILTER_MODEL_SEMANTIC_NAME默认all-MiniLM-L6-v2见 config_dev.yaml加载时会自动补全sentence-transformers/前缀。3.4 LLM 匹配TEMPLATE_METHOD LLM当配置为LLM时会实例化 TemplateAgent用 template.yaml 构造提示词把模板描述列表与给定任务一起交给模型要求模型返回形如{1.docx: short description of why you pick this}的 JSON随后解析 JSON 键作为所选模板文件名_choose_target_template_file_llm。需要说明的是采用 LLM 视觉版时需要按 dataflow/README.md 的说明在templates/app/images目录手工准备与模板同名的 PNG 截图。4. Phase 2Prefill the Task任务预填充4.1 PrefillFlow真实环境中的任务转写PrefillFlow继承自AppAgentProcessor定义于 dataflow/instantiation/workflow/prefill_flow.py它负责细化任务计划并自动化 UI 交互构造时接收app_name、task_file_name和WindowsAppEnv。其关键职责Agent 复用以_app_prefill_agent_dict字典按应用缓存PrefillAgent同一应用只创建一个 Agent 实例UI 工具初始化ControlInspectorFacade(uia)负责控件检查PhotographerFacade负责截图日志系统在PREFILL_LOG_PATH默认dataflow/logs/{task}/prefill/下分别记录prefill_messages.json与prefill_responses.json。核心执行方法是_get_prefill_actions()prefill_flow.py分为四步更新应用状态_update_state(file_path)通过ControlInspectorFacade抓取应用窗口内的控件元素控件类型来自 UFO 配置的CONTROL_LIST生成带编号标注的_annotation_dict再过滤出_filtered_annotation_dict与_control_info保存截图_save_screenshot()先用文档名匹配窗口WindowsAppEnv.find_matching_window窗口不存在则退化为全屏截图保存为日志目录下的screenshot.png构造提示词调用PrefillAgent.message_constructor(, given_task, reference_steps, log_path)调用模型并解析以prefill作为 process 名、use_backup_engineTrue调用模型解析响应的 JSON取出New_taskinstantiated_request与Actions_planinstantiated_plan。execute()最终返回{instantiated_request: ..., instantiated_plan: ...}并记录execution_time。4.2 PrefillAgent 与 PrefillPrompterPrefillAgent 继承自 UFO 的BasicAgent构造时通过get_prompter()装载 PrefillPrompter。message_constructor按三段式组装消息System 消息system_prompt_construction(dynamic_examples)把可用 API 列表与示例注入系统提示词User 消息user_content_construction(given_task, reference_steps, log_path)在视觉模式下会把截图以image_url形式加入消息同时用sanitize_user_input清洗任务与步骤文本后再填充用户提示词模板。Prompt 模板 prefill.yaml 明确了两个输出目标New_task 约束必须基于给定任务细化、具体且不含主观词、最多在给定任务上增加 50 词、必须能被 Windows 应用逐步完成Actions_plan 约束每个动作必须来自可用 API 列表按Step/Subtask/ControlLabel/ControlText/Function/Args的 JSON 结构逐行输出多个动作以\n分隔。示例提示词见 prefill_example.yaml其中包含 Delete Text、Highlight Text 等完整示例帮助模型学会先观察画布状态 → 推理可用控件 → 输出 select_text / click_input 动作的决策范式。5. Phase 3Filter the Task任务过滤5.1 FilterFlow质量评估的编排层FilterFlow 是 Instantiation 与后续执行之间的质检关卡负责按预定义过滤标准细化任务步骤并评估任务可行性。构造时按应用复用FilterAgent_app_filter_agent_dict并在FILTER_LOG_PATH默认dataflow/logs/{task}/filter/下初始化filter_messages.json与filter_responses.json两份日志。execute(instantiated_request)调用_get_filtered_result()用FilterAgent.message_constructor(instantiated_request, app_name)构造提示词并写入消息日志以filter为 process 名调用模型对响应做_fix_json_commas()去除换行符以修复格式后再用response_to_dict解析将解析结果含execution_time写入响应日志返回{judge: ..., thought: ..., request_type: ...}三元组。5.2 FilterAgent 与评估维度FilterAgent 同样继承BasicAgent通过 FilterPrompter 装载 filter.yaml。评估维度在 prompt 中定义得非常明确任务必须只与当前应用如 Word相关不涉及与其他应用/插件的交互否则判为App_involve是客观可执行的任务不含 custom、you want 等主观表述否则判为Non_task指定明确元素例如不能只说 text 而不给出具体字符串不依赖版本升级/降级等环境变化否则判为Env其余无法执行或无关的情况统一归为Others。模型输出要求严格为如下 JSON 结构{ judge: true, thought: Outline the reason why you give the judgement., type: None/Non_task/App_involve/Env/Others }judge为布尔值决定该任务是否通过实例化质检。6. 配置与准备运行 Instantiation 的前置条件6.1 LLM 配置PREFILL_AGENT / FILTER_AGENT运行前需要复制 dataflow/config/config.yaml.template 为dataflow/config/config.yaml并分别为 PrefillAgent 和 FilterAgent 配置大模型。模板默认值如下PREFILL_AGENT: { VISUAL_MODE: True, # 是否使用视觉模式 API_TYPE: openai, # openai / aoai / azure_ad API_BASE: https://api.openai.com/v1/chat/completions, API_KEY: sk-, # OpenAI API Key API_VERSION: 2024-02-15-preview, API_MODEL: gpt-4-vision-preview # 需要支持视觉输入 }FILTER_AGENT 结构与之完全一致。若使用 Azure OpenAIAOAI则切换API_TYPE: aoai并配置API_BASE: https://{your-resource-name}.openai.azure.com、API_DEPLOYMENT_ID若希望改用非视觉模型如 GPT-4将VISUAL_MODE设为False并更换API_MODEL/API_DEPLOYMENT_ID即可。其余公共参数包括MAX_TOKENS: 2000、MAX_RETRY: 3、TEMPERATURE: 0.0、TOP_P: 0.0、TIMEOUT: 60。注意config.yaml包含私密 Key切勿上传到公开仓库。6.2 路径与行为参数config_dev.yamldataflow/config/config_dev.yaml 定义了默认路径与行为参数实例化相关的核心项如下配置项默认值说明TEMPLATE_METHODLLM模板选择后端支持SemanticSimilarity/LLMTEMPLATE_PROMPTdataflow/prompts/instantiation/{mode}/template.yaml模板选择提示词PREFILL_PROMPTdataflow/prompts/instantiation/{mode}/prefill.yaml预填充提示词PREFILL_EXAMPLE_PROMPTdataflow/prompts/instantiation/{mode}/prefill_example.yaml预填充示例提示词FILTER_PROMPTdataflow/prompts/instantiation/{mode}/filter.yaml过滤提示词API_PROMPTufo/prompts/share/lite/api.yaml可用 API 描述TASKS_HUBdataflow/tasks/prefill默认任务目录TEMPLATE_PATHdataflow/templates模板根目录RESULT_HUBdataflow/results/{task_type}结果输出目录INSTANTIATION_RESULT_SCHEMAdataflow/schema/instantiation_schema.json结果校验 SchemaCONTROL_FILTER_MODEL_SEMANTIC_NAMEall-MiniLM-L6-v2语义匹配 embedding 模型CONTROL_EMBEDDING_CACHE_PATHdataflow/cache/embedding 缓存目录PREFILL_LOG_PATHdataflow/logs/{task}/prefill/预填充日志目录FILTER_LOG_PATHdataflow/logs/{task}/filter/过滤日志目录REFORMAT_TO_BATCHTrue是否将结果重排为 UFO batch 模式6.3 准备任务文件、模板与描述任务以 JSON 文件组织在TASKS_HUB默认dataflow/tasks/prefill格式如下示例来自 dataflow/README.md{ app: word, unique_id: 1, task: Type hello and set the font type to Arial, refined_steps: [ Type hello, Set the font to Arial ] }同时确保模板文件与description.json就位最终目录结构类似dataflow/ ├── tasks/prefill/ # 待实例化的任务 JSON ├── templates/word/ # 模板与描述 │ ├── description.json │ ├── 1.docx │ └── ... └── config/config.yaml # 由 config.yaml.template 复制而来6.4 命令行运行安装依赖后pip install -r requirements.txt在仓库根目录执行入口为 dataflow/main.py 与 dataflow/dataflow.py# 仅实例化单文件或目录皆可自动判定单任务/批量 python -m dataflow --instantiation --task_path path_to_task_file # 端到端 dataflow实例化 执行 python -m dataflow --dataflow --task_path path_to_task_file # 仅执行 python -m dataflow --execution --task_path path_to_task_file--task_path缺省时取TASKS_HUB若传入目录则遍历目录内所有 JSON 批量处理dataflow.py。7. 结果输出与质量分级实例化结果经jsonschema.validate校验后按judge结果归档到dataflow/results/instantiation/下的instantiation_pass/instantiation_fail子目录同时选中的模板副本保存在dataflow/results/saved_document/映射逻辑见 data_flow_controller.py 与INSTANTIATION_RESULT_MAP。以 README 中 Turning lines of text into a bulleted list 为例实例化产出的关键片段为{ instantiation_result: { choose_template: { result: dataflow\\results\\saved_document\\bulleted.docx, error: null }, prefill: { result: { instantiated_request: Turn the line of text text to edit into a bulleted list in Word., instantiated_plan: [ { Step: 1, Subtask: Place the cursor at the beginning of the text text to edit, ControlLabel: null, ControlText: , Function: select_text, Args: { text: text to edit } }, { Step: 2, Subtask: Click the Bullets button in the Paragraph group on the Home tab, ControlLabel: 61, ControlText: Bullets, Function: click_input, Args: { button: left, double: false } } ] }, error: null }, instantiation_evaluation: { result: { judge: true, thought: The task is specific and involves a basic function in Word that can be executed locally without any external dependencies., request_type: None }, error: null } }, time_cost: { choose_template: 0.012, prefill: 15.649, instantiation_evaluation: 2.469 } }可以看到Prefill 产出的instantiated_plan中每条动作都包含Step / Subtask / ControlLabel / ControlText / Function / Args直接供 Execution 阶段逐条执行Filter则以judge: true给出可本地执行的判定。字段级约束详见 instantiation_schema.json。8. 实践要点与注意事项模板文件必须预先保存模板被打开后若未保存原始文件应用关闭时未保存的内容会丢失dataflow/README.md 的 Notes运行期间勿手动关闭应用窗口Prefill 阶段依赖实时截图窗口被关闭会直接导致截图失败LLM 输出必须严格 JSONprefill.yaml与filter.yaml都强制要求输出可被json.loads()解析的 JSONFilterFlow还通过_fix_json_commas做了换行修复但格式错误仍会抛JSONDecodeError并计入错误日志视觉模式依赖截图PrefillPrompter.load_screenshots会把日志目录下的screenshot.png编码进用户消息因此VISUAL_MODE与API_MODEL的视觉能力必须匹配三种 task_type 可独立使用若只想生成任务-动作数据单独运行--instantiation即可无需进入执行阶段。参考资源官方文档instantiation.md、dataflow 概览模块说明dataflow/README.md核心实现choose_template_flow.py、prefill_flow.py、filter_flow.py、data_flow_controller.pyAgent 与 Prompterprefill_agent.py、filter_agent.py、template_agent.py、prompts/instantiation/visual配置与 Schemaconfig.yaml.template、config_dev.yaml、instantiation_schema.json模板示例dataflow/templates/word/description.json【免费下载链接】UFOUFO³: Weaving the Digital Agent Galaxy项目地址: https://gitcode.com/GitHub_Trending/uf/UFO创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考