Viking AI 搜索
Viking AI 搜索
文档指南
请输入
- 文档首页
Viking AI 搜索AI搜索引擎用户手册最佳实践内容社区借助 Viking AI 搜索实现个性化推荐最佳实践
复制全文
下载 pdf内容社区借助 Viking AI 搜索实现个性化推荐最佳实践
文档反馈
问问助手本文档旨在为内容社区（新闻资讯、社区论坛、知识社区、垂直行业平台、社交娱乐平台等）的业务、产品、运营及技术团队提供一份详尽的 Viking AI 搜索—个性化推荐搭建的落地实践指南。我们将结合内容分发场景下的具体需求，系统性地介绍从数据处理、冷启动策略配置到构建“搜推一体”闭环的全流程最佳实践。
一个优秀的社区，不仅要有优质的内容，更要有将内容精准送达目标用户的能力。按照本指南完成配置，您可以轻松解锁以下业务效果：
- 千人千面精准分发：基于用户行为画像，实现从“人找内容”到“内容找人”的转变，大幅提升点击率。
- 精细化流量调控：您可以灵活控制不同内容的推荐权重，比如“新内容”、“大V内容”或“本地内容”，让算法完全服务于您的运营目标。
- 用推荐理由合理种草：利用大模型生成的推荐理由，在电商或种草场景下精准满足用户需求，有效缩短决策链路，提升转化效率。
一、数据准备
在开始配置之前，请务必先做好数据准备阶段的相关工作。
说明
我们建议您对字段进行筛选，而非上传全部字段。无效的字段会增加您的Token成本、干扰大模型的判断。
您可以剔除超大且低价值的字段（如大段的 HTML 源码、Base64 编码图片），保留能帮助推荐模型理解内容语义及用户兴趣的数据字段。
物品数据集
物品数据集包含了帖子的标题、正文、视觉素材及标签等核心元数据，是推荐引擎构建多模态语义索引、实现精准内容召回的基础。
以下是一份通用的内容/社交行业物品数据的核心字段建议表，建议包含以下关键信息，会对整体效果有帮助。
如果缺失一些字段也不用担心，按您业务已有字段筛选后，上传就好。
用户行为数据集
行为数据记录了用户在社区内的浏览、点赞、评论等全链路交互痕迹，是推荐引擎动态捕捉用户兴趣演变、构建个性化画像的关键。
以下是适配内容社区/社交平台场景的行为数据核心字段建议表，建议包含以下关键信息，会对整体效果有帮助。
如果缺失一些字段也不用担心，按您业务已有字段筛选后，上传就好。
样例数据准备
在正式全量导入数据前，建议先用50-100 条有代表性的数据进行“跑通”测试，验证物品入库与行为关联的流程是否顺畅。
- 物品数据：建议准备 50-100 条 具有代表性的帖子数据（覆盖不同分类、带图文），用于构建基础内容池。
- 行为数据：建议准备 200+ 条 基于物品数据的互动数据。
数据规范与建议
二、4 步搭建内容/社区个性化推荐引擎
步骤一：创建应用
步骤二：导入数据
2.1 创建物品数据集
- 写入数据集名称。
- 选择数据类型。“私域物品数据”可用于上传结构化数据，“文档”可用于上传非结构化数据。为了搭建个性化引擎，请您选择“私域物品数据”。
- 选择数据形态，如您的数据集包含多模态内容，则需将图文和视频内容需要分别上传到对应的物品数据集。
- 直接上传JSONL格式文件，或通过JSON代码上传数据。
2.1.1 配置数据字段
- 数据导入后，大模型会扫描样例数据，推断字段类型、属性、含义和索引配置。大概需要两分钟。
- 请检查各字段的“字段属性”和“应用配置”是否符合预期。例如，确保您的物品唯一ID字段的“字段属性”被正确识别为“唯一标识”，并勾选“用于过滤”。您可以根据需要手动校准或删除字段，以确保后续的过滤和推荐策略能正确生效。
- 出现异常处理提示，并非因为您的数据真的存在问题。为了避免不必要的Token消耗，您可以选择两种计费方式：
- “不处理，视为异常数据”：若图片资产是您的核心资产，则选择此项。选择后，若该条数据中，图片这一项有问题，那么该条数据都不处理。
- “继续处理，仅跳过问题图片”：若您允许用户仅上传图片内容，或文字内容更重要，则选择此项。选择后，你得到的数据里，图片字段可能是空的，但其他字段（如 content, comments 等）是完整的。
2.2 设置物品展示样式
- 按照以下内容填充您想要展示的字段。这里只是控制台示意图，具体的页面您可以自行配置。
- 点击完成，系统会开始进行数据上传，每千条数据可能需要10分钟左右。
- 完成后，数据集状态会显示“配置已生效”，右上角会弹出“配置更新完成”，有效数据量为全部。
2.3 上传行为数据集
- 选中要上传行为数据集的应用，点击管理应用
- 选择用户行为数据集，点击创建数据集。如果已上传数据集，可以点击关联数据集，找到相应数据集，进行关联。
- 点击创建数据集，输入数据集名称，直接上传用户行为数据集或通过 JSON 代码上传数据集。
- 数据导入后，大模型会扫描样例数据，推断字段类型、属性和含义。大概需要两分钟。您可以手动校准，或删除字段。
- 将全部行为类型与字段名称相匹配，如没有找到相应的匹配项，可以手动写入行为类型含义。
- 右上角弹出“画像已构建完成”，即可体验个性化推荐配置。
步骤三：配置个性化推荐
推荐策略配置
以下是内容/社交场景中最常用的一些体验配置能力，您可以结合业务需求进行配置：
说明
不要追求一成不变的 “模板化” 配置。内容社区的不同细分场景（如新闻资讯、社区论坛、知识社区、社交娱乐平台）、不同的内容类型（图文 / 视频 / 问答）、不同的用户群，其最佳推荐策略都可能存在显著差异。
比如新闻资讯行业可能更看重 “时效性” 和 “热点话题”，而社区论坛可能更看重 “互动热度” 和 “话题争议性”，知识社区则可能更关注 “内容深度” 和 “收藏量”。
我们强烈推荐您将体验配置视为一个持续迭代的过程，并通过线上体验和用户反馈来科学地评估和选择最优策略。
3.1 推荐范围
3.1.1 关联的页面/模块
该功能负责将推荐策略与动作发生界面（event_scene）精准绑定。只有“对号入座”，系统才能从混杂的行为数据中，识别出用户在当前界面的特定行为，从而筛选出有效数据喂给模型，实现精准推荐。
从下拉框中勾选该推荐位对应的具体页面。选对后，你的策略就能在该特定场景下生效。
3.1.2 筛选推荐物品
这一功能是个性化推荐前的前置过滤机制，决定哪些物品有资格进入推荐候选池，将不符合要求的内容拦截在候选池外。
说明
- 建议将“底线”设置为过滤条件。过滤条件设置过严，可能导致推荐结果为空。
- 当筛选条件（如地域、用户关注博主等）需要根据实际场景动态调整时，配置推荐规则时，可使用“动态参数”作为占位符。配置后需在 API 请求体中通过 filter 字段传入具体参数值，才能使动态筛选生效并体验实际效果。
- 您可以配置多个筛选策略，但同一页面只能应用一个推荐策略。
- 内容合规：所有推荐流的“保底”配置，确保不推草稿内容或违规内容。此配置为静态推荐范围，配好后长期生效。
外层逻辑 | 筛选字段 (选您实际对应的字段) | 操作符 | 条件值 | 配置图片 |
且 | 内容状态 (status) | 等于 | 已发布 | |
且 | 审核状态 (is_audit) | 等于 | 机审通过 | |
- 同城推荐：适合“附近”页面的个性化推荐策略，仅推荐用户附近的内容，更具地域接近性。此配置为动态推荐范围，需在 API 请求体中通过 filter 字段传入具体参数值。由于同一页面只能应用一个推荐策略，建议在限制地理位置的同时，也对帖子合规性进行限制。
外层逻辑 | 筛选字段 | 操作符 | 条件值 (动态参数) | 配置图片 |
且 | 帖子纬度 (latitude) | 在区间 | {{latitude_l}}～{{latitude_r}} | |
且 | 帖子经度 (longitude) | 在区间 | {{longitude_l}}～{{longitude_r}} | |
以下是一个 API 请求体示例，展示了如何在 `filter` 字段中通过拼接字符串的方式传递动态参数值：
3.1.3 兜底策略配置
- 使用场景：新用户没有行为数据时，或者推荐服务故障时，可采用兜底策略。
- 多策略优先级：平台支持配置多个兜底策略，但同一时间仅会执行优先级最高的策略。当高优先级策略无法满足推荐需求（如物品数量不足）时，才会依次触发低优先级策略。
建议兜底配置：
3.2 推荐数量
推荐数量需 按页面展示布局调整 ，平衡用户浏览体验与转化效率，通常设置为10或20。
不建议配置过大的推荐数量。若推荐 API 的page_size参数大于 400，接口将返回InvalidParameter错误。
3.3 排序
3.3.1 提权/降权规则
您可以根据内容属性、创作者等级或时效性，动态调整内容在推荐流中的排序权重。以下是适配内容/社交行业的一些调权建议。
策略名称 | 策略目标 | 涉及示例字段 | 逻辑条件 | 建议调权数值 | 配置图片 |
新内容扶持 | 确保用户每次刷新都能看到新内容 | post_time （发布时间） | post_time 小于 24小时 | +25% | |
旧帖清洗 | 减少老旧内容出现 | | post_time 大于 180天 | -50% | |
高互动内容扶持 | 引导用户参与高热度讨论，活跃社区氛围 | comments （评论） | comments 大于 50 | +20% | |
爆款助推 | 鼓励易于传播的内容，帮助平台获取外部流量 | likes、shares （喜欢、分享） | likes 大于 200 shares 大于 100 | +30% | |
内容形态调优 | 在注重视觉体验的社区，减少纯文字内容的占比 | images （图片链接） | images 不等于 "" | +10% | |
特定内容提权 | 对官方主推的话题进行提权，强化社区核心氛围 | tags （标签） | tags = 主推关键词 | +25% | |
3.3.2 去除重复推荐
在指定时间窗口内，不向用户推送已推荐的内容，避免用户对推荐内容产生厌倦。您可以设置去重的时间和数量限制：
- 已曝光的物品去重（长期 / 中短期去重）
- 已下发的物品去重（防曝光延迟 / 短期防刷）
3.3.3 推荐多样性
为避免用户快速产生腻烦感，我们可以设置多样性策略。
策略名称 | 策略目标 | 连续推荐物品数 | 当物品字段满足某一条件相同时 | 最多展示数 | 配置图片 |
内容类型打散 | 避免同一形式内容刷屏 | 5 | tags 相同 | 2 | |
作者 / 创作者打散 | 避免推荐页变成个人主页 | 10 | user_id相同 | 1 | |
3.3.4 置顶物品
- 置顶物品会占用正常的推荐位置，展示逻辑优先于所有个性化推荐算法。
- 当设置了置顶推荐后，平台会优先展示置顶物品，而不会因这些物品已被用户曝光过而进行过滤。
- 如需置顶某内容，请按照内容唯一标识（item_id）进行置顶。
3.4 推荐话术配置
除了个性化配置外，我们还支持智能推荐理由的生成。
以下是娱乐类社区内容推荐理由的提示词示例，您可以根据业务需求，对提示词进行修改。
步骤四：上传全量数据与推荐功能上线
上述配置完成后，您可以上传更多物品数据和行为数据，以及集成推荐 API 到您的业务场景来进一步体验测试。
4.1 上传全量数据
- 点击数据集列表，找到需要上传全量数据的数据集
- 点击查看，进入该数据集的详情页面。
- 点击数据导入。
- 物品数据支持本地JSONL文件导入、API导入两种方式。API导入支持批量导入与实时导入，详细步骤请查看：
- 行为数据支持本地JSONL文件导入、API导入两种方式。API导入详细步骤请查看：
4.2 集成推荐 API
- 同步配置至 API ：体验界面策略配置完成后，在配置页右上角，点击 “更新配置” 按钮，保存对应策略。
- 创建与集成 API Key ：
- 创建一个新的 API Key，并将其与您要上线的搜索策略绑定。
- 选择“推荐”，复制平台提供的 API 调用示例代码 ，交给您的技术团队。
- 技术团队需将推荐 API 接口集成到您的应用前端页面中，从而获取推荐结果并展示给用户。
4.3 推荐功能集成逻辑
为了在内容或社交平台中提供流畅且精准的“信息流”与“相关阅读”体验，我们强烈建议您采用“前端交互 -> 业务后端中转 -> AI 推荐服务”的标准化三层架构。
4.3.1 完整的数据流转路径
- 前端触发推荐请求：用户打开 App 首页（触发主页推荐），或点击进入某篇图文/视频的详情页（触发详情页推荐）。前端向业务后端请求新一批内容。
- 业务后端封装与状态注入：业务后端拦截请求后，向 AI 推荐 API 发起 POST 请求。在此阶段，后端除附加 API Key 进行鉴权外，需显式注入关键的系统与用户变量：
- 注入当前操作者的唯一标识 user_id。
- 注入当前会话的 session_id。
- 若为详情页场景，需通过 parent_items 明确传入当前正在浏览的内容 ID。
- 引擎执行召回与排序：AI 推荐引擎基于用户画像、内容特征以及后端传入的过滤条件，执行复杂的双端匹配与排序，最终输出个性化的内容列表。
- 后端数据格式化与前端渲染：业务后端接收到推荐结果（rec_results）后，将其与平台自身的互动数据（如：该用户是否已点赞、收藏）进行拼装，返回给前端。前端解析后，将其渲染为无限下拉的瀑布流或视频列表。
4.3.2 为什么必须通过“业务后端”进行中转与管控？
在推荐系统中，业务后端的网关作用不仅限于隐藏 API Key，更是保障推荐质量、控制带宽成本的核心枢纽：
- 🛡️ 流量防刷与数据瘦身
- 严格限制单次返回量：为保障接口极速响应，平台强制限制 page_size 上限为 400。由业务后端严格控制该参数，可避免前端误传超大数值导致 InvalidParameter 错误引发大面积白屏。
- 字段按需提取：推荐引擎底层可能包含数百个内容特征字段。后端应通过 output_fields 仅提取前端渲染必备的字段（如 title、cover_url、author_name），大幅降低外网带宽消耗与解析延迟。
- 🔄 避免内容疲劳与重复曝光 (session_id 控制)： 对于高热度的“置顶内容”，如果用户反复刷新依然看到同一条内容，会严重影响体验。由后端统一生成并维护 session_id 传递给 AI 接口，平台即可自动判断并在 24 小时内对同一会话跳过已曝光的置顶内容（见 ForcedItems 生效逻辑）。
- ⚖️ 合规响应与业务规则兜底 ：
- 隐私合规：当用户在 App 隐私设置中选择“关闭个性化推荐”时，业务后端可直接在请求中下发 disable_personalize: true，此时引擎将自动降级为无个性化的高热度内容召回，确保平台合规。
- 内容安全过滤：后端可以通过 filter 强制设定仅推荐审核状态为“已通过”且可见级别为“公开”的内容，将底层数据安全的最后一道防线留在后端。
- 📍 场景上下文的动态注入 (context)： 对于具有“同城”或“附近”属性的社交圈子，业务后端可安全解析用户的 IP 或基站位置，转换为 context.location 传入引擎，从而实现本地创作者和内容的自动提权。
三、常见问题与优化建议
推荐返空
也可按照如下流程排查：
排查模块 | 排查逻辑与建议 |
行为数据质量 |
|
操作流程 | 整体流程是：应用关联至少一个物品数据集“生效” → 再关联并“生效”用户行为数据集 → 再点击“生效配置” 请注意，行为数据集的关联和生效，必须在图文数据集生效后进行。 |
筛选推荐物品 | 核心是没有满足上面所有条件的物品，拆开看 可能的原因：
|
去除重复推荐 | 都被曝光去重、下发去重过滤掉了 |
兜底策略配置 | 兜底策略是否合理 |
物品数据质量 |
|
推荐耗时长
推荐耗时长，有可能是因为召回请求物品属性信息时属性信息值非常大，获取超时导致的。
可以检查物品表中是否有值很大的字段，类似下面这些字段：
排查项 | 排查逻辑与建议 |
召回结果重排 | 召回结果重排数量是否太大。建议配置为20个 |
用于文搜的是否有大字段 | |
推荐场景用户画像为空 / 个性化测试用户兴趣标签为空
- 用户画像标签的计算逻辑是：
- 统计用户最近7天内正向行为的物品id，根据物品id去物品表里查询对应的兴趣标签字段。
- 兴趣标签字段 是火山大模型分析物品数据集智能选择的某个物品字段。
- 建议：
- 所以先检查该用户最近7天内有没有正向行为
- 如果有，再看正向行为的物品是否在物品表里找得到
- 如果也能找得到，查一下智能选择的物品字段是否合适，不合适的话，手动调整。
推荐结果不够个性化
在推荐内容不符合该预期时，可能是数据配置上有些问题。
若想要有较强的个性化推荐效果，需依次确认以下数据是否存在问题：
- 行为数据
- 数据量足够大
- 包括曝光和正向行为（比如点击、购买、播放等）
- 行为数据集中的物品ID要能在物品数据里找到
- 物品数据
检查 Viking AI 自动选择的“兴趣维度”字段是否合适，好的字段需满足以下三个标准：
- 契合业务： 能真实代表业务侧想抓取的用户兴趣（通常选择“商品类目”或“资讯标签”）。
- 覆盖率高： 绝大部分物品的这个字段都必须有值，不能大面积留空。
- 区分度好： 该字段的枚举值分布要均匀。
- 不能太集中： 避免大部分物品都共用同一个标签（失去区分意义）。
- 不能太稀疏： 避免枚举值太多，导致每个枚举值下面只有寥寥几个物品。
- 文搜字段配置：查“核心信息”纯度
- 只选核心： 在配置用于文搜的字段时，只勾选包含关键信息的字段（如标题、类目）。
- 剔除冗余： 坚决不勾选非核心信息。如果塞入太多无关杂乱的字段，会稀释核心信息的浓度，导致系统检出大量不相关的物品。
详情页场景未推出父物品相似物品
排查项 | 排查逻辑 |
API传参 | 检查：传参格式是否正确。正确传参如下： |
父物品 | 检查：父物品 ID 必须在物品数据集内 |
推荐返回的物品重复
排查模块 | 排查逻辑 |
去除重复推荐 | 如果去重配置太小，则每次新推荐时，只过滤掉最近很少推出过的物品，就可能会推出之前已经推荐过的物品。 （当前曝光去重可设置的最大时间窗口为7天） |
行为数据实时性 | 检查曝光的行为数据 有没有实时的同步到火山平台？ 如果延迟较高，【已曝光物品去重】获取不到曝光的物品，导致消重失败（建议：提高行为数据实时性+增加【已下发的物品去重】 |
打散未生效
排查项 | 排查逻辑与建议 |
确认是否真的没有生效 |
|
是不是打的太散了 | 如果把内容打的非常散，比如连续非常多个 都不允许出现同样维度，就可能因为 召回的物品根本没有这么多种类，导致最后打散失败。 并且从个性化推荐的实践来说，每个用户在某些维度上是有特定偏好的，比如某用户最近就是想买某种款式的羽绒服类，某用户就是喜欢某一个作者的作品，那在推荐上就是会多给用户返回这类物品。 最后，因为打散只在一刷内生效，如果一刷返回10个物品，打散若配置 连续20个最多展示n个，则也很可能会出现badcase。 所以建议： |
打散字段是否合适 |
|
推荐-过滤没有生效
一条动态过滤需要平台配置 且 API传参过来才能生效，缺失一个 都会不生效，会在接口返回的omitted_params里标识。
可按下表依次排查可能的原因：
原因分类 | 排查逻辑 与 建议 |
API里传了，但是筛选策略里没有配置 | |
筛选策略里配置动态筛选，但是API传参里没有传 | |
动态过滤传参不合法 | |
逻辑条件check | 筛选过滤表达式逻辑 「不属于」后若是列表，是都匹配上才符合，不是 有交集就行 如果希望是匹配上一个就过滤，则可以用多个表达式来表示 |
其他 逻辑条件选错 | check配置的是否是「或」的逻辑 |
说明
最近更新时间：2026.08.09 01:06:40
这个页面对您有帮助吗？
有用
有用
无用
无用