API Console

文件与集合

Metadata 字段

查看 Markdown
创建 API Key 了解 Grok 4.5

Metadata 字段允许你为 collection 中的文档附加结构化属性。这些字段支持：

  • 过滤检索，将搜索结果限定为符合特定条件的文档（例如 author="Sandra Kim"）

  • Contextual embedding，将 metadata 注入 chunk 以提高检索准确度（例如在每个 chunk 前添加文档标题）

  • 数据完整性约束，强制要求字段存在，或确保字段值在文档之间唯一

创建包含 Metadata 字段的 Collection

创建 collection 时，使用 field_definitions 定义 metadata 字段：

Bash

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。
uniqueCollection 中只能有一个文档为该字段使用某个给定值。默认为 false。
inject_into_chunk将该字段的值添加到每个 embedding chunk 前，通过提供 context 提高检索效果。默认为 false。

上传包含 Metadata 的文档

在 fields 参数中以 JSON object 形式包含 metadata：

Bash

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 参数，根据 metadata 值限制搜索结果。Filter 使用 AIP-160 语法：

Bash

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"
  }'

支持的 Filter Operator

Operator示例说明
=author="Jane"等于
!=status!="draft"不等于
<、>、<=、>=year>=2020数值 / 词法比较
ANDa="x" AND b="y"两个条件都必须匹配
ORa="x" OR a="y"任一条件匹配即可

AIP-160 Filter String 示例

基础示例

Bash

# 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'

比较 Operator

Bash

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

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

逻辑 Operator

Bash

# 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")

复杂示例

Bash

# 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"

快速参考

使用场景Filter String
精确匹配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
复杂 filtercategory="finance" AND year>=2020 AND status!="archived"