知识库设置参考
查阅分块、检索、融合、重排序和文档处理字段
知识库设置同时影响文档处理和运行时检索。创建后嵌入模型与向量维度应保持稳定。
嵌入模型与维度
| 字段 | 类型 | 默认值 | 限制/说明 |
|---|---|---|---|
embedding_model_id | UUID/null | null | 知识库绑定的嵌入模型；创建后不可修改 |
embedding_dimension | integer/null | null | 由首次向量化实测并固化，后续向量维度必须严格一致 |
创建知识库时 embedding_dimension 为空，系统在首批文档切片向量化后写入实测维度。此后再更新 embedding_model_id 会被拒绝，提交维度不一致的向量则抛出 DimensionMismatchError。供应商支持范围与 Qdrant 多维集合映射见 Embedding 适配器与向量维度。
知识库的 visibility 默认为 private（仅创建者可访问），可设为 team（团队成员可访问）；public 仅为兼容保留。
跨团队共享只授予只读权限（read_only）：接收团队可以列出/查看知识库、读取文档与分块、执行检索，但上传、处理、删除和修改分块等写操作仍要求调用者属于所有者团队（通常还需要 owner/admin 角色）。private 可见性的知识库不能共享，也不能共享给所有者团队本身，且同一目标团队只能被共享一次。创建或取消共享要求所有者团队的 owner/admin 角色。
分块与重排序
| 字段 | 类型 | 默认值 | 限制 |
|---|---|---|---|
chunk_size | integer | 1000 | >=100 字符 |
chunk_overlap | integer | 100 | >=0 字符 |
separator | string/null | null | 自定义文本分隔符 |
rerank_model_id | UUID/null | null | 团队授权的重排序模型 ID；需与 rerank_enabled 配合 |
rerank_enabled | boolean | true | 是否启用重排序 |
rerank_candidate_k | integer | 10 | 1-100 |
rerank_score_threshold | number/null | null | 0-1 |
检索
| 字段 | 类型 | 默认值 | 限制/说明 |
|---|---|---|---|
search_mode | vector、fulltext 或 hybrid | null（知识库设置）；请求默认 hybrid | 混合融合向量与全文 |
top_k | integer/null | null（设置）；请求默认 5 | 请求范围 1-20；设置范围 1-100 |
score_threshold | number/null | null（设置）；请求默认 0 | 0-1 |
dense_weight | number/null | null（设置）；请求默认 1.0 | >=0 |
lexical_weight | number/null | null（设置）；请求默认 1.0 | >=0 |
rrf_k | integer/null | null（设置）；请求默认 60 | 1-1000 |
混合检索要求稠密权重或词法权重至少一个大于 0。查询长度为 1-1000 字符；批量对比最多 10 个配置且 ID 必须唯一。
底层存储：向量召回走 Qdrant，全文召回走 PostgreSQL 的 pg_search 扩展——分块写入 knowledge_lexical_chunks 表（BM25 索引 knowledge_lexical_chunks_bm25_idx，jieba 分词），标题与文档名权重为 2 倍，命中标识符（编号、错误码等）的结果优先排在前面。
生效优先级是请求参数 > 知识库设置 > 内置默认值。知识库设置只在通过该知识库检索时生效；当 Agent/工作流关联多个知识库时，每个知识库先用各自的设置召回，再对全部候选做一次全局加权 RRF（每个候选带上所属知识库的 dense_weight/lexical_weight/rrf_k，缺省 1.0/1.0/60），并由按 ID 排序后第一个绑定了 rerank 模型的活跃知识库统一重排。公开的检索端点一次只查询一个知识库。
expand_adjacent 为内部选项
检索层还有一个 expand_adjacent 开关（默认 false）：开启后会把命中切片在文档中的相邻切片一并召回，以补足上下文。它和上下文装配的 max_documents（最多几个文档）、max_chunks_per_document（每文档最多几个分块）、context_token_budget（上下文 Token 预算）一样，都是检索服务的内部请求参数，当前未通过公开检索 API 暴露，无法在知识库设置或搜索请求中配置；当前公开检索接口也不提供这些字段。
文档与状态
支持 PDF、DOC/DOCX、TXT、Markdown、HTML、CSV、XLS/XLSX、PPT/PPTX、JSON 和 URL。文档状态为 pending、processing、completed、error。站点默认单文件上传上限为 50MB，可在 1-1024MB 范围修改。
失败诊断
检索响应可能包含 inactive、missing_embedding_model、timeout、failed 诊断以及 recall、rerank、context、total 阶段耗时。生产排障依次检查文档完成状态、嵌入维度、Qdrant、PostgreSQL/pg_search、重排序模型凭据和服务商配额。
这篇文章对你有帮助吗？