외부 지식창고 연결에 대한 Dify 튜토리얼

쉽게 구분할 수 있도록 이 백서에서는 다음과 같이 설명합니다. Dify 플랫폼 외부의 지식 저장소를 통칭하여 "외부 지식 저장소"라고 합니다.

기능 소개

Dify의 기본 제공 지식창고 기능과 텍스트 검색 메커니즘은 텍스트 검색 결과를 보다 정밀하게 제어해야 하는 일부 고급 개발자의 요구 사항을 충족하지 못할 수 있습니다.

일부 팀은 자체 조사를 선택합니다. RAG 알고리즘을 사용하고 텍스트 리콜 시스템을 독립적으로 유지 관리하거나 클라우드 제공업체(예: AWS Bedrock)에서 제공하는 지식창고 서비스를 사용할 수 있습니다.

개방형 LLM 애플리케이션 개발 플랫폼인 Dify는 개발자에게 더 많은 옵션을 제공하고자 합니다.

Dify는 '외부 지식 베이스에 연결' 기능을 통해 외부 지식 베이스에 연결할 수 있습니다. 이를 통해 AI 애플리케이션은 더 많은 정보 소스에 액세스할 수 있습니다.

구체적으로 다음과 같은 이점이 있습니다:

• Dify는 클라우드 제공업체의 지식창고에 호스팅된 텍스트에 직접 액세스할 수 있으므로 개발자가 콘텐츠를 Dify의 지식창고에 복사할 필요가 없습니다.
• Dify는 자체 구축된 지식 베이스에서 알고리즘으로 처리된 텍스트에 직접 액세스할 수 있으며, 개발자는 검색 정확도를 높이기 위해 정보 검색 메커니즘을 최적화하는 데만 집중하면 됩니다.
• 클라우드 공급업체의 지식창고 서비스를 직접 사용하는 것과 비교하여 Dify는 보다 유연한 애플리케이션 계층 통합 기능을 제공하므로 개발자가 다양한 AI 애플리케이션을 쉽게 구축할 수 있습니다.

다음 그림은 외부 지식창고에 연결하는 원리를 설명합니다:

연결 단계

1. 규정을 준수하는 외부 지식창고 API 구축

API 서비스를 설정하기 전에 Dify에서 작성한 외부 기술 자료 API 사양을 주의 깊게 읽어보세요.

2. 연결된 외부 지식창고 API

현재 Dify는 외부 지식창고를 검색하는 기능만 지원하며 수정하는 기능은 지원하지 않습니다. 개발자가 직접 외부 지식창고를 유지 관리해야 합니다.

'지식창고' 페이지로 이동하여 오른쪽 상단에 있는 '외부 지식창고 API'를 클릭한 다음 '외부 지식창고 API 추가'를 클릭합니다.

페이지의 안내에 따라 양식을 작성합니다:

• 지식창고 이름: 다양한 외부 지식창고 API를 차별화하도록 사용자 지정할 수 있습니다.
• API 인터페이스 주소입니다: 외부 지식창고로 연결되는 링크 주소(예 api-endpoint/retrieval. 자세한 지침은 외부 지식창고 API를 참조하세요.
• API 키: 외부 지식창고에 대한 연결 키는 자세한 내용은 외부 지식창고 API를 참조하세요.

3. 외부 지식창고에 연결하기

'지식창고' 화면의 '지식창고 추가' 아래에서 '외부 지식창고에 연결'을 클릭하여 매개변수 구성 화면으로 들어갑니다.

다음 매개변수를 입력합니다:

• 지식창고 이름 및 설명
• 외부 지식창고 API: 2단계에서 연결된 외부 지식창고 API를 선택합니다. 디파이가 API 연결을 통해 외부 지식창고의 텍스트 콘텐츠를 호출합니다.
• 외부 지식창고 ID: 연동할 외부 지식창고의 ID를 지정하고, 자세한 내용은 외부 지식창고 API를 참조하세요.
• 리콜 설정을 조정합니다:
  • Top K: 값이 클수록 더 많은 텍스트 조각을 불러옵니다. 더 작은 값으로 실험을 시작하여 최적의 균형을 찾을 때까지 점차적으로 값을 늘려가는 것이 좋습니다.
  • 점수 임계값: 값이 높을수록 불러오는 텍스트 세그먼트가 질문과 더 관련성이 높지만 그 수는 감소합니다. 충분한 양의 관련 텍스트를 얻으려면 높은 값으로 시작하여 점차적으로 값을 낮추는 것이 좋습니다.

4. 연결 테스트 및 리콜

연결이 설정된 후에는 "리콜 테스트"에서 문제 키워드를 시뮬레이션하고 외부 지식창고에서 리콜된 텍스트 조각을 미리 볼 수 있습니다. 결과가 만족스럽지 않은 경우에는 리콜 매개변수를 수정하거나 외부 지식창고의 검색 설정을 조정해 볼 수 있습니다.

5. 애플리케이션 내 통합

• 챗봇/상담원 유형 애플리케이션: 편곡 페이지의 컨텍스트에서 화면을 선택합니다. EXTERNAL 태그가 지정된 외부 지식창고.

• 채팅 플로우/워크플로 유형 애플리케이션: 지식 검색 노드를 추가하고 노드를 선택한 다음 EXTERNAL 태그가 지정된 외부 지식창고.

6. 외부 지식창고 관리

지식창고 페이지에서 외부 지식창고 카드의 오른쪽 위 모서리에 다음과 같은 텍스트가 표시됩니다. EXTERNAL 탭을 클릭합니다. 수정하려는 지식창고를 입력하고 '설정'을 클릭하여 수정합니다:

• 지식창고 이름 및 설명
• 공개 범위('나만', '모든 팀원' 및 '일부 팀원'). 권한이 없는 팀원은 지식창고에 액세스할 수 없습니다.
• 리콜 설정(상위 K 및 점수 임계값)

참고: 연결된 외부 지식창고 API 및 외부 지식 ID는 수정할 수 없으며, 수정하려면 새 외부 지식창고 API를 연결한 후 다시 연결하세요.

연결 예: AWS 베드락 지식창고에 연결하려면 어떻게 하나요?

이 백서에서는 외부 지식 베이스 API를 통해 Dify 플랫폼을 AWS 베드락 지식 베이스에 연결하여 Dify 플랫폼 내의 AI 애플리케이션이 AWS 베드락 지식 베이스에 저장된 콘텐츠에 직접 액세스하여 새로운 정보 소스에 대한 액세스를 확장할 수 있는 방법을 간략하게 설명합니다.

사전 포지셔닝

• AWS 베드락 기술 자료
• Dify SaaS 서비스 / Dify 커뮤니티 에디션
• 백엔드 API 개발 기본 사항

1. AWS 베드락 지식창고 등록 및 생성하기

지식창고 서비스를 생성하려면 AWS 베드락을 방문하세요.

2. 백엔드 API 서비스 구축

Dify 플랫폼은 아직 AWS 베드락 지식창고에 직접 연결할 수 없으며, 개발팀이 외부 지식창고 연결에 대한 Dify의 API 정의를 참조하고 백엔드 API 서비스를 수동으로 생성하여 AWS 베드락과의 연결을 설정해야 합니다. 아키텍처 다이어그램을 참조하세요:

다음 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

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 지식창고 ID 얻기

이 매개 변수는 이후 단계에서 Dify 플랫폼에 연결하기 위해 사용됩니다. AWS 베드락 지식창고 백엔드에 로그인하여 생성된 지식창고의 ID를 얻습니다.

4. 외부 지식 API 연동

Dify 플랫폼으로 이동 "지식창고" 페이지의 오른쪽 상단 모서리를 클릭하고 "외부 지식창고 API"밝게. "외부 지식창고 API 추가".

페이지의 지시에 따라 다음을 순서대로 작성합니다:

• 지식창고의 이름으로, Dify 플랫폼 내에 연결된 다양한 외부 지식 API를 구분할 수 있도록 사용자 지정할 수 있습니다;
• 외부 지식창고의 연결 주소인 API 인터페이스 주소는 두 번째 단계에서 사용자 지정할 수 있습니다. 예시 api-endpoint/retrieval.;
• 두 번째 단계에서 외부 지식창고 연결 키인 API 키를 사용자 지정할 수 있습니다.

5. 외부 지식창고에 연결하기

떠나기 "지식창고" 페이지 아래의 지식 기반 추가 카드를 클릭합니다. "외부 지식창고에 연결" 매개변수 구성 페이지로 이동합니다.

다음 매개변수를 입력합니다:

• 지식창고 이름 및 설명
• 외부 지식창고 API4단계에서 연결된 외부 지식창고 API를 선택합니다.
• 외부 지식창고 ID3단계에서 얻은 AWS Bedrock 지식창고 ID를 입력합니다.
• 리콜 설정 조정상위 K: 사용자가 질문을 시작하면 관련성이 높은 콘텐츠 세그먼트를 얻기 위해 외부 지식 API가 요청됩니다. 이 매개변수는 사용자의 질문과 유사성이 높은 텍스트 세그먼트를 필터링하는 데 사용됩니다. 기본값은 3이며 값이 클수록 관련성이 높은 텍스트 세그먼트가 더 많이 리콜됩니다.

  점수 임계값: 텍스트 조각 필터링을 위한 유사도 임계값으로, 설정된 점수를 초과하는 텍스트 조각만 불러오며 기본값은 0.5입니다. 값이 클수록 텍스트와 문제 간의 유사도가 높을수록 불러올 것으로 예상되는 텍스트의 수가 적어지고 결과는 상대적으로 더 정확해집니다.

설정이 완료되면 외부 지식창고 API에 연결할 수 있습니다.

6. 외부 지식창고 연결 및 리콜 테스트하기

외부 지식창고에 연결을 설정한 후 개발자는 다음을 수행할 수 있습니다. "리콜 테스트." AWS 베드락 지식 베이스에서 불러온 텍스트 세그먼트의 미리 보기에서 가능한 문제 키워드를 모의해 보세요.

리콜 결과가 만족스럽지 않은 경우, 리콜 매개 변수를 수정하거나 AWS Bedrock 기술 자료 검색 설정을 직접 조정해 볼 수 있습니다.

일반적인 문제

외부 지식창고 API에 연결할 때 오류가 발생하면 어떻게 하나요?

다음은 오류 코드와 해당 해결 방법입니다:

외부 지식창고 API 사양

시작점 또는 종료점(스토리 등)

POST <your-endpoint>/retrieval

요청 헤더

이 API는 팀 내에서 독립적으로 관리되는 지식창고에 연결하는 데 사용됩니다. 이 작업을 수행하는 방법에 대한 자세한 안내는 외부 지식창고에 연결하기를 참조하세요.

는 HTTP 요청 헤더의 Authorization 필드를 사용하여 API-Key 를 사용하여 권한을 인증합니다. 인증 로직은 아래와 같이 검색 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)
• 내부 서버 예외: 내부 서버 오류입니다. (HTTP 상태 코드: 500)