Viking AI 搜索
Viking AI 搜索
文档指南
请输入
- 文档首页
Viking AI 搜索AI搜索引擎用户手册API参考OpenAPIAI 搜词库管理 OpenAPI 使用文档
复制全文
下载 pdfAI 搜词库管理 OpenAPI 使用文档
文档反馈
问问助手Viking AI 搜索是一款基于生成式 AI 的企业级 AI 搜索产品，基于大模型的多模态语义表征和理解能力，结合字节跳动信息检索领域多年最佳实践，为客户提供开箱即用的 AI 搜索搭建平台服务，帮助客户轻松搭建和集成端到端的多模态图文搜索和推荐能力。 想要体验更多 Viking AI 搜索能力，点击前往：Viking AI 搜索引擎，企业搜推问一体化智能引擎
概述
本文档面向接入字节跳动 Viking AI 搜索 词库能力的开发者，覆盖控制台层（Console Top OpenAPI）与数据层（aisearch-online Data OpenAPI）两套接口共 6 个核心方法：
整体调用顺序：
CreateDict → （可选）CheckDictInput → WriteDictTerms → BindDictToScenes → 在线生效；后续可通过ListDictTerms/DeleteDictTerms 维护词条内容。
⚠️注意
本文档中所有请求示例均以华北环境域名为示例展示，实际调用时请根据业务所在地域替换为对应的 regional 域名。
词库（Dict）业务模型速览
词库是搜推链路上对查询（query）做扩展、纠错、补全或推荐的离线词条集合，5 种类型与单条词条 schema 如下：
关键限额：
每租户每个 Type 最多 5 个词库；单词库最多 50,000 条词条；同义词词条内单边最多 10 个同义词；建议单次请求 items ≤ 1000 条（服务端通用上限 10,000，建议保持 1000 以更好与限流策略配合）。
控制台 OpenAPI（词库元信息）
通用调用约定
- 请求 URL：https://open.volcengineapi.com/?Action=<Action>&Version=2025-03-01
- HTTP Method：POST，Content-Type: application/json
- 签名：火山 Volc Signature V4（AK/SK），与火山其他 OpenAPI 一致。
- 响应包裹：火山 OpenAPI 标准结构。
公共业务参数：
CreateDict — 创建词库
创建一个新的词库（仅元信息，不含词条内容）。EnableIdempotent=true 且租户内已存在同名词库时，接口直接返回已有词库，不重复创建。
接口元信息
请求参数
响应参数（Result 字段）
请求 / 响应示例
业务规则：
- 参数合法性校验：Name 长度 1~100、Description ≤ 1000、Type 必须是上文枚举之一。
- 同租户同 Type 下的词库总量上限为 5，超出会返回 QuotaExceeded。
- DictId 由后端生成（dict- + 数字 ID），调用方不可指定；若启用幂等且命中已有同名词库，则返回该词库的既有 DictId。
CheckDictInput — 词库格式与限额校验
在执行真正的词条写入前，对一批待入库词条做预校验：表头、字段数、字段格式（非空 / 非负整数）、词条总量、同义词数量等，全部在内存中完成，不会真正落库。该接口同时支持「文件方式（TosKey）」与「直接传词条数组（Entries）」两种入参，但二者互斥。
接口元信息
请求参数
DictEntry 结构：
不同 Type 对 Fields 的列数与含义要求：
响应参数（Result 字段）
Errors 中的子字段（任一存在即代表对应类型的校验失败，不影响 HTTP 200 返回，调用方需自行判断 Errors 是否非空）：
请求 / 响应示例
业务规则
- 入参互斥：TosKey 与 Entries 同时非空将报 DictInputInvalid。
- CSV 表头：表头字段名按前缀匹配预期表头，多余列会被忽略；首列允许带 UTF-8 BOM。
- 空行容忍：所有字段都为空白的行会被跳过，不计入 BatchEntryCount。
BindDictToScenes — 将词库绑定到搜索场景
将一个已有词库挂载到一个或多个搜索场景的对应配置位上。绑定成功后，会自动触发场景配置上线，让在线检索链路立即生效。
接口元信息
请求参数
DictScene 结构：
响应
成功时返回空对象 Result: {}；失败通过 ResponseMetadata.Error 表达。
请求 / 响应示例
绑定行为说明
- 去重写入：对同一个 Scene 重复绑定同一 DictId 是幂等的，后端会跳过已存在条目。
- 强制上线：每个 Scene 绑定完成后会推送配置，请确保场景本身处于可上线的合法状态。
- DatasetId 校验：当词库类型需要 DatasetId 但传入的 ID 在场景的配置中不存在时，将返回 InvalidParameter:DatasetID。
词条数据 OpenAPI（aisearch-online）
通用调用约定
- 接入域名：https://aisearch.cn-beijing.volces.com（火山 APIG）
- HTTP Method：POST，Content-Type: application/json
- 请求体字段命名：snake_case（如 dict_id、page_size、_data_tos_link）。
- 鉴权：火山 AK/SK，Volcengine Signature V4；签名关键参数：Region=cn-beijing、Service=aisearch、Date=YYYYMMDDTHHMMSSZ（UTC）。
公共请求 Header
公共响应包裹（CommonResponse）
服务统一返回 CommonResponse 结构。
成功（HTTP 200）：业务字段在 result 中（注意：不是 data）：
失败（HTTP 4xx / 5xx）：错误信息在 error 对象中，错误码以字符串名承载在 error.code：
说明
调用方对齐要点：
(1) 成功字段名 result，不是 data；(2) 错误码字符串放在 error.code；(3) 应基于字符串错误码 + HTTP 状态码组合判断；(4) 三个接口的请求体均不接受 term_type 字段——服务端从 dict_id 反查类型。
WriteDictTerms — 批量写入 / 编辑词条
将一批词条写入指定词库。_last_data 缺省表示新增；同时携带 _last_data 与 _current_data 时表示编辑（先按 _last_data 删除旧条目，再按 _current_data 写入新条目）。
接口元信息
路径与请求参数
注意：当 items 与 _data_tos_link 同时非空时，服务端优先处理 TOS 链接并忽略 items，不会报错；调用方仍应明确二选一以避免误用。
TermItem 结构：
响应（result 字段）
请求 / 响应示例
A. 内联写入猜你想搜词条：
B. 编辑同义词（先删旧、再写新）：
C. TOS 大文件批量导入：
TOS 文件每行一条业务字段 JSON，例如 {"query":"iphone 16","query_count":100}，不要包裹 _current_data。
响应示例：
业务规则
- 二选一：items 与 _data_tos_link 同时非空时服务端优先处理 TOS 链接，调用方应保证只传一种。
- 大小限制：建议内联 items ≤ 1000；服务端通用上限 10,000 条，超过返回 ItemsTooLarge。
DeleteDictTerms — 批量删除词条
通过 _last_data 携带的词条内容定位到具体的文档并删除。不支持只传 dict_id 触发整库清空（整库清理请走控制台 DeleteDict）。
接口元信息
请求参数
TermDeleteItem 结构：
响应（result 字段）
请求 / 响应示例
业务规则
- 删除使用内容定位：_last_data 必须填写当前 ES 中存在的完整业务字段；缺字段或字段值与 ES 中不一致将无法命中目标文档。
- 同义词类（bidirection_synonyms）按归一化后的词组定位到对应记录，传入顺序不影响命中。
- 不支持 TOS 文件批量删除；如需大批量清理，请走控制台 DeleteDict。
- 删除为异步操作，多次删除同一词条不会报错。
ListDictTerms — 分页列出词条
按 dict_id 列出词库下全部词条。
接口元信息
请求参数
响应（result 字段）
当前版本响应仅包含 items，不返回 total / page / page_size；调用方不要依赖这些字段。
请求 / 响应示例（query_recommendation）
业务规则
- 当前版本不开放自定义排序。
- 返回字段以词条业务字段为主，公共内部字段会一并返回，调用方按需使用。
错误码
控制台 Top OpenAPI（CreateDict / CheckDictInput / BindDictToScenes）
词条数据 OpenAPI（WriteDictTerms / DeleteDictTerms / ListDictTerms）
错误体放在 error 对象内，error.code 为字符串错误名。下表与实际代码（aisearch-online）对齐：
典型业务流程
Step 1：控制台 Top OpenAPI 调用 CreateDict 创建词库 → 拿到 DictId。
Step 2（可选）：控制台 Top OpenAPI 调用 CheckDictInput 预校验词条格式。
Step 3：调用 WriteDictTerms 写入词条；大批量请上传 TOS 后传入 _data_tos_link。
Step 4：通过 ListDictTerms 查看写入结果（异步秒级延迟）。
Step 5：业务变更时调用 DeleteDictTerms / WriteDictTerms 进行细粒度增删改。
Step 6：控制台 Top OpenAPI 调用 BindDictToScenes 把词库挂到搜索场景，在线生效。
附录
控制台 OpenAPI 与数据 OpenAPI 的关系
最近更新时间：2026.08.10 16:32:10
这个页面对您有帮助吗？
有用
有用
无用
无用