serviette 0.1.8 配置参数详解

目标：逐项讲清 serviette 0.1.8 的 YAML 配置体系——参数查看与修改方式、全部配置段的字段/类型/默认值、一份可直接落地的生产配置模板，以及配置校验报错的真实排障。参数含义与默认值溯源自官方 docs/README.md 配置参考（查询日期 2026-10-22），配置示例与校验回显均在 Ubuntu 22.04.5 LTS 上用 serviette 0.1.8 实测通过。

一、环境信息

本文实测与溯源环境：

• 操作系统：Ubuntu 22.04.5 LTS（x86_64），root 用户；
• serviette：0.1.8（PyPI，2026-10-15 发布），底座 pathway 0.33.0，Python 3.10.12（venv /opt/serviette-venv）；
• 实验工作目录：/root/serviette-demo/（配置文件、语料目录 docs/、DuckDB 库文件、serviette-workdir/ 工作目录均在此）；
• 参数来源：官方 docs/README.md 第 4 节 Config reference（https://github.com/pathwaycom/serviette/blob/main/docs/README.md ，查询日期 2026-10-22）+ 实测向导生成的配置文件 + 实测启动校验回显；
• 约定：下文「官方默认值」均指官方配置参考标注的默认；「实测」指在上述环境跑出的真实结果。

二、前置条件

• 已按《Ubuntu 22.04 安装 serviette 0.1.8 指南》完成安装，serviette --version 返回 serviette 0.1.8；
• 已领取免费 Pathway 许可证（indexer 运行必需；仅编辑/校验配置不需要）；
• 会用到哪个向量库，就具备哪个库的连接条件（DuckDB 无需任何外部服务，本文实测用它）。

验证安装（实测回显）：

serviette --version

serviette 0.1.8

三、参数查看与修改方式

3.1 配置文件：一份 YAML 管两进程

serviette 的全部参数集中在一个 YAML 文件里。可以一份「universal」配置同时喂给 indexer 和 server（本文采用），也可以拆成 indexer-only / server-only 两份。用哪个文件由命令行 --config 指定，没有隐式默认路径。

3.2 三种生成/修改方式

方式一：向导生成（推荐起步）。serviette wizard 交互式提问，DuckDB+本地嵌入的「快乐路径」只问 7 个问题，其余参数写文档化的静默默认值。完整实测流程见《serviette 0.1.8 常用 CLI 命令与工具详解》向导一节；实测生成的配置全文如下（原样照抄，本文后续章节以它为解剖样本）：

# serviette config — generated by `serviette wizard`
pathway_license_key: ${PATHWAY_LICENSE_KEY}
sources:
- type: fs
  path: /root/serviette-demo/docs
  glob: '**/*'
vector_db:
  type: duckdb
  path: ./embeddings.duckdb
  table: embeddings
embedder:
  type: sentence_transformer
  model: sentence-transformers/all-MiniLM-L6-v2
splitter:
  type: token_count
  chunk_size: 512
  chunk_overlap: 50
server:
  host: 127.0.0.1
  port: 8989
llm:
  type: mock

方式二：手写配置。从空文件按第四章参数总览逐段写（本文 5.x 各节的手写样本均实测通过预检）。

方式三：环境变量插值。任何字符串值都支持 ${ENV_VAR}，凭据不落盘。实测确认两个行为：① 变量未导出时启动立即报错并精确点名（真实回显见第八章 Q1）；② 向导检测到环境里已导出 PATHWAY_LICENSE_KEY 时，会主动在配置里写 ${PATHWAY_LICENSE_KEY} 引用而非让你粘贴明文（实测生成文件即如此）。

3.3 配置校验：启动即检错

indexer/server/up 启动前会做「常识级」预检：源目录是否存在、${VAR} 是否已导出、openai 型 embedder/llm 是否缺 key、后端能否被两进程共享，每项报错都是一段话而非 traceback（本文第八章收录全部实测报错原文）。改配置后无需专门校验命令——直接跑一次目标子命令，预检通过即会进入下一步。

四、参数总览

按配置段归类的全景表（字段、类型、默认值均溯源自官方配置参考，2026-10-22）：

💡 说明：官方配置参考中 embedder.type 的「provider default」指跟随所选提供商的默认模型；实测向导为 sentence_transformer 家族写入的是 sentence-transformers/all-MiniLM-L6-v2。

五、核心参数分类详解

5.1 pathway_license_key：许可证

类型 str，默认无。免费 Pathway 许可证，值可以是明文或 ${PATHWAY_LICENSE_KEY} 引用。官方明确：许可证在索引图初始化时校验。实测用哑值启动 indexer 的报错（原文）：

RuntimeError: the feature(s) you used ["DUCKDB"] require a Pathway license key, which is free.
Get one in seconds (sign up with GitHub or LinkedIn) at https://pathway.com/framework/get-license, then set the PATHWAY_LICENSE_KEY environment variable.

报错里会列出用到的特性名（如 ["DUCKDB"]），便于确认是哪个能力触发了校验。推荐写法即向导生成的引用式：pathway_license_key: ${PATHWAY_LICENSE_KEY}，密钥经环境变量注入。

5.2 sources：文档来源

列表类型，必填。每个元素是一个来源，type 可选 fs/gdrive/s3/sharepoint/pyfilesystem（默认 fs），多类型可混用。

通用字段：

fs（本地目录，实测默认路径）：

实测样本（向导生成）：

sources:
- type: fs
  path: /root/serviette-demo/docs
  glob: '**/*'

gdrive：object_id（必填，Drive 文件夹/文件 id）、service_user_credentials_file（必填，服务账号 JSON 路径）、file_name_pattern（可选 glob）、object_size_limit（可选字节上限）。装 serviette[gdrive]。

s3 / MinIO：bucket（必填）、path（键前缀，默认 "" 全桶）、access_key/secret_access_key（缺省走 AWS 凭据链）、region/endpoint（自定义端点接 MinIO 等）、with_path_style（bool，默认 false；MinIO 等自托管对象存储需设 true）。装 serviette[s3]。

sharepoint：url/tenant/client_id/cert_path/thumbprint/root_path（均必填，证书认证）、recursive（默认 true）、refresh_interval（秒，默认 30）。⚠️ 需要 Pathway Scale 许可，装 serviette[sharepoint]。

pyfilesystem：fs_url（必填，任意 PyFilesystem URL：ftp://…、ssh://…、webdav://…、zip://…）、path（默认 "" 递归）、refresh_interval（秒，默认 30.0）。装 serviette[pyfilesystem]，部分协议需额外驱动包（fs.sshfs、fs.webdavfs）。

5.3 parser：解析路由

规则列表，默认「无 API key 的解析器优先」。每条规则形如 {match: ["*.pdf"], type: docling, options: {...}}，glob 同时对文件名与其路径匹配（* 能匹配 /，可用 */scans/*.png 选中目录），首条命中生效，未命中的走内置默认路由：

可用 type：utf8、pypdf、docling、unstructured、paddle_ocr、vision_image、vision_slide、whisper、twelvelabs_video、skip。缺 key 的模态跳过并告警，不崩溃。⚠️ 解析路由变更受「配置指纹」保护（见 5.6 节），改动会触发重建索引确认。

5.4 vector_db：向量库后端（8 选 1）

type 必填，可选 duckdb/pgvector/milvus/qdrant/chroma/weaviate/pinecone/mongodb。启动时 indexer 自动建库建表建索引（prepare_backend），向量维度取 vector_db.embedding_dimension（设置了的话）或内省 embedder。

各后端连接字段与默认值：

DuckDB 并发语义（官方文档明示）：单文件单写者；indexer 借 detach_between_batches 在批间释放文件锁，server 以短连接只读查询并发工作。请求撞上批提交时等待锁（最长 30 秒；大语料首轮提交可持锁约 10 秒），超时返回 503「索引更新中，请稍后再试」。实测确认空库时 server 正常应答：

curl -s http://127.0.0.1:8989/api/v1/stats

{"backend":"duckdb","stats_available":false}

💡 技术拓展：vector_db 还有一个进阶键 embedding_dimension（int，未在向导中出现）——DBA 手工建 schema 时用它显式指定向量维度；不设则由 embedder 内省得出。若想启用混合检索，在此段加 hybrid: true（BM25+向量倒数秩融合，进程内关键词索引，默认每 30 秒随库刷新，hybrid_max_chunks 以上自动跳过关键词路）——Pinecone 除外。

5.5 embedder 与 splitter

embedder（indexer 与 server 共用一节）：

⚠️ indexer 与 server 必须用同一模型，否则向量不可比。换嵌入模型 = 全量重建索引（指纹校验拦截）。

本地模型怎么选（官方指引原文义）：默认 all-MiniLM-L6-v2 是纯英文模型——中文/法语/德语等语料会检索退化成「上下文不含信息」。非英文或混合语料改用 intfloat/multilingual-e5-small（约 100 种语言，同速同尺寸，需配训练前缀 query_prefix: "query: "、document_prefix: "passage: "）；要最高质量与长分块用 BAAI/bge-m3（1024 维，约 2.3 GB 下载，CPU 上慢数倍）。向导把这一步作为「Embedding model」问题呈现（实测界面见《serviette 0.1.8 常用 CLI 命令与工具详解》）。

splitter（仅 indexer）：

5.6 indexer、workdir_path、persistence

配置指纹（<workdir_path>/serviette-fingerprint.json）记录分块相关设置（splitter、parser 路由、embedder 身份、库版本、chunk-id 方案）。启动时发现变更会打印 diff 并拒绝运行，需交互确认或设 SERVIETTE_ACCEPT_FINGERPRINT_CHANGES=1——因为库里旧行保留旧 chunk id，不确认会留孤儿向量。该检查持久化开关与否都生效。另注意：拉取/解析失败的文档按「空文档」入库且本次版本内不再自动重试，修复原因后 touch 文件（或重新上传对象）触发重发。

实测确认工作目录在首次 indexer 启动时创建（哑许可证触发校验失败前，库文件已建立——回显见第八章 Q4，文件实测存在）：

ls /root/serviette-demo

bad.yaml  config.yaml  docs  embeddings.duckdb  serviette-workdir  server-openai.yaml

5.7 server、up、llm、rag

server（API 服务）：

up（监管器）：index_wait_timeout（秒，默认 120）——indexer 多久无动静后不再拦着 server 开门；计时按「日志里最后一次工作迹象」算，解析大 PDF 的几分钟不会误触发；全空转的语料（如无 ocr extra 的扫描件）会在超时后让 server 带着空索引上线并告警。设 null 无限等。

llm（/rag 回答生成，省略整段即禁用 /rag）：

rag（检索增强策略）：

• rag.adaptive：{factor, max_iterations, no_answer_string}，默认关。自适应 RAG：先按 k 块作答，答不上（回复含 no_answer_string，默认 No information found）就按 factor 扩上下文重问，最多 max_iterations 轮。注意：system_prompt 若允许模型自由发挥，则几乎不会触发「答不上」标记；
• rag.documents：默认开。文档级问答（数文档、点名读整份文件、跨文件 diff 对比）。子字段：enabled、corpus_card、source_labels、max_context_chars（默认 24000）、max_request_chars（默认 100000）、max_listed_documents。单请求对 LLM 的总发送量受 max_request_chars 硬顶（含 adaptive 循环）；响应带 mode（search/catalog/document/compare/unresolved）、documents、notice。Pinecone 上忽略。

实测确认：llm.type: mock + embedder.type: openai 的组合可以让 server 无 OpenAI 真实调用地跑起来（启动日志与 / 页面 <title>serviette</title> 实测回显见《Ubuntu 22.04 安装 serviette 0.1.8 指南》4.6 节）。

5.8 frontend（拆分部署专用）

六、生产配置模板

场景约定：16GB 内存 / NVMe SSD / 中文为主的团队文档库（数万文件级），后端选 pgvector（复用既有 PostgreSQL 运维），嵌入用本地多语模型（数据不出门），/rag 用 OpenAI 生成回答。模板逐段给出（字段含义见第五章）：

pathway_license_key: ${PATHWAY_LICENSE_KEY}

sources:
  - type: fs
    path: /srv/teamdocs
    glob: '**/*'
  - type: s3
    bucket: archive-docs
    endpoint: http://minio.internal:9000
    with_path_style: true
    access_key: ${MINIO_ACCESS_KEY}
    secret_access_key: ${MINIO_SECRET_KEY}

vector_db:
  type: pgvector
  connection_string: postgresql://serviette:q1w2e3r4@127.0.0.1:5432/serviette
  table: serviette_embeddings
  hybrid: true

embedder:
  type: sentence_transformer
  model: intfloat/multilingual-e5-small
  query_prefix: "query: "
  document_prefix: "passage: "

splitter:
  type: token_count
  chunk_size: 512
  chunk_overlap: 50

indexer:
  workers: 4
  monitoring_http_port: 20000

workdir_path: /var/lib/serviette/workdir

persistence:
  enabled: true
  backend: filesystem

server:
  host: 0.0.0.0
  port: 8989
  cors_origins: []

llm:
  type: openai
  model: gpt-4o-mini
  api_key: ${OPENAI_API_KEY}

rag:
  adaptive:
    factor: 3
    max_iterations: 2

模板要点解读：

• 中文语料必须换 multilingual-e5-small 并带 query: /passage: 前缀（默认英文模型会检索退化，官方明示）；
• MinIO 走 S3 协议：endpoint + with_path_style: true 是自托管对象存储的标配两行；
• server.host: 0.0.0.0 前必须先架好认证反代（Caddy basic_auth / nginx auth_basic / oauth2-proxy 等，官方文档给了 Caddy 五行示例）——serviette 本身无内置认证；
• indexer.workers: 4 适配 16GB 内存机器（每个 worker 携带一份本地嵌入栈；官方 50 GB 基准用 8 worker 在 96 核主机上跑到 14.65 GiB 峰值，4 worker + e5-small 在 16GB 内是稳妥档）；
• Prometheus 抓 127.0.0.1:20000~20003（/metrics）获得输入/输出延迟与每算子行数。

单机轻量档（笔记本/演示，8GB 内存）：删掉 s3 来源与 hybrid，vector_db 改 duckdb（path: ./embeddings.duckdb），indexer.workers 去掉（默认 1），server.host 保持 127.0.0.1——即向导生成的形态。

七、配置与运行行为的关系速查

改哪些键会触发什么行为（编辑配置前先看这张表）：

八、常见问题（FAQ）

Q1：启动报 Invalid configuration ... environment variable(s) that are not set

实测回显：

Invalid configuration in config.yaml:
The config references environment variable(s) that are not set:
  - ${PATHWAY_LICENSE_KEY} (used in pathway_license_key)
Export them before starting (e.g. `export OPENAI_API_KEY=sk-...`) or replace the reference in the config.

• 原因：配置里的 ${VAR} 引用没有对应的已导出变量。serviette 不会把缺变量静默替换为空串（那会把问题拖到 provider 401 才暴露）。
• 解决：导出变量，或把值直接写进配置（不推荐，凭据落盘）。

Q2：indexer 报 Source directory not found

实测回显：

Source directory not found:
  - /root/serviette-demo/nodir
Check the 'path' of the fs source(s) in your config (relative paths resolve against the current working directory; '~' is expanded), or create the directory first — documents dropped into an existing folder are indexed live.

• 原因：fs 来源的 path 不存在；相对路径按启动时的工作目录解析。
• 解决：mkdir -p 建目录或修正路径；systemd 部署时与单元的 WorkingDirectory 对齐。

Q3：报 OpenAI API key missing for: embedder

实测回显：

OpenAI API key missing for: embedder (type: openai).
Export it before starting (`export OPENAI_API_KEY=sk-...`) or set `api_key` in those config sections. To run without OpenAI, switch the embedder to `sentence_transformer` (free, local) and drop or change the `llm` section.

• 解决：导出 key / 在段内写 api_key: ${OPENAI_API_KEY} / 换本地嵌入。

Q4：许可证哑值触发 RuntimeError: ... require a Pathway license key

实测回显：

RuntimeError: the feature(s) you used ["DUCKDB"] require a Pathway license key, which is free.
Get one in seconds (sign up with GitHub or LinkedIn) at https://pathway.com/framework/get-license, then set the PATHWAY_LICENSE_KEY environment variable.

• 解决：领真实免费许可证替换环境变量。报错中的特性名（如 ["DUCKDB"]）指示触发校验的能力。

Q5：改了分块/模型后 indexer 拒绝启动

• 现象：启动打印「配置指纹」diff 并停止。
• 原因：分块相关设置变更会让库里旧行带着旧 chunk id 成为孤儿，serviette 用指纹机制拦截。
• 解决：确认废弃旧索引后，交互确认或 export SERVIETTE_ACCEPT_FINGERPRINT_CHANGES=1 再启动；随后全量重建（持久化开启时启动即自动完成重嵌与旧向量清理）。

Q6：检索/stats 显示 stats_available: false 或 503

• stats_available: false：索引为空，先跑 indexer（实测回显见 5.4 节）；
• 503「索引更新中」：DuckDB 批提交持锁期间到达的请求等待超 30 秒所致，稍后重试即可；频繁出现说明批过大，可减小 chunk_size 或改用客户端-服务型后端（pgvector/Qdrant）。

九、参考链接

• 官方配置参考（本篇字段与默认值的溯源依据）：https://github.com/pathwaycom/serviette/blob/main/docs/README.md
• 官方仓库：https://github.com/pathwaycom/serviette
• Pathway 免费许可证：https://pathway.com/framework/get-license
• 相关文档：《serviette 介绍与选型指南》《Ubuntu 22.04 安装 serviette 0.1.8 指南》《serviette 0.1.8 常用 CLI 命令与工具详解》