机器学习版本工具 - MLV-tools

用于版本控制机器学习数据的公共仓库。

安装

MLV-tools可以从PyPi安装

pip install ml-versioning-tools

也可以直接从源代码安装它

git clone https://github.com/peopledoc/ml-versioning-tools.git
cd ml-versioning-tools

    make develop
OR
    make package
    pip install ./package/*.whl

教程

有一个教程可以展示如何使用这些工具。请参阅MLV-tools教程。

关键词

步骤元数据：在此文档中，当它用于声明如参数、dvc输入/输出等元数据时，指代第一个代码单元。

工作目录：项目的的工作目录。用户配置中指定的文件相对于此目录。使用--working-directory（或-w）标志来指定工作目录。

工具

ipynb_to_python：此命令将给定的Jupyter Notebook转换为参数化和可执行的Python3脚本（请参阅下面章节中的具体语法）

ipynb_to_python -n [notebook_path] -o [python_script_path]

gen_dvc：此命令创建一个调用由ipynb_to_python生成的脚本的DVC命令

gen_dvc -i [python_script] --out-py-cmd [python_command] \
              --out-bash-cmd [dvc_command]

export_pipeline：此命令将对应于给定DVC元文件的pipeline导出为bash脚本。pipeline步骤按依赖顺序依次调用。仅适用于本地步骤。

export_pipeline --dvc [DVC target meta file] -o [pipeline script]

ipynb_to_dvc：此命令将指定的Jupyter Notebook转换为参数化和可执行的Python3脚本以及DVC命令。它是ipynb_to_python和gen_dvc的组合。它仅适用于配置文件。

ipynb_to_dvc -n [notebook_path]

check_script_consistency和check_all_scripts_consistency：这些命令确保Jupyter Notebook与其生成的Python脚本之间的一致性。它们可以用作git钩子或在项目的持续集成中使用。一致性检查会忽略空白行和注释。

check_script_consistency -n [notebook_path] -s [script_path]

check_all_scripts_consistency -n [notebook_directory]
# Works only with a configuration file (provided or auto-detected)

配置

可以提供配置文件，但不是必需的。其默认位置是[工作目录]/.mlvtools。使用命令行上的--conf-path（或-c）标志指定特定的配置文件路径。

配置文件格式为JSON

{
  "path":
  {
    "python_script_root_dir": "[path_to_the_script_directory]",
    "dvc_cmd_root_dir": "[path_to_the_dvc_cmd_directory]",
    "dvc_metadata_root_dir": "[path_to_the_dvc_metadata_directory]" [optional]
  },
  "ignore_keys: ["keywords", "to", "ignore"],
  "dvc_var_python_cmd_path": "MLV_PY_CMD_PATH_CUSTOM",
  "dvc_var_python_cmd_name": "MLV_PY_CMD_NAME_CUSTOM",
  "docstring_conf": "./docstring_conf.yml"
}

所有给定路径都必须相对于工作目录

• 脚本目录的路径：是使用ipynb_to_script命令生成Python 3脚本的位置。Python 3脚本的名称基于笔记本名称。

    ipynb_to_script -n ./data/My\ Notebook.ipynb
  
    Generated script: `[path_to_the_script_directory]/my_notebook.py`
  

• DVC命令目录的路径：是使用gen_dvc命令生成DVC命令的位置。生成的命令名称基于Python 3脚本名称。

    gen_dvc -i ./scripts/my_notebook.py
  
    Generated commands: `[path_to_the_python_cmd_directory]/my_notebook_dvc`
  

• DVC元数据目录的路径：是执行gen_dvc命令时生成DVC元数据文件的位置。此值是可选的，默认情况下，DVC元数据文件将保存在工作目录中。生成的DVC元数据文件名称基于Python 3脚本名称。

    ./[path_to_the_python_cmd_directory]/my_notebook_dvc
  
    Generated files: `[path_to_the_dvc_metadata_directory]/my_notebook.dvc`
  

• 忽略键：用于丢弃单元格的关键字列表。默认值是['# No effect ']。（见丢弃单元格部分）

• dvc_var_python_cmd_path、dvc_var_python_cmd_name、dvc_var_meta_filename：它们允许自定义可以在dvc-cmd Docstring参数中使用的变量名称。它们分别对应于存储Python命令文件路径、文件名和存储DVC默认元数据文件名的变量。默认值是'MLV_PY_CMD_PATH'、'MLV_PY_CMD_NAME'和'MLV_DVC_META_FILENAME'。（见DVC命令/复杂情况部分的使用说明）

• docstring_conf：用于Jinja模板的docstring配置文件的路径（见DVC模板部分）。此参数不是必需的。

Jupyter Notebook语法

用于声明脚本参数和DVC输出及依赖的步骤元数据单元格。可以使用基本的Docstring语法完成此操作。此Docstring必须是此单元格中的第一个语句，上方只能写注释。

最佳实践

请避免在您的Jupyter Notebook中使用相对路径，因为它们相对于笔记本位置，而在转换为脚本时位置可能不同。

Python脚本参数

可以使用基本的Docstring语法在Jupyter Notebook中声明参数。此参数描述用于生成可配置和可执行的Python脚本。

Jupyter Notebook中的参数声明

Jupyter Notebook：process_files.ipynb

#:param [type]? [param_name]: [description]?
"""
:param str input_file: the input file
:param output_file: the output_file
:param rate: the learning rate
:param int retry:
"""

生成的Python3脚本

[...]
def process_file(input_file: str, output_file, rate, retry:int):
    """
     ...
    """
[...]

脚本命令行参数

my_script.py -h

usage: my_cmd [-h] --input-file INPUT_FILE --output-file OUTPUT_FILE --rate
             RATE --retry RETRY

Command for script [script_name]

optional arguments:
  -h, --help            show this help message and exit
  --input-file INPUT_FILE
                        the input file
  --output-file OUTPUT_FILE
                        the output_file
  --rate RATE           the rate
  --retry RETRY

所有声明的参数都是必需的。

DVC命令

DVC命令是调用由ipynb_to_python命令生成的Python 3脚本上的dvc run命令的包装器。它是管道的一个步骤。

它基于在notebook元数据中声明的数据，有两种模式可供选择：- 仅描述简单情况下的输入/输出（推荐）- 描述复杂情况下的完整命令

简单情况

语法

:param str input_csv_file: Path to input file
:param str output_csv_file: Path to output file
[...]

[:dvc-[in|out][\s{related_param}]?:[\s{file_path}]?]*
[:dvc-extra: {python_other_param}]?

:dvc-in: ./data/filter.csv
:dvc-in input_csv_file: ./data/info.csv
:dvc-out: ./data/train_set.csv
:dvc-out output_csv_file: ./data/test_set.csv
:dvc-extra: --mode train --rate 12

提供的{file_path}路径可以是绝对路径，也可以是相对于工作目录的相对路径。

{related_param}是相应Python 3脚本的参数，在调用Python脚本时进行填充

dvc-extra允许声明不是DVC输出或依赖的参数。这些参数提供给调用Python 3命令。

pushd /working-directory

INPUT_CSV_FILE="./data/info.csv"
OUTPUT_CSV_FILE="./data/test_set.csv"

dvc run \
-d ./data/filter.csv\
-d $INPUT_CSV_FILE\
-o ./data/train_set.csv\
-o $OUTPUT_CSV_FILE\
gen_src/python_script.py --mode train --rate 12
        --input-csv-file $INPUT_CSV_FILE
        --output-csv-file $OUTPUT_CSV_FILE

复杂情况

语法

:dvc-cmd: {dvc_command}

:dvc-cmd: dvc run -o ./out_train.csv -o ./out_test.csv
    "$MLV_PY_CMD_PATH -m train --out ./out_train.csv &&
     $MLV_PY_CMD_PATH -m test --out ./out_test.csv"

此语法允许提供完整的 dvc 命令以生成。所有路径都可以是绝对路径或相对于工作目录的相对路径。变量 $MLV_PY_CMD_PATH 和 $MLV_PY_CMD_NAME 可用。它们分别包含相应的 Python 命令的路径和名称。变量 $MLV_DVC_META_FILENAME 包含 DVC 元文件的默认名称。

pushd /working-directory
MLV_PY_CMD_PATH="gen_src/python_script.py"
MLV_PY_CMD_NAME="python_script.py"

dvc run -f $MLV_DVC_META_FILENAME -o ./out_train.csv \
    -o ./out_test.csv \
    "$MLV_PY_CMD_PATH -m train --out ./out_train.csv && \
    $MLV_PY_CMD_PATH -m test --out ./out_test.csv"
popd

DVC 模板化

可以在 DVC 的 Docstring 部分使用 Jinja2 模板。例如，声明所有步骤的依赖项、输出和额外参数可能很有用。

示例

# Docstring in Jupyter notebook
"""
[...]
:dvc-in: {{ conf.train_data_file_path }}
:dvc-out: {{ conf.model_file_path }}
:dvc-extra: --rate {{ conf.rate }}
"""

# Docstring configuration file (Yaml format): ./dc_conf.yml

train_data_file_path: ./data/trainset.csv
model_file_path: ./data/model.pkl
rate: 45

# DVC command generation
gen_dvc -i ./python_script.py --docstring-conf ./dc_conf.yml

可以通过主配置或使用 --docstring-conf 参数提供 Docstring 配置文件。此功能仅适用于 gen_dvc 命令。

丢弃单元格

在 Jupyter Notebook 中，某些单元格仅执行以观察中间结果。在 Python 3 脚本中，这些是没有效果的语句。注释 # No effect 允许丢弃整个单元格内容，以避免浪费时间运行这些语句。可以自定义丢弃关键字列表，请参阅 配置 部分。

贡献

我们愉快地欢迎对 MLV-tools 的贡献。有关详细信息，请参阅我们的 贡献指南。