browser-use

本文集文档发布于灏天文库

第五章：使用方法与实践

文档摘要

第五章：使用方法与实践 第五章：使用方法与实践 本章将深入探讨 browser-use 代理网站访问器的使用方法与实践，旨在帮助用户更好地理解和应用该工具，充分发挥其在 AI 智能体与网页交互方面的潜力。我们将从基本使用流程入手，详细解析常用 API，并总结最佳实践，为用户提供全面的操作指南。 5.1 基本使用流程 browser-use 的核心价值在于简化 AI 智能体与网页的交互过程。其基本使用流程围绕着用户任务的解析、智能体决策、浏览器操作执行以及最终结果的输出展开。下图使用 mermaid graph TD 图清晰地展示了这一流程： 流程详解: 用户任务 (User Task)： 这是使用 browser-use 的起点。

第五章：使用方法与实践

第五章：使用方法与实践

本章将深入探讨 browser-use 代理网站访问器的使用方法与实践，旨在帮助用户更好地理解和应用该工具，充分发挥其在 AI 智能体与网页交互方面的潜力。我们将从基本使用流程入手，详细解析常用 API，并总结最佳实践，为用户提供全面的操作指南。

5.1 基本使用流程

browser-use 的核心价值在于简化 AI 智能体与网页的交互过程。其基本使用流程围绕着用户任务的解析、智能体决策、浏览器操作执行以及最终结果的输出展开。下图使用 mermaid graph TD 图清晰地展示了这一流程：

流程详解:

  1. 用户任务 (User Task)：

    • 这是使用 browser-use 的起点。用户需要明确定义智能体需要执行的任务，例如“打开维基百科，搜索‘人工智能’，并提取搜索结果页面的所有标题和链接”。任务描述应尽可能清晰、具体，以便 LLM 能够准确理解并执行。

    • 任务的清晰度直接影响后续步骤的效率和准确性。任务描述越好，LLM 解析和智能体决策的偏差就越小。

  2. LLM 解析 (LLM Parsing)：

    • 接收到用户任务后，browser-use 内部集成的 LLM (如 GPT-4o, Gemini, Claude 等) 将对任务描述进行自然语言解析，理解用户的意图。

    • LLM 的强大语言理解能力是 browser-use 的核心驱动力之一。它能够将人类语言的任务指令转化为机器可执行的步骤。

    • 例如，对于 “搜索‘人工智能’并提取标题和链接” 的任务，LLM 会解析出需要进行 “打开网页”、“输入关键词”、“执行搜索”、“提取页面元素” 等操作。

  3. Agent 决策/规划 (Agent Decision/Planning)：

    • 智能体 (Agent) 是 browser-use 的核心组件，它基于 LLM 的解析结果，进行任务的决策和规划。

    • Agent 会根据任务的性质，决定需要执行哪些浏览器动作，以及如何提取所需的数据。这可能涉及到复杂的逻辑判断，例如页面元素的定位、交互方式的选择、以及错误处理策略等。

    • 规划阶段可能还会涉及到工具的调用，例如，如果需要进行更复杂的页面数据处理，Agent 可能会调用预先配置的 Python 函数或工具。

    • 在更高级的应用场景中，Agent 还可以利用 Planner LLM 进行多步骤的任务规划，尤其是在任务较为复杂或需要长期交互时。Planner LLM 可以帮助 Agent 制定更合理的执行策略，提高任务完成的效率和成功率。

  4. 浏览器动作 (Browser Action - Playwright 调用)：

    • Agent 的决策最终转化为一系列浏览器动作指令，这些指令通过 Playwright 库来执行。

    • Playwright 是一个强大的浏览器自动化库，browser-use 在其基础上进行了封装，简化了浏览器操作的 API。

    • 常见的浏览器动作包括：

      • 导航 (Navigation): goto(url) 打开指定 URL 的网页。

      • 元素交互 (Element Interaction): click(selector) 点击指定选择器对应的元素； type(selector, text) 在指定元素中输入文本； hover(selector) 鼠标悬停在指定元素上等。

      • 页面滚动 (Page Scrolling): scroll_down(), scroll_to_bottom(), scroll_to_element(selector) 等滚动页面。

      • 截图 (Screenshot): screenshot(path) 截取当前页面或指定元素的截图。

      • 执行 JavaScript (Execute JavaScript): evaluate(script) 在浏览器环境中执行 JavaScript 代码。

    • browser-use 抽象了 Playwright 的底层细节，使得用户可以通过更简洁的 API 来控制浏览器行为。

  5. 数据提取页面信息 (Data Extraction)：

    • 在执行浏览器动作的过程中，Agent 会根据任务需求，从网页中提取所需的信息。

    • 数据提取可以采用多种方式：

      • 选择器提取 (Selector Extraction): 使用 CSS 选择器或 XPath 表达式定位页面元素，并提取元素的文本内容、属性值等。例如，extract_text(selector) 提取文本， get_attribute(selector, attribute_name) 获取属性值。

      • 视觉信息提取 (Vision-based Extraction): 如果启用了视觉能力 (use_vision=True)，Agent 可以利用视觉模型分析页面截图，识别图像中的文本或元素，并进行提取。这对于处理动态内容或难以用选择器定位的元素非常有用。

      • 脚本提取 (Script Extraction): 通过执行 JavaScript 代码，可以获取更复杂的数据，例如网页的 JSON 数据、LocalStorage 内容等。

    • browser-use 提供了灵活的数据提取机制，能够应对各种网页结构和数据格式。

  6. 模型处理 (Model Processing)：

    • 提取到的页面信息可能需要进一步的模型处理，才能得到最终的结构化结果。

    • 模型处理可能包括：

      • 信息总结 (Information Summarization): 使用 LLM 对提取到的文本信息进行概括和总结。

      • 数据清洗 (Data Cleaning): 清理和格式化提取到的数据，去除噪音和冗余信息。

      • 情感分析 (Sentiment Analysis): 分析提取到的文本信息的情感倾向。

      • 关系抽取 (Relation Extraction): 从提取到的信息中抽取实体之间的关系。

    • 模型处理步骤使得 browser-use 不仅能获取网页数据，还能对数据进行深层次的理解和分析。

  7. 结构化结果输出 (Structured Output)：

    • 最终，browser-use 将处理后的结果以结构化的形式输出给用户。

    • 常见的输出格式包括 JSON, CSV, 文本等。用户可以根据自己的需求选择合适的输出格式。

    • 结构化输出方便用户在后续的应用中使用这些数据，例如数据分析、报告生成、知识图谱构建等。

环境准备:

在使用 browser-use 之前，需要进行一些环境准备工作：

  • Python 版本: 确保 Python 版本为 3.11 或更高。推荐使用虚拟环境 (venv) 或 conda 进行环境管理，避免版本冲突。

  • 安装 browser-use: 使用 pip 命令安装 browser-use 库：

    pip install browser-use
​

  • 安装 Playwright: browser-use 依赖 Playwright 进行浏览器自动化，需要安装 Playwright 及其浏览器驱动：

    playwright install
​

    这将自动下载 Chromium 浏览器。如果需要支持 Firefox 或 WebKit，可以执行 playwright install firefox 或 playwright install webkit。

  • 配置 LLM API Keys: 如果使用需要 API Key 的 LLM (例如 OpenAI, DeepSeek)，需要在 .env 文件中配置相应的 API Key。例如，对于 OpenAI 的 GPT 模型，需要在 .env 文件中添加：

    OPENAI_API_KEY=sk-your-openai-api-key
​

    对于 DeepSeek 模型，需要配置 DEEPSEEK_API_KEY。

完成以上环境准备后，就可以开始使用 browser-use 构建强大的 AI 网页交互应用了。

5.2 常用 API 详解

browser-use 的核心 API 围绕 Agent 类展开。Agent 类是与浏览器和 LLM 交互的中心枢纽。以下详细解析 Agent 类的常用参数和方法：

5.2.1 Agent 类参数详解

Agent 类的初始化函数 __init__ 接受多个参数，用于配置智能体的行为和能力。以下是对常用参数的详细解释：

  • task (str, 必传): 代理需要执行的任务描述。这是启动智能体的核心输入，清晰的任务描述是成功完成任务的关键。例如：

    agent = Agent(task="打开 https://www.example.com，找到 ‘关于我们’ 链接并点击，然后提取 ‘公司愿景’ 部分的文本。", llm=llm)
​

  • llm (BaseChatModel, 必传): 主语言模型实例，用于任务解析、决策和内容生成。需要传入 LangChain 提供的 BaseChatModel 的子类实例，例如 ChatOpenAI, ChatAnthropic, ChatGoogleGenerativeAI 等。例如：

    from langchain_openai import ChatOpenAI
llm = ChatOpenAI(model="gpt-4o")
agent = Agent(task="...", llm=llm)
​

  • controller (object, 可选, 默认 Controller 实例): 自定义函数/工具调用的注册表。允许用户扩展 Agent 的功能，注册自定义的函数或工具，供 LLM 在决策过程中调用。关于自定义 Controller 的详细用法将在后续章节介绍。

  • use_vision (bool, 可选, 默认 True): 是否启用视觉能力。如果设置为 True，Agent 将能够利用视觉模型分析页面截图，增强对网页内容的理解，尤其是在处理复杂布局或图像内容时非常有效。但启用视觉能力会产生额外的 token 成本。例如：

    agent = Agent(task="...", llm=llm, use_vision=True)
​

  • save_conversation_path (str, 可选): 指定对话历史保存路径。如果设置了该参数，Agent 会将对话历史记录保存在指定路径下的文件中，用于调试或审计。例如：

    agent = Agent(task="...", llm=llm, save_conversation_path="./conversation_history.json")
​

  • system_prompt_class (type, 可选, 默认 Prompt 类): 自定义 System Prompt 类。允许用户自定义系统提示词的逻辑，更精细地控制 LLM 的行为。关于自定义 System Prompt 的详细用法将在高级特性章节介绍。

  • browser (Browser, 可选): 重用已创建的 Browser 实例。如果需要跨多个 Agent 实例共享同一个浏览器会话，可以传入预先创建的 Browser 实例。如果不提供，Agent 每次 run() 时会自动创建并关闭新的浏览器实例。

  • browser_context (BrowserContext, 可选): 使用已有的浏览器上下文 (Context)。适用于需要维护持久会话 (cookies/localStorage) 的场景。可以传入 Playwright 的 BrowserContext 实例，实现会话的持久化。

  • max_steps (int, 可选, 默认 100): 允许 Agent 执行的最大步骤数，防止 Agent 进入死循环或无限操作。可以根据任务的复杂程度调整该参数。

  • planner_llm (BaseChatModel, 可选): Planner 规划用语言模型。与主 LLM 分开，用于高层策略规划。可以使用较小或更经济的模型作为 Planner LLM，以降低成本。如果设置了该参数，Agent 将启用 Planner 功能，进行更高级的任务规划。

  • use_vision_for_planner (bool, 可选, 默认 True): Planner 是否能使用视觉功能。如果主 LLM 已开启视觉功能，可以独立控制 Planner 是否使用视觉功能，以节省资源。

  • planner_interval (int, 可选, 默认 1): Planner 模型执行间隔。即每多少步调用一次 Planner 进行重新规划。

  • message_context (str, 可选): 额外的任务/上下文信息，辅助 LLM 更好地理解或执行任务。可以提供更详细的背景信息或约束条件。

  • initial_actions (list[dict], 可选): 初始化时要执行的动作列表。在 Agent 启动时，可以预先执行一些动作，无需经过 LLM 调用。动作格式为 [{action_name: {action_params}}]。

  • max_actions_per_step (int, 可选, 默认 1): 每个步骤里可执行的最大动作数。用于控制 Agent 过度频繁操作。

  • max_failures (int, 可选, 默认 3): 允许 Agent 失败的最大次数。超过最大失败次数后，Agent 将停止任务。

  • retry_delay(int, 秒, 可选, 默认10`): 当遇到限流 (rate limit) 或可重试的错误时，等待多少秒后再次尝试。可以根据目标网站的特性调整重试延迟。

  • generate_gif (bool 或 str, 可选, 默认 False): 是否录制浏览器操作过程并生成 GIF 动画。

    • 设置为 True 时，自动生成随机文件名的 GIF 动画。

    • 设置为字符串路径时，将 GIF 动画存储到指定路径。

    • 这对于调试和可视化 Agent 的行为非常有用。例如：

    agent = Agent(task="...", llm=llm, generate_gif=True) # 自动生成 GIF
agent = Agent(task="...", llm=llm, generate_gif="./task_recording.gif") # 指定 GIF 路径
​

5.2.2 Agent 类常用方法详解

Agent 类提供了核心方法来启动和控制智能体的运行。最常用的方法是 run() 方法：

  • async run() -> Any: 异步执行 Agent 任务的核心方法。

    • 功能: run() 方法启动整个 browser-use 流程，包括任务解析、智能体决策、浏览器操作执行、数据提取和结果处理。这是一个异步方法，需要使用 await 关键字调用。

    • 返回值: run() 方法返回任务执行的结果。结果的具体类型取决于任务本身以及 Agent 的配置。通常情况下，返回结果会是结构化的数据，例如字典或列表，包含了从网页提取的信息。如果任务执行过程中发生错误，run() 方法可能会抛出异常。

    • 示例:

    import asyncio
from browser_use import Agent
from langchain_openai import ChatOpenAI
import os
from dotenv import load_dotenv
load_dotenv()
llm = ChatOpenAI(model="gpt-4o")
async def main():
    agent = Agent(
        task="打开 https://www.example.com，提取页面标题和所有的段落文本。",
        llm=llm
    )
    result = await agent.run()
    print("任务结果:", result)
if __name__ == "__main__":
    asyncio.run(main())
​

    • 内部流程: run() 方法内部封装了之前在基本使用流程章节中描述的完整步骤：

      1. 任务接收: 接收在 Agent 初始化时传入的 task 参数。

      2. LLM 解析: 调用配置的 LLM (通过 llm 参数传入) 解析任务描述，理解用户意图。

      3. Agent 规划与决策: Agent 基于 LLM 的解析结果，制定执行计划，决定需要执行的浏览器动作和数据提取策略。

      4. 浏览器交互: Agent 通过 Playwright 调用，执行浏览器动作，例如打开网页、点击链接、填写表单等。

      5. 数据提取: Agent 从网页中提取目标信息，可以使用选择器、视觉分析或 JavaScript 脚本等多种方式。

      6. 模型处理 (可选): 对提取的数据进行进一步的模型处理，例如信息总结、数据清洗等。

      7. 结果输出: 将处理后的结构化结果返回。

  • 其他可能的方法 (根据实际 library 文档补充): 根据 browser-use 库的实际 API 文档，可能还存在其他方法，例如用于更细粒度控制流程的方法，或者用于获取 Agent 状态信息的方法。 用户应查阅最新的官方文档以获取完整和准确的 API 信息。 常见的库可能会提供诸如以下的方法 (需要根据 browser-use 实际情况确认):

    • reset(): 重置 Agent 的状态，例如清除对话历史，重新初始化浏览器实例 (如果 Agent 配置为自动创建浏览器实例)。

    • get_history(): 获取 Agent 的对话历史记录。

    • stop(): 提前停止正在运行的 Agent 任务。

    • pause()/resume(): 暂停和恢复 Agent 任务的执行。

    • add_action(action_dict): 动态地向 Agent 添加需要在下一步执行的动作。

5.3 最佳实践

为了更有效地使用 browser-use，并构建稳定、高效、可靠的 AI 网页交互应用，以下总结了一些最佳实践：

5.3.1 清晰明确的任务定义

  • 详细的任务描述: 提供尽可能详细和具体的任务描述。任务描述越清晰，LLM 就越能准确理解用户意图，从而做出正确的决策和规划。避免使用模糊或歧义的语言。

    • 良好示例: "打开亚马逊网站，搜索 ‘最新款的降噪耳机’，筛选品牌为 Sony 和 Bose，按照用户评价排序，提取前 5 款耳机的商品名称、价格和用户评价星级，并保存为 CSV 文件。"

    • 不良示例: "在网上找耳机，要好评的，贵的也行。"

  • 结构化任务分解 (对于复杂任务): 对于复杂的任务，例如多步骤的网页交互或需要处理多个网页的任务，可以将任务分解为更小的、更易于管理的子任务。 这可以通过在任务描述中明确步骤来实现，或者利用 Agent 的 Planner 功能 (如果启用)。

    • 示例 (结构化任务描述): "1. 打开 https://www.example-ecommerce.com。 2. 在搜索框中输入 ‘智能手表’ 并点击搜索按钮。 3. 在搜索结果页面，点击 ‘价格从高到低’ 排序。 4. 滚动页面到底部加载所有商品。 5. 提取所有商品的名称和价格。 6. 将结果保存到 ‘smartwatches.json’ 文件中。"

5.3.2 合理利用视觉能力 (use_vision)

  • 权衡成本与收益: 启用 use_vision=True 可以增强 Agent 对网页内容的理解，尤其是在处理视觉元素或复杂布局时。但视觉分析会增加 token 消耗，从而增加成本。 因此，需要根据任务的实际需求权衡是否启用视觉能力。

  • 针对性使用: 对于需要处理图像内容、识别验证码、或者定位难以通过选择器定位的动态元素等场景，视觉能力非常有用。 对于简单的文本信息提取任务，可以考虑关闭视觉能力以节省资源。

  • 优化视觉模型 (如果可能): 一些 LLM 平台允许用户选择不同的视觉模型。可以根据任务的特点选择合适的视觉模型，以提高识别精度和效率，同时控制成本。

5.3.3 有效的错误处理和重试机制

  • 预判潜在错误: 在设计 Agent 任务时，预判可能出现的错误类型，例如网络连接错误、页面元素未找到、网站限流等。

  • 设置合理的重试策略: 利用 max_failures 和 retry_delay 参数配置重试机制。对于网络波动或临时性错误，重试可以提高任务的成功率。但需要避免无限重试导致资源浪费。

  • 自定义错误处理逻辑 (高级): 对于更复杂的错误处理需求，可以考虑自定义 Controller，注册自定义的错误处理函数，例如在元素未找到时，可以尝试滚动页面或切换定位策略。

5.3.4 优化性能和控制成本

  • 选择合适的 LLM 模型: 根据任务的复杂程度和性能要求，选择合适的 LLM 模型。对于简单的任务，可以使用性价比更高的模型 (例如 gpt-3.5-turbo, DeepSeek Chat)。 对于复杂的任务，可能需要使用更强大的模型 (例如 gpt-4o)。

  • 减少不必要的浏览器操作: 优化 Agent 的任务规划，减少不必要的浏览器操作，例如避免频繁的页面刷新或不必要的元素点击。

  • 数据提取优化: 使用高效的选择器或数据提取方法，减少需要处理的数据量。 例如，只提取需要的字段，而不是整个页面的 HTML 代码。

  • 利用 Planner 功能 (如果适用): 对于复杂任务，Planner 可以帮助 Agent 制定更优的执行策略，减少试错次数，提高效率。

  • 监控 token 消耗: 定期监控 LLM 的 token 消耗，分析成本构成，并根据需要调整模型选择或任务策略。

5.3.5 安全性考虑

  • 敏感信息处理: 避免在任务描述或 Agent 配置中直接硬编码敏感信息，例如 API Keys, 密码等。 推荐使用环境变量或安全配置管理工具来管理敏感信息。

  • 网站交互安全: 在与网站交互时，遵守网站的使用条款和 robots.txt 协议，避免进行恶意操作或对网站造成不必要的负担。

  • 数据安全: 对于提取到的敏感数据，例如用户个人信息、支付信息等，采取必要的安全措施进行保护，例如加密存储、访问控制等。

5.3.6 调试与监控

  • 使用 save_conversation_path: 在开发和调试阶段，启用 save_conversation_path 参数，保存对话历史记录，方便分析 Agent 的决策过程和排查错误。

  • 利用 generate_gif: 使用 generate_gif 参数录制浏览器操作过程，可视化 Agent 的行为，有助于理解和调试。

  • 日志记录: browser-use 通常会提供详细的日志输出。 仔细分析日志信息，可以了解 Agent 的运行状态、错误信息和性能瓶颈。

  • 监控工具: 对于长期运行的 Agent 应用，建议使用监控工具，例如 Prometheus, Grafana 等，监控 Agent 的性能指标、错误率和资源消耗情况。

5.3.7 持续学习和迭代

  • 关注官方文档和社区: browser-use 是一个快速发展的项目，官方文档和社区论坛是获取最新信息、学习最佳实践和解决问题的重要资源。

  • 实验和优化: 不断尝试不同的 Agent 配置、任务描述和参数设置，优化 Agent 的性能和效果。

  • 收集用户反馈: 如果 Agent 应用是面向用户的，收集用户反馈，了解用户需求和痛点，持续改进 Agent 的功能和用户体验。

总结

本章详细介绍了 browser-use 代理网站访问器的使用方法与实践。 从基本使用流程到常用 API 详解，再到最佳实践总结，旨在帮助用户全面掌握 browser-use 的使用技巧，构建强大的 AI 网页交互应用。 通过清晰的任务定义、合理的参数配置、有效的错误处理和持续的优化，用户可以充分发挥 browser-use 的潜力，赋能 AI 智能体完成更复杂、更有价值的网页自动化任务。 随着 browser-use 和 LLM 技术的不断发展，其应用前景将更加广阔。

发布者: 作者: 转发
评论区 (0)
U
0/500