facetmark · 模型与配置

配置来源与优先级#

生效优先级如下。请从同一个工作目录启动命令和服务；工作目录中的 .env 也会参与读取。

优先级

环境变量   >   config.toml   >   内置默认值

设置屏会告诉你每个值来自这三者中的哪一个；如果是环境变量在压着它，那个输入框会变成只读并说明原因，而不是放你写一个根本不会生效的值。在浏览器里改会写进文件，永远不会去动你的环境变量。

文件在哪

facetmark config path

第一次有东西往里写的时候它才被创建。并不要求你必须有这个文件——没有文件、没有环境变量，全用默认值跑起来也是完全正常的一次运行。

有三项要重启才生效

embed_backend、embed_dim 和 local_embed_path 决定向量库的形状。这一屏会把它们存下来，然后明确告诉你要下次启动才生效。

连接模型#

配置项	人话
`api_key`	你的 key。存在文件里，回显给你看的是掩码，而且你保存别的字段时它不会被重新写一遍。
`base_url`	请求发到哪。任何说 OpenAI 那套 API 的都行，包括跑在你自己机器上的东西。
`chat_model`	建索引时生成网页摘要，使用“综述”时生成带引用的回答。
`embed_model`	把文字变成向量。决定搜索质量的是这一项。

换向量模型就要重建索引

两个不同模型出来的向量不可比。换了就跑一次重建，否则搜索会悄悄变差，而且没有任何报错会告诉你。

通过本机或 SSH 转发打开设置，填写模型字段后点击“测试连接”。测试使用表单中的值，但不会保存；分别确认对话与向量结果后，再点击该组的“保存”。每组保存只处理本组改动。标为需重启的字段保存后，要重启服务才会用于实际任务。

服务商配置示例#

官方文档核对日期：2026-10-03。先运行 facetmark config path 找到配置文件。请确认账户已开通所选模型，并先测试少量页面；以下型号更新未重新评测检索效果。

OpenAI

api_key = "sk-..."
base_url = "https://api.openai.com/v1"
chat_model = "gpt-6-luna"
chat_extra_body = "{\"reasoning_effort\":\"none\",\"max_completion_tokens\":4096}"
embed_model = "text-embedding-3-small"
embed_dim = 1536

Luna 适合批量提取；需要更强模型可选 gpt-6.1-sol（思考设为 low，不支持 none）。现有小型向量模型仍是当前型号。官方文档.

DeepSeek

api_key = "sk-..."
base_url = "https://api.deepseek.com/v1"
chat_model = "deepseek-flash"
chat_extra_body = "{\"thinking\":{\"type\":\"disabled\"},\"max_tokens\":4096}"
embed_backend = "local"
local_embed_path = "BAAI/bge-m3"
embed_model = "BAAI/bge-m3"
embed_dim = 1024

DeepSeek-V4.1-Flash 替换旧 deepseek-chat 示例。此配置搭配本地向量，先安装 facetmark[local]。官方文档.

Moonshot / Kimi

api_key = "sk-..."
base_url = "https://api.moonshot.cn/v1"
chat_model = "kimi-k3"
chat_extra_body = "{\"reasoning_effort\":\"low\",\"max_completion_tokens\":8192}"
embed_backend = "local"
local_embed_path = "BAAI/bge-m3"
embed_model = "BAAI/bge-m3"
embed_dim = 1024

moonshot-v1 已于 2026-08-31 下线。K3 始终思考：不传 temperature，使用 max_completion_tokens。本地向量需要 facetmark[local]。官方文档.

Zhipu / GLM

api_key = "..."
base_url = "https://open.bigmodel.cn/api/paas/v4"
chat_model = "glm-5.3-flash"
chat_extra_body = "{\"reasoning_effort\":\"low\",\"max_tokens\":8192}"
embed_model = "embedding-3"
embed_dim = 2048

5.3 Flash 是付费且始终思考的模型。免费对话可选 glm-4.7-flash，参数换成 {"thinking":{"type":"disabled"},"max_tokens":4096}。embedding-3 仍是当前向量型号，单独计费。官方文档.

SiliconFlow

api_key = "sk-..."
base_url = "https://api.siliconflow.cn/v1"
chat_model = "Qwen/Qwen3.6-27B"
chat_extra_body = "{\"enable_thinking\":false,\"max_tokens\":4096}"
embed_model = "Qwen/Qwen3-Embedding-0.6B"
embed_dim = 1024

采用当前中文官方指南确认的 Qwen 型号；服务商上架进度与 Qwen 官方发布不同。若用 Qwen/Qwen3-Embedding-8B 并保留 1024 维，还需设置 embed_send_dimensions = true。官方文档.

Aliyun Bailian

api_key = "sk-..."
base_url = "https://dashscope.aliyuncs.com/compatible-mode/v1"
chat_model = "qwen3.8-flash"
chat_extra_body = "{\"enable_thinking\":false,\"max_tokens\":4096}"
embed_model = "qwen3.7-text-embedding"
embed_dim = 1024
embed_batch_size = 20

原北京域名仍受支持，也可填写控制台提供的业务空间专属域名；Key 与地域需匹配。当前向量接口每批最多 20 条文本。官方文档.

Ollama

base_url = "http://127.0.0.1:11434/v1"
api_key = "ollama"
chat_model = "qwen3.8:27b"
chat_extra_body = "{\"reasoning_effort\":\"none\",\"max_tokens\":4096}"
embed_model = "qwen3-embedding:0.6b"
embed_dim = 1024

先用 ollama pull 下载两种模型。Qwen3.8 27B 约 18 GB；小内存可选 qwen3.5:4b 或 qwen3.5:9b。占位 Key 用于启用真实本地接口，避免进入演示模式。官方文档.

vLLM

base_url = "http://127.0.0.1:8000/v1"
api_key = "not-used"
chat_model = "Qwen/Qwen3.8-27B"
chat_extra_body = "{\"chat_template_kwargs\":{\"enable_thinking\":false},\"max_tokens\":4096}"
embed_backend = "local"
local_embed_path = "BAAI/bge-m3"
embed_model = "BAAI/bge-m3"
embed_dim = 1024

模型名必须与部署时的名称一致；启用鉴权时填写实际 Key。对话服务不会自动提供向量模型，本例使用 facetmark[local]。官方文档.

对话与在线向量共用接口地址

只有一组 base_url 与 api_key。DeepSeek、Kimi 或独立 vLLM 对话服务可搭配上面的本地向量配置。更换向量模型，即使维度不变，也需要重建向量索引。对话附加参数会用于所有备用模型，必须同时兼容。

使用本地向量#

先安装 python -m pip install "facetmark[local]"。模型文件首次需要下载，之后可在运行服务的机器上计算向量；网页抓取和已配置的在线对话模型仍会联网。

本地向量

embed_backend = "local"
local_embed_path = "BAAI/bge-m3"
embed_model = "BAAI/bge-m3"
embed_dim = 1024

建索引更慢，而且模型要先下载一次。搜索质量不错：在 1024 token 的窗口上，bge-m3 两次跑出来的向量自身余弦是 0.999976，而这正是一个「要长期留着而不是天天重建」的索引最需要的性质。

你放弃了什么

有两条路是建立在「让语言模型读一遍你的页面」上的：一个页面能回答的那些问题，以及主题标签。没有对话模型，这两块就是空的，你搜的是正文和全文检索——仍然是最强的两条路，也仍然比你浏览器给你的强。

你也可以先从这里开始，以后再加 key。什么都不用丢掉；索引会把之前建不出来的那部分补上。

并发、隐私与其他选项#

向量

配置项	人话
`embed_backend`	`api` 或 `local`。要重启生效。
`embed_dim`	每个向量多长。必须和模型实际返回的一致。要重启生效。
`local_embed_path`	本地后端用的模型 id 或目录。要重启生效。

它使多大劲

配置项	人话
`request_timeout`	多少秒之后放弃一次调用。网慢就调大；某家服务卡住就调小。
`fetch_concurrency`	同时下载几个页面。你的网络抗议的时候调小。
`enrich_concurrency`	同时往模型发几个页面。被限流的时候，要调小的是这一项。

不许它看的东西

配置项	人话
`privacy_excluded_domains`	永远不抓、永远不外发的域名。银行、健康、公司内网。书签还在，只有标题进索引。
`chat_model_fallbacks`	第一个模型不干的时候，按顺序往下试的那些。

首次抓取前设置排除名单

排除规则限制后续处理，不等于删除已经存下的正文或已有备份。先确认排除范围，再导入和建索引。

连接与保存问题#

报错	怎么办
`401` / `invalid_api_key`	key 不对，或者这个 `base_url` 配了另一家的 key。在设置屏上测一下——它会告诉你是哪一半挂了。
模型名报 `404`	这个端点上没有这个名字。去查服务商的模型列表。
`429`	被限流。把 `enrich_concurrency` 调小再跑一次；已经完成的阶段不会重做。
`dim mismatch`	`embed_dim` 和模型不一致。改对，重启，重建。
对话能用，向量 403	确认当前接口和账号支持所选向量模型。可改用同时支持两种能力的接口，或按上面的步骤配置本地向量；对话和在线向量共用接口地址。
保存时报 `unknown setting`	某个键名打错了。写入器会拒绝不认识的键，而不是存一个从此被永久忽略的东西。