简介一套基于PyTorch和Hugging Face Transformers的本地法律大模型搭建方案主要面向企业内部合同审核、律师判例研究以及自动化法律咨询等场景覆盖数据处理、模型选择与微调、性能评估、本地服务部署及安全保密等完整流程适合自然语言处理研究者、法律科技开发者以及希望将深度学习应用于垂直行业的初学者参考。压缩包仅包含1个docx文档大小约23KB其中系统整理了项目概述、技术选型PyTorch、Transformers、pandas/numpy、数据集准备数据清洗、jieba分词、词汇表构建、序列填充、模型训练DataLoader划分、交叉熵损失、超参数调优、早停策略以及模型评估优化准确率、召回率、F1值、数据增强、集成学习等关键环节。目前已有100人学习/下载可帮助读者快速搭建本地法律AI服务。通过阅读文档读者能够获取从合同文本清洗、微调BERT/RoBERTa到开发Flask/FastAPI接口的全链路思路并了解用户权限管理、HTTPS加密等数据隐私保护措施为实际项目提供可落地的实施蓝图。1. 本地法律大模型从 PyTorch 微调到合同审查可用的完整闭环如果你以为“本地法律大模型”指的是把某个通用大模型下载下来、接个网页对话窗口就叫部署那这个项目给你的东西远不止这些。它真正做的是用 PyTorch 和 Hugging Face Transformers把开源的 BERT 类模型在客户脱敏后的法律语料上做针对性微调让模型能完成合同风险识别、案例分类、法律意见输出这三类任务并且自带一套可用的本地服务接口。对从事 NLP 落地、法律科技或想学垂直领域微调的人来说它的价值在于数据和模型代码、数据清洗到部署的路径全是闭环的不是停留在 Kaggle 式实验阶段。本文会按“选型 → 数据处理 → 微调 → 踩坑 → 接口落地”的顺序把整条链路拆开每一步都给出能直接抄作业的代码和参数说明。2. 为什么是 PyTorch Transformers BERT选型理由与本地部署边界2.1 为什么是 PyTorch 而不是 TensorFlow做法律文本分类本质上是在做序列文本的特征提取和语义理解这类任务在 PyTorch 生态里最顺手。PyTorch 的动态计算图让调试变得直观你在forward里打印中间张量、用pdb打断点都不需要像静态图那样先构图再执行。对法律文本这种格式复杂、需要频繁调整预处理逻辑的场景这个灵活性很关键。另外一个现实因素是 Hugging Face Transformers 库对 PyTorch 的支持最完整、更新最快。虽然它也支持 TensorFlow但很多新模型和新特性都是 PyTorch 版本先行。你后续如果想换更强的模型比如从 BERT 换成 RoBERTa 或法律领域专用的 Lawformer 之类Transformers 库里直接改一行from_pretrained的模型名就行不用重写训练循环。2.2 为什么用 BERT 而不是直接上 GPT这个项目要处理的是合同审查、案例分析、法律意见出具这三类任务的核心是“理解”而非“生成”。BERT 类模型是双向编码器能同时看到上下文两侧的信息对文本的分类和风险判断更有利。GPT 类模型是单向的擅长续写和生成但在分类任务上要么加分类头改造、要么走 prompt 路线工程复杂度高且推理成本大。再者客户要求是本地部署、数据保密资源和算力往往有限。BERT-base-chinese 参数量大概 1.1 亿一张 16GB 显存的显卡就能跑推理微调也勉强能跑。换成生成式大模型光加载权重可能就要几十 GB 内存还得处理显存溢出和推理速度的问题不划算。在有标注数据的前提下BERT 微调所得的效果与成本和风险比是这个场景下的最优解。2.3 本地部署的边界条件“本地”这两个字不是指离线运行这么简单。你需要明确三个边界第一数据不出内网。你的训练数据来自客户提供的保密数据集从数据清洗到模型推理全程不能调用任何外部 API。这意味着在线大模型的接口方案直接出局一切都要自给自足。第二算力有上限。微调阶段建议至少准备一张 8GB 以上显存的 GPU如果没有也可以用 CPU 跑但训练时间会成倍增加。推理阶段反而宽松CPU 也能跑但要控制并发。第三模型要可解释。法律场景出的意见要能追溯依据不能黑匣子一开就给出“有风险”三个字。所以模型输出之后还要接规则层把预测结果映射到具体的风险条款和依据文本这一点在接口设计章节会细说。3. 法律文本预处理清洗、分词、序列填充与数据集划分3.1 数据格式与清洗先把脏数据干掉法律文本的来源五花八门可能是扫描件转出的文本可能是从合同管理系统导出的 CSV还可能带各种奇怪的编码字符。原始数据里经常混着换行符、全角半角混乱、制表符、甚至乱码。这一阶段的目标是让文本干净到模型能直接吃。import pandas as pd data pd.read_csv(legal_data.csv) def clean_text(text): if not isinstance(text, str): return # 先将全角字符转为半角再统一处理空白 text text.replace(\u3000, ).replace(\xa0, ) text .join([c for c in text if c.isprintable()]) # 压缩连续空白字符 text .join(text.split()) return text data[text] data[text].apply(clean_text) data data.drop_duplicates(subset[text]) data data.dropna(subset[text, label])这里有个关键细节没体现在代码里isprintable()会把所有不可打印字符过滤掉包括\n、\r。对普通文本没问题但如果你的合同条款本身依赖换行表示段落结构这种删法会丢失层级信息。我一般会改成用正则只删除控制字符保留换行符并压缩为空行以上的逻辑。还有一点drop_duplicates一定要在dropna之前做否则NaN值本身也会被视为重复值把本不该删的记录删掉。3.2 分词、词汇表与序列填充中文分词的第一个坑法律文本里大量出现“违约金”“不可抗力”“知识产权”这类复合术语用jieba.lcut默认词典很容易把它们切碎比如“不可抗力”切成“不可/抗力”语义就丢了。import jieba # 自定义法律术语词典避免专业词被切碎 legal_terms [违约金条款, 不可抗力, 知识产权, 保密义务, 竞业限制, 合同解除权, 违约责任, 争议解决, 补充协议, 股权转让] for term in legal_terms: jieba.add_word(term) def tokenize_text(text): return jieba.lcut(text) data[tokens] data[text].apply(tokenize_text)分词器还牵扯一个后续细节BERT 分词用的是 WordPiece你在这里先用 jieba 分一遍其实是冗余的。更常见的做法是让BertTokenizer自己处理你只做字符级的清理和截断。但在教学和对比实验的场景下用 jieba 分词能看到词边界、方便分析错误案例也有它的价值。建议把 jieba 分词结果当作一个分析工具真正输入模型时直接用tokenizer。词汇表构建是另一个需要小心的点。原方案的逻辑是构建全局 vocab然后把 token 映射成数字索引。这里有个坑如果先做pad_sequence往序列里补PAD再做vocab {word: i for i, word in enumerate(vocab)}PAD根本不在 vocab 里后续映射必然 KeyError。正确顺序是先构建 vocab 时就把特殊符号加进去或者用tokenizer自带的[PAD]和[UNK]。3.3 序列填充、截断与数据集划分长度分布决定 max_len法律文本的长度分布极不均衡一份合同可能几千字一条案例摘要可能一两百字。如果 max_len 取所有样本的最大值会导致大多数样本被大量 PAD 填充训练效率低且浪费显存。MAX_LEN 512 def truncate_and_pad(tokens, max_lenMAX_LEN): if len(tokens) max_len: tokens tokens[:max_len] else: tokens tokens [[PAD]] * (max_len - len(tokens)) return tokens data[padded_tokens] data[tokens].apply(lambda x: truncate_and_pad(x)) from sklearn.model_selection import train_test_split train_texts, temp_texts, train_labels, temp_labels train_test_split( data[text], data[label], test_size0.3, random_state42, stratifydata[label] ) val_texts, test_texts, val_labels, test_labels train_test_split( temp_texts, temp_labels, test_size0.5, random_state42, stratifytemp_labels )关于MAX_LEN的选择不要拍脑袋定 512。先统计一下语料里 token 数量的分位数取第 90 百分位附近的数作为MAX_LEN。合同全文截断会丢失尾部条款但尾部往往是签署页和盖章信息对风险判断影响相对小真正要命的是把“违约责任”这类核心条款截掉了所以关键段落应该前置。常见做法是取每份合同的前 512 个 token这在工业界是默认操作但如果你发现某类风险标签只出现在文档尾部就得考虑用滑动窗口或分段输入的方式处理。train_test_split加stratify是必须的法律数据类别分布通常不均衡“无风险”样本可能占 70% 以上不按标签分层抽样验证集里可能根本看不到少数类样本模型评估指标就会虚高。4. BERT 微调训练加载预训练模型、损失函数与超参调优4.1 加载 BERT 模型分类头的数量由任务决定Hugging Face Transformers 库把预训练模型和分类头封装在了一起BertForSequenceClassification内部自动加载了 BERT 主体和一个全连接分类层。这个分类层的输出维度就是num_labels你需要根据数据集的标签类别数来定。from transformers import BertTokenizer, BertForSequenceClassification MODEL_NAME bert-base-chinese tokenizer BertTokenizer.from_pretrained(MODEL_NAME) # num_classes 根据你的任务标签数量来定 # 例如合同审查0无风险1低风险2高风险则 num_classes3 num_classes 3 model BertForSequenceClassification.from_pretrained( MODEL_NAME, num_labelsnum_classes )注意一个细节bert-base-chinese这个模型本身已经带了中文分词能力你不需要再把文本预先切好词再喂给它。BertTokenizer会把输入文本自动转成input_ids、token_type_ids和attention_mask三个张量。如果你的数据已经是 jieba 分词后的 token 序列那直接调用tokenizer反而会造成二次切分的问题。正确做法是保留原始文本让tokenizer统一处理。4.2 训练循环优化器、学习率与验证评估微调 BERT 和从头训练网络是完全不同的思路。预训练模型已经具备了较强的语言理解能力你不需要大学习率去“重新学”而是用小学习率在已有语义空间里做细微调整。学习率设太大模型会遗忘预训练学到的通用语义在少量法律数据上迅速过拟合。import torch from torch.utils.data import DataLoader, Dataset from transformers import AdamW, get_linear_schedule_with_warmup class LegalDataset(Dataset): def __init__(self, texts, labels, tokenizer, max_len512): self.texts texts self.labels labels self.tokenizer tokenizer self.max_len max_len def __len__(self): return len(self.texts) def __getitem__(self, idx): text str(self.texts[idx]) label self.labels[idx] encoding self.tokenizer( text, truncationTrue, paddingmax_length, max_lengthself.max_len, return_tensorspt ) return { input_ids: encoding[input_ids].flatten(), attention_mask: encoding[attention_mask].flatten(), label: torch.tensor(label, dtypetorch.long) } train_dataset LegalDataset(train_texts, train_labels, tokenizer) val_dataset LegalDataset(val_texts, val_labels, tokenizer) train_loader DataLoader(train_dataset, batch_size16, shuffleTrue) val_loader DataLoader(val_dataset, batch_size16, shuffleFalse) device torch.device(cuda if torch.cuda.is_available() else cpu) model.to(device) optimizer AdamW(model.parameters(), lr2e-5) total_steps len(train_loader) * num_epochs scheduler get_linear_schedule_with_warmup( optimizer, num_warmup_stepsint(total_steps * 0.1), num_training_stepstotal_steps ) criterion torch.nn.CrossEntropyLoss()这段代码里我把tokenizer放进了Dataset每次取样本时实时做编码。如果数据量大这样做会拖慢训练速度。更快的方案是提前把编码后的结果存成内存数组或磁盘缓存DataLoader 直接加载编码结果省去重复分词。对一个几百条数据的小项目来说实时编码无所谓但数据量过万就必须做预编码。batch_size16是 BERT-base 在 16GB 显存下的安全值。如果你的显存只有 8GB降到 8如果显存够大且想加快训练可以适度调到 32但要注意学习率也要相应调整一般 batch size 翻倍学习率也翻倍。4.3 训练与早停监控验证损失而不是训练准确率法律文本分类最怕的就是模型在训练集上表现完美、验证集上一塌糊涂。核心原因是数据量小、类别不均衡。应对方案是每个 epoch 结束后在验证集上计算损失和准确率当验证损失连续多个 epoch 不再下降时提前终止训练并恢复最佳模型。num_epochs 10 best_val_loss float(inf) patience_counter 0 patience 3 for epoch in range(num_epochs): model.train() total_loss 0 for batch in train_loader: input_ids batch[input_ids].to(device) attention_mask batch[attention_mask].to(device) labels batch[label].to(device) optimizer.zero_grad() outputs model( input_idsinput_ids, attention_maskattention_mask, labelslabels ) loss outputs.loss loss.backward() torch.nn.utils.clip_grad_norm_(model.parameters(), max_norm1.0) optimizer.step() scheduler.step() total_loss loss.item() avg_train_loss total_loss / len(train_loader) model.eval() val_loss 0 correct 0 total 0 with torch.no_grad(): for batch in val_loader: input_ids batch[input_ids].to(device) attention_mask batch[attention_mask].to(device) labels batch[label].to(device) outputs model( input_idsinput_ids, attention_maskattention_mask, labelslabels ) val_loss outputs.loss.item() preds torch.argmax(outputs.logits, dim1) correct (preds labels).sum().item() total labels.size(0) avg_val_loss val_loss / len(val_loader) val_acc correct / total print(fEpoch {epoch1}/{num_epochs} | Train Loss: {avg_train_loss:.4f} | fVal Loss: {avg_val_loss:.4f} | Val Acc: {val_acc:.4f}) if avg_val_loss best_val_loss: best_val_loss avg_val_loss patience_counter 0 torch.save(model.state_dict(), legal_bert_best.pth) else: patience_counter 1 if patience_counter patience: print(fEarly stopping at epoch {epoch1}) breakclip_grad_norm_这行是很多新手会漏的。BERT 这类深层 Transformer 模型在训练初期很容易出现梯度爆炸loss 直接变 NaN。把梯度范数限制在 1.0 以内能有效避免这个问题。早停的阈值设置要结合数据量。数据量小几千条时验证损失可能会有较大波动patience3可能过早停止数据量大时可以适当放宽到 5。另外保存模型的时机要严格绑定验证集最优而不是最后一个 epoch 的模型否则你在测试集上看到的指标会虚高。4.4 类别不均衡准确率不是唯一的裁判法律合同数据里“低风险”样本往往占绝大多数“高风险”样本寥寥无几。模型只要全预测为“低风险”准确率就能做到 80% 以上但这显然没有使用价值。from sklearn.metrics import classification_report # 测试集评估时打印完整报告 preds [] true_labels [] model.eval() with torch.no_grad(): for batch in test_loader: input_ids batch[input_ids].to(device) attention_mask batch[attention_mask].to(device) labels batch[label].to(device) outputs model(input_idsinput_ids, attention_maskattention_mask) batch_preds torch.argmax(outputs.logits, dim1).cpu().numpy() preds.extend(batch_preds) true_labels.extend(labels.cpu().numpy()) print(classification_report(true_labels, preds, target_names[no_risk, low_risk, high_risk]))classification_report会输出每个类别的精确率、召回率和 F1。你应该关注少数类的召回率看高风险合同有多少被正确识别。如果少数类召回率低于 60%优先考虑在损失函数里加类别权重CrossEntropyLoss(weighttorch.tensor([0.2, 0.5, 1.0]).to(device))权重值根据样本占比的倒数来设。不要一上来就加先看 baseline 再决定——加权重会影响整体的精确率属于以部分准确率换召回率的交易。5. 避坑指南法律文本微调的五个典型翻车现场5.1 截断策略把“违约责任”截没了现象训练出来的模型对合同前半部分的风险识别很准但对涉及“违约金计算方式”“合同解除条件”这类文档中后段的条款几乎不敏感测试集 F1 明显偏低。原因直接取了每个文本的前 512 个 token。合同文本动辄几千字前 512 个 token 通常只覆盖首部、定义和主体开头关键风险条款分布在后面的段落里被截断了。解决先统计语料中标签与条款位置的分布关系。如果风险条款位置不固定用滑动窗口切分把长文档切成多个窗口每个窗口独立预测最后用规则聚合窗口结果。更简单的方案是把“违约责任”“合同解除”“争议解决”等关键词所在的句子抽出来拼进前置摘要把摘要和原文拼接后再输入模型。5.2 中英文混合文本被分词器切碎现象涉外合同里大量出现 “Force Majeure”“Intellectual Property” 等英文术语使用bert-base-chinese微调后模型对这些术语的识别能力和判断能力明显弱于中文术语。原因bert-base-chinese的词表以中文为主对英文词的处理比较粗糙同一个英文词可能被切成多个子词语义信息被拆碎。解决换用同时支持中英文的预训练模型比如bert-base-multilingual-cased或hfl/chinese-roberta-wwm-ext后者结合了中文全词掩码和更强的英文兼容。如果不想换模型就在预处理阶段把常见法律英文术语映射成固定编号或统一替换为中文译名但这种方法会损失原术语的表达精度。5.3 序列填充后模型把 PAD 当成了有效输入现象训练 loss 正常下降但验证时发现模型对短文本的预测结果不稳定同样的短句换一下措辞预测结果差异很大。原因max_length512的设置让样本长度确定为 512但attention_mask没有正确传入模型。没有 mask模型会把[PAD]位置也当作有效 token 参与注意力计算PAD 过多时注意力分布被稀释。解决检查调用模型时是否传入了attention_mask参数。在BertForSequenceClassification里如果你传给模型的 input_ids 是填充过后的序列就必须同步传 attention_mask。Hugging Face 的 tokenizer 返回的结果里已经包含了这个字段直接用就行。别自己手动 build input_ids 然后忘了 mask这是新手比较容易翻车的一步。5.4 训练时 GPU 显存溢出调试时反而正常现象训练到第几个 batch 时突然报 CUDA out of memory但单条样本推理时占用显存很小。原因显存溢出往往和 batch size 及序列长度有关。BERT 的显存占用和序列长度的平方成正比同一 batch 里如果有一条 5000 token 的长文本没有截断这一条就可能占掉大半显存。解决除了设置max_length512截断外还要检查是否有样本在截断逻辑里被跳过。如果你用的是tokenizer的truncationTrue参数这个参数会截断长文本但要注意它只有在 padding 之前生效。还有一个实用技巧用batch_size动态调整采样若干样本估算单 batch 显存占用超出阈值就减半 batch size。5.5 接口部署后首次请求特别慢甚至超时现象模型训练完Flask 服务启动后第一条请求花了十几秒才返回客户端直接超时。原因服务启动时没有预热。模型权重是懒加载的第一条请求进来才开始加载权重和分词器同时tokenizer要做词表映射这些一次性开销全堆到第一个请求上了。解决在服务启动后主动跑一次空预测强制完成模型和分词器的初始化加载让后续请求直接走推理路径。这个动作叫预热warmup是部署环节的常规操作。如果服务端用的是 FastAPI可以在事件处理器里做这一步。6. 本地服务落地FastAPI 接口改造与批量合同预审实战6.1 用 FastAPI 替换 Flask并发与类型校验更稳原方案用的是 Flask在小规模内部工具的场景下够用。但如果要考虑并发请求和多客户端同时接入我更推荐 FastAPI它基于 ASGI、原生支持异步处理自带的请求体校验能直接省掉手动解析 JSON 的错误处理。from fastapi import FastAPI, HTTPException from pydantic import BaseModel, Field import torch app FastAPI() class ContractRequest(BaseModel): text: str Field(..., min_length10, description合同文本内容) class PredictResponse(BaseModel): risk_level: int risk_level_desc: str high_risk_clauses: list # 启动预热 app.on_event(startup) def warmup(): model.eval() _ model( input_idstorch.zeros(1, 64, dtypetorch.long).to(device), attention_masktorch.ones(1, 64, dtypetorch.long).to(device) )Field(min_length10)会拒绝过短的无效输入比在 Flask 里手动判断文本是否为空要干净。预热那一步形状无关紧要只是强制触发一次前向计算。6.2 接口响应合并规则不只是返回一个标签合同审查的场景光返回一个“高风险”标签意义有限客户要的是哪些条款有问题。这里要加一层规则映射。RISK_DESC { 0: 合同风险较低建议常规审查, 1: 合同存在部分风险重点审查以下条款, 2: 合同风险较高建议终止交易或重新谈判 } HIGH_RISK_KEYWORDS [违约金, 免责条款, 解除权, 不可抗力, 竞业限制] def extract_risk_clauses(text, max_clauses3): clauses [] for keyword in HIGH_RISK_KEYWORDS: idx text.find(keyword) if idx ! -1: start max(0, idx - 30) end min(len(text), idx len(keyword) 50) clauses.append(text[start:end]) if len(clauses) max_clauses: break return clauses app.post(/predict, response_modelPredictResponse) def predict(req: ContractRequest): try: encoding tokenizer( req.text, truncationTrue, paddingmax_length, max_length512, return_tensorspt ).to(device) with torch.no_grad(): outputs model(**encoding) pred torch.argmax(outputs.logits, dim1).item() risk_clauses extract_risk_clauses(req.text) if pred 2 else [] return PredictResponse( risk_levelpred, risk_level_descRISK_DESC[pred], high_risk_clausesrisk_clauses ) except Exception as e: raise HTTPException(status_code500, detailstr(e))extract_risk_clauses是规则层和模型层的配合模型负责判断整体风险等级规则负责定位具体文本片段。这种做法在工程上很成熟既利用模型语义判断能力又保留规则的可解释性律师在审查时能看到依据不会把模型当黑匣子。6.3 批量合同预审把逐条调用变成文件级处理接口一次只处理一条文本但实际使用场景往往是整批合同。写一个批量预审脚本、把结果输出为带风险等级的表格实用性比逐个调接口高得多。import pandas as pd def batch_predict(input_csv_path, output_csv_path): df pd.read_csv(input_csv_path) results [] for _, row in df.iterrows(): resp predict(ContractRequest(textrow[contract_text])) results.append({ contract_id: row[contract_id], risk_level: resp.risk_level, risk_desc: resp.risk_level_desc, high_risk_clauses: ||.join(resp.high_risk_clauses) }) out_df pd.DataFrame(results) out_df.to_csv(output_csv_path, indexFalse, encodingutf-8-sig) return out_df # 用法batch_predict(contracts.csv, contracts_review_result.csv)utf-8-sig编码是为了让 Excel 直接打开不乱码这个细节对交付给非技术同事很有用。批量预审可以做成定时任务合同文件更新后自动重新跑一遍结果表里高风险合同排在最前律师按照优先级人工复核。从那以后我每次搭这类垂直领域模型都会在部署阶段强制走一遍“预热请求 规则层映射 批量输出”三件套不多做但一步都不敢省。模型的预测结果永远只作为一个信号真正能交付给业务方的是把信号翻译成可读、可追溯、可复核的审查意见。希望这篇文章能让你少走几步弯路。本文章与资源获取https://xiaoyaojon.github.io/law-llm-setup 密码公众号极客TD本文还有配套的精品资源点击获取