使用元数据属性组织已索引文档,并提供上下文以指导 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" |
在提取自定义元数据之前,请在 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 时:
- 新字段会添加到搜索索引。
- 已移除的字段会从搜索索引中删除。
- 对所有文档触发完整重新索引。
- 现有向量会使用新的元数据结构更新。
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 |
| 字段名匹配 | 不区分大小写 |