# 功能说明 AI 搜索支持在调用搜索时进行预先的候选数据过滤，从而达到在特定范围的候选物品中搜索与用户查询相关的物品的效果。搜索过滤使用接口（Search API）控制，作用于召回阶段，即在召回时进行前置的预过滤，在满足过滤条件的物品中进行query匹配。从而避免召回后再过滤可能造成的空搜的情况。 # 操作说明在调用搜索接口时，使用`filter`参数传入过滤语法进行过滤操作。如下方示例所示： ```HTTP 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对象，其结构包含一个或多个过滤条件，每个条件由字段名、操作符和值组成，用于指定需要满足的过滤规则。 **基本结构:** ```JSON { ... "filter": { "op": "算子类型", "field": "字段名称", "conds": [条件值列表] } ... } ``` |**参数** |**类型** |**必填** |**说明** | |---|---|---|---| |`op` |String |是 |算子类型：`must` / `must_not` / `range` / `and` / `or` | |`field` |String |条件必选 |要过滤的字段名（`must`/`must_not`/`range`必填，`and`/`or`不需要） | |`conds` |Array |条件必选 |条件值数组（`range`算子不使用此参数） | |`gte` |Float |否 |大于等于（仅`range`算子使用，作为条件） | |`gt` |Float |否 |大于（仅`range`算子使用，作为条件） | |`lte` |Float |否 |小于等于（仅`range`算子使用，作为条件） | |`lt` |Float |否 |小于（仅`range`算子使用，作为条件） | ## 过滤算子使用说明 ### 1. must 算子（必须包含/交集） **条件表达式参数写法：** * `op`：传入"must" * `field`：传入过滤目标字段 * `conds`：传入过滤值列表，列表元素需与field中的类型相同 **语义：** 当`field`为整数、字符串的单个元素，含义为 **“属于”** ，即“字段中的值属于传入的过滤列表”。当`field`为整数、字符串列表，含义为 **“有交集”** ，即“目标字段和过滤列表中的元素有重叠” **支持的字段类型**： * `Int32` / `Int64` / `String` / `Bool` * `Array` / `Array` / `Array` **使用场景**： * 筛选特定状态的商品 * 限定特定地区的数据 * 选择指定类目的内容 **示例1：筛选在售商品** ```JSON { "filter": { "op": "must", "field": "status", "conds": [1, 2] } } ``` **解读**：只返回status值为1或2的商品（如1=在售，2=预售） **示例2：筛选特定类目** ```JSON { "filter": { "op": "must", "field": "category", "conds": ["女士高跟鞋", "女士运动鞋", "女士凉鞋"] } } ``` **解读**：只返回category值包含女士高跟鞋、女士运动鞋或女士凉鞋的商品 ### 2. must_not 算子（必须排除） **条件表达式参数写法：** * `op`：传入"must_not" * `field`：传入过滤目标字段 * `conds`：传入过滤值列表，列表元素需与field中的类型相同 **语义：** 当`field`为整数、字符串的单个元素，含义为 **“不属于”** ，即“目标字段值不在过滤列表中” 当`field`为整数、字符串列表，其含义为 **“没有交集”** ，即“目标字段和过滤列表中的元素不重叠” **支持的字段类型**： * `Int32` / `Int64` / `String` / `Bool` * `Array` / `Array` / `Array` **使用场景**： * 排除下架商品 * 过滤禁用账号 * 剔除特定类型内容 **示例1：排除下架和售罄商品** ```JSON { "filter": { "op": "must_not", "field": "status", "conds": [0, 3] } } ``` **解读**：不返回status为0（下架）或3（售罄）的商品 ### ### 3. range 算子（范围过滤） **条件表达式参数写法：** * `op`：传入"range" * `field`：传入过滤目标字段 * `gt`：大于 * `gte`：大于等于（对整数有效） * `lt`：小于 * `lte`：小于等于（对整数有效）含义为目标数值字段值必须在指定范围内。 **语义**：数值字段必须在指定范围内 **支持的字段类型**： * `Int32` / `Int64` / `Float` **范围参数**： * `gte`：大于等于（\>=） * `gt`：大于（\>） * `lte`：小于等于（<=） * `lt`：小于（<） **使用场景**： * 价格区间筛选 * 评分范围过滤 * 时间段筛选 **示例1：筛选价格大于等于100的商品** ```JSON { "filter": { "op": "range", "field": "price", "gte": 100.0 } } ``` **示例2：筛选价格在100\-500之间的商品** ```JSON { "filter": { "op": "range", "field": "price", "gte": 100.0, "lt": 500.0 } } ``` ### ### 4. time_range 算子（时间计算过滤） :::tip 可用于过滤标注为 **“上新时间”** 属性的字段，支持： * int64：UNIX时间戳（秒级或毫秒级） * string：ISO8601时间格式；或"YYYY\-Mm\-DD hh:mm:ss.sss"格式详情见 [检查预留字段属性](/docs/85296/1873471#bb64f3ff) ::: **条件表达式参数写法：** * `op`：传入"time_range" * `field`：传入过滤目标字段 * `gt`：晚于 * `lt`：早于 **语义：** 时间必须在特定的区间范围内。时间区间范围由 gt 和 lt 参数共同定义，其中 `gt` 表示时间下限（必须晚于该值），`lt `表示时间上限（必须早于该值），两者共同构成一个闭区间范围。 **`lt`** ** 和 ** **`gt `** **的参数值支持2类写法：** * **绝对时间条件（固定时间段）：** 使用**精确到毫秒的**UNIX时间戳传入（int） * **相对时间条件（以请求时间为参考点的相对时间段）：** 使用表达式 "now[+/\-][数值][d/h/m/s]"以字符串的形式传入。相对时间表达式示例： * `now+2d`：距当前时间2天以后的时间点 * `now-24h`：距当前时间24小时之前的时间点 **示例一：基于一个固定时间点的过滤** ```JSON { "op": "time_range", "field": "publish_time", "gt": 1767196800000, } ``` **含义：** 仅搜索2026年后发布的内容 **示例二：基于当前时间的相对时间条件过滤** ```JSON { "op": "time_range", "field": "publish_time", "gt": "now-30d", } ``` **含义：** 仅搜索最近30天发布的内容 ### 5. and 算子（逻辑与） **语义**：所有子条件必须同时满足（交集） **特点**： * 不需要`field`参数 * 通过`conds`数组嵌套多个过滤条件 * 支持嵌套任意算子（`must`/`must_not`/`range`/`and`/`or`） **使用场景**： * 同时满足多个条件 * 复合筛选逻辑 **示例1：同时筛选状态和价格** ```JSON { "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：三个条件组合** ```JSON { "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用户 ```JSON { "filter": { "op": "or", "conds": [ { "op": "must", "field": "region", "conds": ["cn", "us"] }, { "op": "must", "field": "is_vip", "conds": [true] } ] } } ``` **解读**：返回地区为中国或美国**或者**是VIP用户的数据 ### ### 快速参考 |**算子** |**语义** |**需要field** |**需要conds** |**支持类型** | |---|---|---|---|---| |`must` |在列表中/包含 |✓ |✓ |Int/String/Bool/Array | |`must_not` |不在列表中/不包含 |✓ |✓ |Int/String/Bool/Array | |`range` |数值范围 |✓ |✗ |Int/Float | |`time_range` |时间范围 |✓ |✗ |Int/String 字段必须在控制台选择**时间属性** | |`and` |逻辑与（交集） |✗ |✓ |任意算子嵌套 | |`or` |逻辑或（并集） |✗ |✓ |任意算子嵌套 | **Range算子参数对照** |**参数** |**符号** |**含义** |**示例** | |---|---|---|---| |`gte` |\>= |大于等于 |`"gte": 100` → \>= 100 | |`gt` |\> |大于/晚于 |`"gt": 100` → \> 100|\ | | | |`"gt": 1767196800000` → 在2026年1月1日0点（UTC + 8）之后 | |`lte` |<= |小于等于 |`"lte": 500` → <= 500 | |`lt` |< |小于/早于 |`"lt": 500` → < 500|\ | | | |`"lt": now+7d`→ 现在开始的7天内 | ## 完整请求示例 ### 示例1：基础单条件过滤 ```Bash 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：复杂组合过滤 ```Bash curl -X POST 'https://aisearch.cn-beijing.volces.com/api/v1/application/your_app_id/search' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -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] }, { "op":"time_range", "field":"online_date", "gt":"now-90d" } ] } }' ``` :::tip 完整接口使用说明详见：[API参考 > Search-搜索](https://www.volcengine.com/docs/85296/1544974) :::

全域AI搜索