AI 搜索支持在调用搜索时进行预先的候选数据过滤，从而达到在特定范围的候选物品中搜索与用户查询相关的物品的效果。
搜索过滤使用接口（Search API）控制，作用于召回阶段，即在召回时进行前置的预过滤，在满足过滤条件的物品中进行query匹配。从而避免召回后再过滤可能造成的空搜的情况。

在调用搜索接口时，使用filter参数传入过滤语法进行过滤操作。如下方示例所示：

curl -X POST 'https://aisearch.cn-beijing.volces.com/api/v1/application/application_id}/search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer API key' \
  -d '{
    "query": {
        "text": "query文本字符串"
        "image_url"：image文件
    },
    "page_number": 搜索页码，从 1 开始,
    "page_size": 每页搜索结果的数量,
    "user": {
        "user_id": 用户ID
    },
    "filter": 搜索过滤条件
    "dataset_id": 指定的数据集ID
}'

Filter参数说明

filter是一个JSON对象，其结构包含一个或多个过滤条件，每个条件由字段名、操作符和值组成，用于指定需要满足的过滤规则。
基本结构:

{
    ...
    "filter": {
        "op": "算子类型",
        "field": "字段名称",
        "conds": [条件值列表]
    }
    ...
}

过滤算子使用说明

1. must 算子（必须包含）

语义：字段值必须在指定的值列表中（类似SQL的IN）
支持的字段类型：

• Int32 / Int64 / String / Bool
• Array<int32> / Array<int64> / Array<string>

使用场景：

• 筛选特定状态的商品
• 限定特定地区的数据
• 选择指定类目的内容

示例1：筛选在售商品

{
  "filter": {
    "op": "must",
    "field": "status",
    "conds": [1, 2]
  }
}

解读：只返回status值为1或2的商品（如1=在售，2=预售）

示例2：筛选特定类目

{
  "filter": {
    "op": "must",
    "field": "category",
    "conds": ["女士高跟鞋", "女士运动鞋", "女士凉鞋"]
  }
}

2. must_not 算子（必须排除）

语义：字段值必须不在指定的值列表中（类似SQL的NOT IN）
支持的字段类型：

• Int32 / Int64 / String / Bool
• Array<int32> / Array<int64> / Array<string>

使用场景：

• 排除下架商品
• 过滤禁用账号
• 剔除特定类型内容

示例1：排除下架和售罄商品

{
  "filter": {
    "op": "must_not",
    "field": "status",
    "conds": [0, 3]
  }
}

解读：不返回status为0（下架）或3（售罄）的商品

3. range 算子（范围过滤）

语义：数值字段必须在指定范围内
支持的字段类型：

• Int32 / Int64 / Float

范围参数：

• gte：大于等于（>=）
• gt：大于（>）
• lte：小于等于（<=）
• lt：小于（<）

使用场景：

• 价格区间筛选
• 评分范围过滤
• 时间段筛选

示例1：筛选价格大于等于100的商品

{
  "filter": {
    "op": "range",
    "field": "price",
    "gte": 100.0
  }
}

示例2：筛选价格在100-500之间的商品

{
  "filter": {
    "op": "range",
    "field": "price",
    "gte": 100.0,
    "lt": 500.0
  }
}

解读：返回价格 >= 100 且 < 500 的商品

4. and 算子（逻辑与）

语义：所有子条件必须同时满足（交集）
特点：

• 不需要field参数
• 通过conds数组嵌套多个过滤条件
• 支持嵌套任意算子（must/must_not/range/and/or）

使用场景：

• 同时满足多个条件
• 复合筛选逻辑

示例1：同时筛选状态和价格

{
  "filter": {
    "op": "and",
    "conds": [
      {
        "op": "must",
        "field": "status",
        "conds": [1, 2]
      },
      {
        "op": "range",
        "field": "price",
        "gte": 100.0,
        "lte": 500.0
      }
    ]
  }
}

解读：返回既在售（status为1或2）又在100-500价格区间的商品

示例2：三个条件组合

{
  "filter": {
    "op": "and",
    "conds": [
      {
        "op": "must",
        "field": "category",
        "conds": ["女士高跟鞋"]
      },
      {
        "op": "must_not",
        "field": "brand",
        "conds": ["BrandX"]
      },
      {
        "op": "range",
        "field": "price",
        "lt": 1000.0
      }
    ]
  }
}

解读：返回分类为女士高跟鞋、品牌不是BrandX、且价格小于1000的商品

5. or 算子（逻辑或）

语义：任意子条件满足即可（并集）
特点：

• 不需要field参数
• 通过conds数组嵌套多个过滤条件
• 支持嵌套任意算子

使用场景：

• 满足任一条件即可
• 多种可选筛选路径

示例1：筛选热门地区或VIP用户

{
  "filter": {
    "op": "or",
    "conds": [
      {
        "op": "must",
        "field": "region",
        "conds": ["cn", "us"]
      },
      {
        "op": "must",
        "field": "is_vip",
        "conds": [true]
      }
    ]
  }
}

解读：返回地区为中国或美国或者是VIP用户的数据

快速参考

Range算子参数对照

完整请求示例

示例1：基础单条件过滤

curl -X POST 'https://aisearch.cn-beijing.volces.com/api/v1/application/{your_app_id}/search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer API Key' \
  -d '{
    "query": {
        "text": "女鞋 春夏"
    },
    "dataset_id": "106265704",
    "page_number": 1,
    "page_size": 20,
    "filter": {
        "op": "must",
        "field": "status",
        "conds": [1, 2]
    }
}'

示例2：复杂组合过滤

curl -X POST 'https://aisearch.cn-beijing.volces.com/api/v1/application/your_app_id/search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <API Key>' \
  -d '{
    "query": {
        "text": "运动鞋"
    },
    "dataset_id": "106265704",
    "page_number": 1,
    "page_size": 20,
    "filter": {
        "op": "and",
        "conds": [
            {
                "op": "must",
                "field": "category",
                "conds": ["女士运动鞋", "男士运动鞋"]
            },
            {
                "op": "range",
                "field": "price",
                "gte": 200.0,
                "lte": 1000.0
            },
            {
                "op": "must_not",
                "field": "status",
                "conds": [0, 3]
            }
        ]
    }
}'