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

dtflow/SKILL.md

@@ -1,6 +1,17 @@
 ---
 name: dtflow
-description: 数据文件处理（JSONL/CSV/Parquet）- 去重/采样/统计/过滤/转换/Schema验证/训练框架导出
+description: >
+  当用户需要处理 JSONL/CSV/Parquet/JSON/Arrow 数据文件时使用此 skill。
+  提供 CLI 工具 `dt` 和 Python API `DataTransformer`。
+  适用场景：(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) 数据集切分：dt split 按比例切分 train/test/val；
+  (7) 训练框架导出：dt export / export_for() 一键导出到 llama-factory/swift/axolotl；
+  (8) 大文件流式处理：load_stream() O(1) 内存处理 100GB+ 文件。
+  注意：此工具专注数据文件的结构化处理，不涉及 LLM 调用（LLM 调用请用 flexllm）。
 ---
 
 # dtflow - 机器学习训练数据格式转换工具
@@ -135,6 +146,8 @@ dt.stats()                        # 统计
 dt stats data.jsonl                               # 基本统计（文件大小、条数、字段）
 dt stats data.jsonl --full                        # 完整模式：值分布、唯一值、非空率
 dt stats data.jsonl --full -n 20                  # 显示 Top 20 值分布
+dt stats data.jsonl --field=meta.source           # 只统计指定字段（支持嵌套路径，可多次使用）
+dt stats data.jsonl --expand=tags                 # 展开 list 字段统计（可多次使用）
 
 # Token 统计
 dt token-stats data.jsonl                         # 默认统计 messages 字段
@@ -149,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   # 固定随机种子并保存
 
 # 去重
@@ -165,8 +178,26 @@ dt clean data.jsonl --max-len=text:2000           # 最大长度过滤
 dt clean data.jsonl --min-len=messages.#:2        # 最少 2 条消息
 dt clean data.jsonl --keep=question,answer        # 只保留指定字段
 dt clean data.jsonl --drop=metadata               # 删除指定字段
+dt clean data.jsonl --rename=question:instruction,answer:output  # 重命名字段
+dt clean data.jsonl --promote=meta.label          # 提升嵌套字段到顶层
+dt clean data.jsonl --promote=meta.label:tag      # 提升并自定义名称
+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 --strip --drop-empty=input -o cleaned.jsonl  # 组合使用
+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
@@ -185,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.7"
+__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)
 
 
 # ============ 数据转换命令 ============
@@ -164,11 +189,44 @@ def clean(
     max_len: Optional[str] = typer.Option(None, "--max-len", help="最大长度过滤 (字段:长度)"),
     keep: Optional[str] = typer.Option(None, "--keep", help="只保留指定字段"),
     drop: Optional[str] = typer.Option(None, "--drop", help="删除指定字段"),
+    rename: Optional[str] = typer.Option(None, "--rename", help="重命名字段 (old:new,old2:new2)"),
+    promote: Optional[str] = typer.Option(
+        None, "--promote", help="提升嵌套字段到顶层 (meta.label 或 meta.label:tag)"
+    ),
+    add_field: Optional[str] = typer.Option(None, "--add-field", help="添加常量字段 (key:value)"),
+    fill: Optional[str] = typer.Option(None, "--fill", help="填充空值 (field:default_value)"),
+    reorder: Optional[str] = typer.Option(
+        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="输出文件路径"),
 ):
     """数据清洗"""
-    _clean(filename, drop_empty, min_len, max_len, keep, drop, strip, output)
+    _clean(
+        filename,
+        drop_empty,
+        min_len,
+        max_len,
+        keep,
+        drop,
+        rename,
+        promote,
+        add_field,
+        fill,
+        reorder,
+        strip,
+        min_tokens,
+        max_tokens,
+        model,
+        output,
+    )
 
 
 # ============ 数据统计命令 ============
@@ -179,9 +237,15 @@ def stats(
     filename: str = typer.Argument(..., help="输入文件路径"),
     top: int = typer.Option(10, "--top", "-n", help="显示 Top N 值"),
     full: bool = typer.Option(False, "--full", "-f", help="完整模式：统计值分布、唯一值等详细信息"),
+    field: Optional[List[str]] = typer.Option(
+        None, "--field", help="指定统计字段（可多次使用），支持嵌套路径"
+    ),
+    expand: Optional[List[str]] = typer.Option(
+        None, "--expand", help="展开 list 字段统计（可多次使用）"
+    ),
 ):
     """显示数据文件的统计信息"""
-    _stats(filename, top, full)
+    _stats(filename, top, full, field, expand)
 
 
 @app.command("token-stats")
@@ -217,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)
+
+
 # ============ 验证命令 ============