① 拿到凭据
⚠️ 在本站，页头那块写着「已登录」就说明你已经有一把了 —— 它是登录进来时拿到的，不用做任何事。下面这张表讲的是 你要在自己代码里怎么拿。
两条路 —— 看你要哪一种：
| 走哪条 | 怎么拿 | 拿到的是 |
|---|---|---|
| 登录 （人用 · 本站页头那条） |
POST /api/v1/auth/login给 user_name + password；到期用 POST /api/v1/auth/refresh 换 |
JWT（access_token）⇒ 走 Authorization: Bearer 你的令牌⚠️ access_token 只活 15 分钟，refresh_token 活 30 天 |
| 管理员建号 （程序用 · 长期 key） |
POST /api/v1/admin/create_user🔴 要管理员，非管理员回 403 |
一把 api_key ⇒ 走 X-API-Key: 你的 key⚠️ 明文只在响应里出现这一次 —— 库里只存 sha256 |
⚠️ 两条不是一回事，别混：/auth/login 发的是 JWT ⇒ 走
Authorization: Bearer；/admin/create_user 回的是一把 api_key ⇒ 走
X-API-Key。
🔴 后端两条都收（同一个依赖）—— ⛔ 但别把 JWT 塞进 X-API-Key、
⛔ 也别拿 api_key 当 Bearer 用。也 ⛔ 不要在任何地方回显请求头。
② 粘一段能跑的
最小的一次调用（内部线那条；尖括号里换成你自己的）：
# 问一句只有本库答得出的问题curl -X POST "<你的主机>/api/v1/rag/search?mode=accurate_norerank" \ -H "X-API-Key: <你的凭据>" \ -H "Content-Type: application/json" \ -d '{"question":"在保设备上门收不收工时费","citations":true,"generate_answer":true}'
⚠️ mode 走 query 参数，一共四档：
| mode | 走哪几段 | 注意 |
|---|---|---|
| accurate_norerank | 改写 + 向量 + BM25 + RRF | 默认档 —— 不依赖重排模型 |
| fast | 向量 + BM25 + RRF | 不做改写，最快 |
| accurate | 在默认档上再加 Cross-Encoder 重排 | 🔴 要本机装重排模型 |
| full | 再叠加查询扩展，覆盖最全 | 🔴 同上 |
🔴 在本 demo 这个部署上，accurate 与 full 会回 500 ——
它的镜像有意不装重排依赖（那会连带拉进 torch，550 MB 上下）。⛔ 不是你调错了。
要用那两档，得自己部署、把重排依赖装上。
⚠️ 传一个表外的值会当场得到 422，⛔ 不会被静默兜成默认档。
③ 看到真返回
返回的顶层就这几个键 —— 这段是真契约（顺着后端代码核过），⛔ 不是示意：
| 键 | 是什么 |
|---|---|
| query | 你问的那句话（原样带回） |
| docs | 检索到的每一条：id · content · source · 相关度 rrf_score · from |
| sources | 答案里的引用（只有成文时才有内容）：index（就是答案里那个 [来源 n] 的 n）· source · 相似度 similarity |
| answer | 成文的答案 —— ⚠️ 只在 generate_answer=true 时才有，否则是 null |
| timing | 各阶段的真耗时（毫秒）—— ⚠️ total_ms 不含生成那一段 |
| pipeline | 这次实际跑了哪几段 |
| mode | 这次实际用的那一档 |
| requested_by | 检索的范围 = 这个用户名下的库（⛔ 看不到别人的） |
字段名、结构、每一栏什么意思，在 总览那一页逐字段标着。 这里只说一句：它每次都是真返回，⛔ 不是画出来的样例。
第一个坑：两个默认值是关的
| 参数 | 默认 | 不给会怎样 |
|---|---|---|
| generate_answer | false | 只回检索结果，没有答案 |
| citations | false | 答案里没有引用 —— 也就没有"点回原文" |
要引用，两个都得显式打开（像上面那段 curl 那样）。
第二个坑：流式与非流式不同源
/rag/search 走的是改写 + 向量 + BM25 + RRF 那条完整链；
/rag/stream_search 是另一条更轻的链。
⇒ 同一个问题，两边结果可能不一样 —— 这是现状，⛔ 不是 bug。
第三个坑：状态码与重试
| 码 | 什么时候 | 你该做什么 |
|---|---|---|
| 401 | 没给凭据 / 凭据失效 | 重新拿 |
| 422 | 参数不合法（例如 mode 拼错） | 改参数 —— ⛔ 它不会静默兜底 |
| 429 | 被限速，或额度用尽 | 🔴 看 Retry-After，⛔ 别硬重试 |
业务错误是一个固定的三件套：
{"error": <给人看的一句话>, "code": <给机器读的码>, "status_code": <数字>}
—— 给人看的与给机器读的是分开的：⛔ 别去解析 error，认 code。
被限流 / 配额用尽那两条还会多给一个 retry_after。
🔴 但 422 不走这个体 —— 参数校验失败回的是框架自己的
{"detail":[...]}，里面每条含 loc / msg / type。
⇒ 按状态码分流，⛔ 别假定错误体只有一种形状。
给 agent 的入口（llms.txt / MCP 发现） 现状：还没有 · 点开 ▾
对照行业惯例（2026 年文档站的常规做法是给 llms.txt、MCP 发现入口、以及"每页加 .md 后缀"）——
🔴 本仓现在这三样都还没有做。这一格只如实说现状，⛔ 不是承诺。