摘要
摘要 :一份常见的错误配置里给出一段 YAML,写着
knowledge_base.embedding、retrieval.similarity_threshold、weight、top_k,看起来很像 RAG 调优参数。实际打开平台会发现根本没有这份配置文件:Nexent 的知识库是界面创建、上传后自动解析切片,切片可在"Chunk 详情"里查看、搜索、增删改,检索质量主要靠创建时绑定的向量模型 + 系统重排模型槽位 + 分片治理。本文按官方流程写清创建知识库、上传与六种处理状态、Embedding 选型、Chunk 管理、知识库总结、绑定到智能体检索工具的完整链路,给出 20 MB 等真实限制数值,并把"引用溯源、召回调优、多知识库挂载"落到平台里真实存在的操作上。
文章目录
-
- 摘要
- [一、为什么这份 YAML 配置不存在:背景与常见误写](#一、为什么这份 YAML 配置不存在:背景与常见误写)
- 二、环境与版本:知识库与核心组件介绍
- 三、操作步骤
-
- [3.1 创建知识库(六个配置项)](#3.1 创建知识库(六个配置项))
- [3.2 上传文件与真实限制](#3.2 上传文件与真实限制)
- [3.3 六种处理状态:判断"能不能检索"的唯一依据](#3.3 六种处理状态:判断"能不能检索"的唯一依据)
- [3.4 Embedding 选型](#3.4 Embedding 选型)
- [3.5 Chunk 分片管理(真正的调优现场)](#3.5 Chunk 分片管理(真正的调优现场))
- [3.6 知识库概览与自动描述(影响智能体选库)](#3.6 知识库概览与自动描述(影响智能体选库))
- [3.7 绑定到智能体:`knowledge_base_search`](#3.7 绑定到智能体:
knowledge_base_search)
- 四、关键配置与排查
-
- [4.1 官方列出的失败原因(逐条对照,不用猜)](#4.1 官方列出的失败原因(逐条对照,不用猜))
- [4.2 服务侧排查命令](#4.2 服务侧排查命令)
- [4.3 重排模型:官方认可的检索精度手段](#4.3 重排模型:官方认可的检索精度手段)
- [4.4 多知识库与检索链路时序](#4.4 多知识库与检索链路时序)
- 五、结果验证
- 六、常见问题
- 七、总结
- 参考资料
一、为什么这份 YAML 配置不存在:背景与常见误写
先看这段容易照抄出错的配置:
yaml
knowledge_base:
embedding:
type: "your-embedding"
model: "your-embedding-model"
retrieval:
similarity_threshold: 0.7
weight: 0.8
top_k: 5
对照官方文档,问题有三层:
| 层级 | 虚构写法 | 官方事实 |
|---|---|---|
| 配置载体 | 手写 YAML 文件 | 全部在界面完成:创建面板、上传区、Chunk 详情、工具配置弹窗 |
| Embedding | embedding.type / model |
创建知识库时选向量模型 ,分 embedding 与 multi_embedding 两类;创建时绑定,贯穿知识库整个生命周期 |
| 检索参数 | similarity_threshold / weight / top_k |
官方知识库配置页未提供这些参数或界面字段;检索侧可操作的是 Chunk 搜索、分片治理、系统重排模型槽位 |
更要紧的是"创建时绑定、生命周期不可换"这条:向量模型选错,不是改个阈值就能救,通常要重建知识库 。所以调优的重点应该前移到选型阶段,而不是幻想有个 top_k 滑杆。
#mermaid-svg-HJRLD2hVQaVJiz9a{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-HJRLD2hVQaVJiz9a .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-HJRLD2hVQaVJiz9a .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-HJRLD2hVQaVJiz9a .error-icon{fill:#552222;}#mermaid-svg-HJRLD2hVQaVJiz9a .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-HJRLD2hVQaVJiz9a .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-HJRLD2hVQaVJiz9a .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-HJRLD2hVQaVJiz9a .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-HJRLD2hVQaVJiz9a .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-HJRLD2hVQaVJiz9a .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-HJRLD2hVQaVJiz9a .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-HJRLD2hVQaVJiz9a .marker{fill:#333333;stroke:#333333;}#mermaid-svg-HJRLD2hVQaVJiz9a .marker.cross{stroke:#333333;}#mermaid-svg-HJRLD2hVQaVJiz9a svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-HJRLD2hVQaVJiz9a p{margin:0;}#mermaid-svg-HJRLD2hVQaVJiz9a .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-HJRLD2hVQaVJiz9a .cluster-label text{fill:#333;}#mermaid-svg-HJRLD2hVQaVJiz9a .cluster-label span{color:#333;}#mermaid-svg-HJRLD2hVQaVJiz9a .cluster-label span p{background-color:transparent;}#mermaid-svg-HJRLD2hVQaVJiz9a .label text,#mermaid-svg-HJRLD2hVQaVJiz9a span{fill:#333;color:#333;}#mermaid-svg-HJRLD2hVQaVJiz9a .node rect,#mermaid-svg-HJRLD2hVQaVJiz9a .node circle,#mermaid-svg-HJRLD2hVQaVJiz9a .node ellipse,#mermaid-svg-HJRLD2hVQaVJiz9a .node polygon,#mermaid-svg-HJRLD2hVQaVJiz9a .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-HJRLD2hVQaVJiz9a .rough-node .label text,#mermaid-svg-HJRLD2hVQaVJiz9a .node .label text,#mermaid-svg-HJRLD2hVQaVJiz9a .image-shape .label,#mermaid-svg-HJRLD2hVQaVJiz9a .icon-shape .label{text-anchor:middle;}#mermaid-svg-HJRLD2hVQaVJiz9a .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-HJRLD2hVQaVJiz9a .rough-node .label,#mermaid-svg-HJRLD2hVQaVJiz9a .node .label,#mermaid-svg-HJRLD2hVQaVJiz9a .image-shape .label,#mermaid-svg-HJRLD2hVQaVJiz9a .icon-shape .label{text-align:center;}#mermaid-svg-HJRLD2hVQaVJiz9a .node.clickable{cursor:pointer;}#mermaid-svg-HJRLD2hVQaVJiz9a .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-HJRLD2hVQaVJiz9a .arrowheadPath{fill:#333333;}#mermaid-svg-HJRLD2hVQaVJiz9a .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-HJRLD2hVQaVJiz9a .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-HJRLD2hVQaVJiz9a .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-HJRLD2hVQaVJiz9a .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-HJRLD2hVQaVJiz9a .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-HJRLD2hVQaVJiz9a .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-HJRLD2hVQaVJiz9a .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-HJRLD2hVQaVJiz9a .cluster text{fill:#333;}#mermaid-svg-HJRLD2hVQaVJiz9a .cluster span{color:#333;}#mermaid-svg-HJRLD2hVQaVJiz9a div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-HJRLD2hVQaVJiz9a .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-HJRLD2hVQaVJiz9a rect.text{fill:none;stroke-width:0;}#mermaid-svg-HJRLD2hVQaVJiz9a .icon-shape,#mermaid-svg-HJRLD2hVQaVJiz9a .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-HJRLD2hVQaVJiz9a .icon-shape p,#mermaid-svg-HJRLD2hVQaVJiz9a .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-HJRLD2hVQaVJiz9a .icon-shape .label rect,#mermaid-svg-HJRLD2hVQaVJiz9a .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-HJRLD2hVQaVJiz9a .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-HJRLD2hVQaVJiz9a .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-HJRLD2hVQaVJiz9a :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 已就绪
解析失败/入库失败
租户管理员登录
创建知识库 选向量模型
上传文件 单文件 20MB 以内
六种处理状态
Chunk 详情 查看与搜索分片
悬停状态图标看原因与建议
生成知识库总结
智能体高级设置启用 knowledge_base_search
对话检索并核对来源与相关性评分

图1:虚构检索阈值与官方知识库调优手段的对照。
二、环境与版本:知识库与核心组件介绍
| 项目 | 采集方式 |
|---|---|
| Nexent 版本 | cat VERSION / 页面左下角 |
| 登录角色 | 租户管理员(超管无权创建知识库) |
| 已配置的向量模型 | 模型配置页 → 向量模型槽位,连通性 🟢 |
| 是否已配重排模型 | 模型配置页 → 重排模型槽位 |
| 测试文档 | 文件名、格式、大小、页数 |
| 个人知识库容量 | 知识库列表底部"个人知识库容量" |
前置条件:平台部署完成、租户管理员登录、已在模型配置页配好向量模型且连通性为绿色。官方文档明确"向量模型配置会影响知识库的稳定运行"。
三、操作步骤
3.1 创建知识库(六个配置项)
入口:知识库模块 → 点击左侧知识库列表上方的 "创建知识库" 按钮。
| 配置项 | 官方说明 | 实操要点 |
|---|---|---|
| 知识库名称 | 必填、必须唯一,只能含中文字符或小写字母,不允许空格、斜杠等特殊字符,输入时自动查重 | 别用 合同 2026、rag/test 这类名字 |
| 向量模型 | 选 文本向量模型(embedding) 或 多模态向量模型(multi_embedding),后者自动支持图片等非文本内容向量化 |
创建后贯穿整个生命周期,先想清楚再建 |
| 用户组 | 多选,控制哪些用户组可见可用;普通用户创建个人知识库时该项不显示 | 团队共享才配 |
| 组内权限 | 可编辑(EDIT) 维护内容 / 只读(READ_ONLY) 只能查看和检索 / 私有(PRIVATE) 仅创建者和管理员;普通用户固定私有 |
对外只给 READ_ONLY |
| 保留源文件 | 开启后保留原始文件,便于重新处理或下载;关闭则只保留向量化数据 | 建议开启,便于溯源 |
| 存储配额 | 可选,支持 GB/MB 单位切换;接近配额时系统预警 |
大文档批次前先设 |
配置项填完,可在下方文件上传区直接选文件(也可跳过后续再传);文件上传后系统自动创建知识库并开始处理文件。
3.2 上传文件与真实限制
操作:选中知识库 → 点击文件上传区域多选,或直接拖拽 → 系统自动提取文本并向量化 → 在列表里看处理状态。
text
单个文件大小上限:20 MB(超过无法上传)
支持的格式:
文本/结构化 : .txt .md .csv .json .xml
网页 : .html
PDF/电子书 : .pdf .epub
Word : .doc .docx
PowerPoint : .pptx
Excel : .xlsx
官方原话很关键:"文件后缀受支持不代表一定能提取有效内容 。例如纯扫描 PDF 可能没有可解析文本,需要先完成 OCR 或使用支持图像内容的处理方式"------后者正是创建时该选 multi_embedding 的场景。
上传前系统还会检查知识库自身配额、租户容量、个人知识库容量 。个人知识库容量显示在列表底部(已用空间 / 有效配额,管理员未设上限则显示"无限制");达到配额会阻止继续创建内容或上传文件,但不会删除已有数据。提示容量不足时,先删除不再需要的文件,或联系管理员调配额。
3.3 六种处理状态:判断"能不能检索"的唯一依据
| 状态 | 含义 |
|---|---|
| 等待处理 | 已上传,排队等待解析 |
| 解析中 | 正在提取文件文本内容 |
| 入库中 | 文本向量化并写入向量数据库 |
| 已就绪 | 处理完成,可正常检索使用 |
| 解析失败 | 悬停状态图标看详细错误原因与排查建议 |
| 入库失败 | 同上 |
把光标移到状态图标上还能看到进度,官方举例:"已处理 23/50 个切片"。这一步是"结果验证"最硬的证据,比任何"配置成功"的自述都可靠。
3.4 Embedding 选型
| 类型 | 作用 | 官方示例 |
|---|---|---|
文本向量模型 embedding |
纯文本文档向量化 | BGE、M3E |
多模态向量模型 multi_embedding |
同时处理文本与图片 | DashScope、Jina |
选型判断顺序:文档是不是纯文本 → 是否含扫描件/图片/表格图 → 业务语言是中文为主还是多语 → 模型能力与切片大小的权衡。官方提醒:"根据模型能力选择合适的文档切片大小和单次请求切片量。切片越小,系统越稳定,但文件解析质量也会受到影响 。"这是一条真实的、可写进调优章节的权衡关系,比虚构的 0.7 阈值有用得多。
若要对比不同向量模型的效果,官方没有提供"换模型"按钮,可操作做法是建两个知识库、绑定不同向量模型、上传同一份文档、用同一组问题在 Chunk 详情里对比召回分片------把两组结果截图填进【待实测填写】。
3.5 Chunk 分片管理(真正的调优现场)
- 点击知识库名称进入文档列表;
- 点击上方 "Chunk 详情" 标签页;
- 顶部列出知识库所有文档,点某个文档查看其分片;
- 分片以卡片分页展示,包含内容、字符数、来源、相关性评分等信息。
搜索框会同时进行关键词与语义匹配,按综合相关性展示结果;清空搜索框回到当前文档的分页列表。这正是验证"召回准不准"的官方入口。手动管理能力:
| 操作 | 说明 |
|---|---|
| 创建 | 手动添加自定义分片,创建后跳到最后一页查看 |
| 编辑 | 修改分片文本并重新生成对应向量 |
| 删除 | 删除不需要的分片,同步更新分片数 |
| 下载 | 把单个分片内容下载为 .txt |
3.6 知识库概览与自动描述(影响智能体选库)
- 点击知识库名称右侧 "详细内容" 进入概览页;
- 选一个大语言模型,点 "自动总结";
- 编辑生成的总结使其准确;
- 点 "保存"。
官方说明:"建议您为每个知识库配置准确且完整的总结描述,这有助于后续智能体在进行检索时,准确选择合适的知识库 "------多知识库场景下,这句话就是"挂载多个库还不串味"的关键。概览页还能设定时自动总结频率:1 小时 / 3 小时 / 6 小时 / 1 天 / 1 周,系统会判断是否有文档更新,无变更则跳过本次生成。
3.7 绑定到智能体:knowledge_base_search
官方原文:"创建智能体时,在工具配置区域的高级设置 启用对应的知识库检索工具,并选择关联的知识库。"Nexent 原生知识库使用 knowledge_base_search 工具。工具配置弹窗里可以看到已绑定的知识库列表,支持搜索与勾选,每个知识库旁边会显示其向量模型信息,帮助确认兼容性------这也是"多知识库挂载"时检查兼容性的真实位置。

图2:文档格式上限与六种处理状态的链路矩阵。
四、关键配置与排查
4.1 官方列出的失败原因(逐条对照,不用猜)
text
文件不存在 / 超过 20 MB / 类型不受支持
文件无法提取有效文本 / 包含不受支持的换行格式
向量模型繁忙 / 维度不匹配 / 单次切片数量超过模型并行度
Elasticsearch、对象存储或数据处理服务不可用
知识库、租户或个人知识库容量已达上限
官方给的处置原则:"根据提示修复问题后重新上传;如果问题指向平台服务或存储空间,请联系管理员处理,不要连续重复提交相同文件。"这条尤其值得写进文章------反复点重试只会制造更多失败任务。
4.2 服务侧排查命令
bash
# 先确认数据处理与向量相关容器都在 Up 状态,再判断检索是否有结果
# 若有容器反复重启,回到第 4 章按状态排查,不要直接重建知识库
docker ps --format 'table {{.Names}}\t{{.Status}}'
docker logs nexent-data-process --tail 100
docker logs nexent-config --tail 100
文档解析与向量化依赖数据处理服务;配合模型配置页的"检查模型连通性"确认向量模型为 🟢。这三步能覆盖"文档一直停在解析中"的大部分情况。
4.3 重排模型:官方认可的检索精度手段
模型配置页对重排模型的定义:"用于初筛后的文档进行语义匹配与评分,确保最相关的核心答案能够排在首位,以提升检索的准确性和效率。"所以检索排序调优的真实落点是在模型配置页指定重排模型槽位 ,不是在知识库里调 weight。若未配重排模型,召回结果只经过初筛,排序质量自然受限。
4.4 多知识库与检索链路时序
智能体 数据处理服务 知识库模块 操作者 智能体 数据处理服务 知识库模块 操作者 #mermaid-svg-8wR56yRMg9NK9ATj{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-8wR56yRMg9NK9ATj .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-8wR56yRMg9NK9ATj .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-8wR56yRMg9NK9ATj .error-icon{fill:#552222;}#mermaid-svg-8wR56yRMg9NK9ATj .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-8wR56yRMg9NK9ATj .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-8wR56yRMg9NK9ATj .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-8wR56yRMg9NK9ATj .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-8wR56yRMg9NK9ATj .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-8wR56yRMg9NK9ATj .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-8wR56yRMg9NK9ATj .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-8wR56yRMg9NK9ATj .marker{fill:#333333;stroke:#333333;}#mermaid-svg-8wR56yRMg9NK9ATj .marker.cross{stroke:#333333;}#mermaid-svg-8wR56yRMg9NK9ATj svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-8wR56yRMg9NK9ATj p{margin:0;}#mermaid-svg-8wR56yRMg9NK9ATj .actor{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-8wR56yRMg9NK9ATj text.actor>tspan{fill:black;stroke:none;}#mermaid-svg-8wR56yRMg9NK9ATj .actor-line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-8wR56yRMg9NK9ATj .innerArc{stroke-width:1.5;stroke-dasharray:none;}#mermaid-svg-8wR56yRMg9NK9ATj .messageLine0{stroke-width:1.5;stroke-dasharray:none;stroke:#333;}#mermaid-svg-8wR56yRMg9NK9ATj .messageLine1{stroke-width:1.5;stroke-dasharray:2,2;stroke:#333;}#mermaid-svg-8wR56yRMg9NK9ATj #arrowhead path{fill:#333;stroke:#333;}#mermaid-svg-8wR56yRMg9NK9ATj .sequenceNumber{fill:white;}#mermaid-svg-8wR56yRMg9NK9ATj #sequencenumber{fill:#333;}#mermaid-svg-8wR56yRMg9NK9ATj #crosshead path{fill:#333;stroke:#333;}#mermaid-svg-8wR56yRMg9NK9ATj .messageText{fill:#333;stroke:none;}#mermaid-svg-8wR56yRMg9NK9ATj .labelBox{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-8wR56yRMg9NK9ATj .labelText,#mermaid-svg-8wR56yRMg9NK9ATj .labelText>tspan{fill:black;stroke:none;}#mermaid-svg-8wR56yRMg9NK9ATj .loopText,#mermaid-svg-8wR56yRMg9NK9ATj .loopText>tspan{fill:black;stroke:none;}#mermaid-svg-8wR56yRMg9NK9ATj .loopLine{stroke-width:2px;stroke-dasharray:2,2;stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-8wR56yRMg9NK9ATj .note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-8wR56yRMg9NK9ATj .noteText,#mermaid-svg-8wR56yRMg9NK9ATj .noteText>tspan{fill:black;stroke:none;}#mermaid-svg-8wR56yRMg9NK9ATj .activation0{fill:#f4f4f4;stroke:#666;}#mermaid-svg-8wR56yRMg9NK9ATj .activation1{fill:#f4f4f4;stroke:#666;}#mermaid-svg-8wR56yRMg9NK9ATj .activation2{fill:#f4f4f4;stroke:#666;}#mermaid-svg-8wR56yRMg9NK9ATj .actorPopupMenu{position:absolute;}#mermaid-svg-8wR56yRMg9NK9ATj .actorPopupMenuPanel{position:absolute;fill:#ECECFF;box-shadow:0px 8px 16px 0px rgba(0,0,0,0.2);filter:drop-shadow(3px 5px 2px rgb(0 0 0 / 0.4));}#mermaid-svg-8wR56yRMg9NK9ATj .actor-man line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-8wR56yRMg9NK9ATj .actor-man circle,#mermaid-svg-8wR56yRMg9NK9ATj line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;stroke-width:2px;}#mermaid-svg-8wR56yRMg9NK9ATj :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 创建知识库并选向量模型 上传文档 解析 切片 向量化 返回 已就绪 与分片数 Chunk 详情搜索验证召回 自动总结并保存 高级设置启用 knowledge_base_search 并勾选知识库 对话时检索 返回分片与相关性评分
图:知识库文档的六种处理状态
链路图讲创建与绑定的先后,时序图讲检索调用,这张状态图专门解释"文档上传后到底在等什么"。只有进入"已就绪"的文档才参与检索;解析失败要回到格式与 20 MB 限制检查,而不是反复调检索参数。
#mermaid-svg-13tLbKAhHp0CRAVS{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-13tLbKAhHp0CRAVS .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-13tLbKAhHp0CRAVS .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-13tLbKAhHp0CRAVS .error-icon{fill:#552222;}#mermaid-svg-13tLbKAhHp0CRAVS .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-13tLbKAhHp0CRAVS .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-13tLbKAhHp0CRAVS .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-13tLbKAhHp0CRAVS .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-13tLbKAhHp0CRAVS .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-13tLbKAhHp0CRAVS .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-13tLbKAhHp0CRAVS .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-13tLbKAhHp0CRAVS .marker{fill:#333333;stroke:#333333;}#mermaid-svg-13tLbKAhHp0CRAVS .marker.cross{stroke:#333333;}#mermaid-svg-13tLbKAhHp0CRAVS svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-13tLbKAhHp0CRAVS p{margin:0;}#mermaid-svg-13tLbKAhHp0CRAVS defs #statediagram-barbEnd{fill:#333333;stroke:#333333;}#mermaid-svg-13tLbKAhHp0CRAVS g.stateGroup text{fill:#9370DB;stroke:none;font-size:10px;}#mermaid-svg-13tLbKAhHp0CRAVS g.stateGroup text{fill:#333;stroke:none;font-size:10px;}#mermaid-svg-13tLbKAhHp0CRAVS g.stateGroup .state-title{font-weight:bolder;fill:#131300;}#mermaid-svg-13tLbKAhHp0CRAVS g.stateGroup rect{fill:#ECECFF;stroke:#9370DB;}#mermaid-svg-13tLbKAhHp0CRAVS g.stateGroup line{stroke:#333333;stroke-width:1;}#mermaid-svg-13tLbKAhHp0CRAVS .transition{stroke:#333333;stroke-width:1;fill:none;}#mermaid-svg-13tLbKAhHp0CRAVS .stateGroup .composit{fill:white;border-bottom:1px;}#mermaid-svg-13tLbKAhHp0CRAVS .stateGroup .alt-composit{fill:#e0e0e0;border-bottom:1px;}#mermaid-svg-13tLbKAhHp0CRAVS .state-note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-13tLbKAhHp0CRAVS .state-note text{fill:black;stroke:none;font-size:10px;}#mermaid-svg-13tLbKAhHp0CRAVS .stateLabel .box{stroke:none;stroke-width:0;fill:#ECECFF;opacity:0.5;}#mermaid-svg-13tLbKAhHp0CRAVS .edgeLabel .label rect{fill:#ECECFF;opacity:0.5;}#mermaid-svg-13tLbKAhHp0CRAVS .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-13tLbKAhHp0CRAVS .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-13tLbKAhHp0CRAVS .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-13tLbKAhHp0CRAVS .edgeLabel .label text{fill:#333;}#mermaid-svg-13tLbKAhHp0CRAVS .label div .edgeLabel{color:#333;}#mermaid-svg-13tLbKAhHp0CRAVS .stateLabel text{fill:#131300;font-size:10px;font-weight:bold;}#mermaid-svg-13tLbKAhHp0CRAVS .node circle.state-start{fill:#333333;stroke:#333333;}#mermaid-svg-13tLbKAhHp0CRAVS .node .fork-join{fill:#333333;stroke:#333333;}#mermaid-svg-13tLbKAhHp0CRAVS .node circle.state-end{fill:#9370DB;stroke:white;stroke-width:1.5;}#mermaid-svg-13tLbKAhHp0CRAVS .end-state-inner{fill:white;stroke-width:1.5;}#mermaid-svg-13tLbKAhHp0CRAVS .node rect{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-13tLbKAhHp0CRAVS .node polygon{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-13tLbKAhHp0CRAVS #statediagram-barbEnd{fill:#333333;}#mermaid-svg-13tLbKAhHp0CRAVS .statediagram-cluster rect{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-13tLbKAhHp0CRAVS .cluster-label,#mermaid-svg-13tLbKAhHp0CRAVS .nodeLabel{color:#131300;}#mermaid-svg-13tLbKAhHp0CRAVS .statediagram-cluster rect.outer{rx:5px;ry:5px;}#mermaid-svg-13tLbKAhHp0CRAVS .statediagram-state .divider{stroke:#9370DB;}#mermaid-svg-13tLbKAhHp0CRAVS .statediagram-state .title-state{rx:5px;ry:5px;}#mermaid-svg-13tLbKAhHp0CRAVS .statediagram-cluster.statediagram-cluster .inner{fill:white;}#mermaid-svg-13tLbKAhHp0CRAVS .statediagram-cluster.statediagram-cluster-alt .inner{fill:#f0f0f0;}#mermaid-svg-13tLbKAhHp0CRAVS .statediagram-cluster .inner{rx:0;ry:0;}#mermaid-svg-13tLbKAhHp0CRAVS .statediagram-state rect.basic{rx:5px;ry:5px;}#mermaid-svg-13tLbKAhHp0CRAVS .statediagram-state rect.divider{stroke-dasharray:10,10;fill:#f0f0f0;}#mermaid-svg-13tLbKAhHp0CRAVS .note-edge{stroke-dasharray:5;}#mermaid-svg-13tLbKAhHp0CRAVS .statediagram-note rect{fill:#fff5ad;stroke:#aaaa33;stroke-width:1px;rx:0;ry:0;}#mermaid-svg-13tLbKAhHp0CRAVS .statediagram-note rect{fill:#fff5ad;stroke:#aaaa33;stroke-width:1px;rx:0;ry:0;}#mermaid-svg-13tLbKAhHp0CRAVS .statediagram-note text{fill:black;}#mermaid-svg-13tLbKAhHp0CRAVS .statediagram-note .nodeLabel{color:black;}#mermaid-svg-13tLbKAhHp0CRAVS .statediagram .edgeLabel{color:red;}#mermaid-svg-13tLbKAhHp0CRAVS #dependencyStart,#mermaid-svg-13tLbKAhHp0CRAVS #dependencyEnd{fill:#333333;stroke:#333333;stroke-width:1;}#mermaid-svg-13tLbKAhHp0CRAVS .statediagramTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-13tLbKAhHp0CRAVS :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 上传成功
文本抽取完成
生成 Chunk
写入向量库
格式不支持或超过 20 MB
重新上传修正后的文件
可被 knowledge_base_search 检索
等待处理
解析中
切片中
向量化中
已就绪
处理失败

图3:切片召回与引用溯源关系的概念。
五、结果验证
| 验证项 | 判断依据 |
|---|---|
| 文档处理完成 | 文件状态为 已就绪;悬停状态图标可见切片处理进度 |
| 分片可查 | Chunk 详情能列出分片卡片(内容、字符数、来源、相关性评分) |
| 检索可用 | 智能体高级设置已启用 knowledge_base_search 并勾选知识库;对话能返回带来源的结果 |
六、常见问题
Q1:文件一直"解析中"? 先 docker logs nexent-data-process --tail 100,再确认向量模型连通性为 🟢;官方文档说明向量模型配置影响知识库稳定运行。
Q2:扫描版 PDF 上传成功但搜不到内容? 后缀受支持不代表能提取文本,需先 OCR,或创建时选 multi_embedding。
Q3:报"维度不匹配"? 官方列出的失败原因之一,与创建时绑定的向量模型有关;因模型生命周期绑定,通常需按修复后的配置重建知识库,不要连续重复提交同一文件。
Q4:上传被拒? 核对单文件 20 MB、格式白名单、知识库/租户/个人容量配额。
Q5:多知识库检索串了? 为每个知识库写准确完整的总结描述,官方说明这有助于智能体准确选择合适的知识库;并在工具配置弹窗核对各库向量模型兼容性。
Q6:召回排序不理想? 在模型配置页指定重排模型槽位;在 Chunk 详情里删掉噪声分片或编辑后重新生成向量;调整文档切片大小与单次请求切片量(切片越小越稳定,但解析质量会受影响)。
七、总结
Nexent 的知识库 RAG 链路没有那份流行的 YAML:创建面板里选的向量模型会绑定整个知识库生命周期,文档上传后在六种状态间流转,"已就绪"和悬停可见的切片进度才是可检索的判断依据;真正的调优现场是 Chunk 详情------那里能查看分片内容、字符数、来源与相关性评分,能按关键词与语义综合检索,能增删改分片并重新生成向量;排序精度靠模型配置页的重排模型槽位,多知识库靠准确的总结描述和工具配置弹窗里的向量模型兼容性提示。20 MB 单文件上限、12 类支持格式、六种处理状态、容量配额机制,都是复现这条链路时必须对上的硬指标。把 similarity_threshold、weight、top_k 换成这些真实操作,文章才站得住。文中【待实测填写】的模型名、测试文档、切片数、召回结果与四组截图,需要你在自己的平台里跑一遍补齐------这部分只能由你在自己的平台里跑一遍得到。
最后补一句边界:本文讲的是平台原生知识库,外接第三方向量库或自行改写检索链路的场景不适用。20 MB、六种状态、Chunk 详情这些都是当前界面里的真实约束,版本升级后可能调整,发布前对照官方知识库配置页复核一次即可。
参考资料
- Nexent 仓库(AtomGit):https://atomgit.com/ModelEngine/nexent
- Nexent 官方文档 · 知识库配置:https://modelengine-group.github.io/nexent/zh/user-guide/agent-development/knowledge-configuration.html
- Nexent 官方文档 · 模型配置(向量/重排模型槽位):https://modelengine-group.github.io/nexent/zh/user-guide/agent-development/model-configuration.html
- Nexent 官方文档 · 常见问题:https://modelengine-group.github.io/nexent/zh/quick-start/faq.html
- Nexent 用户指南 · 首页:https://modelengine-group.github.io/nexent/zh/user-guide/home-page.html