***Viking AI 搜索****是一款基于生成式 AI 的企业级 AI 搜索产品，基于大模型的多模态语义表征和理解能力，结合字节跳动信息检索领域多年最佳实践，为客户提供开箱即用的 AI 搜索搭建平台服务，帮助客户轻松搭建和集成端到端的多模态图文搜索和推荐能力。 * *想要体验更多 Viking AI 搜索能力，点击前往：* [Viking AI 搜索引擎，企业搜推问一体化智能引擎](https://www.volcengine.com/product/AI-Search-Rec) --- 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 1. 登录 Viking AI 搜索控制台。 2. 创建或获取用于调用 Viking AI 搜索的 API Key。 3. 确认该 API Key 对应的账号包含需要检索的应用和数据集。 **注意**：请勿将 API Key 写入智能体提示词、对话内容或工具参数。API Key 应通过凭证库保存，并在调用时由平台携带。

### 添加 MCP Server 1. 登录火山方舟控制台，进入 Managed Agents。 2. 创建智能体，或打开需要接入检索能力的智能体。 3. 填写完基础信息后，在智能体的 MCPs 配置区域添加Viking Search。

### 配置访问凭证 1. 在 Managed Agents 的 Credentials Vault 中创建 Vault 2. 创建 Credential,选择MCP静态凭证。 3. MCP Server 选择Viking Search，并填入 API Key 。

### 验证接入 1. 点击创建session,选择对应的 Agent , Credential 和 Environment,创建并进入调试。

2. 在智能体会话中输入以下内容，查看 item.info 是否返回预期的应用、数据集和搜索场景。 ```XML 请调用 item.info，不要调用 item.search。请列出我当前可以访问的： application_id 和应用名称；每个应用下的 dataset_id、数据集名称和 query_modes；可用的 scene_id，以及每个 scene 关联的 dataset_ids；字段的 filterable、sortable、displayable、primary_key 能力； config_version。只依据工具返回结果回答，不要猜测。 ```

3. 使用一条在 Viking AI 搜索中已验证有命中的问题发起检索，查看 item.search 是否返回预期物品。选择 item.info 中实际返回的一组： ```Plain Text application_id dataset_id 支持该 dataset 的 scene_id ``` 然后输入： ```Plain Text 请先参考刚才 item.info 的结果，选择一个支持 text 查询的数据集，以及支持该数据集的 scene。调用 item.search 搜索：“{替换成你的数据集中确定存在的关键词}”。要求： - top_k=5； - 第一轮不要添加 filters； - 不设置 sort_by； - 不指定 output_fields； - application_id、dataset_id、scene_id 必须使用 item.info 的实际返回值； - 返回 item_id、score 和 fields； - 不得补充工具结果中没有的内容。 ```

### 获取检索配置 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。