spaCy 项目让您可以管理和共享用于不同用例和领域的端到端 spaCy 工作流程，并协调训练、打包和部署您的自定义管道。您可以从克隆预定义的项目模板开始，根据您的需要进行调整，加载您的数据，训练管道，将其导出为 Python 包，将您的输出上传到远程存储，并与您的团队共享您的结果。spaCy 项目可以通过新的 spacy project 命令使用，并且我们在我们的 projects 仓库中提供模板。

spaCy 项目使您可以轻松地与数据科学和机器学习生态系统中许多其他出色的工具集成，以跟踪和管理您的数据和实验，迭代演示和原型，并将您的模型投入生产。

1. 克隆一个项目模板

spacy project clone 命令克隆现有的项目模板并将文件复制到本地目录。然后您可以运行该项目，例如训练一个管道并编辑命令和脚本以构建完全自定义的工作流程。

默认情况下，项目将克隆到当前工作目录。您可以指定可选的第二个参数来定义输出目录。 --repo 选项允许您定义要克隆的自定义仓库，如果您不想使用 spaCy projects 仓库。您还可以使用您有权访问的任何私有仓库。

2. 获取项目资源

资源是您的项目需要的数据文件——例如，训练和评估数据或预训练的向量和嵌入，用于初始化您的模型。每个项目模板都带有 project.yml，它定义了要下载的资源以及放置它们的位置。 spacy project assets 将为您获取项目资源

资源 URL 可以是多种不同的协议：HTTP、HTTPS、FTP、SSH，甚至云存储，如 GCS 和 S3。您还可以使用 git 获取资源，方法是将 url 字符串替换为 git 块。spaCy 将使用 Git 的“稀疏检出”功能来避免下载整个仓库。

有时您的项目配置可能包含大型资源，您不一定希望在运行 spacy project assets 时下载它们。这就是为什么资源可以标记为 extra——默认情况下，这些资源不会被下载。如果应该下载它们，请运行 spacy project assets --extra。

3. 运行一个命令

命令由一个或多个步骤组成，可以使用 spacy project run 运行。以下将运行在 project.yml 中定义的 preprocess 命令

命令可以使用 deps（命令所需的的文件）和 outputs（命令创建的文件）键定义其期望的 依赖项和输出。这允许您的项目跟踪更改并确定是否需要重新运行命令。例如，如果您的输入数据发生更改，您希望重新运行 preprocess 命令。但是，如果没有更改，可以跳过此步骤。您还可以设置 --force 以强制重新运行命令，或 --dry 以执行“dry run”并查看会发生什么（而不实际运行脚本）。

从 spaCy v3.4.2 开始，spacy projects run 会检查您已安装的依赖项，以验证您的环境是否已正确设置并与项目的 requirements.txt 对齐。如果检测到缺失或冲突的依赖项，将显示相应的警告。如果您想禁用依赖项检查，请在您的项目的 project.yml 中设置 check_requirements: false。

4. 运行一个工作流程

工作流程是一系列按顺序运行的命令，并且通常相互依赖。例如，要生成一个管道包，您可以首先转换您的数据，然后运行 spacy train 在转换后的数据上训练您的管道，如果成功，则运行 spacy package 将最佳训练工件转换为可安装的 Python 包。以下命令运行在 project.yml 中定义的名为 all 的工作流程，并按顺序执行它指定的命令

使用命令中定义的期望的 依赖项和输出，spaCy 可以确定是否需要重新运行命令（如果其输入或输出已更改）或是否跳过它。如果您正在寻找实施更高级的数据管道并跟踪您在 Git 中的更改，请查看 数据版本控制 (DVC) 集成。 spacy project dvc 命令从在您的 project.yml 中定义的工作流程生成一个 DVC 配置文件，以便您可以将您的 spaCy 项目作为 DVC 仓库管理。

5. 可选：推送到远程存储

训练管道后，您可以选择使用 spacy project push 命令使用 S3、 Google Cloud Storage 或 SSH 等协议将您的输出上传到远程存储。这可以帮助您导出管道包，共享与团队的工作，或缓存结果以避免重复工作。

您的 project.yml 中的 remotes 部分允许您为不同的存储分配名称。要从远程存储下载状态，您可以使用 spacy project pull 命令。有关更多详细信息，请参阅有关 远程存储的文档。

项目目录和资源

project.yml

project.yml 定义了项目所依赖的资源，例如数据集和预训练权重，以及可以单独或作为工作流程运行的一系列命令——例如，预处理数据，将其转换为 spaCy 的格式，训练管道，评估它并导出指标，打包它并启动一个快速的 Web 演示。它看起来非常类似于用于定义 CI 管道的配置文件。

explosion/projects/v3/pipelines/tagger_parser_ud/project.yml

Data assets

资源是您的项目可能需要的任何文件，例如训练和开发语料库或用于初始化模型的预训练权重。 资源在您的 project.yml 的 assets 块中定义，可以使用 project assets 命令下载。 定义校验和可以让您验证运行项目的其他人将使用您使用的相同文件。 资源 URL 可以是多种不同的 协议：HTTP、HTTPS、FTP、SSH，甚至 云存储，例如 GCS 和 S3。 您还可以从 Git 仓库 下载资源。

Downloading from a URL or cloud storage

在底层，spaCy 使用 smart-open 库，因此您可以使用它支持的任何协议。 请注意，您可能需要安装额外的依赖项才能使用某些协议。

Downloading from a Git repo

如果提供 git 块，则从给定的 Git 仓库下载资源。 您可以从您有权访问的任何仓库下载。 在底层，这使用了 Git 的“稀疏检出”功能，因此您只需下载所需的文件，而不是整个仓库。

Working with private assets

对于许多项目，您正在处理的数据集和权重可能是公司内部的，并且无法在互联网上获取。 在这种情况下，您可以指定目标路径和校验和，并省略 URL。 当您的团队成员克隆并运行您的项目时，他们可以将文件放在各自的目录中。 project assets 命令会提醒您有关缺失的文件和不匹配的校验和，以便您可以确保其他人使用与您相同的数据运行您的项目。

Dependencies and outputs

在 project.yml 中定义的每个命令可以选择性地定义依赖项和输出的列表。 这些是命令需要和创建的文件。 例如，用于训练管道的命令可能依赖于 config.cfg 以及训练和评估数据，并且它将导出目录 model-best，您可以在其他命令中重新使用它。

project.yml

如果您正在运行一个命令，并且它依赖于缺失的文件，spaCy 会向您显示一个错误。 如果命令定义了自上次运行以来未更改的依赖项和输出，则该命令将被跳过。 这意味着您只会重新运行需要重新运行的命令。 命令还可以设置 no_skip: true，如果它们永远不应被跳过 – 例如运行测试的命令。 没有输出的命令也永远不会被跳过。 要强制重新运行命令或工作流，即使没有任何更改，您可以使用 --force 标志。

请注意，spacy project 不会根据依赖项和输出编译任何依赖项图，也不会自动重新运行以前的步骤。 例如，如果您只运行命令 train，该命令依赖于由 preprocess 创建的数据，并且这些文件缺失，spaCy 会显示一个错误 – 它不会只是重新运行 preprocess。 如果您正在寻找更高级的数据管理，请查看 Data Version Control (DVC) 集成。 如果您计划将您的 spaCy 项目与 DVC 集成，您还可以使用 outputs_no_cache 代替 outputs 来定义不会被缓存或跟踪的输出。

Files and directory structure

project.yml 可以定义一个应在项目内创建的目录列表 – 例如，assets、training、corpus 等。 spaCy 将确保这些目录始终可用，以便您的命令可以写入和读取它们。 项目目录还将包含使用 spacy project clone 从项目模板复制的所有文件和目录。 以下是项目目录的示例

Example project directory

如果您不想让项目创建目录，您可以删除它并将其从 project.yml 中删除 – 只要它不是任何命令所必需的即可。 自定义模板 可以使用它们需要的任何目录 – 项目所需的唯一文件是 project.yml。

Custom scripts and projects

project.yml 允许您定义任何自定义命令并在训练、评估或部署工作流中运行它们。 script 部分定义了一个按顺序调用的命令列表，作为子进程。 这让您可以执行其他 Python 脚本或命令行工具。 假设您编写了一些集成测试，这些测试加载训练命令生成的最佳模型并检查其是否正常工作。 现在，您可以定义一个 test 命令，该命令调用 pytest，运行您的测试并使用 pytest-html 导出测试报告

project.yml

将 training/model-best 添加到命令的 deps 可确保文件可用。 否则，spaCy 会显示一个错误，并且该命令将不会运行。 设置 no_skip: true 意味着该命令将始终运行，即使依赖项（训练的管道）未更改。 这在这里很有意义，因为您通常不想跳过测试。

Writing custom scripts

您的项目命令可以包含任何自定义脚本——基本上，您可以从命令行运行的任何内容。这是一个使用 typer 的自定义脚本示例，用于快速轻松地定义通过您的 project.yml 定义的命令行参数。

scripts/custom_evaluation.py

在您的 project.yml 中，您可以调用 python scripts/custom_evaluation.py 来运行脚本，并带有函数参数。您还可以使用 vars 部分来定义可重用的变量，这些变量将在命令、路径和 URL 中被替换。在本例中，批大小被定义为一个变量，将在脚本中的 ${vars.batch_size} 处添加。就像在 训练配置 中一样，您也可以在命令行上覆盖设置——例如使用 --vars.batch_size。

project.yml

您还可以使用 env 部分来引用环境变量并使其值可用于命令。这对于在命令行上覆盖设置和传递系统级设置非常有用。

project.yml

记录您的项目

当您的自定义项目准备好并希望与他人共享时，您可以使用 spacy project document 命令来自动生成一个漂亮的、Markdown 格式的 README 文件，该文件基于您的项目的 project.yml。它将列出项目中定义的所有命令、工作流程和资源，并包含有关如何运行该项目的详细信息，以及指向相关 spaCy 文档的链接，以便其他人可以轻松开始使用您的项目。

在底层，会添加隐藏标记来标识自动生成的内容的开始和结束位置。这意味着您可以在其之前或之后添加自己的自定义内容，并且重新运行 project document 命令将仅更新自动生成的部分。这使得保持文档的最新状态变得容易。

从您自己的仓库克隆

spacy project clone 命令允许您使用 --repo 选项自定义要克隆的仓库。它调用 git，因此您将能够克隆您有权访问的任何仓库，包括私有仓库。

最少情况下，有效的项目模板需要包含一个 project.yml。它还可以包含 其他文件，例如自定义脚本、列出其他依赖项的 requirements.txt、训练配置和模型元模板，或包含用法示例的 Jupyter Notebook。

远程存储

您可以使用 project push 命令将您的项目输出持久保存到远程存储。这可以帮助您导出您的管道包，共享与团队的工作，或缓存结果以避免重复工作。 project pull 命令将下载远程存储中的任何不可用的本地输出。

您可以在 project.yml 的 remotes 部分列出一个或多个远程仓库，方法是将字符串名称映射到存储的 URL。在底层，spaCy 使用 cloudpathlib 与远程存储进行通信，因此您可以使用 cloudpathlib 支持的任何协议，包括 S3、Google Cloud Storage 和本地文件系统，尽管您可能需要安装额外的依赖项才能使用某些协议。

project.yml

例如，假设您在 project.yml 中有以下命令

project.yml

完成训练后，您运行 project push 以确保将 training/model-best 输出保存到远程存储。然后，spaCy 将从您的命令脚本和列出的依赖项 corpus/train、corpus/dev 和 config.cfg 构建一个哈希，以识别输出的执行上下文。然后，它将计算 training/model-best 目录的 MD5 哈希，并使用这三条信息构建存储 URL。

如果您更改了命令或其依赖项之一（例如，通过编辑 config.cfg 文件来调整超参数），将计算不同的创建哈希，因此当您使用 project push 时，您将不会覆盖以前的文件。该系统甚至支持相同文件和相同上下文的多个输出，这可能会发生如果您的训练过程不是确定性的，或者如果您有未在命令中表示的依赖项。

总而言之，spacy project 远程存储旨在做出特定的权衡。优先考虑便利性、正确性和避免数据丢失。您可以自由地使用 project push，因为您永远不会覆盖远程状态，并且您不必提出名称或版本号。但是，您需要管理远程存储的大小，并删除不再与您相关的文件。

集成

数据版本控制 (DVC)

训练语料库或预训练权重等数据资源是任何 NLP 项目的核心，但它们通常难以管理：您不能只是将它们签入您的 Git 仓库进行版本控制和跟踪。如果您有相互依赖的多个步骤，例如生成训练数据的预处理步骤，则需要确保数据始终是最新的，并且每次都重新运行所有步骤，只是为了安全起见。

数据版本控制 (DVC) 是一种独立的开源工具，它集成到您的工作流程中，就像 Git 一样，为您的数据管道构建依赖关系图，并跟踪和缓存您的数据文件。如果您正在从外部来源（例如存储桶）下载数据，DVC 可以判断资源是否已更改。它还可以根据其输入是否已更改来确定是否重新运行步骤。所有元数据都可以签入 Git 仓库，因此您始终能够重现您的实验。

要设置 DVC，请安装该软件包并将您的 spaCy 项目初始化为 Git 和 DVC 仓库。您还可以 自定义您的 DVC 安装 以包含对 Google Cloud Storage、S3、Azure、SSH 等远程存储的支持。

“spacy project dvc”命令会根据“project.yml”中定义的工作流程创建一个“dvc.yaml”配置文件。每当您更新项目时，可以重新运行该命令来更新您的DVC配置。然后，您可以像管理任何其他DVC项目一样管理您的spaCy项目，运行dvc add来添加和跟踪资源，以及dvc repro来重现工作流程或单个命令。

Prodigy

Prodigy是由我们开发的，用于为机器学习模型创建训练数据的现代标注工具。它开箱即用地与spaCy集成，并为各种NLP任务提供许多不同的标注配方，无论有模型参与还是没有。如果您的项目中安装了Prodigy，您可以从“project.yml”启动标注服务器，从而在数据开发和训练之间建立紧密的反馈循环。

以下示例显示了一个用于合并和导出使用Prodigy收集的NER标注，以及训练spaCy管道的工作流程

project.yml

“train-curve”配方是您可以包含在项目中的另一个很棒的工作流程。它将使用不同比例的数据运行训练，例如25%、50%、75%和100%。一般来说，如果准确率在最后一个片段中增加，这可能表明收集更多相同类型的数据可以进一步改进模型。

project.yml (excerpt)

您可以为各种类型的项目和标注工作流程使用相同的方法，包括命名实体识别、跨度分类、文本分类、依存关系解析、词性标注或完全自定义配方。您还可以使用spaCy项目模板快速启动标注服务器，以收集更多标注并将其添加到您的Prodigy数据集中。

Streamlit

Streamlit是一个用于构建交互式数据应用程序的Python框架。spacy-streamlit包可帮助您将spaCy可视化集成到您的Streamlit应用程序中，并快速启动演示来交互式地探索您的管道。它包括一个完整的嵌入式可视化工具，以及各个组件。

使用spacy-streamlit，您的项目可以轻松定义自己的脚本，启动一个交互式可视化工具，使用您训练的最新管道，或选择管道以便比较它们的结果。

project.yml

以下脚本从“project.yml”调用，并接受两个位置命令行参数：一个加载管道的路径或包的逗号分隔列表，以及用作默认文本的示例文本。

explosion/projects/v3/integrations/streamlit/scripts/visualize.py

FastAPI

FastAPI是一个现代高性能的Python框架，用于构建REST API，基于Python类型提示。它已成为提供机器学习模型的流行库，您可以在spaCy项目中使用它来快速提供训练好的管道，并通过REST API使其可用。

project.yml

模板中包含的脚本显示了一个具有POST端点的简单REST API，该端点接受一批文本并返回一批预测结果，例如文档中找到的命名实体。类型提示和pydantic用于定义预期的数据类型。

explosion/projects/v3/integrations/fastapi/scripts/main.py

Weights & Biases

Weights & Biases是一个流行的实验跟踪平台。spaCy通过WandbLogger开箱即用地与其集成，您可以将其作为训练配置的[training.logger]块添加。然后，每个步骤的结果都会记录在您的项目中，以及完整的训练配置。这意味着每个超参数、注册函数名称和参数都将被跟踪，并且您将能够看到它对结果的影响。

Hugging Face Hub

“Hugging Face Hub”允许您上传模型并与他人共享。它将模型作为基于Git的存储库托管，这些存储库是包含所有文件的存储空间。它开箱即用地支持版本控制、分支和自定义元数据，并提供基于浏览器的可视化工具来交互式地探索您的模型，以及用于生产用途的API。spacy-huggingface-hub包会自动将huggingface-hub命令添加到您的spacyCLI（如果已安装）。

然后，您可以上传使用spacy package打包的任何管道。请确保设置--build wheel以输出二进制.whl文件。上传器将从管道包中读取所有元数据，包括自动生成的漂亮README.md和meta.json中可用的模型详细信息。有关示例，请查看我们上传的spaCy管道。

上传后，您将看到管道包的实时URL，以及您可以通过pip install安装的模型wheel的直接URL。您还可以从浏览器中交互式地测试您的管道

在您的“project.yml”中，您可以添加一个将训练好的打包管道上传到hub的命令。您可以将其作为手动步骤运行，也可以作为工作流程的一部分自动运行。确保在运行spacy package时设置--build wheel以构建管道包的wheel文件。

project.yml