implement optimised dataset filtration for all backends

Author: bghira

documentation/DATALOADER.es.md

@@ -270,7 +270,7 @@ Los backends de memoria requieren Linux o macOS y suficiente RAM o swap para la
 ### `instance_data_dir` / `aws_data_prefix`
 
 - **Local:** Ruta a los datos en el filesystem.
-- **AWS:** Prefijo S3 de los datos en el bucket.
+- **AWS:** Prefijo S3 de los datos en el bucket. `aws_data_prefix` puede ser una cadena para un prefijo o una lista de cadenas para escanear varios prefijos del mismo bucket.
 
 ### `caption_strategy`
 
@@ -999,6 +999,32 @@ Las coordenadas del bounding box estan normalizadas a [0, 1] en formato XYXY. El
 
 Para datasets parquet o HuggingFace, especifica un `bbox_column` en la configuracion del backend.
 
+## Filtrado de muestras
+
+### `filter_func`
+
+`filter_func` puede configurarse en el nivel superior de cualquier backend de dataset para omitir muestras antes de construir buckets de metadatos y cachés VAE. Los backends de Hugging Face siguen aceptando la ubicación antigua `huggingface.filter_func`, pero el valor superior tiene prioridad si ambos existen.
+
+Filtros admitidos:
+
+- `collection`: lista permitida de coincidencia exacta para el campo `collection` de una fila.
+- `quality_thresholds`: valores numéricos mínimos dentro de `quality_column` (por defecto, `quality_assessment`).
+- `min_width` / `min_height`: dimensiones mínimas de fila cuando existen campos de ancho y alto.
+- `path_include` / `path_exclude`: filtrado por nombre de archivo/ruta para datasets local, AWS, CSV, Hugging Face, parquet y Webshart. `path_include` es lista permitida y `path_exclude` lista bloqueada. Las exclusiones ganan si ambas coinciden.
+- `path_match`: modo de coincidencia de rutas. `auto` (predeterminado para claves planas) usa subcadenas para texto normal, glob para `*` y `?`, y regex para patrones con prefijo `re:`. También se puede usar `contains`, `glob`, `regex` o `exact`.
+
+```json
+{
+  "filter_func": {
+    "path_include": ["clothing", "notable", "*/curated/*.jpg"],
+    "path_exclude": ["watermark", "bad"],
+    "path_match": "auto"
+  }
+}
+```
+
+La forma antigua anidada `filter_func.path.include` / `exclude` / `mode` sigue aceptándose para configs existentes, pero las nuevas configs deben usar las claves planas anteriores.
+
 ## Filtrado de captions
 
 ### `caption_filter_list`
@@ -1368,8 +1394,6 @@ webshart optimize-captions \
 
 `--destination` escribe un árbol de metadata portátil por shard, y `--push-to-hub` lo sube a un repositorio de metadata; después apunta la opción `metadata` del dataloader a ese repositorio. `--shard-cache-dir` permite que la consolidación reutilice shards completamente cacheados en lugar de emitir una lectura por rango por cada sidecar.
 
-Este backend requiere un build de Webshart con `TarDataLoader.list_shard_sample_aspect_buckets()`; `webshart_optimize_captions` requiere además `probe_caption_layout()` y `coalesce_caption_metadata()`.
-
 ## Mapeo personalizado de relación de aspecto a resolución
 
 Cuando SimpleTuner inicia por primera vez, genera listas de mapeo de aspecto específicas de resolución que vinculan un valor decimal de relación de aspecto con su tamaño de píxel objetivo.

documentation/DATALOADER.hi.md

@@ -270,7 +270,7 @@ Memory backends के लिए Linux या macOS और मौजूदा ca
 ### `instance_data_dir` / `aws_data_prefix`
 
 - **Local:** filesystem पर डेटा का path.
-- **AWS:** bucket में डेटा का S3 prefix.
+- **AWS:** bucket में डेटा का S3 prefix. `aws_data_prefix` एक prefix के लिए string हो सकता है, या उसी bucket में कई prefixes scan करने के लिए strings की list हो सकता है.
 
 ### `caption_strategy`
 
@@ -999,6 +999,32 @@ Bounding box coordinates XYXY format में [0, 1] पर normalised हो
 
 Parquet या HuggingFace datasets के लिए, backend config में `bbox_column` specify करें।
 
+## Samples फ़िल्टर करना
+
+### `filter_func`
+
+`filter_func` किसी भी dataset backend के top level पर सेट किया जा सकता है ताकि metadata buckets और VAE caches बनने से पहले samples skip किए जा सकें। Hugging Face backends compatibility के लिए पुराने `huggingface.filter_func` स्थान को अभी भी स्वीकार करते हैं, लेकिन दोनों मौजूद होने पर top-level value प्राथमिकता लेती है।
+
+Supported filters:
+
+- `collection`: row के `collection` field के लिए exact-match whitelist।
+- `quality_thresholds`: `quality_column` (default: `quality_assessment`) में minimum numeric values।
+- `min_width` / `min_height`: width और height fields उपलब्ध होने पर minimum row dimensions।
+- `path_include` / `path_exclude`: local, AWS, CSV, Hugging Face, parquet, और Webshart datasets के लिए filename/path filtering। `path_include` whitelist है और `path_exclude` blacklist है। दोनों match होने पर exclude जीतेगा।
+- `path_match`: path matching mode. Flat keys के लिए default `auto` है: plain text के लिए substring match, `*` और `?` के लिए glob, और `re:` prefix वाले patterns के लिए regex। `contains`, `glob`, `regex`, या `exact` भी इस्तेमाल कर सकते हैं।
+
+```json
+{
+  "filter_func": {
+    "path_include": ["clothing", "notable", "*/curated/*.jpg"],
+    "path_exclude": ["watermark", "bad"],
+    "path_match": "auto"
+  }
+}
+```
+
+पुराना nested form `filter_func.path.include` / `exclude` / `mode` existing configs के लिए अब भी accepted है, लेकिन नए configs में ऊपर वाली flat keys इस्तेमाल करें।
+
 ## Captions फ़िल्टर करना
 
 ### `caption_filter_list`
@@ -1368,8 +1394,6 @@ webshart optimize-captions \
 
 `--destination` एक portable per-shard metadata tree लिखता है, और `--push-to-hub` उसे metadata repository पर upload करता है; बाद में dataloader के `metadata` option को उसी repository पर point करें। `--shard-cache-dir` से coalescing हर sidecar के लिए एक range read करने की बजाय पूरी तरह cached shards reuse कर पाती है।
 
-इस backend के लिए `TarDataLoader.list_shard_sample_aspect_buckets()` वाला Webshart build चाहिए; `webshart_optimize_captions` के लिए अतिरिक्त रूप से `probe_caption_layout()` और `coalesce_caption_metadata()` भी चाहिए।
-
 ## Custom aspect ratio‑to‑resolution mapping
 
 जब SimpleTuner पहली बार चलता है, तो यह resolution‑specific aspect mapping lists बनाता है जो decimal aspect‑ratio मान को target pixel size से जोड़ते हैं।

documentation/DATALOADER.ja.md

@@ -270,7 +270,7 @@ Hugging Face の音声データセットでは、キャプション（プロン
 ### `instance_data_dir` / `aws_data_prefix`
 
 - **Local:** ファイルシステム上のデータパス。
-- **AWS:** バケット内のデータに対する S3 プレフィックス。
+- **AWS:** バケット内のデータに対する S3 プレフィックス。`aws_data_prefix` は単一プレフィックスの文字列、または同じ bucket 内の複数プレフィックスを走査する文字列リストにできます。
 
 ### `caption_strategy`
 
@@ -999,6 +999,32 @@ Grounding パイプラインは、エンティティごとのバウンディン
 
 parquet または HuggingFace データセットの場合、バックエンド設定で `bbox_column` を指定します。
 
+## サンプルのフィルタリング
+
+### `filter_func`
+
+`filter_func` は任意のデータセットバックエンドのトップレベルに設定でき、メタデータバケットと VAE キャッシュを作成する前にサンプルを除外します。Hugging Face バックエンドでは従来の `huggingface.filter_func` も互換性のため引き続き使用できますが、両方がある場合はトップレベルの値が優先されます。
+
+対応フィルタ:
+
+- `collection`: 行の `collection` フィールドに対する完全一致の許可リスト。
+- `quality_thresholds`: `quality_column`（既定は `quality_assessment`）内の数値の最小値。
+- `min_width` / `min_height`: 幅と高さのフィールドがある場合の最小寸法。
+- `path_include` / `path_exclude`: local、AWS、CSV、Hugging Face、parquet、Webshart データセットのファイル名/パスフィルタ。`path_include` は許可リスト、`path_exclude` はブロックリストです。両方に一致する場合は除外が優先されます。
+- `path_match`: パス一致モード。`auto`（フラットキーの既定）は通常文字列に substring match、`*` と `?` に glob、`re:` prefix の pattern に regex を使います。`contains`、`glob`、`regex`、`exact` も指定できます。
+
+```json
+{
+  "filter_func": {
+    "path_include": ["clothing", "notable", "*/curated/*.jpg"],
+    "path_exclude": ["watermark", "bad"],
+    "path_match": "auto"
+  }
+}
+```
+
+従来のネスト形式 `filter_func.path.include` / `exclude` / `mode` は既存 config の互換性のため引き続き使用できますが、新しい config では上記のフラットキーを使ってください。
+
 ## キャプションのフィルタリング
 
 ### `caption_filter_list`
@@ -1369,8 +1395,6 @@ webshart optimize-captions \
 
 `--destination` はポータブルな shard ごとの metadata ツリーを書き出し、`--push-to-hub` はそれを metadata repository にアップロードします。その後、dataloader の `metadata` オプションをその repository に向けてください。`--shard-cache-dir` を指定すると、統合処理は sidecar ごとに 1 回の range read を発行する代わりに、完全に cache された shard を再利用できます。
 
-この backend には `TarDataLoader.list_shard_sample_aspect_buckets()` を提供する Webshart build が必要です。`webshart_optimize_captions` にはさらに `probe_caption_layout()` と `coalesce_caption_metadata()` が必要です。
-
 ## アスペクト比と解像度のカスタムマッピング
 
 SimpleTuner の初回起動時、10 進のアスペクト比を目標ピクセルサイズに対応付ける解像度別のマッピング一覧が生成されます。

documentation/DATALOADER.md

@@ -272,7 +272,7 @@ Memory backends require Linux or macOS and enough RAM or swap for the existing c
 ### `instance_data_dir` / `aws_data_prefix`
 
 - **Local:** Path to the data on the filesystem.
-- **AWS:** S3 prefix for the data in the bucket.
+- **AWS:** S3 prefix for the data in the bucket. Set `aws_data_prefix` to a string for one prefix, or to a list of strings to scan multiple prefixes in the same bucket.
 
 ### `caption_strategy`
 
@@ -1045,6 +1045,41 @@ The column value is parsed using the same formats as `.bbox` files (JSON array o
 
 ---
 
+## Filtering samples
+
+### `filter_func`
+
+`filter_func` may be set at the top level of any dataset backend to skip samples before metadata buckets and VAE caches are built. Hugging Face backends still accept the older nested `huggingface.filter_func` location, but the top-level value takes precedence when both are present.
+
+Supported filters:
+
+- `collection`: exact-match whitelist for a row's `collection` field. This is available when the backend has row metadata, such as Hugging Face datasets.
+- `quality_thresholds`: minimum numeric values inside `quality_column` (default: `quality_assessment`). This is available when the backend has row metadata.
+- `min_width` / `min_height`: minimum row dimensions when width and height fields are available.
+- `path_include` / `path_exclude`: filename/path filtering for local, AWS, CSV, Hugging Face, parquet, and Webshart datasets. Includes are a whitelist and excludes are a blacklist. Excludes win if both match.
+- `path_match`: path match mode. `auto` (default for flat keys) uses fast substring matching for plain text, glob matching for `*` and `?`, and regex matching for patterns prefixed with `re:`. You can also set `contains`, `glob`, `regex`, or `exact`.
+
+Example:
+
+```json
+{
+  "id": "regularisation-512",
+  "type": "local",
+  "instance_data_dir": "/data/reg",
+  "caption_strategy": "textfile",
+  "metadata_backend": "discovery",
+  "filter_func": {
+    "path_include": ["clothing", "notable", "*/curated/*.jpg"],
+    "path_exclude": ["watermark", "bad"],
+    "path_match": "auto"
+  }
+}
+```
+
+The older nested `filter_func.path.include` / `exclude` / `mode` form is still accepted for existing configs, but new configs should use the flat keys above.
+
+---
+
 ## Filtering captions
 
 ### `caption_filter_list`
@@ -1415,8 +1450,6 @@ webshart optimize-captions \
 
 `--destination` writes a portable per-shard metadata tree, and `--push-to-hub` uploads it to a metadata repository; point the dataloader `metadata` option at that repository afterwards. `--shard-cache-dir` lets coalescing reuse fully cached shards instead of issuing one range read per sidecar.
 
-This backend requires a Webshart build with `TarDataLoader.list_shard_sample_aspect_buckets()`; `webshart_optimize_captions` additionally requires `probe_caption_layout()` and `coalesce_caption_metadata()`.
-
 ## Custom aspect ratio-to-resolution mapping
 
 When SimpleTuner first launches, it generates resolution-specific aspect mapping lists that link a decimal aspect-ratio value to its target pixel size.

documentation/DATALOADER.pt-BR.md

@@ -270,7 +270,7 @@ Backends de memória exigem Linux ou macOS e RAM ou swap suficiente para o cache
 ### `instance_data_dir` / `aws_data_prefix`
 
 - **Local:** Caminho para os dados no sistema de arquivos.
-- **AWS:** Prefixo S3 para os dados no bucket.
+- **AWS:** Prefixo S3 para os dados no bucket. `aws_data_prefix` pode ser uma string para um prefixo ou uma lista de strings para varrer vários prefixos no mesmo bucket.
 
 ### `caption_strategy`
 
@@ -999,6 +999,32 @@ As coordenadas do bounding box sao normalizadas para [0, 1] no formato XYXY. O f
 
 Para datasets parquet ou HuggingFace, especifique um `bbox_column` na configuracao do backend.
 
+## Filtragem de amostras
+
+### `filter_func`
+
+`filter_func` pode ser configurado no nível superior de qualquer backend de dataset para pular amostras antes da criação dos buckets de metadados e caches VAE. Backends Hugging Face ainda aceitam o local antigo `huggingface.filter_func`, mas o valor de nível superior tem prioridade quando ambos existem.
+
+Filtros suportados:
+
+- `collection`: lista permitida com correspondência exata para o campo `collection` de uma linha.
+- `quality_thresholds`: valores numéricos mínimos dentro de `quality_column` (padrão: `quality_assessment`).
+- `min_width` / `min_height`: dimensões mínimas da linha quando campos de largura e altura existem.
+- `path_include` / `path_exclude`: filtragem por nome de arquivo/caminho para datasets local, AWS, CSV, Hugging Face, parquet e Webshart. `path_include` é uma lista permitida e `path_exclude` uma lista bloqueada. Exclusões vencem se ambas coincidirem.
+- `path_match`: modo de correspondência de caminhos. `auto` (padrão para chaves planas) usa substring para texto simples, glob para `*` e `?`, e regex para padrões com prefixo `re:`. Também é possível usar `contains`, `glob`, `regex` ou `exact`.
+
+```json
+{
+  "filter_func": {
+    "path_include": ["clothing", "notable", "*/curated/*.jpg"],
+    "path_exclude": ["watermark", "bad"],
+    "path_match": "auto"
+  }
+}
+```
+
+A forma antiga aninhada `filter_func.path.include` / `exclude` / `mode` continua aceita para configs existentes, mas novas configs devem usar as chaves planas acima.
+
 ## Filtragem de captions
 
 ### `caption_filter_list`
@@ -1368,8 +1394,6 @@ webshart optimize-captions \
 
 `--destination` grava uma árvore de metadados portátil por shard, e `--push-to-hub` a envia para um repositório de metadata; depois aponte a opção `metadata` do dataloader para esse repositório. `--shard-cache-dir` permite que a consolidação reutilize shards totalmente em cache em vez de emitir uma leitura por intervalo para cada sidecar.
 
-Esse backend exige um build do Webshart com `TarDataLoader.list_shard_sample_aspect_buckets()`; `webshart_optimize_captions` exige adicionalmente `probe_caption_layout()` e `coalesce_caption_metadata()`.
-
 ## Mapeamento personalizado de proporção para resolução
 
 Quando o SimpleTuner inicia pela primeira vez, ele gera listas de mapeamento de aspecto específicas de resolução que vinculam um valor decimal de proporção a seu tamanho de pixel alvo.

documentation/DATALOADER.zh.md

@@ -269,7 +269,7 @@ LTX-2 使用原生纯音频分支；MiniMax-H3 在打包序列中为每个 laten
 ### `instance_data_dir` / `aws_data_prefix`
 
 - **Local:** 文件系统中的数据路径。
-- **AWS:** 存储桶中的 S3 前缀。
+- **AWS:** 存储桶中的 S3 前缀。`aws_data_prefix` 可以是单个前缀字符串，也可以是字符串列表，用于扫描同一 bucket 中的多个前缀。
 
 ### `caption_strategy`
 
@@ -998,6 +998,32 @@ Grounding 流水线支持为每个实体添加边界框和遮罩标注，用于
 
 对于 parquet 或 HuggingFace 数据集，在后端配置中指定 `bbox_column`。
 
+## 过滤样本
+
+### `filter_func`
+
+`filter_func` 可配置在任意数据集后端的顶层，用于在构建元数据 buckets 和 VAE 缓存之前跳过样本。Hugging Face 后端仍兼容旧的 `huggingface.filter_func` 位置，但当两者同时存在时顶层值优先。
+
+支持的过滤器：
+
+- `collection`：对行的 `collection` 字段进行精确匹配白名单过滤。
+- `quality_thresholds`：`quality_column`（默认 `quality_assessment`）内数值的最低要求。
+- `min_width` / `min_height`：当存在宽高字段时要求的最小尺寸。
+- `path_include` / `path_exclude`：按文件名/路径过滤 local、AWS、CSV、Hugging Face、parquet 和 Webshart 数据集。`path_include` 是白名单，`path_exclude` 是黑名单；两者都匹配时排除优先。
+- `path_match`：路径匹配模式。`auto`（扁平键的默认值）对普通文本使用子串匹配，对 `*` 和 `?` 使用 glob，对带 `re:` 前缀的模式使用 regex。也可以设置为 `contains`、`glob`、`regex` 或 `exact`。
+
+```json
+{
+  "filter_func": {
+    "path_include": ["clothing", "notable", "*/curated/*.jpg"],
+    "path_exclude": ["watermark", "bad"],
+    "path_match": "auto"
+  }
+}
+```
+
+旧的嵌套形式 `filter_func.path.include` / `exclude` / `mode` 仍兼容已有配置，但新配置应使用上面的扁平键。
+
 ## 过滤字幕
 
 ### `caption_filter_list`
@@ -1368,8 +1394,6 @@ webshart optimize-captions \
 
 `--destination` 写出一棵可移植的按 shard 组织的 metadata 树，`--push-to-hub` 将其上传到 metadata 仓库；之后把 dataloader 的 `metadata` 选项指向该仓库即可。`--shard-cache-dir` 让合并过程复用已完整 cache 的 shards，而不是为每个 sidecar 发起一次 range read。
 
-该 backend 需要提供 `TarDataLoader.list_shard_sample_aspect_buckets()` 的 Webshart build；`webshart_optimize_captions` 还额外需要 `probe_caption_layout()` 和 `coalesce_caption_metadata()`。
-
 ## 自定义纵横比到分辨率映射
 
 SimpleTuner 首次启动时，会生成分辨率专用的纵横比映射列表，将十进制纵横比值映射到目标像素尺寸。