버킷

**버킷(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