流程：改造spaCy文档——增量：文档篇

让文档满足需求迥异的用户是一项挑战。以下是spaCy（一个用于自然语言处理的开源库）的实现方案。

跨学科开发者的包容

spaCy用户群体最显著的特点是背景多样性。我们唯一能确定的共同点是：他们都想处理文本。其中包括不关心Python生态的语言学家、刚接触机器学习的资深Python程序员、从未深入思考语言学的机器学习工程师、大型企业中专注扩展性的开发者，以及主要在浏览器中使用Jupyter Notebook的数据科学家。

为支持多元化受众，文档需从不同视角（语言学家、程序员、数据科学家等）出发，并采用多种媒体形式。部分用户需要解释基础概念的入门指南，另一部分用户则偏好直接查看上下文中的端到端示例脚本。同一用户在不同场景下也可能需要不同类型的文档——有时需要宏观概览以确定问题解决方向，有时则需要特定功能的具体说明。

应对不可预测性的用户引导

当前多数机器学习系统依赖监督学习：通过标注的输入输出对训练程序，使其能对新数据执行类似计算。这种被某AI机构研究员称为"软件2.0"的范式（通过示例数据编程）为文档编写带来新挑战：传统函数可标注预期输入输出，但统计模型的行为并非完全可预测。

许多开发者使用预训练模型处理文本时，若输入文本与训练数据相似则效果良好。但基于报纸文本训练的模型在推特内容上可能表现不佳，五年前训练的模型可能从未见过"Tinder"（2012年发布）或"Snapchat"（2011年发布）。随着媒体环境持续变化，这些预训练模型也会面临挑战。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

import spacy

# 加载英语统计模型
nlp = spacy.load('en_core_web_sm')

# 处理文本字符串并创建文档对象
doc = nlp(u"The hysterical concern over how to pay for Bernie's plans is hilarious")

# 遍历统计模型预测的命名实体
for ent in doc.ents:
  print('发现实体:', ent.text, ent.label_)

# 输出: 发现实体: Bernie ORG

命名实体是被赋予名称的"真实世界对象"（如人物、国家或组织）。spaCy的统计模型可根据上下文预测这些名称。此例中模型将"Bernie"预测为组织（ORG）显然错误，但替换为"Sony"则合理，替换为"Bezos"时能正确预测为人名。

机器学习具有高度实验性，从业者并不总能确切知晓操作原理。因此文档不仅需要说明模型在正确预测时的预期输出，还需提供以下指导：模型在何种文本上表现最佳、如何设计应用以减轻错误影响，以及如何针对特定用例提升模型精度。

模型精度评估

模型精度描述其在给定条件下预测正确的频率。NLP算法的"经典"评估通常基于1989年《华尔街日报》文章组成的Penn Treebank语料库。虽然这有助于研究者在相同数据上基准测试系统，但该语料库与现实用例相距甚远。为此我们既提供标准学术基准，也对从原始文本到个体预测的完整处理流程进行现代评估。

为突破黑盒模式，我们特别注重帮助开发者针对自身用例定制模型。训练文档的编写颇具挑战：当训练效果不佳时，难以立即判断问题是出自用户执行的代码、尝试的设置还是提供的示例。由于训练是实验性和迭代性的，用户需要理解所做选择与获得结果之间的逻辑关系——重点在于提供概念框架而非解决具体问题。

改进spaCy的错误和警告系统极大帮助了训练过程的信息输出。在NLP和机器学习领域，解决方案通常是增加训练所用标注示例的数量或质量，这正是我们开发标注工具Prodigy的原因。

跨Python版本与平台的个性化入门

Python已成为机器学习和数据科学最受欢迎的语言，其丰富的开源生态系统备受开发者推崇。Jupyter等项目通过浏览器内笔记本实现代码开发与共享，相关开源交互计算技术显著提升了生产效率，使开发者减少环境配置时间。

但库的安装始终存在困难。为支持最多开发者，我们需兼容常见配置、操作系统、包管理器和Python版本。跨平台支持的代价是必须编写具有细微差异的矩阵式安装说明。线性安装文档对此效果不佳——当开发者发现新库急于尝试时，最不愿阅读冗长的平台说明和注意事项。

1
2
3
4
5

python -m pip install -U virtualenv
virtualenv .env
source .env/bin/activate
pip install -U spacy
python -m spacy download en

为帮助用户快速找到正确安装命令，我们开发了可嵌入文档的交互式小组件（受PyTorch"快速开始"章节启发）。但spaCy作为高性能Python库使用Cython编写（Python与C/C++的混合体），用户需下载预编译版本或本地编译。若系统未预装编译器，可能陷入C++构建工具和gcc错误的困境。

安装过程往往成为用户使用新库时的首道障碍，这不仅造成不良初体验，更将不熟悉包管理器、编译器或Python环境的新开发者拒之门外。

实现动态交互式文档

软件和应用越抽象，越难想象使用示例如何应用于独特场景。教计算机识别动物很有趣，但这如何帮助分析法律文档？在德语或法语中又会如何呈现？

为满足用户多样化需求，我们致力于使文档具备足够灵活性。最佳学习方式是通过复制、修改、运行示例并观察结果。Web技术在此具有明显优势：不同于Python，它们可在浏览器中原生运行。虽然让网站执行Python十分困难——不仅需要Python解释器，还需预装spaCy及其模型包，且必须为每个用户提供隔离环境。

通过以下技术栈实现突破：

• Jupyter Notebook：创建和共享含实时代码文档的开源Web应用
• Jupyter Kernel：在Jupyter环境中运行和检查用户代码的内置程序
• JupyterLab：新一代基于Web的Jupyter用户界面
• JupyterHub：用于启动和管理多实例的多用户服务器
• BinderHub：从GitHub仓库构建Docker镜像并连接至JupyterHub的开源工具
• Binder：即用型公共BinderHub部署

最终我们选择Binder和BinderHub方案：基于GitHub仓库构建依赖项的Docker镜像，按需启动新实例。每个用户获得独立环境，可通过Jupyter内核执行Python代码。这不仅支持在笔记本中操作，还能直接连接内核、发送待运行代码字符串、接收输出并在网站渲染。由此实现了大多数代码示例的可执行和可编辑化。

1
2
3
4
5
6
7

# 通过Binder在浏览器中执行代码
import spacy

nlp = spacy.load('en_core_web_sm')   # 加载spaCy模型
doc = nlp(u"This is a sentence.")    # 处理文本
for token in doc:
    print(token.text, token.pos_)    # 打印单词及其词性标注

通过juniper.js库连接Binder的交互式代码组件，使spaCy的多样化交互文档成为可能。借助现代Web技术，我们已远离旧式软件手册时代。通过探索实验更好的文档生产方式——识别用户独特用例并理解其特定需求——我们能为更多开发者提供更优质的开源工具，持续为繁荣的自由软件生态系统贡献力量。