jevreel

jevreel

使用 Jev 实现零嵌入的视频智能方案。

jevreel 会将视频排布在带标签的联系表中，每秒一帧，每张图片包含 60 帧，并让 Jev——TypeSafe 的快速决策模型——并行评判每张表。然后，它会在完整画面上重新检查最佳片段。你的 Agent（Claude Code、Codex、Cursor、Claude Desktop，以及任何支持 MCP 的工具）会收到片段、时间点和概率，随后自行仔细查看。整个过程中不会计算或存储任何向量。

看看它如何运作

以下是 5 次未经编辑的 Claude Code 会话，它们使用 jevreel MCP 服务和技能，检索 Blender 开源电影 Tears of Steel（12:14，(CC) Blender Foundation， CC BY 3.0）。每个片段都取自会话录制内容：Agent 的工具调用、Jev 对每张表和每一帧的回答、命中结果、成本，以及 Agent 给出的原话。点击片段可查看全分辨率视频。

	提问	结果	Jev
1	有人从果汁盒里喝东西的片段吗？	筛查了 13 张表，在完整画面上验证了 6 个片段，保留 2 个：2:28.5（p 0.95）和 12:06.5（0.86）	19 次请求，$0.0054
2	Thom 什么时候向 Celia 道歉？他说了什么？	对字幕使用语音模式：6:47 "I'm sorry."（0.85）；Agent 将 5:02 脱口而出的 "Sorry!" 搁置	10 次请求，$0.0003
3	一开始有人在看报纸。头条写了什么？	只检索前 5 分钟：在 1:20.5（0.94）确认；Agent 从画面中读出 ROBOTICIST CREATES KILLER ROBOTS	8 次请求，$0.0024
4	captain.jpg 中的人物在哪些场景出现过？列出所有场景。	按照片搜索：找到 8 个片段，6 个以 0.86–0.97 的概率通过验证，另有 2 个由 Agent 使用 zoom 确认	19 次请求，$0.0064
5	梳理这部电影：机器人、枪支、全息影像、场景，以及电影类型。	Agent 自己设计了一个包含 4 个问题的检索视角，免费读取了逐分钟结果行，并询问了一个关于整部电影的问题	14 次请求，$0.0051

1. 找到一个三秒片段

2. 搜索对话

3. 读取画面中的文字

4. 根据照片查找人物

参考照片是 9:18 画面的裁剪图，因此 9:17 的命中是其自身来源；其余七个是搜索结果。

5. 绘制整部影片的地图

会话以两次失败的调用开场，并保留了下来：先是录制不允许执行的 shell 命令，然后是错误的文件夹。错误信息指出相对路径所依据的文件夹，接下来的调用便成功了。

为什么使用决策模型，而不是嵌入模型

多模态嵌入模型已经能很好地搜索视频：EmbeddingGemma 2（2026 年 10 月）将文本、图像、视频帧和音频置于同一个向量空间中，并可在手机上运行。jevreel 通过另一条路径实现同一目标，取舍也有所不同。

• 依据你的问题，而不是固定的“相似”定义。 嵌入索引在建立索引时就决定了哪些内容算接近。决策模型则会根据你此刻提出的问题进行判断，并返回一个概率，供你的代码设置阈值、排序和筛选。
• 低成本处理每一秒。 Jev 只对输入令牌收费，输出免费。联系表只发送一次，之后关于它的每个问题都会一并随同请求发送，因此 jevreel 可以按每秒一帧筛查整段视频，而不是只看少数关键帧。
• 提问几乎免费，所以可以多问。 镜头分析可将你自己的类型化问题添加到每一分钟中，几乎无需额外成本；之后你可以随意筛选，不收取费用。
• 只有通过筛选的内容才会交给昂贵的模型。 你的 Agent 会得到少数关键时刻的全分辨率画面，而不是一堆缩略图。
• 提供类型化答案，而不只是排序结果。 可按分钟或针对整段视频，返回是／否及事件发生的秒数、选项之一，或你所设定量表上的等级。

对于反复查询大型资料库，嵌入模型更合适：向量生成后，每次搜索都只是一次无需成本的查找；而 jevreel 的每次提问都会按筛查的分钟数向 Jev 付费（每小时视频约 $0.02–0.03）。两者也很适合搭配使用：先用嵌入模型筛选出候选视频，再用 jevreel 查找、核实并描述相关时刻。

工作原理

flowchart LR
    V[video file or URL] --> F["ffmpeg: 1 frame/s"]
    F --> S["contact sheets<br/>60 labelled tiles, 1 minute each"]
    V --> T["captions, or local<br/>speech-to-text"]
    S --> J{{"screen: one Jev request<br/>per sheet, in parallel"}}
    T --> J
    J --> R["verify: top-ranked windows<br/>re-checked on full frames,<br/>every 0.5 s around the pick"]
    R --> H["hits: time, probability,<br/>frame, nearby speech"]
    H --> A["your agent: zoom, locate,<br/>read, cite 12:04"]

1. 建立索引。 以 1 fps 的频率采样视频，并将帧平铺到 1568 px 的联系表上，每个图块标记为 T01、T02 等。获取字幕，或在本地转录。向每张联系表各提问一次固定问题集（人物、屏幕文字、剪辑、场景、活动、代表性帧），再加上你添加的任何视角，从而生成带类型的时间线。
2. 筛查。 每张联系表发送一个请求：用 Noul 判断“是否在这一分钟内”，再用 Choice 从图块 ID 中选择“是哪一秒”。筛查和语音是分开的问题，由代码合并。
3. 验证。 按排名（而非阈值）选出排名靠前的时间段，每隔半秒检查一次所选时间点附近的完整帧，每帧提一个是非问题。即使筛查无法确认，也能正确地为一秒长的事件排序；验证会确认事件，或排除错误线索。
4. 仔细查看。 zoom 重新渲染全分辨率帧；locate 在一帧中用 Box 定位目标并裁剪；whole 则根据故事板、时间线和转录内容回答一个关于整段视频的问题。

答案会缓存：相同图像和问题发送给同一模型，不会重复计费。

这遵循 TypeSafe 自身的模式。他们的行搜索指南将对已标注单元的 Choice 与“是否存在”的 Noul 配对。他们的图像指南通过对图块进行 Choice 来搜索大型图像，并且只在需要时进一步查看。他们的 Box 指南要求每个框都先通过 Noul 筛选，并检查其边缘。

快速入门

你需要 Python 3.11+、PATH 中的 FFmpeg，以及一个 TypeSafe API 密钥。

uv tool install "jevreel[all]"
export TYPESAFE_API_KEY=...

jevreel index talk.mp4                       # prints the video id
jevreel ask talk "a slide with a bar chart"  # id, id prefix, path or title all work
jevreel zoom talk 12:00 12:10                # full-resolution frames to look at

[all] 会添加 URL 支持（yt-dlp）和本地语音转文本功能（faster-whisper）。没有这些功能时，jevreel 会为本地文件建立索引，并使用保存在视频旁边的 .srt 或 .vtt 字幕。

视角：在每一分钟提出自己的问题

视角是一组针对每张联系表提出、并作为时间线列保留的类型化问题。问题可以是 noul（是非题，并给出事件发生的秒数）、choice（从选项中选择一个）或 score（按等级评分，最低等级排在最前）。

# examples/lenses/driving.toml
name = "driving"

[[questions]]
name = "on_bridge"
type = "noul"
ask = "Is the car driving on a bridge?"

[[questions]]
name = "weather"
type = "choice"
ask = "What is the weather mostly like?"
options = ["clear", "cloudy", "rain", "snow", "fog"]

[[questions]]
name = "traffic"
type = "score"
ask = "How much other traffic is on the road?"
levels = ["None", "Light", "Moderate", "Heavy"]

jevreel index drive.mp4 --lens driving.toml     # rides in the indexing requests: almost free
jevreel lens drive driving.toml                 # or run it later: one request per minute of video
jevreel query drive "on_bridge > 0.7"           # filter as often as you like: no requests
jevreel query drive "weather == snow and traffic >= 2"

在 Agent 中使用

MCP 服务提供十种工具。技能会教 Agent 遵循工作流：提问、在作出任何断言前先查看，并引用时间点。

作为插件

该插件捆绑了 MCP 服务和技能。它通过 uvx --from "jevreel[url]==0.2.0" 启动服务，因此你需要 uv 和 PATH 中的 FFmpeg。为加快首次启动，插件未包含本地语音转文本功能；如需使用该功能，请按照下文所示，手动使用 jevreel[all] 添加服务。

启用插件时，Claude Code 会要求你提供 TypeSafe API 密钥，并将其保存在系统的凭据存储区中：

claude plugin marketplace add DeepAleph/jevreel
claude plugin install jevreel@jevreel

Codex 只会向插件服务传递环境变量白名单，因此请先保存密钥。相同的命令也会安装插件启动所需的环境，让插件首次启动更快：

uvx --from "jevreel[url]==0.2.0" jevreel login
codex plugin marketplace add DeepAleph/jevreel
codex plugin add jevreel@jevreel

手动配置

Claude Code

claude mcp add jevreel -e TYPESAFE_API_KEY=your-key -- uvx --from "jevreel[all]" jevreel mcp

Codex

codex mcp add jevreel --env TYPESAFE_API_KEY=your-key -- uvx --from "jevreel[all]" jevreel mcp

Claude Desktop、Cursor 和其他 mcpServers 客户端

{
  "mcpServers": {
    "jevreel": {
      "command": "uvx",
      "args": ["--from", "jevreel[all]", "jevreel", "mcp"],
      "env": { "TYPESAFE_API_KEY": "your-key" }
    }
  }
}

VS Code 使用 "servers" 下的相同条目，并设置 "type": "stdio"。

技能（Claude Code、Codex 和其他可读取 Agent Skills 的 Agent）：

npx skills add DeepAleph/jevreel

没有 MCP 的 Agent 可以只通过 CLI 使用技能；每条命令都会输出 JSON。

工具

MCP 工具	CLI	功能
index_video	jevreel index	创建分镜表、转录文本、带类型的时间线和任意镜头。作为 MCP 后台任务运行；重复调用会返回索引，并且只运行新的镜头。
ask_video	jevreel ask	查找与描述匹配的片段：经过筛选，并在完整帧上验证，同时提供时间、概率、附近的语音内容和帧图像。mode：visual、speech、both。
find_in_video	jevreel find	查找参考照片中的主体出现过的所有片段。
locate_in_frame	jevreel locate	在一张完整分辨率帧中框选并裁剪目标。
zoom_video	jevreel zoom	获取两个时间点之间均匀分布的完整分辨率帧。
video_transcript	jevreel transcript	获取两个时间点之间说的话。
ask_whole_video	jevreel whole	针对整个视频生成一个带类型的回答（是/否、选项或评分）。
run_lens	jevreel lens	针对已索引视频的每一分钟，提出你自己的带类型问题。
query_timeline	jevreel query	筛选时间线（默认回答和镜头）。不会发送请求。
list_videos	jevreel list	列出这台机器上已索引的视频。

jevreel measure <video> 会报告在你的账户上以多种网格尺寸生成一张联系表的费用。

Python

import asyncio

from jevreel import Reel


async def main() -> None:
    async with Reel() as reel:
        video = await reel.index("talk.mp4")
        result = await reel.ask(video.id, "a slide with a bar chart")
        for hit in result.hits:
            print(hit.time, hit.probability, hit.frame)
        print(reel.query(video.id, "text_on_screen > 0.8").rows)


asyncio.run(main())

配置

变量	默认值	含义
TYPESAFE_API_KEY	（Jev 必需）	你的 TypeSafe 密钥。不带时间线的索引、缩放、转录和查询无需此密钥。
JEVREEL_HOME	用户缓存文件夹	已索引的视频、联系表、帧和回答缓存的存放位置。运行 jevreel home 可查看。
JEVREEL_MODEL	jev-1.14.0	有意固定此版本：Box 和图像图块需要 1.14，而别名会变动。
JEVREEL_FPS	1	采样到联系表上的帧率（最高为 5）。
JEVREEL_TILES_PER_SHEET	60	每张联系表的帧数。数量越少，图块越大，请求越多。
JEVREEL_VERIFY_TOP	6	每次提问时，在完整帧上验证的排名靠前窗口数量；设为 0 可关闭验证。
JEVREEL_CACHE	1	设为 0 可始终重新向 Jev 提问。
JEVREEL_CONCURRENCY	16	并行 Jev 请求数。速率限制按 TypeSafe 账户计算。
JEVREEL_ASR_MODEL	small	用于无字幕视频的 faster-whisper 模型。
JEVREEL_CAPTION_LANGUAGES	en,en-orig,en.*	按顺序为 URL 获取的字幕语言。

费用

在 2026-10-15 使用 jev-1.14.0 测得，输入令牌价格为每百万个 $0.042，视频为 10 分钟、1080p：

	请求数	输入令牌	费用
一张完整联系表（网格从 4×7 到 8×14 均可）	1	约 6,000	$0.00025
索引（11 张联系表，每张包含 8 个默认问题，耗时 14 秒）	11	78,000	$0.0033
一个包含 5 个问题的镜头，在索引后运行	11	84,000	$0.0035
一次 ask，经过筛选和验证	13–15	97,000–115,000	$0.004–0.005
再次运行同一 ask	0	0	$0（缓存）
locate（Box 加边缘检查）	2	5,000	$0.0002
whole（一次故事板请求）	1	7,600	$0.0003

对一小时视频提问一个问题，费用约为 $0.02–0.03。在索引时提出的问题会与默认问题一起处理，这就是“几乎免费”的原因：包含 8 个问题的请求与包含 2 个问题的请求费用差不多。TypeSafe 尚未公布图像令牌数量。这些数字来自 API 的报告。运行 jevreel measure 查看你自己的费用。

在真实视频上测得

一段 10 分钟、1080p 的游戏实录，没有语音，所有结果均已逐帧手动核对：

查询	结果
"the game's pause menu is open"	三次出现均被找到，每次都不到一秒：0:08.5、2:19.5、10:12.5（p 0.99–1.00）。仅筛选时的得分分别为 0.36、0.50、0.95。验证前，三次中有两次被漏掉。
"the full-screen city map is shown"	0:10 和 2:21，都是地图画面。没有误报。
"the car drives across a big steel truss bridge"	2:07 和 5:05.5，都是实际驶过桥梁的画面。
Lens driving：query "on_bridge > 0.7"	恰好是驶过桥梁的两分钟片段，时间为 2:14 和 5:02。
Lens driving：query "menu_open > 0.7"	恰好是出现菜单的三分钟片段。
locate "the location name caption"，时间为 5:02	已框选并裁剪；裁剪图中可读到 "Fathers Bridge"。
whole "What is this video mostly?"	"a driving sequence in a video game"，0.98。

局限

• 短暂事件需要筛选步骤来确定其所在片段的排名。 验证每半秒检查一次，但只检查排名最高的片段（默认 6 个）。如果筛选排名低于此范围，就不会检查该事件。提高 JEVREEL_VERIFY_TOP 的值，或降低 JEVREEL_TILES_PER_SHEET 的值以使用更大的图块。
• 除语音外，不处理其他声音。 音频仅以转录文本的形式传给 Jev。
• Jev 的图像支持仍处于实验阶段。 TypeSafe 将图像和 Box 调用称为“适用于梦创者”，而非可用于生产环境，并表示限制和准确度可能随版本变化。
• Jev 实际要求的图像最小尺寸为每边 280 px。 文档称为 256，但 API 会拒绝小于 280 的图像（测量日期：2026-10-15）。jevreel 会自行填充每张图像。
• 需要针对你的素材调整阈值。 0.5 用于报告、0.7 用于标记“强匹配”，这是遵循 TypeSafe 的示例设置。在测试视频上效果不错，但测试素材只有一个视频。

贡献

欢迎提交问题和拉取请求。请参阅 CONTRIBUTING.md。编码 Agent 应阅读 AGENTS.md。

许可证

MIT。jevreel 是独立项目，与 TypeSafe AI 无关。Jev 是 TypeSafe 的模型，通过其公开 API 使用，并受 TypeSafe 条款约束。