ANNOTARES：德语法律文本逻辑结构抽取数据集实战解析

这次我们来看一个偏 NLP + 法律文本处理方向的数据集项目：ANNOTARES。它的全称是“A Dataset for Extracting Logical Structures from German Statutory Texts”，简单说，就是专门为“从德语法律法规原文中抽取逻辑结构”这一任务构建的标注语料。提到法律 NLP，很多人第一反应是“能不能用大模型写合同、审合同”，但 ANNOTARES 解决的是一个更底层的问题：让模型先读懂法条内部的层级关系、引用关系和修改关系。

如果把这个任务展开讲，核心就是：一段法律文本里，哪部分是条文编号，哪一段属于第几款，哪句话是对其他条文的引用，哪个条文曾经被后续立法修改过。这些信息在文档里都是“隐藏结构”，人读起来不费力，但机器很难直接理解。ANNOTARES 这类数据集做的事情，就是把这些隐藏结构显式标注出来，做成训练样本，供模型学习和评测。

这篇文章会围绕这个数据集展开一套可落地的技术路径，包括：法律逻辑结构抽取的应用场景、数据集的加载与字段设计、把原始文本转成序列标注数据、用 German BERT/LegalBERT 类模型训练结构抽取器、封装成推理接口、以及批量处理和显存观察。无论你是在做法律知识图谱、法规智能检索，还是想把法律条文喂给大模型做 RAG，这篇文章都值得看完。

1. 核心能力速览

从表里可以看到，ANNOTARES 不是一个“开箱即用”的可视化工具，而是一个数据资产。要发挥它的价值，需要配套的数据处理脚本和模型训练流程。后面几章就按这个思路展开。

2. 为什么要做法律文本逻辑结构提取

德文法律文本有非常强的结构特征。典型的法律条文会按照“章 / 节 / 条 / 款 / 句 / 项”组织，条文编号通常以§开头，款以Abs.表示，句以Satz表示，项以Nr.表示。除了这种树状层级，法律文本还有一个显著特点就是大量引用。一个条文在修改另一个条文时，会直接写“§ 123 Abs. 2 wird wie folgt geändert”，如果模型分不清这句话指向哪个条文、属于哪一款，后续的法规分析和知识图谱构建就会出现错误。

从应用角度看，逻辑结构提取至少能对以下几个方向产生直接影响：

• 法规检索：不是全文匹配，而是精确到“哪一条、哪一款、哪一句”的结构化检索。
• 法条演化分析：识别“被修改”“被废除”“被新增”的条文，追踪法律文本的版本变化。
• 知识图谱构建：把条文、款、句作为节点，把引用关系作为边，构建法律知识网络。
• 大模型 RAG：把法律文本切成结构化的片段再喂给检索增强生成系统，比整篇丢进去更容易控制上下文。

如果没有 ANNOTARES 这种标注数据，以上任务都只能靠规则硬匹配。规则在简单的“条文编号识别”上有效，但一旦遇到嵌套引用、跨章节引用、间接修改表达，规则的维护成本会迅速失控。数据集的价值就在于此：它提供了可训练、可评估的“正确答案”，让模型从标注样本中学习结构规律。

3. 适用场景与使用边界

先说适合的场景。你是研究法律 NLP 的研究人员，想找一份带结构化标注的德语法律语料做实验，ANNOTARES 属于比较对口的选择；你在做法规知识图谱，需要从德国法律文本里抽出条文之间的引用和修改关系，这个数据集可以作为标注依据和模型训练基础；你在做多语言法律文档解析，可以把德语结构抽取做成一个独立子模块，后面再接其他语言的模型；你本身就在跑 German BERT 或 LegalBERT 的微调实验，那这个数据集可以当作一个中高难度的序列标注评测任务。

不适合的场景也要说清楚。ANNOTARES 解决的是“结构抽取”，不是“法律问答”，更不是“合同审查建议生成”，不要指望拿它微调一个模型之后直接给用户输出法律结论。其次，数据集的文本是德语，如果项目只处理中文或英文法律文本，直接用它训练跨语言效果会打折扣，需要做额外的迁移或重新标注。最后，如果只是想做关键词级别的条文定位，用正则可能更轻，不必引入模型训练成本。

合规边界是必须强调的。法律文本可能存在版权、数据库权或使用权限制。使用 ANNOTARES 之前，要先确认官方仓库的许可证、数据来源和允许的使用范围，尤其是商用场景。不要因为一个项目标注了数据就默认可以无限制分发或商用。涉及将法律数据接入对外服务时，建议确认数据来源的合法性和输出内容的免责声明。

4. 环境准备与前置条件

这个数据集的工作流偏向“数据处理 + 模型训练”，环境准备集中在 Python 生态。下面给一套通用检查清单，具体版本以你的系统实际兼容情况为准。

如果本机已经装了深度学习环境，先确认 GPU 是否可用：

python -c "import torch; print(torch.cuda.is_available())"

返回True说明 PyTorch 能看到 GPU，可以正常做训练。返回False也能跑，只是训练速度会慢很多。项目目录建议按下面结构组织：

annotares_workspace/ ├── data/ # 存放数据集文件 ├── scripts/ # 数据处理与训练脚本 ├── models/ # 保存微调后的模型权重 ├── outputs/ # 推理输出 └── logs/ # 训练和推理日志

5. 数据集格式与加载方式

从标题看，ANNOTARES 的核心输出是“带逻辑结构标注的德语法律文本”。不同法律数据集常见的发布格式有两种：一种是JSON/JSONL，每条样本包含原始文本和标注区间；另一种是CoNLL格式，每个 token 一行，用标签列标注每个词在结构中的角色。具体到 ANNOTARES 官方仓库会采用哪种格式，需要看 README 的说明。这里给出一个通用的 JSON 结构示例，帮助你理解这类数据集的样子：

{ "document_id": "BGB_001", "text": "§ 1 Anwendungsbereich. (1) Dieses Gesetz gilt für alle Verträge...", "annotations": [ {"type": "section_number", "start": 0, "end": 7, "label": "SECTION"}, {"type": "subsection", "start": 21, "end": 29, "label": "ABS"}, {"type": "norm_element", "start": 30, "end": 60, "label": "TEXT"} ] }

字段说明：

• document_id：文档唯一标识。
• text：原始法律文本。
• annotations：标注列表，每个标注包含type、start、end和label，表示该结构片段在原文中的起止位置和类型。

加载这类 JSON 数据，可以先做一个简单的字段检查：

import json with open("data/annotares_sample.json", "r", encoding="utf-8") as f: data = json.load(f) print("样本总数:", len(data)) print("首条文档ID:", data[0]["document_id"]) print("字段列表:", list(data[0].keys())) print("标注数量:", len(data[0]["annotations"]))

如果官方发布的是 CoNLL 格式，加载方式就变成按空格和标签切分。但不管哪种格式，下一步都是把原始文本转换成模型能学习的序列标注样本。

6. 从文本到标注序列：数据预处理

序列标注是处理“法律结构抽取”任务最常用的建模方式。把文本拆成 token，每个 token 对应一个标签。常用的是 BIO 标注体系：

• B-SECTION：条文编号开始
• I-SECTION：条文编号中间
• B-ABS：款开始
• I-ABS：款中间
• B-SENT：句开始
• I-SENT：句中间
• B-REF：引用关系开始
• I-REF：引用关系中间
• O：无关 token

如果原始标注用的是字符级别起止位置，需要把它转成 token 级别。以 Hugging Face Tokenizer 为例，整体思路是：先对原文做 tokenization，然后给每个 token 分配偏移量映射，再根据字符区间找到对应 token 并打标签。一个简化的预处理脚本如下：

def convert_annotations_to_bio(text, annotations, tokenizer): # 先做最基本的按词切分，方便理解 words = text.split() labels = ["O"] * len(words) char_to_word = {} idx = 0 for i, word in enumerate(words): for j in range(len(word)): char_to_word[idx] = i idx += 1 if idx < len(text): char_to_word[idx] = i idx += 1 for ann in annotations: start, end, label = ann["start"], ann["end"], ann["label"] start_word = char_to_word.get(start) end_word = char_to_word.get(end - 1) if start_word is None or end_word is None: continue for w in range(start_word, end_word + 1): prefix = "B-" if w == start_word else "I-" labels[w] = prefix + label return words, labels

这段代码是一个偏教学示范的版本，真正处理时还要考虑tokenizer会把一个词拆成多个 subword，以及tokenizer是否在词首添加##前缀等细节。更稳妥的做法是使用transformers提供的offset_mapping来做字符到 subword token 的对齐：

from transformers import AutoTokenizer tokenizer = AutoTokenizer.from_pretrained("bert-base-german-cased") encoded = tokenizer( text, return_offsets_mapping=True, truncation=True, max_length=512, ) offset_mapping = encoded["offset_mapping"] token_labels = ["O"] * len(offset_mapping) for ann in annotations: start, end, label = ann["start"], ann["end"], ann["label"] for i, (s, e) in enumerate(offset_mapping): if s >= start and e <= end: prefix = "B-" if token_labels[i] == "O" else "I-" token_labels[i] = prefix + label

这样得到的token_labels就是和 tokenizer 输出对齐的标签序列，可以直接交给模型训练。注意[CLS]和[SEP]这两个特殊 token 的 offset 通常是(0, 0)，不会落入任何标注区间，因此保持O。

7. 模型训练与效果验证

模型选择上，法律德语文本领域最常用的是 German BERT 和 LegalBERT 这类预训练模型。它们在德文语料上做过预训练，对法律表达的理解会优于通用多语言模型。训练阶段可以把任务建模为 Token Classification，即给每个 token 预测一个结构标签。

训练脚本模板如下：

from transformers import ( AutoTokenizer, AutoModelForTokenClassification, TrainingArguments, Trainer, ) model_name = "bert-base-german-cased" label_list = ["O", "B-SECTION", "I-SECTION", "B-ABS", "I-ABS", "B-REF", "I-REF"] tokenizer = AutoTokenizer.from_pretrained(model_name) model = AutoModelForTokenClassification.from_pretrained( model_name, num_labels=len(label_list), id2label={i: label for i, label in enumerate(label_list)}, label2id={label: i for i, label in enumerate(label_list)}, ) training_args = TrainingArguments( output_dir="models/annotares_ner", num_train_epochs=3, per_device_train_batch_size=8, per_device_eval_batch_size=8, evaluation_strategy="epoch", save_strategy="epoch", logging_dir="logs", logging_steps=50, fp16=True, )

这里用了fp16=True，需要 GPU 支持半精度计算。如果显存较小，可以把per_device_train_batch_size调低到 4 或 2，或者关掉fp16。trainer 的train_dataset和eval_dataset需要转换成 Hugging FaceDataset格式：

from datasets import Dataset def tokenize_and_align_labels(examples): tokenized_inputs = tokenizer( examples["text"], padding=True, truncation=True, max_length=512, return_offsets_mapping=True, ) labels = [] for i, offset in enumerate(tokenized_inputs["offset_mapping"]): word_labels = examples["bio_labels"][i] label_ids = [] for s, e in offset: if s == 0 and e == 0: label_ids.append(-100) else: matched = False for j, (ws, we, wlabel) in enumerate(word_labels): if ws <= s and e <= we: label_ids.append(label2id[wlabel]) matched = True break if not matched: label_ids.append(label2id["O"]) labels.append(label_ids) tokenized_inputs["labels"] = labels return tokenized_inputs train_dataset = Dataset.from_list(train_samples) train_dataset = train_dataset.map(tokenize_and_align_labels, batched=True)

评估指标要用序列标注的专用指标，不能只看整体准确率。推荐使用seqeval计算每个标签的精确率、召回率和 F1：

import numpy as np from seqeval.metrics import classification_report, f1_score def compute_metrics(eval_pred): predictions, labels = eval_pred predictions = np.argmax(predictions, axis=2) true_labels = [] pred_labels = [] for pred_seq, label_seq in zip(predictions, labels): true_seq = [] pred_seq_text = [] for p, l in zip(pred_seq, label_seq): if l != -100: pred_seq_text.append(label_list[p]) true_seq.append(label_list[l]) true_labels.append(true_seq) pred_labels.append(pred_seq_text) return { "f1": f1_score(true_labels, pred_labels), }

模型的最终评估不能只看整体 F1，还要分别看SECTION、ABS、REF这些细分类别的表现。如果某个类别的召回率特别低，说明该结构的训练样本偏少或表达方式比较复杂，需要检查数据分布。

8. 推理与接口 API 调用

训练完成后，可以把模型保存下来，用 Hugging Facepipeline直接加载推理：

from transformers import pipeline model_path = "models/annotares_ner/checkpoint-1000" nlp = pipeline( "token-classification", model=model_path, tokenizer=model_path, aggregation_strategy="simple", ) text = "§ 1 Anwendungsbereich. (1) Dieses Gesetz gilt für alle Verträge." results = nlp(text) for r in results: print(r["entity_group"], r["start"], r["end"], r["word"])

如果要把模型封装成服务，推荐用 FastAPI 做一个轻量接口。轮到一个请求时就加载一次模型，并发高的场景可以常驻模型实例：

from fastapi import FastAPI from pydantic import BaseModel from transformers import pipeline app = FastAPI() nlp = pipeline( "token-classification", model="models/annotares_ner/latest", aggregation_strategy="simple", ) class DocRequest(BaseModel): text: str class DocResponse(BaseModel): result: list @app.post("/api/extract", response_model=DocResponse) def extract_structure(req: DocRequest): result = nlp(req.text) return DocResponse(result=result)

启动接口服务：

uvicorn api_server:app --host 0.0.0.0 --port 8000

调用示例：

curl -X POST http://127.0.0.1:8000/api/extract \ -H "Content-Type: application/json" \ -d '{"text": "§ 1 Anwendungsbereich. (1) Dieses Gesetz gilt für alle Verträge."}'

接口返回的是 JSON，后续可以直接接到检索系统、知识图谱构建流程或 RAG 前端。

批量任务也是这个场景最常见的诉求。如果有一批法律文本需要结构化，可以写一个目录批处理脚本，把文本文件逐条送入模型，并把结果写成 JSONL：

import json from pathlib import Path from transformers import pipeline nlp = pipeline( "token-classification", model="models/annotares_ner/latest", aggregation_strategy="simple", ) input_dir = Path("data/raw_text") output_file = Path("outputs/parsed_results.jsonl") with open(output_file, "w", encoding="utf-8") as f: for path in input_dir.glob("*.txt"): text = path.read_text(encoding="utf-8") result = nlp(text) record = { "file": path.name, "length": len(text), "structures": result, } f.write(json.dumps(record, ensure_ascii=False) + "\n")

批量任务建议加上日志记录，每处理一个文件就输出一条进度，失败的文件单独记录，避免整个任务中断后无法定位问题。

9. 资源占用与显存观察

训练阶段的显存占用通常是最不受控的部分。模型越大、max_length越长、batch_size越大，显存占用越高。建议先在小测试集上用batch_size=2跑一个 step，观察显存峰值，再逐步调大。观察手段是：

nvidia-smi -l 2

这个命令每两秒刷新一次显存和 GPU 利用率。如果显存溢出，优先做三件事：降低batch_size、降低max_length、开启gradient_accumulation_steps。例如把batch_size从 8 降到 2，同时设置gradient_accumulation_steps=4，实际效果相当于 batch size 8，但单步显存占用会低很多。fp16=True也可以减少显存占用，代价是训练稳定性需要额外观察。

推理阶段的显存占用就低得多。BERT-base 类模型在推理时，如果输入长度是 512 token，batch size 为 1，绝大多数中端显卡都能轻松跑。CPU 推理也可以，但速度会慢一个数量级，适合离线批量处理，不适合在线服务。

性能观察方面，有几个点值得记录：单条文本的平均推理耗时、CPU 推理和 GPU 推理的差值、批量大小与显存的增长曲线。这些指标能帮助你判断当前模型能否支撑实时接口的 QPS 要求。如果单条推理耗时 200ms，接口并发 10 时基本没问题；如果单条推理耗时超过 2 秒，就说明需要 GPU 或更小的模型。

10. 常见问题与排查方法

其中最容易踩坑的是标签列表不一致。训练时，id2label的顺序可能和label_list的顺序绑定在一起，如果你在训练后的新脚本里重新定义了不同的label_list，预测结果就会错位。最稳妥的做法是训练完直接保存id2label配置，推理时从模型目录加载，不要手动重建。

另一个问题是max_length=512。BERT 类模型的输入长度上限是 512 token，法律条文通常不会超过这个长度，但一个文档如果包含多个条文，就可能被截断。遇到这种情况，优先按条文切分文本，而不是直接截断。

11. 最佳实践与使用建议

先跑小样本，再全量训练。第一次接触 ANNOTARES 数据时，不要急着启动完整训练。先取 50 到 100 条样本，跑通“加载数据 → 转 BIO → 训练 → 推理”全链路，确认每一步输出符合预期，再扩展数据集。

保持一套最小可运行配置。把数据路径、模型路径、标签列表、超参数写在一个config.py或 YAML 文件里。这样换机器、换数据、跑对比实验时，不需要改脚本内部代码。

数据、模型、输出分目录管理。输入原始数据放data/raw，清洗后的训练数据放data/tokenized，模型权重放models/，推理结果放outputs/。这个习惯能避免训练完找不到中间产物。

批量任务必须加日志和失败重试。法律文本批量解析可能跑几百上千个文件，单文件失败不应该中断整个任务。每个文件处理状态写入日志，失败文件单独记录，处理完成后可以重新执行失败列表。

接口服务要限制访问范围。如果封装成 FastAPI 服务，至少做到本机监听或内网访问，不要直接暴露公网。如果多人使用，可以加一个简单的 API Key 或 Token 校验。

涉及版权和法律数据，先确认授权。ANNOTARES 如果包含第三方法律数据库内容，使用范围可能受限制。训练开源模型或对外提供服务前，必须确认数据集的许可证和原始文本的使用条款。输出内容也要考虑场景，不要用结构抽取结果直接替代专业法律意见。

发布或商用前做效果复核。序列标注模型对未见表达可能不稳定，尤其是“引用关系”“修改关系”这类比较容易混淆的标签。建议在真实业务数据上抽检 100 条左右，逐条看模型输出，确认标签质量后再投入生产。

12. 总结与下一步

ANNOTARES 这类数据集的真正价值，不是给你一个训练好的模型，而是给你一份“带标准答案的结构化法律数据”。有了它，模型才能从法条文本里稳定抽出条文编号、款、句、引用和修改结构，而不是靠一堆脆弱的正则规则硬匹配。

如果你决定动手试，第一步不是急着下载大模型，而是先看数据集官方仓库的 README，确认三件事：数据格式是 JSON 还是 CoNLL；标签体系覆盖哪些结构；许可证允许什么范围的使用。然后再按照这篇文章的流程，把数据加载、BIO 转换、模型训练、推理验证这四个环节跑通一遍。

最容易踩的坑有两个：一个是标签列表在训练和推理时不一致，另一个是offset_mapping对齐错误导致训练噪声很大。这两个问题都在数据处理阶段，多打印几行输出检查，比训练完之后再反查要省事得多。

后续可以扩展的方向也很明确：在 ANNOTARES 基础上尝试不同预训练模型的效果对比；把抽取出的结构接到法规知识图谱或 RAG 系统里；如果项目需要处理中文法律文本，可以参考 ANNOTARES 的标注体系，构建一套中文法律结构标注规范和对应的标注工具。整个方向的技术链路是通畅的，建议收藏备用。