Cloudflare R2 파일, 이름 그대로 AI Search에 인덱싱하는 법

Cloudflare R2에서 실제로 달라진 점

Cloudflare AI Search는 자체 콘텐츠를 검색할 수 있게 해주는 관리형 검색 서비스입니다. 데이터를 넣는 방법 중 하나가 R2 버킷이며, R2는 Cloudflare의 객체 스토리지입니다. AI Search는 버킷을 읽고, 지원되는 문서를 검색 가능한 텍스트로 변환한 뒤, 앱이 쿼리를 보낼 때 사용할 인덱스를 만듭니다.

이번 업데이트 전에는 파일 형식을 안정적으로 감지하려면 파일명 확장자가 필요했습니다. manual.pdf 같은 키는 인덱서가 파일 종류를 알아볼 수 있지만, documents/manual-alpha처럼 고정된 키만으로는 알 수 없었습니다.

이제 AI Search는 확장자 없는 객체에 저장된 일반 HTTP Content-Type으로 형식을 판별할 수 있습니다. application/pdf는 해당 바이트가 PDF라는 뜻이고, text/markdown은 Markdown이라는 뜻입니다. Cloudflare가 안내하는 지원 형식에는 text/plain, application/json, text/html, text/csv도 포함됩니다.

파일명 확장자 방식이 없어진 것은 아닙니다. Cloudflare는 여전히 인식 가능한 확장자를 더 빠르고 우선적인 감지 경로로 설명합니다. 이번 새 경로는 키를 바꿀 때 URL, 데이터베이스 참조, 테넌트 매핑, 서명 또는 이미 운영 중인 업로드 규약이 깨지는 경우에 특히 유용합니다.

여기서 반드시 구분해야 할 점이 있습니다. Content-Type은 R2 객체에 붙는 HTTP 메타데이터입니다. 카테고리, 고객, 문서 상태 같은 필터에 AI Search가 쓰는 사용자 지정 메타데이터가 아닙니다. 사용자 지정 필드는 x-amz-meta-* 헤더에 실리며 AI Search에서 스키마를 정의해야 합니다. x-amz-meta-content-type을 추가해도 실제 HTTP 필드를 대신할 수 없습니다.

이번 변화가 적용되는 지점은 문서가 인덱스에 들어오는 소스 수집 단계입니다. 검색된 내용을 바탕으로 답변을 작성하는 모델은 바뀌지 않습니다. GLM-5.3 Flash 업데이트는 그 이후의 생성 단계에 해당합니다.

핵심 변화는 파일명 체계를 하나 덜 관리하는 것입니다

불투명한 키가 널리 쓰이는 데는 이유가 있습니다. 제품에서 고정된 데이터베이스 ID를 R2 키로 사용하면 객체 내용이 바뀌어도 주소는 그대로 둘 수 있습니다. 문서 서비스는 고객의 원래 파일명이 노출되지 않도록 할 수 있고, 서명된 URL은 정확한 키에 의존할 수도 있습니다.

기존 우회 방식은 검색용 사본에 확장자가 있는 이름을 새로 만들거나, AI Search가 객체를 보기 전에 이름 변경 단계를 추가하는 것이었습니다. 그러면 저장하고, 대조하고, 정리해야 할 식별자가 하나 더 생깁니다.

이번 업데이트로 HTTP 메타데이터가 이미 올바른 객체는 원래 키를 그대로 유지할 수 있습니다. 운영 측면에서 실질적으로 줄어드는 일이 바로 이 부분입니다.

업데이트 전후의 수집 작업을 비교하면 다음과 같습니다. 실제 측정 벤치마크나 보장된 절감액이 아니라, 작업 흐름을 설명하기 위한 모델입니다.

이 표가 비용 절감액을 제시하지 않는 데는 이유가 있습니다. Cloudflare는 이 기능으로 절약되는 시간을 공개하지 않았으며, 이번 릴리스가 기존 메타데이터를 자동으로 다시 작성해 주지도 않습니다.

남은 작업에는 얼마의 비용이 드는가

AI Search는 오픈 베타 기간에 무료이며, 사용 중인 Workers 플랜의 한도 안에서 이용할 수 있습니다. 스토리지와 벡터 인덱싱도 포함됩니다. Workers AI와 AI Gateway 사용량은 별도로 과금될 수 있지만, 이번 수집 방식 변경이 그 요금을 바꾸지는 않습니다.

메타데이터를 복구하면 R2 비용이 발생할 수 있습니다. ListObjects, PutObject, CopyObject는 Class A 작업으로 계산됩니다. 복구 도구가 객체를 검사하거나 읽을 때 사용할 수 있는 HeadObject와 GetObject는 Class B 작업입니다.

Standard storage의 Class A 요청은 월간 무료 허용량 1 million건을 넘으면 $4.50 per million입니다. Infrequent Access에는 무료 구간이 없으며 Class A 요청 가격은 $9.00 per million입니다. 객체를 읽거나 복사할 때는 $0.01 per GB가 추가될 수도 있습니다.

따라서 예산 원칙은 명확합니다. Content-Type이 올바른 객체는 이름 변경을 위한 복구가 필요 없습니다. 값이 잘못된 객체는 사용하는 도구에 따라 쓰기 또는 복사 작업이 필요할 수 있습니다. 버킷 전체를 정리하기 전에 이런 작업 수부터 계산해야 합니다.

AI Search 측에서는 규모도 따져야 합니다. Workers Free의 인스턴스당 한도는 100,000개 파일입니다. Workers Paid에서는 1 million개 파일까지 허용되며, 하이브리드 검색을 켜면 500,000개입니다. 4 MB 파일 제한은 두 플랜 모두 같습니다.

지금 바로 적용할 수 있는 팀

고정 업로드 ID로 혼자 서비스를 운영하는 SaaS 창업자

데이터베이스에 이미 저장된 R2 키는 유지하고, 업로더가 객체를 쓸 때 실제 MIME 형식을 함께 저장하도록 합니다. 그러면 고객 지원 검색이 두 번째 파일명 열이나 검색용 사본을 만드는 배치 작업 없이 같은 객체를 수집할 수 있습니다.

고객이 문서를 교체하거나 삭제하거나 이동할 때 대조해야 할 식별자가 줄어듭니다. 다만 검색 대상 객체라면 업로드 단계에서 범용 바이너리 형식을 계속 거부해야 합니다.

레거시 버킷을 관리하는 플랫폼 엔지니어

확장자 없는 객체와 그 HTTP 메타데이터를 나열하고, 각 값을 Cloudflare가 지원하는 MIME 형식과 비교해 실패 대상을 분리합니다. 버킷 전체를 건드리기 전에 작은 표본부터 복구합니다.

이렇게 하면 마이그레이션 범위를 통제할 수 있습니다. 실제 복구가 필요한 객체에만 비용을 쓰고, 유효한 메타데이터가 있는 키는 곧바로 동기화와 검증 단계로 넘길 수 있습니다.

멀티테넌트 제품팀

원래 파일명을 노출하지 않는 불투명한 객체 키를 유지하고, 업로드할 때 신뢰할 수 있는 서버 측 검사 결과로 Content-Type을 설정합니다. 테넌트마다 인덱싱 경계를 나눠야 한다면 AI Search 경로 필터나 접두사는 별도로 적용합니다.

그 결과 아키텍처의 일관성을 지킬 수 있습니다. 스토리지의 식별자는 파일 표시 방식과 분리하면서도, 인덱서에는 검증 가능한 형식 정보를 제공할 수 있습니다.

고객 지식베이스를 운영하는 에이전시

런북에서 두 가지 메타데이터 작업을 분리합니다. HTTP Content-Type은 확장자 없는 파일을 수집할 수 있는지 결정합니다. 사용자 지정 x-amz-meta-* 필드는 스키마를 정의한 뒤 인덱싱된 결과를 어떻게 필터링할지 결정합니다.

문제 원인을 찾기도 쉬워집니다. 문서가 보이지 않을 때 필터 규칙이나 답변 모델부터 바꾸는 대신, 팀이 먼저 수집 메타데이터를 확인할 수 있습니다.

확장자 없는 파일을 Cloudflare R2 지원 경로에 넣는 방법

Cloudflare의 R2 Workers API는 요청 헤더를 httpMetadata로 받을 수 있습니다. 아래 Worker는 요청 경로를 객체 키로 그대로 쓰고, Content-Type 없이 들어온 업로드는 거부합니다.

wrangler.jsonc에서 R2 버킷을 DOCS로 바인딩합니다.

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "r2-document-upload",
  "main": "src/index.ts",
  "compatibility_date": "2026-09-11",
  "r2_buckets": [
    {
      "binding": "DOCS",
      "bucket_name": "your-bucket"
    }
  ]
}

그런 다음 아래 Worker를 사용합니다.

interface Env {
  DOCS: R2Bucket;
}

export default {
  async fetch(request, env): Promise<Response> {
    if (request.method !== "PUT") {
      return new Response("Method Not Allowed", { status: 405 });
    }

    const key = new URL(request.url).pathname.replace(/^\//, "");
    const contentType = request.headers.get("content-type");

    if (!key || !contentType) {
      return new Response("Key and Content-Type are required");
    }

    await env.DOCS.put(key, request.body, {
      httpMetadata: request.headers,
    });

    return new Response(`Stored ${key}`);
  },
} satisfies ExportedHandler<Env>;

npx wrangler dev를 실행하고, Wrangler가 출력한 로컬 주소를 WORKER_URL에 넣은 뒤 로컬 PDF를 확장자 없는 경로로 업로드합니다.

curl "$WORKER_URL/documents/manual-alpha" \
  --request PUT \
  --header "Content-Type: application/pdf" \
  --data-binary @manual.pdf

이 예제로 확인되는 것은 스토리지 저장 단계까지입니다. 인덱싱 성공까지 입증하지는 않습니다. 프로덕션에서는 인증을 추가하고, 사용자가 보낸 파일명만 믿지 말고 신뢰할 수 있는 검사로 형식을 판별한 뒤 Cloudflare의 지원 목록과 대조해야 합니다.

업로드 성공이 검색 가능을 뜻하지 않는 이유

R2 쓰기는 강한 일관성을 보장하므로 성공한 쓰기 작업 뒤에는 객체와 메타데이터가 바로 보입니다. 하지만 AI Search 인덱싱은 별도의 비동기 작업입니다. 동기화 요청이 접수돼도 해당 항목은 나중에 실패할 수 있습니다.

R2 기반 인스턴스는 기본적으로 6시간마다 동기화됩니다. 간격은 1, 2, 4, 6, 12, 24시간 중에서 선택하거나 직접 작업을 시작할 수 있습니다.

npx wrangler ai-search jobs create <INSTANCE_NAME>

수동 소스 동기화는 30초에 한 번까지만 실행할 수 있습니다. 재시도 횟수를 늘려도 잘못된 메타데이터가 고쳐지지는 않습니다.

작업이 끝난 뒤 항목 로그, 항목 세부 정보 또는 인스턴스 통계를 확인합니다. AI Search가 감지한 파일 형식을 받아들이지 못할 때 나타나는 항목 수준 오류는 unsupported_type입니다. 객체를 수정한 다음 해당 항목이나 소스를 다시 동기화합니다.

모든 R2 키에 이미 인식 가능한 확장자가 있다면 이번 변경의 영향을 받지 않습니다. AI Search 소스가 외부 R2 버킷이 아니라 웹사이트나 기본 제공 스토리지인 경우도 마찬가지입니다. 이번 변경으로 지원되지 않는 형식이나 크기 제한을 넘은 파일까지 인덱싱할 수 있게 된 것은 아닙니다.

이번 주에 실행할 작업 순서

처음부터 일괄 재작성을 하지 말고 감사부터 시작합니다.

불투명하거나 고정된 R2 키 때문에 AI Search용 파일명 경로를 따로 관리해 왔다면 이번 주에 적용할 가치가 있습니다. 기존 객체의 형식 정보를 신뢰할 수 없다면 먼저 분류 계획을 세워야 하므로 기다리는 편이 낫습니다. 인식 가능한 확장자만으로도 수집 경로가 문제없이 작동한다면 별도 조치는 필요 없습니다.

다음 플랫폼 변화도 운영자의 의사결정 관점에서 정리해 받고 싶다면 뉴스레터에 가입하세요.