Viking AI 搜索
Viking AI 搜索
文档指南
请输入
- 文档首页
Viking AI 搜索AI搜索引擎用户手册用户指南配置 AI 搜索 在搜索时过滤
复制全文
下载 pdf在搜索时过滤
文档反馈
问问助手说明
Viking AI 搜索是一款基于生成式 AI 的企业级 AI 搜索产品，基于大模型的多模态语义表征和理解能力，结合字节跳动信息检索领域多年最佳实践，为客户提供开箱即用的 AI 搜索搭建平台服务，帮助客户轻松搭建和集成端到端的多模态图文搜索和推荐能力。
- 想要体验更多 Viking AI 搜索能力，点击前往：Viking AI 搜索引擎，企业搜推问一体化智能引擎
功能说明
AI 搜索支持在调用搜索时进行预先的候选数据过滤，从而达到在特定范围的候选物品中搜索与用户查询相关的物品的效果。
搜索过滤使用接口（Search API）控制，作用于召回阶段，即在召回时进行前置的预过滤，在满足过滤条件的物品中进行query匹配。从而避免召回后再过滤可能造成的空搜的情况。
操作说明
在调用搜索接口时，使用filter参数传入过滤语法进行过滤操作。如下方示例所示：
Filter参数说明
filter是一个JSON对象，其结构包含一个或多个过滤条件，每个条件由字段名、操作符和值组成，用于指定需要满足的过滤规则。
基本结构:
过滤算子使用说明
1. must 算子（必须包含/交集）
条件表达式参数写法：
- op：传入"must"
- field：传入过滤目标字段
- conds：传入过滤值列表，列表元素需与field中的类型相同
语义：
当field为整数、字符串的单个元素，含义为“属于”，即“字段中的值属于传入的过滤列表”。
当field为整数、字符串列表，含义为“有交集”，即“目标字段和过滤列表中的元素有重叠”
支持的字段类型：
- Int32 / Int64 / String / Bool
- Array<int32> / Array<int64> / Array<string>
使用场景：
- 筛选特定状态的商品
- 限定特定地区的数据
- 选择指定类目的内容
示例1：筛选在售商品
解读：只返回status值为1或2的商品（如1=在售，2=预售）
示例2：筛选特定类目
解读：只返回category值包含女士高跟鞋、女士运动鞋或女士凉鞋的商品
2. must_not 算子（必须排除）
条件表达式参数写法：
- op：传入"must_not"
- field：传入过滤目标字段
- conds：传入过滤值列表，列表元素需与field中的类型相同
语义：
当field为整数、字符串的单个元素，含义为“不属于”，即“目标字段值不在过滤列表中”
当field为整数、字符串列表，其含义为“没有交集”，即“目标字段和过滤列表中的元素不重叠”
支持的字段类型：
- Int32 / Int64 / String / Bool
- Array<int32> / Array<int64> / Array<string>
使用场景：
- 排除下架商品
- 过滤禁用账号
- 剔除特定类型内容
示例1：排除下架和售罄商品
解读：不返回status为0（下架）或3（售罄）的商品
3. range 算子（范围过滤）
条件表达式参数写法：
- op：传入"range"
- field：传入过滤目标字段
- gt：大于
- gte：大于等于（对整数有效）
- lt：小于
- lte：小于等于（对整数有效）
含义为目标数值字段值必须在指定范围内。
语义：数值字段必须在指定范围内
支持的字段类型：
- Int32 / Int64 / Float
范围参数：
- gte：大于等于（>=）
- gt：大于（>）
- lte：小于等于（<=）
- lt：小于（<）
使用场景：
- 价格区间筛选
- 评分范围过滤
- 时间段筛选
示例1：筛选价格大于等于100的商品
示例2：筛选价格在100-500之间的商品
4. time_range 算子 （时间计算过滤）
说明
可用于过滤标注为“上新时间”属性的字段，支持：
- int64：UNIX时间戳（秒级或毫秒级）
- string：ISO8601时间格式；或"YYYY-Mm-DD hh:mm:ss.sss"格式
条件表达式参数写法：
- 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小时之前的时间点
示例一：基于一个固定时间点的过滤
含义：仅搜索2026年后 发布的内容
示例二：基于当前时间的相对时间条件过滤
含义：仅搜索最近30天发布的内容
5. geo_distance算子 （地理位置距离过滤）
*
条件表达式参数写法：
- op：传入"geo_distance"
- field：需要进行地理位置过滤的字段名称。该字段的类型必须为包含 latitude 和 longitude 子字段的对象（Object）。
- center：距离计算的基准点，格式为 "{longitude},{latitude}" 的字符串。如果未提供此参数，则默认使用搜索接口请求中 context.location 的值作为基准点。
- radius：距离范围，格式为 "{数值}{单位}" 的字符串。例如："5km", "10000m"。
语义:
筛选出目标字段的经纬度值与指定的基准点（center）之间的距离在给定半径（radius）范围内的所有内容。
参数详解：
- field
- 字段类型要求：该字段在你的物品数据集中必须是 对象（Object） 类型，且必须包含名为 latitude（纬度）和 longitude（经度）的两个子字段。不支持对象列表（List of Object）。
- center (可选)
- 格式：一个由经度和纬度组成的字符串，格式为 "{longitude},{latitude}"。
- 默认行为：如果请求中不包含 center 参数，系统将自动使用 context.location 中提供的用户位置作为基准点。要使用此功能，你必须在请求的 context 对象中传入合法的 location 信息。
- radius
- 格式：一个由数值和单位组成的字符串，格式为 "{数值}{单位}"。
- 单位支持：支持 m（米）和 km（千米）。
- 数值精度：数值部分支持整数和小数。为保证计算精度，小数部分最多支持 7 位。如果传入的数值超过 7 位小数，系统将自动进行截断处理。
示例一：使用用户当前位置作为基准点
此示例筛选出 store_location 字段距离用户当前位置（通过 context.location 传入）5 公里以内的所有物品。
示例二：使用指定经纬度作为基准点
此示例筛选出 store_location 字段距离特定经纬度坐标（121.4737,31.2304）10000 米以内的所有物品。
6. and 算子（逻辑与）
语义：所有子条件必须同时满足（交集）
特点：
- 不需要field参数
- 通过conds数组嵌套多个过滤条件
- 支持嵌套任意算子（must/must_not/range/and/or）
使用场景：
- 同时满足多个条件
- 复合筛选逻辑
示例1：同时筛选状态和价格
解读：返回既在售（status为1或2）又在100-500价格区间的商品
示例2：三个条件组合
解读：返回分类为女士高跟鞋、品牌不是BrandX、且价格小于1000的商品
7. or 算子（逻辑或）
语义：任意子条件满足即可（并集）
特点：
- 不需要field参数
- 通过conds数组嵌套多个过滤条件
- 支持嵌套任意算子
使用场景：
- 满足任一条件即可
- 多种可选筛选路径
示例1：筛选热门地区或VIP用户
解读：返回地区为中国或美国或者是VIP用户的数据
快速参考
Range算子参数对照
完整请求示例
示例1：基础单条件过滤
占位符替换说明：
- {your_app_id} ：请替换为目标 AI 搜索应用的实际 "app_id"，可在火山引擎 AI 搜索控制台的应用详情页中获取
- <API_KEY> ：请替换为您的 API Key，API Key 可在云搜索服务控制台的 AI 搜索服务中创建和查看。
- 创建 API Key：https://www.volcengine.com/docs/6465/1359479
- 查看 API Key：https://www.volcengine.com/docs/6465/1359481
示例2：复杂组合过滤
最近更新时间：2026.08.06 12:10:52
这个页面对您有帮助吗？
有用
有用
无用
无用