1. 注册火山账号并开通 VikingDB 知识库服务

访问 火山引擎 并登录，进入VikingDB知识库

2. 构建后端 API 服务

火山 VikingDB 知识库提供的检索接口 和 Dify 定义的外部数据库 API 定义不完全适配，需要开发团队人工维护 API 服务，包装 火山 VikingDB 知识库提供的检索接口，再建立与 Dify 的连接。

火山 VikingDB 知识库检索 API 与 Dify 外部知识库 API 的映射

请求参数

retrieval_setting 映射如下：

VikingDB 知识库检索接口没有 score_threshold 参数，返回的切片是按 score 倒序排序的，为适配 Dify 协议，需要手动过滤。

响应消息

records 属性是一个包含以下键的对象列表：

VikingDB 检索接口返回的切片包含切片标题和原文本标题，切片标题对应字段为 chunk_title，原文档标题对应字段在 doc_info 元信息中的 title 字段。

你可以参考以下 2 个代码文件，构建后端服务 API。
knowledge.py

from flask import request
from flask_restful import Resource, reqparse

from bedrock.knowledge_service import ExternalDatasetService


class BedrockRetrievalApi(Resource):
    # url : <your-endpoint>/retrieval
    def post(self):
        parser = reqparse.RequestParser()
        parser.add_argument("retrieval_setting", nullable=False, required=True, type=dict, location="json")
        parser.add_argument("query", nullable=False, required=True, type=str,)
        parser.add_argument("knowledge_id", nullable=False, required=True, type=str)
        args = parser.parse_args()

        # Authorization check
        auth_header = request.headers.get("Authorization")
        if " " not in auth_header:
            return {
                "error_code": 1001,
                "error_msg": "Invalid Authorization header format. Expected 'Bearer <api-key>' format."
            }, 403
        auth_scheme, auth_token = auth_header.split(None, 1)
        auth_scheme = auth_scheme.lower()
        if auth_scheme != "bearer":
            return {
                "error_code": 1001,
                "error_msg": "Invalid Authorization header format. Expected 'Bearer <api-key>' format."
            }, 403
        if auth_token:
            # process your authorization logic here
            pass

        # Call the knowledge retrieval service
        result = ExternalDatasetService.knowledge_retrieval(
            args["retrieval_setting"], args["query"], args["knowledge_id"]
        )
        return result, 200

knowledge_service.py

火山 VikingDB 知识库 API 签名鉴权方式
示例中基于 Python SDK 生成签名。
安装火山引擎程序包: pip install volcengine

from volcengine.viking_knowledgebase import VikingKnowledgeBaseService


viking_knowledgebase_service = VikingKnowledgeBaseService(host="api-knowledgebase.mlp.cn-beijing.volces.com", scheme="https", connection_timeout=30, socket_timeout=30)
viking_knowledgebase_service.set_ak("自己的ak")
viking_knowledgebase_service.set_sk("自己的sk")

class ExternalDatasetService:
    @staticmethod
    def knowledge_retrieval(retrieval_setting: dict, query: str, knowledge_id: str):
        top_k = retrieval_setting.get("top_k")
        res = viking_knowledgebase_service.search_knowledge(collection_name=knowledge_id, query=query, limit=top_k)
        result_list = res["result_list"]
        if len(result_list) <= top_k:
            top_result = result_list
        else:
            top_result = result_list[:top_k]
        # parse response
        results = []

        for retrieval_result in top_result:
            # filter out results with score less than threshold
            if retrieval_result.get("score") < retrieval_setting.get("score_threshold", .0):
                continue
            result = {
                "metadata": retrieval_result.get("doc_info"),
                "score": retrieval_result.get("score"),
                "title": retrieval_result.get("chunk_title"), # chunk title
                "content": retrieval_result.get("content"),
            }
            results.append(result)
        return {
            "records": results
        }

在该示例中，Dify 传递的 knowledge_id 实际作为火山 VikingDB 知识库中的知识库名，默认 project 为 default，可以根据自身需要调整代码。

3. 获取火山 VikingDB 知识库 Knowledge Base ID

登录 VikingDB 知识库，获取已创建知识库名。此参数将会在后续步骤用于与 Dify 平台的连接。

4. 关联外部知识 API

前往 Dify 平台中的 “知识库” 页，点击右上角的 “外部知识库 API”，轻点 “添加外部知识库 API”。
按照页面提示，依次填写以下内容：
知识库的名称，允许自定义名称，用于区分 Dify 平台内所连接的不同外部知识 API；
API 接口地址，外部知识库的连接地址，可在第二步中自定义。示例 api-endpoint/retrieval；
API Key，外部知识库连接密钥，可在第二步中自定义。

5. 连接外部知识库

前往 “知识库” 页，点击添加知识库卡片下方的 “连接外部知识库” 跳转至参数配置页面。

填写以下参数：
知识库名称与描述

外部知识库 API
选择在第四步中关联的外部知识库 API

外部知识库 ID
填写在第三步中获取的火山 VikingDB Knowledge Collection Name

调整召回设置
Top K：用户发起提问时，将请求外部知识 API 获取相关性较高的内容分段。该参数用于筛选与用户问题相似度较高的文本片段。默认值为 3，数值越高，召回存在相关性的文本分段也就越多。
Score 阈值：文本片段筛选的相似度阈值，只召回超过设置分数的文本片段，默认值为 0.5。数值越高说明对于文本与问题要求的相似度越高，预期被召回的文本数量也越少，结果也会相对而言更加精准。

设置完成后即可建立与外部知识库 API 的连接。

6. 测试外部知识库连接与召回

建立与外部知识库的连接后，开发者可以在 “召回测试” 中模拟可能的问题关键词，预览从火山 VikingDB 知识库召回的文本分段。

若对于召回结果不满意，可以根据召回接口尝试在代码中修改召回参数，当前 VikingDB 知识库还未提供固化召回参数的实体概念（敬请期待）。

7. 应用案例：基于豆包模型 + VikingDB 知识库构建聊天 bot

在建立好外部知识库后，可以在 “工作室” 中使用豆包模型和上面建立的外部 VikingDB 知识库构建聊天机器人。