mlcroissant 🥐

通过此 Google Colab中的入门教程 发现 mlcroissant 🥐。

Python需求

Python版本 >= 3.10。

如果您没有Python环境

python3 -m venv ~/py3
source ~/py3/bin/activate

安装

python -m pip install ".[dev]"

命令可能会失败，例如，由于缺少依赖项，例如。

Failed to build pygraphviz
ERROR: Could not build wheels for pygraphviz, which is required to install pyproject.toml-based projects

可以通过运行以下命令来修复

sudo apt-get install python3-dev graphviz libgraphviz-dev pkg-config

Conda安装

Conda可以帮助创建一致的环境。它还可以在没有root访问权限的情况下安装软件包。要使用Conda，请运行

conda create --name croissant python=3.10 -y
conda activate croissant
conda install graphviz
python3 -m pip install ".[dev]"

验证/加载Croissant数据集

mlcroissant validate --jsonld ../../datasets/titanic/metadata.json

命令

• 退出时返回0，打印完成并显示文件中遇到的警告，如果没有发现错误。
• 退出时返回1并显示所有遇到的错误/警告，否则。

同样，您可以通过启动以下命令生成数据集

mlcroissant load \
    --jsonld ../../datasets/titanic/metadata.json \
    --record_set passengers \
    --num_records 10

通过git+https加载distribution

如果一个 distribution 的 encodingFormat 是 git+https，请通过设置环境变量 CROISSANT_GIT_USERNAME 和 CROISSANT_GIT_PASSWORD 来提供用户名和密码。这些将用于构建加载分布所需的认证。

注意，对于托管在 HuggingFace 上的数据集，CROISSANT_GIT_USERNAME 和 CROISSANT_GIT_PASSWORD 应分别对应您的 HuggingFace 用户名和用户访问令牌。用户访问令牌可以按照 此指南 生成。

通过 HTTP 使用基本认证加载 distribution

如果 distribution 的 contentUrl 需要通过基本认证进行认证，请通过设置环境变量 CROISSANT_BASIC_AUTH_USERNAME 和 CROISSANT_BASIC_AUTH_PASSWORD 来提供用户名和密码。这些将用于构建加载分布所需的认证。

程序化构建 JSON-LD 文件

您可以使用 Python API 程序化地构建 Croissant JSON-LD 文件。

import mlcroissant as mlc
metadata=mlc.nodes.Metadata(
  name="...",
)
metadata.to_json()  # this returns the JSON-LD file.

向标准添加新属性

节点（元数据、RecordSets 等）实现 PEP 681。因此，您可以使用 dataclass 语法声明 RDF 三元组。

示例 1：实现 CreativeWork

@mlc_dataclasses.dataclass
class CreativeWork(Node):

    JSONLD_TYPE = SDO.CreativeWork           # https://schema.org/CreativeWork

    name: str | None = mlc_dataclasses.jsonld_field(
        cardinality="ONE",                   # Cardinality can be ONE or MANY
        default=None,                        # Specify the default value in Python
        description="The name of the item.", # The full description
        input_types=[SDO.Text],              # The schema.org type
        url=SDO.name,                        # The URL of the property
    )

示例 2：实现 RecordSet

@mlc_dataclasses.dataclass
class RecordSet(Node):
    JSONLD_TYPE = constants.ML_COMMONS_RECORD_SET_TYPE

    fields: list[Field] = mlc_dataclasses.jsonld_field(
        cardinality="MANY",                  # Example with cardinality=="MANY"
        default_factory=list,
        description=(
            "A data element that appears in the records of the RecordSet (e.g., one"
            " column of a table)."
        ),
        input_types=[Field],                 # Types can also be other nodes (here `Field`)
        url=constants.ML_COMMONS_FIELD,
    )

示例 3：指定一个版本（默认为所有版本）

@mlc_dataclasses.dataclass
class Field(Node):
    is_enumeration: bool | None = mlc_dataclasses.jsonld_field(
        default=None,
        input_types=[SDO.Boolean],
        url=constants.ML_COMMONS_IS_ENUMERATION,
        versions=[CroissantVersion.V_0_8],   # `is_enumeration` is only valid for v0.8, not v1.0
    )

运行测试

所有测试都可以从 Makefile 中运行

make tests

请注意，应安装 git lfs 才能成功通过所有测试

git lfs install

设计

库中最重要的模块是

• mlcroissant/_src/structure_graph 负责对 Croissant 文件进行 静态分析。我们将 Croissant 文件转换为称为 "结构图" 的 Python 表示形式（使用 NetworkX）。在这个过程中，我们会捕获任何静态分析问题（例如，缺失必填字段或文件中的逻辑问题）。
• mlcroissant/_src/operation_graph 负责对 Croissant 文件进行 动态分析（即，通过产生示例实际加载数据集）。我们将结构图转换为 "操作图"。操作是构建数据集的单位转换（如 Download、Extract 等）。

其他重要模块包括

• mlcroissant/_src/core 定义了所有需要的核心内部组件。例如，Issues 是在分析 Croissant 文件期间跟踪错误和警告的一种方式。
• mlcroissant/__init__.py 声明公共 API，使用 mlcroissant.Dataset。

有关完整设计，请参阅 设计文档，以了解实现的概述。

缓存。默认情况下，所有下载/提取的文件都缓存在 ~/.cache/croissant 中，但您可以通过设置环境变量 $CROISSANT_CACHE 来覆盖此设置。

贡献

欢迎所有贡献！我们甚至有 良好的首次问题 以在项目中开始。有关更详细的用户故事，请参阅 GitHub 项目，并阅读上面关于如何 设计 仓库的说明。

为 mlcroissant 做贡献的一个简单方法就是使用 Croissant 的配置 codespaces。要启动一个 codespace

• 在 Croissant 的主 repo 页面 上，点击 <Code> 按钮，并选择 Codespaces 选项卡。您可以通过点击选项卡左侧的 + 符号来启动一个新的 codespace。默认情况下，codespace 将在 Croissant 的 main 分支上启动，除非您从左侧的分支下拉菜单中选择其他分支。
• 在构建环境时，您的 codespace 将安装所有 mlcroissant 所需的依赖项 - 这样您就可以立即开始编码了！当然，您可以通过 进一步个性化 您的 codespace。
• 要开始为 Croissant 贡献
  • 在您的 codespace 底部面板的 Terminal 选项卡中，使用 git checkout -b feature/my-awesome-new-feature 创建一个新分支
  • 您可以在左侧面板的 Source Control 选项卡中创建新的提交，并运行大多数 git 命令。或者，使用 codespace 底部面板中的 Terminal。
  • 在所有测试都为绿色之前，迭代您的代码（您可以使用 make pytest 或从左侧面板的 Tests 选项卡中运行测试）。
  • 向 https://github.com/mlcommons/croissant 的主分支提交一个 pull request (PR)，并寻求反馈！

或者，您可以使用“经典”的 GitHub 工作流程来为 mlcroissant 贡献

调试

您可以使用 --debug 标志来调试文件的验证

mlcroissant validate --jsonld ../../datasets/titanic/metadata.json --debug

这将

1. 打印额外信息，例如生成的节点；
2. 将生成的结构图保存到日志中指定的文件夹。

发布包

要发布一个包，

1. 在 croissant/python/mlcroissant/pyproject.toml 中提高版本，并合并您的 PR。
2. 在 GitHub 中发布一个 新版本，并在其中添加一个带有 pyproject.toml 中最新版本的标签。确保新版本被标记为 latest。工作流程脚本 python-publish.yml 将触发并发布包到 PyPI。