spacy-streamlit: 用于 Streamlit 应用的 spaCy 构建模块

此包包含用于可视化 spaCy 模型以及使用 Streamlit 构建交互式 spaCy 驱动应用的实用工具。它提供了多种构建模块，你可以在自己的 Streamlit 应用中使用，例如针对句法依存关系、命名实体、文本分类、通过词向量实现的语义相似度、标记属性等的可视化组件。

🚀 快速入门

你可以通过 pip 安装 spacy-streamlit：

pip install spacy-streamlit

该包包含调用 Streamlit 并为你设置所有必要元素的构建模块。你可以直接使用各个组件，并将其与其他应用元素结合，或者调用 visualize 函数来嵌入整个可视化工具。

首先从 spaCy 下载英语模型以开始使用。

python -m spacy download en_core_web_sm

然后将以下示例代码放入一个文件中。

# streamlit_app.py
import spacy_streamlit

models = ["en_core_web_sm", "en_core_web_md"]
default_text = "Sundar Pichai 是 Google 的 CEO。"
spacy_streamlit.visualize(models, default_text)

之后，你可以使用 streamlit run streamlit_app.py 运行你的应用。应用应该会在你的网页浏览器中弹出。😀

📦 示例：01_out-of-the-box.py

直接使用内置可视化工具，并自定义设置。

streamlit run https://raw.githubusercontent.com/explosion/spacy-streamlit/master/examples/01_out-of-the-box.py

👑 示例：02_custom.py

在现有应用中使用单独的组件。

streamlit run https://raw.githubusercontent.com/explosion/spacy-streamlit/master/examples/02_custom.py

🎛 API

可视化组件

这些函数可以在你的 Streamlit 应用中使用。它们在底层调用 streamlit，并设置所需的元素。

function visualize

嵌入包含所选组件的完整可视化工具。

import spacy_streamlit

models = ["en_core_web_sm", "/path/to/model"]
default_text = "Sundar Pichai 是 Google 的 CEO。"
visualizers = ["ner", "textcat"]
spacy_streamlit.visualize(models, default_text, visualizers)

参数	类型	描述
models	List[str] / Dict[str, str]	可加载的 spaCy 模型名称（路径或包名）。这些模型可通过下拉菜单选择。可以是名称列表，也可以是名称与在下拉菜单中显示的描述的映射关系。
default_text	str	加载时要分析的默认文本。默认值为 ""。
default_model	Optional[str]	默认模型的可选名称。如果未设置，则使用 models 列表中的第一个模型。
visualizers	List[str]	要显示的可视化工具名称。默认值为 ["parser", "ner", "textcat", "similarity", "tokens"]。
ner_labels	Optional[List[str]]	要包含的 NER 标签。如果未设置，则会使用 "ner" 管道组件中所有存在的标签。
ner_attrs	List[str]	在命名实体表格中显示的 Span 属性。默认值请参阅 visualizer.py。
token_attrs	List[str]	在词元可视化工具中显示的词元属性。默认值请参阅 visualizer.py。
similarity_texts	Tuple[str, str]	相似度可视化工具中用于比较的默认文本。默认值为 ("apple", "orange")。
show_json_doc	bool	显示切换 Doc 的 JSON 表示形式的按钮。默认值为 True。
show_meta	bool	显示切换当前管道的 meta.json 的按钮。默认值为 True。
show_config	bool	显示切换当前管道的 config.cfg 的按钮。默认值为 True。
show_visualizer_select	bool	显示侧边栏下拉菜单，用于选择要显示的可视化工具（基于已启用的可视化工具）。默认值为 False。
sidebar_title	Optional[str]	侧边栏中显示的标题。默认值为 None。
sidebar_description	Optional[str]	侧边栏中显示的描述。支持 Markdown 格式的文本。
show_logo	bool	在侧边栏中显示 spaCy 徽标。默认值为 True。
color	Optional[str]	实验性：用于部分主要 UI 元素的主色调（设置为 None 可禁用此功能）。默认值为 "#09A3D5"。
get_default_text	Callable[[Language], str]	可选的可调用函数，接收当前加载的 nlp 对象并返回默认文本。可用于提供特定语言的默认文本。如果该函数返回 None，则使用 default_text 的值（如果有）。默认值为 None。

函数 visualize_parser

使用 spaCy 的 displacy 可视化工具可视化依存句法分析和词性标注。

import spacy
from spacy_streamlit import visualize_parser

nlp = spacy.load("en_core_web_sm")
doc = nlp("This is a text")
visualize_parser(doc)

参数	类型	描述
doc	Doc	要可视化的 spaCy Doc 对象。
仅限关键字
title	Optional[str]	可视化组件的标题。
key	Optional[str]	用于 Streamlit 组件选择标签的键。
manual	bool	标志位，指示 doc 参数是 Doc 对象，还是包含解析信息的字典列表。
displacy_options	Optional[Dict]	传递给 displacy 渲染方法以生成要渲染的 HTML 的选项字典。请参阅：https://spacy.io/api/top-level#options-dep

函数 visualize_ner

使用 spaCy 的 displacy 可视化工具可视化 Doc 中的命名实体。

import spacy
from spacy_streamlit import visualize_ner

nlp = spacy.load("en_core_web_sm")
doc = nlp("Sundar Pichai is the CEO of Google.")
visualize_ner(doc, labels=nlp.get_pipe("ner").labels)

参数	类型	描述
doc	Doc	要可视化的 spaCy Doc 对象。
仅限关键字
labels	Sequence[str]	在标签下拉菜单中显示的标签。
attrs	List[str]	在实体表格中显示的跨度属性。
show_table	bool	是否显示实体及其属性的表格。默认为 True。
title	Optional[str]	可视化组件的标题。
colors	Dict[str,str]	用于可视化实体跨度的颜色字典，键为标签，值为对应颜色。此参数即将弃用。未来颜色参数将需要通过 displacy_options 参数中的 "colors" 键来传递。)
key	Optional[str]	用于 Streamlit 组件选择标签的键。
manual	bool	标志位，指示 doc 参数是 Doc 对象，还是包含实体跨度信息的字典列表。
displacy_options	Optional[Dict]	传递给 displacy 渲染方法以生成要渲染的 HTML 的选项字典。请参阅 https://spacy.io/api/top-level#displacy_options-ent。

函数 visualize_spans

使用 spaCy 的 displacy 可视化工具可视化 Doc 中的跨度。

import spacy
from spacy_streamlit import visualize_spans

nlp = spacy.load("en_core_web_sm")
doc = nlp("Sundar Pichai is the CEO of Google.")
span = doc[4:7]  # CEO of Google
span.label_ = "CEO"
doc.spans["job_role"] = [span]
visualize_spans(doc, spans_key="job_role", displacy_options={"colors": {"CEO": "#09a3d5"}})

参数	类型	描述
doc	Doc	要可视化的 spaCy Doc 对象。
仅关键字
spans_key	序列[str]	从哪个 spans 键渲染实体跨度。默认值为 "sc"。
attrs	列表[str]	实体 Span 上要标注的属性。只有当 show_table 参数为 True 时，才会显示这些属性。
show_table	布尔值	是否显示实体跨度及其属性的表格。默认值为 True。
title	可选[str]	可视化模块的标题。
manual	布尔值	标志参数，用于指示 doc 参数是 Doc 对象，还是包含实体跨度信息的字典列表。
displacy_options	可选[字典]	传递给 displacy 渲染方法以生成待渲染 HTML 的选项字典。请参阅 https://spacy.io/api/top-level#displacy_options-span。

函数 visualize_textcat

可视化由训练好的文本分类器预测出的文本类别。

import spacy
from spacy_streamlit import visualize_textcat

nlp = spacy.load("./my_textcat_model")
doc = nlp("这是一篇关于某个主题的文章")
visualize_textcat(doc)

参数	类型	描述
doc	Doc	要可视化的 spaCy Doc 对象。
仅关键字
title	可选[str]	可视化模块的标题。

visualize_similarity

使用模型的词向量可视化语义相似度。如果模型中没有词向量，则会显示警告。

import spacy
from spacy_streamlit import visualize_similarity

nlp = spacy.load("en_core_web_lg")
visualize_similarity(nlp, ("pizza", "fries"))

参数	类型	描述
nlp	Language	包含词向量的已加载 nlp 对象。
default_texts	元组[str, str]	加载时默认比较的文本对。默认值为 ("apple", "orange")。
仅关键字
threshold	浮点数	判断“相似”的阈值。如果相似度得分高于该阈值，则结果被视为相似。默认值为 0.5。
title	可选[str]	可视化模块的标题。

函数 visualize_tokens

可视化 Doc 中的各个标记及其属性。

import spacy
from spacy_streamlit import visualize_tokens

nlp = spacy.load("en_core_web_sm")
doc = nlp("这是一段文字")
visualize_tokens(doc, attrs=["text", "pos_", "dep_", "ent_type_"])

参数	类型	描述
doc	Doc	要可视化的 spaCy Doc 对象。
仅关键字
attrs	列表[str]	要使用的标记属性名称。默认设置请参阅 visualizer.py。
title	可选[str]	可视化模块的标题。

缓存助手

这些助手尝试缓存已加载的模型和创建的 Doc 对象。

函数 process_text

使用给定名称的模型处理文本，并创建一个 Doc 对象。该函数会调用 load_model 助手来加载模型。

import streamlit as st
from spacy_streamlit import process_text

spacy_model = st.sidebar.selectbox("模型名称", ["en_core_web_sm", "en_core_web_md"])
text = st.text_area("待分析文本", "这是一段文本")
doc = process_text(spacy_model, text)

参数	类型	描述
model_name	str	可加载的 spaCy 模型名称。可以是路径或包名。
text	str	待处理的文本。
返回值	Doc	处理后的文档。

函数 load_model

从路径或已安装的包中加载 spaCy 模型，并返回一个已加载的 nlp 对象。

import streamlit as st
from spacy_streamlit import load_model

spacy_model = st.sidebar.selectbox("模型名称", ["en_core_web_sm", "en_core_web_md"])
nlp = load_model(spacy_model)

参数	类型	描述
name	str	可加载的 spaCy 模型名称。可以是路径或包名。
返回值	Language	已加载的 nlp 对象。

spacy-streamlit 快速上手指南

spacy-streamlit 是一个用于在 Streamlit 应用中可视化 spaCy 模型并构建交互式 NLP 应用的工具包。它提供了语法依赖、命名实体识别 (NER)、文本分类、语义相似度等组件的现成可视化模块。

环境准备

• 系统要求：支持 Python 3.8+ 的操作系统（Windows, macOS, Linux）。
• 前置依赖：
  • Python 环境
  • pip 包管理工具
  • 已安装的 spaCy 库（安装本工具时通常会自动处理，但建议确保环境正常）

安装步骤

1. 安装 spacy-streamlit 使用 pip 安装主程序包。国内用户推荐使用清华或阿里镜像源以加速下载：

   pip install spacy-streamlit -i https://pypi.tuna.tsinghua.edu.cn/simple
   

2. 下载 spaCy 语言模型 为了演示功能，需要下载一个基础的英语模型（如 en_core_web_sm）：

   python -m spacy download en_core_web_sm
   

   (注：如果下载速度慢，可尝试手动下载 .whl 文件后本地安装，或配置 pip 全局镜像源)

基本使用

以下是最简单的“开箱即用”示例，它将创建一个包含模型选择器、文本输入框以及多种可视化视图（依存句法、实体、分类等）的完整应用。

1. 创建应用文件 新建一个名为 streamlit_app.py 的文件，并填入以下代码：

   # streamlit_app.py
   import spacy_streamlit
   
   # 定义可用的模型列表
   models = ["en_core_web_sm", "en_core_web_md"]
   # 设置默认分析文本
   default_text = "Sundar Pichai is the CEO of Google."
   
   # 启动可视化组件
   spacy_streamlit.visualize(models, default_text)
   

2. 运行应用 在终端中执行以下命令启动 Streamlit 服务：

   streamlit run streamlit_app.py
   

3. 查看结果 命令执行后，浏览器会自动打开一个新标签页显示应用界面。你可以在侧边栏切换模型，或在主界面输入文本，实时查看 spaCy 的分析结果（如高亮的实体、依存关系图等）。