quivr 2.0.0-alpha.7 常用 CLI 命令与工具详解

quivr 2.0.0-alpha.7 运维命令实测手册：安装器 setup.py（init/prepare/upgrade 与排障表）、docker compose 编排命令（ps/logs/top/exec/restart/config/down）、psql 巡检（SHOW 参数核对、121 张表清单、pg_stat_statements）、temporal CLI（namespace/workflow/search-attribute）与 curl 公共 API 速查（版本/语料库/记录/回执/三种检索模式），全部命令与回显逐条实测。

quivrquivrRAGLLM知识库2026/10/23

quivr 2.0.0-alpha.7 常用 CLI 命令与工具详解

目标：汇总 quivr 2.0.0-alpha.7 单机部署日常运维中真实可用的五类命令行工具——官方安装器 setup.py、编排入口 docker compose、数据库客户端 psql、工作流客户端 temporal CLI 与 curl 公共 API 速查——逐条给出实测命令与回显，作为部署（《quivr Docker Compose 部署指南》）与配置（《quivr 2.0.0-alpha.7 配置参数详解》）之外的运维操作手册。已在 Ubuntu 24.04（x86_64）+ Docker Engine 29.8 + Docker Compose v5.5.1 环境逐条实测通过。

一、环境信息

本文所有命令与回显均在以下环境实测：

  • 操作系统：Ubuntu 24.04 LTS（x86_64），内核 6.8 系
  • Docker Engine：29.8 系，Docker Compose v5.5.1
  • quivr 版本：2.0.0-alpha.7（revision 7b5ffe3eaa031ccbb1f49244b76e8b9bf5d11426，API v0，插件引擎 0.2.0）
  • 安装目录：/opt/quivr（官方发布包解压目录，下文命令均在该目录执行；与部署篇同一演示安装：--embedding e5 --project quivr-2-0-0-alpha-7-stack --profile small）
  • PostgreSQL：17.11（psql (PostgreSQL) 17.11，实测回显见六.1）；Temporal CLI 1.8.3（Server 1.31.2，实测见七.1）
  • 演示密钥：QUIVR_API_KEY=08dee2d53f038fd455294fdad3bf59240c9be17d3723a2ae8f189e91fdc6ad26（演示安装实测值，你的安装取自你的 .env）

💡 说明：单机栈是 image-only 形态，引擎没有暴露面向用户的独立 CLI 二进制——对运维真正可用的命令面就是本文五类工具。引擎进程面（api 服务内实际运行的进程）见五.3 的 compose top 实测。

二、工具概览

工具所在职责本文章节
setup.py安装目录（Python 3.12+）安装生命周期：初始化渲染（init）、模型缓存（prepare）、滚动升级（upgrade）四
docker composeDocker Engine v2栈编排：状态/日志/进程/进入/重启/配置核对/停止清理五
psqlquivr-postgres 服务内（17.11）数据库巡检：参数核对、库表清单、语句统计六
temporal CLItemporal 服务内工作流巡检：namespace/workflow/检索属性七
curl任意可达 API 端口的主机公共 API 速查：版本/语料库/记录/回执/检索八

关键解读：setup.py 是唯一改动安装形态的入口（渲染 .env → compose.yaml）；docker compose 是唯一改动运行状态的入口；psql/temporal 是只读巡检为主；curl 面向业务与集成验证。四类操作的权限与风险依次递减。

三、前置条件

  • 已按《quivr Docker Compose 部署指南》完成部署：docker compose ps -a 中 7 个常驻服务 Up (healthy)、migrate Exited (0)（回显样例见五.1）。
  • 命令执行位置：涉及 setup.py 与 docker compose 的命令在安装目录 /opt/quivr 执行；psql/temporal 经 docker compose exec <服务> 进入，不依赖宿主机安装客户端。
  • 演示密钥与端点：API 端口 127.0.0.1:8080；示例用 KEY=08dee2d53f038fd455294fdad3bf59240c9be17d3723a2ae8f189e91fdc6ad26。

四、安装器 setup.py 详解

4.1 帮助与子命令总览

setup.py 有三个子命令（init/prepare/upgrade）与 8 个共用选项。帮助回显：

cd /opt/quivr && python3 setup.py --help

实测输出：

usage: setup.py [-h] [--directory DIRECTORY] [--release RELEASE]
                [--project PROJECT] [--embedding {gemma,e5}]
                [--profile {small,large}] [--secret-file KEY=PATH]
                [--mirror MIRROR] [--source SOURCE]
                {init,prepare,upgrade}

Initialize one protected environment and render a standalone image-only stack.

positional arguments:
  {init,prepare,upgrade}

options:
  -h, --help            show this help message and exit
  --directory DIRECTORY
  --release RELEASE
  --project PROJECT
  --embedding {gemma,e5}
  --profile {small,large}
  --secret-file KEY=PATH
  --mirror MIRROR
  --source SOURCE

💡 说明：argparse 的子命令帮助与全局帮助一致（python3 setup.py init --help 回显与上面相同），各选项语义与逐项说明见《quivr 2.0.0-alpha.7 配置参数详解》第五章，此处只列命令形态。

4.2 init：初始化安装

生成/复用 .env（0600）并按 release digest 渲染 compose.yaml。全新安装（e5 演示参数）：

cd /opt/quivr && python3 setup.py init --embedding e5 --project quivr-2-0-0-alpha-7-stack

实测输出（exit 0）：

Ready: one Compose file and protected .env; model cache preparation is a separate install step.

幂等重跑（保留密钥、只重渲染）：

cd /opt/quivr && python3 setup.py init

实测输出：

Ready: one Compose file and protected .env; model cache preparation is a separate install step.

注入既有密钥重建安装（每把密钥一个 0600 文件、内容 64 位十六进制）：

umask 077
openssl rand -hex 32 > /protected/api-key
python3 setup.py init --secret-file QUIVR_API_KEY=/protected/api-key

4.3 prepare：准备模型缓存

把锁定版本的嵌入模型下载进 <项目名>-model-cache 命名卷并校验；已就绪时重跑仅校验：

cd /opt/quivr && python3 setup.py prepare

实测输出（缓存已就绪，exit 0）：

Ready: one Compose file and protected .env; model cache preparation is a separate install step.

离线选项：--mirror <URL>（镜像源下载）、--source <DIR>（本地模型目录）。

4.4 upgrade：滚动升级

选项与 init 相同，渲染后自动按序执行：停 api worker demo → 移除一次性的 migrate → docker compose up -d。等价手工序列：

cd /opt/quivr
docker compose stop api worker demo
docker compose rm -f migrate
docker compose up -d

⚠️ 注意：2.0.0-alpha 各版本间官方明确不支持原地升级（alpha.7 相对 alpha.6 及更早为 BREAKING）；升级前按部署篇第五章备份命名卷。

4.5 安装器排障：Setup refused

安装器对非法输入一律拒绝且不回显敏感值，报错形如 Setup refused: <原因>（stderr，exit 1）。实测归纳的高频触发与处置：

报错原因触发场景处置
environment must be a regular private file (chmod 600).env 权限宽于 0600 或是符号链接chmod 600 .env 后重跑
installation secrets must contain 64 hexadecimal characters--secret-file 内容不是 64 hex用 openssl rand -hex 32 重新生成
API and operator keys must differ注入的两把密钥相同分开生成注入
invalid installation input（不回显细节）非 0600 的 secret 文件、越界的 --embedding/--profile 等按第五章参数表核对输入
service memory budget must be at least 128 MiB内存覆盖键小于 128改为 ≥128 的整数 MiB
installation model revision cannot change; use a fresh installation已有数据安装改 QUIVR_MODEL_REVISION全新安装 + 重发内容

五、Compose 编排命令详解

5.1 服务状态：docker compose ps -a

运维第一步。-a 把一次性的 migrate（正常终态 Exited (0)）也列出来：

cd /opt/quivr && docker compose ps -a

实测输出（9 行全量）：

NAME                                     IMAGE                                                                                                                      COMMAND                  SERVICE      CREATED        STATUS                   PORTS
quivr-2-0-0-alpha-7-stack-api-1          ghcr.io/the-vibe-company/quivr-core@sha256:928a76de67872b244daefffea09d522db35b6d82016a39f2207763faa287af1d                "python /app/core-en…"   api          14 hours ago   Up 14 hours (healthy)    127.0.0.1:8080->8080/tcp
quivr-2-0-0-alpha-7-stack-demo-1         ghcr.io/the-vibe-company/quivr-web@sha256:706d7ac2dbd3153ae3ec07e096d58adff60f5c398e18697a04a7dd35dea237cb                 "docker-entrypoint.s…"   demo         14 hours ago   Up 6 hours               127.0.0.1:3000->3000/tcp
quivr-2-0-0-alpha-7-stack-embeddings-1   ghcr.io/the-vibe-company/quivr-tei@sha256:40f8e6738ea49ade4e849f8bc1e312c6c135bbf535b1dc041a94df459788307d                 "sh /app/tei-entrypo…"   embeddings   14 hours ago   Up 14 hours (healthy)
quivr-2-0-0-alpha-7-stack-migrate-1      ghcr.io/the-vibe-company/quivr-core@sha256:928a76de67872b244daefffea09d522db35b6d82016a39f2207763faa287af1d                "python /app/core-en…"   migrate      14 hours ago   Exited (0) 6 hours ago
quivr-2-0-0-alpha-7-stack-postgres-1     ghcr.io/the-vibe-company/quivr-postgres@sha256:c790f0ea98ab27af045d38cf7e2b7017a2d698e863f4cedb821524133a7b6d03            "quivr-postgres post…"   postgres     14 hours ago   Up 14 hours (healthy)    5432/tcp
quivr-2-0-0-alpha-7-stack-seaweed-1      ghcr.io/the-vibe-company/quivr-seaweed@sha256:d18537c2e220877f1725d52fe39dadc7766afee06e0bbe4c24d043ec2d73588c             "sh /usr/local/bin/q…"   seaweed      14 hours ago   Up 14 hours (healthy)    7333/tcp, 8080/tcp, 8333/tcp, 8888/tcp, 9333/tcp, 18080/tcp, 18888/tcp, 19333/tcp
quivr-2-0-0-alpha-7-stack-temporal-1     temporalio/temporal:1.8.3@sha256:cea463d98a8d6def4420f903ea5c3fcd0d85c8d10fbcc2770a50c12fff2eb26d                          "temporal server sta…"   temporal     14 hours ago   Up 14 hours (healthy)
quivr-2-0-0-alpha-7-stack-weaviate-1     cr.weaviate.io/semitechnologies/weaviate:1.39.10@sha256:de371bb2e07604636915581d784ce182303f0046376a3dd23822936fa10acc56   "/bin/weaviate --hos…"   weaviate     14 hours ago   Up 14 hours (healthy)
quivr-2-0-0-alpha-7-stack-worker-1       ghcr.io/the-vibe-company/quivr-core@sha256:928a76de67872b244daefffea09d522db35b6d82016a39f2207763faa287af1d                "python /app/core-en…"   worker       14 hours ago   Up 14 hours

健康判读：7 个常驻服务应全部 Up (healthy)（worker 无 healthcheck，Up 即正常）；migrate 恒为 Exited (0)；非 0 退出码见十.2。

5.2 服务日志：docker compose logs

引擎日志是 JSON 行，含 trace 关联字段。跟踪实时日志加 -f；看最近几行用 --tail：

cd /opt/quivr && docker compose logs worker --tail 1

实测输出：

worker-1  | {"ts":"2026-10-23T06:43:59.223845536Z","level":"INFO","msg":"evaluation backlog","service":"[REDACTED].worker","version":"2.0.0-alpha.7","instance":"ac7d508e136a:33","environment":"unspecified","pending_intents":0,"erroring_intents":0,"trace_id":"","span_id":""}

ts/level/msg 是定位起点，trace_id/span_id 与 api 请求日志（含 request_id 字段）可交叉关联；栈内日志轮转由 compose 渲染的 max-size 10m × 3 文件 兜底。

5.3 进程清单：docker compose top

查看引擎服务内实际进程面（api 角色示例）：

cd /opt/quivr && docker compose top api

实测输出（输出节选，保留每类进程首行）：

SERVICE  #   UID    PID    PPID   C   STIME  TTY  TIME      CMD
api      1   10001  71811  71786  0   Oct22  ?    00:00:12  python /app/core-entrypoint.py
api      1   10001  71987  71811  0   Oct22  ?    00:00:00  /usr/local/bin/quivr-x-list
api      1   10001  71988  71811  0   Oct22  ?    00:00:00  /usr/local/bin/quivr-core-ingest
api      1   10001  71989  71811  0   Oct22  ?    00:00:00  /usr/local/bin/quivr-core-retrieve
api      1   10001  71990  71811  0   Oct22  ?    00:00:04  /opt/quivr-plugins/bin/python -m alerts
api      1   10001  71991  71811  0   Oct22  ?    00:06:12  quivr api

判读：入口是 python /app/core-entrypoint.py，主引擎进程为 quivr api（Go 二进制），旁边挂 quivr-x-list/quivr-core-ingest/quivr-core-retrieve 辅助二进制与 alerts 插件进程；进程以 UID 10001 运行。

5.4 进入服务：docker compose exec

在指定服务内执行一次性命令（本文 psql/temporal 章节的基础形态）：

cd /opt/quivr && docker compose exec postgres psql --version

实测输出：

psql (PostgreSQL) 17.11

脚本化采集输出时用非交互形式 docker compose exec -T <服务> <命令>（-T 关闭 TTY 分配）。

5.5 服务管理：restart / stop / start / up -d / pull

重启单个服务（重启后由 compose 依赖关系自行恢复）：

cd /opt/quivr && docker compose restart worker

实测输出：

 Container quivr-2-0-0-alpha-7-stack-worker-1 Stopping
 Container quivr-2-0-0-alpha-7-stack-worker-1 Stopped
 Container quivr-2-0-0-alpha-7-stack-worker-1 Starting
 Container quivr-2-0-0-alpha-7-stack-worker-1 Started

重启后验证（实测）：docker compose ps worker 回显 Up。

  • docker compose stop <服务> / start <服务>：停起指定服务；
  • docker compose up -d：幂等重建/补拉（改动 .env 重渲染后生效的落点；渲染产物变化时按需重建受影响服务）；
  • docker compose pull：按 digest 拉齐 9 服务镜像；
  • docker compose --profile demo up -d：补拉演示界面（demo 挂在 demo profile 下）。

5.6 配置核对：docker compose config --services

列出当前渲染产物中的服务清单（默认 profile，不含 demo）：

cd /opt/quivr && docker compose config --services

实测输出：

embeddings
postgres
seaweed
temporal
weaviate
migrate
worker
api

完整渲染校验用 docker compose config（输出全部解析后的编排定义，校验语法与变量替换）。

5.7 停止与清理：down / down -v

cd /opt/quivr
docker compose --profile demo down   # 停止并移除容器与网络（保留 5 个命名卷）
docker compose --profile demo down -v   # 危险：连同命名卷一并删除

⚠️ 注意：down 不带 -v 不会删数据卷；-v 会删除全部已摄取内容与索引，官方排障口径明确「迁移失败时不要删卷重试」。卷清单核对：docker volume ls --format "{{.Name}}" | grep <项目名> 应见 <项目名>-postgres-data/-temporal-data/-seaweed-data/-weaviate-data/-model-cache 5 个。

六、psql 数据库工具详解

6.1 进入与版本

cd /opt/quivr && docker compose exec postgres psql -U quivr -d quivr -c "SELECT version();"

实测输出：

                                                 version
----------------------------------------------------------------------------------------------------------
 PostgreSQL 17.11 on x86_64-pc-linux-musl, compiled by gcc (Alpine 15.2.0) 15.2.0, 64-bit
(1 row)

业务库固定为 quivr、用户固定为 quivr（密码即 .env 的 QUIVR_DB_PASSWORD，exec 方式无需手输）。交互式进入：docker compose exec postgres psql -U quivr -d quivr。

6.2 参数核对（SHOW）

核对 QUIVR_POSTGRES_* 调优键的实际生效值（非交互 -At 逐条输出）：

cd /opt/quivr && docker compose exec postgres psql -U quivr -d quivr -At \
  -c "SHOW max_connections;" -c "SHOW work_mem;" -c "SHOW wal_compression;" \
  -c "SHOW synchronous_commit;" -c "SHOW shared_buffers;"

实测输出（每行一条，顺序与命令一致）：

256
4MB
lz4
on
8012MB

shared_buffers 未显式声明时由启动脚本按内存预算推导（25% 口径与全部推导规则见《quivr 2.0.0-alpha.7 配置参数详解》8.3）。

6.3 库与表巡检

数据库清单：

cd /opt/quivr && docker compose exec postgres psql -U quivr -d quivr -c '\l'

实测输出（输出节选）：

                                                 List of databases
   Name    | Owner | Encoding | Locale Provider |  Collate   |   Ctype    | Locale | ICU Rules | Access privileges
-----------+-------+----------+-----------------+------------+------------+--------+-----------+-------------------
 postgres  | quivr | UTF8     | libc            | en_US.utf8 | en_US.utf8 |        |           |
 quivr     | quivr | UTF8     | libc            | en_US.utf8 | en_US.utf8 |        |           |
 template0 | quivr | UTF8     | libc            | en_US.utf8 | en_US.utf8 |        |           | =c/quivr         +
           |       |          |                 |            |            |        |           | quivr=CTc/quivr
 template1 | quivr | UTF8     | libc            | en_US.utf8 | en_US.utf8 |        |           | =c/quivr         +

引擎建表规模（2.0.0-alpha.7 迁移完成后 public schema 共 121 张表）：

cd /opt/quivr && docker compose exec postgres psql -U quivr -d quivr -At -c "SELECT count(*) FROM pg_tables WHERE schemaname='public';"

实测输出：

121

抽看核心表（按字典序前 20 张）：

cd /opt/quivr && docker compose exec postgres psql -U quivr -d quivr -At -c "SELECT tablename FROM pg_tables WHERE schemaname='public' ORDER BY tablename LIMIT 20;"

实测输出：

accepted_revisions
active_pipeline_plan
audit_events
backfill_estimates
backfills
bulk_ingestion_batches
bulk_ingestion_outbox
change_events
change_feed_starts
change_journal_prunes
change_journal_publication
compact_embedding_coverage
compact_embeddings
connector_credentials
connector_instance_tokens
connector_instances
connector_push_answers
connector_push_buckets
connector_signature_replays
content_blobs

⚠️ 注意：引擎自有 schema 负责全部业务读写，运维侧对库只做巡检与备份（pg_dump），不要手工 DML。

6.4 pg_stat_statements 语句统计

QUIVR_POSTGRES_STAT_STATEMENTS_TRACK=all 已内置（扩展实测 pg_stat_statements 1.11）。按总耗时看 Top 语句：

cd /opt/quivr && docker compose exec postgres psql -U quivr -d quivr -c "SELECT query, calls, ROUND(total_exec_time::numeric,1) AS total_ms FROM pg_stat_statements ORDER BY total_exec_time DESC LIMIT 3;"

实测输出（输出节选，保留首条与行数）：

                                              query                                               | calls  | total_ms
---------------------------------------------------------------------------------------------------+--------+----------
 WITH wanted AS (                                                                                 +|  92001 | 189805.2
          SELECT source,stripe FROM unnest($1::text[]) sources(source)                            +|        |
          CROSS JOIN generate_series($2,$3) stripes(stripe)                                        +|        |
          ORDER BY source,stripe                                                                   +|        |
  )                                                                                                +|        |
  INSERT INTO queue_metric_totals(source,stripe)                                                   +|        |
          SELECT source,stripe FROM wanted                                                         +|        |
          ON CONFLICT(source,stripe) DO NOTHING                                                     |        |
(3 rows)

队列指标维护类语句调用频次高属正常（摄取管道的心跳写入）；排障时关注 calls 异常放大或新增的高耗时语句。

七、temporal CLI 详解

7.1 版本确认

cd /opt/quivr && docker compose exec temporal temporal --version

实测输出：

temporal version 1.8.3 (Server 1.31.2, UI 2.50.1)

（CLI 与随栈分发的 server dev 版本同镜像内置；Server 字段是服务端版本。）

7.2 namespace list

引擎使用 default namespace（dev server 自带）：

cd /opt/quivr && docker compose exec temporal temporal operator namespace list

实测输出：

  NamespaceInfo.Name                    default
  NamespaceInfo.Id                      01a1647d-4058-78c8-8bf7-642d2421c3c4
  NamespaceInfo.Description
  NamespaceInfo.OwnerEmail
  NamespaceInfo.State                   Registered
  NamespaceInfo.Data                    map[]
  Config.WorkflowExecutionRetentionTtl  24h0m0s
  ReplicationConfig.ActiveClusterName   active

7.3 workflow list

列出摄取工作流（带状态过滤）：

cd /opt/quivr && docker compose exec temporal sh -c 'temporal workflow list --query "ExecutionStatus = \"Completed\""'

实测输出（输出节选）：

   Status                                        WorkflowId                                                  Type              StartTime
  Completed  ingestion-batch-v1_b2bec2aa3903309d4d5d226a1336bf38d8c1ef8ad480bf530c25bfc4830b5444  process-ingestion-batch-v1  6 hours ago
  Completed  ingestion-batch-v1_f6c7967a6dbc3d4c77690894721e215e48eed2c0abf573d80445ca31f767f68b  process-ingestion-batch-v1  13 hours ago

⚠️ 注意：--query 的值必须整体加引号且比较值用引号包裹。实测把查询写成 --query ExecutionStatus=Closed（值未加引号）时直接报错：

Error: failed listing workflows: invalid query: operation is not supported: column name on the right side of comparison expression (did you forget to quote 'Closed'?)

修正方式即上面的带引号写法。

7.4 search-attribute list

cd /opt/quivr && docker compose exec temporal temporal operator search-attribute list

实测输出（输出节选）：

                  Name                     Type
  BatcherNamespace                      Keyword
  BatcherUser                           Keyword
  BinaryChecksums                       KeywordList
  BuildIds                              KeywordList
  CloseTime                             Datetime

八、curl 与公共 API 速查

API 基址 http://127.0.0.1:8080，鉴权 Authorization: Bearer <QUIVR_API_KEY>。以下命令的幂等键（Idempotency-Key 头与 body 内 idempotency_key）为客户端生成的唯一值——本文实测使用下列字面值，重放时请换成你自己的新 UUID。

8.1 版本端点（无鉴权）

curl -sS http://127.0.0.1:8080/v0/version

实测输出（HTTP 200）：

{"api_version":"v0","plugin_engine_version":"0.2.0","revision":"7b5ffe3eaa031ccbb1f49244b76e8b9bf5d11426","version":"2.0.0-alpha.7"}

8.2 语料库创建与列表

KEY=08dee2d53f038fd455294fdad3bf59240c9be17d3723a2ae8f189e91fdc6ad26
curl -sS -X POST http://127.0.0.1:8080/v0/corpora \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c2a9e11-5f0d-4b8e-a3c6-smoke-0001" \
  -d '{"idempotency_key":"7c2a9e11-5f0d-4b8e-a3c6-smoke-0001","name":"demo-corpus"}'

实测输出（HTTP 201）：

{"archived":false,"corpus_id":"corpus_3b1fd5a4b8cdce8bedb84cc9ff260e6b","name":"demo-corpus","effective_retrieval":{"fields":[]}}

curl -sS http://127.0.0.1:8080/v0/corpora -H "Authorization: Bearer $KEY"

实测输出（HTTP 200）：

{"items":[{"archived":false,"corpus_id":"corpus_3b1fd5a4b8cdce8bedb84cc9ff260e6b","name":"demo-corpus","effective_retrieval":{"fields":[]}}]}

8.3 记录写入与回执轮询

写入一条文本记录（立即返回摄取回执，state=pending）：

curl -sS -X POST http://127.0.0.1:8080/v0/records \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8d3b0f22-6a1e-4c9f-b4d7-smoke-0002" \
  -d '{"idempotency_key":"8d3b0f22-6a1e-4c9f-b4d7-smoke-0002","source":{"corpus_id":"corpus_3b1fd5a4b8cdce8bedb84cc9ff260e6b","namespace":"wire","record_key":"eclipse-2026-10-22"},"content":{"kind":"text","text":"Total solar eclipse draws crowds. On Tuesday a rare total solar eclipse crossed the continent, and crowds gathered in every city along the path of totality. Astronomers reminded spectators that the moon blocked the sun for just over four minutes, while libraries handed out protective glasses."}}'

实测输出（HTTP 202，输出节选）：

{"diagnostics":[],"processing":{"phase":"materialization","state":"queued"},"receipt_id":"receipt_a155d6fffeb99664b9948886dc9f6fcbc04071e4a245a8dc32dc86f3f56f1eb4","record_id":"record_f6821cb62cef6f30324ab168243c96e8347f5ca1c70eb71a349aa7029d3c8eed","source":{"corpus_id":"corpus_3b1fd5a4b8cdce8bedb84cc9ff260e6b","namespace":"wire","record_key":"eclipse-2026-10-22"},"state":"pending"}

轮询回执直到 state=resolved（实测写入约数秒内到达终态）：

curl -sS http://127.0.0.1:8080/v0/ingestion-receipts/receipt_a155d6fffeb99664b9948886dc9f6fcbc04071e4a245a8dc32dc86f3f56f1eb4 -H "Authorization: Bearer $KEY"

实测输出（HTTP 200，输出节选，保留状态与标识字段）：

{"availability":{"is_current":true,"searchable":true,"state":"retrieval_ready"},"diagnostics":[],"outcome":"created","processing":{"state":"idle"},"receipt_id":"receipt_a155d6fffeb99664b9948886dc9f6fcbc04071e4a245a8dc32dc86f3f56f1eb4","record_id":"record_f6821cb62cef6f30324ab168243c96e8347f5ca1c70eb71a349aa7029d3c8eed","source":{"corpus_id":"corpus_3b1fd5a4b8cdce8bedb84cc9ff260e6b","namespace":"wire","record_key":"eclipse-2026-10-22"},"state":"resolved","version_id":"version_06db9af127348af8676518df55126c095f1e714a17abe2471ee5b73c1596f67a"}

8.4 三种检索模式

关键词检索（lexical）：

curl -sS -X POST http://127.0.0.1:8080/v0/search \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"query":"eclipse","corpus_ids":["corpus_3b1fd5a4b8cdce8bedb84cc9ff260e6b"],"mode":"lexical","limit":5}'

实测输出（HTTP 200，输出节选，保留命中与计时字段）：

{"items":[{"availability":{"is_current":true,"searchable":true,"state":"retrieval_ready"},"excerpt":{"coordinate_system":"unicode_codepoint","end":293,"start":0,"text":"Total solar eclipse draws crowds. On Tuesday a rare total solar eclipse crossed the continent, and crowds gathered in every city along the path of totality. Astronomers reminded spectators that the moon blocked the sun for just over four minutes, while libraries handed out protective glasses."},"explanation":"keywords","part_key":"body","rank":1,"record_id":"record_f6821cb62cef6f30324ab168243c96e8347f5ca1c70eb71a349aa7029d3c8eed","vector_space_id":"core.ingest.e5-small@1","version_id":"version_06db9af127348af8676518df55126c095f1e714a17abe2471ee5b73c1596f67a"}],"retrieval_profile":{"name":"default","version":"plugin:core.retrieve@1.2.0/default"},"usage":{"cost_cents":0,"elapsed_ms":41,"paid_calls":0,"phases":{"coverage_ms":8,"hydration_ms":16,"index_query_ms":5,"plugin_rounds_ms":7,"query_encoding_ms":0,"routing_ms":3},"profiles":[{"cost_cents":0,"paid_calls":0,"plugin_version":"1.2.0","profile":"core.retrieve/default","rounds":2}],"rounds":2}}

语义检索（semantic，用文章未出现的表述命中）：

curl -sS -X POST http://127.0.0.1:8080/v0/search \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"query":"the moon blocked the sun","corpus_ids":["corpus_3b1fd5a4b8cdce8bedb84cc9ff260e6b"],"mode":"semantic","limit":5}'

实测输出（HTTP 200，输出节选；explanation 表明走向量空间，query_encoding_ms 是语义检索相对 lexical 新增的阶段耗时）：

{"items":[{"availability":{"is_current":true,"searchable":true,"state":"retrieval_ready"},"embedding_artifact_id":"0959822eee362fcea02e703f193bc2077f67a4d429d46384f7fd552e73030a0b","excerpt":{"coordinate_system":"unicode_codepoint","end":293,"start":0,"text":"Total solar eclipse draws crowds. On Tuesday a rare total solar eclipse crossed the continent, and crowds gathered in every city along the path of totality. Astronomers reminded spectators that the moon blocked the sun for just over four minutes, while libraries handed out protective glasses."},"explanation":"vectors in core.ingest.e5-small@1","part_key":"body","projection_generation_id":"generation_108b3cb0b87f82dbe1dcba5378e523a8983a82cc114f5da62e9a190d21e54d32","rank":1,"record_id":"record_f6821cb62cef6f30324ab168243c96e8347f5ca1c70eb71a349aa7029d3c8eed","segment_id":"segment_591328c46b3e9aae81aacdee11f55d81f20839320aff06864baaf78381bd12fe","segmentation_id":"segmentation_4e7b5ad81f404eb2e7d051072850c842eeee7dac17d0bc3a156c09c15352dc40","vector_space_id":"core.ingest.e5-small@1","version_id":"version_06db9af127348af8676518df55126c095f1e714a17abe2471ee5b73c1596f67a"}],"retrieval_profile":{"name":"default","version":"plugin:core.retrieve@1.2.0/default"},"usage":{"cost_cents":0,"elapsed_ms":88,"paid_calls":0,"phases":{"coverage_ms":2,"hydration_ms":18,"index_query_ms":39,"plugin_rounds_ms":1,"query_encoding_ms":24,"routing_ms":1},"profiles":[{"cost_cents":0,"paid_calls":0,"plugin_version":"1.2.0","profile":"core.retrieve/default","rounds":2}],"rounds":2}}

混合检索（hybrid）：

curl -sS -X POST http://127.0.0.1:8080/v0/search \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"query":"eclipse crowds","corpus_ids":["corpus_3b1fd5a4b8cdce8bedb84cc9ff260e6b"],"mode":"hybrid","limit":5}'

实测输出（HTTP 200，输出节选，explanation 记录融合口径）：

{"items":[{"availability":{"is_current":true,"searchable":true,"state":"retrieval_ready"},"embedding_artifact_id":"0959822eee362fcea02e703f193bc2077f67a4d429d46384f7fd552e73030a0b","excerpt":{"coordinate_system":"unicode_codepoint","end":293,"start":0,"text":"Total solar eclipse draws crowds. On Tuesday a rare total solar eclipse crossed the continent, and crowds gathered in every city along the path of totality. Astronomers reminded spectators that the moon blocked the sun for just over four minutes, while libraries handed out protective glasses."},"explanation":"keywords and vectors in core.ingest.e5-small@1, alpha 0.5, relative score fusion","part_key":"body","projection_generation_id":"generation_108b3cb0b87f82dbe1dcba5378e523a8983a82cc114f5da62e9a190d21e54d32","rank":1,"record_id":"record_f6821cb62cef6f30324ab168243c96e8347f5ca1c70eb71a349aa7029d3c8eed","segment_id":"segment_591328c46b3e9aae81aacdee11f55d81f20839320aff06864baaf78381bd12fe","segmentation_id":"segmentation_4e7b5ad81f404eb2e7d051072850c842eeee7dac17d0bc3a156c09c15352dc40","vector_space_id":"core.ingest.e5-small@1","version_id":"version_06db9af127348af8676518df55126c095f1e714a17abe2471ee5b73c1596f67a"}],"retrieval_profile":{"name":"default","version":"plugin:core.retrieve@1.2.0/default"},"usage":{"cost_cents":0,"elapsed_ms":62,"paid_calls":0,"phases":{"coverage_ms":4,"hydration_ms":26,"index_query_ms":10,"plugin_rounds_ms":1,"query_encoding_ms":16,"routing_ms":2},"profiles":[{"cost_cents":0,"paid_calls":0,"plugin_version":"1.2.0","profile":"core.retrieve/default","rounds":2}],"rounds":2}}

explanation 字段是检索走线的权威回执：keywords（词法）、vectors in <向量空间>（语义）、keywords and vectors …, alpha 0.5, relative score fusion（混合融合）；usage.phases 给出各阶段毫秒分解，可直接用于慢查询定位。

九、注意事项

  • 写操作只走两个入口：改安装形态用 setup.py init（渲染），改运行状态用 docker compose up -d（应用）；不要直接改渲染产物 compose.yaml（下次 init 被覆盖）。
  • 密钥不落日志：setup.py 报错刻意不回显异常值（防路径/响应带出密钥）；运维巡检命令输出含密钥时（如 compose exec api env）不要整屏外发，先过滤。
  • 幂等键必须唯一：/v0/corpora、/v0/records 的幂等键重复不会报错而是返回既有结果——重放请求请生成新 UUID。
  • migrate 是一次性服务：Exited (0) 是正常终态；每次 up -d 都会重跑一次幂等迁移，清理它的容器用 docker compose rm -f migrate。
  • psql/temporal 只读巡检：业务数据与工作流由引擎自有 schema 管理，人工只做 SELECT/SHOW 与备份，不做 DML/DDL。
  • 删卷等于删数据：down -v 前务必确认备份（部署篇第五章的卷清单与备份口径）。

十、常见问题

10.1 docker compose 命令报「no configuration file provided」

不在安装目录执行。compose.yaml 以 .env 的 COMPOSE_PROJECT_NAME 与安装目录绑定，cd /opt/quivr 后再执行（或用 --project-directory 显式指定）。

10.2 migrate 显示 Exited (非 0)

迁移失败。处置序列（实测口径）：docker compose logs migrate 看首条 ERROR 定位（常见为 DATABASE_URL 凭据不符、依赖未健康）→ 修正 .env → python3 setup.py init 重渲染 → docker compose rm -f migrate → docker compose up -d 重试（迁移支持重跑续做）。不要删卷重试。

10.3 temporal workflow list 报 invalid query

--query 的比较值没加引号（实测报错回显见七.3）。改成 --query "ExecutionStatus = \"Completed\"" 的完整引号形态。

10.4 psql 连接被拒（password authentication failed）

exec 进容器的方式不触发密码校验（本地 socket）；从外部连接 5432 时才用 .env 的 QUIVR_DB_PASSWORD。注意 postgres 端口未对宿主发布（仅栈内 5432/tcp），外部直连需先确认端口映射存在。

10.5 检索不到刚写入的记录

摄取是异步管道：回执 state=resolved 且 availability.searchable=true 后才可检索（轮询命令见八.3）。CPU 嵌入吞吐官方实测口径约 0.55 passages/秒（1533-token、batch 1、4 线程），大批量导入按「文档数 × 3 passages ÷ 吞吐」预估等待；large 档 ASYNC_INDEXING=true 下向量可见性还有额外滞后，以回执为准。

10.6 setup.py 报错没有细节

安装器的安全设计：Setup refused: <原因> 只在 ValueError/RuntimeError 时回显原因，其余输入错误统一 invalid installation input（防密钥泄漏）。按四.5 的触发表逐项核对输入，或用 bash -x 复查你传入的参数值（不要把 .env 内容带进 trace）。

十一、参考链接

  1. 官方单机部署文档：https://docs.quivr.thevibecompany.co/run-quivr/single-machine （查询日期 2026-10-22）
  2. 官方 Quickstart（API 最小闭环）：https://docs.quivr.thevibecompany.co/quickstart （查询日期 2026-10-22）
  3. Temporal CLI 文档：https://docs.temporal.io/cli （查询日期 2026-10-22）
  4. PostgreSQL psql 文档：https://www.postgresql.org/docs/17/app-psql.html
  5. Docker Compose CLI 文档：https://docs.docker.com/reference/cli/docker/compose/
  6. 站内延伸阅读：产品认知与选型见《quivr 介绍与选型指南》；部署全流程见《quivr Docker Compose 部署指南》；配置参数与档位见《quivr 2.0.0-alpha.7 配置参数详解》