**Viking AI 搜索**是一款基于生成式 AI 的企业级 AI 搜索产品，基于大模型的多模态语义表征和理解能力，结合字节跳动信息检索领域多年最佳实践，为客户提供开箱即用的 AI 搜索搭建平台服务，帮助客户轻松搭建和集成端到端的多模态图文搜索和推荐能力。想要体验更多 Viking AI 搜索能力，点击前往：[Viking AI 搜索引擎，企业搜推问一体化智能引擎](https://www.volcengine.com/product/AI-Search-Rec) --- # 概述本文档面向接入字节跳动 Viking AI 搜索词库能力的开发者，覆盖**控制台层（Console Top OpenAPI）** 与**数据层（aisearch\-online Data OpenAPI）** 两套接口共 6 个核心方法： |层级 |接口 |用途 |接入域 | |---|---|---|---| |控制台 |CreateDict |创建词库（仅元信息） |aisearch.cn\-beijing.volcengineapi.com | |控制台 |CheckDictInput |词条格式与限额预校验 |aisearch.cn\-beijing.volcengineapi.com | |控制台 |BindDictToScenes |将词库绑定到搜索场景 |aisearch.cn\-beijing.volcengineapi.com | |数据层 |WriteDictTerms |批量写入 / 编辑词条 |aisearch.cn\-beijing.volces.com | |数据层 |DeleteDictTerms |批量按内容删除词条 |aisearch.cn\-beijing.volces.com | |数据层 |ListDictTerms |分页列出词条 |aisearch.cn\-beijing.volces.com |

整体调用顺序：

CreateDict → （可选）CheckDictInput → WriteDictTerms → BindDictToScenes → 在线生效；后续可通过ListDictTerms/DeleteDictTerms 维护词条内容。

⚠️注意

本文档中所有请求示例均以华北环境域名为示例展示，实际调用时请根据业务所在地域替换为对应的 regional 域名。

# 词库（Dict）业务模型速览词库是搜推链路上对查询（query）做扩展、纠错、补全或推荐的离线词条集合，5 种类型与单条词条 schema 如下： |**Type / term_type** |**含义** |**单条业务字段** | |---|---|---| |query_recommendation |猜你想搜 |query: string、query_count: int64 | |query_completion |搜索补全 |query: string、query_count: int64 | |query_correction_exemption |纠错豁免 |word: string | |bidirection_synonyms |双向同义词 |group_terms: array（≥2 个） | |unidirection_synonyms |单向同义词 |source_term: string、target_terms: array |

关键限额：

每租户每个 Type 最多 5 个词库；单词库最多 50,000 条词条；同义词词条内单边最多 10 个同义词；建议单次请求 items ≤ 1000 条（服务端通用上限 10,000，建议保持 1000 以更好与限流策略配合）。

--- # 控制台 OpenAPI（词库元信息） ## 通用调用约定 * **请求 URL**：https://open.volcengineapi.com/?Action=&Version=2025\-03\-01 * **HTTP Method**：POST，Content\-Type: application/json * **签名**：火山 Volc Signature V4（AK/SK），与火山其他 OpenAPI 一致。 * **响应包裹**：火山 OpenAPI 标准结构。 ```JSON // 成功 { "ResponseMetadata": { "RequestId": "", "Action": "CreateDict", "Version": "2025-03-01", "Service": "ai_search_rec", "Region": "cn-beijing", "Error": null }, "Result": { /* 接口业务返回 */ } } // 失败 { "ResponseMetadata": { "RequestId": "", "Error": {"Code": "InvalidParameter", "Message": "...", "CodeN": 300001} } } ``` ### **公共业务参数**： |**参数名** |**类型** |**必填** |**说明** | |---|---|---|---| |ProjectName |string |是 |项目名称（火山多项目隔离单元），由系统自动识别注入，无需用户手动入参。 | ## CreateDict — 创建词库创建一个新的词库（仅元信息，不含词条内容）。EnableIdempotent=true 且租户内已存在同名词库时，接口直接返回已有词库，不重复创建。 ### 接口元信息 |**项** |**值** | |---|---| |Action |CreateDict | |Version |2025\-03\-01 | |HTTP Method |POST | |Top URL |* 火山国内：https://aisearch.cn\-beijing.volcengineapi.com/api/v1/CreateDict

* 火山柔佛：https://aisearch.ap\-southeast\-1.volcengineapi.com/api/v1/CreateDict

* byteplus柔佛：https://aisearch.ap\-southeast\-1.byteplusapi.com/api/v1/CreateDict | ### 请求参数 |**参数名** |**类型** |**必填** |**说明** | |---|---|---|---| |ProjectName |string |是 |项目名称。 | |Name |string |是 |词库名称，长度 1~100（按 UTF\-8 rune 计），同租户同名时若开启幂等会被复用。 | |Type |string |是 |词库类型，枚举：query_recommendation （猜你想搜）/ query_completion （搜索补全）/ query_correction_exemption （纠错保护）/ bidirection_synonyms （双向同义词）/ unidirection_synonyms。（单向同义词） | |Description |string |否 |词库描述，最长 1000 字符。 | |EnableIdempotent |bool |否 |是否启用幂等。true 时若已存在同名词库直接返回该词库，避免业务方重试导致超额。 | ### 响应参数（Result 字段） |**参数名** |**类型** |**说明** | |---|---|---| |ProjectName |string |项目名称。 | |DictId |string |词库唯一 ID，形如 dict\-。 | |Name |string |词库名称。 | |Type |string |词库类型。 | |Description |string |词库描述。 | |CreatedAt |int64 |创建时间（秒级时间戳）。 | |UpdatedAt |int64 |最近更新时间（秒级时间戳）。 | |UpdatedBy |string |最近更新人名称（创建时即为创建人）。 | ### 请求 / 响应示例 ```Bash curl -X POST 'https://open.volcengineapi.com/?Action=CreateDict&Version=2025-03-01' \ -H 'Content-Type: application/json' \ -H 'Authorization: HMAC-SHA256 Credential=/...' \ -d '{ "ProjectName": "default", "Name": "电商纠错豁免词", "Type": "query_correction_exemption", "Description": "电商搜索-不应被纠错的品牌词集合", "EnableIdempotent": true }' ``` ```JSON { "ResponseMetadata": {"RequestId": "", "Action": "CreateDict", "Version": "2025-03-01"}, "Result": { "ProjectName": "default", "DictId": "", "Name": "电商纠错豁免词", "Type": "query_correction_exemption", "Description": "电商搜索-不应被纠错的品牌词集合", "CreatedAt": 1781616000, "UpdatedAt": 1781616000, "UpdatedBy": "alice" } } ``` ### 业务规则： 1. 参数合法性校验：Name 长度 1~100、Description ≤ 1000、Type 必须是上文枚举之一。 2. 同租户同 Type 下的词库总量上限为 **5**，超出会返回 QuotaExceeded。 3. DictId 由后端生成（dict\- + 数字 ID），调用方不可指定；若启用幂等且命中已有同名词库，则返回该词库的既有 DictId。 ## CheckDictInput — 词库格式与限额校验在执行真正的词条写入前，对一批待入库词条做**预校验**：表头、字段数、字段格式（非空 / 非负整数）、词条总量、同义词数量等，全部在内存中完成，不会真正落库。该接口同时支持「文件方式（TosKey）」与「直接传词条数组（Entries）」两种入参，但二者**互斥**。 ### 接口元信息 |**项** |**值** | |---|---| |Action |CheckDictInput | |Version |2025\-03\-01 | |HTTP Method |POST | |Top URL |* 火山国内：https://aisearch.cn\-beijing.volcengineapi.com/api/v1/CheckDictInput

* 火山柔佛：https://aisearch.ap\-southeast\-1.volcengineapi.com/api/v1/CheckDictInput

* byteplus柔佛：https://aisearch.ap\-southeast\-1.byteplusapi.com/api/v1/CheckDictInput | ### 请求参数 |**参数名** |**类型** |**必填** |**说明** | |---|---|---|---| |ProjectName |string |是 |项目名称。 | |DictId |string |否 |已有词库 ID。**给已有词库追加条目时必填**：传入后会忽略 Type，使用该词库的实际 Type 校验，并在条目数计算中累计已有条目数。 | |Language |string |否 |词条语言，可选 zh / en / ja。缺省按中文（zh）处理。 | |Type |string |条件必填 |词库类型；当 DictId 为空（即新词库场景）时必填。 | |TosBucket |string |否 |TOS Bucket，与 TosKey 配合使用。 | |TosKey |string |条件必填 |TOS 对象 Key（CSV 文件），**与 Entries 二选一**。 | |Entries |array |条件必填 |直接传入的词条数组，**与 TosKey 二选一**。 | DictEntry 结构： ```JSON { "Fields": ["手机", "1000"] } ``` 不同 Type 对 Fields 的列数与含义要求： |**Type** |**必须字段数** |**字段语义** | |---|---|---| |query_recommendation / query_completion / unidirection_synonyms |2 |第 1 列文本，第 2 列为非负整数（推荐分 / 频次 / 权重等）。 | |query_correction_exemption / bidirection_synonyms |1 |纠错豁免：单 token；双向同义词：英文逗号分隔的同义词集合。 | ### 响应参数（Result 字段） |**参数名** |**类型** |**说明** | |---|---|---| |BatchEntryCount |uint64 |本次校验中识别到的有效词条数（已跳过空行）。 | |Errors |object |结构化错误集合，可能为空对象（表示通过校验）。Key 见下表。 | Errors 中的子字段（任一存在即代表对应类型的校验失败，**不影响 HTTP 200 返回**，调用方需自行判断 Errors 是否非空）： |**Key** |**类型** |**说明** | |---|---|---| |ErrHeader |object |表头不匹配。包含 Expected 与 Actual。仅 CSV 文件场景出现。 | |ErrEntryCount |object |条目数超限。包含 MaxEntriesPerBatch(10000)、MaxEntriesPerDict(50000)、DictExistingEntry、ThisBatchEntry。 | |ErrsFieldCount |array |字段数过少的行明细，单错误最多 10 条：LineNumber、Expected、Actual。 | |ErrsFieldFormat |array |字段格式错误（空字段、非负整数列含非法值）。最多 10 条：LineNumber、FieldName、ExpectedFormat、ActualContent。 | |ErrsFieldTermCount |array |同义词数量越界。最多 10 条：LineNumber、FieldName、ExpectedMin、ExpectedMax、Actual。 | ### 请求 / 响应示例 ```Bash curl -X POST 'https://open.volcengineapi.com/?Action=CheckDictInput&Version=2025-03-01' \ -H 'Content-Type: application/json' \ -H 'Authorization: HMAC-SHA256 Credential=/...' \ -d '{ "ProjectName": "default", "Type": "query_recommendation", "Language": "zh", "Entries": [ {"Fields": ["手机", "1000"]}, {"Fields": ["平板电脑", "abc"]}, {"Fields": ["", "5"]} ] }' ``` ```JSON { "ResponseMetadata": {"RequestId": ""}, "Result": { "BatchEntryCount": 3, "Errors": { "ErrsFieldFormat": [ {"LineNumber": 2, "FieldName": "Score", "ExpectedFormat": "non_negative_integer", "ActualContent": "abc"}, {"LineNumber": 3, "FieldName": "Query", "ExpectedFormat": "non_empty", "ActualContent": ""} ] } } } ``` ### 业务规则 1. **入参互斥**：TosKey 与 Entries 同时非空将报 DictInputInvalid。 2. **CSV 表头**：表头字段名按前缀匹配预期表头，多余列会被忽略；首列允许带 UTF\-8 BOM。 3. **空行容忍**：所有字段都为空白的行会被跳过，不计入 BatchEntryCount。 ## BindDictToScenes — 将词库绑定到搜索场景将一个已有词库挂载到一个或多个搜索场景的对应配置位上。绑定成功后，会自动**触发场景配置上线**，让在线检索链路立即生效。 ### 接口元信息 |**项** |**值** | |---|---| |Action |BindDictToScenes | |Version |2025\-03\-01 | |HTTP Method |POST | |Top URL |* 火山国内：https://aisearch.cn\-beijing.volcengineapi.com/api/v1/BindDictToScenes

* 火山柔佛：https://aisearch.ap\-southeast\-1.volcengineapi.com/api/v1/BindDictToScenes

* byteplus柔佛：https://aisearch.ap\-southeast\-1.byteplusapi.com/api/v1/BindDictToScenes | ### 请求参数 |**参数名** |**类型** |**必填** |**说明** | |---|---|---|---| |ProjectName |string |是 |项目名称。 | |DictId |string |是 |要绑定的词库 ID。 | |Scenes |array |是 |需要绑定的目标场景列表。 | DictScene 结构： |**参数名** |**类型** |**必填** |**说明** | |---|---|---|---| |AppId |string |是 |应用 ID。 | |SceneId |string |是 |场景 ID（在该应用下）。 | |DatasetId |string |条件必填 |仅同义词 / 纠错豁免类词库需要指定，用于定位场景下数据集级配置；补全 / 推荐类词库可留空。 | ### 响应成功时返回空对象 Result: {}；失败通过 ResponseMetadata.Error 表达。 ### 请求 / 响应示例 ```Bash curl -X POST 'https://open.volcengineapi.com/?Action=BindDictToScenes&Version=2025-03-01' \ -H 'Content-Type: application/json' \ -H 'Authorization: HMAC-SHA256 Credential=/...' \ -d '{ "ProjectName": "default", "DictId": "dict-1738291231231231", "Scenes": [ {"AppId": "app-12345", "SceneId": "scene-001", "DatasetId": "ds-abc"}, {"AppId": "app-12345", "SceneId": "scene-002", "DatasetId": "ds-abc"} ] }' ``` ```JSON {"ResponseMetadata": {"RequestId": ""}, "Result": {}} ``` ### 绑定行为说明 1. **去重写入**：对同一个 Scene 重复绑定同一 DictId 是幂等的，后端会跳过已存在条目。 2. **强制上线**：每个 Scene 绑定完成后会推送配置，请确保场景本身处于可上线的合法状态。 3. **DatasetId 校验**：当词库类型需要 DatasetId 但传入的 ID 在场景的配置中不存在时，将返回 InvalidParameter:DatasetID。 # 词条数据 OpenAPI（aisearch\-online） ## 通用调用约定 * **接入域名**：https://aisearch.cn\-beijing.volces.com（火山 APIG） * **HTTP Method**：POST，Content\-Type: application/json ```Plain Text POST https://aisearch.cn-beijing.volces.com/api/v1/dict/{dict_id}/ ``` * **请求体字段命名**：**snake_case**（如 dict_id、page_size、_data_tos_link）。 * **鉴权**：火山 AK/SK，**Volcengine Signature V4**；签名关键参数：Region=cn\-beijing、Service=aisearch、Date=YYYYMMDDTHHMMSSZ（UTC）。 ### 公共请求 Header |**Header** |**必填** |**说明** | |---|---|---| |Authorization |是 |Volcengine Signature V4 签名头：HMAC\-SHA256 Credential=//cn\-beijing/aisearch/request, SignedHeaders=..., Signature=...。 | |X\-Date |是 |请求时间，UTC ISO8601 紧凑格式（如 20260611T080000Z），用于参与 V4 签名计算。 | |Content\-Type |是 |固定 application/json。 | |X\-Account\-Id |是 |账号（租户）ID，由 custommiddleware.AuthDictMiddleware 校验，用于隔离不同租户的数据。 | |X\-Project\-Name |是 |项目名称（与控制台保持一致）。 | |X\-Request\-Id |否 |调用方自定义请求 ID，便于排障；不传则由服务自动分配。 | ### 公共响应包裹（CommonResponse）服务统一返回 CommonResponse 结构。 **成功**（HTTP 200）：业务字段在 **result** 中（注意：不是 data）： ```JSON { "result": { /* 接口业务返回 */ }, "request_id": "" } ``` **失败**（HTTP 4xx / 5xx）：错误信息在 error 对象中，错误码以**字符串名**承载在 error.code： ```JSON { "error": { "code": "InvalidParameter", "message": "items length exceeds limit" }, "request_id": "" } ```

说明

调用方对齐要点：

(1) 成功字段名 result，不是 data；(2) 错误码字符串放在 error.code；(3) 应基于字符串错误码 + HTTP 状态码组合判断；(4) 三个接口的请求体均不接受 term_type 字段——服务端从 dict_id 反查类型。

## WriteDictTerms — 批量写入 / 编辑词条将一批词条写入指定词库。_last_data 缺省表示**新增**；同时携带 _last_data 与 _current_data 时表示**编辑**（先按 _last_data 删除旧条目，再按 _current_data 写入新条目）。 ### 接口元信息 |**项** |**值** | |---|---| |HTTP Method |POST | |URL |* 火山国内：https://aisearch.cn\-beijing.volces.com/api/v1/dict/{dict_id}/write_terms

* 火山柔佛：https://aisearch.ap\-southeast\-1.volces.com/api/v1/dict/{dict_id}/write_terms

* byteplus柔佛：https://aisearch.ap\-southeast\-1.byteplusapi.com/api/v1/dict/{dict_id}/write_terms | |语义 |异步写入：接口返回成功仅表示写入请求已被系统接收，词条数据将异步处理并最终生效，请求返回与词条实际生效之间可能存在短暂延迟，请以查询接口的实际结果为准。 | ### 路径与请求参数 |**参数名** |**位置/类型** |**必填** |**说明** | |---|---|---|---| |dict_id |path / string |是 |词库 ID，由 CreateDict 返回。 | |items |body / array |条件必填 |内联词条数组，与 _data_tos_link **二选一**。建议单次 ≤ 1000 条；服务端通用上限 10,000 条，超过返回 ItemsTooLarge。 | |_data_tos_link |body / string |条件必填 |大批量 TOS 文件路径（如 tos://bucket/key），与 items **二选一**；仅支持新增，文件每行一条业务字段 JSON。 | > **注意**：当 items 与 _data_tos_link 同时非空时，服务端**优先处理 TOS 链接并忽略 items**，不会报错；调用方仍应明确二选一以避免误用。 TermItem 结构： |**字段** |**类型** |**必填** |**说明** | |---|---|---|---| |_last_data |object |否 |变更前的词条业务字段；缺省表示纯新增，传入则先按 _last_data 删除旧条目。需要填写的schema 参考「词库（Dict）业务模型速览」。 | |_current_data |object |是 |变更后的词条业务字段；需要填写的schema 参考「词库（Dict）业务模型速览」。 | ### 响应（result 字段） |**字段** |**类型** |**说明** | |---|---|---| |accepted |int64 |本次成功投递到 Kafka 的词条数（内联场景）；TOS 模式下为 1，表示已提交批量任务。 | ### 请求 / 响应示例 |**data_type** |**单条词记录data示例** | |---|---| |query_recommendation

搜索推荐词

|```JSON```
```{ ```
``` "_last_data" : {```
``` "query": "AVCC",```
``` "query_count": 1```
``` },```
``` "_current_data" : {```
``` // 以猜你想搜为例，```
``` "query": "AVCC",```
``` "query_count": 123```
``` },```
```}```
| |query_completion

搜索补全词 |```JSON```
```{ ```
``` "_last_data" : {```
``` "query": "AVCC",```
``` "query_count": 1```
``` },```
``` "_current_data" : {```
``` // 以猜你想搜为例，```
``` "query": "AVCC",```
``` "query_count": 123```
``` },```
``` }```
| |query_correction_exemption

纠错保护词 |```JSON```
```{```
``` "_last_data": {},```
``` "_current_data": {```
``` "word": "AVCC"```
``` }```
``` }```
| |unidirection_synonyms

单向同义词 |```JSON```
```{```
``` "_last_data": {},```
``` "_current_data": {```
``` "source_term": "手机",```
``` "target_terms": ["移动电话", "智能手机"]```
``` }```
``` }```
| |bidirection_synonyms

双向同义词 |```JSON```
```{```
``` "_last_data": {},```
``` "_current_data": {```
``` "group_terms": ["电视", "TV", "电视机"]```
``` }```
``` }```
| **A. 内联写入猜你想搜词条**： ```Bash curl -X POST 'https://aisearch.cn-beijing.volces.com/api/v1/dict//write_terms'\ -H 'Content-Type: application/json' \ -H 'X-Account-Id: ' \ -H 'X-Project-Name: default' \ -H 'X-Date: 20260611T080000Z' \ -H 'Authorization: HMAC-SHA256 Credential=/...' \ -d '{ "items": [ {"_current_data": {"query": "iphone 16", "query_count": 100}}, {"_current_data": {"query": "AVCC Pro", "query_count": 5}} ] }' ``` **B. 编辑同义词（先删旧、再写新）** ： ```JSON { "items": [ { "_last_data": {"source_term": "手机", "target_terms": ["移动电话"]}, "_current_data": {"source_term": "手机", "target_terms": ["移动电话", "智能手机"]} } ] } ``` **C. TOS 大文件批量导入**： ```JSON { "_data_tos_link": "my-bucket/dict_imports/iphone_completion.jsonl" } ``` > TOS 文件每行一条业务字段 JSON，例如 {"query":"iphone 16","query_count":100}，**不要**包裹 _current_data。 **响应示例**： ```JSON { "result": {"accepted": 2}, "request_id": "" } ``` ### 业务规则 1. **二选一**：items 与 _data_tos_link 同时非空时服务端优先处理 TOS 链接，调用方应保证只传一种。 2. **大小限制**：建议内联 items ≤ 1000；服务端通用上限 10,000 条，超过返回 ItemsTooLarge。 ## DeleteDictTerms — 批量删除词条通过 _last_data 携带的词条内容定位到具体的文档并删除。**不支持只传 dict_id 触发整库清空**（整库清理请走控制台 DeleteDict）。 ### 接口元信息 |**项** |**值** | |---|---| |HTTP Method |POST | |URL |* 火山国内：https://aisearch.cn\-beijing.volces.com/api/v1/dict/{dict_id}/delete_terms

* 火山柔佛：https://aisearch.ap\-southeast\-1.volces.com/api/v1/dict/{dict_id}/delete_terms

* byteplus柔佛：‌https://aisearch.ap\-southeast\-1.byteplusapi.com/api/v1/dict/{dict_id}/delete_terms | ### 请求参数 |**参数名** |**位置/类型** |**必填** |**说明** | |---|---|---|---| |dict_id |path / string |是 |词库 ID。 | |items |body / array |是 |待删除词条列表。建议单次 ≤ 10000 条。 | TermDeleteItem 结构： |**字段** |**类型** |**必填** |**说明** | |---|---|---|---| |_last_data |object |是 |待删除的词条业务内容；schema参考「词库（Dict）业务模型速览」，**必须传完整业务字段**用于内容定位。 | ### 响应（result 字段） |**字段** |**类型** |**说明** | |---|---|---| |accepted |int64 |本次成功接收并进入异步处理流程的删除请求数 | ### 请求 / 响应示例 ```Bash curl -X POST 'https://aisearch.cn-beijing.volces.com/api/v1/dict//delete_terms' \ -H 'Content-Type: application/json' \ -H 'X-Account-Id: ' \ -H 'X-Project-Name: default' \ -d '{ "items": [ {"_last_data": {"group_terms": ["电视", "TV", "电视机"]}}, {"_last_data": {"group_terms": ["手机", "移动电话"]}} ] }' ``` ```JSON { "result": {"accepted": 2}, "request_id": "" } ``` ### 业务规则 3. 删除使用**内容定位**：_last_data 必须填写当前 ES 中存在的完整业务字段；缺字段或字段值与 ES 中不一致将无法命中目标文档。 4. 同义词类（bidirection_synonyms）按归一化后的词组定位到对应记录，传入顺序不影响命中。 5. 不支持 TOS 文件批量删除；如需大批量清理，请走控制台 DeleteDict。 6. 删除为**异步**操作，多次删除同一词条不会报错。 ## ListDictTerms — 分页列出词条按 dict_id 列出词库下全部词条。 ### 接口元信息 |**项** |**值** | |---|---| |HTTP Method |POST | |URL |* 火山国内：https://aisearch.cn\-beijing.volces.com/api/v1/dict/{dict_id}/list_terms

* 火山柔佛：https://aisearch.ap\-southeast\-1.volces.com/api/v1/dict/{dict_id}/list_terms

* byteplus柔佛：https://aisearch.ap\-southeast\-1.byteplusapi.com/api/v1/dict/{dict_id}/list_terms | ### 请求参数 |**参数名** |**位置/类型** |**必填** |**说明** | |---|---|---|---| |dict_id |path / string |是 |词库 ID。 | |page |body / int32 |否 |页码，从 1 开始，默认 1。 | |page_size |body / int32 |否 |每页条数，默认 10；服务端校验 page_size < 1000。 | ### 响应（result 字段） |**字段** |**类型** |**说明** | |---|---|---| |items |array |词条业务字段数组，每个元素 schema 与该词库 Type 对应（schema 参考「词库（Dict）业务模型速览」）；同时会附带内部字段。 | > 当前版本响应**仅包含 items**，不返回 total / page / page_size；调用方不要依赖这些字段。 ### 请求 / 响应示例（query_recommendation） ```Bash curl -X POST 'https://aisearch.cn-beijing.volces.com/api/v1/dict//list_terms' \ -H 'Content-Type: application/json' \ -H 'X-Account-Id: 200000123' \ -H 'X-Project-Name: default' \ -d '{"page": 1, "page_size": 50}' ``` ```JSON { "result": { "items": [ {"query": "iphone 16", "query_count": 100, "_update_timestamp": ""}, {"query": "AVCC Pro", "query_count": 5, "_update_timestamp": ""} ] }, "request_id": "" } ``` ### 业务规则 1. 当前版本不开放自定义排序。 2. 返回字段以词条业务字段为主，公共内部字段会一并返回，调用方按需使用。 # 错误码 ## 控制台 Top OpenAPI（CreateDict / CheckDictInput / BindDictToScenes） |**Error Code** |**CodeN** |**HTTP** |**说明 / 触发场景** | |---|---|---|---| |InvalidParameter |300001 |400 |参数非法。常见：Type 取值不在枚举内、DatasetID 在场景配置中不存在等。 | |InvalidParameter.Length |300002 |400 |字段长度越界。Name 必须 1~100，Description ≤ 1000。 | |InternalError |300004 |500 |未知后端异常（DB、依赖服务故障等），需查 RequestId 排查。 | |QuotaExceeded |300013 |429 |同 Project + Type 维度词库总数超过 5（MaxDictsPerType）。 | |DictInputInvalid |400001 |400 |CheckDictInput 入参非法：Entries 与 TosKey 同传、CSV 解析失败、Type/Language 不被支持等。 | |InvalidParameter.DictNameAlreadyExists |400002 |409 |词库名已存在（CreateDict 在非幂等模式下创建同名词库）。 | |OperationDenied.DictBoundToSearchScene |400003 |403 |词库已被场景绑定（DeleteDict 时校验）。 | ## 词条数据 OpenAPI（WriteDictTerms / DeleteDictTerms / ListDictTerms）错误体放在 error 对象内，error.code 为字符串错误名。下表与实际代码（aisearch\-online）对齐： |**错误码（error.code）** |**HTTP** |**说明 / 触发场景** | |---|---|---| |InvalidParameter |400 |请求体非法：字段缺失、类型错误、page_size 超界、TOS 链接为空等。 | |AccessDenied |401 / 403 |签名校验失败或 X\-Account\-Id 缺失/越权（由 AuthDictMiddleware 拒绝）。 | |DatasetNotFound |404 |dict_id 在配置缓存中不存在或已被删除。 | |WriteLimitExceeded |429 |写接口在 account_id + dict_id 维度被限流。 | |ItemsTooLarge |400 |items 长度超过通用上限（10,000）。 | |InternalServiceError |500 |未知后端异常（含下游 ES/Kafka 短时不可用），请携带 request_id 排障并指数退避重试。 | # 典型业务流程 **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 的关系 |**能力** |**所属服务 / 仓库** |**调用入口** | |---|---|---| |词库元信息 CURD |控制台 Top OpenAPI（ai\-search\-rec/console） |open.volcengineapi.com，Action/Version 路由 | |词条 CURD |data\-api（ai\-search\-rec/aisearch\-online） |aisearch.cn\-beijing.volces.com，RESTful 路径 | |词库 ↔ 场景绑定 |控制台 Top OpenAPI |BindDictToScenes |