命令与接口参考

安装#

Python 3.10 以上，Windows / macOS / Linux 都行。基础安装没有任何需要编译的机器学习依赖；向量检索来自 sqlite-vec，它是一个 SQLite 扩展。

pip install facetmark
# 或者用 uv：
uv pip install facetmark

facetmark version

带本地嵌入

只有你想在自己机器上算嵌入、而不走端点时才需要。它会拉 PyTorch 和 sentence-transformers，几百 MB。

pip install "facetmark[local]"

从源码装

git clone https://github.com/88lin/facetmark
cd facetmark
python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"

pytest -q                 # 1,700+ 个测试
ruff check src tests scripts

数据存在哪

一个目录，按平台选，里面一个 SQLite 文件。用 FACETMARK_DATA_DIR 换目录，或者用 --db 给单条命令指一个文件。

数据目录通常包含数据库、配对令牌及可选的配置文件。备份时分别保管数据库与密钥；路径以 facetmark stats 和 facetmark config path 的输出为准。

没 key 没网也能先试

facetmark demo 会造一个合成库，用确定性的离线 provider 建索引，然后跑三条搜索。首页那个终端就是这么录的。

facetmark demo --size 60

另见: 快速上手

把书签导进来#

导入是单向只读的。facetmark 读浏览器配置或者导出文件，两者都不写。

Chromium 系：不用导出

Chrome、Edge、Brave、Vivaldi、Chromium、Opera 和 Opera GX 都把书签放在一个 JSON 文件里，facetmark 能自己找到。浏览器开着也能安全读。

facetmark browsers        # 它能看到哪些
facetmark import          # 只有一个时直接导

装了多个配置时，它不猜 —— 导错人的书签比多敲一条命令糟糕得多。它会把候选列出来，你自己指：

facetmark import "$HOME/.config/google-chrome/Default/Bookmarks"

Firefox 和 Safari：先导出 HTML

facetmark import ~/Downloads/bookmarks.html

导入会报什么

同一条命令同时处理 Netscape HTML 和 Chrome JSON，并且报它干了什么，而不是转一个圈。在一份真实的 1.7 MB 导出上（96 个文件夹、四层嵌套）：解析 1,710 条，写入 1,701 条，合并 9 条重复，1 条不可索引。

另见: 快速上手

模型接入#

在线模型共用一个 OpenAI 兼容的 base_url 和 api_key。确认端点同时提供需要的对话与向量能力；兼容网关、自托管服务或本地向量后端可以补足服务商缺少的能力。

对话模型生成摘要、主题、实体、要点和候选问题；向量模型把页面文本与查询转换为向量。没有正文时，部分衍生内容可能依据标题生成。

走端点

export FACETMARK_API_KEY=sk-...
export FACETMARK_BASE_URL=https://api.openai.com/v1
export FACETMARK_CHAT_MODEL=gpt-6-luna
export FACETMARK_EMBED_MODEL=text-embedding-3-small
export FACETMARK_EMBED_DIM=1536

不想设环境变量，可以在运行目录放一个 .env。名字一样，前缀一样。

FACETMARK_API_KEY=sk-...
FACETMARK_BASE_URL=https://api.deepseek.com/v1
FACETMARK_CHAT_MODEL=deepseek-flash

共享端点或免费端点

备用对话模型按配置顺序尝试。请先确认每个模型在当前账户和端点可用；不要用备用链掩盖错误的接口地址或权限。

export FACETMARK_CHAT_MODEL_FALLBACKS=deepseek-flash,deepseek-v4-pro

provider 会记录每一次调用到底是哪个模型答的。任何建立在降级链上的报告，都必须把这个混合比例公开。

本地嵌入，不要 key

本地向量使用 sentence-transformers。首次下载模型后可在服务所在机器计算；网页抓取仍会联网。若保留在线对话配置，摘要与综述仍可能调用该服务。

pip install "facetmark[local]"

export FACETMARK_EMBED_BACKEND=local
export FACETMARK_EMBED_MODEL=bge-m3
export FACETMARK_EMBED_DIM=1024
export FACETMARK_LOCAL_EMBED_PATH=BAAI/bge-m3   # 或本地模型目录
export FACETMARK_LOCAL_EMBED_MAX_SEQ=1024

一个模型都不接

照装照跑。你保留两个词面、保存会话、域名与链接图、链接健康。你失去内容面和意图面。facetmark search --quick 是明确的纯词面路径，一次模型调用都不发。

另见: 模型与配置

建索引#

facetmark index

索引按阶段执行，并通过输入指纹复用已完成的工作。新增书签或正文、模型配置变化时，相应阶段需要更新；请查看实际任务输出。

常用参数

指纹是怎么算的

• 富化按正文哈希。正文没变，就不发第二次 chat 请求。
• 嵌入按重建后的嵌入文本，而不是按正文。所以富化变了、嵌入文本跟着变了，那个陈旧向量会被发现 —— karakeep 往返的损伤就是这么插出来的。
• 会话和边每次重建；它们便宜，而且依赖整个库。

facetmark reindex 把所有衍生产物丢掉，从书签本身重建。facetmark migrate 把旧库升到当前 schema，默认先快照一份，除非你加 --no-backup。

这一跑的代价

费用由文本长度、模型和服务商定价决定，建议先处理小样本。耗时还受网页抓取和站点限流影响；默认单主机并发为 2，并保留请求间隔。

给个量级感：刚才那个真实的 1,700 条书签库，用 --no-fetch 建索引，得到 322 个保存会话、9,132 条边、1,386 个域名、1,775 个向量。

另见: 快速上手

搜索#

facetmark search "那篇讲把向量存在 sqlite 里的"
facetmark search "sqlite-vec" -n 20 --explain
facetmark search "error EADDRINUSE" --quick

profile 和消融档

--config 接受任何预注册档、任何出厂 profile，以及大约 20 个探索性消融档。档位的定义在 search/pipeline.py 里。

排名是怎么构成的

选中的每个面各返回最多 CANDIDATES_PER_FACET 条候选。RRF 按 sum_f w_f / (k + rank_f) 合并，k = 60。然后按顺序跑上下文、衰减、重排；一跳图扩展作为单独一组返回 —— 不混进排名，因为当初测的就是它作为“补充”的效果，不是“替代”。

看一次保存会话

facetmark sessions -n 20     # 最近的保存会话
facetmark show 412 --body    # 一条书签的 JSON
facetmark stats              # 索引规模与覆盖率

查询语言#

所有检索入口用的是同一套语法：网页搜索框、facetmark search、/search 与 /quick、MCP 工具、karakeep 插件。它是一门过滤语言，不是第二个排序器——过滤器只决定哪些页面有资格，从不改动幸存页面的分数。完整参考：docs/query-language.md。

facetmark search "postgres domain:github.com -title:tutorial"
facetmark search "kafka added:<7d"          # 这周存的
facetmark search 'title:encryption (signal|matrix)'
facetmark search "tag:work sort:date"       # 一次浏览，按时间倒序

否定、短语、多选、通配

-facebook                    排除一个词
-domain:pinterest.com        排除整个站
"consumer group rebalancing"  精确短语
(security|privacy)           两个词任一
domain:(github.com|gitlab.com)   两个值任一
domain:*.github.io           * 是任意长度的一段字符

日期

写时长时比的是书签的年龄，所以 added:>90d 是「存了 90 天以上」。写绝对日期时直接比时间戳，所以 added:>=2026-04-01 是「那天及之后存的」。两者方向相反，因为对各自的写法来说，这都是唯一自然的读法。

排序，以及什么叫一次浏览

sort:date 最新在前，sort:-date 最旧在前；也支持 title、domain、url 和 opened。只有过滤器或排序指令、没有自由文本时，查询直接浏览书签，不调用模型。纯词面搜索和本地向量搜索也不产生在线向量费用。

你自己的标签

Netscape 与 pinboard 导出带着 TAGS 属性，现在它被保留下来：存在书签上、随每条命中返回、并且可以用 tag:work 查询。匹配的是列表里完整的一个元素，所以 tag:work 不会扩到 workshop；要匹配多个用 tag:(work|rust)。POST /bookmark 和 MCP 的 save_bookmark 也接受 tags；重复导入同一个文件时标签取并集而不是覆盖。

起服务：HTTP API 与配对令牌#

facetmark serve        # 127.0.0.1:8787

令牌

令牌首次运行时生成，保存在数据目录的 pairing-token.txt。请求可使用 Authorization: Bearer <token> 或 x-facetmark-token。不要把令牌放入公开链接或日志。

facetmark token             # 打印
facetmark token --rotate    # 作废旧的

TOKEN=$(facetmark token)

curl -s http://127.0.0.1:8787/health

curl -s -X POST http://127.0.0.1:8787/search \
  -H 'content-type: application/json' \
  -H "x-facetmark-token: $TOKEN" \
  -d '{"q":"vectors inside sqlite","limit":5}'

POST /search

全部路由

本地页面#

facetmark serve 同时提供 /app 应用和 HTTP API。页面包含搜索、综述、书签库、浏览批次与系统状态，设置从齿轮入口进入。

facetmark serve
# facetmark 2.0.0  http://127.0.0.1:8787
# open the search page:     http://127.0.0.1:8787/app
# pairing token written to the data directory
#   (facetmark config show lists the effective data_dir)

Python 包里的纯 HTML、CSS 和 ES 模块：没有 Node，没有打包器，也就没有会和服务端对不上的构建产物。页面和 API 由同一个进程发出，所以是同源的 —— 这也是它没法托管到别处去的原因：这个服务的 CORS 只对浏览器扩展的来源开放。

五个标签页与管理入口

结果行上的标记是什么意思

和扩展弹窗用的是同一套词。在页面里，每个标记鼠标悬停都有一行解释；这张表是为了让你一次看全。

第二组里每一行都带着走到它的那条边 —— 同一次浏览（同一次上网时存的）、语义相近、已被取代、同一页面、同一站点。这些名字背后的权重在配置表里。

页面怎么拿到令牌

它去问 GET /app/boot。这是唯一一条能把配对令牌交出去的路由，而且只在调用方和请求里写的地址两者都是回环地址时才交。在你自己机器上两条都成立，页面就自己配对好了，没有什么要复制的。

键盘

语言和主题

中英文和主题偏好保存在当前浏览器的当前站点。官网与应用使用同名偏好键，但不同域名的浏览器存储不会自动同步。界面尊重系统的减少动态效果设置。

另见: 应用使用指南

翻页：limit、offset 和 depth#

每个搜索入口都收 limit、offset 和 depth，而每个搜索响应报的是它实际给出的那个窗口，不是把你要的原样回显。

facetmark search "kafka rebalance" -n 20
facetmark search "kafka rebalance" -n 20 -o 20 --depth 60

只要还有下一页，CLI 就会把下一页的 --offset 和 --depth 打出来。走 HTTP 时，同样这三个字段放在 POST /search 的请求体里：

{
  "hits": [ ],
  "limit": 20,          // 实际给的，已经夹过
  "offset": 20,
  "depth": 60,          // 这次排名跑的深度
  "total": 137,         // 已经排过的条数；封顶时是下界
  "has_more": true,
  "depth_capped": false
}

为什么 depth 是个参数，而不是实现细节

页面大小决定一次展示多少条，检索深度决定候选池范围。下一页沿用响应中的 depth，可以在同一个候选池上继续读取，避免翻页时改变排名依据。

两个上限

MAX_PAGE_SIZE（200）限住一页。MAX_CANDIDATE_DEPTH（2000）限住它们背后的整个候选池，撞上它就是 depth_capped 被置上的原因。两个都在同一个地方、在任何查询开跑之前夹好，所以一个超大的请求不花什么代价，回给你的就是实际给出的那个窗口。

浏览器扩展#

Manifest V3，Chromium 系浏览器。它只和 127.0.0.1:8787 说话 —— 那就是它全部的必需主机权限。

1. 从发行页下载 facetmark-extension.zip 并解压。
2. 打开 chrome://extensions，开启开发者模式，选加载已解压的扩展，指向刚才那个目录。
3. 在终端跑 facetmark serve 并保持运行。
4. 跑 facetmark token，打开扩展的设置页，把令牌粘进去。
5. 按 Ctrl+Shift+K（macOS 是 Cmd+Shift+K）就能搜了。

它能干什么

设置项

另见: 连接工具与备份

MCP 服务器#

facetmark mcp 在 stdio 上跑一个 FastMCP 服务器，所以 Claude Desktop 这类 MCP 客户端可以搜你的库、读一次保存会话、存一个页面。

{
  "mcpServers": {
    "facetmark": {
      "command": "facetmark",
      "args": ["mcp"]
    }
  }
}

在 args 里加 "--db", "/path/to/facetmark.db" 可以指定库，加 "--mock" 可以没 key 先试。环境变量的读法和其他命令完全一样。

9 个工具

3 个资源

• bookmark://{id} —— 一条记录的 JSON。
• session://{id} —— 一次保存会话。
• facetmark://stats —— 索引规模与覆盖率。

另见: 连接工具与备份

karakeep 插件#

karakeep 是一个可自托管的书签管理器，搜索提供者可插拔。这个插件把 facetmark 接到它的搜索框后面：karakeep 管界面，facetmark 管检索。

1. 把插件拷进 karakeep 的插件包。
2. 在 exports 映射里注册它。
3. 在 meilisearch 之后加载，因为插件管理器发出去的是最后注册的那个提供者。
4. 把它指向一个在跑的 facetmark 服务。

cp -r integrations/karakeep/search-facetmark \
  /path/to/karakeep/packages/plugins/search-facetmark

// packages/plugins/package.json — exports 映射
"./search-facetmark": "./search-facetmark/index.ts"

// packages/shared-server/src/plugins.ts 的 loadAllPlugins()
await import("@karakeep/plugins/search-meilisearch");
await import("@karakeep/plugins/search-facetmark");  // 必须在后面

export FACETMARK_URL=http://127.0.0.1:8787
export FACETMARK_TOKEN=$(facetmark token)
facetmark serve

协议是怎么钉住的

• karakeep 上游的类型按 blob SHA 钉在 integrations/karakeep/typecheck/upstream-pins.json，CI 会对着它跑 tsc --noEmit。
• 报文格式存在 integrations/karakeep/contract/wire.json，由 tests/test_karakeep_contract.py 回放。
• 这个回放测试真的接住了一个：只有一条命中时的 offset 1，正确答案是 hits: [] 配 totalHits: 1。空的 hits 不等于没有结果。

想卸掉这座桥，把 karakeep_doc 表 drop 了就行。enrichment.source_hash == 'karakeep' 是保留值，意思是这行桥可以覆写；其他任何值都意味着是真模型写的，桥不碰。

另见: 连接工具与备份

数据库里有什么#

一个 SQLite 文件。任何 SQLite 工具都能打开，不加密、不混淆、不私有。就算你不用 facetmark 了，数据也还读得出来。

链接健康与冷层

facetmark health                       # 已知的
facetmark health --check               # 真的去探网络
facetmark health --check --no-save-recovered   # 只读扫描

扫描可以用 DNS-over-HTTPS、Wayback 可用性 API 和一个阅读代理，来区分「页面没了」和「你 DNS 坏了」。在拿这个库做任何测量之前，请加 --no-save-recovered，让扫描除了健康日志之外保持只读。

全部配置项#

作为环境变量时，每个名字前面加 FACETMARK_；放在 .env 里也一样。下面的默认值就是出厂值。

存储

模型接入

本地嵌入

抓取

富化与意图

会话、检索与衰减

链接健康与服务

另见: 模型与配置

全部命令#

使用 facetmark COMMAND --help 查看每条命令支持的参数。数据库相关命令通常支持 --db，许多命令提供 --json 便于脚本处理。

跑你自己的评测

评测命令接受包含 {text, qtype, target_url} 的 JSONL 查询集，在指定书签库上比较检索配置，并输出置信区间与配对检验。先固定数据集和协议，再解释结果。

facetmark eval --no-build \
  --queries my-queries.jsonl \
  --rungs A,C,full \
  --bootstrap 10000 --concurrency 4 \
  --out report.json

另见: 连接工具与备份

排错#

每次模型调用都返回 404

核对服务商要求的完整 base URL，包括路径前缀（常见为 /v1），并确认模型名称可用。404 可能来自地址或模型名，不能单凭它判断 API Key 无效。

建索引或搜索时报「维度不匹配」

数据库记录的向量维度与 FACETMARK_EMBED_DIM 不一致。先确认模型的实际输出维度，修正配置并重启服务，再重建索引。修改前保留数据库备份。

富化静悄悄地什么也没做

存着的 source_hash 已经等于当前正文哈希，指纹认为活干完了。这是正确行为，facetmark index --force 可以覆盖它。

向量有，但结果很差

通常是向量写完之后嵌入文本又变了 —— 比如富化被一座桥覆写了。用 facetmark index --force 重算。如果是一个全新的索引就差，先确认自己是不是不小心跑在 mock provider 上：facetmark stats 会报当前用的嵌入模型。

SQLite 报 disk I/O error

SQLite 在某些网络文件系统和 FUSE 上跑不稳。用 FACETMARK_DATA_DIR 把数据目录换到本地磁盘。

抓得很慢，或者页面是空的

两个通常都是故意的。遵守 robots.txt，单主机并发封顶 2，两次请求之间还有最小间隔。有些站就是不给。没正文的页面照样建索引 —— 管线会退到只用标题的指纹 —— 只是弱一些。想要快而浅的索引，用 --no-fetch。

扩展连不上服务

按顺序查三件事：facetmark serve 真的在跑吗；设置里的 endpoint 和它实际监听的主机端口对得上吗；设置里的令牌和 facetmark token 一致吗。轮换过令牌的话，扩展要拿新的。

其他

facetmark stats 和 facetmark health 会把索引里到底有什么打出来，大部分困惑到这就解了。实在不行就提个 issue —— 最有用的是把出错那条命令的 --json 输出贴上来。

另见: 快速上手