# 概念 (/docs/cloud/services/knowledge/concepts)



## 知识库与文件 [#知识库与文件]

知识库使用 `vs_` 开头的 ID。`/knowledge/v1` 和 `/openai/v1/vector_stores` 访问相同数据；前者额外提供恢复、失败重试、分段、事件和搜索解释。所有示例都使用 API Key，从服务端调用。

先通过文件服务上传，得到 `file_id`，再将其加入知识库。知识库内文件 ID 与源文件 ID 相同。重复加入已有文件会返回原记录，不重新处理，也不会应用新的属性或分段策略。批次也一样：已在库中的文件出现在批次里不会重新入库，批次的 attributes 和 chunking\_strategy 只作用于新加入的文件。要改属性，用更新文件接口（`POST /vector_stores/{id}/files/{file_id}`）；要换分段策略，先移除该文件再重新加入。

## 处理状态 [#处理状态]

| status       | 含义     | 下一步                                |
| ------------ | ------ | ---------------------------------- |
| in\_progress | 内容正在处理 | 轮询文件状态或使用 SDK 的 poll 方法            |
| completed    | 内容已可搜索 | 发起搜索                               |
| failed       | 处理失败   | 查看 last\_error，修正文件或通过原生 API retry |
| cancelled    | 已取消处理  | 先移除，再按需要重新添加                       |

图片（PNG、JPEG、GIF、WebP）入库的内容是模型生成的画面描述，不是逐字 OCR：图中的文字可能被概括或遗漏，搜索命中的是这段描述。图片入库比文本慢，实测单张约数秒到数十秒，多个文件同时入库时更久。

原生 API 的 `praxis.stage` 给出 queued、parse、chunk、embed、index 进度。完成后 stage 为 null。知识库的 status 由处理情况与过期状态决定；空库也可为 completed，因此它不表示库内一定有内容。

批次把多个文件添加到同一知识库，最多 500 个。`file_ids` 和逐文件配置的 `files` 二选一。使用 `files` 时忽略顶层 attributes 和 chunking\_strategy。取消只对进行中的批次生效；对已完成、已失败或已取消的批次调用取消，会原样返回当前状态。

## 分段 [#分段]

默认 auto 会转为每段 800 个估算 token、相邻重叠 400 token。static 可设置每段 100–4096 token；重叠不得超过段大小的一半。token 数为估算值，不等同于具体模型 tokenizer 的结果。

原生 API 可读取每段的文本、序号、估算 token、页码、UTF-16 起止位置和相邻重叠量；页码可能为 null。读取文件 content 得到的是分段文本，拼接时需考虑重复内容。`usage_bytes` 是已入库文件的源文件大小（字节），未完成入库的文件为 0；知识库的 `usage_bytes` 是其中所有文件之和。

## 搜索结果 [#搜索结果]

`/openai/v1/vector_stores/{id}/search` 与 OpenAI 一致：**每个文件一条结果**，`content` 按相关度从高到低列出该文件命中的文本块，`score` 取其中最高分，`max_num_results` 限制的是文件数（默认 10、最多 50）。`/knowledge/v1` 的搜索**按块返回**，同一文件可能出现多次，适合直接拼接成模型的参考资料。

`query` 可为字符串或字符串数组；数组会以换行连接后共同搜索。`filters` 筛选文件属性，支持 eq、ne、gt、gte、lt、lte、in、nin 和 and/or 组合。比较按类型匹配，例如数字 1 与字符串 "1" 不相同。

默认混合语义与关键词检索，权重为 0.7/0.3。原生 API 可通过 `ranking_options.hybrid_search` 调整权重并用 `praxis.explain: true` 查看解释；在 OpenAI 兼容接口传 hybrid\_search 会返回 400。只有 ranker 为 default-2024-11-15 时请求重排；none、auto 和省略时使用初始排序。重排的效果尚未单独实测。

score 在 0–1 之间，是同一次搜索内的相对排序依据，不是相关性概率，也没有默认下限：库里不相关的内容也会返回，分数可能与相关内容很接近（实测相关文件 0.70，不相关文件 0.61–0.62）。需要过滤时设置 `ranking_options.score_threshold`，低于该值的结果不返回；OpenAI 同样默认不设阈值。可以从 0.5 起试，再用自己的资料和典型问题看相关与不相关结果的分数，逐步上调到不再误删相关结果为止。

`rewrite_query: true` 时先改写查询再检索，见下方「模型」。`has_more` 表示还有更多结果被 `max_num_results` 截掉；搜索不支持翻页，`next_page` 恒为 null。原生结果附带 chunk\_id、page、span；兼容结果不含这些字段和 praxis。

## 模型 [#模型]

每个知识库有三个模型角色，创建时可在原生 API 的 `models` 里指定，之后用更新接口修改；不指定就用默认模型。读取知识库时 `models` 返回各角色当前生效的模型。

| 角色              | 作用                                                  | 默认模型              |
| --------------- | --------------------------------------------------- | ----------------- |
| `embedding`     | 给分段和查询生成向量                                          | bge-m3            |
| `rerank`        | `ranking_options.ranker` 为 default-2024-11-15 时重排结果 | bge-reranker-base |
| `query_rewrite` | 搜索设置 `rewrite_query: true` 时改写查询                    | qwen3.8-flash     |

库中已有文件后不能更换 `embedding`（已有向量来自原模型），更换会返回 409；其他角色随时可改。模型必须在模型目录中并支持该角色，嵌入模型还必须输出 1024 维向量，否则返回 400。某个角色设为 null 恢复它的默认模型，`models: null` 恢复全部默认。OpenAI 兼容接口不返回 `models`，传入会返回 400（与 OpenAI 对未知参数的处理一致），但搜索同样按知识库设置的模型执行。

`rewrite_query: true` 时，搜索前先用 `query_rewrite` 模型把问题改写成简洁的检索查询（例如「退货以后多久能收到退款？」→「退款到账时间」），用改写结果检索，`search_query` 返回改写后的查询；`query` 为数组时逐条改写。每次改写是一次小模型调用，会产生费用，按模型用量计费，并增加约 1–2 秒延迟。改写失败、超过 5 秒或返回为空时，该条查询回退为原文继续搜索，不会让搜索失败。不传或为 false 时不调用模型。

## 更新、过期与删除 [#更新过期与删除]

name 省略时默认为空字符串；创建时不接受 null，更新时 null 会清空名称。metadata 更新会替换全部内容；null 清空。description 被接受后丢弃，不能用来保存说明。未知写入字段当前会被忽略，拼写错误不一定报错。

`expires_after` 只接受 last\_active\_at 和 1–365 天；搜索和添加文件刷新活动时间，null 取消自动过期。删除后，知识库进入「删除中」：`/knowledge/v1` 读取返回 `status: deleting` 和清除时间 `purge_at`，默认列表不再显示（用 `status=deleting` 可以列出），搜索、更新和添加文件返回 409；7 天内可以 `restore` 恢复，也可以用 `purge` 立即永久删除（不可撤销）。`/openai/v1/vector_stores` 与 OpenAI 一致，删除后读取返回 404。删除知识库不会删除「文件」中的源文件。

[API 参考 →](/docs/api/native/knowledge) · [上限与错误 →](/docs/cloud/services/knowledge/limits-and-errors)