简介面向自然语言处理研究人员、技术开发者及希望将深度学习落地法律垂直领域的初学者这份资料提供了一套基于 PyTorch 与 Hugging Face Transformers 搭建本地法律大模型的完整技术方案。方案围绕客户保密前提下的数据集准备、文本清洗与预处理对比了 BERT/RoBERTa 预训练模型的选型思路并详细展开微调训练、超参数调整、评估指标准确率、召回率、F1 值与数据增强、集成学习等优化手段同时涵盖 Flask/FastAPI 本地服务搭建、API 接口规范以及 HTTPS、加密传输和权限管理等安全保密措施。资源包共 1 个 docx 文档体积约 23KB以可实现方案和核心代码说明为主内容组织层次分明便于直接作为项目启动前的技术预研与实施参考。目前已有 100 人学习下载适合需要快速搭建法律 NLP 系统全流程的读者。1. 本地法律大模型为什么客户点名要本地以及这条链路能拆出什么本地部署法律大模型这件事客户的要求往往只有两句话数据不出内网输出要能解释。用 PyTorch 和 Hugging Face Transformers 搭一条从合同文本到风险结论的链路核心其实不是训一个多大的模型而是把 bert-base-chinese 这类通用中文模型在合同语料上做微调再包一层可用的本地接口。本文拆的是这套完整落地方案数据清洗与分词、BERT 微调训练循环、Flask 服务封装以及我在实际项目里踩过的坑。适合手上有法律语料、想把 NLP 落地到垂直行业的工程师也适合想完整走一遍 Transformers 微调流程的初学者。2. 把法律语料喂进 BERT 前数据清洗、分词与 DataLoader 的三个关键参数2.1 为什么是 PyTorch Transformers选型理由与版本约束法律文本处理选 PyTorch 不是因为它最火而是因为微调场景下它的动态图和 Python 风格调试最顺手。Transformers 库把所有主流预训练模型的加载、前向、微调统一成一套接口BERT、RoBERTa 之间切换基本只改一行from_pretrained。对合同审查这类任务BERT 的双向编码结构能同时看到条款上下文比单向 GPT 更适合做文本分类和风险识别。版本上有两个坑要先讲清楚。第一Transformers 4.x 的接口和 3.x 差别很大BertForSequenceClassification的返回从 tuple 变成了ModelOutput老教程里的outputs[0]写法会失效要用outputs.logits。第二PyTorch 版本必须跟 CUDA 版本匹配装完torch.cuda.is_available()返回 False 是最常见的事故。我的建议是先用 CPU 环境把整个流程跑通再上 GPU避免一开始就陷入环境问题。2.2 数据清洗与分词从原始 CSV 到 vocab 映射第一步先把客户给的原始数据读进来。法律数据通常长这样CSV 或 JSON每条记录包含合同条款文本或案例描述以及对应的标签列。标签可以是合同风险等级、案由类别甚至是对应法条编号。读数据时编码要指定utf-8-sig否则客户从 Windows 导出的 CSV 经常在首列出现乱码。import pandas as pd import numpy as np import jieba import re df pd.read_csv(legal_data.csv, encodingutf-8-sig) print(df[label].value_counts()) # 检查类别分布类别极度不平衡后面要处理 def clean_text(text): if not isinstance(text, str): return text re.sub(r[^], , text) # 去 HTML 残留标签 text re.sub(r[\r\n\t], , text) # 统一换行和制表符 text .join(ch for ch in text if ch.isprintable()) # 去不可打印字符 return text.strip() df[text] df[text].apply(clean_text)清洗逻辑按优先级排先去掉 HTML 残留再统一空白符最后过滤控制字符。法律文书经常是从 PDF 或者 Word 直接复制出来的会带各种不可见字符.isprintable()这一步能省掉很多后续麻烦。value_counts()输出要重点看如果某个类别占比超过 90%后面评估指标就不能只看准确率。分词这步是资源正文里最值得注意的地方。项目用 jieba 把句子切成词然后构建自己的 vocab。这套流程对理解 BERT 输入机制很有帮助但要注意它和 Hugging Face 标准做法有差异——真正的 BertTokenizer 用的是子词切分能处理 jieba 切不出来的生僻法律术语。df[tokens] df[text].apply(lambda t: jieba.lcut(t)) # 预留 PAD 和 UNK防止 padding 和未登录词没有对应 id vocab {PAD: 0, UNK: 1} for tokens in df[tokens]: for w in tokens: if w not in vocab: vocab[w] len(vocab) MAX_LEN 512 def encode(tokens): ids [vocab.get(w, vocab[UNK]) for w in tokens[:MAX_LEN]] ids ids [vocab[PAD]] * (MAX_LEN - len(ids)) return ids df[input_ids] df[tokens].apply(encode)MAX_LEN 512是 BERT 的位置编码上限硬要塞更多 token 进去模型会直接报错。法律条款往往很长靠截断会丢信息这个矛盾留给后面的进阶方案处理。vocab 构建时必须保留PAD和UNK两个特殊 token否则 padding 和未登录词没有地方可去。这里把每个样本的长度都补到 512优点是把数据集变成规整的矩阵缺点是显存浪费明显后面我会给出更省的做法。提示如果直接用BertTokenizer的标准流程其实不需要 jieba 和自定义 vocab。但先把这套链路走通能帮你理解「词表映射」到底在做什么排查问题时会更有方向。2.3 数据划分与 DataLoader70/15/15 与 batch_size 设置资源正文里的划分方式是random_state42随机切。但法律数据通常类别不平衡随机切训练集、验证集、测试集会放大分布偏差我一般会用分层抽样保证三份数据里的类别比例一致。from sklearn.model_selection import train_test_split from torch.utils.data import Dataset, DataLoader train_df, rest_df train_test_split(df, test_size0.3, random_state42, stratifydf[label]) val_df, test_df train_test_split(rest_df, test_size0.5, random_state42, stratifyrest_df[label]) class LegalDataset(Dataset): def __init__(self, data_df): self.texts np.array(data_df[input_ids].tolist(), dtypenp.int64) self.labels np.array(data_df[label].tolist(), dtypenp.int64) def __len__(self): return len(self.labels) def __getitem__(self, idx): return self.texts[idx], self.labels[idx] train_loader DataLoader(LegalDataset(train_df), batch_size16, shuffleTrue) val_loader DataLoader(LegalDataset(val_df), batch_size32, shuffleFalse) test_loader DataLoader(LegalDataset(test_df), batch_size32, shuffleFalse)stratify是这里的关键参数按标签比例分层抽样避免验证集里某一类样本缺失。batch_size 的选择直接受显存约束BERT-base 在 512 长度下batch_size16 大约需要 12-14G 显存8G 显卡要降到 8或者配合后面的梯度累积。shuffleTrue只用于训练集验证和测试集要保持顺序方便对齐预测结果。3. 微调 bert-base-chinese 的完整训练循环AdamW、早停与七项超参数3.1 加载预训练模型与设备num_labels 是事故高发区加载 BERT 做分类微调的核心是把最后一层替换成自己的分类头。BertForSequenceClassification做的事情就是bert → dropout → linear → logits你只需要告诉它类别数。类别数必须和你的标签总数严格一致这是最容易被忽略的翻车点。import torch from transformers import BertTokenizer, BertForSequenceClassification, AdamW NUM_CLASSES len(df[label].unique()) print(类别数:, NUM_CLASSES) tokenizer BertTokenizer.from_pretrained(bert-base-chinese) model BertForSequenceClassification.from_pretrained( bert-base-chinese, num_labelsNUM_CLASSES ) device torch.device(cuda if torch.cuda.is_available() else cpu) model.to(device)from_pretrained第一次运行会从 Hugging Face 下载模型权重到本地缓存之后离线可用——这对客户内网环境很重要可以提前把模型文件拷到内网机器上。设备选择上torch.cuda.is_available()返回 False 时不要硬跑 GPU。另外注意BERT 模型的前向需要attention_mask而且我们前面对齐了input_ids这里要补一个 mask 生成函数def make_mask(input_ids): # input_ids 里 token 是 0 的位置是 paddingmask 置 0 表示不参与注意力 return (input_ids ! 0).long()凡是 padding 的位置注意力掩码都必须为 0。很多经典代码里model(inputs)单参数直传在 Transformers 4.x 下要么报参数缺失要么 mask 全为 1 导致模型在 padding 上浪费计算这一点放到避坑章详细展开。3.2 AdamW、早停与超参数微调法律模型的推荐配置微调和预训练不一样学习率必须压得很低。BERT 的原始权重已经学到了通用语义学习率太大会把预训练学到的知识覆盖掉造成「灾难性遗忘」。下面是这份资源里跑下来最稳的一组超参超参数推荐值说明learning_rate1e-5微调场景安全区间是 1e-5 到 5e-5batch_size16512 长度下 12G 显存刚好num_epochs6配合早停不必固定死warmup_steps500前 10% 的训练步数逐步提升学习率max_grad_norm1.0梯度裁剪防 loss 炸掉weight_decay0.01AdamW 自带权重衰减正则化防过拟合patience2验证集连续 2 个 epoch 不涨就停训练循环里每一步的职责要分清楚optimizer.zero_grad()清空上一步梯度loss.backward()算梯度clip_grad_norm_把梯度模长限制在 1.0 以内optimizer.step()更新参数。漏掉零梯度是新手最常见的 bug梯度会不断累加损失曲线直接起飞。from torch.nn.utils import clip_grad_norm_ optimizer AdamW(model.parameters(), lr1e-5, weight_decay0.01) criterion torch.nn.CrossEntropyLoss() num_epochs 6 best_val_acc 0.0 patience 0 for epoch in range(num_epochs): model.train() total_loss 0.0 for inputs, labels in train_loader: inputs inputs.to(device) labels labels.to(device) attention_mask make_mask(inputs) optimizer.zero_grad() outputs model(input_idsinputs, attention_maskattention_mask) loss criterion(outputs.logits, labels) loss.backward() clip_grad_norm_(model.parameters(), max_norm1.0) optimizer.step() total_loss loss.item() model.eval() correct 0 total 0 with torch.no_grad(): for inputs, labels in val_loader: inputs inputs.to(device) labels labels.to(device) attention_mask make_mask(inputs) outputs model(input_idsinputs, attention_maskattention_mask) _, pred torch.max(outputs.logits, dim1) correct (pred labels).sum().item() total labels.size(0) val_acc correct / total print(fepoch {epoch 1} | loss {total_loss / len(train_loader):.4f} | val_acc {val_acc:.4f}) if val_acc best_val_acc: best_val_acc val_acc patience 0 torch.save(model.state_dict(), legal_model_best.pth) else: patience 1 if patience 2: print(验证集指标不再提升触发早停) break早停的逻辑是验证集准确率连续两个 epoch 没创新高就停止训练保存的是历史最优权重而不是最后一个 epoch 的权重。torch.save(model.state_dict(), ...)只保存参数字典不保存模型结构加载时必须先用同样的from_pretrained重建模型。提示类别不平衡时CrossEntropyLoss可以传入class_weight把少数类的权重调高。这是我处理法律数据时的默认操作能明显改善 F1 而不是准确率。3.3 模型保存与评估测试集上的精确率、召回率与 F1保存用state_dict加载用load_state_dict中间有个隐藏要求加载时的模型结构和训练时的结构必须完全一致包括num_labels。训练时用了 3 类加载时写错成 2 类load_state_dict会直接报尺寸不匹配的错误这是自己给自己挖坑的高频操作。from sklearn.metrics import classification_report model.load_state_dict(torch.load(legal_model_best.pth, map_locationdevice)) model.eval() preds, golds [], [] with torch.no_grad(): for inputs, labels in test_loader: inputs inputs.to(device) attention_mask make_mask(inputs) outputs model(input_idsinputs, attention_maskattention_mask) _, pred torch.max(outputs.logits, dim1) preds.extend(pred.cpu().tolist()) golds.extend(labels.tolist()) print(classification_report(golds, preds))map_locationdevice是模型在 GPU 上训练、想在 CPU 机器上加载时的后悔药。评估指标里准确率只能说明总体情况法律场景更需要看每个类别的 precision 和 recall——把一份有风险的合同判成无风险和把无风险的合同判成有风险代价完全不同。分类报告会逐类给出指标哪一类弱一眼就能看出来。4. 用 Flask 把模型变成本地接口推理封装、并发与保密部署4.1 服务结构与路由设计先定输入输出格式再做业务有了训练好的权重接下来是把模型包装成可调用的服务。Flask 的优势是轻几行代码就能起服务适合内网部署。但要做的是先把接口协议定清楚再写业务逻辑。我常用的格式是这样// 请求 POST /predict { text: 甲方逾期付款超过30日乙方有权解除合同... } // 响应 { label: 高风险条款, confidence: 0.87 }模型加载放全局变量是部署时最容易忽略的性能问题。如果放在请求函数里加载每个请求都会重新读一遍权重几百兆的模型文件会让服务直接卡死。正确做法是服务启动时加载一次之后所有请求共用这份内存。from flask import Flask, request, jsonify import torch app Flask(__name__) INFER_MODEL BertForSequenceClassification.from_pretrained( bert-base-chinese, num_labelsNUM_CLASSES ) INFER_MODEL.load_state_dict(torch.load(legal_model_best.pth, map_locationdevice)) INFER_MODEL.to(device).eval() INFER_TOKENIZER BertTokenizer.from_pretrained(bert-base-chinese) LABELS [低风险, 中风险, 高风险]推理函数里把 tokenizer、模型前向、概率转换串起来业务路由只负责拿文本、返回结果。这里我直接用encode_plus替代前面的 jieba 手工 vocab 流程因为服务端不需要再维护一份自定义词表Transformers 自带的 tokenizer 更稳定。4.2 推理封装与概率输出softmax 和阈值要一起设计from scipy.special import softmax def predict(text): encoded INFER_TOKENIZER.encode_plus( text, max_length512, truncationTrue, paddingmax_length, return_tensorspt ) input_ids encoded[input_ids].to(device) attention_mask encoded[attention_mask].to(device) with torch.no_grad(): logits INFER_MODEL(input_idsinput_ids, attention_maskattention_mask).logits probs softmax(logits.cpu().numpy()[0]) idx int(probs.argmax()) return LABELS[idx], float(probs[idx]) app.route(/predict, methods[POST]) def predict_api(): payload request.get_json(forceTrue) text payload.get(text, ) if not text: return jsonify({error: empty text}), 400 label, confidence predict(text) return jsonify({label: label, confidence: confidence}) app.route(/health, methods[GET]) def health(): return jsonify({status: ok}) if __name__ __main__: app.run(host0.0.0.0, port8080, debugFalse)encode_plus直接完成分词、截断、padding、生成 attention_mask 四件事return_tensorspt返回 PyTorch 张量。truncationTrue解决超长文本的问题超出 512 的部分直接截掉它会放在左侧还是右侧可以配置合同条款我一般保留头部因为关键信息往往在开头。debugFalse是上线必须改的debug 模式会开交互式调试器法律数据服务的日志里泄露堆栈信息是很危险的。概率输出这里有个容易被忽略的点argmax得到的是概率最高的类别但这个概率可能是 0.31。法律场景里如果一个条款在三个类别间概率分布很平说明模型没把握。我通常的做法是加一个置信度阈值低于 0.6 的返回「无法判断」并标记为需要人工复核。4.3 本地部署的保密与性能权限、日志和并发控制本地部署不等于安全数据不出内网只是第一步。客户的数据不能出现在日志里尤其不能把整个合同文本打进 Flask 默认的 access log。我一般会在 Nginx 层关掉请求体日志或者用中间件只记录长度不记录内容。权限控制上最简单有效的是在服务里加一个 token 校验每个请求的 Header 带Authorization: Bearer token服务端启动时从环境变量读 token不匹配就返回 401。HTTPS 证书在内网环境可以用自签证书主要目的是防止同一个交换机下的抓包。性能方面要认清瓶颈BERT 推理是计算密集型并发上来了 CPU 就会打满。单机部署有两个曲线救国的方案一是把batch_size1的推理改为请求排队用队列把多个请求拼成一个 batch 再推理二是用torch.jit.trace把模型固化提速。如果并发需求真的很大Flask 不适合直接扛要换 FastAPI Uvicorn或者用 Triton 这类推理服务。5. 法律模型落地避坑手册五次报错的排查全过程5.1 模型训练时报TypeError: forward() got an unexpected keyword argument现象按资源代码执行outputs model(inputs)报 TypeError或者 loss 异常大。原因Transformers 4.x 的BertForSequenceClassification.forward需要显式传input_ids、attention_mask。直接传一个张量进去它不知道这个张量是什么。如果传了但没给 maskpadding 位置也会参与注意力计算模型相当于在无效位置上学了一些噪声特征。解决改为model(input_idsinputs, attention_maskattention_mask)确保两个参数都传。如果你把make_mask算出来的 mask 打印出来看会发现它的形状和inputs完全一致全是 0 和 1这层关系搞清楚以后就不会再错。5.2 验证集准确率一直停在 0.5 附近不上涨现象训练 loss 在降验证集准确率却稳定在 50%像是随机猜。原因类别不平衡且没有分层抽样。客户给的数据里 90% 是低风险条款模型把所有样本预测成低风险就能拿到 0.9 的训练准确率但验证集里中高风险样本全被误判。另一个常见原因是标签列被读成了字符串和模型的整数输出永远对不上。解决用stratify做分层抽样打印df[label].dtype确认标签类型训练时在CrossEntropyLoss里传class_weight把少数类权重提升。5.3CUDA out of memory显存直接爆掉现象训练循环跑到第二个 batchPyTorch 报CUDA out of memory。原因MAX_LEN512加上batch_size16BERT-base 的激活值占显存非常夸张。法律文本又普遍很长padding 大量存在等于把大量显存花在了无意义的 [PAD] token 上。解决batch_size 降到 8 或 4用encode_plus的paddingmax_length只对当前批次对齐而不是全局对齐 512实在不行用梯度累积每 4 个 batch 更新一次参数模拟大 batch 的效果。如果显存还是不够把MAX_LEN改成 256观察对准确率的影响。5.4 Windows 下导入 torch 报缺少msvcp140.dll现象import torch直接抛DLL load failed或者numpy正常、torch进不去。原因Windows 缺 Visual C 运行库。PyTorch 的预编译包依赖 MSVC 运行环境很多内网机器只装了最小化的系统没装全。解决装Microsoft Visual C Redistributable重启后再试。如果还是不行检查torch.version.cuda和机器上nvidia-smi的 CUDA 版本是否匹配版本不匹配时卸载重装对应的 PyTorch wheel。这条在客户的内网 Windows 服务器上几乎必踩建议第一时间补装运行库。5.5 加载模型权重后预测结果全是同一个类别现象训练时 F1 正常部署后所有请求都返回「低风险」日志里 confidence 出奇一致。原因两个典型错误。其一load_state_dict前用from_pretrained重建模型时num_labels写错权重加载时虽然没报错但输出头被随机初始化的新层覆盖了其二训练时的标签映射顺序和部署时不一致比如训练时 label0 是高风险部署时代码写成了低风险。解决在classification_report里核对每个类别的索引保存模型时额外保存一份label_map.json部署时严格按同一份映射加载。我在项目里吃过这个亏之后把「标签映射文件」和「权重文件」打包成同一份发布物部署时强制校验类别数不一致就直接拒绝启动。6. 从合同分类到生成式法律意见迁移路径与评估习惯分类模型能做的是「判断风险等级」和「打标签」但客户要的往往是「为什么这个条款有问题依据是什么」。这一步要从判别式模型走向生成式模型常见做法是换用支持中文的生成式底座比如基于 ChatGLM、Qwen 等开源模型做 LoRA 微调输入变成「合同条款 任务指令」输出变成自然语言的法律意见。迁移路径并不复杂数据格式从「文本 类别标签」换成「指令 输入 期望输出」比如请审查以下条款的风险并指出依据: {条款}对该条款未约定违约金计算方式依据《民法典》第五百八十五条...。训练目标从分类头的交叉熵换成生成模型的标准语言建模损失评估方式从准确率换成人工抽样复核。生成式模型对显存要求高很多7B 量级的 LoRA 微调最少需要 16G 显存推理速度也比分类模型慢一个量级所以我的习惯是保留分类模型做第一道筛选只有命中高风险才把条款交给生成式模型出意见。模型效果好不好最终要落到评估习惯上。我现在的流程是每次迭代固定抽 100 条测试样本其中 50 条高风险、30 条中风险、20 条无风险人工逐条核对模型输出的两个维度风险判断对不对法律依据是否引用准确。这张评分表每次训练后更新直接对比不同版本模型的差异比单看 F1 值有用得多——因为只有你知道模型的错误是「漏判了条款」还是「法律引用张冠李戴」下一步优化才有方向。做法律 NLP 项目我有一条从翻车里换来的铁规矩训练之前先和客户确认「人工复核样本」和「验收指标」没有这个前置约定模型训得再好验收时各说各话。从那以后我每次接这类项目都强制走一遍「先定评估集、再训模型、最后部署」的顺序希望帮到你。本文还有配套的精品资源点击获取