버킷

**버킷(bucket)**은 Schift의 공개 지식 저장소(public knowledge storage surface)다. 문서 집합과 추출된 텍스트, 임베딩(embedding), 그리고 검색 인덱스를 보유하며, 답변 준비가 완료된 검색 결과 반환을 위한 단일 엔드포인트(endpoint)를 제공한다.

버킷을 생성하고, 파일을 업로드하고, 인덱싱(indexing)이 완료될 때까지 기다린 후 검색을 호출한다. Schift는 임베딩 모델(embedding model), 벡터 백엔드(vector backend), 청킹(chunking), OCR, 재순위화(reranking), 그리고 인용 형식 지정(citation formatting)을 관리하므로 사용자가 이 구성 요소들을 직접 연결할 필요가 없는다.

버킷에 포함된 것

각 버킷은 다음을 포함하는 관리형 컬렉션(managed collection)을 나타냅다:

• 문서 , PDF, Markdown, 일반 텍스트, Office 파일, 이미지, 그리고 기타 지원되는 업로드 파일들이다.
• 추출된 청크 , 파싱과 OCR을 통해 생성된 텍스트 조각들이다.
• 임베딩 , 버킷에 구성된 임베딩 모델로 생성된 밀집 벡터 표현(dense vector representation)이다.
• 메타데이터 , 필터링과 접근 제어(access control)를 위해 문서에 부착된 사용자 정의 키-값 쌍이다.
• 검색 인덱스 , 관리형 검색 파이프라인(managed search pipeline)에서 사용하는 벡터 및 어휘 구조이다.

버킷은 조직(organization)별로 격리된다. 버킷 이름은 내부 시스템 컬렉션용으로 예약된 __schift_ 접두사(prefix)로 시작해서는 안 된다.

버킷의 구현 방식

버킷을 생성하면 Schift가 컬렉션을 자동 구성한다:

• 기본 텍스트 임베딩 모델과 차원(dimension)을 선택한다.
• 일반적으로 engine 백엔드를 사용하는 벡터 백엔드를 선택한다.
• 기본 벡터 테이블을 생성한다.

이는 새 버킷이 생성 직후 문서 수신이 준비되었음을 의미한다. 직접 임베딩 엔드포인트나 벡터 데이터베이스를 구성할 필요가 없는다.

문서 처리는 비동기(asynchronous)이다. 파일을 업로드하면 Schift는 즉시 작업 ID(job ID)를 반환한 후, 백그라운드에서 추출, 청킹, 임베딩, 그리고 인덱싱을 수행한다. 버킷이 질의(query)에 응답할 준비가 되었는지 확인하기 위해 GET /v2/buckets/{bucket_id}/search/status를 폴링(poll)할 수 있는다.

버킷 라이프사이클

버킷 생성

이름과 선택적 설명(optional description)을 포함하여 POST /v2/buckets를 사용한다. 응답에는 버킷 ID, 차원, 모델, 백엔드, 그리고 개수(counts)가 포함된다.

문서 업로드

하나 이상의 파일을 업로드하려면 POST /v2/buckets/{bucket_id}/documents를 사용한다. 지원되는 옵션은 OCR 전략, 청크 크기(chunk size), 청크 중첩(chunk overlap), 그리고 문서 메타데이터를 포함한다. 각 업로드는 Jobs API나 검색 준비 상태 엔드포인트(search readiness endpoint)를 통해 추적할 수 있는 백그라운드 작업(background jobs)을 반환한다.

참고: 파일 개수와 전체 배치 크기(total batch size)에 대해 요청당 제한(per-request limits)이 있는다. 대용량 업로드는 더 작은 배치로 분할해야 한다.

검색 준비 상태 확인

버킷의 답변에 의존하기 전에 GET /v2/buckets/{bucket_id}/search/status를 호출하세요. ready 상태는 대기 중인 모든 인덱싱 작업(indexing jobs)이 완료되었고 버킷이 검색 요청(search requests)을 처리할 수 있음을 의미한다.

검색

관리형 지식 검색 파이프라인(managed knowledge-search pipeline)을 실행하려면 POST /v2/buckets/{bucket_id}/search를 사용한다. 요청은 질의(query), top-k 값, 컨텍스트 예산(context budget), 메타데이터 필터(metadata filters), 그리고 재순위화 옵션(reranking options)을 받는다. 응답에는 붙여넣기 준비가 완료된 컨텍스트 블록(context block)과 원본 문서를 가리키는 인용(citations)이 포함된다.

문서 관리

/v2/buckets/{bucket_id}/documents 엔드포인트를 통해 문서를 나열하고, 조회하고, 메타데이터를 업데이트하고, 삭제할 수 있는다. 문서 삭제 역시 비동기이며 작업 ID(job ID)를 반환한다.

버킷 수정 또는 삭제

이름, 설명, 메타데이터와 같은 변경 가능한 필드(mutable fields)를 수정하려면 PATCH /v2/buckets/{bucket_id}를 사용한다. 버킷 삭제를 대기열에 넣으려면 DELETE /v2/buckets/{bucket_id}를 사용한다. 공개 버킷(public buckets)은 읽기 전용(read-only)이며 수정하거나 삭제할 수 없는다.

메타데이터와 접근 제어

문서는 검색 중 필터링과 콘텐츠 구성을 위해 사용되는 사용자 정의 메타데이터를 가질 수 있는다. 버킷은 또한 문서가 검색되고 노출되는 방식을 제어하는 개인정보 보호 및 접근 정책(privacy and access-policy) 설정을 지원한다.

서버에서 기록된 접근 정책 키(server-stamped access policy keys)를 포함한 예약된 메타데이터 키(reserved metadata keys)는 호출자(caller)가 설정할 수 없는다. 메타데이터를 업데이트할 때 Schift는 값을 정리하고 검증(sanitizes and validates)하여 버킷을 일관된 상태(consistent state)로 유지한다.

API 버전

공개 제품 API는 v2이다. 새로운 통합(integrations)은 위에서 설명한 /v2/buckets/* 경로를 사용해야 한다.

기존 /v1/buckets/*, /v1/query, 그리고 /v1/collections/*/search 경로는 기존 클라이언트를 위한 호환성 표면(compatibility surfaces)으로 남아 있는다. 새로운 통합에는 권장되지 않으며, 관리형 v2 검색 파이프라인(managed v2 search pipeline)과 같은 일부 최신 기능은 v2에서만 사용할 수 있는다.

참고

• Buckets API