Viking AI 搜索是一款基于生成式 AI 的企业级 AI 搜索产品，基于大模型的多模态语义表征和理解能力，结合字节跳动信息检索领域多年最佳实践，为客户提供开箱即用的 AI 搜索搭建平台服务，帮助客户轻松搭建和集成端到端的多模态图文搜索和推荐能力。

想要体验更多 Viking AI 搜索能力，点击前往：Viking AI 搜索引擎，企业搜推问一体化智能引擎

Viking AI 搜索支持通过 MCP 接入火山方舟 Managed Agents，将物品检索能力作为工具提供给智能体。配置完成后，智能体可根据用户问题检索已接入的商品、工单、FAQ 或内容数据，并基于检索结果作答。本文介绍首期 MCP 服务的接入方式、工具能力和使用限制。

功能介绍

Viking AI 搜索 MCP 服务复用应用已有的数据集和搜索策略，支持文本、图片及图文组合检索。数据接入、索引构建和搜索策略配置仍在 Viking AI 搜索中完成，无需在智能体侧重新实现检索逻辑。

核心功能	对应工具	功能描述
获取检索配置	item.info	获取当前账号可访问的应用、Item 类型数据集、关联搜索场景及字段能力，供智能体选择检索范围。
检索物品	item.search	在指定应用、数据集和搜索场景中执行检索，支持过滤、排序、返回数量及输出字段控制。

说明：首期提供上述两个只读工具，不通过 MCP 创建、修改或删除数据，也不提供推荐接口。智能体的回答由 Managed Agents 基于工具返回结果生成。

前置条件

开始接入前，请确保已完成以下准备。

已在 Viking AI 搜索中创建应用，关联 Item 类型数据集，并完成数据接入与索引构建。

已为目标数据集配置可用的搜索场景，并确认检索可正常返回结果。

具有创建或获取 Viking AI 搜索 API Key 的权限。

具有在火山方舟 Managed Agents 中创建或配置智能体、管理调用凭证的权限。

说明：item.info 返回资源配置不代表数据集已经可用于检索。当前资源发现不会显式校验数据集发布状态或索引完成状态，接入前仍需确认检索服务可用。

接入 MCP 服务

在 Managed Agents 中配置 MCP Server 地址，并通过 Credentials Vault（凭证库）保存 Viking AI 搜索 API Key，即可为智能体配置检索工具。以下配置项按功能含义说明，具体入口及界面名称以控制台为准。

获取 API Key

登录 Viking AI 搜索控制台。

创建或获取用于调用 Viking AI 搜索的 API Key。

确认该 API Key 对应的账号包含需要检索的应用和数据集。

注意：请勿将 API Key 写入智能体提示词、对话内容或工具参数。API Key 应通过凭证库保存，并在调用时由平台携带。

添加 MCP Server

登录火山方舟控制台，进入 Managed Agents。

创建智能体，或打开需要接入检索能力的智能体。

填写完基础信息后，在智能体的 MCPs 配置区域添加Viking Search。

配置访问凭证

在 Managed Agents 的 Credentials Vault 中创建 Vault

创建 Credential,选择MCP静态凭证。

MCP Server 选择Viking Search，并填入 API Key 。

验证接入

点击创建session,选择对应的 Agent , Credential 和 Environment,创建并进入调试。

在智能体会话中输入以下内容，查看 item.info 是否返回预期的应用、数据集和搜索场景。

使用一条在 Viking AI 搜索中已验证有命中的问题发起检索，查看 item.search 是否返回预期物品。

选择 item.info 中实际返回的一组：

然后输入：

获取检索配置

item.info 无业务入参，返回当前账号下可访问应用中的 Item 类型数据集及其关联搜索场景。智能体可据此确定以下信息。

配置信息	用途
应用与数据集	获取 application_id 和 dataset_id，确定本次检索使用的应用及数据集。
搜索场景	获取 scene_id 及其关联的 dataset_ids，选择支持目标数据集的搜索策略。
查询模式	通过 query_modes 查看数据集支持的查询模式，如 text、image、text_and_image。
字段能力	通过 filterable、sortable、displayable 判断字段是否可用于过滤、排序和结果输出。

执行物品检索

item.search 的主要参数如下。应用、数据集和搜索场景必须属于 item.info 返回的可访问范围，服务端会再次校验资源归属与字段能力。

参数	说明
application_id	必填，指定应用 ID。
dataset_id	必填，指定数据集 ID，必须属于所选应用。
scene_id	必填，指定搜索场景 ID，必须支持所选数据集。
query	必填，查询对象。通过 query.text 传入文本，通过 query.image_url 传入图片地址，两者至少提供一个。
filters	可选，结构化过滤条件。每项包含 field、operator 和 values，字段必须可过滤；支持 eq、in、gt、gte、lt、lte、range。
sort_by、sort_order	可选，指定可排序字段及排序方向。sort_order 支持 asc、desc，默认 desc；指定 sort_by 时生效。
top_k	可选，单次返回的物品数量上限，默认 10，取值范围为 1～20。
output_fields	可选，指定需要返回的字段，仅可选择 item.info 中声明为 displayable=true 的字段。

检索结果通过 items 返回，每条结果包含物品唯一标识 item_id 和字段数据 fields。相关性得分 score、结果总数 total 是否返回，以底层搜索接口为准；未命中时，items 为空数组。

使用图片检索

进行图片或图文组合检索时，建议向智能体提供检索服务可通过公网访问的 HTTP/HTTPS 图片地址，并传入 query.image_url。图片格式的支持范围以搜索接口的实际能力为准。

若无法获取图片地址，但智能体能够识别图片内容，可将能可靠映射到数据集字段、且需要作为硬约束的属性写入 filters，将其余视觉描述写入 query.text。同一属性不要重复表达；这种方式使用识别后的文本和属性检索，不等同于直接以图片检索。

使用限制

以下限制适用于首期接入能力。

数据范围：仅发现应用中的 Item 类型数据集。单次 item.search 指定一个数据集，不是一次请求聚合所有数据集。

账号范围：item.info 当前按账号查询应用，项目名称不参与其应用范围过滤。配置时需确认账号下可被发现的数据范围，不应将智能体的业务范围配置视为单物品库或项目级权限隔离。

字段范围：item.info 当前仅返回主键字段或可过滤字段。仅可展示、不可过滤的普通字段不会出现在字段列表中，不能假设所有源数据字段均可用于 MCP 输出。

默认返回字段：default_output_fields 为预留字段，当前搜索服务未赋值。需要稳定的结果字段时，建议显式指定允许输出的 output_fields 并验证返回结果。

常见问题

工具无法调用怎么办？

检查 MCP Server URL 是否填写正确、调用凭证是否配置到实际运行的智能体，以及 API Key 是否有效。若收到身份缺失错误，不要自行补填身份请求头，应确认请求使用的是正确的公网 MCP 入口及凭证配置。

能看到数据集，但检索失败怎么办？

先确认数据接入、索引构建和搜索场景配置已经完成，且该场景支持目标数据集。item.info 不保证返回的资源均已完成发布或索引构建。配置发生变化后，重新获取资源信息再进行检索。

过滤、排序或输出字段报错怎么办？

重新调用 item.info，检查字段名称及 filterable、sortable、displayable 标记。删除不支持的参数，或在 Viking AI 搜索中调整字段配置后重新验证。

图片检索失败怎么办？

检查图片地址是否能被检索服务访问，以及数据集是否支持对应查询模式。不要将智能体本地文件路径或平台内部文件标识当作公网图片地址。无法提供有效图片地址时，可在智能体能够识别图片的前提下，改用文本及属性条件检索。

如何提供排障信息？

保留调用时间、错误信息、相关应用及数据集 ID，以及工具结果中的 _meta.request_id 和 _meta.trace_id。其中 _meta.request_id 是业务排障使用的请求标识，可能与 HTTP 响应头中的 X-Request-Id 不同。提供排障信息时请勿包含 API Key。