新版API V2 升级与迁移文档--向量数据库VikingDB-火山引擎

文档中心

导航

新版API V2 升级与迁移文档

最近更新时间：2025.10.31 11:15:57首次发布时间：2025.08.15 11:30:50

背景

为了降低用户对于新版API/SDK V2的理解成本，提升用户使用体验，将于2025年10月17日0点后在全部region将新版API/SDK V2 与旧版 API/SDK V1接口的使用进行强隔离。具体体现为基于新版API/SDK V2创建的数据集无法通过API/SDK V1进行操作，基于旧版API/SDK V1创建的数据集无法通过API/SDK V2进行操作，在10月17日前创建的数据集不受影响。

注意

为了更好地兼容多模态检索的使用场景，以及提升接口稳定性和易用性，我们本次做了API V2版本的升级，提供更丰富的多模态功能，更易懂的接口设计、更清晰的错误码返回，后续新功能将通过API/SDK V2版本迭代，建议大家升级并使用API/SDK V2。
我们提供此文档，来帮助用户理解和使用最新的API V2接口，后续也将提供配套的SDK能力。

API V2 升级内容介绍

更丰富的功能

后续更多的产品功能都将仅通过API V2接口迭代并提供给用户使用，以下将介绍最近将上线升级的能力：

新增功能	介绍
新增视频数据写入及检索功能	实现视频的端到端向量化能力，支持用户直接写入视频数据，自动向量化，并可以任意模态对视频数据进行检索。
图片数据写入支持通用URL格式	不再要求用户一定是以tos URL写入数据，放开了数据类型限制，对于原始数据在其他云上的客户而言更为友好。
上线多关键词检索功能	支持用户指定多个关键词进行向量及关键词检索，适合关键词检索场景。
暂时移除子索引功能	暂不支持索引管理中的PartitionBy参数、数据查询和检索中的partition参数。未来以性能更强、更友好的产品形态支持。

更易懂的接口

在 API V2版本中，为了便于用户使用，将接口按功能划分为数据面 API 与 控制面 API，方便用户在使用时快速定位所需接口以及了解接口功能。
数据面 API
面向业务数据本身进行操作的接口，如对数据的写入、更新、删除、向量化、点查与多种检索能力，通常是被业务方直接集成调用的接口，具备有高吞吐低延时的特点，请求响应参数采用小写蛇形命名规则。
控制面 API
面向向量库的资源进行配置或者管理的接口，与数据集、索引与离线任务等管控对象的创建、更新、删除与查询能力，通常是被业务低频调用的接口，我们与火山引擎其它各产品的控制面接口风格相同，请求响应参数采用大驼峰命名规则。

数据面 API

负责直接处理业务数据，包括数据的写入、读取、删除以及检索相关操作。包括：

数据操作

接口能力	接口名称	升级差异
数据写入	UpsertData	自动返回模型消耗tokens，数据量限制优化等
数据更新	UpdateData	自动返回模型消耗tokens，数据量限制优化等
数据删除	DeleteData	调整主键参数名从primary_keys为ids
在数据集中点查	FetchDataInCollection	调整主键参数名从primary_keys为ids，且响应结果中将主键单独列出
在索引中点查	FetchDataInIndex	调整主键参数名从primary_keys为ids，且响应结果中将主键单独列出

检索能力

对检索的公共参数做了更系统的梳理，更加清晰，便于您针对自己的业务场景，选择合适的检索方式。
接口设计差异:V1接口将各种检索模式放置在同一接口中，由不同参数组合来区分不同的检索模式。V2接口则将不同检索模式对应到不同的接口，参数则通过公共参数和差异参数组合而成。
公共参数
可参考：检索公共参数
差异参数

接口能力	接口名称	差异参数
向量检索/稠密稀疏向量混合检索	SearchByVector	设置稠密向量参数 dense_vector 设置稀疏向量参数 sparse_vector（稀疏向量可选）
多模态检索	SearchByMultiModal	设置文本参数 text（可选）设置图像参数 iamge（可选）设置指令参数 need_instruction（可选）
id检索	SearchById	设置参数 id
标量排序检索	SearchByScalar	设置标量参数 field 设置排序顺序参数 order
随机检索	SearchByRandom	无
关键词检索	SearchByKeywords	设置关键词列表参数 keywords 设置大小写严格参数 case_sensitive 升级的新能力

Embedding计算

接口能力	接口名称	升级差异
向量化计算	Embedding	稠密和稀疏模型可以独立指定，支持稠密+稀疏任意组合、仅稠密、或仅稀疏embedding计算。自动返回模型消耗tokens。单请求默认限制不超过10条数据，但时延更短，如需提升，请联系Oncall。

控制面API

负责资源管理与配置，包括数据集管理、索引管理和任务管理等操作，管理数据所在的资源与元信息。包括：

数据集管理

接口能力	接口名称	升级差异
创建数据集	CreateVikingdbCollection	参数命名风格调整为驼峰。 Vectorize参数类型调整：由[]map改为map。主键参数位置调整。
删除数据集	DeleteVikingdbCollection	参数命名风格调整为驼峰。
更新数据集	UpdateVikingdbCollection
查看数据集详情	GetVikingdbCollection
查看数据集列表	ListVikingdbCollection

索引管理

接口能力	接口名称	升级差异
创建索引	CreateVikingdbIndex	参数命名风格调整为驼峰。
删除索引	DeleteVikingdbIndex
更新索引	UpdateVikingdbIndex
查看索引详情	GetVikingdbIndex
查看索引列表	ListVikingdbIndex

任务管理

接口能力	接口名称	升级差异
创建离线任务	CreateVikingdbTask	参数命名风格调整为驼峰。
删除离线任务	DeleteVikingdbTask
更新离线任务	UpdateVikingdbTask
查看离线任务列表	ListVikingdbTask
查看离线任务详情	GetVikingdbTask

更清晰的错误码和排查指南

V1 错误码和排查指南	V2 错误码和排查指南
错误码与故障排查指南	API V2错误码与故障排查指南

私网连接服务更新

region	API V1版本	API V2版本
北京	com.volces.privatelink.cn-beijing.vikingdb-vector	com.volces.privatelink.cn-beijing.vikingdb-ann
上海	com.volces.privatelink.cn-shanghai.vikingdb-vector	com.volces.privatelink.cn-shanghai.vikingdb-ann
广州	com.volces.privatelink.cn-guangzhou.vikingdb-vector	com.volces.privatelink.cn-guangzhou.vikingdb-ann

API V2 使用指南

升级前的准备

我们会自动帮您确认您的数据集是否适合使用API V2接口，如果不适合，您可继续使用旧版API 接口，不会受到任何影响。
如果您愿意升级，可参考升级步骤。

升级步骤

步骤	操作	截图
步骤一：控制台升级。	可通过点击页面的升级新版本一键完成升级。控制台将自动以API V2接口去请求您的向量库，同时无法兼容的数据集/索引也将标识出来，仍可通过旧版接口使用。
步骤二：新接口调用。	因接口升级，因此TOS服务需要重新授权，在创建数据集或者写入数据页面，需要再次授权您的TOS服务（可选）然后可以参考升级文档，通过API V2接口使用你的向量库。
步骤三：测试	进行功能和性能测试。确保向量存储和检索接口以及控制面接口能正常在业务中工作。若无法满足需求也可点击返回旧版。
步骤四：生产使用	可切换至生产环境使用。

API V1/V2 使用隔离：

为了降低用户对于新版API V2的理解成本，提升用户使用体验，将于2025年10月17日0点后将新版API V2 与旧版 API V1接口的使用进行强隔离。具体体现为基于新版API V2创建的数据集无法通过API V1进行操作，基于旧版API V1创建的数据集无法通过API V2进行操作，在10月17日前的数据集不受影响（list数据集展示全量，不兼容的会置灰）。
具体限制行为如下：

接口	通过旧版控制台/接口操作基于新版创建的数据集	通过新版页面/接口操作基于旧版创建的数据集
Collection - Update/Delete/Get/List	400，报错： `This collection was created by API V2, but you are accessing it via API V1. Please switch to access this collection via API V2. 该数据集是由API V2创建的，但您正在通过API V1访问它。请切换至API V2访问该数据集。`	400，报错： `This collection was created by API V1, but you are accessing it via API V2. Please switch to access this collection via API V1. 该数据集是由API V1创建的，但您正在通过API V2访问它。请切换至API V1访问该数据集。`
Collection - List	过滤掉所有新数据集	过滤掉所有老数据集
Index - Create/Update/Delete/Get/List	400，报错： `This collection was created by API V2, but you are accessing it via API V1. Please switch to access this collection via API V2. 该数据集是由API V2创建的，但您正在通过API V1访问它。请切换至API V2访问该数据集。`	400，报错： `This collection was created by API V1, but you are accessing it via API V2. Please switch to access this collection via API V1. 该数据集是由API V1创建的，但您正在通过API V2访问它。请切换至API V1访问该数据集。`
Index - List	过滤掉所有新数据集下的索引	过滤掉所有老数据集下的索引
Task - Create	400，报错： `This collection was created by API V2, but you are accessing it via API V1. Please switch to access this collection via API V2. 该数据集是由API V2创建的，但您正在通过API V1访问它。请切换至API V2访问该数据集。`	400，报错： `This collection was created by API V1, but you are accessing it via API V2. Please switch to access this collection via API V1. 该数据集是由API V1创建的，但您正在通过API V2访问它。请切换至API V1访问该数据集。`
Task - Update/Delete/Get/List	✅新老创建的全部任务（因为task操作不能根据数据集做过滤）	✅新老创建的全部任务（因为task操作不能根据数据集做过滤）
其他数据面全部带Collection的操作（写入、修改数据、检索数据、查询数据）	400，报错： `This collection was created by API V2, but you are accessing it via API V1. Please switch to access this collection via API V2. 该数据集是由API V2创建的，但您正在通过API V1访问它。请切换至API V2访问该数据集。`	400，报错： `This collection was created by API V1, but you are accessing it via API V2. Please switch to access this collection via API V1. 该数据集是由API V1创建的，但您正在通过API V2访问它。请切换至API V1访问该数据集。`

常见问题

Q1: 新版不好用，我如何回滚到旧版API？
页面上可以通过点击切换返回旧版本。同时在接口层面直接仍通过原API 接口调用即可。也欢迎将不好用的问题进行反馈，我们会持续优化。
Q2: API V2和API V1相比提升在哪？
API V2相比于V1的区别在于V2支持更丰富的功能，包括但不限于视频数据写入及检索、多关键词检索等；同时V2接口按照数据面和控制面划分，更加便于用户理解和使用。可参考上方文档的介绍，从新功能特性，接口易用性等角度进行了介绍。
Q3: 我是新用户，如何使用API V2？
对于新用户默认在新版页面，直接按照页面使用即可。
Q4: 现在的最佳实践能参考吗？
目前的快速入门和最佳实践仍然是以旧版API V1实现的，后续我们会陆续更新。
Q5: 如何判断使用的控制台版本是API V1还是API V2？
以数据集入口链接为例，API V2的页面链接和API V1的页面链接的区别在于域名V2域名增加了bohr，其他页面类似。
V1入口：https://console.volcengine.com/vikingdb/region:vikingdb+cn-beijing/collection/list
V2入口：https://console.volcengine.com/vikingdb/region:vikingdb+cn-beijing/bohr/collection/list
可根据此判断控制台版本是V1还是V2。
Q6: 为什么我在控制台找不到我创建的向量数据库？
这种情况有可能是因为当前控制台的版本和创建向量库所使用的API版本不一致。控制台仅展示其对应版本API所创建的向量数据库：点击下图页面位置，可以切换控制台版本。

切换后如果可以找到创建的向量数据库，则说明建库使用的API版本和控制台版本不一致，需统一使用版本（V1版本不再维护更新，推荐使用V2版本）；切换后如果还是找不到创建的向量数据库，可以联系我们或发起oncall解决。
Q7: 为什么访问数据库出现以下报错提示：“This collection was created by API V2, but you are accessing it via API V1. Please switch to access this collection via API V2. 该数据集是由API V2创建的，但您正在通过API V1访问它。请切换至API V2访问该数据集。“？
APIV1/V2已于2025年10月17日0点后进行强隔离，API V2创建的数据集无法通过API V1进行操作，API V1创建的数据集无法通过API V2进行操作，可以按照用户实际情况选择更换为都使用V2操作或都使用V1操作（V1版本不再维护更新，推荐使用V2版本），详情可参考：API V1/V2使用隔离

向量数据库VikingDB