基于LLM与Playwright的智能网页自动化：Web-Use项目实战解析

1. 项目概述一个能“看懂”网页的智能体如果你也厌倦了那些重复、繁琐的网页操作——比如在不同电商平台比价、手动填写表单、或者从一堆搜索结果里筛选信息——那么今天聊的这个项目你可能会非常感兴趣。它叫Web-Use本质上是一个智能化的自主网页浏览代理。简单来说你可以把它理解为一个拥有“眼睛”和“手”的AI助手它能像真人一样打开浏览器阅读网页内容理解你的指令然后自动执行点击、输入、滚动、下载等一系列操作。这个项目的核心价值在于它将大语言模型的理解能力与浏览器的自动化操控能力结合了起来。传统的网页自动化工具比如Selenium需要你编写非常精确的脚本告诉它“点击ID为‘submit’的按钮”。但现实中的网页千变万化按钮的ID可能每天都不一样。Web-Use的思路则更接近人类它让AI“看”到网页的截图和DOM结构然后“思考”“用户想让我找RTX 4060的价格这个页面上有好几个商品卡片我应该点开哪一个看看详情” 这种基于视觉和语义理解的自动化适应性要强得多。我花了一些时间深入研究了这个项目的代码和设计它非常适合开发者、数据分析师、或者任何需要从网上批量获取和处理信息的从业者。无论是做市场调研、竞品分析、内容聚合还是自动化一些日常的办公流程它都能显著提升效率。接下来我会拆解它的核心设计、手把手带你完成部署和定制并分享我在测试过程中踩过的坑和总结的经验。2. 核心架构与设计思路拆解要理解Web-Use为什么能工作我们需要先抛开代码看看它的大脑和四肢是如何协同的。整个系统的设计可以概括为“感知-思考-行动”的循环这个循环在LangGraph的框架下被组织成一个可控的工作流。2.1 大脑LLM的决策与规划能力项目默认支持Gemini、Groq和Ollama三种大模型后端。选择哪个模型是第一个需要权衡的点。Gemini尤其是gemini-2.0-flash在响应速度和多模态理解结合视觉上表现均衡API调用也相对方便适合快速上手和大多数任务。Groq凭借其极快的推理速度著称如果你需要代理进行大量、快速的链式思考比如分析一个结构复杂的页面它会是不错的选择。Ollama则提供了完全的本地化部署能力使用像llama3.2、qwen2.5这样的开源模型保证了数据的私密性但需要你本地有足够的GPU资源。模型在这里扮演“指挥官”的角色。它接收来自用户的自然语言指令如“去亚马逊找RTX 4060笔记本显卡的价格”并结合当前浏览器的“观察结果”网页截图、文本摘要、可交互元素列表进行思考。它的输出不是最终答案而是一个或多个具体的“动作”指令比如CLICK(//button[contains(text(), Next)])或TYPE(search_box, RTX 4060 laptop)。注意模型的选择直接影响智能体的“智商”和成本。对于简单的导航任务轻量模型足够但对于需要复杂逻辑判断的任务例如从一篇长文中提取特定观点的摘要更强大的模型能显著提升成功率。在项目初期建议先用Gemini Flash这类低成本模型验证流程。2.2 眼睛与手Playwright与CDP如果说LLM是大脑那么Playwright就是智能体的眼睛和手。Playwright是一个强大的浏览器自动化库它支持Chromium、Firefox和WebKit。Web-Use主要利用它做两件事导航与交互根据LLM发出的动作指令精准地打开网页、点击元素、输入文本、滚动页面。环境感知这是关键。Playwright不仅能获取页面的DOM树还能通过Chrome DevTools Protocol捕获页面的完整截图。这张截图会被传递给LLM如果开启了视觉功能让模型能“看到”按钮的实际位置、图片内容、甚至是验证码从而做出更接近人类的判断。为什么不用更老的SeleniumPlaywright在速度、稳定性以及对现代Web应用大量使用JavaScript动态渲染的支持上更胜一筹。它的API设计也更现代化与异步编程Async/Await模式结合得更好这对于需要等待页面加载、元素出现的自动化任务至关重要。2.3 协调中枢LangGraph的工作流管理LLM和Playwright各司其职但它们需要一个“神经系统”来有序地组织“观察-思考-行动”这个循环。这就是LangGraph的用武之地。LangGraph允许你以图Graph的形式定义智能体的工作流。在Web-Use中这个工作流大致是这样的开始节点接收用户查询。观察节点使用Playwright获取当前页面的状态文本、截图、可操作元素。思考节点将用户查询和观察结果一起喂给LLM请求LLM决定下一步做什么动作或者判断任务是否已完成。行动节点执行LLM决定的动作如点击、输入。条件判断检查LLM的输出是“继续行动”还是“任务完成”。如果是继续则跳回第2步观察节点形成循环如果完成则结束。这种图结构使得智能体的行为不再是线性的脚本而是一个可以根据环境反馈动态调整的决策过程非常灵活。3. 从零开始环境部署与核心配置详解理论讲完了我们动手把它跑起来。这里我会详细说明每一步的意图和可能遇到的问题。3.1 基础环境搭建项目推荐使用uv作为Python包管理器和python 3.12。uv是新兴的工具速度极快能完美处理依赖冲突。如果你还没安装可以先用pip安装它pip install uv。首先克隆仓库并进入目录git clone https://github.com/CursorTouch/Web-Use.git cd Web-Use接着使用uv sync安装所有依赖。这个命令会根据项目根目录的pyproject.toml文件创建一个独立的虚拟环境并安装所有包。这比传统的pip install -r requirements.txt更干净、更快速。然后安装Playwright所需的浏览器内核playwright install chromium这里我明确指定安装chromium因为它是CDP支持最完善的也是项目默认使用的浏览器。安装过程会自动下载浏览器二进制文件。3.2 模型API密钥配置项目的智能核心是LLM所以你需要准备一个模型的API密钥。这里以Google Gemini为例。前往 Google AI Studio 创建一个API密钥。在项目根目录下复制.env.example文件并重命名为.env。打开.env文件将你的密钥填入对应位置GOOGLE_API_KEY你的_actual_api_key_here重要安全提示永远不要将.env文件提交到Git仓库.gitignore文件通常已经包含了它。你的API密钥就是钱泄露可能导致未经授权的使用和费用损失。如果你想使用Groq或Ollama配置方式类似。对于Ollama你通常需要设置OLLAMA_BASE_URL例如http://localhost:11434和OLLAMA_MODEL例如llama3.2并在本地运行Ollama服务。3.3 首次运行与验证项目提供了一个简单的入口脚本app.py。但在运行前我们先创建一个简单的测试脚本test_agent.py来理解其工作原理# test_agent.py from src.inference.gemini import ChatGemini from src.agent.web import WebAgent from dotenv import load_dotenv import os # 1. 加载环境变量 load_dotenv() google_api_key os.getenv(GOOGLE_API_KEY) # 2. 初始化LLM # 参数说明 # model: 指定Gemini模型版本gemini-2.0-flash 是性价比之选。 # api_key: 传入密钥。 # temperature: 创造性设为0使输出更确定、可重复适合自动化任务。 llm ChatGemini(modelgemini-2.0-flash, api_keygoogle_api_key, temperature0) # 3. 初始化Web智能体 # 参数说明 # llm: 上面创建的语言模型实例。 # verbose: 设为True会在控制台打印详细的决策日志调试时非常有用。 # use_vision: 是否将网页截图传给模型。开启后能力更强但消耗更多token。 agent WebAgent(llmllm, verboseTrue, use_visionFalse) # 4. 发起一个简单的任务 user_query 打开百度首页在搜索框里输入天气预报然后点击搜索按钮。 print(f[用户指令] {user_query}) try: agent_response agent.invoke(user_query) print(f\n[智能体最终回复] {agent_response.get(output)}) except Exception as e: print(f\n[执行出错] {e})运行这个脚本python test_agent.py如果一切顺利你会看到控制台开始滚动日志。verboseTrue会让你看到智能体的思考过程例如[THOUGHT] 用户想搜索天气预报。我需要先导航到百度首页。 [ACTION] NAVIGATE(urlhttps://www.baidu.com) [OBSERVATION] 已成功加载百度首页。页面包含一个搜索框和一个“百度一下”按钮。 [THOUGHT] 现在需要在搜索框中输入“天气预报”。 [ACTION] TYPE(selector#kw, text天气预报) ...最终浏览器会自动完成打开百度、输入、搜索这一系列操作。第一次看到浏览器被自动操控感觉还是挺奇妙的。4. 核心功能模块深度解析与定制让一个Demo跑起来只是第一步。要让Web-Use真正为你所用必须理解它的核心模块并知道如何调整。4.1 观察模块智能体如何“看”网页智能体在行动前必须先观察环境。在src/agent/state.py和相关的工具函数中定义了观察的内容。主要包括页面文本摘要通过Playwright获取页面的主要文本内容并经过清洗和截断避免token超限。这是LLM理解页面内容的基础。可交互元素列表提取页面上所有可点击、可输入的HTML元素如按钮、链接、输入框并生成它们的XPath或CSS选择器以及描述性文字如按钮上的文字。这个列表是LLM决定“点击哪里”的关键依据。屏幕截图可选当use_visionTrue时Playwright会截取当前页面的完整PNG图片并将其编码为Base64字符串随提示词一起发送给支持多模态的LLM如Gemini。这对于识别验证码、理解图表或处理纯图片按钮至关重要。自定义观察粒度默认的文本摘要可能过于简略。如果你处理的页面信息密集可以修改提取逻辑。例如你可以选择只提取article或.main-content标签内的文本或者通过Playwright的evaluate方法执行自定义JavaScript来提取更结构化的数据。4.2 动作模块智能体如何“操作”网页LLM思考后输出的动作需要被解析并执行。动作定义在src/agent/tools.py中通常包括navigate(url): 导航到指定URL。click(selector): 点击某个元素。type(selector, text): 在输入框输入文本。scroll(direction): 滚动页面。wait(time): 等待一段时间。extract_text(selector): 提取特定元素的文本。关键点选择器的稳定性。LLM通常基于元素文本如“搜索”来生成选择器但网页上的文本可能不唯一或者动态变化。为了提高可靠性项目代码中通常会结合多种策略来定位元素优先使用唯一的ID其次是稳定的CSS类组合最后才是XPath。在实际使用中你可能会发现智能体偶尔点击错误。这时你可以通过增强提示词Prompt来指导LLM生成更稳健的选择器例如要求它“优先使用包含># price_monitor.py import json from datetime import datetime from src.inference.gemini import ChatGemini from src.agent.web import WebAgent from dotenv import load_dotenv import os def monitor_jd_price(product_name, output_fileprices.json): 监控京东商品价格 load_dotenv() llm ChatGemini(modelgemini-2.0-flash, api_keyos.getenv(GOOGLE_API_KEY), temperature0) # 开启vision帮助识别商品图片和价格标签 agent WebAgent(llmllm, verboseTrue, use_visionTrue) # 构建更精确的指令 detailed_query f 请执行以下步骤 1. 打开 https://www.jd.com 2. 在首页找到搜索框输入“{product_name}”然后点击搜索按钮。 3. 在搜索结果页面找到并点击第一个看起来是“联想拯救者Y7000P”笔记本电脑的商品链接。注意避开广告。 4. 进入商品详情页后找到商品标题和当前价格。 5. 将标题和价格信息整理后告诉我。 注意如果页面需要滚动才能看到更多内容请先向下滚动。每一步操作后请等待页面加载稳定。 print(f开始监控任务: {product_name}) try: response agent.invoke(detailed_query) result_text response.get(output, ) print(f智能体返回结果:\n{result_text}) # 简单解析结果这里可以做得更复杂比如用正则表达式提取价格数字 # 假设结果格式为“标题xxx价格yyy元” import re price_match re.search(r价格[:]?\s*([\d,]\.?\d*)元?, result_text) title_match re.search(r标题[:]?\s*(.), result_text) data { product: product_name, title: title_match.group(1) if title_match else 未提取到, price: price_match.group(1) if price_match else 未提取到, timestamp: datetime.now().isoformat(), source: JD } # 保存到JSON文件 try: with open(output_file, r, encodingutf-8) as f: history json.load(f) except FileNotFoundError: history [] history.append(data) with open(output_file, w, encodingutf-8) as f: json.dump(history, f, ensure_asciiFalse, indent2) print(f价格数据已保存: {data}) except Exception as e: print(f任务执行失败: {e}) if __name__ __main__: monitor_jd_price(联想拯救者Y7000P)5.3 处理复杂交互与稳定性优化上面的基础脚本可能会在真实网站中遇到挑战登录与验证码京东未登录状态可能无法获取准确价格。解决方案是使用Playwright的context.storage_state()功能先手动登录一次并保存登录状态Cookie、LocalStorage后续任务加载该状态。对于验证码可以结合use_visionTrue让LLM识别或者集成第三方打码平台API。页面动态加载商品列表可能是滚动加载。需要在提示词中明确指示智能体“向下滚动直到看到更多商品”或者在动作循环中加入判断逻辑。元素定位失败商品的选择器可能每天变化。更健壮的方法是让LLM基于商品标题、价格等文本特征来识别而不是依赖固定的CSS路径。可以修改观察模块提取每个商品块的文本信息让LLM从中选择。超时与重试网络不稳定可能导致操作失败。应在agent.invoke外层添加重试机制并对特定错误如TimeoutError进行捕获和重试。6. 常见问题排查与性能调优指南在实际使用中你肯定会遇到各种问题。下面是我总结的一些典型场景和解决方案。6.1 智能体陷入循环或行为异常现象智能体在页面上重复点击同一个按钮或者在“输入”和“搜索”之间来回切换无法推进任务。原因观察信息不足LLM没有从提供的页面文本/元素列表中识别出关键信息。提示词不清晰任务指令存在歧义LLM无法理解最终目标。动作执行反馈有误点击动作执行了但页面状态没有按预期变化例如触发了JavaScript错误而观察模块没有捕获到这个变化。排查步骤开启verbose日志这是最重要的调试工具。查看每一步LLM接收到的观察信息是否准确反映了页面状态。检查观察输出如果页面文本摘要太短或遗漏了关键信息需要调整观察模块的提取逻辑。优化提示词在系统提示中加入更严格的约束例如“如果你在连续3个步骤中执行了相似的动作但页面状态没有发生实质性变化请停止并报告‘可能遇到障碍’。”人工介入检查让智能体在关键步骤暂停手动检查浏览器页面是否如预期加载。可能是网站有反爬机制触发了验证码。6.2 执行速度慢或Token消耗高现象完成一个简单任务花费很长时间或者Gemini API账单费用增长较快。原因use_visionTrue传输高清截图会消耗大量Token且模型处理图片需要时间。页面内容过于复杂观察模块提取的页面文本过长导致每次请求的提示词都非常庞大。LLM响应慢使用的模型本身推理速度较慢如某些大型模型。网络延迟与Playwright浏览器实例或LLM API的通信存在延迟。优化策略按需使用视觉对于文本信息丰富的页面如新闻、文档关闭use_vision。仅在需要识别图像内容时开启。精简观察内容修改代码只提取与当前任务可能相关的页面区域文本。例如在搜索场景下只提取搜索框和结果列表区域的DOM。选择高效模型对于导航类任务gemini-2.0-flash或groq-llama3在速度和成本上远优于更大的模型。设置超时与重试为Playwright操作如click、wait_for_selector设置合理的超时时间避免因元素未加载而长时间等待。并行化考虑对于需要监控大量独立页面的任务可以运行多个智能体实例但要注意API的速率限制。6.3 特定网站兼容性问题现象在A网站工作正常在B网站完全无法操作。原因反机器人检测网站检测到Playwright的自动化特征如navigator.webdriver属性为true。复杂前端框架页面由React/Vue等框架动态渲染DOM结构在初始加载后剧烈变化导致元素选择器失效。非标准交互网站使用了自定义的富交互组件如拖拽、画布Playwright的标准API难以模拟。应对方案启用Stealth模式Playwright可以通过加载特定插件或设置参数来隐藏自动化特征。需要更深入的Playwright配置。等待网络空闲在关键操作后使用page.wait_for_load_state(networkidle)等待页面动态内容加载完成再进行观察。使用更稳健的定位器优先使用page.get_by_role()、page.get_by_text()或page.get_by_test_id()等基于语义的定位器这些比脆弱的XPath或CSS选择器更可靠。定制化动作对于特殊交互可以在tools.py中编写新的动作函数利用Playwright的evaluate直接执行JavaScript来操作页面。6.4 错误处理与日志记录一个健壮的自动化系统必须有完善的错误处理和日志记录。增强错误处理 在调用agent.invoke时用try-except包裹捕获特定异常并执行备用方案如重试、切换策略、发送警报。import time from playwright._impl._errors import TimeoutError as PlaywrightTimeoutError def robust_invoke(agent, query, max_retries3): for attempt in range(max_retries): try: return agent.invoke(query) except PlaywrightTimeoutError as e: print(f尝试 {attempt1} 超时: {e}) if attempt max_retries - 1: time.sleep(2 ** attempt) # 指数退避 else: raise # 重试次数用尽抛出异常 except Exception as e: print(f尝试 {attempt1} 发生未知错误: {e}) # 可以根据错误类型决定是否重试 break return None结构化日志 不要只依赖verbose的打印输出。将运行日志时间戳、用户查询、LLM思考、执行动作、观察结果、最终输出结构化地记录到文件或数据库中便于后续分析和复盘。7. 进阶应用与扩展思路当你熟悉了基础操作后可以尝试将这些智能体组合起来解决更复杂的问题。7.1 多智能体协作工作流想象一个场景你需要收集某个行业趋势报告需要从新闻网站、学术数据库和社交媒体多源头获取信息。你可以设计三个 specialized agents新闻采集Agent专门导航新闻网站搜索关键词提取文章摘要和链接。论文检索Agent专门操作知网、Google Scholar等下载相关论文摘要。舆情分析Agent专门在社交媒体平台搜索话题讨论。然后用一个协调员Agent来接收用户指令“收集关于‘AI for Science’的近期资料”并将子任务分发给上述三个智能体最后汇总结果。这可以通过更复杂的LangGraph来实现图中包含并行执行和结果聚合的节点。7.2 与本地工具和数据库集成Web-Use获取的数据不应该只停留在打印输出。可以轻松地将其与你的数据栈集成保存到数据库在动作循环的最后添加一个save_to_db工具将提取的结构化数据如商品价格、新闻标题存入SQLite、PostgreSQL或MongoDB。触发本地脚本当监控到商品价格低于阈值时让智能体调用一个本地Python脚本向你发送邮件或钉钉通知。连接本地API让智能体将提取的文本发送给你本地部署的总结模型如通过Ollama运行的Qwen生成一份简洁的报告。7.3 构建图形化界面与控制面板对于非技术同事让他们直接操作命令行和Python脚本是不现实的。你可以利用FastAPI或Gradio为你的Web-Use智能体快速搭建一个简单的Web界面。界面可以包含任务输入框。模型和参数选择下拉菜单。任务执行状态显示实时日志流。历史任务记录和结果查看。 这样任何人都可以通过浏览器提交一个网址和指令启动一个网页自动化任务。Web-Use项目提供了一个强大的起点但它不是一个开箱即用、解决所有问题的万能工具。它的真正威力在于其可扩展的架构。理解其“观察-思考-行动”的核心循环掌握如何调试和优化提示词学会处理真实网站的复杂性你就能将它定制成专属于你的、无比顺手的自动化利器。从简单的数据抓取到复杂的多步骤业务流程边界只取决于你的想象力。