Cloudflare R2: come indicizzare file senza estensione

Cosa cambia per Cloudflare R2

Cloudflare AI Search è un servizio di ricerca gestito per i propri contenuti. Tra le fonti supportate c'è un bucket R2, lo storage a oggetti di Cloudflare. AI Search legge il bucket, converte i documenti compatibili in testo ricercabile e crea l'indice interrogato dall'applicazione.

Prima di questo aggiornamento, il percorso di rilevamento più sicuro dipendeva dall'estensione del nome file. Una chiave come manual.pdf comunica all'indicizzatore il tipo di contenuto; una chiave stabile come documents/manual-alpha, invece, non lo fa.

Ora AI Search può usare il normale Content-Type HTTP dell'oggetto senza estensione. application/pdf identifica i byte come PDF, mentre text/markdown indica un documento Markdown. Cloudflare include anche text/plain, application/json, text/html e text/csv tra i tipi supportati.

Le estensioni non scompaiono: Cloudflare continua a indicare un'estensione riconosciuta come percorso di rilevamento preferito e più rapido. La nuova opzione serve quando modificare la chiave romperebbe URL, riferimenti nel database, associazioni dei tenant, firme o un contratto di upload già operativo.

È importante non confondere due concetti. Content-Type è un metadato HTTP dell'oggetto R2. Non coincide con i metadati personalizzati usati da AI Search per filtri come categoria, cliente o stato del documento. Questi campi personalizzati viaggiano nelle intestazioni x-amz-meta-* e richiedono uno schema in AI Search. Aggiungere x-amz-meta-content-type non sostituisce il vero campo HTTP.

Questo aggiornamento riguarda l'ingestion della fonte, cioè il punto in cui un documento entra nell'indice. Non modifica il modello che genera la risposta dopo il recupero dei contenuti. L'aggiornamento a GLM-5.3 Flash interviene in quella fase successiva di generazione.

Il vero vantaggio: un sistema di nomi in meno

Le chiavi opache sono diffuse per ottime ragioni. Un prodotto può usare come chiave R2 un ID stabile del database, così l'oggetto può cambiare senza cambiare indirizzo. Un servizio documentale può evitare di esporre il nome file originale di un cliente. Un URL firmato può dipendere dalla chiave esatta.

La soluzione precedente consisteva nel creare per la copia destinata alla ricerca un nome provvisto di estensione, oppure nell'aggiungere una fase di rinomina prima che AI Search vedesse l'oggetto. Il risultato era un'identità aggiuntiva da memorizzare, riconciliare e ripulire.

Con l'aggiornamento, la chiave originale può rimanere invariata quando i suoi metadati HTTP sono già corretti. È questa la concreta semplificazione del workflow.

La tabella confronta il lavoro di ingestion prima e dopo il rilascio. Si tratta di un modello di processo, non di un benchmark misurato né di un risparmio garantito.

La tabella evita volutamente di attribuire un valore economico al cambiamento. Cloudflare non ha pubblicato stime sul tempo risparmiato da questa funzione e il rilascio non corregge automaticamente i metadati esistenti.

Quanto costa il lavoro che rimane

AI Search è gratuito durante la beta aperta entro i limiti del piano Workers. Lo storage e l'indicizzazione vettoriale sono inclusi. L'uso di Workers AI e AI Gateway può comunque essere fatturato separatamente, ma questa modifica all'ingestion non ne cambia le tariffe.

La correzione dei metadati può incidere sulla fattura R2. ListObjects, PutObject e CopyObject sono operazioni di Classe A. HeadObject e GetObject, che uno strumento di correzione può usare per ispezionare o leggere un oggetto, sono operazioni di Classe B.

Con lo storage Standard, le richieste di Classe A costano $4.50 per milione dopo la quota gratuita mensile di 1 milione. Infrequent Access non prevede una fascia gratuita e applica $9.00 per milione alle richieste di Classe A. Può inoltre addebitare $0.01 per GB quando gli oggetti vengono letti o copiati.

La regola di budget è semplice. Un oggetto con Content-Type corretto non richiede interventi specifici di rinomina. Un oggetto con un valore errato può invece richiedere una scrittura o una copia, a seconda dello strumento utilizzato. Prima di pianificare una bonifica dell'intero bucket, occorre conteggiare queste operazioni.

Anche sul versante AI Search la scala conta. Il limite per istanza è di 100,000 file con Workers Free. Workers Paid consente 1 milione di file, oppure 500,000 quando è attiva la ricerca ibrida. Il limite di 4 MB per file rimane identico in entrambi i piani.

Chi può sfruttare la novità già da domani

Un founder SaaS indipendente con ID di upload stabili

Si può mantenere la chiave R2 già registrata nel database e fare in modo che l'uploader associ il tipo MIME corretto quando scrive l'oggetto. Il motore di ricerca dell'assistenza può così acquisire lo stesso oggetto, senza una seconda colonna per il nome file né un job batch che generi copie destinate alla ricerca.

Il vantaggio è ridurre le identità da riconciliare quando un cliente sostituisce, elimina o sposta un documento. L'upload deve comunque rifiutare un tipo binario generico se l'oggetto dovrà diventare ricercabile.

Un platform engineer alle prese con un bucket legacy

Prima si elencano gli oggetti senza estensione insieme ai rispettivi metadati HTTP, poi si confrontano i valori con i tipi MIME supportati da Cloudflare e si isolano gli errori. Conviene correggere un piccolo campione prima di intervenire sull'intero bucket.

Il vantaggio è una migrazione circoscritta. Il budget per la correzione viene speso soltanto sugli oggetti che ne hanno bisogno; quelli con metadati validi passano direttamente alla sincronizzazione e alla verifica.

Un team di prodotto multi-tenant

Le chiavi opache che non espongono i nomi file originali possono rimanere in uso, mentre il Content-Type viene impostato durante l'upload tramite un controllo affidabile lato server. I filtri per percorso o i prefissi di AI Search vanno applicati separatamente quando ogni tenant richiede un proprio confine di indicizzazione.

Il vantaggio è la coerenza architetturale. L'identità nello storage resta separata dalla presentazione del file, mentre l'indicizzatore riceve comunque un tipo che può validare.

Un'agenzia che gestisce basi di conoscenza per i clienti

Nel runbook vanno distinti i due compiti dei metadati. Il Content-Type HTTP determina se un file senza estensione può essere acquisito. I campi personalizzati x-amz-meta-* stabiliscono invece come filtrare i risultati indicizzati dopo averne definito lo schema.

Il vantaggio è un debugging più lineare. Quando manca un documento, il team controlla i metadati di ingestion prima di modificare le regole dei filtri o il modello di risposta.

Come indicizzare file R2 senza estensione

La R2 Workers API di Cloudflare accetta le intestazioni della richiesta tramite httpMetadata. Il Worker seguente mantiene il percorso della richiesta come chiave dell'oggetto e rifiuta gli upload privi di Content-Type.

Associare un bucket R2 come DOCS in wrangler.jsonc:

{
  "$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"
    }
  ]
}

Usare quindi questo 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>;

Eseguire npx wrangler dev, assegnare a WORKER_URL l'indirizzo locale mostrato da Wrangler e caricare un PDF locale in una destinazione senza estensione:

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

Questo esempio dimostra la parte relativa allo storage, non l'avvenuta indicizzazione. In produzione bisogna aggiungere l'autorizzazione, ricavare il tipo tramite un'ispezione affidabile anziché dal solo nome file fornito dall'utente e confrontarlo con l'elenco dei formati supportati da Cloudflare.

Il punto decisivo: un upload riuscito non rende il file ricercabile

Le scritture R2 hanno consistenza forte, quindi dopo una scrittura riuscita l'oggetto e i suoi metadati risultano visibili. L'indicizzazione di AI Search è però un job asincrono separato: una richiesta di sincronizzazione può essere accettata e l'indicizzazione dell'elemento può comunque non riuscire in seguito.

Le istanze basate su R2 si sincronizzano ogni 6 ore per impostazione predefinita. Si può scegliere un intervallo di 1, 2, 4, 6, 12 o 24 ore, oppure avviare manualmente un job:

npx wrangler ai-search jobs create <INSTANCE_NAME>

Le sincronizzazioni manuali della fonte possono essere eseguite al massimo una volta ogni 30 secondi. Aumentare i tentativi non corregge metadati errati.

Dopo il job, occorre controllare i log degli elementi, i relativi dettagli o le statistiche dell'istanza. unsupported_type è l'errore a livello di elemento da cercare quando AI Search non accetta il tipo di file rilevato. Dopo aver corretto l'oggetto, si sincronizza nuovamente quell'elemento o l'intera fonte.

La modifica non ha effetti se tutte le chiavi R2 hanno già un'estensione riconosciuta. Lo stesso vale quando la fonte di AI Search è un sito web o lo storage integrato, anziché un bucket R2 esterno. L'aggiornamento non rende indicizzabili formati non supportati o file troppo grandi.

Piano operativo per lunedì

Si parte da un audit, non da una riscrittura in massa.

È il momento di intervenire se chiavi R2 stabili o opache hanno imposto un secondo percorso di denominazione per AI Search. È meglio aspettare se gli oggetti esistenti non hanno informazioni affidabili sul tipo, perché serve un piano di classificazione prima di riscriverli. Non occorre fare nulla se le estensioni riconosciute rendono già lineare il percorso di ingestion.

Per ricevere anche il prossimo aggiornamento di piattaforma trasformato in una decisione operativa, iscriviti alla newsletter.