serviette 0.1.8 常用 CLI 命令与工具详解

目标：把 serviette 0.1.8 的命令行工具链一次讲全——主入口与 6 个子命令的参数与真实帮助回显、向导的完整交互实测、REST API 端点的实测调用、运行所需环境变量，以及启动校验报错的真实排障。本文全部命令与回显均在 Ubuntu 22.04.5 LTS + serviette 0.1.8（pathway 0.33.0）上实测采集，逐行照抄。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（x86_64），root 用户；
serviette：0.1.8（venv 安装于 /opt/serviette-venv，入口 /opt/serviette-venv/bin/serviette）；
底座：pathway 0.33.0，Python 3.10.12；
实验目录：/root/serviette-demo/（含 config.yaml（向导生成）、server-openai.yaml（手写）、语料 docs/）；
服务端口：8989（server 默认）；

版本确认（实测回显）：

serviette --version

serviette 0.1.8

二、工具概览

serviette 是单入口多子命令形态：一个 serviette 命令分发全部子命令。主帮助（serviette --help，实测回显）：

usage: serviette [-h] [--version] {indexer,server,up,demo,frontend,wizard} ...

Single ``serviette`` entrypoint dispatching all subcommands. Subcommands:
serviette indexer --config FILE Build & run the Pathway indexing graph
serviette server --config FILE Start the FastAPI retrieval/RAG server
serviette up --config FILE Run indexer + server together (dev/demo) serviette
demo Zero-to-chat demo on a bundled corpus serviette wizard Interactive
config-generation wizard

positional arguments:
  {indexer,server,up,demo,frontend,wizard}
    indexer             Run the indexer
    server              Run the server
    up                  Run indexer + server together
    demo                Zero-to-chat demo on a bundled corpus
    frontend            Run the web chat frontend
    wizard              Interactive config wizard

options:
  -h, --help            show this help message and exit
  --version             show program's version number and exit

子命令分工速查：

子命令	角色	一句话
`serviette indexer`	写路径	监视文档、解析分块嵌入、实时同步进向量库（需许可证）
`serviette server`	读路径	FastAPI 检索/RAG API + 同端口聊天页
`serviette up`	监管器	开发/演示用：一条命令同时跑 indexer + server
`serviette demo`	演示	内置语料零到聊天
`serviette frontend`	前端层	拆分部署时独立聊天 UI（服务端代理 API）
`serviette wizard`	配置生成	交互式问答生成 YAML 配置

💡 说明：除 up/demo 外，各子命令都是前台常驻进程——生产托管（systemd）时它们就是服务本体；日常调试建议直接前台跑，Ctrl+C 退出。

三、前置条件

已安装 serviette（见《Ubuntu 22.04 安装 serviette 0.1.8 指南》），which serviette 能找到入口（实测回显 /opt/serviette-venv/bin/serviette）；
使用前导出环境变量（见第七章清单）：PATHWAY_LICENSE_KEY（indexer/demo/up 必需）、OPENAI_API_KEY（openai 嵌入/回答时必需）；
有一个 YAML 配置文件（向导生成或手写，字段见《serviette 0.1.8 配置参数详解》）。

四、各子命令详解

4.1 `serviette indexer` —— 索引器（写路径）

帮助（实测回显）：

usage: serviette indexer [-h] --config CONFIG [--log-level LOG_LEVEL]

options:
  -h, --help            show this help message and exit
  --config CONFIG       Path to the YAML config file
  --log-level LOG_LEVEL
                        Logging level (default: INFO)

参数说明：

参数	必填	默认	说明
`--config`	✅	—	YAML 配置文件路径
`--log-level`	❌	`INFO`	日志级别（排障时可调 `DEBUG`）

行为要点：启动即做配置预检（环境变量/源目录/缺 key 三关，实测报错原文见《serviette 0.1.8 配置参数详解》第八章），通过后初始化 Pathway 索引图——此刻校验 Pathway 许可证，无效则报错退出（实测回显：RuntimeError: the feature(s) you used ["DUCKDB"] require a Pathway license key, which is free. ...，完整原文与解决见安装指南 FAQ Q5）。有效许可证下，indexer 持续运行，监视源目录并把变更实时写入向量库。

4.2 `serviette server` —— 检索/RAG 服务器（读路径）

帮助（实测回显）：

usage: serviette server [-h] --config CONFIG

options:
  -h, --help       show this help message and exit
  --config CONFIG  Path to the YAML config file

参数只有一个 --config。server 是纯 FastAPI 读路径，启动不校验 Pathway 许可证真伪（只做配置预检），因此装完即可用它验证链路。

实测启动（配置：DuckDB + openai 嵌入 + mock LLM）：

export PATHWAY_LICENSE_KEY=<你的免费许可证> OPENAI_API_KEY=sk-<你的OpenAI密钥>
serviette server --config server-openai.yaml

实测回显：

INFO:     Started server process [4791]
INFO:     Waiting for application startup.
INFO llm client ready in 0.0s
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8989 (Press CTRL+C to quit)

启动后同一端口承载：聊天页（/）与版本化 REST API（/api/v1/*），端点实测见第六章。

4.3 `serviette up` —— 一键监管器（开发/演示）

帮助全文（实测回显，原文信息量很大， supervisor 的完整行为契约都在里面）：

usage: serviette up [-h] --config CONFIG [--verbose]

``serviette up`` — run the indexer and the server together from one config. A
deliberately dumb supervisor: it spawns ``serviette indexer``, waits until the
vector store is queryable (printing an "indexing in progress" heartbeat — the
chat page must never open onto a guaranteed error), then spawns ``serviette
server`` and waits until its ``/api/v1/health`` answers before printing the
URL to open (uvicorn binds the port only after the lifespan warm-up — a local
embedder imports torch and loads its model there, tens of seconds during which
the port is not even listening). No refresh loops — every backend runs its
native streaming mode, so freshness is seconds everywhere. Teardown rules: -
SIGINT/SIGTERM → terminate both children, exit 0. - server exits (any code) →
terminate the indexer, exit with the server code. - indexer exits non-zero →
terminate the server, exit with that code. - indexer exits 0 (all sources were
``mode: static``) → one-shot indexing finished; the server keeps serving. This
is a dev/demo convenience; production deployments still run the components
separately (see docs/README "Scaling").

options:
  -h, --help       show this help message and exit
  --config CONFIG
  --verbose        pass the indexer's and the server's full output through (by
                   default routine INFO lines are hidden)

行为契约解读（原文义）：

启动顺序：先拉 indexer，等向量库可查询（期间打印「indexing in progress」心跳），再拉 server，等 /api/v1/health 应答后才打印 URL；
退出联动：Ctrl+C（SIGINT/SIGTERM）终止两个子进程并 exit 0；server 退出 → 连带停 indexer；indexer 非零退出 → 连带停 server；indexer 以 0 退出（全部来源是 mode: static）→ 一次性索引完成，server 继续服务；
--verbose：默认隐藏两个子进程的例行 INFO 行（只显示进度/警告/错误/URL），加上后全透传；被隐藏的行仍会保留用于 STOPPED 诊断报告——若任一子进程死亡，up 会以一个框住的 serviette up STOPPED 块给出原因与建议；
⚠️ up 同样会走到许可证校验（它启动的 indexer 需要有效许可证）。

4.4 `serviette demo` —— 零到聊天演示

帮助（实测回显）：

usage: serviette demo [-h] [--dir DIR] [--port PORT]
                      [--embedder {local,openai}]

``serviette demo`` — zero-to-chat in one command. Copies a small bundled
corpus (a fictional company, Lumina Coffee Systems) into a working directory,
generates a DuckDB-backed config, and runs the ``serviette up`` supervisor
over it. The printed script walks the presenter through the money shot: edit
``docs/pricing.md`` and watch the answer change. Embedder/LLM selection. By
default the embedder is local — ``sentence-transformers`` when installed, the
mock embedder otherwise — so retrieval is free and the index never depends on
an API key. ``--embedder openai`` opts into OpenAI embeddings instead: nothing
to install, fast to start, but every indexed token costs money — meant for
small corpora. The LLM (independently of the embedder) uses ``OPENAI_API_KEY``
when it is set (real generated answers) and falls back to the mock LLM (the
answer quotes the retrieved snippet) when not.

options:
  -h, --help            show this help message and exit
  --dir DIR             Demo working directory
  --port PORT
  --embedder {local,openai}
                        local (default): free sentence-transformers
                        embeddings; openai: nothing to install but indexing
                        costs money (needs OPENAI_API_KEY) — for small corpora

参数说明：

参数	默认	说明
`--dir`	`./serviette-demo`	演示工作目录（内置语料复制到其中 `docs/`）
`--port`	8989	聊天页端口
`--embedder`	`local`	`local`=本地嵌入（装了 sentence-transformers 才可用，否则退化为 mock）；`openai`=API 嵌入，按 token 计费

实测确认的两个行为：

未设许可证时立即友好报错（原文）：

serviette demo needs a Pathway license key (free, one click at https://pathway.com/framework/get-license). Set PATHWAY_LICENSE_KEY and re-run.

demo 会把虚构公司 Lumina Coffee Systems 的小语料落盘到 <dir>/docs 并生成 DuckDB 配置，运行中编辑 docs/pricing.md 数秒内答案即变——这是官方设计的核心卖点演示脚本。

4.5 `serviette frontend` —— 独立聊天前端（拆分部署）

帮助（实测回显）：

usage: serviette frontend [-h] --config CONFIG

options:
  -h, --help       show this help message and exit
  --config CONFIG  Path to the YAML config file

仅在「UI 与 API 分机部署」时使用：前端无状态，按配置的 frontend.api_url（默认 http://localhost:8989）在服务端代理 API，浏览器只与前端同源通信（无 CORS 问题）。单机部署不需要它——server 的 serve_frontend: true（默认）已在 / 提供同一聊天页。

4.6 `serviette wizard` —— 交互式配置向导

帮助（实测回显）：

usage: serviette wizard [-h]

Interactively generate a YAML config.

向导无参数，全部内容在交互里。以下为实测完整流程（每步选项原样照抄；答案以行尾输入给出）：

Step 1: What to generate?
Config type:
    [1] Universal config (default)
    [2] Indexer config only
    [3] Server config only
  Enter number [1-3] [1]:
Step 2: Document sources
Add a document source:
    [1] Filesystem (local directory) (default)
    [2] Google Drive
    [3] S3 / MinIO / S3-compatible bucket
    [4] Microsoft SharePoint
    [5] FTP / SFTP / WebDAV / ZIP (PyFilesystem URL)
  Enter number [1-5] [1]:   Directory path: /root/serviette-demo/docs
Add another source?
    [1] Filesystem (local directory)
    [2] Google Drive
    [3] S3 / MinIO / S3-compatible bucket
    [4] Microsoft SharePoint
    [5] FTP / SFTP / WebDAV / ZIP (PyFilesystem URL)
    [6] Done — no more sources (default)
  Enter number [1-6] [6]:
Step 3: Vector database
Vector database:
    [1] duckdb (local file · zero setup · in-database vector search) (default)
    [2] pgvector (Postgres)
    [3] qdrant
    [4] milvus
    [5] chroma
    [6] weaviate
    [7] pinecone
    [8] mongodb (Atlas Vector Search)
  Enter number [1-8] [1]:
Step 4: Vector DB connection
  DuckDB file ./embeddings.duckdb already exists; path to use [./embeddings.duckdb]:
Step 5: Embedder
Embedder:
    [1] sentence_transformer (local · no API key needed) (default)
    [2] openai
    [3] litellm
    [4] gemini
    [5] bedrock
  Enter number [1-5] [1]:   ! sentence_transformer needs the sentence_transformers package, which is not installed in this Python environment. Install it before running the stack:
      pip install "serviette[local]" --extra-index-url https://download.pytorch.org/whl/cpu
What now?
    [1] Keep it (I will install the package before `serviette up`) (default)
    [2] Choose another embedder
  Enter number [1-2] [1]:
Step 6: Embedding model
Embedding model:
    [1] all-MiniLM-L6-v2 — English only · smallest and fastest · 384-dim (reads the first 256 tokens of each chunk) (default)
    [2] multilingual-e5-small — ~100 languages (French, German, Spanish, Polish, Russian, Chinese, …) · same speed class · 384-dim · pick this for non-English or mixed documents
    [3] bge-m3 — 100+ languages · highest quality, long chunks (8k tokens) · 1024-dim · ~2.3 GB download, several times slower on CPU
    [4] Other — type a Hugging Face model id
  Enter number [1-4] [1]:
Step 7: Chat answers
  The /rag endpoint and the web chat are always available. This picks
  the LLM that turns the retrieved snippets into an answer:
    mock    - no LLM and no API key. The chat replies with the best
              matching snippet quoted verbatim: good for checking what
              gets retrieved, but the answers are not natural language.
    openai  - real generated answers from the OpenAI API (needs
              OPENAI_API_KEY).
    litellm - any provider LiteLLM supports (needs that provider's key).
LLM for chat answers:
    [1] mock (no LLM: quote the best snippet) (default)
    [2] openai
    [3] litellm
  Enter number [1-3] [1]:
Step 8: Pathway License Key
  Pathway requires a free license key. Get yours in one click at https://pathway.com/framework/get-license (email or LinkedIn sign-in).
  PATHWAY_LICENSE_KEY is set in your environment — press Enter to reference it from the config, or paste a key to store it instead.
  Pathway license key [${PATHWAY_LICENSE_KEY}]:
Step 9: Output file path
  Output file path [./config.yaml]:
Wrote universal config to ./config.yaml
Advanced settings (file glob patterns, chunking/splitter, persistence, backpressure, table names) can be tuned by editing ./config.yaml.
Run it with:  serviette up --config ./config.yaml

实测要点：

必填拦截：Step 2 目录路径为空时重复追问 This field is required.，持续到 EOF 时输出 Aborted.（实测）；
缺包提示：Step 5 选本地嵌入而 sentence-transformers 未安装时，当场给出安装命令（上文 ! 行为实测原文）；
许可证引用：Step 8 检测到环境已导出 PATHWAY_LICENSE_KEY，默认写 ${PATHWAY_LICENSE_KEY} 引用（避免明文落盘）；
中文语料提醒：Step 6 选项 [2]/[3] 即官方对非英语语料的推荐（multilingual-e5-small/bge-m3），中文团队不要选默认 [1]；
生成的 config.yaml 全文见《serviette 0.1.8 配置参数详解》3.2 节（实测照抄）。

五、REST API 端点实测

server 在一个端口同时提供聊天页与 API，路径分两层：/api/v1/* 为版本化端点，旧的 /retrieve、/rag、/health 仍作为弃用别名可用。以下全部端点均为实测调用与真实回显（server 启动方式见 4.2 节；索引为空状态）。

健康检查：

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

{"status":"ok"}

索引统计（供仪表盘/巡检，读向量库）：

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

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

实测说明：空索引时 stats_available: false；indexer 完成首轮索引后此端点返回后端名、已索引分块数与索引新鲜度。

检索（向量检索 top-k，需 embedder 可用）：

curl -X POST http://127.0.0.1:8989/api/v1/retrieve \
  -H 'Content-Type: application/json' \
  -d '{"query": "how does persistence work?", "k": 3}'

⚠️ 实测说明：本文实验环境 OPENAI_API_KEY 为占位值，该请求在嵌入查询阶段被 OpenAI 服务端拒绝（401），未返回检索结果——这是「key 无效」的真实表现；配置有效 key 后同一请求返回命中的分块列表。这也说明 server 端点对 key 真伪的校验发生在首次真实调用时，而非启动时（启动预检只查 key 是否存在）。

文档清单（按名称/路径模糊搜索已索引文档；分页参数 q、case_sensitive（默认 false）、limit（默认 100，最大 1000））：

curl -s 'http://127.0.0.1:8989/api/v1/documents?q=report&case_sensitive=false'

⚠️ 实测说明：空索引（DuckDB 表未建）状态下该端点返回 Internal Server Error——索引为空属边界状态，先跑 indexer 再用；Pinecone 后端此端点固定返回 501（无法枚举文档）。

聊天页：

curl -s http://127.0.0.1:8989/ | grep -oE '<title>[^<]*</title>'

<title>serviette</title>

实测注意：对 / 发 HEAD 请求返回 405 Method Not Allowed（allow: GET），探活请用 GET 或直接用 /api/v1/health。

/rag 回答端点：配置了 llm 段后可用（POST /api/v1/rag，body 同 retrieve），llm.type: mock 时回复原样引用最佳片段——适合先检查检索质量再接真模型。

六、环境变量清单

serviette 运行涉及的全部环境变量（官方文档与实测综合）：

变量	必需性	作用
`PATHWAY_LICENSE_KEY`	indexer/demo/up 必需	免费 Pathway 许可证；配置 `${PATHWAY_LICENSE_KEY}` 引用时未导出会启动报错
`OPENAI_API_KEY`	openai 型嵌入/LLM 必需	嵌入查询与文档、`/rag` 回答生成、Whisper 音频解析
`TWELVELABS_API_KEY`	可选	视频解析（TwelveLabs Pegasus），未设则视频跳过并告警
`SERVIETTE_ACCEPT_FINGERPRINT_CHANGES=1`	可选	非交互确认配置指纹变更（分块设置改动/升级后重建索引）
`SERVIETTE_TEST_MILVUS_URI`	仅测试	集成测试用 Milvus 服务器地址

七、注意事项

生产用 indexer + server 分开跑，up 是开发/演示便利（其帮助原文明言）；两进程只共享向量库，可独立重启、独立伸缩；
server 默认只听 127.0.0.1 且无内置认证——对外暴露必须显式 server.host: 0.0.0.0 并前置认证反代；
改分块设置/换嵌入模型会触发指纹确认与全量重建（非交互场景设 SERVIETTE_ACCEPT_FINGERPRINT_CHANGES=1）；
up 的 --verbose 只影响实时输出，不影响诊断——子进程死亡时的 STOPPED 报告永远含被隐藏的日志行；
拉取/解析失败的文档按空文档入库且本版本内不自动重试：修复后 touch 文件或重新上传触发重发；
提示词/文档显示中出现的「免费许可证」不是营销话术——实测哑值确实被引擎拒绝（回显见《Ubuntu 22.04 安装 serviette 0.1.8 指南》FAQ Q5），注册领取后即可用。

八、常见问题（FAQ）

Q1：serviette 命令找不到（command not found）

原因：装在 venv 而未激活，或 PATH 未含 venv bin。
解决：source /opt/serviette-venv/bin/activate，或用绝对路径 /opt/serviette-venv/bin/serviette（实测入口位置见第三章）。

Q2：up --config nope.yaml 报 FileNotFoundError

实测回显（末尾）：

FileNotFoundError: [Errno 2] No such file or directory: '/root/nope.yaml'

解决：--config 路径写错所致，核对后重跑。注意这是少数直接抛 traceback 的情况（配置内容类错误都有友好一段话提示）。

Q3：配置里的 ${VAR} 未导出

实测回显：

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.

解决：导出变量；报错精确到「变量名 + 使用它的配置键」。

Q4：serviette demo 提示需要许可证

实测回显：

serviette demo needs a Pathway license key (free, one click at https://pathway.com/framework/get-license). Set PATHWAY_LICENSE_KEY and re-run.

解决：领取并导出许可证后重跑。

Q5：indexer 启动报 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.
Occurred here:
    Line: pw.io.duckdb.write(

解决：许可证无效/哑值所致，换真实免费许可证。校验时机在索引图初始化（写 sink 时），报错会带触发特性名与出错位置。

Q6：/api/v1/documents 返回 Internal Server Error

原因：索引为空（DuckDB 表未建）时该端点报 500（实测）；属边界状态。
解决：先跑完 indexer 首轮索引再调用。

Q7：向导一直追问 This field is required. 后 Aborted

实测回显（节选）：

  Directory path:   This field is required.
  Directory path:   This field is required.
  ...
Aborted.

原因：必填项（目录路径）用空回车跳过，向导反复重问，stdin 耗尽后中止。
解决：在 Directory path 处输入真实存在的目录（如 /root/serviette-demo/docs），或先 mkdir -p。

九、参考链接

官方文档（子命令行为与 API 的溯源依据）：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 配置参数详解》

serviette 0.1.8 常用 CLI 命令与工具详解

serviette 0.1.8 常用 CLI 命令与工具详解

一、环境信息

二、工具概览

三、前置条件

四、各子命令详解

4.1 serviette indexer —— 索引器（写路径）

4.2 serviette server —— 检索/RAG 服务器（读路径）

4.3 serviette up —— 一键监管器（开发/演示）

4.4 serviette demo —— 零到聊天演示

4.5 serviette frontend —— 独立聊天前端（拆分部署）

4.6 serviette wizard —— 交互式配置向导

五、REST API 端点实测

六、环境变量清单

七、注意事项

八、常见问题（FAQ）

九、参考链接

4.1 `serviette indexer` —— 索引器（写路径）

4.2 `serviette server` —— 检索/RAG 服务器（读路径）

4.3 `serviette up` —— 一键监管器（开发/演示）

4.4 `serviette demo` —— 零到聊天演示

4.5 `serviette frontend` —— 独立聊天前端（拆分部署）

4.6 `serviette wizard` —— 交互式配置向导