无论你是spaCy的新手，还是只想温习一些NLP基础知识和实现细节——本页面都能满足你的需求。每个章节都会用简单的语言和示例或图示来解释spaCy的一项功能。部分章节还会在使用指南中重复出现，作为快速入门介绍。

什么是spaCy?

spaCy不是什么

• spaCy不是一个平台或"API"。与平台不同，spaCy不提供软件即服务或网络应用程序。它是一个开源库，旨在帮助你构建NLP应用，而不是一个可消费的服务。
• spaCy 不是一个开箱即用的聊天机器人引擎。虽然spaCy可以用于支持对话应用程序，但它并不是专门为聊天机器人设计的，仅提供基础的文本处理能力。
• spaCy不是研究软件。它基于最新研究构建，但设计初衷是为了解决实际问题。这导致其设计理念与NLTK或CoreNLP有显著不同——后两者是作为教学研究平台创建的。主要区别在于spaCy采用一体化设计且具有明确主张。spaCy尽量避免让用户在功能雷同的多个算法之间做选择。通过精简选项，spaCy能够提供更优的整体性能和开发者体验。
• spaCy不是一个公司。它是一个开源库。我们发布spaCy和其他软件的公司叫做Explosion。

功能

在文档中，您会遇到关于spaCy功能和特性的描述。其中一些涉及语言学概念，而另一些则与更通用的机器学习功能相关。

统计模型

虽然spaCy的部分功能可以独立运行，但其他功能需要加载训练好的管道，这些管道使spaCy能够预测语言注释——例如判断一个单词是动词还是名词。训练好的管道可能包含多个组件，这些组件使用基于标注数据训练的统计模型。spaCy目前为多种语言提供训练好的管道，这些管道可作为独立的Python模块安装。管道包在大小、速度、内存占用、准确性和包含的数据方面可能有所不同。您选择的包始终取决于您的具体用例和处理的文本内容。对于通用场景，小型默认包通常是不错的起点，它们通常包含以下组件：

• 二进制权重 用于词性标注器、依存关系解析器和命名实体识别器，以预测上下文中的这些标注。
• 词汇条目 在词汇表中，即单词及其上下文无关的属性，如形状或拼写。
• 数据文件 如词形还原规则和查找表。
• 词向量，即单词的多维语义表示，可让你判断它们之间的相似程度。
• 配置选项，例如语言和处理流水线设置以及要使用的模型实现，用于在加载流水线时将spaCy置于正确状态。

Linguistic annotations

spaCy提供多种语言注释，帮助您深入理解文本的语法结构。这包括词性标注（如词类划分）以及词语之间的关联关系。例如，在分析文本时，判断一个名词是句子的主语还是宾语会产生巨大差异——同样，"google"是被用作动词，还是在特定上下文中指代网站或公司名称，也会带来完全不同的解析结果。

当您下载并安装训练好的管道后，可以通过spacy.load加载它。这将返回一个包含处理文本所需所有组件和数据的Language对象。我们通常称它为nlp。在文本字符串上调用nlp对象将返回处理后的Doc：

可编辑代码spaCy v3.7 · Python 3 · 通过 Binder
run

尽管Doc经过处理——例如被分割成单个词语并添加注释——它仍然保留原始文本的所有信息，比如空格字符。你总是可以获取某个词符在原始字符串中的偏移量，或者通过连接词符及其尾部空格来重建原始文本。这种方式确保你在使用spaCy处理文本时永远不会丢失任何信息。

Tokenization

在处理过程中，spaCy首先会对文本进行分词，也就是将其分割成单词、标点符号等。这是通过应用针对每种语言的特定规则来完成的。例如，句子末尾的标点符号应该被分开——而"U.K."则应保持为一个词元。每个Doc由独立的词元组成，我们可以遍历它们：

可编辑代码spaCy v3.7 · Python 3 · 通过 Binder
run

首先，原始文本会按照空白字符进行分割，类似于text.split(' ')。然后，分词器会从左到右处理文本。对于每个子字符串，它会执行两项检查：

1. 子字符串是否匹配分词器异常规则？ 例如，"don't"不包含空格，但应拆分为两个词元"do"和"n't"，而"U.K."应始终保持为一个词元。

2. 能否拆分前缀、后缀或中缀？ 例如逗号、句号、连字符或引号等标点符号。

如果匹配成功，规则将被应用，分词器继续循环处理，从新分割的子字符串开始。这样，spaCy可以分割复杂、嵌套的标记，比如缩写组合和多个标点符号的组合。

虽然标点符号规则通常相当通用，但分词器异常强烈依赖于每种语言的具体特性。这就是为什么每种可用语言都有其自己的子类，如English或German，它们会加载硬编码数据和异常规则列表。

词性标注与依存关系 需要模型

在分词之后，spaCy可以对给定的Doc进行解析和标注。这时训练好的处理流程及其统计模型就会发挥作用，使spaCy能够预测在当前上下文中最可能适用的标签或标注。训练好的组件包含由系统通过学习足够多示例后生成的二进制数据，这些数据使其能够做出适用于整个语言的预测——例如，在英语中跟在"the"后面的单词很可能是名词。

语言注释可通过 Token属性获取。与许多NLP库类似，spaCy 将所有字符串编码为哈希值以减少内存使用并提高 效率。因此要获取属性的可读字符串表示形式，我们 需要在属性名称后添加下划线_：

可编辑代码spaCy v3.7 · Python 3 · 通过 Binder
run

使用spaCy内置的displaCy可视化工具，以下是我们示例句子及其依存关系的展示效果：

命名实体 需要模型

命名实体是指被赋予名称的"现实世界对象"，例如人物、国家、产品或书名。spaCy能够通过模型预测来识别文档中的各类命名实体。由于模型是基于统计的，且高度依赖其训练样本，因此效果并非总是完美，根据具体使用场景可能需要进行后续调整。

命名实体可以通过Doc的ents属性获取：

可编辑代码spaCy v3.7 · Python 3 · 通过 Binder
run

使用spaCy内置的displaCy可视化工具，以下是我们示例句子及其命名实体的展示效果：

词向量与相似度 需要模型

相似度是通过比较词向量或"词嵌入"来确定的，即词语的多维语义表示。词向量可以使用类似word2vec的算法生成，通常呈现如下形式：

banana.vector

内置词向量的Pipeline包使它们可以通过Token.vector属性获取。 Doc.vector和Span.vector默认会返回其词向量的平均值。您还可以检查一个词是否分配了向量，并获取L2范数（可用于向量归一化）。

可编辑代码spaCy v3.7 · Python 3 · 通过 Binder
run

单词"dog"、"cat"和"banana"在英语中都非常常见，因此它们是spacy词汇表的一部分，并且拥有对应的词向量。而单词"afskfsd"则非常罕见且属于词汇表外(OOV)词汇——所以它的向量表示由300维的0组成，这意味着它实际上不存在。如果您的应用程序需要更大的词汇量和更多向量，您应该考虑使用更大的spacy模型包或加载完整的词向量包，例如en_core_web_lg，它包含68.5万个独特向量。

spaCy能够比较两个对象，并预测它们的相似程度。预测相似度对于构建推荐系统或标记重复内容非常有用。例如，您可以向用户推荐与他们当前查看内容相似的资讯，或者当支持工单与已有工单高度相似时将其标记为重复。

每个Doc、Span、Token和 Lexeme都带有一个.similarity 方法，可用于与其他对象进行比较并确定 相似度。当然相似度总是主观的——两个词、片段 或文档是否相似实际上取决于您如何看待它。spaCy的 相似度实现通常采用一种相当通用的相似度定义。

可编辑代码spaCy v3.7 · Python 3 · 通过 Binder
run

相似度结果的预期

计算相似度分数在许多情况下都很有帮助，但对其能提供的信息保持现实的预期也很重要。词语之间可以通过多种方式相互关联，因此单一的"相似度"分数始终是不同信号的混合体，而且基于不同数据训练的向量可能产生差异很大的结果，这些结果可能并不符合您的需求。以下是需要牢记的一些重要考量因素：

• 相似性没有客观的定义。"我喜欢汉堡"和"我喜欢意大利面"是否相似取决于您的应用场景。两者都谈论食物偏好，这使得它们非常相似——但如果您在分析提及的食物时，这些句子就相当不同了，因为它们谈论的是完全不同的食物。
• Doc和Span对象的相似度默认采用平均词向量计算。这意味着"fast food"的向量是"fast"和"food"向量的平均值，这种计算方式不一定能准确反映短语"fast food"的含义。
• 向量平均意味着多个标记的向量对单词的顺序不敏感。两个用不同措辞表达相同含义的文档将返回较低的相似度分数，而两个恰好包含相同单词但表达不同含义的文档则会获得较高分数。

Pipelines

当你对文本调用nlp时，spaCy首先会对文本进行分词以生成Doc对象。然后Doc会经过多个不同步骤的处理——这也被称为处理管道。训练好的管道通常包含词性标注器、词形还原器、依存分析器和实体识别器。每个管道组件都会返回处理后的Doc对象，然后传递给下一个组件。

处理管道的能力始终取决于其组件、模型及训练方式。例如，一个命名实体识别管道需要包含训练好的命名实体识别器组件，该组件需配备统计模型和权重，使其能够预测实体标签。这就是为什么每个管道都会在config中指定其组件及配置：

架构

spaCy中的核心数据结构是Language类、Vocab和Doc对象。Language类用于处理文本并将其转换为Doc对象，通常存储为名为nlp的变量。Doc对象拥有词符序列及其所有标注。通过将字符串、词向量和词汇属性集中存储在Vocab中，我们避免了数据的多重存储。这节省了内存，并确保存在单一数据源。

文本标注的设计也遵循单一数据源原则：Doc对象拥有数据，而Span和Token是指向该数据的视图。Doc对象由Tokenizer构建，然后被流水线组件原地修改。Language对象负责协调这些组件，它接收原始文本并通过流水线处理，最终返回一个标注文档，同时还负责管理训练和序列化流程。

容器对象

处理流程

处理流程由一个或多个流程组件组成，这些组件按顺序在Doc上调用。分词器在组件之前运行。可以使用Language.add_pipe添加流程组件。它们可以包含统计模型和训练权重，或者仅对Doc进行基于规则的修改。spaCy为不同的语言处理任务提供了一系列内置组件，并允许添加自定义组件。

Matchers

匹配器(Matchers)帮助您根据描述目标序列的匹配模式，从Doc对象中查找和提取信息。匹配器在Doc上运行，并让您能在上下文中访问匹配到的词元。

其他类

Vocab, hashes and lexemes

在可能的情况下，spaCy会尝试将数据存储在词汇表Vocab中，该词汇表将被多个文档共享。为了节省内存，spaCy还会将所有字符串编码为哈希值——例如在这个例子中，"coffee"的哈希值是3197928453018144401。像"ORG"这样的实体标签和"VERB"这样的词性标签也会被编码。在内部，spaCy只"说"哈希值。

如果您处理大量包含单词“coffee”的文档，且这些文档涉及各种不同的上下文，那么每次都存储确切的字符串“coffee”会占用过多空间。因此，spaCy会对字符串进行哈希处理并将其存储在StringStore中。您可以将StringStore视为一个双向查找表——您可以通过字符串查找其哈希值，或通过哈希值查找对应的字符串：

可编辑代码spaCy v3.7 · Python 3 · 通过 Binder
run

现在所有字符串都已编码，词汇表中的条目不需要包含单词文本本身。相反，它们可以通过哈希值在StringStore中查找。词汇表中的每个条目，也称为Lexeme，包含了单词的上下文无关信息。例如，无论"love"在某个上下文中是作为动词还是名词使用，其拼写和是否由字母字符组成都不会改变。它的哈希值也将始终保持不变。

可编辑代码spaCy v3.7 · Python 3 · 通过 Binder
run

单词到哈希值的映射不依赖于任何状态。为确保每个值都是唯一的，spaCy使用哈希函数来基于单词字符串计算哈希值。这也意味着无论您使用哪个流程或如何配置spaCy，"coffee"的哈希值始终相同。

然而，哈希值无法被逆向还原，无法将3197928453018144401重新解析为"coffee"。spaCy唯一能做的是在词汇表中查找它。这就是为什么你必须确保创建的所有对象都能访问相同的词汇表。如果无法做到这一点，spaCy可能无法找到所需的字符串。

可编辑代码spaCy v3.7 · Python 3 · 通过 Binder
run

如果词汇表中不包含字符串3197928453018144401，spaCy会报错。你可以手动重新添加"coffee"这个词，但这仅在你确实知道文档包含该词时才有效。为避免这个问题，当你保存Doc或nlp对象时，spaCy也会导出Vocab。这将为你提供对象及其编码注释，以及解码所需的"密钥"。

序列化

如果您一直在修改管道、词汇表、向量和实体，或更新组件模型，最终会希望保存进度——例如nlp对象中的所有内容。这意味着需要将其内容和结构转换为可保存的格式，如文件或字节字符串。这个过程称为序列化。spaCy提供内置序列化方法并支持Pickle协议。

所有容器类，即 Language (nlp), Doc, Vocab 和 StringStore 都提供以下方法：

训练

spaCy的标注器、解析器、文本分类器等众多组件都由统计模型驱动。这些组件做出的每个"决策"——例如分配什么词性标签，或判断一个词是否为命名实体——都是基于模型当前权重值的预测结果。权重值是根据模型在训练过程中见过的样本估算得出的。要训练模型，首先需要训练数据——文本样本以及希望模型预测的标签。这些标签可以是词性标注、命名实体或任何其他信息。

训练是一个迭代过程，在此过程中将模型的预测结果与参考标注进行比较，以估计损失梯度。然后通过反向传播利用损失梯度计算权重梯度。这些梯度指示应如何调整权重值，使模型的预测随时间推移逐渐接近参考标签。

在训练模型时，我们不仅希望它能记住我们的示例，更希望它能形成一套可以推广到未见数据的理论。毕竟，我们不只想让模型学会眼前这个"Amazon"实例是家公司，而是希望它能理解在类似这样的上下文中，"Amazon"极有可能指代公司。因此训练数据必须始终能代表我们想要处理的数据类型。一个基于维基百科训练的模型（其中第一人称句子极为罕见）在推特数据上可能表现糟糕。同样地，用言情小说训练的模型在法律文本上也可能表现不佳。

这也意味着，为了了解模型的表现以及它是否在学习正确的内容，你不仅需要训练数据——还需要评估数据。如果只用训练数据来测试模型，你将无法知道它的泛化能力如何。如果想从头开始训练一个模型，通常至少需要几百个训练和评估样本。

训练配置与生命周期

训练配置文件包含训练流程所需的全部设置和超参数。您无需在命令行提供大量参数，只需将config.cfg文件传递给spacy train。这也便于集成用您选择的框架编写的自定义模型和架构。管道的config.cfg文件被视为"唯一真实来源"，无论是在训练还是运行时。

可训练组件

spaCy的Pipe类可帮助您实现自定义的可训练组件，这些组件拥有自己的模型实例，能对Doc对象进行预测，并可通过spacy train进行更新。这使您能够将完全定制的机器学习组件接入流程中，这些组件可通过单一训练配置进行设置。

语言数据

每种语言都有所不同——通常充满了例外情况和特殊规则，尤其是在最常用的词汇中。其中一些例外是跨语言共通的，而另一些则完全特定于某种语言——通常特定到需要硬编码处理。lang模块包含了所有语言特定的数据，这些数据以简单的Python文件形式组织，便于更新和扩展。

目录根目录中的共享语言数据包含可跨语言通用的规则——例如基本标点符号、表情符号、表情图和单字母缩写的规则。子模块中的特定语言数据包含仅与特定语言相关的规则。它还负责整合所有组件并创建Language子类——例如English或German。这些值在Language.Defaults中定义。

社区与常见问题

我们非常高兴看到spaCy社区不断发展壮大，吸引了来自各种不同背景的成员——包括计算语言学、数据科学、深度学习、研究等领域。如果您想参与其中，以下是一些重要问题的解答以及进一步阅读的资源。

Help, my code isn’t working!

Bug很烦人，我们正在尽最大努力持续改进测试并尽快修复问题。在提交问题之前，请先快速搜索并检查该问题是否已被报告。如果您遇到安装或加载问题，请务必查看故障排除指南。spaCy的帮助可通过以下平台获取：

• Stack Overflow: 使用问题以及所有与您特定代码问题相关的内容。Stack Overflow社区比我们的社区大得多，因此如果其他人能解决您的问题，您将更快获得帮助。
• GitHub discussions: 一般讨论、项目构想和使用问题。与其他社区成员交流，获取具体代码实现的帮助，讨论新项目/插件的想法，支持更多语言，并分享最佳实践。
• GitHub issue tracker: Bug reports 和 改进建议, 即所有可能是spaCy的问题。这还包括训练管道中超出统计误差范围的问题，比如指向bug的模式。

如何为spaCy做贡献？

您不需要成为NLP专家或Python高手即可参与贡献，我们很乐意帮助您入门。如果您是spaCy的新手，可以从GitHub上的help wanted (easy)标签开始，我们用它来标记那些简单且独立的问题和功能请求。我们也欢迎对文档的贡献——无论是修正拼写错误、改进示例还是添加额外说明。您会在每页底部找到一个"建议编辑"链接，它将引导您到源代码。

另一种参与方式是帮助我们改进 语言数据——尤其是当您 恰好会说当前处于 alpha支持阶段的某种语言时。即使是添加简单的分词器 例外情况、停用词或词形还原数据也能产生重大影响。这还将 使我们未来更容易为该语言提供训练好的处理流程。提交记录错误或性能问题的测试用例， 或覆盖对您的应用特别重要的功能也非常 有帮助。通过这种方式，您还能确保我们永远不会意外地对您最关心的库部分 引入回归问题。

如需了解更多关于我们寻求的贡献类型、代码规范和其他实用建议，请务必查阅贡献指南。

我用spaCy构建了一个很酷的东西——如何让更多人知道？

首先，恭喜你——我们很乐意查看你的作品！如果你认为自己的项目适合加入spaCy Universe，欢迎随时提交！教程对其他用户也极具价值，是获得曝光的好方法。因此我们强烈建议撰写你的经验分享，或在博客上分享代码及实用技巧。由于我们的网站是开源的，你可以通过GitHub提交pull request来添加你的项目或教程。

如果您想在网站上使用spaCy徽标，请先联系我们并征得许可。不过，如果您想表示支持并告知他人您的项目正在使用spaCy，可以在此获取我们的spaCy徽章：