1. 这包到底是干什么的被XML折腾过的人才会懂先说个真实场景。做人文数字化的朋友应该都有这种感觉手里拿到的语料根本不是干净清爽的纯文本而是一堆带着密密麻麻标签的TEI XML文件。TEIText Encoding Initiative是人文领域的事实标准古籍、书信、学术版本、语料库几乎都用它来标注结构——章节、段落、说话人、地名、人名、注释、校勘记全都有对应的标签。但问题来了。我们做NLP的时候绝大多数模型和工具链吃的都是纯文本或者是带词法标注的文档对象。spaCy作为工业级NLP框架处理纯文本很顺手可你让它直接吃TEI XML它做不到。老办法是什么正则表达式硬剥标签把XML拍平成纯文本再喂给spaCy。这个方案听着简单实际上是个灾难标签剥不干净、结构信息全丢、脚注和正文混在一起、说话人跟内容脱节。最要命的是TEI里那些“层级信息”——比如某段话是出自书信还是校勘记——一旦拍平就再也找不回来了。acdh-spacytei这个包就是冲着这个痛点来的。它是某高校数字人文团队开源的工具核心作用只有一句话把TEI XML文档直接解析成spaCy的Doc对象。中间不用你手工剥离标签不用你写正则XML里的结构信息会映射到Doc的span属性上元数据会挂到doc._.metadata里。也就是说你从XML到可用的NLP文档对象走的是直路。这篇文章我会把它的语法规则、关键参数、以及三个我用过的实际案例一次讲清楚。内容基于该包的公开文档和源码行为结合我自己在几个语料项目里的使用经验展开。如果你正在做古典文献的信息抽取、书信集的对话分析、或者任何“语料是TEI XML但模型需要纯文本”的活这篇应该能帮你少走不少弯路。2. 环境准备安装很简单但坑都在细节里2.1 安装与依赖安装acdh-spacytei只需要一行pip命令pip install acdh-spacytei它会自动带上spaCy、lxml这些核心依赖。不过这里要提醒一句它依赖的spaCy版本可能跟你项目里已有的版本冲突。我自己的项目里原本是用spaCy 3.7的装这个包的时候pip直接把spacy降到了某个兼容版本结果我其他模块又出问题了。所以建议在虚拟环境里装或者在requirements.txt里锁定版本。装完之后还需要下载一个spaCy的模型。这个包本身不绑定具体模型你可以根据语料语言选择python -m spacy download en_core_web_sm # 如果处理中文、梵语等需要选对应的模型 python -m spacy download xx_ent_wiki_sm # 多语言模型示例2.2 验证安装装好后做一个最简单的导入测试确认环境没问题from acdh_spacytei import read_tei print(read_tei)能输出函数对象就说明导入正常。如果你发现read_tei导不进来多半是版本兼容问题检查一下spaCy版本换个Python环境再试试。2.3 我踩过的环境坑lxml的XML解析错误TEI XML文件如果带了不规范的实体引用比如nbsp;lxml解析会直接报错。解决办法是解析前对文件做个预处理或者让包用更宽松的解析器。不过据我实测这个包默认的解析行为对大部分规范TEI文件都没问题。spaCy模型没下载就调用这个错很常见。你光装了包没下载模型跑起来会提示找不到模型。记着模型是独立下载的这步不能省。XML命名空间问题有些TEI文件的根节点带命名空间比如TEI xmlnshttp://www.tei-c.org/ns/1.0。这个包有做命名空间处理但我遇到过个别文件因为多个命名空间混杂导致解析异常。这种情况我会先手动看一眼XML结构确认它是不是严格遵循TEI标准的文件。3. 核心语法Text对象与read_tei函数的玩法拆解3.1 先搞懂返回的Text对象是什么在我们动手写代码之前得先搞清楚它的数据模型。read_tei()返回的是acdh_spacytei.text.Text对象这个对象有几个关键的属性.doc这是我们最常用的一个spaCy的Doc对象.tei原始的TEI ElementTree结构用于需要读取原始XML信息的场景所以整个流程是TEI XML文件 → Text对象 → .doc属性得到spacy Doc → 接下来就可以用spaCy的各种API做NLP处理了。我习惯用一段很小的开放式测试数据来理解这个包的行为。比如构造一个最简单的TEI片段TEI xmlnshttp://www.tei-c.org/ns/1.0 teiHeader fileDesc titleStmttitle测试文档/title/titleStmt publicationStmtpublisher某出版社/publisher/publicationStmt /fileDesc /teiHeader text body div typechapter xml:idch1 head第一章/head p这是第一段内容。/p /div /body /text /TEI用read_tei读取from acdh_spacytei import read_tei tei_obj read_tei(test.xml) doc tei_obj.doc for token in doc: print(token.text, token.pos_)这样就能在spaCy Doc里看到分词和词性标注结果了。3.2 read_tei的亮眼特性文本内容归并这个包最核心的机制是对text()函数的重新编排。TEI XML里经常出现同一个逻辑段落被多个标签分割的情况比如一个p标签里嵌着hi、persName、placeName这些内联标签。如果你用lxml自带的xpath(//text())去提取纯文本得到的是很多段碎片文本你还得自己拼。而这个包用了一套内部的文本归并逻辑把嵌套标签里的文本内容按顺序拼成连续的字符串同时记录每个片段的起始和结束位置。这个机制有什么好处举个例子p张三去了placeName北京/placeName又去了placeName上海/placeName。/p如果用纯lxml处理文本碎片是[张三去了, 北京, 又去了, 上海, 。]。而acdh-spacytei会把它们拼成完整句子“张三去了北京又去了上海。”这就为后续的实体识别、关系抽取提供了干净的输入。顺带一提这个归并过程不是简单地字符串相加它保存了每个片段的边界信息。你后续如果要定位某个词在原始XML里的位置是可以倒推回去的——虽然这需要你读一点源码才能找到具体的映射逻辑但至少设计上是通的。3.3 元数据是怎么挂上去的TEI头teiHeader里的信息比如标题、作者、出版信息会被解析后存到doc._.metadata里。下面这段代码可以打印元数据print(doc._.metadata)实际输出是一个字典键值取决于你的TEI头里有哪些字段。比如{ title: 测试文档, publisher: 某出版社, }这里有个值得注意的点不同文件提供的TEI头字段差异极大所以metadata字典的键不是固定的。你在写下游代码时要做好键存在性检查别上来就doc._.metadata[author]万一没有这个字段就直接KeyError了。3.4 支持哪些TEI结构就我目前用到的它对text、body、div、p、head、list、item、quote、note、persName、placeName、rs这些常规TEI结构都有处理逻辑。特别是note标签默认情况下的行为是把脚注内容单独分组而不是混进正文。这个我们下一节细说。4. 参数详解这些参数不调好效果天差地别一开始用这个包的时候我照着文档把read_tei当黑盒调结果输出跟预期差很远。后来仔细看了源码才发现参数的设置直接影响文本切分逻辑。下面我把几个关键参数逐一拆开讲附上我自己测试过的效果对比。4.1 quotes参数引文要不要单独拆出来这是我在书信集项目里用得最多的参数。TEI里对引用内容通常用quote标签包裹。如果quotes参数设为False默认quote标签里的内容和正文一起按正常文本处理如果设为True每个quote里的内容会单独变成Doc里的一个span方便你单独抽取引文。这里有个非常微妙的行为差异。我在某书信编研项目里处理过一批19世纪的书信信中大量引用别人的著述。当时想做的事情是识别每封信里引用了哪些外部作品。如果quotesFalse引文内容和写信人的正文混在一起实体识别结果里就分不清哪些是引文里的书名、哪些是正文里提到的书名。而quotesTrue之后每个引文块自动成为独立span配合句子切分我能把“信主正文”和“引文内容”做成两类输入下游的分类准确率提升非常明显。from acdh_spacytei import read_tei # 引文单独抽取模式 tei_obj read_tei(letters.xml, quotesTrue) doc tei_obj.doc for span in doc.spans.get(quotes, []): print(引文内容:, span.text)这个doc.spans.get(quotes, [])是我在这个包源码里看到的结构。引文被存到了Doc的span groups里key是quotes。如果你的任务是做引用分析、互文性研究这个参数必须打开。4.2 remove_notes参数脚注怎么处理TEI的脚注和注解用的是note标签。默认情况下这个包会把note里的内容从正文文本流中移除放到单独的span里。为什么要这样设计因为很多古籍和学术版本的脚注是校勘记或译注跟正文的语体差异很大。如果混在一起NLP模型可能会被带偏。但这里有个坑当你设置remove_notesFalse时note的内容并不会以span group的形式保存而是直接混入正文且不一定有清晰的边界标识。这导致一个问题——注释内容和正文粘连在一起切出来的句子可能语义混乱。我的建议是除非你做的是纯文本还原任务否则保持默认的remove_notesTrue把注释单独收集。收集方式同样是spanskey是notesfor span in doc.spans.get(notes, []): print(注:, span.text)还有footnotes有些TEI结构用footnotes标签独立存放脚注文本。包里也做了对应处理key是footnotes。如果你处理的是带脚注的学术版文献跑一遍之后单独导出脚注集做注释文本的专题分析会非常方便。4.3 empty_tags参数空标签要不要保留中文古籍的TEI里有一种情况非常普遍某些p标签里没有任何文本内容或者只有空格、换行。empty_tagsFalse默认的时候这些空标签会被直接过滤掉不生成空span。empty_tagsTrue的时候则保留这些空标签。到底选哪个看你的下游任务。如果你做的是文档结构对比空段落是有意义的——它表示原文里有一段留白。但如果你做的是文本分析空段落只会制造一堆空span干扰句子边界判断。我一般选择False省心。4.4 split_on参数结构性分割点这个参数决定用什么标签层级作为段落切分的依据。默认情况下是包含div和p的层级。这个参数不常需要改但当你的TEI文件嵌套层级特别深比如div里嵌套了好几层div时默认的切分逻辑可能跟你想要的粒度不一致。举个例子我做某大型历史文献数字化项目时原始文档一个页面里有“章”、“节”、“小节”三层div。默认切分会把三层都打散到若干段落里但是我想以“章”作为最大切分单元。这时候就需要理解它内部的分割逻辑——具体来说是通过设置split_on参数传入你希望作为分割点的标签列表让那些层级的标签不参与文本归并而是作为切分边界。这个参数需要试。建议你在正式项目开始前先拿一个小的样本文档尝试不同分割标签组合输出看看段落数量和每段内容是否合理再确定正式参数。4.5 其他值得留意的参数包的read_tei函数还接收一些文件处理相关的参数比如处理XML的parser参数、编码相关参数等。大多数时候默认值就够用。真正需要你操心的就是上面这四个——quotes、remove_notes、empty_tags、split_on。把这四个吃透这个包你已经能驾驭90%的功能了。5. 实际案例我用它处理的三种典型语料5.1 案例一古籍校勘本的实体识别与注文分离某古籍数字化项目里我处理了一批明清时期的刻本。这批文献的TEI结构大体是这样的正文用p包裹刻工添加的校勘记放在note标签里引用他人著作的地方用quote包裹。当时的任务是两件事第一从正文中提取人名、地名、书名实体第二把所有校勘记单独导出做研究。用acdh-spacytei处理非常顺手from acdh_spacytei import read_tei import spacy # 加载一个古汉语友好的模型具体看你项目选型 nlp spacy.load(xx_ent_wiki_sm) # 解析TEI文件开启引文抽取默认移除注释 tei_obj read_tei(ancient_book.xml, quotesTrue) doc tei_obj.doc # 这里已经是spaCy Doc # 实体识别 for ent in doc.ents: print(ent.text, ent.label_) # 导出所有校勘记 notes [span.text for span in doc.spans.get(notes, [])] with open(notes_output.txt, w, encodingutf-8) as f: f.write(\n\n---\n\n.join(notes))这个流程跑下来实体抽取的准确度比我之前用正则硬撸的方式高出一大截。原因很简单干净了。注释文本不掺和正文引文也不干扰实体的上下文。5.2 案例二书信集对话抽取与引文分析第二个案例是某书信编研项目。这批书信的TEI标记里每一个div对应一封信信内有收信人、写信人、正文段落、引用片段等。我当时的任务是把每封信里的“A提到B”这类关系抽出来。这个场景下spans里的引文group特别珍贵。因为写信人在信里引用别人著作时往往就是“A提到B”的最直接证据。配合quotesTrue我做了两路抽取# 遍历每封信的div层级的span for div in doc.spans.get(divs, []): if div.label_ letter: # 具体label_如何设置取决于TEI的type属性 letter_text div.text quotes [s.text for s in div.spans.get(quotes, [])] print(信件内容:, letter_text) print(引用:, quotes)这个方案顺利提取出每封信引用的外部文本片段然后我用引用文本的标题匹配来推断“提到”的关系整套流程比人工阅读效率高太多。当然span的层级信息和label的设置需要你对这个包的数据结构有一定了解我建议用dir(doc.spans)去探查有哪些可用的group key。5.3 案例三跨语言文献的混合文本处理第三个案例比较特殊。某个跨国合作项目里有一批用多种语言混排的文献——主要内容是近代某地区的历史资料每页正文下方有译者的双语注释脚注里还有现代学者的评注。原文是法语注释是德语和英语混合。这种文本如果做纯文本抽取模型基本崩溃一句话里法语、德语、英语交错出现语言检测器不停跳变。用acdh-spacytei的分离机制就好办多了# 正文用法语模型处理 body_doc nlp_fr(div_text) # 注释和脚注用多语言或者英语模型处理 note_spans doc.spans.get(notes, [])同一份TEI文档正文和注释各自走各自的NLP管线。这在以前连想都不敢想。acdh-spacytei帮我们把结构分离好了剩下的就是模型选型问题。5.4 一个小型完整Demo最后给一个可直接复制运行的小demo演示完整流程。假设你有一个简单的TEI文件demo.xmlTEI xmlnshttp://www.tei-c.org/ns/1.0 teiHeader fileDesc titleStmttitleDemo/title/titleStmt /fileDesc /teiHeader text body p某人在placeName杭州/placeName发表了演说。/p quote路漫漫其修远兮吾将上下而求索。/quote note此句出自《离骚》。/note /body /text /TEI对应的Python代码from acdh_spacytei import read_tei import spacy nlp spacy.load(xx_ent_wiki_sm) tei_obj read_tei(demo.xml, quotesTrue) doc tei_obj.doc print( 句子切分 ) for sent in doc.sents: print(sent.text) print(\n 实体 ) for ent in doc.ents: print(ent.text, ent.label_) print(\n 引文 ) for span in doc.spans.get(quotes, []): print(span.text) print(\n 注释 ) for span in doc.spans.get(notes, []): print(span.text)跑出来效果符合预期句子完整实体识别能识别出“杭州”这样的地点实体引文和注释各自分离。这个demo可以作为你上手任何一种TEI语料的最小验证环境。6. 实际使用的心得这几个坑我最想拿出来说6.1 关于spans的结构一定要先探查这个包用起来最让我不习惯的是spans结构不如普通字符串直观。第一次用的时候我到处找“段落”在哪里后来才发现段落本身就是Doc的句子或span group里的divs。建议任何新项目开始前先写一段探查代码doc read_tei(sample.xml).doc for key in doc.spans.keys(): print(key, len(doc.spans[key]))这样你能快速知道有哪些span group可用来取数。不同TEI文件的标签差异会导致group key变化这是我反复被教训的一点。6.2 当TEI结构不规范时会发生什么有一批外购语料TEI编码质量参差不齐。有的p标签没闭合有的note标签没内容有的quote里再嵌quote。这个包对不规范结构的容忍度有限——它不是玄学遇到结构性错误时会报lxml解析错误或者更麻烦的是不报错但输出缺失。我建议流程里加一道预处理检查用lxml.etree先解析一遍确认XML格式正确检查是否所有div都有type或xml:id属性如果有大量空标签考虑empty_tagsTrue是否更合适6.3 文本被注释切断的问题有些TEI文件里长段落的中间某处会嵌一个注释标签。默认移除注释的逻辑下正文文本会从注释位置断开成两段。从纯文本还原的角度是可以理解的——注释毕竟不是正文。但如果你要做整段语义分析这种断裂会让句子不完整。这种情况下可以试试在解析后对doc.sents做二次合并或者设置remove_notesFalse让注释文本留在正文中然后用正则把注释边界提取出来。不过说实话最稳妥的还是回到数据源头推动语料库建设方规范编码方式——但这就不完全是技术问题了。6.4 语料规模与性能我测试过一个30MB的TEI XML从解析到生成Doc大约几秒到十几秒取决于spaCy模型的复杂度。这个性能对于离线语料处理完全够用。但如果你做的是Web服务实时处理建议加上缓存层不要每次请求都重新解析XML。6.5 和spaCy生态的配合读进来之后理论上所有spaCy生态的工具都可以直接用。我做实体链接的时候直接把doc传给相关组件没有任何兼容问题。这一点很重要——说明acdh-spacytei没有为了特化而破坏spaCy的标准数据结构做得很干净。7. 从acdh-spacytei到其他工具的自然延伸acdh-spacytei解决的只是“把TEI XML变成可用Doc”这一步。真正研究的时候后面还有一堆活要干。这个包给我的最大启示其实是“结构不要拍平”这个思路——如果你手里任何结构化文本被拍平了可以考虑找到对应解析工具保留层级信息或者自己用span group的方式来存结构化边界。我现在处理新的语料不管是TEI还是别的XML方言第一个问题就是它有没有现成的解析库没有的话能不能借鉴acdh-spacytei的span group思路自己写一个轻量解析说到底NLP的下游任务千变万化但“在保留结构的前提下做分析”这个原则是通用的。如果你后续想自己扩展可以试试两个方向一是把doc._.metadata里的TEI头信息利用起来做文档级分类二是结合spaCy的entity_ruler把你领域内的专名表加进去让实体识别效果更精准。这些都是我在现有项目里用过且有效的组合方案。acdh-spacytei这个包不算热门用的人也不多文档更是简陋。但它的设计思路和参数灵活性在“人文数据NLP”这个细分赛道上真的能帮你省掉大量脏活累活。我建议你先拿一篇自己的TEI文件跑一遍把quotes和remove_notes两个参数反复调一调直观感受一下输出区别再决定后续怎么做——很多东西光看文档是看不出来的得亲手摸一遍才知道它的脾气。