创建知识库
创建原生知识库需要填写基本信息,并确定默认分段方式、Embedding 模型、检索参数和 Metadata 模板。Embedding 模型和向量维度创建后不能更换,请在提交前选定。本文介绍创建页各配置项的设置方法,以及建库后添加资料并验证的操作。
使用限制
以下配置在提交创建后不可更换或不会自动回溯,请在提交前确认:
-
Embedding 模型和向量维度创建后不能更换;如需切换,应创建新知识库并重新接入资料。
-
外部来源为单次导入,源文件后续的变更、删除和撤权不会自动同步到已导入的副本。
-
Metadata 模板改动只适用于后续新文档和替换产生的新版本,不会自动修改已有文档。
-
Metadata 过滤只能引用模板中已经声明的字段。
外部渠道权限要求
以下要求仅在使用 OSS 或飞书外部渠道时适用。配置前查看权限开通提示,执行角色和来源授权需要分别核对:
-
外部渠道导入涉及事件总线(EventBridge)依赖,来源需要具备读取权限。
-
OSS 渠道的创建页列出
AliyunAgentCoreKnowledgeBaseFullAccess与AliyunOSSReadOnlyAccess策略。 -
飞书渠道的执行角色需具备
AliyunAgentCoreKnowledgeBaseFullAccess,应用需要目标知识空间的读取权限。
打开创建页
如果要使用已有的表格存储(OTS)或百炼知识库,请切换到知识库连接 > 创建知识库连接并选择连接模板;该入口与原生知识库的创建入口不同,具体见渠道集成概览。创建原生知识库时,执行以下操作:
-
在工作空间左侧栏进入 AGENT 上下文 > 知识库。
-
选择知识库页签,单击创建知识库,进入独立创建页。
步骤一:填写基本信息
名称应便于辨认,描述写清收录范围,方便日后区分列表中的不同知识库。
| 字段 | 填写要求 | 示例 |
| 名称 | 必填 | 报销制度 |
| 描述 | 可选,最多 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 或飞书目标资料的读取权限 |