spaCy + Stanza（原名 StanfordNLP）

本包封装了 Stanza（原名 StanfordNLP）库，使您能够在 spaCy 管道中使用斯坦福的模型。斯坦福模型在 CoNLL 2017 和 2018 共享任务中取得了最高准确率，该任务涉及 68 种语言的分词、词性标注、形态学分析、词形还原以及带标签的依存句法分析。自 v1.0 起，Stanza 还支持部分语言的命名实体识别。

⚠️ 此软件包的早期版本曾以 spacy-stanfordnlp 的名义发布。

通过此封装器，您可以利用由预训练的 stanza 模型计算出的以下注释：

• 统计分词（反映在 Doc 及其标记中）
• 词形还原（token.lemma 和 token.lemma_）
• 词性标注（token.tag、token.tag_、token.pos、token.pos_）
• 形态学分析（token.morph）
• 依存句法分析（token.dep、token.dep_、token.head）
• 命名实体识别（doc.ents、token.ent_type、token.ent_type_、token.ent_iob、token.ent_iob_）
• 句子分割（doc.sents）

️️️⌛️ 安装

自 v1.0.0 起，spacy-stanza 仅与 spaCy v3.x 兼容。要安装最新版本：

pip install spacy-stanza

对于 spaCy v2，请安装 v0.2.x 版本，并参考 v0.2.x 使用文档：

pip install "spacy-stanza<0.3.0"

请务必同时 下载 一个 预训练的 Stanza 模型。

📖 使用与示例

⚠️ 重要提示： 本包已重构，以充分利用 spaCy v3.0 的功能。先前为 spaCy v2.x 构建的版本工作方式有很大不同。有关旧版本的文档，请参阅此 README 的先前标记版本。

使用 spacy_stanza.load_pipeline() 创建一个 nlp 对象，可用于通过 Stanza 管道处理文本并生成 spaCy Doc 对象。默认情况下，spaCy 管道和 Stanza 管道将使用相同的 lang 初始化，例如“en”：

import stanza
import spacy_stanza

# 如有必要，下载 Stanza 模型
stanza.download("en")

# 初始化管道
nlp = spacy_stanza.load_pipeline("en")

doc = nlp("巴拉克·奥巴马出生于夏威夷。他于2008年当选总统。")
for token in doc:
    print(token.text, token.lemma_, token.pos_, token.dep_, token.ent_type_)
print(doc.ents)

如果给定语言的语言数据在 spaCy 中可用，则可以使用相应的语言类作为 nlp 对象的基础——例如， English()。这使您可以使用 spaCy 的词汇属性，如 is_stop 或 like_num。nlp 对象遵循与其他 spaCy Language 类相同的 API——因此，您可以使用 displaCy 可视化 Doc 对象，向管道添加自定义组件，使用基于规则的匹配器，以及执行几乎所有通常在 spaCy 中进行的操作。

# 访问 spaCy 的词汇属性
print([token.is_stop for token in doc])
print([token.like_num for token in doc])

# 可视化依存关系
from spacy import displacy
displacy.serve(doc)  # 或者如果您在 Jupyter 笔记本中，可以使用 displacy.render

# 使用 nlp.pipe 处理文本
for doc in nlp.pipe(["大量文本", "更多文本", "..."]):
    print(doc.text)

# 结合您自己的自定义管道组件
from spacy import Language
@Language.component("custom_component")
def custom_component(doc):
    # 在此处对 doc 执行某些操作
    print(f"自定义组件被调用：{doc.text}")
    return doc

nlp.add_pipe("custom_component")
doc = nlp("一些文本")

# 将属性序列化为 numpy 数组
np_array = doc.to_array(['ORTH', 'LEMMA', 'POS'])

Stanza 管道选项

可以根据 Stanza Pipeline API 提供额外的选项作为关键字参数：

• 使用 lang 参数指定 Stanza 语言。对于没有 spaCy 支持的语言，可在 spaCy 语言设置中使用“xx”：

  # 初始化科普特语管道
  nlp = spacy_stanza.load_pipeline("xx", lang="cop")
  

• 根据 Stanza Pipeline API 提供 Stanza 管道设置：

  # 使用 `hdt` 包初始化德语管道
  nlp = spacy_stanza.load_pipeline("de", package="hdt")
  

• 使用 spaCy 分词而非统计分词器（仅适用于英语）：

  nlp = spacy_stanza.load_pipeline("en", processors= {"tokenize": "spacy"})
  

• 提供任何其他处理器设置作为额外的关键字参数：

  # 提供预分词文本（按空格分词）
  nlp = spacy_stanza.load_pipeline("de", tokenize_pretokenized=True)
  

spaCy 配置会在 [nlp.tokenizer] 块中指定所有 Pipeline 选项。例如，上述最后一个示例的配置——带有预分词文本的德语管道：

[nlp.tokenizer]
@tokenizers = "spacy_stanza.PipelineAsTokenizer.v1"
lang = "de"
dir = null
package = "default"
logging_level = null
verbose = null
use_gpu = true

[nlp.tokenizer.kwargs]
tokenize_pretokenized = true

[nlp.tokenizer.processors]

序列化

完整的 Stanza 管道配置存储在 spaCy 管道的 配置文件 中，因此您可以像保存和加载任何其他 nlp 管道一样保存和加载该管道：

# 保存到本地目录
nlp.to_disk("./stanza-spacy-model")

# 重新加载管道
nlp = spacy.load("./stanza-spacy-model")

请注意，默认情况下不会保存任何 Stanza 模型数据。由于 Stanza 模型体积较大，目前本包要求您使用 stanza.download() 单独下载模型，并将其放置在默认模型目录或配置中 [nlp.tokenizer.dir] 指定的路径中。

添加额外的 spaCy 管道组件

默认情况下，由 spacy_stanza.load_pipeline() 返回的 nlp 对象中的 spaCy 管道是空的，这是因为所有 stanza 属性都在自定义分词器 StanzaTokenizer 中计算并设置。不过，由于它是一个普通的 nlp 对象，你可以向管道中添加自己的组件。例如，你可以使用 nlp.add_pipe("textcat", source=source_nlp) 添加你自己的自定义文本分类组件，或者利用EntityRuler 组件基于规则模式扩展命名实体识别结果。

spacy-stanza 快速上手指南

spacy-stanza 是一个桥接工具，允许你在 spaCy 管道中使用斯坦福大学开发的 Stanza（原 StanfordNLP）模型。它结合了 Stanza 在 68 种语言中顶尖的准确率（涵盖分词、词性标注、形态分析、依存句法分析和命名实体识别）与 spaCy 强大的工程化能力。

环境准备

• Python 版本：建议 Python 3.7+
• 核心依赖：
  • spaCy v3.x：本工具 v1.0.0+ 仅兼容 spaCy v3 系列。
  • Stanza：需要安装 Stanza 库并下载对应的预训练模型。
• 系统要求：支持 Linux、macOS 和 Windows。若需使用 GPU 加速，请确保已安装 CUDA 及对应的 PyTorch GPU 版本。

安装步骤

1. 安装 spacy-stanza

使用 pip 安装最新稳定版：

pip install spacy-stanza

注意：如果你仍在使用 spaCy v2.x，请安装旧版本：pip install "spacy-stanza<0.3.0"，但强烈建议升级至 spaCy v3。

2. 下载 Stanza 预训练模型

在使用前，必须通过 Stanza 官方接口下载对应语言的模型数据（例如英语 en）：

import stanza
stanza.download("en")

提示：国内开发者若下载缓慢，可检查网络环境或配置代理，Stanza 模型文件较大，首次下载需耐心等待。

基本使用

初始化管道

使用 spacy_stanza.load_pipeline() 创建 nlp 对象。默认情况下，spaCy 和 Stanza 会使用相同的语言代码（如 "en"）。

import stanza
import spacy_stanza

# 确保已下载模型，若未下载请取消下一行注释
# stanza.download("en")

# 初始化管道
nlp = spacy_stanza.load_pipeline("en")

# 处理文本
doc = nlp("Barack Obama was born in Hawaii. He was elected president in 2008.")

# 输出每个词的详细标注信息
for token in doc:
    print(token.text, token.lemma_, token.pos_, token.dep_, token.ent_type_)

# 输出识别到的实体
print(doc.ents)

结合 spaCy 高级功能

生成的 doc 对象完全兼容 spaCy API，你可以直接使用词汇属性、可视化依赖关系或添加自定义组件：

# 使用 spaCy 内置词汇属性
print([token.is_stop for token in doc])  # 判断是否为停用词
print([token.like_num for token in doc]) # 判断是否为数字

# 可视化依存句法树
from spacy import displacy
displacy.serve(doc)  # 在浏览器中查看，或在 Jupyter 中使用 displacy.render(doc)

# 批量处理文本
texts = ["Lots of texts", "Even more texts", "..."]
for doc in nlp.pipe(texts):
    print(doc.text)

# 添加自定义组件
from spacy import Language

@Language.component("custom_component")
def custom_component(doc):
    print(f"Custom component called: {doc.text}")
    return doc

nlp.add_pipe("custom_component")
doc = nlp("Some text")

保存与加载

你可以像标准 spaCy 模型一样保存管道配置（注意：默认不保存庞大的 Stanza 模型文件，加载时需确保本地已存在对应模型）：

# 保存到本地目录
nlp.to_disk("./stanza-spacy-model")

# 重新加载
nlp = spacy.load("./stanza-spacy-model")