以下最佳实践基于新版API V2，推荐使用此版本。

向量数据库 VikingDB 是构建于火山引擎的云基础设施之上的向量数据库系统，其核心功能涵盖了对机器学习模型产生的海量向量数据进行生产、存储、索引以及分析等操作。
在本指南里，我们会引导您在短短几分钟内迅速完成首个向量库的开通、配置工作，让您能够在我们的配置页面走完数据集创建、索引创建以及检索查询的全部流程。

分为以下三个步骤：

1. 注册火山引擎账号。
2. 完成实名认证。
3. 开通向量数据库服务。

注册账号

1. 进入 火山引擎官网，单击页面右上角的【立即注册】。
2. 根据要求完整填写表单后即可完成注册，更多详情参考 火山引擎账号注册。

实名认证

1. 使用已注册的火山引擎账号登录 火山引擎官网。
2. 单击右上角账号名下拉框中的【账号管理】进入对应页面。
3. 单击左侧导航中的【实名认证】，根据实际情况选择个人或者企业，并填写对应表单或上传相关材料完成实名认证，更多详情参考 实名认证。

开通向量数据库

登录 火山引擎控制台，找到 VikingDB，根据对应的提示按需开通 向量数据库服务。

4. 在创建数据集页面填写相关参数，包括数据集基础信息、向量配置和数据库内字段。参照右图示例完成具体配置。
5. 填写完成后单击右下角提交，​完成数据集创建流程。

（示例）

数据集配置项目

数据写入现在支持在线写入、本地数据导入、从TOS添加和单条数据插入四种形式（目前视频只支持在线写入）。

第一类：在线写入

• 同步写入

适用于在线服务数据实时写入生效场景，提供流式写入接口
写入数据：​在写入数据时请根据选择**“从向量化开始”​或“已有向量数据”​**来决定上传时需要写入的参数。

• 具体写入流程请参考数据面API调用流程，写入数据API参考数据写入-UpsertData
• 多模态数据写入详见最佳实践

写入示例：
请创建数据集、填入数据集名称、aksk、字段名、json文件地址

'''
> uv run --env-file .env python main.py
'''

import os
import json
import requests
from volcengine.auth.SignerV4 import SignerV4
from volcengine.Credentials import Credentials
from volcengine.base.Request import Request

def main() -> None:
    client = HTTPClient(
        ak=os.environ.get("VIKINGDB_AK"),
        sk=os.environ.get("VIKINGDB_SK"),
        host=os.environ.get("VIKINGDB_HOST"),  # https://www.volcengine.com/docs/84313/1792715
        region=os.environ.get("VIKINGDB_REGION"),
    )

    req_method = "POST"
    collection_name = os.environ.get("VIKINGDB_COLLECTION")
    index_name = os.environ.get("VIKINGDB_INDEX")

    upsert_body = {
        "collection_name": collection_name,
        "data": [{"text": "hello world"}],
    }
    upsert_resp = client.do_req(
        req_method=req_method,
        req_path="/api/vikingdb/data/upsert",
        req_params=None,
        req_body=upsert_body,
    )
    print(f"[upsert status={upsert_resp.status_code} body={upsert_resp.text}]\n===")

    search_body = {
        "collection_name": collection_name,
        "index_name": index_name,
        "limit": 1,
    }
    search_resp = client.do_req(
        req_method=req_method,
        req_path="/api/vikingdb/data/search/random",
        req_params=None,
        req_body=search_body,
    )
    print(f"[search status={search_resp.status_code} body={search_resp.text}]")

class HTTPClient:
    def __init__(self, ak: str, sk: str, host: str, region: str):
        self.ak = ak
        self.sk = sk
        self.host = host
        self.region = region

    def prepare_request(self, method: str, path: str, params=None, data=None) -> Request:
        r = Request()
        r.set_schema("https")            # ensure HTTPS
        r.set_method(method)
        r.set_connection_timeout(10)
        r.set_socket_timeout(10)
        mheaders = {
            "Accept": "application/json",
            "Content-Type": "application/json",
            "Host": self.host,
        }
        r.set_headers(mheaders)
        if params:
            r.set_query(params)
        r.set_host(self.host)
        r.set_path(path)
        if data is not None:
            r.set_body(json.dumps(data))
        credentials = Credentials(self.ak, self.sk, "vikingdb", self.region)
        SignerV4.sign(r, credentials)
        return r

    def do_req(self, req_method: str, req_path: str, req_params, req_body):
        req = self.prepare_request(
            method=req_method,
            path=req_path,
            params=req_params,
            data=req_body,
        )
        return requests.request(
            method=req.method,
            url="{}://{}{}".format(req.schema, self.host, req.path),  # use the schema set above
            headers=req.headers,
            data=req.body,
            timeout=10000,
        )

if __name__ == "__main__":
    main()

• 异步写入

完成初始化的基础上，对于已有向量数据的数据集，您可以使用在线异步写入的方式写入数据。通过设置 async 参数为true。

第二类：本地数据导入

适用于首次建库，一次性大批量离线数据上传场景，提供大批量处理能力，速度更快。

1. 直接导入json/parquet格式文档
2. 选择是否忽略失败数据，若开启，单条数据写入失败，则跳过本条数据继续写入任务。

第三类：​从TOS导入

1. TOS 服务开通及授权
   • TOS 服务开通
     • 点击创建 TOS 桶。去开通
   • 授权 VikingDB 访问
     • 授权 VikingDB 服务可以访问您的 TOS 权限。去授权

若需要上传多模态数据，请先将图片上传至TOS，并将图片的tos存储路径传入"image"字段。

{"animal_image": "tos://best-practice-pic-search-tos/pic_search_1000_images/0009fc27d9.jpg"}

2. 选择json/parquet格式文档的TOS桶

具体执行逻辑可参考如下流程图。详见【向量库】多模态搜索最佳实践

第四类：​单条数据插入

此外，你还可以在数据集详情页面插入单条数据

此外，我们在开始使用页面还为您准备了探索指南，您可以根据需要按照指引深入探索VikingDB向量数据库：

• 快速入门：​了解如何开始使用并快速创建您的向量数据库。
• 最佳实践：​学习在多模态搜索、多模态标注等高频场景下向量数据库最佳实践，帮助找到符合您场景的使用方式。
• 常见问题：​解答您在使用过程中遇到的常见问题，提供解决方案和建议。
• API参考：​查阅 API 的详细文档，包括 API、示例代码和集成指南，帮助您高效开发。