Учебное пособие Dify по подключению к внешним базам знаний

Для простоты изложения в данной статье мы будем Dify Хранилища знаний за пределами Платформы в совокупности называются "внешними хранилищами знаний".

Введение функции

Встроенная в Dify функциональность базы знаний и механизмы поиска текста могут не удовлетворить потребности некоторых продвинутых разработчиков, которым требуется более точный контроль над результатами поиска текста.

Некоторые команды предпочитают проводить самостоятельные исследования RAG Алгоритмы и поддержка системы запоминания текста самостоятельно, либо использование сервиса базы знаний, предоставляемого облачным провайдером (например, AWS Bedrock).

Dify, как открытая платформа для разработки LLM-приложений, хочет предоставить разработчикам больше возможностей.

Dify может подключаться к внешним базам знаний с помощью функции "Подключение к внешним базам знаний". Это дает приложениям искусственного интеллекта доступ к большему количеству источников информации.

В частности, это следующие преимущества:

• Dify может напрямую обращаться к тексту, размещенному в базе знаний облачного провайдера, что избавляет разработчиков от необходимости копировать содержимое в базу знаний Dify.
• Dify может напрямую обращаться к алгоритмически обработанному тексту в самостоятельно созданной базе знаний, и разработчикам остается только сосредоточиться на оптимизации механизма поиска информации для повышения точности запоминания.
• По сравнению с прямым использованием сервисов баз знаний облачных поставщиков, Dify предоставляет более гибкие возможности интеграции на уровне приложений, что облегчает разработчикам создание разнообразных приложений ИИ.

На следующем рисунке показан принцип подключения к внешней базе знаний:

Этапы подключения

1. создание совместимой внешней базы знаний API

Перед настройкой службы API внимательно ознакомьтесь со спецификацией API внешней базы знаний, написанной компанией Dify.

2. Ассоциированные API внешних баз знаний

Обратите внимание, что в настоящее время Dify поддерживает только получение внешних баз знаний, но не их модификацию. Разработчикам необходимо самостоятельно поддерживать внешние базы знаний.

Перейдите на страницу "База знаний", нажмите "Внешний API базы знаний" в правом верхнем углу, а затем нажмите "Добавить внешний API базы знаний".

Следуйте подсказкам страницы, чтобы заполнить форму:

• Название базы знаний: Может быть настроена для различения различных API внешних баз знаний.
• Адрес интерфейса API: Адрес ссылки на внешнюю базу знаний, например. api-endpoint/retrieval. Подробные инструкции см. во внешней базе знаний API.
• Ключ API: Ключ подключения к внешней базе знаний, подробнее см. в разделе Внешняя база знаний API.

3. подключение к внешним базам знаний

На экране "База знаний" нажмите "Подключиться к внешней базе знаний" в разделе "Добавить базу знаний", чтобы перейти на экран настройки параметров.

Заполните следующие параметры:

• Название и описание базы знаний
• Внешний API базы знаний: Выберите API внешней базы знаний, связанный с ней на шаге 2. Dify вызовет текстовое содержимое внешней базы знаний через API-соединение.
• Внешний идентификатор базы знаний: Укажите идентификатор внешней базы знаний, с которой необходимо связать базу, подробнее см. в разделе API внешней базы знаний.
• Настройка параметров вызова:
  • Топ К: Чем больше значение, тем больше фрагментов текста будет вызвано. Рекомендуется начать экспериментировать с меньшими значениями и постепенно увеличивать их, пока не будет найден оптимальный баланс.
  • Пороговый балл: Чем выше значение, тем более релевантными для вопроса являются отобранные сегменты текста, но их количество уменьшается. Рекомендуется начинать с более высокого значения и постепенно уменьшать его, чтобы получить достаточное количество релевантного текста.

4. Проверка соединений и отзывы

После установления соединения вы можете смоделировать проблемные ключевые слова в "Тесте отзыва" и просмотреть фрагменты текста, вызванные из внешней базы знаний. Если вы не удовлетворены результатами, можно попробовать изменить параметры отзыва или настроить параметры поиска во внешней базе знаний.

5. интеграция в приложения

• Чатботы / агенты: На странице "Контекст аранжировки" выберите экран с кнопкой EXTERNAL Внешняя база знаний с меткой.

• Приложение типа Chatflow / Workflow: Добавьте узел Knowledge Retrieval и выберите узел с именем EXTERNAL Внешняя база знаний с меткой.

6. управление внешней базой знаний

На странице "База знаний" карточка "Внешняя база знаний" будет иметь следующий текст в правом верхнем углу EXTERNAL Вкладка. Введите базу знаний, которую вы хотите изменить, и нажмите "Настройки", чтобы изменить ее:

• Название и описание базы знаний
• Область видимости ("Только я", "Все члены команды" и "Некоторые члены команды"). Участники, не имеющие прав доступа, не могут получить доступ к базе знаний.
• Настройки запоминания (пороговые значения Top K и Score)

Примечание: Невозможно изменить связанный API внешней базы знаний и идентификатор внешних знаний, если вы хотите изменить их, пожалуйста, создайте новый API внешней базы знаний и подключите его заново.

Пример подключения: Как подключиться к базе знаний AWS Bedrock?

В этом документе рассказывается о том, как платформа Dify может быть подключена к базе знаний AWS Bedrock через внешний API базы знаний, что позволяет приложениям искусственного интеллекта в платформе Dify напрямую обращаться к контенту, хранящемуся в базе знаний AWS Bedrock, расширяя доступ к новым источникам информации.

предварительное размещение

• База знаний AWS Bedrock
• Услуги Dify SaaS / Dify Community Edition
• Основы разработки внутренних API

1. Зарегистрируйтесь и создайте базу знаний AWS Bedrock

Посетите AWS Bedrock, чтобы создать службу базы знаний.

2. Создание внутренних API-сервисов

Платформа Dify пока не может напрямую подключаться к базе знаний AWS Bedrock, поэтому команде разработчиков необходимо обратиться к определению API Dify по подключению к внешней базе знаний и вручную создать внутренний API-сервис для установления соединения с AWS Bedrock. Пожалуйста, ознакомьтесь с диаграммой архитектуры:

Вы можете обратиться к следующим двум файлам кода, чтобы создать 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

import boto3

class ExternalDatasetService:
    @staticmethod
    def knowledge_retrieval(retrieval_setting: dict, query: str, knowledge_id: str):
        # get bedrock client
        client = boto3.client(
            "bedrock-agent-runtime",
            aws_secret_access_key="AWS_SECRET_ACCESS_KEY",
            aws_access_key_id="AWS_ACCESS_KEY_ID",
            # example: us-east-1
            region_name="AWS_REGION_NAME",
        )
        # fetch external knowledge retrieval
        response = client.retrieve(
            knowledgeBaseId=knowledge_id,
            retrievalConfiguration={
                "vectorSearchConfiguration": {"numberOfResults": retrieval_setting.get("top_k"), "overrideSearchType": "HYBRID"}
            },
            retrievalQuery={"text": query},
        )
        # parse response
        results = []
        if response.get("ResponseMetadata") and response.get("ResponseMetadata").get("HTTPStatusCode") == 200:
            if response.get("retrievalResults"):
                retrieval_results = response.get("retrievalResults")
                for retrieval_result in retrieval_results:
                    # 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("metadata"),
                        "score": retrieval_result.get("score"),
                        "title": retrieval_result.get("metadata").get("x-amz-bedrock-kb-source-uri"),
                        "content": retrieval_result.get("content").get("text"),
                    }
                    results.append(result)
        return {
            "records": results
        }

В этом процессе вы можете создать адрес интерфейса API и ключ API для аутентификации и последующих подключений.

3. Получите идентификатор базы знаний AWS Bedrock

Войдите в бэкэнд AWS Bedrock Knowledge и получите идентификатор созданной базы знаний. Этот параметр будет использоваться в последующих шагах для подключения к платформе Dify.

4. API связанных внешних знаний

Перейдите на платформу Dify "База знаний" Страница, нажмите на правый верхний угол "Внешний API базы знаний"Расслабьтесь. "Добавить внешний API базы знаний".

Следуя подсказкам страницы, заполните следующие поля по порядку:

• Название базы знаний, позволяющее настраивать имя для различения различных внешних API знаний, подключенных к платформе Dify;
• Адрес интерфейса API, адрес подключения к внешней базе знаний, можно настроить на втором этапе. Пример api-endpoint/retrieval.;
• API Key, ключ подключения к внешней базе знаний, можно настроить на втором этапе.

5. подключение к внешним базам знаний

уезжать "База знаний" На странице нажмите на карточку Добавить базу знаний, расположенную под "Подключение к внешним базам знаний" Переход на страницу конфигурации параметров.

Заполните следующие параметры:

• Название и описание базы знаний
• Внешний API базы знанийВыберите API внешней базы знаний, связанный с ней в шаге 4
• Идентификатор внешней базы знанийВведите идентификатор базы знаний AWS Bedrock, полученный в шаге 3
• Настройка параметров повторного воспроизведенияTop K: когда пользователь задает вопрос, внешний API знаний запрашивается для получения сегментов контента с высокой степенью релевантности. Этот параметр используется для фильтрации текстовых сегментов, имеющих высокую степень сходства с вопросом пользователя. Значение по умолчанию равно 3. Чем выше значение, тем более релевантные сегменты текста будут вызваны.

  Score Threshold: порог сходства для фильтрации текстовых фрагментов, только фрагменты текста, превышающие заданный балл, будут вызваны, значение по умолчанию - 0.5. Чем выше значение, тем выше сходство между текстом и вопросом, тем меньше количество текстов, которые будут вызваны, и результат будет относительно более точным.

После настройки вы можете установить соединение с внешним API базы знаний.

6. тестирование подключений к внешним базам знаний и вызовов

Установив соединение с внешней базой знаний, разработчик может "Испытание на отзыв". Моделирование возможных проблемных ключевых слов в предварительном просмотре текстовых сегментов, вызванных из базы знаний AWS Bedrock.

Если результаты отзыва вас не устраивают, вы можете попробовать изменить параметры отзыва или самостоятельно настроить параметры поиска в базе знаний AWS Bedrock.

общие проблемы

Что делать, если при подключении к внешнему API базы знаний возникает ошибка?

Ниже приведены коды ошибок и соответствующие решения:

Спецификация API внешней базы знаний

начальная или конечная точка (в рассказах и т.д.)

POST <your-endpoint>/retrieval

заголовок запроса

Этот API используется для подключения к независимо поддерживаемым базам знаний внутри команды. Дополнительное руководство по подключению к внешним базам знаний см. в разделе Подключение к внешним базам знаний.

можно найти в заголовке HTTP-запроса Authorization поля с помощью API-Key для проверки подлинности разрешений. Логика аутентификации определяется вами в Retrieval API, как показано ниже:

Authorization: Bearer {API_KEY}

запросчик

Запрос принимает данные в следующем формате JSON:

retrieval_setting Атрибут содержит следующие ключи:

Пример запроса

POST <your-endpoint>/retrieval HTTP/1.1
Content-Type: application/json
Authorization: Bearer your-api-key
{
"knowledge_id": "your-knowledge-id",
"query": "你的问题",
"retrieval_setting": {
"top_k": 2,
"score_threshold": 0.5
}
}

орган реагирования

Если операция выполнена успешно, служба возвращает ответ HTTP 200 со следующими данными в формате JSON:

records Атрибут представляет собой список объектов, содержащих следующие ключи:

Образец ответа

HTTP/1.1 200
Content-Type: application/json
{
"records": [
{
"metadata": {
"path": "s3://dify/knowledge.txt",
"description": "dify 知识文档"
},
"score": 0.98,
"title": "knowledge.txt",
"content": "这是外部知识的文档。"
},
{
"metadata": {
"path": "s3://dify/introduce.txt",
"description": "dify 介绍"
},
"score": 0.66,
"title": "introduce.txt",
"content": "GenAI 应用程序的创新引擎"
}
]
}

неправильный

Если операция не удалась, служба возвращает следующее сообщение об ошибке (в формате JSON):

error_code Тип атрибута:

Код состояния HTTP

• AccessDeniedException: Отсутствие прав доступа. (Код состояния HTTP: 403)
• InternalServerException: Внутренняя ошибка сервера. (Код состояния HTTP: 500)