mlvtools

机器学习版本控制工具。
mlvtools 版本 2.1.1 是支持 dvc<=0.94.1 的最后一个版本。

安装

使用 PyPI 中的 pip 安装 mlvtools

$ pip install mlvtools

从源代码安装以进行开发

$ git clone http://github.com/peopledoc/mlvtools.git
$ cd mlvtools
$ pip install -e .[dev]

教程

有一份教程可供展示如何使用这些工具。请参阅 mlvtools 教程。

关键词

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

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

工具

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

$ ipynb_to_python -n [notebook_path] -o [python_script_path]

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

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

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

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

ipynb_to_dvc：此命令将 Jupyter Notebook 转换为参数化和可执行的 Python 脚本和 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)

配置

可以提供配置文件，但不是必需的。其默认位置是 [working_directory]/.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"
}

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

• path_to_the_script_directory：使用 ipynb_to_script 命令生成 Python 脚本的目录。生成的 Python 脚本名称基于笔记本名称。

  $ ipynb_to_script -n ./data/My\ Notebook.ipynb
  

  生成的脚本：[path_to_the_script_directory]/my_notebook.py

• path_to_the_dvc_cmd_directory：使用 gen_dvc 命令生成 DVC 命令的目录。生成的命令名称基于 Python 脚本名称。

  $ gen_dvc -i ./scripts/my_notebook.py
  

  生成的命令：[path_to_the_python_cmd_directory]/my_notebook_dvc

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

  生成的文件：[path_to_the_dvc_metadata_directory]/my_notebook.dvc

• ignore_keys：用于丢弃单元格的关键词列表。默认值是 ['# No effect ]。（请参阅“丢弃单元格”部分）

• dvc_var_python_cmd_path、dvc_var_python_cmd_name、dvc_var_meta_filename：允许自定义可在 dvc-cmd 文档字符串参数中使用的变量名称。

  它们分别对应于包含 Python 命令文件路径、文件名和包含 DVC 默认元文件名称的变量的变量。

  默认值是 MLV_PY_CMD_PATH、MLV_PY_CMD_NAME 和 MLV_DVC_META_FILENAME。（请参阅 DVC 命令/复杂情况部分以了解使用方法。）

• docstring_conf：用于 Jinja 模板化的文档字符串配置路径（请参阅 DVC 模板化部分）。此参数是可选的。

Jupyter Notebook 语法

步骤元数据单元格用于声明脚本参数和DVC输出及依赖项。这可以使用基本的文档字符串语法完成。这个文档字符串必须是该单元格中的第一条语句，只能在上方写入注释。

良好实践

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

Python脚本参数

可以使用基本的文档字符串语法在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:
"""

生成的Python脚本

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

脚本命令行参数

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脚本上的dvc run命令的包装器。它是管道的一个步骤。

它基于笔记本的步骤元数据中声明的数据。

有两种模式可用

• 仅描述简单情况下的输入/输出（推荐）
• 描述复杂情况下的完整命令

简单情况

语法

:param str input_csv_file: Path to input file
:param str output_csv_file_1: Path to output file 1
:param str output_csv_file_2: Path to output file 2
[...]

[: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_1.csv
:dvc-out output_csv_file_1: ./data/test_set_1.csv
:dvc-out-persist: ./data/train_set_2.csv
:dvc-out-persist output_csv_file_2: ./data/test_set_2.csv
:dvc-extra: --mode train --rate 12

• {file_path}路径可以是绝对路径或相对于工作目录的相对路径。
• {related_param}是对应Python脚本的一个参数，在调用Python脚本时进行填充
• dvc-extra允许声明不是DVC输出或依赖项的参数。这些参数提供给Python命令的调用。

pushd /working-directory

INPUT_CSV_FILE="./data/info.csv"
OUTPUT_CSV_FILE_1="./data/test_set_1.csv"
OUTPUT_CSV_FILE_2="./data/test_set_2.csv"

dvc run \
-d ./data/filter.csv\
-d $INPUT_CSV_FILE\
-o ./data/train_set_1.csv\
-o $OUTPUT_CSV_FILE_1\
--outs-persist ./data/train_set_2.csv\
--outs-persist $OUTPUT_CSV_FILE_2\
gen_src/python_script.py --mode train --rate 12
        --input-csv-file $INPUT_CSV_FILE
        --output-csv-file-1 $OUTPUT_CSV_FILE_1
        --output-csv-file-2 $OUTPUT_CSV_FILE_2

复杂情况

语法

: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文档字符串部分使用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参数提供文档字符串配置文件。此功能仅适用于gen_dvc命令。

删除单元格

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

贡献

我们非常欢迎为mlvtools做出贡献。请参阅我们的贡献指南以获取详细信息。