向量数据库 Viking DB 现已提供 Python SDK，可直接在数据面（Data / Search / Embedding）完成鉴权、读写、检索与向量化操作。使用前请先完成 SDK 安装与客户端初始化。

1. 已通过 注册账号及开通服务。
2. 已获取火山引擎 AK / SK。详情参考 Access Key（密钥）管理。
3. 准备可用的 Python 3.9+ 运行环境，并具备安装第三方依赖的权限。

Python 版 SDK 已发布到 PyPI，可选择直接安装发行版或在源码目录中以开发模式安装。

1. 使用 pip 安装发行版

推荐通过 pip 或 uv 获取最新稳定版本：

uv add vikingdb-python-sdk
// or 
python3 -m pip install -U vikingdb-python-sdk

安装完成后可通过 python3 -m pip show vikingdb-python-sdk 验证版本。

2. 在源码目录中安装

若需调试最新源码，请克隆仓库并以 editable 模式安装：

git clone https://github.com/volcengine/vikingdb-python-sdk.git
cd vikingdb-python-sdk
uv sync

初始化步骤包含三部分：配置网络出口（域名/Region）、准备鉴权信息、构造客户端并发起一次请求以验证连通性。

1. 数据面 (Data / Search / Embedding)

数据面域名供 VikingVector、CollectionClient、IndexClient 以及 Embedding 接口使用。

import os

from vikingdb import IAM
from vikingdb.vector import SearchByRandomRequest, UpsertDataRequest, VikingVector

client = VikingVector(
    host=os.environ["VIKINGDB_HOST"],
    region=os.environ["VIKINGDB_REGION"],
    auth=IAM(ak=os.environ["VIKINGDB_AK"], sk=os.environ["VIKINGDB_SK"]),
    scheme="https",
)

collection_name=os.environ["VIKINGDB_COLLECTION"]
index_name=os.environ["VIKINGDB_INDEX"]

upsert_resp = client.collection(collection_name=collection_name).upsert(UpsertDataRequest(data=[{"text": "something"}]))
response = client.index(collection_name=collection_name,index_name=index_name).search_by_random(SearchByRandomRequest(limit=5))
hits = len(response.result.data) if response.result else 0
if response.result:
    for item in response.result.data:
        print(item.id, item.score, item.fields.get("text"))

2. 控制面 (Collection / Index / Task)

控制面用于管理集合、索引与任务编排，目前仍通过火山引擎 OpenAPI 提供服务。可以复用 volcengine-python-sdk 或自定义 HTTP 客户端，只需确保使用下列域名并带上 AK/SK 鉴权签名。