文件与集合

元数据字段

元数据字段允许您为集合中的文档附加结构化属性。这些字段可以实现：

• 过滤检索 — 将搜索结果缩小到符合特定条件的文档（例如 author="Sandra Kim"）
• 上下文嵌入 — 将元数据注入到块中，以提高检索准确性（例如在每个块前添加文档标题）
• 数据完整性约束 — 强制要求必填字段或确保文档间字段值的唯一性

创建带元数据字段的集合

创建集合时使用 field_definitions 定义元数据字段：

curl -X POST "https://management-api.x.ai/v1/collections" \
  -H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "collection_name": "research_papers",
    "field_definitions": [
      { "key": "author", "required": true },
      { "key": "year", "required": true, "unique": true },
      { "key": "title", "inject_into_chunk": true }
    ]
  }'

字段定义选项

选项	描述
required	文档上传必须包含此字段。默认为 false。
unique	集合中只有一个文档可以拥有此字段的特定值。默认为 false。
inject_into_chunk	将此字段的值添加到每个嵌入块的开头，通过提供上下文来改进检索。默认为 false。

上传带元数据的文档

将元数据作为 JSON 对象包含在 fields 参数中：

curl -X POST "https://management-api.x.ai/v1/collections/{collection_id}/documents" \
  -H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY" \
  -F "name=paper.pdf" \
  -F "data=@paper.pdf" \
  -F "content_type=application/pdf" \
  -F 'fields={"author": "Sandra Kim", "year": "2024", "title": "Q3 Revenue Analysis"}'

在搜索中过滤文档

使用 filter 参数根据元数据值限制搜索结果。过滤器使用 AIP-160 语法：

curl -X POST "https://api.x.ai/v1/documents/search" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "revenue growth",
    "source": { "collection_ids": ["collection_xxx"] },
    "filter": "author=\"Sandra Kim\" AND year>=2020"
  }'

支持的过滤器操作符

操作符	示例	描述
=	author="Jane"	等于
!=	status!="draft"	不等于
<, >, <=, >=	year>=2020	数值/字典序比较
AND	a="x" AND b="y"	两个条件必须同时满足
OR	a="x" OR a="y"	任一条件满足即可

NOTE

AND 的优先级高于 OR，因此 a="x" OR b="y" AND c="z" 会被计算为 a="x" OR (b="y" AND c="z")。使用括号使分组更明确。

WARNING

不支持通配符匹配（例如 author="E*"）。所有字符串比较都是精确匹配。

WARNING

对文档中不存在的字段进行过滤将不返回任何结果。请仔细检查字段名称是否与集合的 field_definitions 匹配。

AIP-160 过滤器字符串示例

基础示例

# Equality (double or single quotes for strings with spaces)
author="Sandra Kim"
author='Sandra Kim'

# Equality (no quotes needed for simple values)
year=2024
status=active

# Not equal
status!="archived"
status!='archived'

比较操作符

# Numeric comparisons
year>=2020
year>2019
score<=0.95
price<100

# Combined comparisons (range)
year>=2020 AND year<=2024

逻辑操作符

# AND - both conditions must match
author="Sandra Kim" AND year=2024

# OR - either condition matches
status="pending" OR status="in_progress"

# Combined (OR has higher precedence than AND)
department="Engineering" AND status="active" OR status="pending"

# Use parentheses for clarity
department="Engineering" AND (status="active" OR status="pending")

复杂示例

# Multiple conditions
author="Sandra Kim" AND year>=2020 AND status!="draft"

# Nested logic with parentheses
(author="Sandra Kim" OR author="John Doe") AND year>=2020

# Multiple fields with mixed operators
category="finance" AND (year=2023 OR year=2024) AND status!="archived"

快速参考

用例	过滤器字符串
精确匹配	author="Sandra Kim"
数值比较	year>=2020
不等于	status!="archived"
多个条件	author="Sandra Kim" AND year=2024
任一条件	status="pending" OR status="draft"
分组逻辑	(status="active" OR status="pending") AND year>=2020
复杂过滤器	category="finance" AND year>=2020 AND status!="archived"