Knowledge Base API 시작

기술 자료 API가 콘텐츠를 구성하고 문서를 처리하며 AI 작업을 수행하는 방법을 이해하여 플랫폼에 맞는 애플리케이션을 작성할 수 있습니다.

이 API는 컬렉션과 문서 관리, 콘텐츠 처리, 질의응답, 요약, 검색, 구조화된 추출 등의 AI 기능 적용을 위한 워크플로를 지원합니다. 이 페이지를 통해 이러한 요소들이 어떻게 함께 작동하는지 이해한 후, 엔드포인트 레벨 구현 세부 항은 API 참조를 사용하세요.

시작하기 전에

다음 사항을 확인하세요:

• Knowledge Base에 액세스합니다.
• 애플리케이션에 대한 API 액세스가 구성되었습니다.
• 컬렉션에 대한 액세스 권한이 있거나 컬렉션을 만들 권한이 있는지 확인합니다.
• Knowledge Base API 참조는 현재 엔드포인트 정의 및 스키마에 사용할 수 있습니다.

API 액세스를 구성하지 않은 경우 기술 자료 API 액세스 설정을 참조하세요.

API 작동 원리

일반적인 기술 자료 API 워크플로는 다음 순서를 따릅니다:

인증 → 컬렉션 → 문서 → 색인 → 추론 → 응답

컬렉션

컬렉션은 애플리케이션이 작업하는 지식 도메인을 정의합니다. 컬렉션을 만들면 응답에 고유 네임스페이스가 포함되며, 이를 후속 작업에서 사용합니다.

예:

{
"namespace": "<collection-namespace>",
"name": "example-collection"
}

문서 및 추론 요청에 대해 컬렉션 네임스페이스를 유지하세요.

문서

문서는 컬렉션에 업로드되고 고유한 문서 식별자가 할당됩니다.

업로드 응답은 문서를 식별하므로 애플리케이션이 처리를 추적하고 나중에 요청에서 참조할 수 있습니다.

{
"document_id": "<document-id>",
"document_name": "example.pdf"
}

색인화

문서 업로드와 색인화는 별도의 단계입니다.

업로드하면 파일이 Knowledge Base로 전송됩니다. 색인화는 콘텐츠를 추출하고 AI 작업에서 사용할 수 있도록 해당 콘텐츠를 처리합니다.

애플리케이션은 문서에 대한 추론 요청을 제출하기 전에 처리가 완료되었는지 확인해야 합니다.

추론

추론 작업은 처리된 콘텐츠에 Knowledge Base AI 기능을 적용합니다.

사용 가능한 작업은 다음과 같습니다:

• 질의응답
• 문서 요약
• 컨텍스트 검색
• 구조화된 속성 추출

수행하려는 작업의 엔드포인트와 요청 스키마를 결정하려면 API 참조를 사용하세요.

응답

추론 응답은 생성된 결과를 반환하며 보조 기여도 정보를 포함할 수 있습니다.

작업에 따라 기여도 데이터는 결과와 연관된 소스 콘텐츠, 페이지, 좌표를 식별할 수 있습니다. 해당 정보를 사용자에게 어떻게 표시할지는 애플리케이션에서 결정합니다.

기본 API 워크플로 실행

가장 간단한 애플리케이션 워크플로는 컬렉션을 생성하고, 문서를 추가하고, 처리를 기다린 후, 추론 작업을 실행하는 것입니다.

문서 처리 이해하기

문서 생명 주기는 애플리케이션이 업로드된 콘텐츠를 언제 사용할 수 있는지에 영향을 줍니다.

이러한 구분은 자동화된 워크플로에 특히 중요합니다. 애플리케이션은 업로드 후 즉시 추론 요청을 보내는 대신 처리 상태를 확인해야 합니다.

추론 작업 선택하기

소스 콘텐츠로 애플리케이션이 수행해야 하는 작업을 기반으로 작업을 선택하세요.

질의응답

Q&A를 사용해 컬렉션 또는 문서 콘텐츠에 대한 자연언어 질문을 제출하세요.

API는 스트리밍 및 비스트리밍 Q&A를 모두 제공합니다.

스트리밍 Q&A는 생성되는 대로 응답을 점진적으로 반환합니다. 인터페이스에서 생성된 콘텐츠를 점진적으로 표시해야 할 때 사용하세요.

스트리밍 Q&A는 또한 요청에 사용자 지정 지침을 적용할지 여부를 컨트롤하는 기능을 지원합니다. 스트리밍 Q&A 응답에 대해 추론이 생성되는지 여부도 제어할 수 있습니다.

비스트리밍 Q&A는 생성이 완료될 때까지 기다린 후 완성된 응답을 반환합니다. 애플리케이션에서 부분 출력을 표시할 필요가 없을 때 사용하세요.

요약

요약을 사용하여 문서 콘텐츠의 압축된 표현을 생성하세요.

API 참조는 현재 요청 요구 사항과 지원되는 입력을 정의합니다.

컨텍스트 검색

컨텍스트 검색을 사용하여 지정된 검색 텍스트와 관련된 콘텐츠를 가져오세요.

이를 통해 애플리케이션은 대화형 응답을 생성하지 않고도 관련 소스 자료를 식별할 수 있습니다.

속성 추출

애플리케이션에서 문서 콘텐츠에서 구조화된 값이 필요할 때 추출을 사용하세요.

추출 정의는 다음과 같은 정보를 식별할 수 있습니다:

속성 이름: contract_value
유형: integer
설명: 계약 금액
프롬프트: 달러로 표시된 가장 큰 계약 금액을 추출하세요.

반환된 결과에는 추출된 값, 신뢰도 정보 및 소스 기여도가 포함될 수 있습니다.

작업에서 사용하는 콘텐츠 제어

API는 요청에 참여하는 콘텐츠를 결정하는 여러 방법을 제공합니다.

컬렉션 및 문서

컬렉션 및 문서 식별자를 사용하여 작업에 사용할 수 있는 기본 콘텐츠를 정의하세요.

문서 태그

태그는 컬렉션이 아닌 문서와 연결됩니다.

문서 태그는 기술 자료 API를 통해서만 사용할 수 있으며 표준 사용자 인터페이스에는 노출되지 않습니다.

지원되는 작업과 함께 태그를 사용하여 요청에 고려되는 문서를 필터링할 수 있습니다. 예를 들어, 애플리케이션에서 문서 그룹을 금융 문서로 태그 지정하고 해당 태그가 지정된 문서로 질문을 제한할 수 있습니다.

첨부 파일

첨부 파일은 컬렉션 문서와 별개입니다.

대화에 첨부를 추가해도 해당 파일이 컬렉션에 추가되지는 않습니다. 첨부는 컬렉션 콘텐츠 및 채팅 작업 내역과 함께 생성된 응답에 컨텍스트를 제공할 수 있습니다.

애플리케이션에서 컬렉션에 영구적으로 추가하지 않고 임시 또는 대화별 콘텐츠가 필요한 경우 첨부 엔드포인트를 사용하세요.

기여도 데이터 작업하기

추론 응답에는 생성된 출력을 지원하는 소스 콘텐츠에 연결하는 기여도 정보가 포함될 수 있습니다.

기여도 데이터에는 다음과 같은 정보가 포함될 수 있습니다.

• 지원 텍스트
• 문서 정보
• 페이지 번호
• 페이지 좌표

API는 이 정보를 데이터로 제공합니다.애플리케이션에서 이를 어떻게 표시할지 결정해야 합니다.

예를 들어, 애플리케이션은 반환된 좌표를 사용하여 생성된 답변을 지원하는 위치를 식별하는 소스 강조 표시 경험을 생성할 수 있습니다.

액세스 및 요청 실패 처리

API 작업은 인증된 ID에 사용 가능한 권한을 사용합니다.

인증된 ID가 요청된 컬렉션, 문서 또는 작업에 대한 액세스 권한이 없으면 요청이 실패할 수 있습니다.

문제 해결 시:

• 반환된 HTTP 상태 및 응답을 검토하세요.
• 인증된 ID가 요청된 리소스에 액세스할 수 있는지 확인하세요.
• 추론을 실행하기 전에 문서 처리가 성공적으로 완료되었는지 확인하세요.
• 요청에 제공된 식별자가 올바른지 확인하세요.
• 응답 헤더에 반환된 X-Request-ID를 캡처합니다.

X-Request-ID는 Knowledge Base 서비스 전반에 걸쳐 요청을 식별하며 지원팀이 실패한 요청을 조사하는 데 도움이 될 수 있습니다.

구현 시 고려 사항

• 단일 업로드 요청은 최대 200개의 파일을 지원합니다. 추가 파일은 후속 요청을 통해 업로드할 수 있습니다.
• 업로드와 색인화는 별도의 작업입니다.
• 문서는 추론에 사용되기 전에 완료된 처리 상태에 도달해야 합니다.
• 첨부는 독립적인 리소스이며 컬렉션에 자동으로 추가되지 않습니다.
• 태그는 문서에 속하며 지원되는 작업에서 소스 콘텐츠를 필터링하는 데 사용할 수 있습니다.
• 현재 엔드포인트, 매개변수, 스키마 및 지원되는 작업에 대한 권위 있는 소스로 API 참조를 사용하세요.

개발 계속하기

애플리케이션에서 이러한 개념을 보여주는 실제 작동 예제를 원할 때는 Python Demo를 사용하세요.

Knowledge Base Python 데모 시작

특정 작업을 구현할 준비가 되었을 때는 API 레퍼런스를 사용하세요.

Knowledge Base API 참조 열기