使用指南

01安装

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,514 个测试
ruff check src tests scripts

数据存在哪

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

里面是 facetmark.db 和 pairing-token.txt。全部安装足迹就这么多，删目录等于卸数据。

没 key 没网也能先试

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

facetmark demo --size 60

02把书签导进来

导入是单向只读的。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 条不可索引。

03模型接入

facetmark 只通过一个 OpenAI 兼容端点访问模型。代码里故意没有任何针对具体厂商的分支：一个 base_url 加一个 api_key 就覆盖 OpenAI、DeepSeek、Kimi、智谱、硅基流动、阿里百炼、together.ai、Azure OpenAI、Ollama、vLLM、LM Studio，以及任何说同一套协议的内部网关。

用到两个角色。chat 模型写富化（摘要、主题、实体、要点）和候选意图查询。嵌入模型把页面正文变成向量。

走端点

export FACETMARK_API_KEY=sk-...
export FACETMARK_BASE_URL=https://api.openai.com/v1
export FACETMARK_CHAT_MODEL=gpt-4o-mini
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-chat

共享端点或免费端点

如果端点上一个列出来的模型可能根本不在、可能欠费、也可能不支持 response_format，那就配一条降级链。默认为空是故意的：付费端点报错是在告诉你事情，吠掉它比失败更糟。

export FACETMARK_CHAT_MODEL_FALLBACKS=deepseek-chat,qwen-plus

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

本地嵌入，不要 key

用 sentence-transformers 在你自己机器上跑嵌入模型。再把 API key 留空，除了抓页面之外就什么都不出去了。

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=/path/to/bge-m3   # 不设就下载
export FACETMARK_LOCAL_EMBED_MAX_SEQ=1024

一个模型都不接

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

04建索引

facetmark index

一条命令按顺序跑完所有阶段。每个阶段都幂等且带指纹，所以新增 50 条书签后再跑，它只做这 50 条的活，不是整个库。

常用参数

指纹是怎么算的

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

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

这一跑的代价

钱主要在富化：大致每页一次小的 chat 调用，所以 1,700 页的库用便宜模型是几毛钱。壁钟时间主要在抓页面，而抓页面是故意慢的 —— FETCH_PER_HOST_CONCURRENCY 是 2，同一主机两次请求之间还有最小间隔。

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

05搜索

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              # 索引规模与覆盖率

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

facetmark serve        # 127.0.0.1:8787

令牌

首次运行时生成，写在数据目录的 pairing-token.txt 里。请求时放在 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

全部路由

07本地页面

facetmark serve 同时还托管着一个搜索页。它是唯一一个除了 facetmark 本身什么都不用装的入口 —— 不用加载浏览器扩展，不用配编辑器，也不用 curl。

facetmark serve
# facetmark 1.6.1  http://127.0.0.1:8787
# open the search page:     http://127.0.0.1:8787/app
# pairing token written to: ~/.facetmark/pairing-token.txt

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

两个视图

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

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

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

页面怎么拿到令牌

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

键盘

语言和主题

中英文，顶栏切换，下次记得。没存过选择时跟随浏览器语言。主题开关在 跟随系统 → 浅色 → 深色 之间循环，而且和本站共用同一个存储键，所以在这里选了深色的人，那边也是深色。所有动效都包在 prefers-reduced-motion 查询里。

08翻页：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 是个参数，而不是实现细节

以前页大小和检索深度是同一个数：要更多条就会悄悄检索得更深，而第 51 条在任何页大小下都够不着，因为候选池不管怎样都是 50 条。现在，页是一个窗口，看的是一个你能看见、也能钉住的候选池。

两个上限

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

09浏览器扩展

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）就能搜了。

它能干什么

设置项

10MCP 服务器

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 —— 索引规模与覆盖率。

11karakeep 插件

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' 是保留值，意思是这行桥可以覆写；其他任何值都意味着是真模型写的，桥不碰。

12数据库里有什么

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

链接健康与冷层

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

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

13全部配置项

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

存储

模型接入

本地嵌入

抓取

富化与意图

会话、检索与衰减

链接健康与服务

14全部命令

每条命令都有 --db，可以指向具体的数据库文件或数据目录。大部分都支持 --json。

跑你自己的评测

这是 facetmark 最重要、也是至今没有第二个人用过的部分。给它一个 {text, qtype, target_url} 的 JSONL，它就能在你自己的库上跑任意一组档位，给出 bootstrap 置信区间和配对差异的 McNemar 检验。

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

15排错

每次模型调用都返回 404

base URL 漏了 /v1。这是差距很大的第一名配置失败，而且错误以 provider error 的形式冒出来，看起来很像密钥不对。

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

第一次建库时记在 meta 里的嵌入维度，和当前的 FACETMARK_EMBED_DIM 对不上了。facetmark 宁可报错也不混维度。要么改回去，要么用 facetmark index --force 重算全部向量。

富化静悄悄地什么也没做

存着的 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 输出贴上来。