跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

元数据属性

最后更新 查看 MarkdownAgent 设置

使用元数据属性组织已索引文档,并提供上下文以指导 AI 响应。本页介绍内置元数据属性与自定义元数据 schema。要在查询时按这些属性筛选搜索结果,请参阅筛选。

内置元数据属性

AI Search 会自动从已索引文档中提取以下元数据属性:

属性 描述 示例
filename 文件名。 guide.pdf 或 docs/getting-started/guide.pdf
folder 对象的文件夹或前缀。 对于 docs/getting-started/guide.pdf,文件夹为 docs/getting-started/
timestamp 对象上次修改时的 Unix 时间戳(毫秒)。比较会向下取整到秒。 1735689600000(2025-01-01 00:00:00 UTC)

自定义元数据属性

自定义元数据允许你定义用于筛选搜索结果的额外字段。你可以将结构化元数据附加到文档,并按类别、版本或任意自定义字段筛选查询。

支持的数据类型

类型 描述 示例值
text 字符串值 "documentation"、"blog-post"
number 数值(解析为 float) 2.5、100、-3.14
boolean 布尔值 true、false、1、0、yes、no
datetime 日期与时间值 "2026-01-15T00:00:00Z"

定义 schema

在提取自定义元数据之前,请在 AI Search 配置中使用 custom_metadata 字段定义 schema。schema 指定要提取的字段及其数据类型。

custom_metadata: [
	{ field_name: "category", data_type: "text" },
	{ field_name: "version", data_type: "number" },
	{ field_name: "is_public", data_type: "boolean" },
];

Schema 约束:

  • 每个 AI Search 实例最多 5 个自定义元数据字段
  • 字段名不区分大小写,并以小写存储
  • 字段名不能使用保留名称:timestamp、folder、filename
  • 更改 schema 会触发所有文档的完整重新索引

向文档添加自定义元数据属性

如何附加自定义元数据属性取决于你的数据源:

  • R2 存储桶:使用 S3 兼容的自定义标头(x-amz-meta-*)设置元数据。示例请参阅 R2 自定义元数据。
  • 网站:在 HTML 页面中添加 <meta> 标签。详情请参阅网站自定义元数据。
  • 内置存储:通过 Items API 上传文件时附加元数据。

重新索引行为

当你修改 custom_metadata schema 时:

  1. 新字段会添加到搜索索引。
  2. 已移除的字段会从搜索索引中删除。
  3. 对所有文档触发完整重新索引。
  4. 现有向量会使用新的元数据结构更新。

元数据存储与筛选

AI Search 会将每个向量的元数据存储在共享的 10 KiB 紧凑 JSON UTF-8 封装中。该封装包含字段名、JSON 语法、必需的 AI Search 系统元数据以及客户元数据。这不是按字段设置的限制。

已配置的自定义字段优先于未声明的来源元数据。AI Search 会以确定性方式组装元数据,并保留能够放入的完整值。当仍有容量时,已配置的字符串值可在 UTF-8 字符边界处截断。必需的 AI Search 元数据始终会保留。

每个已索引字符串仅前 64 个 UTF-8 字节可筛选。更长的字符串仍可存储,但前 64 字节之后的内容不可筛选。有关 Vectorize 详情,请参阅 限制 和 元数据筛选。

限制

约束 限制
最大自定义字段数 每个 AI Search 实例 5 个
每个向量的元数据 总计 10 KiB,包含系统数据与 JSON 语法
可筛选的已索引字符串 每个字符串的前 64 个 UTF-8 字节
保留字段名 timestamp、folder、filename
字段名匹配 不区分大小写

这篇文档对您有帮助吗?