dtflow 0.5.6__py3-none-any.whl → 0.5.8__py3-none-any.whl

dtflow/cli/stats.py

@@ -3,7 +3,7 @@ CLI 数据统计相关命令
 """
 
 from pathlib import Path
-from typing import Any, Dict, List
+from typing import Any, Dict, List, Optional
 
 import orjson
 
@@ -22,6 +22,8 @@ def stats(
     filename: str,
     top: int = 10,
     full: bool = False,
+    fields: Optional[List[str]] = None,
+    expand_fields: Optional[List[str]] = None,
 ) -> None:
     """
     显示数据文件的统计信息。
@@ -33,11 +35,15 @@ def stats(
         filename: 输入文件路径，支持 csv/excel/jsonl/json/parquet/arrow/feather 格式
         top: 显示频率最高的前 N 个值，默认 10（仅完整模式）
         full: 完整模式，统计值分布、唯一值等详细信息
+        fields: 指定统计的字段列表（支持嵌套路径）
+        expand_fields: 展开 list 字段统计的字段列表
 
     Examples:
         dt stats data.jsonl            # 快速模式（默认）
         dt stats data.jsonl --full     # 完整模式
         dt stats data.csv -f --top=5   # 完整模式，显示 Top 5
+        dt stats data.jsonl --full --field=category  # 指定字段
+        dt stats data.jsonl --full --expand=tags     # 展开 list 字段
     """
     filepath = Path(filename)
 
@@ -48,7 +54,10 @@ def stats(
     if not _check_file_format(filepath):
         return
 
+    # 快速模式：忽略 --field 和 --expand 参数
     if not full:
+        if fields or expand_fields:
+            print("⚠️  警告: --field 和 --expand 参数仅在完整模式 (--full) 下生效")
         _quick_stats(filepath)
         return
 
@@ -65,7 +74,7 @@ def stats(
 
     # 计算统计信息
     total = len(data)
-    field_stats = _compute_field_stats(data, top)
+    field_stats = _compute_field_stats(data, top, fields, expand_fields)
 
     # 输出统计信息
     _print_stats(filepath.name, total, field_stats)
@@ -200,16 +209,104 @@ def _quick_stats(filepath: Path) -> None:
         print(f"字段: {len(fields)} 个")
 
         if fields:
-            print(f"\n📋 字段结构:")
+            print("\n📋 字段结构:")
             for i, f in enumerate(fields, 1):
                 print(f"  {i}. {f['field']} ({f['type']})")
 
 
-def _compute_field_stats(data: List[Dict], top: int) -> List[Dict[str, Any]]:
+def _extract_with_wildcard(item: dict, field_spec: str) -> List[Any]:
+    """处理包含 [*] 的字段路径，返回所有值"""
+    if "[*]" not in field_spec:
+        # 无 [*]，直接返回单个值的列表
+        value = get_field_with_spec(item, field_spec)
+        return [value] if value is not None else []
+
+    # 分割路径：messages[*].role -> ("messages", ".role")
+    before, after = field_spec.split("[*]", 1)
+    after = after.lstrip(".")  # 移除开头的点
+
+    # 获取数组
+    array = get_field_with_spec(item, before) if before else item
+    if not isinstance(array, list):
+        return []
+
+    # 提取每个元素的后续路径
+    results = []
+    for elem in array:
+        if after:
+            val = get_field_with_spec(elem, after)
+        else:
+            val = elem
+        if val is not None:
+            results.append(val)
+
+    return results
+
+
+def _extract_field_values(
+    data: List[Dict],
+    field_spec: str,
+    expand: bool = False,
+) -> List[Any]:
+    """
+    从数据中提取字段值。
+
+    Args:
+        data: 数据列表
+        field_spec: 字段路径规格（如 "messages[*].role"）
+        expand: 是否展开 list
+
+    Returns:
+        值列表（展开或不展开）
+    """
+    all_values = []
+
+    for item in data:
+        if "[*]" in field_spec or expand:
+            # 使用通配符提取所有值
+            values = _extract_with_wildcard(item, field_spec)
+
+            if expand and len(values) == 1 and isinstance(values[0], list):
+                # 展开模式：如果返回单个列表，展开其元素
+                all_values.extend(values[0])
+            elif expand and values and isinstance(values[0], list):
+                # 多个列表，全部展开
+                for v in values:
+                    if isinstance(v, list):
+                        all_values.extend(v)
+                    else:
+                        all_values.append(v)
+            else:
+                # 不展开或非列表值
+                all_values.extend(values)
+        else:
+            # 普通字段路径
+            value = get_field_with_spec(item, field_spec)
+            if expand and isinstance(value, list):
+                # 展开 list
+                all_values.extend(value)
+            else:
+                all_values.append(value)
+
+    return all_values
+
+
+def _compute_field_stats(
+    data: List[Dict],
+    top: int,
+    fields: Optional[List[str]] = None,
+    expand_fields: Optional[List[str]] = None,
+) -> List[Dict[str, Any]]:
     """
     单次遍历计算每个字段的统计信息。
 
     优化：将多次遍历合并为单次遍历，在遍历过程中同时收集所有统计数据。
+
+    Args:
+        data: 数据列表
+        top: Top N 值数量
+        fields: 指定统计的字段列表
+        expand_fields: 展开 list 字段统计的字段列表
     """
     from collections import Counter, defaultdict
 
@@ -218,38 +315,115 @@ def _compute_field_stats(data: List[Dict], top: int) -> List[Dict[str, Any]]:
 
     total = len(data)
 
-    # 单次遍历收集所有字段的值和统计信息
-    field_values = defaultdict(list)  # 存储每个字段的所有值
-    field_counters = defaultdict(Counter)  # 存储每个字段的值频率（用于 top N）
+    # 如果没有指定字段，统计所有顶层字段（保持向后兼容）
+    if not fields and not expand_fields:
+        # 单次遍历收集所有字段的值和统计信息
+        field_values = defaultdict(list)  # 存储每个字段的所有值
+        field_counters = defaultdict(Counter)  # 存储每个字段的值频率（用于 top N）
+
+        for item in data:
+            for k, v in item.items():
+                field_values[k].append(v)
+                # 对值进行截断后计数（用于 top N 显示）
+                displayable = _truncate(v if v is not None else "", 30)
+                field_counters[k][displayable] += 1
+
+        # 根据收集的数据计算统计信息
+        stats_list = []
+        for field in sorted(field_values.keys()):
+            values = field_values[field]
+            non_null = [v for v in values if v is not None and v != ""]
+            non_null_count = len(non_null)
+
+            # 推断类型（从第一个非空值）
+            field_type = _infer_type(non_null)
+
+            # 基础统计
+            stat = {
+                "field": field,
+                "non_null": non_null_count,
+                "null_rate": f"{non_null_count / total * 100:.1f}%",
+                "type": field_type,
+            }
+
+            # 类型特定统计
+            if non_null:
+                # 唯一值计数（对复杂类型使用 hash 节省内存）
+                stat["unique"] = _count_unique(non_null, field_type)
+
+                # 字符串类型：计算长度统计
+                if field_type == "str":
+                    lengths = [len(str(v)) for v in non_null]
+                    stat["len_min"] = min(lengths)
+                    stat["len_max"] = max(lengths)
+                    stat["len_avg"] = sum(lengths) / len(lengths)
+
+                # 数值类型：计算数值统计
+                elif field_type in ("int", "float"):
+                    nums = [float(v) for v in non_null if _is_numeric(v)]
+                    if nums:
+                        stat["min"] = min(nums)
+                        stat["max"] = max(nums)
+                        stat["avg"] = sum(nums) / len(nums)
+
+                # 列表类型：计算长度统计
+                elif field_type == "list":
+                    lengths = [len(v) if isinstance(v, list) else 0 for v in non_null]
+                    stat["len_min"] = min(lengths)
+                    stat["len_max"] = max(lengths)
+                    stat["len_avg"] = sum(lengths) / len(lengths)
+
+                # Top N 值（已在遍历时收集）
+                stat["top_values"] = field_counters[field].most_common(top)
+
+            stats_list.append(stat)
+
+        return stats_list
+
+    # 指定了字段：收集指定字段的统计
+    stats_list = []
+    expand_set = set(expand_fields) if expand_fields else set()
 
-    for item in data:
-        for k, v in item.items():
-            field_values[k].append(v)
-            # 对值进行截断后计数（用于 top N 显示）
-            displayable = _truncate(v if v is not None else "", 30)
-            field_counters[k][displayable] += 1
+    # 合并字段列表
+    all_fields = set(fields) if fields else set()
+    all_fields.update(expand_set)
 
-    # 根据收集的数据计算统计信息
-    stats_list = []
-    for field in sorted(field_values.keys()):
-        values = field_values[field]
+    for field_spec in sorted(all_fields):
+        is_expanded = field_spec in expand_set
+
+        # 提取字段值
+        values = _extract_field_values(data, field_spec, expand=is_expanded)
+
+        # 过滤 None 和空值
         non_null = [v for v in values if v is not None and v != ""]
         non_null_count = len(non_null)
 
-        # 推断类型（从第一个非空值）
+        # 推断类型
         field_type = _infer_type(non_null)
 
         # 基础统计
-        stat = {
-            "field": field,
-            "non_null": non_null_count,
-            "null_rate": f"{(total - non_null_count) / total * 100:.1f}%",
-            "type": field_type,
-        }
+        if is_expanded:
+            # 展开模式：显示元素总数和平均数，而非非空率
+            stat = {
+                "field": field_spec,
+                "non_null": non_null_count,
+                "null_rate": f"总元素: {len(values)}",
+                "type": field_type,
+                "is_expanded": is_expanded,
+            }
+        else:
+            # 普通模式：显示非空率
+            stat = {
+                "field": field_spec,
+                "non_null": non_null_count,
+                "null_rate": f"{non_null_count / total * 100:.1f}%",
+                "type": field_type,
+                "is_expanded": is_expanded,
+            }
 
         # 类型特定统计
         if non_null:
-            # 唯一值计数（对复杂类型使用 hash 节省内存）
+            # 唯一值计数
             stat["unique"] = _count_unique(non_null, field_type)
 
             # 字符串类型：计算长度统计
@@ -274,8 +448,12 @@ def _compute_field_stats(data: List[Dict], top: int) -> List[Dict[str, Any]]:
                 stat["len_max"] = max(lengths)
                 stat["len_avg"] = sum(lengths) / len(lengths)
 
-            # Top N 值（已在遍历时收集）
-            stat["top_values"] = field_counters[field].most_common(top)
+            # Top N 值（需要重新计数）
+            counter = Counter()
+            for v in non_null:
+                displayable = _truncate(v if v is not None else "", 30)
+                counter[displayable] += 1
+            stat["top_values"] = counter.most_common(top)
 
         stats_list.append(stat)
 
@@ -343,9 +521,18 @@ def _print_stats(filename: str, total: int, field_stats: List[Dict[str, Any]]) -
         table.add_column("统计", style="dim")
 
         for stat in field_stats:
-            non_null_rate = f"{stat['non_null'] / total * 100:.0f}%"
+            # 使用 stat 中的 null_rate（支持展开模式的特殊显示）
+            if "null_rate" in stat:
+                non_null_rate = stat["null_rate"]
+            else:
+                non_null_rate = f"{stat['non_null'] / total * 100:.0f}%"
             unique = str(stat.get("unique", "-"))
 
+            # 字段名（添加展开标记）
+            field_name = stat["field"]
+            if stat.get("is_expanded"):
+                field_name += " (展开)"
+
             # 构建统计信息字符串
             extra = []
             if "len_avg" in stat:
@@ -363,7 +550,7 @@ def _print_stats(filename: str, total: int, field_stats: List[Dict[str, Any]]) -
                     )
 
             table.add_row(
-                stat["field"],
+                field_name,
                 stat["type"],
                 non_null_rate,
                 unique,
@@ -387,12 +574,19 @@ def _print_stats(filename: str, total: int, field_stats: List[Dict[str, Any]]) -
             if unique_ratio > 0.9 and stat.get("unique", 0) > 100:
                 continue
 
+            # 字段名（添加展开标记）
+            field_display = stat["field"]
+            if stat.get("is_expanded"):
+                field_display += " (展开)"
+
             console.print(
-                f"\n[bold cyan]{stat['field']}[/bold cyan] 值分布 (Top {len(top_values)}):"
+                f"\n[bold cyan]{field_display}[/bold cyan] 值分布 (Top {len(top_values)}):"
             )
             max_count = max(c for _, c in top_values) if top_values else 1
+            # 展开模式下使用 non_null（元素总数），否则使用 total（数据条数）
+            base_count = stat["non_null"] if stat.get("is_expanded") else total
             for value, count in top_values:
-                pct = count / total * 100
+                pct = count / base_count * 100 if base_count > 0 else 0
                 bar_len = int(count / max_count * 20)  # 按相对比例，最长 20 字符
                 bar = "█" * bar_len
                 display_value = value if value else "[空]"
@@ -403,14 +597,14 @@ def _print_stats(filename: str, total: int, field_stats: List[Dict[str, Any]]) -
     except ImportError:
         # 没有 rich，使用普通打印
         print(f"\n{'=' * 50}")
-        print(f"📊 数据概览")
+        print("📊 数据概览")
         print(f"{'=' * 50}")
         print(f"文件: {filename}")
         print(f"总数: {total:,} 条")
         print(f"字段: {len(field_stats)} 个")
 
         print(f"\n{'=' * 50}")
-        print(f"📋 字段统计")
+        print("📋 字段统计")
         print(f"{'=' * 50}")
         print(f"{'字段':<20} {'类型':<8} {'非空率':<8} {'唯一值':<8}")
         print("-" * 50)
@@ -426,6 +620,7 @@ def token_stats(
     field: str = "messages",
     model: str = "cl100k_base",
     detailed: bool = False,
+    workers: Optional[int] = None,
 ) -> None:
     """
     统计数据集的 Token 信息。
@@ -435,6 +630,7 @@ def token_stats(
         field: 要统计的字段（默认 messages），支持嵌套路径语法
         model: 分词器: cl100k_base (默认), qwen2.5, llama3, gpt-4 等
         detailed: 是否显示详细统计
+        workers: 并行进程数，None 自动检测，1 禁用并行
 
     Examples:
         dt token-stats data.jsonl
@@ -442,6 +638,7 @@ def token_stats(
         dt token-stats data.jsonl --field=conversation.messages
         dt token-stats data.jsonl --field=messages[-1].content   # 统计最后一条消息
         dt token-stats data.jsonl --detailed
+        dt token-stats data.jsonl --workers=4   # 使用 4 进程
     """
     filepath = Path(filename)
 
@@ -473,7 +670,7 @@ def token_stats(
 
     # 尝试使用 rich 进度条
     try:
-        from rich.progress import Progress, SpinnerColumn, TextColumn, BarColumn, TaskProgressColumn
+        from rich.progress import BarColumn, Progress, SpinnerColumn, TaskProgressColumn, TextColumn
 
         with Progress(
             SpinnerColumn(),
@@ -491,14 +688,22 @@ def token_stats(
                 from ..tokenizers import messages_token_stats
 
                 stats_result = messages_token_stats(
-                    data, messages_field=field, model=model, progress_callback=update_progress
+                    data,
+                    messages_field=field,
+                    model=model,
+                    progress_callback=update_progress,
+                    workers=workers,
                 )
                 _print_messages_token_stats(stats_result, detailed)
             else:
                 from ..tokenizers import token_stats as compute_token_stats
 
                 stats_result = compute_token_stats(
-                    data, fields=field, model=model, progress_callback=update_progress
+                    data,
+                    fields=field,
+                    model=model,
+                    progress_callback=update_progress,
+                    workers=workers,
                 )
                 _print_text_token_stats(stats_result, detailed)
 
@@ -509,12 +714,14 @@ def token_stats(
             if isinstance(field_value, list) and field_value and isinstance(field_value[0], dict):
                 from ..tokenizers import messages_token_stats
 
-                stats_result = messages_token_stats(data, messages_field=field, model=model)
+                stats_result = messages_token_stats(
+                    data, messages_field=field, model=model, workers=workers
+                )
                 _print_messages_token_stats(stats_result, detailed)
             else:
                 from ..tokenizers import token_stats as compute_token_stats
 
-                stats_result = compute_token_stats(data, fields=field, model=model)
+                stats_result = compute_token_stats(data, fields=field, model=model, workers=workers)
                 _print_text_token_stats(stats_result, detailed)
         except ImportError as e:
             print(f"错误: {e}")
@@ -594,7 +801,7 @@ def _print_messages_token_stats(stats: Dict[str, Any], detailed: bool) -> None:
         print(f"平均 Token: {stats['avg_tokens']:,} (std: {std:.1f})")
         print(f"范围: {stats['min_tokens']:,} - {stats['max_tokens']:,}")
 
-        print(f"\n📈 百分位分布:")
+        print("\n📈 百分位分布:")
         print(f"  P25: {stats.get('p25', '-'):,}  P50: {stats.get('median_tokens', '-'):,}")
         print(f"  P75: {stats.get('p75', '-'):,}  P90: {stats.get('p90', '-'):,}")
         print(f"  P95: {stats.get('p95', '-'):,}  P99: {stats.get('p99', '-'):,}")
@@ -661,7 +868,7 @@ def _print_text_token_stats(stats: Dict[str, Any], detailed: bool) -> None:
         print(f"平均 Token: {stats['avg_tokens']:.1f} (std: {std:.1f})")
         print(f"范围: {stats['min_tokens']:,} - {stats['max_tokens']:,}")
 
-        print(f"\n📈 百分位分布:")
+        print("\n📈 百分位分布:")
         print(f"  P25: {stats.get('p25', '-'):,}  P50: {stats.get('median_tokens', '-'):,}")
         print(f"  P75: {stats.get('p75', '-'):,}  P90: {stats.get('p90', '-'):,}")
         print(f"  P95: {stats.get('p95', '-'):,}  P99: {stats.get('p99', '-'):,}")

dtflow/cli/validate.py

@@ -6,8 +6,6 @@ from pathlib import Path
 from typing import Optional
 
 from ..schema import (
-    Schema,
-    Field,
     alpaca_schema,
     dpo_schema,
     openai_chat_schema,
@@ -16,7 +14,6 @@ from ..schema import (
 from ..storage.io import load_data, save_data
 from .common import _check_file_format
 
-
 # 预设 Schema 映射
 PRESET_SCHEMAS = {
     "openai_chat": openai_chat_schema,
@@ -36,6 +33,7 @@ def validate(
     filter_invalid: bool = False,
     max_errors: int = 20,
     verbose: bool = False,
+    workers: Optional[int] = None,
 ) -> None:
     """
     使用 Schema 验证数据文件。
@@ -47,11 +45,13 @@ def validate(
         filter_invalid: 过滤无效数据并保存
         max_errors: 最多显示的错误数量
         verbose: 显示详细信息
+        workers: 并行进程数，None 自动检测，1 禁用并行
 
     Examples:
         dt validate data.jsonl --preset=openai_chat
         dt validate data.jsonl --preset=alpaca -o valid.jsonl
         dt validate data.jsonl --preset=chat --filter
+        dt validate data.jsonl --preset=chat --workers=4
     """
     filepath = Path(filename)
 
@@ -99,19 +99,54 @@ def validate(
     print(f"总记录数: {total}")
     print()
 
-    # 验证
-    valid_data = []
-    invalid_count = 0
-    error_samples = []
-
-    for i, item in enumerate(data):
-        result = schema.validate(item)
-        if result.valid:
-            valid_data.append(item)
-        else:
-            invalid_count += 1
-            if len(error_samples) < max_errors:
-                error_samples.append((i, result))
+    # 验证（使用并行或串行）
+    use_parallel = workers != 1 and total >= 1000
+
+    if use_parallel:
+        # 使用进度条（如果有 rich）
+        try:
+            from rich.progress import (
+                BarColumn,
+                Progress,
+                SpinnerColumn,
+                TaskProgressColumn,
+                TextColumn,
+            )
+
+            with Progress(
+                SpinnerColumn(),
+                TextColumn("[bold blue]验证数据"),
+                BarColumn(),
+                TaskProgressColumn(),
+            ) as progress:
+                task = progress.add_task("", total=total)
+
+                def update_progress(current: int, total_count: int):
+                    progress.update(task, completed=current)
+
+                valid_data, invalid_results = schema.validate_parallel(
+                    data, workers=workers, progress_callback=update_progress
+                )
+        except ImportError:
+            print("🔍 验证数据...")
+            valid_data, invalid_results = schema.validate_parallel(data, workers=workers)
+
+        invalid_count = len(invalid_results)
+        error_samples = invalid_results[:max_errors]
+    else:
+        # 串行验证
+        valid_data = []
+        invalid_count = 0
+        error_samples = []
+
+        for i, item in enumerate(data):
+            result = schema.validate(item)
+            if result.valid:
+                valid_data.append(item)
+            else:
+                invalid_count += 1
+                if len(error_samples) < max_errors:
+                    error_samples.append((i, result))
 
     valid_count = len(valid_data)
     valid_ratio = valid_count / total * 100 if total > 0 else 0
@@ -138,9 +173,7 @@ def validate(
 
     # 保存有效数据
     if output or filter_invalid:
-        output_path = output or str(filepath).replace(
-            filepath.suffix, f"_valid{filepath.suffix}"
-        )
+        output_path = output or str(filepath).replace(filepath.suffix, f"_valid{filepath.suffix}")
         save_data(valid_data, output_path)
         print(f"✅ 有效数据已保存: {output_path} ({valid_count} 条)")