概念

知识库与文件

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

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

处理状态

图片（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（已有向量来自原模型），更换会返回 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 参考 → · 上限与错误 →