Ultrafast 安装运行：uv sync 加两个 API Key

上一课把 Jev Ultrafast 原理拆完了，这一课动手：把 jev-ultrafast 安装到你自己的电脑上，跑起本地 inspector。要做的只有两件事——uv sync 装环境，.env 填两个 API Key。

官方 README 的安装路径一共 5 条命令（git clone、cd、uv sync、cp、uv run jev），命令本身不难——但每条命令背后都有「为什么」：为什么是 uv 不是 pip、两个 Key 各管什么、Chrome 是什么时候连上的。这一课把 15 分钟用在这里，装完直接进下一课跑真实的 Google Flights。

学完你能做什么

• 用 git clone + uv sync 完成 jev-ultrafast 安装，依赖锁进仓库自带的 uv.lock、装进项目旁的 .venv，不碰系统 Python
• 配好 .env 里的 6 个环境变量，说清哪两个 Key 必填、各自服务哪次调用
• 在 127.0.0.1:8766 打开 inspector，用 Start demo → Run automatically 跑通第一个 demo
• 用 uv run browser-harness --doctor 连接 Chrome，知道「允许远程调试」提示该不该点
• 把文本 helper 从示例的 OpenRouter + Mercury 换成 DeepSeek、GLM 等 OpenAI 兼容模型

你现在的困境

• 想亲眼看 7 秒搜航班，但 README 只有五行命令，跑不起来时不知道该查哪一层：是没装上、Key 没配、还是 Chrome 没连上
• Key 有点乱：TypeSafe 的 Key 有了，示例配置还要一个 OpenRouter 的——少一个会怎样、什么时候才炸，心里没底
• 电脑上 Python 版本一堆，这个仓库还要求 Python ≥ 3.12——不想再手动折腾一套全局环境

什么时候用这一招

当你需要：

• 在本机跑通开源版 Jev Ultrafast，为跑通 Google Flights备好环境
• 亲眼在 inspector 里看到上一课讲的编号元素、操作概率、目标概率——原理落地成画面
• 之后用 Agent 库写自己的浏览器任务

而且不想：

• 手动建 venv、pip 装依赖、处理版本冲突
• 把 API Key 硬编码进代码，或者不小心提交进 git

🎒 开始前的准备

• 完成了 Jev Ultrafast 原理：知道操作集、投机 target heads 和安全边界，装好后看 inspector 不懵
• 手里有 TypeSafe API Key（没有就先走 注册与 API Key）
• 电脑上装着 Chrome——agent 的所有点击和输入都发生在 Chrome 里
• （可选）一个 OpenRouter 账号的 Key，或者直接用 DeepSeek / GLM 的 Key（第 3 步会讲怎么换）
• 一杯水——这次是真的要让 Jev 替你点浏览器了

系统要求

项	要求	出处
Python	≥ 3.12（requires-python = ">=3.12"）	仓库 pyproject.toml
uv	任意可用版本，没有就第 1 步装	README 用 uv sync 安装
Chrome	本机安装，运行时允许远程调试	README「Try it」
网络	能访问 api.typesafe.ai 和你配置的文本模型端点	jev_ultrafast/model.py

💡 uv 是什么

uv 是 Astral 出的 Python 包和项目管理器（官方原话：extremely fast Python package and project manager, written in Rust）。它在 pyproject.toml 旁边维护一个项目专属的 .venv，uv run 每次都会先确认环境和锁文件同步——你不用再手动 activate 什么。之前在 SDK 安装备用方式里用过 uv add，这次是它的姊妹命令 uv sync。

核心思路

jev-ultrafast 安装的本质 = 一份锁定的依赖 + 两把钥匙。

依赖交给 uv sync。 这个仓库已经带好 pyproject.toml 和 uv.lock，uv sync 做两件事（uv 官方文档《Locking and syncing》的定义）：把依赖锁定成锁文件、再把锁文件里的包装进项目环境（pyproject.toml 旁的 .venv）。装出来的核心三样：

装进 .venv 的东西	版本约束	干什么用
jev-ultrafast 本体	0.1.0	agent 循环 + jev 命令入口
browser-harness	== 0.1.13	连接 Chrome（README：由 uv sync 自动装）
httpx[http2]	≥ 0.28, < 1	发 TypeSafe 和文本模型请求的 HTTP 客户端

开发依赖（pytest、ruff、pillow）属于 dev 组，uv sync 默认一并装上——不用管它们。

钥匙填进 .env，一共要两把。 为什么是两把？上一课讲过：Jev 只做决策、不生成文本；遇到 TYPE_TEXT 操作时，字符串由一个独立的「小 LLM」生成。所以有两个各自独立的服务要授权：

Key	授权谁	什么时候用到
TYPESAFE_API_KEY	api.typesafe.ai/v1/systemone（Jev 决策）	每个决策周期都用，缺了第一个请求就发不出去
TEXT_MODEL_API_KEY	TEXT_MODEL_BASE_URL 指向的 OpenAI 兼容端点（示例是 OpenRouter）	只有操作是 TYPE_TEXT 时，缺了到打字那步才报错

这套「一次请求问操作、打字外包给小模型」的分工，就是 Jev 并行提问里投机扇出的实战形态。

最后是跑法的选择——装好后有三条路，本课走第一条：

跑法	适合谁
本地 demo（uv run jev + inspector）	想先看一眼、能逐步暂停——本课
Agent 库（uv run --env-file .env python 你的脚本.py）	想写自己的任务——第 5 课
BU Ultrafast 云服务（model: "bu-ultrafast"）	不想装任何东西，直接在 Browser Use Cloud 上跑

跟我做

第 1 步：装好 uv 与 Chrome——jev-ultrafast 安装的前置

为什么：整个安装靠 uv 一条命令完成；Chrome 是 agent 的「手」，点按输入都在它里面发生。

先确认 uv 在不在：

uv --version

你应该看到：一行版本号（如 uv 0.13.x，以你装的版本为准）。没有的话，macOS / Linux 用官方安装脚本：

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows（PowerShell）：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

这几条都出自 uv 官方安装文档（docs.astral.sh/uv）；也可以走 brew install uv、pipx install uv、winget install --id=astral-sh.uv -e 等包管理器。系统没有 curl 时官方还给 wget 版：wget -qO- https://astral.sh/uv/install.sh | sh。

Chrome 不用动配置，装着就行——远程调试的授权提示等到第 5 步才出现。

• uv --version 有输出；Chrome 能正常打开

第 2 步：git clone 并运行 uv sync——jev-ultrafast 安装本体

为什么：README「Try it」一节的安装命令就这几条，逐字照抄即可；uv sync 会把仓库锁定的依赖一次装齐（含 Browser Harness），不用你逐个 pip。

git clone https://github.com/browser-use/jev-ultrafast.git
cd jev-ultrafast
uv sync

你应该看到：git 把仓库克隆进 jev-ultrafast/ 目录；uv 完成依赖解析和安装，输出里列出装进环境的包（其中应能看到 browser-harness 和 httpx）；仓库目录下多出一个 .venv/。

三个值得知道的细节（依据 uv 官方文档）：

细节	说明
.venv/	uv 在 pyproject.toml 旁边管理的项目环境，不污染系统 Python，也不用你手动激活
uv.lock	仓库自带，锁定精确版本；已有锁文件时 uv sync 优先用锁定的版本
uv run 会自动同步	之后每次 uv run … 前都会确认环境和锁文件是最新的，所以改了依赖也不用重新手动 sync

• uv sync 无报错，jev-ultrafast/ 下能看到 .venv/

第 3 步：复制 .env.example，填入两个 API Key

为什么：所有 Key 都走 .env 文件——它被仓库 .gitignore 第一行忽略，README 开发一节也写明「Credentials and raw traces stay ignored」，Key 不会跟着 git 走。

cp .env.example .env

然后打开 .env 填两个 Key（<尖括号> 是占位符，填完删掉尖括号）：

TYPESAFE_API_KEY=<你的 TypeSafe API Key>
TYPESAFE_MODEL=jev-latest
TEXT_MODEL_API_KEY=<你的文本模型 Key>
TEXT_MODEL_BASE_URL=https://openrouter.ai/api/v1
TEXT_MODEL=inception/mercury-2.5
TEXT_MODEL_REASONING=none

.env.example 一共 6 个变量，逐个说清（示例值与默认值均出自该文件与 jev_ultrafast/model.py）：

变量	示例值	必填？	管什么
TYPESAFE_API_KEY	—	必填	Jev 决策请求的 Bearer Key，发往 api.typesafe.ai/v1/systemone
TYPESAFE_MODEL	jev-latest	可省	决策模型；不设时代码同样默认 jev-latest
TEXT_MODEL_API_KEY	—	TYPE_TEXT 必需	文本 helper 的 Key；不设且遇到打字操作会直接抛错
TEXT_MODEL_BASE_URL	https://openrouter.ai/api/v1	可省	文本模型端点；不设时代码默认 https://api.deepseek.com/v1
TEXT_MODEL	inception/mercury-2.5	可省	文本模型名；不设时代码默认 deepseek-chat
TEXT_MODEL_REASONING	none	可省	none = 关推理；不设时的规则见下面方式 B

两个 Key 的来源：TypeSafe 的去 console.typesafe.ai/keys（注册课走过一遍）；文本模型的 Key 按你选的方式来：

方式 A（示例配置）：OpenRouter + Mercury

.env.example 的原样配置：OpenRouter 的 Key + inception/mercury-2.5，推理关闭。README 说当前 demo 用的就是它。照抄即可，零决策成本。

方式 B：DeepSeek 直连——代码里的默认端点

只填 TEXT_MODEL_API_KEY=<你的 DeepSeek Key>，TEXT_MODEL_BASE_URL 和 TEXT_MODEL 两行可以不写（从 .env.example 复制来的话要把这两行删掉，留空也不行——空字符串同样算已设置）——model.py 里 unset 时的默认值就是 https://api.deepseek.com/v1 + deepseek-chat。DeepSeek 端点会被自动识别，请求里带 thinking: {type: disabled} 关掉推理。

方式 C：GLM / Gemini 等其他 OpenAI 兼容模型

README 明说：Gemini、GLM、DeepSeek 都可以用这个 OpenAI 兼容的文本 helper——「配置相应的 model、endpoint 和 reasoning 设置」。也就是把 TEXT_MODEL_BASE_URL 换成你所用服务的 OpenAI 兼容端点、TEXT_MODEL 换成对应模型名（具体值以你的服务商文档为准）。

⚠️ reasoning 参数的规则

model.py 的逻辑是：端点含 api.deepseek.com/ 时自动带 thinking: {type: disabled}；其他端点默认带 reasoning: {effort: low}；只有 TEXT_MODEL_REASONING=none 时才变成 reasoning: {enabled: false}。换模型时留一行 TEXT_MODEL_REASONING=none 最省心。

你应该看到：打开的 .env 里 TYPESAFE_API_KEY 与 TEXT_MODEL_API_KEY 两行都是你自己的值，占位尖括号已经删掉；其余 4 行保持示例值或按方式 B/C 调整。

• .env 里两个 Key 都非空；确认它在 .gitignore 里（默认已忽略）

第 4 步：uv run jev 启动本地 inspector

为什么：jev 是 pyproject.toml 注册的命令行入口（[project.scripts] 里 jev = "jev_ultrafast.demo:main"），启动的是一个只监听本机回环地址的 inspector 页面。

在仓库根目录运行：

uv run jev

你应该看到（终端原样输出，出自 demo.py 的 main()）：

Jev Ultrafast: http://127.0.0.1:8766

浏览器打开 http://127.0.0.1:8766，能看到 demo 首页：任务输入框、场景下拉框和一排控制按钮。这个服务只绑定 127.0.0.1（demo.py 文档字符串自称 Loopback-only inspector），别的机器访问不到；Ctrl+C 停止。

两个细节：

• 端口默认 8766，被占用时可用环境变量 TYPESAFE_DEMO_PORT 换（见进阶技巧）

• .env 是启动时从当前目录读取的——所以这条命令必须在 jev-ultrafast/ 仓库根目录里跑（原因见踩坑提醒第 2 条）

• 终端打印出 Jev Ultrafast: http://127.0.0.1:8766，浏览器能看到页面

第 5 步：Start demo 连接 Chrome，跑通第一个 demo

为什么：inspector 是官方给你看决策过程的面板；第一次点 Start demo 时，Browser Harness 会去连 Chrome——远程调试的授权提示就出现在这时。

页面上（按钮名都是界面原文）：

1. 任务框里已预填默认目标：从 Zurich 到 London 的单程航班搜索（原文见 static/index.html，可改成你自己的 1–2000 字符目标）
2. 场景下拉框选 Google Flights · real web（另两个 Travel planner · fixture、Reading room · fixture 是本地页面，不出网）
3. 点 Start demo
4. Chrome 提示远程调试时允许（README 原话：Allow remote debugging in Chrome when prompted）
5. 点 Run automatically 开跑；想逐步看就点 Choose next，它会在每次执行前暂停

如果 Chrome 没连上，在另一个终端（仓库根目录）跑：

uv run browser-harness --doctor

你应该看到：inspector 面板里出现编号元素、操作概率、目标概率和已执行动作（README 原文的四样东西）；浏览器面板里页面开始被自动操作。跑完 Ctrl+C 关掉服务即可。

• Start demo 后 inspector 出现编号元素和两列概率；Chrome 窗口里页面在动

检查点 ✅

• uv --version 有输出，Chrome 已安装
• uv sync 无报错，仓库目录下有 .venv/，安装列表含 browser-harness
• .env 两个 Key 已填：TYPESAFE_API_KEY、TEXT_MODEL_API_KEY
• 仓库根目录 uv run jev 打印 Jev Ultrafast: http://127.0.0.1:8766
• 浏览器打开 127.0.0.1:8766，Start demo 后看到编号元素、操作概率、目标概率

踩坑提醒

❌ 只填了 TYPESAFE_API_KEY 就开跑

现象：demo 能启动、页面也能观察，一到「往输入框里打字」的步骤就停，报错信息原样是：

TYPE_TEXT needs TEXT_MODEL_API_KEY; no text is hardcoded or guessed by the executor.

原因：TEXT_MODEL_API_KEY 只在操作为 TYPE_TEXT 时才被检查（model.py 的 field_text()），启动时不校验，所以缺 Key 能一路跑到打字才炸。Flights demo 要生成城市名，一定躲不过去。

正确做法：两个 Key 一次配齐——这正是本课 H1 里「两个 API Key」的含义。

❌ 不在仓库根目录运行，.env 读不到

现象：明明填了 Key，还是报缺 Key 或用了旧配置。

原因：demo.py 的 load_environment() 从当前工作目录读 .env（代码就是 Path.cwd() / ".env"），在别的目录跑 uv run jev 时读到的是别处的 .env（或没有）。另外它用的是 setdefault——如果你的终端里早就 export 过同名变量，.env 里的值不会覆盖它。

正确做法：先 cd jev-ultrafast 再 uv run jev；排查时用 echo $TEXT_MODEL_API_KEY 看看 shell 里是不是有旧值抢先了。

❌ Chrome 连不上、面板一直不动

原因：Browser Harness 需要 Chrome 允许远程调试，首次连接时 Chrome 会弹提示；错过或拒绝后就连不上。

正确做法：跑 uv run browser-harness --doctor 诊断连接；下次 Chrome 再弹「允许远程调试」时点允许。更多连不上、点不动的排查见 Ultrafast 排错。

❌ 以为文本模型只能用 OpenRouter 的 Mercury

原因：.env.example 的示例值是 OpenRouter + inception/mercury-2.5，看着像绑死了。

事实：README 明说 Gemini、GLM、DeepSeek 都能用这个 OpenAI 兼容 helper；model.py 里不设 TEXT_MODEL_BASE_URL / TEXT_MODEL 时，代码默认值干脆就是 DeepSeek（https://api.deepseek.com/v1 + deepseek-chat）。

正确做法：按第 3 步的方式 B / C 换端点、模型名，并按那条 ⚠️ 提示配好 reasoning；换完后跑一次 demo 验证打字步骤正常。

进阶技巧（可选）

换端口。 8766 被占用时，启动前在 shell 里 export TYPESAFE_DEMO_PORT=8767（Windows PowerShell 用 $env:TYPESAFE_DEMO_PORT="8767"）再 uv run jev。注意：这个变量必须在进程启动前就设好——demo.py 在模块导入时就读定了端口，写进 .env 来不及生效。

先在本地 fixture 页面上练手。 场景下拉框里的 Travel planner · fixture 和 Reading room · fixture 跑的是仓库自带的本地页面（static/fixture.html），不访问外网——想先看看 agent 怎么动、又暂时不想打真实网站时，选它们。

不想本地装？走云服务。 Browser Use Cloud 提供托管版 BU Ultrafast，官方标注所有计划可用：配置 model: "bu-ultrafast" 即可（cloud.browser-use.com）。开源版在你电脑上跑，云服务在 Browser Use Cloud 上跑。

本课小结

✅ jev-ultrafast 安装 = git clone → uv sync → cp .env.example .env → uv run jev，四段五条命令，出自 README「Try it」一节，逐字可用。

✅ 两个 Key 各管一摊：TYPESAFE_API_KEY 授权 Jev 决策（每个周期都用），TEXT_MODEL_API_KEY 授权打字时的小 LLM（缺了到 TYPE_TEXT 才报错，错误信息原文可搜）。

✅ uv sync 把仓库锁定的依赖装进项目旁的 .venv（含连 Chrome 的 browser-harness 0.1.13）；uv run 每次自动确认环境同步。

✅ Chrome 通过 Browser Harness 连接，uv run browser-harness --doctor 是官方诊断命令；首次连接记得允许远程调试。

✅ 文本模型不绑定 OpenRouter：DeepSeek 是代码默认值，GLM / Gemini 走 OpenAI 兼容端点都能用。

关键配置字段回顾（.env，示例值出自 .env.example）：

字段	推荐值	说明
TYPESAFE_API_KEY	（必填）	Jev 决策的钥匙，console.typesafe.ai/keys 获取
TEXT_MODEL_API_KEY	（必填）	文本 helper 的钥匙，随所选服务
TYPESAFE_MODEL	jev-latest	决策模型，可省（默认相同）
TEXT_MODEL_BASE_URL	按方式 A/B/C	文本模型端点，DeepSeek 可省
TEXT_MODEL	按方式 A/B/C	文本模型名，DeepSeek 可省
TEXT_MODEL_REASONING	none	关推理，换模型时建议保留

下一课预告

环境就绪，下一课 跑通 Google Flights：7 秒完成一次真实搜索让 agent 干真活。你会学到：

• 在 inspector 里跑一次真实的 Google Flights 搜索，亲眼看 7 秒是怎么花掉的
• 用 examples/flights.py --keep-open 复现官方实录：搜索、独立验证、保存 trace，不选不订
• 看懂示例的独立 verify() 都查了什么——DONE 不算数，代码验证才算
• 哪些因素会影响这个秒数（测量口径的细节留给性能解读）

附录：源码参考

点击展开查看源码位置

更新时间：2026-11-04（仓库 github.com/browser-use/jev-ultrafast，本地信息源 sources/jev/repo-ultrafast/）

功能	文件路径	关键位置
安装命令与 Chrome 连接说明	README.md	「Try it」一节（git clone / uv sync / cp / uv run jev / 8766 / --doctor / 允许远程调试）；「Use the library」（--env-file 用法）
环境变量示例	.env.example	全文件：6 个变量 + 1 行注释（TYPE_TEXT 必需说明）
Python 版本、依赖、jev 入口	pyproject.toml	requires-python = ">=3.12"；dependencies（browser-harness==0.1.13、httpx[http2]）；[project.scripts] jev = "jev_ultrafast.demo:main"
inspector 端口与 .env 加载	jev_ultrafast/demo.py	L16 PORT（默认 8766，读 TYPESAFE_DEMO_PORT）；L23 load_environment()（cwd 的 .env，setdefault）；L131 main()（打印 Jev Ultrafast: http://127.0.0.1:8766；只绑定 127.0.0.1）
demo 场景与目标长度	jev_ultrafast/demo.py	L44 command()（scenario ∈ travel/research/flights；goal 1–2000 字符）
两个 Key 的使用与报错	jev_ultrafast/model.py	L119 TypeSafe 请求（Bearer TYPESAFE_API_KEY）；L160–168 field_text()（TEXT_MODEL_API_KEY 必需、DeepSeek 默认端点、reasoning 三分支）
面板按钮与预填目标	jev_ultrafast/static/index.html	L33–36 场景下拉；L40–44 默认目标与 Start demo；L56–59 Choose next / Execute choice / Run automatically / Pause
.env 不进 git	.gitignore	第 1 行 .env；另忽略 .venv/、artifacts/
uv 安装与 sync 行为	uv 官方文档	docs.astral.sh/uv（Installation 的 curl/irm 命令；Locking and syncing 的定义与默认行为；.venv 位置见 Projects → Structure and files）