Hugging Face Datasets with_format 和 set_format 混用后为什么列类型变了

在 Hugging Face Datasets 里，with_format 和 set_format 改变的是 Dataset 被索引时的返回视图，通常不会把 features 里的原始列定义改写成另一种存储类型。你看到某一列从 Python 列表变成 NumPy 数组或 PyTorch Tensor，首先应该检查 dataset.format、调用的是哪一个方法，以及 columns 和 output_all_columns 怎样组合。

官方地址：https://huggingface.co/docs/datasets/en/format

最稳妥的判断方式是把“数据对象”“格式状态”“索引返回值”分成三层看：with_format 适合创建训练分支，set_format 适合明确地原地切换当前对象；混用后列类型变化，多数是读取视图残留或变量指向弄错，而不是底层列突然变了。

• 列定义：关注 features，它描述字段的语义和结构。
• 读取状态：关注 format，它记录输出类型、列范围和未格式化列是否保留。
• 调用边界：with_format 返回新对象，set_format 修改当前对象。
• 恢复方式：用 reset_format() 或 set_format() 恢复普通 Python 访问。

先分清“数据没变”和“读取视图变了”

排查这类问题时，我会先把一个 Dataset 的状态拆成三个问题：字段本身叫什么、对象当前挂着什么格式、索引表达式最终返回什么 Python 对象。只看 type(dataset[0]["tokens"]) 很容易把“读取时转换”误认为“数据被改写”。

features 更接近数据集的字段描述；format 则是访问策略。官方文档把 with_format 和 set_format 都描述为改变输出格式，格式化在访问数据时发生。因此同一个字段在默认访问、NumPy 视图和 PyTorch 视图下，返回对象可能不同，但这不代表需要把数据重新保存一份。

可以用下面的最小观察代码把三层信息同时打印出来。这个例子不依赖具体数据集名称，重点是先记录状态再解释类型。

from datasets import Dataset

# 构造一个包含文本和数值序列的最小数据集，便于观察返回类型
dataset = Dataset.from_dict({
    "text": ["a", "b"],
    "tokens": [[1, 2], [3, 4]],
})

# 先看字段定义和默认读取状态，不要只看某一列的运行时类型
print(dataset.features)
print(dataset.format)
print(type(dataset[0]["tokens"]))

# 访问时指定 PyTorch 格式，格式状态会反映在 format 中
torch_view = dataset.with_format(type="torch", columns=["tokens"])
print(torch_view.format)
print(type(torch_view[0]["tokens"]))

接口目标：复制视图还是原地修改

这两个方法最容易混用的地方，不是参数名，而是对象生命周期。with_format 返回一个带有新格式视图的 Dataset；set_format 则把格式设置到当前对象上。调用方如果把两者都写在同一个变量上，后续代码就很难从变量名判断当前拿到的是原始视图还是训练视图。

在一个数据准备模块里，训练器需要 Tensor，而评估、日志或序列化代码可能需要普通 Python 值。此时更清晰的做法是保留 dataset 作为默认对象，用另一个变量保存训练视图；如果确实要切换同一个对象，就在切换前后明确记录 dataset.format。

调用方需求：columns 决定哪些列接受格式化

columns 是最常被忽略的参数。传入列名列表时，只有这些列按指定类型格式化；没有传入时，默认把所有列纳入格式化范围。output_all_columns=True 还会把没有参与格式化的列以 Python 对象一起保留，适合训练输入和原始文本需要同时出现在一个样本里的场景。

例如，训练只需要 tokens，但日志还想保留 text，可以把两种需求写在参数里，而不是在后面猜某列为什么仍然是字符串：

# 只把 tokens 转成训练框架需要的类型，同时保留 text 这类普通列
train_view = dataset.with_format(
    type="torch",
    columns=["tokens"],
    output_all_columns=True,
)

# tokens 是格式化列，text 仍以普通 Python 值返回
sample = train_view[0]
print(type(sample["tokens"]))
print(type(sample["text"]))

如果你只想得到格式化列，就把 output_all_columns 保持为默认的 False，并在接口说明中写清楚未列出的字段是否应该出现在结果里。这是调用方体验上的取舍：字段越完整，调试越方便；字段越收敛，送进训练循环的对象越容易控制。

错误处理：先读 format，再判断列类型

遇到“同一列有时是列表、有时是 Tensor”时，不要立刻在业务代码里加一堆 isinstance 分支。先打印或记录 dataset.format，重点看 type、columns 和 output_all_columns。如果格式是 torch 或 numpy，类型变化就是访问策略的预期结果。

另一个常见来源是 map 之后继续复用旧的格式状态。官方 API 文档说明，set_format 后调用 map 添加新列时，格式化列集合可能随列集合变化而更新。所以在预处理阶段完成后，最好重新确认格式状态；不要把“处理前的列集合”当作“处理后的最终返回契约”。

def describe_dataset_view(dataset, label):
    # 记录视图状态，排查重点是格式而不是底层文件
    state = dataset.format
    print(label, {
        "type": state.get("type"),
        "columns": state.get("columns"),
        "output_all_columns": state.get("output_all_columns"),
    })

# 在交给训练器或评估器前记录一次，避免跨模块猜测状态
describe_dataset_view(dataset, "default")
describe_dataset_view(train_view, "train")

如果希望彻底回到普通 Python 访问，可以调用 reset_format()。对 Dataset 来说，它会把 __getitem__ 的返回格式恢复为默认状态；也可以用 set_format() 或 with_format(None) 表达同一个恢复意图。恢复后再观察一列的类型，结论才不会被之前的训练视图干扰。

兼容策略：让训练视图和普通视图各自有边界

项目一旦同时接入训练、评估和导出，建议把格式选择封装成两个小函数，并让调用者从命名上知道拿到的是什么。这样做的重点不是封装 API，而是避免下游模块接收到一个状态不明的共享 Dataset。

def python_view(dataset):
    # 返回一个普通 Python 读取视图，避免继承训练阶段的残留格式
    return dataset.with_format(None)


def torch_view(dataset, input_columns):
    # 返回独立训练视图，未格式化列也按调用方契约决定是否保留
    return dataset.with_format(
        type="torch",
        columns=input_columns,
        output_all_columns=False,
    )


# 两个调用方拿到不同视图，不需要互相覆盖同一个变量的状态
train_dataset = torch_view(dataset, ["tokens"])
eval_dataset = python_view(dataset)

如果必须临时改变当前对象，可以使用上下文式的 formatted_as，把作用域限制在一个明确的代码块内。离开作用域后，调用方不需要记住“谁在前面调用过 set_format”，这比在多个模块之间共享可变状态更容易维护。

# 只在这一小段读取时使用 NumPy 视图，离开上下文后恢复原状态
with dataset.formatted_as(type="numpy", columns=["tokens"]):
    batch = dataset[:2]
    print(type(batch["tokens"]))

# 上下文之外继续使用默认读取约定，避免把临时视图泄漏给调用方
plain_sample = dataset[0]

常见误区与最终判断

with_format 会把原 Dataset 改掉吗？

按官方接口语义，它返回带有指定格式的新 Dataset。为了让代码意图清楚，保留返回值并使用独立变量；不要调用后又继续假设原变量已经切换。

set_format 为什么会让后面的函数读到 Tensor？

因为它是原地设置当前对象的索引返回格式。只要同一个对象继续向下传递，后面的 __getitem__ 就会看到这个状态，直到再次设置或重置格式。

features 里的类型和索引出来的类型不一致正常吗？

在使用 NumPy、PyTorch 等格式视图时，这是可以预期的。features 负责字段定义，format 负责访问时的转换策略；两者不应混为一个判断。

怎样快速恢复默认结果？

优先调用 reset_format()，然后重新读取 dataset.format 确认状态。需要训练视图时再通过 with_format 创建独立分支，并把视图变量的生命周期控制在训练或批处理边界内。