创建知识库

更新时间:
复制 MD 格式

创建原生知识库需要填写基本信息,并确定默认分段方式、Embedding 模型、检索参数和 Metadata 模板。Embedding 模型和向量维度创建后不能更换,请在提交前选定。本文介绍创建页各配置项的设置方法,以及建库后添加资料并验证的操作。

使用限制

以下配置在提交创建后不可更换或不会自动回溯,请在提交前确认:

  • Embedding 模型和向量维度创建后不能更换;如需切换,应创建新知识库并重新接入资料。

  • 外部来源为单次导入,源文件后续的变更、删除和撤权不会自动同步到已导入的副本。

  • Metadata 模板改动只适用于后续新文档和替换产生的新版本,不会自动修改已有文档。

  • Metadata 过滤只能引用模板中已经声明的字段。

外部渠道权限要求

以下要求仅在使用 OSS 或飞书外部渠道时适用。配置前查看权限开通提示,执行角色和来源授权需要分别核对:

  • 外部渠道导入涉及事件总线(EventBridge)依赖,来源需要具备读取权限。

  • OSS 渠道的创建页列出 AliyunAgentCoreKnowledgeBaseFullAccess 与 AliyunOSSReadOnlyAccess 策略。

  • 飞书渠道的执行角色需具备 AliyunAgentCoreKnowledgeBaseFullAccess,应用需要目标知识空间的读取权限。

打开创建页

如果要使用已有的表格存储(OTS)或百炼知识库,请切换到知识库连接 > 创建知识库连接并选择连接模板;该入口与原生知识库的创建入口不同,具体见渠道集成概览。创建原生知识库时,执行以下操作:

  1. 在工作空间左侧栏进入 AGENT 上下文 > 知识库。

  2. 选择知识库页签,单击创建知识库,进入独立创建页。

步骤一:填写基本信息

名称应便于辨认,描述写清收录范围,方便日后区分列表中的不同知识库。

字段 填写要求 示例
名称 必填 报销制度
描述 可选,最多 255 个字符 员工差旅报销规则、所需材料及申请期限

步骤二:按需配置外部渠道

外部渠道可以在创建页一并配置,也可以在建库后进入外部来源 > 添加数据源追加来源。创建页提供 OSS Bucket 和飞书文档配置入口。使用本地文件时,可在建库后通过概览 > 添加文件上传。配置外部渠道前,先按“外部渠道权限要求”核对权限。

  • OSS:连接名必填、最多 127 个字符;选择 Bucket,按需设置以 / 结尾的文件路径前缀、文档类型和执行角色。

  • 飞书:连接名必填、最多 127 个字符;App ID、App Secret 和知识空间必填。仅导入文本云文档,不含电子表格、多维表格或附件。

外部来源为单次导入,源文件后续的变更、删除和撤权不会自动同步到已导入的副本。详细字段和授权入口见渠道集成概览。

步骤三:设置默认分段与向量化

分段设置

参数 默认值 可选项或范围
分段策略 智能分块 智能分块、按分隔符分块
分隔符 选择按分隔符分块后显示 选择按分隔符分块后显示;必填,按正文实际使用的分隔标记填写
分段最大长度 512 字符 1~6000 字符,不是 Token 数

首次使用可以保留智能分块,建库后对照原文检查分段结果是否完整保留了条件、结论和例外,对照入口见“建库后添加资料并验证”。使用按分隔符分块时,确认正文确实包含所填分隔符。

Embedding 模型与维度

默认模型为 text-embedding-v4,默认维度为 1024。模型下拉提供:

  • text-embedding-v4

  • text-embedding-v3

  • qwen3.7-text-embedding

  • qwen3.7-text-embedding-flash

选择 text-embedding-v4 时,可选维度为 64、128、256、512、768、1024、1536、2048。其他模型应按各自页面显示的维度选择,不套用 v4 的列表。

重要

Embedding 模型和维度创建后不支持更换。如果将来需要切换,应创建新知识库并重新接入资料,确认应用可以使用新知识库后,再将应用配置中引用的知识库更换为新库。

步骤四:设置默认检索参数

默认使用全文检索 + 向量检索:全文适合明确词语、编号和型号,向量适合语义相近的不同问法。

参数 默认值 范围与含义
TopK 10 1~100,表示最终最多返回的片段数量,不是每路各取 10 条
融合算法 RRF 可切换为加权融合
RRF 参数 k 60 控制台范围 1~200,用于双路排名融合,不控制返回条数
向量权重 0.7 选择加权融合后显示;范围 0~1,全文权重为 1 减去向量权重
模型排序 关闭 开启后显示 qwen3-rerank 和刷新模型入口

模型排序区域不支持添加自定义模型。RRF、加权融合和模型排序的作用不同:前两者处理双路结果的融合,模型排序再评估片段与问题的相关性。首次建库可保留默认参数,上传资料后再使用相同问题比较设置,详见知识库检索。

步骤五:设置 Metadata 模板

创建页默认只有以下字段:

字段名 数据类型 赋值方式
document_name STRING 引用变量文档名(DOCUMENT_NAME)

如果只需要记录文档名,可以保留默认模板;需要记录上传时间、来源或业务分类时,再添加相应字段。

引用变量

界面名称 变量
文档名 DOCUMENT_NAME
上传日期 DOCUMENT_UPLOAD_TIME
最后上传日期 SOURCE_MODIFIED_TIME
文件类型 FILE_TYPE
文件大小 FILE_SIZE
来源类型 SOURCE_TYPE
来源地址 SOURCE_URI
  • 引用变量后,数据类型随选择确定,不能手动修改。

  • 时间以毫秒记录。

  • 界面名称最后上传日期对应的变量 SOURCE_MODIFIED_TIME 实际含义是来源修改时间;该值缺失时保留未知,不用上传日期替代。

命名与赋值规则

  • 字段名只允许字母、数字和下划线,不能以数字开头。

  • 字段名不区分大小写且必须唯一。

  • 字段赋值可以使用系统变量或固定值:模板中已赋值的字段,上传时继承且不能覆盖;只有模板中尚未赋值的字段,可在上传时添加填写。

  • 模板改动只适用于后续新文档和替换产生的新版本,不会自动修改已有文档。

  • Metadata 过滤只能引用已经声明的字段。

如需让不同文档分别填写资料分类,应在模板内声明字段并留待上传时赋值,而不是先设成统一固定值再尝试覆盖。

步骤六:提交创建

核对名称、模型、维度和来源授权配置后提交创建。创建后的知识库详情包含概览、分块详情、外部来源、召回测试、集成五项导航。

建库后添加资料并验证

知识库创建后,可按需添加资料并验证处理与检索效果:

  • 添加本地文件:进入概览 > 添加文件,支持 TXT、MD、CSV、HTML、HTM、DOCX、PDF,单文件最大 50 MB。TXT、MD、CSV、HTML 需使用 UTF-8 编码。

  • 配置来源导入:进入外部来源 > 添加数据源,按步骤二的 OSS 或飞书表单准备来源和执行角色。

  • 检查处理内容:查看文件状态,文件就绪后通过查看对照原文和分段结果。

  • 检查检索效果:进入召回测试,输入文档中确有依据的问题,单击开始测试。

  • 接入应用:进入集成,查看 Endpoint、API Key 鉴权和 MCP 配置。

上传弹窗中的高级配置可以单独调整本次所选文件的分段和预处理,不修改知识库的默认设置。PDF 使用文档智能(DocMind)解析,版面中的页眉、页脚、图片、印章等不写入正文;暂不支持 DOC、PPT、PPTX。详见文档管理与解析。

处理表单提示

创建页表单提示内容需要调整时,按下表定位检查:

提示涉及的内容 检查方法
名称或描述 返回步骤一:检查名称是否为空、描述是否超过 255 个字符
按分隔符分块 返回步骤三:检查是否已填写分隔符
分段长度 返回步骤三:检查分段最大长度是否在 1~6000 字符范围内
检索参数 返回步骤四:检查 TopK 是否为 1~100、RRF 参数 k 是否为 1~200、加权融合的向量权重是否为 0~1
Metadata 返回步骤五:检查字段名是否符合命名规则、是否存在仅大小写不同的重名字段
外部渠道权限 按“外部渠道权限要求”核对:权限开通提示、执行角色,以及 OSS 或飞书目标资料的读取权限