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

dtflow/SKILL.md

@@ -3,13 +3,14 @@ name: dtflow
 description: >
   当用户需要处理 JSONL/CSV/Parquet/JSON/Arrow 数据文件时使用此 skill。
   提供 CLI 工具 `dt` 和 Python API `DataTransformer`。
-  适用场景：(1) 查看数据：dt sample/head/tail 采样预览，dt stats 统计字段分布；
+  适用场景：(1) 查看数据：dt sample/head/tail 采样预览，dt slice 按行范围查看，dt stats 统计字段分布；
   (2) 数据清洗：dt clean 支持 --drop-empty/--min-len/--max-len 过滤行，--keep/--drop/--rename/--promote/--add-field/--fill/--reorder 操作字段；
   (3) 去重：dt dedupe 精确去重或 --similar 相似度去重；
   (4) 格式转换：dt transform 预设模板(openai_chat/alpaca/sharegpt/dpo)或自定义配置；
   (5) Schema 验证：dt validate --preset 验证数据格式；
-  (6) ML 训练框架导出：export_for("llama-factory"/"swift"/"axolotl") 一键生成训练配置；
-  (7) 大文件流式处理：load_stream() O(1) 内存处理 100GB+ 文件。
+  (6) 数据集切分：dt split 按比例切分 train/test/val；
+  (7) 训练框架导出：dt export / export_for() 一键导出到 llama-factory/swift/axolotl；
+  (8) 大文件流式处理：load_stream() O(1) 内存处理 100GB+ 文件。
   注意：此工具专注数据文件的结构化处理，不涉及 LLM 调用（LLM 调用请用 flexllm）。
 ---
 
@@ -153,7 +154,6 @@ dt token-stats data.jsonl                         # 默认统计 messages 字段
 dt token-stats data.jsonl -f text                 # 指定统计字段
 dt token-stats data.jsonl -m qwen2.5              # 指定分词器 (cl100k_base/qwen2.5/llama3)
 dt token-stats data.jsonl --detailed              # 显示详细统计
-dt token-stats data.jsonl -w 4                    # 多进程加速（数据量>=1000时自动启用）
 
 # 采样（支持字段路径语法）
 dt sample data.jsonl 100                          # 随机采样 100 条
@@ -162,7 +162,7 @@ dt sample data.jsonl 1000 --by=category           # 分层采样
 dt sample data.jsonl 1000 --by=category --uniform # 均匀分层采样
 dt sample data.jsonl --where="messages.#>=2"      # 条件筛选
 dt sample data.jsonl 10 -f input,output           # 只显示指定字段
-dt sample data.jsonl 10 --raw                     # 输出原始 JSON（不截断）
+dt sample data.jsonl 10 --pretty                  # 表格预览模式（默认原始 JSON）
 dt sample data.jsonl 100 --seed=42 -o out.jsonl   # 固定随机种子并保存
 
 # 去重
@@ -185,14 +185,25 @@ dt clean data.jsonl --add-field=source:web        # 添加常量字段
 dt clean data.jsonl --fill=label:unknown          # 填充空值/缺失字段
 dt clean data.jsonl --reorder=id,text,label       # 控制字段输出顺序
 dt clean data.jsonl --strip                       # 去除字符串首尾空白
+dt clean data.jsonl --min-tokens=content:10          # 最少 10 tokens
+dt clean data.jsonl --max-tokens=content:1000 -m gpt-4  # 最多 1000 tokens（指定分词器）
 dt clean data.jsonl --promote=meta.label --drop=meta --fill=label:unknown  # 组合使用
 
+# 数据集切分
+dt split data.jsonl --ratio=0.8 --seed=42           # 二分: train/test
+dt split data.jsonl --ratio=0.7,0.15,0.15           # 三分: train/val/test
+dt split data.jsonl --ratio=0.8 -o /tmp/output      # 指定输出目录
+
+# 训练框架导出
+dt export data.jsonl --framework=llama-factory       # 导出到 LLaMA-Factory
+dt export data.jsonl -f swift -o ./swift_out         # 导出到 ms-swift
+dt export data.jsonl -f llama-factory --check        # 仅检查兼容性
+
 # 验证
 dt validate data.jsonl --preset=openai_chat       # 预设: openai_chat/alpaca/dpo/sharegpt
 dt validate data.jsonl -p alpaca -f -o valid.jsonl  # 过滤无效数据并保存
 dt validate data.jsonl -p openai_chat -v          # 显示详细信息
 dt validate data.jsonl -p openai_chat --max-errors=50  # 最多显示 50 条错误
-dt validate data.jsonl -p openai_chat -w 4        # 多进程加速
 
 # 转换
 dt transform data.jsonl --preset=openai_chat
@@ -205,10 +216,13 @@ dt diff a.jsonl b.jsonl --key=id                  # 对比差异
 dt diff a.jsonl b.jsonl --key=id -o report.md     # 输出对比报告
 
 # 查看数据
-dt head data.jsonl 10                             # 前 10 条
+dt head data.jsonl 10                             # 前 10 条（默认原始 JSON）
 dt head data.jsonl 10 -f input,output             # 只显示指定字段
-dt head data.jsonl 10 --raw                       # 输出完整 JSON（不截断）
+dt head data.jsonl 10 --pretty                    # 表格预览模式
 dt tail data.jsonl 10                             # 后 10 条
+dt slice data.jsonl 10:20                         # 第 10-19 行（Python 切片语法）
+dt slice data.jsonl :100                          # 前 100 行
+dt slice data.jsonl 100:                          # 第 100 行到末尾
 
 # 其他
 dt run pipeline.yaml                              # Pipeline 执行

dtflow/__init__.py

@@ -60,7 +60,7 @@ from .tokenizers import (
     token_stats,
 )
 
-__version__ = "0.5.8"
+__version__ = "0.5.9"
 
 __all__ = [
     # core

dtflow/__main__.py

@@ -18,6 +18,8 @@ Commands:
     clean         数据清洗
     run           执行 Pipeline 配置文件
     history       显示数据血缘历史
+    split         分割数据集
+    export        导出到训练框架
     validate      使用 Schema 验证数据格式
     logs          日志查看工具使用说明
     install-skill 安装 dtflow skill 到 Claude Code
@@ -33,12 +35,16 @@ from .cli.commands import clean as _clean
 from .cli.commands import concat as _concat
 from .cli.commands import dedupe as _dedupe
 from .cli.commands import diff as _diff
+from .cli.commands import eval as _eval
+from .cli.commands import export as _export
 from .cli.commands import head as _head
 from .cli.commands import history as _history
 from .cli.commands import install_skill as _install_skill
 from .cli.commands import run as _run
 from .cli.commands import sample as _sample
 from .cli.commands import skill_status as _skill_status
+from .cli.commands import slice_data as _slice_data
+from .cli.commands import split as _split
 from .cli.commands import stats as _stats
 from .cli.commands import tail as _tail
 from .cli.commands import token_stats as _token_stats
@@ -69,12 +75,12 @@ def sample(
     by: Optional[str] = typer.Option(None, "--by", help="分层采样字段"),
     uniform: bool = typer.Option(False, "--uniform", help="均匀采样模式"),
     fields: Optional[str] = typer.Option(None, "--fields", "-f", help="只显示指定字段（逗号分隔）"),
-    raw: bool = typer.Option(False, "--raw", "-r", help="输出原始 JSON（不截断）"),
+    pretty: bool = typer.Option(False, "--pretty", "-R", help="使用表格预览（默认原始 JSON）"),
     where: Optional[List[str]] = typer.Option(None, "--where", "-w", help="筛选条件 (可多次使用)"),
 ):
     """从数据文件中采样指定数量的数据"""
     actual_num = num_arg if num_arg is not None else num
-    _sample(filename, actual_num, type, output, seed, by, uniform, fields, raw, where)
+    _sample(filename, actual_num, type, output, seed, by, uniform, fields, not pretty, where)
 
 
 @app.command()
@@ -84,12 +90,12 @@ def head(
     num: int = typer.Option(10, "--num", "-n", help="显示数量", show_default=True),
     output: Optional[str] = typer.Option(None, "--output", "-o", help="输出文件路径"),
     fields: Optional[str] = typer.Option(None, "--fields", "-f", help="只显示指定字段"),
-    raw: bool = typer.Option(False, "--raw", "-r", help="输出原始 JSON（不截断）"),
+    pretty: bool = typer.Option(False, "--pretty", "-R", help="使用表格预览（默认原始 JSON）"),
 ):
     """显示文件的前 N 条数据"""
     # 位置参数优先于选项参数
     actual_num = num_arg if num_arg is not None else num
-    _head(filename, actual_num, output, fields, raw)
+    _head(filename, actual_num, output, fields, not pretty)
 
 
 @app.command()
@@ -99,12 +105,31 @@ def tail(
     num: int = typer.Option(10, "--num", "-n", help="显示数量", show_default=True),
     output: Optional[str] = typer.Option(None, "--output", "-o", help="输出文件路径"),
     fields: Optional[str] = typer.Option(None, "--fields", "-f", help="只显示指定字段"),
-    raw: bool = typer.Option(False, "--raw", "-r", help="输出原始 JSON（不截断）"),
+    pretty: bool = typer.Option(False, "--pretty", "-R", help="使用表格预览（默认原始 JSON）"),
 ):
     """显示文件的后 N 条数据"""
     # 位置参数优先于选项参数
     actual_num = num_arg if num_arg is not None else num
-    _tail(filename, actual_num, output, fields, raw)
+    _tail(filename, actual_num, output, fields, not pretty)
+
+
+@app.command("slice")
+def slice_cmd(
+    filename: str = typer.Argument(..., help="输入文件路径"),
+    range_str: str = typer.Argument(..., help="行号范围 (start:end)，如 10:20、:100、100:、-10:"),
+    output: Optional[str] = typer.Option(None, "--output", "-o", help="输出文件路径"),
+    fields: Optional[str] = typer.Option(None, "--fields", "-f", help="只显示指定字段"),
+    pretty: bool = typer.Option(False, "--pretty", "-R", help="使用表格预览（默认原始 JSON）"),
+):
+    """按行号范围查看数据（Python 切片语法）
+
+    示例:
+        dt slice data.jsonl 10:20     第 10-19 行
+        dt slice data.jsonl :100      前 100 行
+        dt slice data.jsonl 100:      第 100 行到末尾
+        dt slice data.jsonl -10:      最后 10 行
+    """
+    _slice_data(filename, range_str, output, fields, not pretty)
 
 
 # ============ 数据转换命令 ============
@@ -174,6 +199,13 @@ def clean(
         None, "--reorder", help="控制字段顺序 (field1,field2,...)"
     ),
     strip: bool = typer.Option(False, "--strip", help="去除字符串首尾空白"),
+    min_tokens: Optional[str] = typer.Option(
+        None, "--min-tokens", help="最小 token 数过滤 (字段:数量)"
+    ),
+    max_tokens: Optional[str] = typer.Option(
+        None, "--max-tokens", help="最大 token 数过滤 (字段:数量)"
+    ),
+    model: str = typer.Option("cl100k_base", "--model", "-m", help="分词器模型 (默认 cl100k_base)"),
     output: Optional[str] = typer.Option(None, "--output", "-o", help="输出文件路径"),
 ):
     """数据清洗"""
@@ -190,6 +222,9 @@ def clean(
         fill,
         reorder,
         strip,
+        min_tokens,
+        max_tokens,
+        model,
         output,
     )
 
@@ -221,12 +256,9 @@ def token_stats(
         "cl100k_base", "--model", "-m", help="分词器: cl100k_base (默认), qwen2.5, llama3, gpt-4 等"
     ),
     detailed: bool = typer.Option(False, "--detailed", "-d", help="显示详细统计"),
-    workers: Optional[int] = typer.Option(
-        None, "--workers", "-w", help="并行进程数 (默认自动, 1 禁用并行)"
-    ),
 ):
     """统计数据集的 Token 信息"""
-    _token_stats(filename, field, model, detailed, workers)
+    _token_stats(filename, field, model, detailed)
 
 
 @app.command()
@@ -249,6 +281,71 @@ def history(
     _history(filename, json)
 
 
+# ============ 切分与导出命令 ============
+
+
+@app.command()
+def split(
+    filename: str = typer.Argument(..., help="输入文件路径"),
+    ratio: str = typer.Option("0.8", "--ratio", "-r", help="分割比例，如 0.8 或 0.7,0.15,0.15"),
+    seed: Optional[int] = typer.Option(None, "--seed", help="随机种子"),
+    output: Optional[str] = typer.Option(None, "--output", "-o", help="输出目录（默认同目录）"),
+):
+    """分割数据集为 train/test (或 train/val/test)"""
+    _split(filename, ratio, seed, output)
+
+
+@app.command()
+def export(
+    filename: str = typer.Argument(..., help="输入文件路径"),
+    framework: str = typer.Option(
+        ..., "--framework", "-f", help="目标框架: llama-factory, swift, axolotl"
+    ),
+    output: Optional[str] = typer.Option(None, "--output", "-o", help="输出目录"),
+    name: Optional[str] = typer.Option(None, "--name", "-n", help="数据集名称"),
+    check: bool = typer.Option(False, "--check", help="仅检查兼容性，不导出"),
+):
+    """导出数据到训练框架 (LLaMA-Factory, ms-swift, Axolotl)"""
+    _export(filename, framework, output, name, check)
+
+
+# ============ 评估命令 ============
+
+
+@app.command()
+def eval(
+    result_file: str = typer.Argument(..., help="模型输出的 .jsonl 文件路径"),
+    source: Optional[str] = typer.Option(
+        None, "--source", "-s", help="原始输入文件，按行号对齐合并"
+    ),
+    response_col: str = typer.Option("content", "--response-col", "-r", help="模型响应字段名"),
+    label_col: Optional[str] = typer.Option(
+        None, "--label-col", "-l", help="标签字段名（不指定时自动检测）"
+    ),
+    extract: str = typer.Option(
+        "direct",
+        "--extract",
+        "-e",
+        help="管道式提取规则，算子: direct/tag:X/json_key:X/index:N/line:N/lines/regex:X",
+    ),
+    sep: Optional[str] = typer.Option(None, "--sep", help="配合 index 算子使用的分隔符"),
+    mapping: Optional[str] = typer.Option(None, "--mapping", "-m", help="值映射 (k1:v1,k2:v2)"),
+    output_dir: str = typer.Option("record", "--output-dir", "-o", help="指标报告输出目录"),
+):
+    """对模型输出进行解析和指标评估
+
+    两阶段解析：自动清洗（去 think 标签、提取代码块）+ 管道式提取。
+
+    示例:
+        dt eval result.jsonl --label-col=label
+        dt eval result.jsonl --extract="tag:标签" --mapping="是:1,否:0"
+        dt eval result.jsonl --source=input.jsonl --response-col=api_output.content
+        dt eval result.jsonl --extract="json_key:result | index:0" --sep=","
+        dt eval result.jsonl --extract="lines | index:1" --sep="|"
+    """
+    _eval(result_file, source, response_col, label_col, extract, sep, mapping, output_dir)
+
+
 # ============ 验证命令 ============
 
 
@@ -262,12 +359,9 @@ def validate(
     filter: bool = typer.Option(False, "--filter", "-f", help="过滤无效数据并保存"),
     max_errors: int = typer.Option(20, "--max-errors", help="最多显示的错误数量"),
     verbose: bool = typer.Option(False, "--verbose", "-v", help="显示详细信息"),
-    workers: Optional[int] = typer.Option(
-        None, "--workers", "-w", help="并行进程数 (默认自动, 1 禁用并行)"
-    ),
 ):
     """使用预设 Schema 验证数据格式"""
-    _validate(filename, preset, output, filter, max_errors, verbose, workers)
+    _validate(filename, preset, output, filter, max_errors, verbose)
 
 
 # ============ 工具命令 ============

dtflow/cli/clean.py

@@ -138,6 +138,9 @@ def clean(
     fill: Optional[str] = None,
     reorder: Optional[str] = None,
     strip: bool = False,
+    min_tokens: Optional[str] = None,
+    max_tokens: Optional[str] = None,
+    model: str = "cl100k_base",
     output: Optional[str] = None,
 ) -> None:
     """
@@ -173,6 +176,9 @@ def clean(
         dt clean data.jsonl --fill=label:unknown            # 填充空值
         dt clean data.jsonl --reorder=id,text,label         # 控制字段顺序
         dt clean data.jsonl --strip                         # 去除字符串首尾空白
+        dt clean data.jsonl --min-tokens=content:10            # content 字段最少 10 tokens
+        dt clean data.jsonl --max-tokens=content:1000          # content 字段最多 1000 tokens
+        dt clean data.jsonl --min-tokens=text:50 --model=gpt-4 # 使用 gpt-4 分词器
     """
     filepath = Path(filename)
 
@@ -186,6 +192,13 @@ def clean(
     # 解析参数
     min_len_field, min_len_value = _parse_len_param(min_len) if min_len else (None, None)
     max_len_field, max_len_value = _parse_len_param(max_len) if max_len else (None, None)
+    min_tokens_field, min_tokens_value = (
+        _parse_len_param(min_tokens) if min_tokens else (None, None)
+    )
+    max_tokens_field, max_tokens_value = (
+        _parse_len_param(max_tokens) if max_tokens else (None, None)
+    )
+    token_model = model
     keep_fields = _parse_field_list(keep) if keep else None
     drop_fields_set = set(_parse_field_list(drop)) if drop else None
     rename_map = _parse_rename_param(rename) if rename else None
@@ -229,6 +242,14 @@ def clean(
         print(f"🔄 填充空值: {fill_desc}")
     if reorder_fields:
         print(f"🔄 字段排序: {', '.join(reorder_fields)}")
+    if min_tokens_field:
+        print(
+            f"🔄 过滤 {min_tokens_field} tokens < {min_tokens_value} 的记录 (model={token_model})..."
+        )
+    if max_tokens_field:
+        print(
+            f"🔄 过滤 {max_tokens_field} tokens > {max_tokens_value} 的记录 (model={token_model})..."
+        )
 
     output_path = output or str(filepath)
 
@@ -271,6 +292,11 @@ def clean(
                 add_field_map=add_field_map,
                 fill_map=fill_map,
                 reorder_fields=reorder_fields,
+                min_tokens_field=min_tokens_field,
+                min_tokens_value=min_tokens_value,
+                max_tokens_field=max_tokens_field,
+                max_tokens_value=max_tokens_value,
+                token_model=token_model,
             )
 
             # 如果使用了临时文件，移动到目标位置
@@ -316,6 +342,11 @@ def clean(
         add_field_map=add_field_map,
         fill_map=fill_map,
         reorder_fields=reorder_fields,
+        min_tokens_field=min_tokens_field,
+        min_tokens_value=min_tokens_value,
+        max_tokens_field=max_tokens_field,
+        max_tokens_value=max_tokens_value,
+        token_model=token_model,
     )
 
     # 保存结果
@@ -458,6 +489,11 @@ def _clean_data_single_pass(
     add_field_map: Optional[Dict[str, str]] = None,
     fill_map: Optional[Dict[str, str]] = None,
     reorder_fields: Optional[List[str]] = None,
+    min_tokens_field: Optional[str] = None,
+    min_tokens_value: Optional[int] = None,
+    max_tokens_field: Optional[str] = None,
+    max_tokens_value: Optional[int] = None,
+    token_model: str = "cl100k_base",
 ) -> tuple:
     """
     单次遍历执行所有清洗操作。
@@ -476,11 +512,18 @@ def _clean_data_single_pass(
     Returns:
         (清洗后的数据, 统计信息列表)
     """
+    # 延迟导入 count_tokens（仅在需要时）
+    _count_tokens = None
+    if min_tokens_field is not None or max_tokens_field is not None:
+        from ..tokenizers import count_tokens as _count_tokens
+
     result = []
     stats = {
         "drop_empty": 0,
         "min_len": 0,
         "max_len": 0,
+        "min_tokens": 0,
+        "max_tokens": 0,
     }
 
     # 预先计算 keep_fields 集合（如果有的话）
@@ -516,6 +559,20 @@ def _clean_data_single_pass(
                 stats["max_len"] += 1
                 continue
 
+        # 4.5 最小 token 数过滤
+        if min_tokens_field is not None:
+            value = get_field_with_spec(item, min_tokens_field, default="")
+            if _count_tokens(str(value), model=token_model) < min_tokens_value:
+                stats["min_tokens"] += 1
+                continue
+
+        # 4.6 最大 token 数过滤
+        if max_tokens_field is not None:
+            value = get_field_with_spec(item, max_tokens_field, default="")
+            if _count_tokens(str(value), model=token_model) > max_tokens_value:
+                stats["max_tokens"] += 1
+                continue
+
         # 5. 提升嵌套字段（在 drop 之前，否则父字段被删后无法提取）
         if promote_list is not None:
             item = _promote_fields(item, promote_list)
@@ -554,6 +611,10 @@ def _clean_data_single_pass(
         step_stats.append(f"min-len: -{stats['min_len']}")
     if stats["max_len"] > 0:
         step_stats.append(f"max-len: -{stats['max_len']}")
+    if stats["min_tokens"] > 0:
+        step_stats.append(f"min-tokens: -{stats['min_tokens']}")
+    if stats["max_tokens"] > 0:
+        step_stats.append(f"max-tokens: -{stats['max_tokens']}")
     if keep_fields:
         step_stats.append(f"keep: {len(keep_fields)} 字段")
     if drop_fields:
@@ -588,6 +649,11 @@ def _clean_streaming(
     add_field_map: Optional[Dict[str, str]] = None,
     fill_map: Optional[Dict[str, str]] = None,
     reorder_fields: Optional[List[str]] = None,
+    min_tokens_field: Optional[str] = None,
+    min_tokens_value: Optional[int] = None,
+    max_tokens_field: Optional[str] = None,
+    max_tokens_value: Optional[int] = None,
+    token_model: str = "cl100k_base",
 ) -> int:
     """
     流式清洗数据。
@@ -596,6 +662,11 @@ def _clean_streaming(
         处理后的数据条数
     """
 
+    # 延迟导入 count_tokens（仅在需要时）
+    _count_tokens = None
+    if min_tokens_field is not None or max_tokens_field is not None:
+        from ..tokenizers import count_tokens as _count_tokens
+
     def clean_filter(item: Dict) -> bool:
         """过滤函数：返回 True 保留，False 过滤（支持嵌套路径）"""
         # 空值过滤
@@ -618,6 +689,18 @@ def _clean_streaming(
             if _get_value_len(get_field_with_spec(item, max_len_field, default="")) > max_len_value:
                 return False
 
+        # 最小 token 数过滤
+        if min_tokens_field is not None:
+            value = get_field_with_spec(item, min_tokens_field, default="")
+            if _count_tokens(str(value), model=token_model) < min_tokens_value:
+                return False
+
+        # 最大 token 数过滤
+        if max_tokens_field is not None:
+            value = get_field_with_spec(item, max_tokens_field, default="")
+            if _count_tokens(str(value), model=token_model) > max_tokens_value:
+                return False
+
         return True
 
     def clean_transform(item: Dict) -> Dict:
@@ -644,7 +727,13 @@ def _clean_streaming(
         )
 
     # 执行过滤
-    if empty_fields is not None or min_len_field is not None or max_len_field is not None:
+    if (
+        empty_fields is not None
+        or min_len_field is not None
+        or max_len_field is not None
+        or min_tokens_field is not None
+        or max_tokens_field is not None
+    ):
         st = st.filter(clean_filter)
 
     # 提升嵌套字段（在 drop 之前，否则父字段被删后无法提取）

dtflow/cli/commands.py

@@ -16,6 +16,12 @@ CLI 命令统一导出入口
 # 清洗命令
 from .clean import clean, dedupe
 
+# 评估命令
+from .eval import eval
+
+# 导出命令
+from .export import export
+
 # IO 操作命令
 from .io_ops import concat, diff
 
@@ -24,11 +30,14 @@ from .lineage import history
 
 # Pipeline 命令
 from .pipeline import run
-from .sample import head, sample, tail
+from .sample import head, sample, slice_data, tail
 
 # Skill 命令
 from .skill import install_skill, skill_status, uninstall_skill
 
+# 切分命令
+from .split import split
+
 # 统计命令
 from .stats import stats, token_stats
 
@@ -43,6 +52,7 @@ __all__ = [
     "sample",
     "head",
     "tail",
+    "slice_data",
     # 转换
     "transform",
     # 统计
@@ -60,6 +70,12 @@ __all__ = [
     "history",
     # 验证
     "validate",
+    # 切分
+    "split",
+    # 导出
+    "export",
+    # 评估
+    "eval",
     # Skill
     "install_skill",
     "uninstall_skill",