一、 背景

在知识库的使用中，上传文档至知识库无疑是一项常见且至关重要的操作。现阶段，我们为用户精心打造了多种便捷高效的上传途径。目前支持直接通过界面，单次上传多达 100 个本地文档，大大节省了用户的时间与精力；也支持用户从 TOS 中批量导入文档或目录，实现对文档的管理和导入更友好地操作。同时，还可以使用 API 或者 SDK 对文档进行 TOS 或 URL 方式的导入，在导入更多文档时减少用户的重复操作。
但需注意的是，目前 API 或者 SDK 暂不支持直接进行本地上传，这可能导致更多本地文档的导入遭遇阻碍，也不利于文档的有序管理。

二、实践概述

本实践主要实现了将本地文件通过对象存储（TOS）导入到知识库中的功能流程。整个过程包括设置用户相关的ak/sk以及对象存储位置、配置知识库相关的ak/sk、将本地文件上传至TOS桶并配置元数据（可选）、将数据从TOS桶中导入至知识库等操作。

三、环境要求

1. 账号与权限要求
   • 需要有火山引擎的账号，并获取相应的ak（Access Key）和sk（Secret Key）权限，以便在代码中进行身份验证，实现对对象存储和知识库的操作。
2. 安装相关库
   • 本产品实践依赖于tos和volcengine库。可以通过以下命令进行安装：
     • 对于tos库，在命令行中执行pip install tos。
     • 对于volcengine库，在命令行中执行pip install --user volcengine。

四、实施步骤

（一）设置用户相关的ak/sk以及对象存储位置

1. 代码示例

from volcengine.viking_knowledgebase import VikingKnowledgeBaseService
import tos

ak = "ak"
sk = "sk"
# endpoint 和 region 填写Bucket 所在区域对应的Endpoint。
endpoint = "tos-cn-beijing.volces.com"
region = "cn-beijing"

2. 代码解释
   • 用户需要将实际的 ak和sk 值替换此处的示例值。
   • 首先从 volcengine.viking_knowledgebase 和 tos 库中导入所需的模块。
   • 定义ak和sk，这是用于身份验证的访问密钥和秘密密钥。
   • 根据知识库仅支持北京区域对象存储导入的要求，设置endpoint为北京区域对应的tos-cn-beijing.volces.com，region设置为cn-beijing。

（二）配置知识库相关的ak/sk

1. 代码示例

viking_knowledgebase_service = VikingKnowledgeBaseService(host="api-knowledgebase.mlp.cn",
                                                          scheme="https",
                                                          connection_timeout = 30,
                                                          socket_timeout = 30)
viking_knowledgebase_service.set_ak(ak)
viking_knowledgebase_service.set_sk(sk)

2. 代码解释
   • 创建VikingKnowledgeBaseService对象，设置主机地址为api-knowledgebase.mlp.cn-beijing.volces.com，使用https协议，连接超时和套接字超时时间都设置为30秒。
   • 通过set_ak和set_sk方法将前面定义的ak和sk配置到知识库服务对象中。

（三）将本地文件上传至tos桶中，并配置上传文件的元数据meta（可选）

1. 代码示例

try:
    # 创建 TosClientV2 对象，对桶和对象的操作都通过 TosClientV2 实现
    client = tos.TosClientV2(ak, sk, endpoint, region)
    bucket_name = "demo_bucket"    # bucket_name 为目标桶名称
    object_key = "object.txt"    # object_key 为文件上传后在目标桶中的对象名称（即文件名称）
    file_name = "/mypath/object.txt"    # file_name 为本地文件的完整路径。
    client.put_object_from_file(bucket_name,
                                object_key,
                                file_name,
                                meta = {'doc_id': "your_doc_id"},)
except tos.exceptions.TosClientError as e:
    # 操作失败，捕获客户端异常，一般情况为非法请求参数或网络异常
    print('fail with client error, message:{}, cause: {}'.format(e.message, e.cause))
except tos.exceptions.TosServerError as e:
    # 操作失败，捕获服务端异常，可从返回信息中获取详细错误信息
    print('fail with server error, code: {}'.format(e.code))
    # request id 可定位具体问题，强烈建议日志中保存
    print('error with request id: {}'.format(e.request_id))
    print('error with message: {}'.format(e.message))
    print('error with http code: {}'.format(e.status_code))
    print('error with ec: {}'.format(e.ec))
    print('error with request url: {}'.format(e.request_url))
except Exception as e:
    print('fail with unknown error: {}'.format(e))

2. 代码解释
   • 用户需要将实际的bucket_name，object_key ，file_name和meta值替换此处的示例值。
   • 首先在try块中创建TosClientV2对象，传入ak、sk、endpoint和region用于与TOS服务进行交互。
   • 使用put_object_from_file方法将本地文件（由file_name指定完整路径）上传到指定的bucket_name和object_key位置，并可通过meta参数配置元数据。这里的doc_id在元数据中可由用户自定义为与业务场景相关的唯一 id ，且必须满足只能使用英文字母、数字、下划线_的命名规范。
   • 如果出现TosClientError异常，这通常是由于非法请求参数或网络异常，会打印出错误消息和原因。如果是TosServerError异常，会打印出错误码、请求id、错误消息、HTTP状态码、错误码（ec）和请求的URL等详细信息以便定位问题。如果是其他未知异常，也会打印出相应的错误消息。

（四）将数据从TOS桶中导入至知识库中

1. 代码示例

tos_path = "demo_bucket/"
my_collection = viking_knowledgebase_service.get_collection(collection_name)
my_collection.add_doc(add_type = "tos",
                      tos_path = tos_path,
                      )

2. 代码解释
   • 用户需要将实际的collection_name和 tos_path值替换此处的示例值。请注意tos_path若为文件夹，需要以"xxx/"结尾。
   • 首先通过viking_knowledgebase_service的get_collection方法获取指定collection_name的集合对象。
   • 然后使用集合对象的add_doc方法，将add_type设置为tos表示从TOS导入数据，tos_path指定了要导入的TOS中的路径，从而将数据从TOS桶中导入到知识库中。

五、实践意义

1. 数据整合与管理
   • 该流程实现了从本地文件到对象存储再到知识库的完整数据流转过程，有助于企业或用户对数据进行有效的整合与管理，方便知识的存储、共享和利用。
2. 精准召回
   • 通过自定义doc_id的方式，能够根据业务场景为每个文档制定唯一的标识。在后续召回文档时，可以通过doc_id进行过滤，精准地召回对应文档范围，提高知识库查询的准确性和效率。