Index 开源浏览器智能体部署教程

Index 是一个开源浏览器智能体（Browser Agent），能够通过自然语言指令自主执行复杂的网页任务，如导航、信息提取、数据录入等。它支持 Gemini、Claude、OpenAI 等多个先进大语言模型（LLM），并在 WebVoyager 基准测试中达到了 92% 的准确率，是当前该领域的最佳开源方案之一。

本教程将指导您在本地环境部署和运行 Index。

1. 项目背景与核心能力

Index 由 Laminar 团队开发，其核心能力包括：

  • 自主任务执行：将网站转化为可操作界面，通过自然语言驱动，完成如“访问 Hacker News，找到AI相关文章并总结”等复杂任务。
  • 多模型支持：可灵活选用 Gemini 2.5 Pro/Flash、Claude 3.7 Sonnet、OpenAI o4-mini 等模型，在速度、成本和准确性间取得平衡。
  • 结构化输出：支持通过 Pydantic 模式定义输出结构，便于可靠地提取数据。
  • 可观测性：与同团队的 Laminar 平台深度集成，可记录完整的浏览器会话和执行轨迹，便于调试。
  • 多种使用方式：提供 Python 库、交互式 CLI（命令行界面）和生产级 Serverless API。

2. 部署前准备

2.1 系统与环境要求

  • 操作系统：Windows、macOS 或 Linux。
  • Python 环境：Python 3.10 或更高版本。
  • 包管理工具：pip。
  • 浏览器引擎：项目使用 Playwright 控制浏览器，需要安装 Chromium。

2.2 获取 API 密钥

Index 本身是免费的，但它需要调用第三方 LLM 提供商的 API 才能工作。您至少需要准备以下一个服务商的 API 密钥：

  • Google Gemini：GEMINI_API_KEY
  • Anthropic Claude：ANTHROPIC_API_KEY
  • OpenAI：OPENAI_API_KEY

注意：所有 API 密钥均为付费服务，请自行在各平台申请并留意用量和费用。

3. 详细安装与配置步骤

3.1 安装核心包与浏览器驱动

打开终端，执行以下命令安装 Index Python 包及其依赖：

1
pip install lmnr-index 'lmnr[all]'

安装完成后，安装 Playwright 所需的 Chromium 浏览器：

1
playwright install chromium

3.2 配置环境变量

在您的项目根目录下创建 .env 文件，用于安全存储 API 密钥：

1
2
3
4
5
6
7
# 至少填写一个
GEMINI_API_KEY="你的Google Gemini API密钥"
ANTHROPIC_API_KEY="你的Anthropic Claude API密钥"
OPENAI_API_KEY="你的OpenAI API密钥"

# 可选：如需使用Laminar进行可观测性追踪，填写项目API密钥
LMNR_PROJECT_API_KEY="你的Laminar项目API密钥"

4. 运行与验证

方式一：使用交互式 CLI（推荐快速体验）

Index 提供了一个美观的终端交互界面，适合测试和体验。
在终端中直接运行：

1
index run

启动后，CLI 会引导您选择要使用的 LLM 模型。选择后，您就可以在提示符下输入自然语言任务，例如：

1
你的指令: 访问 news.ycombinator.com，找到一篇关于AI的文章，并总结其要点。

Agent 会实时显示执行步骤（如“Step 1: Opening…”），并最终返回结果。

方式二：在 Python 代码中集成

您可以将 Index 作为库集成到自己的 Python 项目中。创建一个 Python 文件（如 run_agent.py）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
import asyncio
from index import Agent, GeminiProvider
from lmnr import Laminar
import os

# 可选：初始化Laminar追踪
# Laminar.initialize()

async def main():
    # 1. 初始化LLM提供商，例如使用Gemini
    llm = GeminiProvider(model="gemini-2.5-pro-preview-05-06")
    # 2. 创建Agent实例
    agent = Agent(llm=llm)
    
    # 3. 运行任务
    output = await agent.run(
        prompt="请访问lmnr.ai，总结其定价页面。"
    )
    
    # 4. 打印结果
    print(output.result)

if __name__ == "__main__":
    asyncio.run(main())

然后使用 python run_agent.py 运行脚本。

方式三：使用 Serverless API（生产环境推荐）

Index 也提供托管式 API，用于生产环境。需要先安装 Laminar 客户端：

1
pip install @lmnr-ai/lmnr

然后在代码中通过 API 密钥调用：

1
2
3
4
5
6
7
from lmnr import LaminarClient, Laminar

Laminar.initialize()
client = LaminarClient(projectApiKey="你的项目API密钥")

response = await client.agent.run(prompt="今日伦敦天气如何？")
# 处理流式响应...

5. 高级功能与可观测性

5.1 使用个人 Chrome 浏览器

如果希望 Agent 利用您现有的浏览器登录态（例如已登录的邮箱、社交媒体），可以指定使用本地 Chrome 实例：

1
index run --local-chrome

5.2 可观测性（Observability）与调试

这是 Index 的核心优势之一。通过初始化 Laminar，所有 Agent 的思考步骤、LLM调用和同步的浏览器操作录像都会被记录下来，并可在 Laminar 平台（可本地自托管）上查看，极大地便利了调试和性能优化。

要启用此功能，您需要：

  1. 获取 LMNR_PROJECT_API_KEY。
  2. 在代码或 CLI 运行前初始化 Laminar.initialize()。
  3. （可选）按照 Laminar 文档 使用 Docker Compose 自托管 Laminar 平台。

6. 常见问题与排查

问题 可能原因与解决方案
安装 lmnr[all] 失败 Python 版本过低或网络问题。请确保使用 Python 3.10+，并尝试使用国内镜像源加速。
提示 API 密钥无效 .env 文件未正确加载，或密钥本身有误。确保文件在项目根目录，且变量名与代码中读取的一致。
浏览器无法启动 Playwright 浏览器未正确安装。重新运行 playwright install chromium。在无图形界面的服务器上，可能需要安装额外的系统依赖（参考 Playwright 文档）。
Agent 执行卡住或超时 网络连接问题，或目标网站反爬机制较强。可尝试更换网络环境，或降低任务复杂度。
找不到 index 命令 Python 的 Scripts 目录未添加到系统 PATH。请确认 lmnr-index 包安装成功，并直接使用 python -m index.cli 运行。

通过以上步骤，您已成功部署并运行了 Index 浏览器智能体。其强大的自动化能力与卓越的可观测性，将为您的 Web 自动化、数据采集和 AI 应用开发提供有力支持。如需更深度的定制或生产部署，建议查阅其官方文档。