Ollama+LangGraph构建本地化法律AI工作流：数据主权与隐私安全实践

作者：CSDN博客
1. 项目概述：当AI工作流开始“关起门来干活”

你有没有过这种感觉：手头正处理一份刚签完的并购协议，或者客户发来的未公开产品白皮书，你本能地想让AI帮你快速梳理风险点、提取关键条款、甚至生成初版法律意见——但鼠标悬停在那个“发送”按钮上时，手指却停住了。不是因为模型不够强，而是心里清楚：一旦点下去，这份文件就可能穿过防火墙、越过CDN节点、被切片缓存进某个云服务商的分布式日志系统里。合规审计时，没人能保证它没被用于模型微调，也没人能说清它的元数据是否被关联到其他客户行为图谱中。这不是 paranoia，是2026年企业级AI落地最真实的门槛。
这就是 Local Agents 的真实语境。它不是“把大模型搬到本地”这么简单，而是一整套   数据主权归位 的工作流重构哲学。Ollama 不是单纯提供一个本地运行的 llama.cpp 封装，它是整个推理层的“物理隔离锚点”；LangGraph 也不是另一个 DAG 编排工具，它是让多个具备明确角色、边界和记忆约束的智能体，在完全离线的沙盒里完成协作的“神经中枢”。我去年帮一家医疗器械公司部署 Legal Sentinel 系统时，客户法务总监盯着我们演示流程看了三遍，最后只问了一句：“你们确认所有 token 都没出过这台服务器的网卡？”——那一刻我就知道，这个项目的价值不在技术多炫，而在它让“信任”重新变成可验证的物理事实。
关键词里的 “Towards AI - Medium” 其实是个重要提示：这篇文章最初面向的是技术决策者与架构师，而非纯开发者。所以本文不会从   ollama run  命令开始教起，而是先拆解一个核心矛盾：为什么“本地运行”不等于“隐私安全”，以及 Ollama + LangGraph 的组合，如何用最小侵入性方案解决这个矛盾。适合三类人直接抄作业：正在做内部知识库升级的技术负责人、需要处理敏感合同的法务/合规团队、以及想避开公有云 API 调用成本的中小型企业CTO。接下来的内容，全部基于我在6个不同行业客户现场的真实部署记录，包括参数配置截图、内存占用曲线、以及三次因忽略某条硬件限制导致 workflow 卡死的完整复盘。
2. 整体设计思路：为什么必须放弃“云端协同”的惯性思维

2.1 本地 ≠ 安全：三个被严重低估的隐私泄漏面

很多团队第一步就栽在概念混淆上。他们认为只要模型跑在自己服务器上，数据就绝对安全。但实际部署中，至少存在三个隐蔽泄漏通道，而 Ollama + LangGraph 的设计恰恰针对这些盲区做了硬性阻断：
  第一，模型权重本身的“后门”风险。
你以为下载的是 clean 的   llama3:70b  ？其实 Ollama 的 model library 里，90% 的模型都经过社区二次量化（如 Q4_K_M），而量化过程会引入不可逆的权重扰动。我们曾用 diff 工具对比 HuggingFace 原始 GGUF 文件与 Ollama 自动拉取的同名模型，发现约 0.3% 的 weight block 存在非随机偏移。虽然不影响推理精度，但理论上可能成为侧信道攻击的载体。解决方案不是拒绝量化，而是   强制指定可信源 ：   ollama create my-legal-model -f ./Modelfile  ，其中 Modelfile 明确声明   FROM https://huggingface.co/bartowski/llama-3-instruct-GGUF/resolve/main/llama-3-instruct.Q5_K_M.gguf  ，并用   sha256sum  校验文件完整性。这步操作看似繁琐，但在金融客户审计中，是必须提交的《模型溯源清单》第一项。
  第二，LangGraph 的 state persistence 默认行为。
LangGraph 的   StateGraph  类默认使用内存存储（in-memory store），这很危险。当你定义一个   LegalReviewNode  处理合同时，它的中间状态（比如已提取的127个条款编号、临时生成的3个风险摘要草稿）会常驻内存。如果此时发生 OOM killer 杀掉进程，或管理员执行   systemctl restart ollama  ，这些状态会瞬间蒸发——但更糟的是，如果忘记关闭 debug 日志，这些中间态文本会以明文形式写入   /var/log/ollama/debug.log  。我们在某次压力测试中发现，单次文档解析产生的 debug 日志高达 87MB，且包含完整的客户名称、签约金额等 PII 字段。解决方案是   显式禁用所有非必要日志 ：在   ollama serve  启动时添加   --log-level error  参数，并在 LangGraph 初始化时强制指定空存储：   memory = InMemoryStore()  ，然后在每个 node 的   invoke  方法里手动   del state['intermediate_results']  。
  第三，“多智能体”带来的隐式网络暴露。
这是最容易被忽视的。LangGraph 的 agent 间通信走的是 Python 进程内消息队列，但很多团队会习惯性给每个 agent 配置独立的 FastAPI 接口（比如   /api/contract-parser  ,   /api/risk-analyzer  ），美其名曰“便于监控”。问题在于：只要这些端口监听在   0.0.0.0:8000  ，哪怕防火墙规则再严，只要服务器上存在任意一个漏洞（比如旧版 curl 的 CVE-2023-23916），攻击者就能绕过所有应用层鉴权，直接向   /api/contract-parser  POST 伪造的 PDF base64。我们的做法是：   所有 agent 必须绑定     127.0.0.1    ，且 LangGraph 的     checkpointer    强制使用 SQLite 文件存储 （而非 Redis 或 Postgres），这样整个 workflow 的网络暴露面收敛为单一入口：Ollama 的   /api/chat  端口，再由 Nginx 做反向代理+IP 白名单+请求体大小限制（   client_max_body_size 50M  ）。

  提示：不要相信任何“自动安全加固”的第三方 wrapper。我们测试过 7 个号称“开箱即用”的 Local Agent 框架，其中 5 个在默认配置下会开启 debug 日志并监听公网地址。安全不是功能开关，而是每行代码的意图确认。

2.2 Ollama 与 LangGraph 的耦合逻辑：为什么非得是这对组合？

市面上有太多替代方案：Llama.cpp 直接调用、Text Generation WebUI、甚至自建 vLLM 集群。但当我们为 Legal Sentinel 设计架构时，最终锁定 Ollama + LangGraph，核心基于三个不可替代的工程现实：
  首先是资源调度的确定性。
Ollama 的   ollama run  命令背后是 cgroups v2 的硬性内存限制。比如   OLLAMA_NUM_GPU=1 OLLAMA_GPU_LAYERS=40 ollama run llama3:70b  ，它会精确将 GPU 显存划分为 40 层，剩余显存留给系统缓冲。而 vLLM 虽然吞吐高，但其   --max-num-seqs  参数在面对长文档（如 200 页 PDF 解析后生成的 15k token prompt）时，会触发动态 batch 扩容，导致显存峰值飙升 300%，最终 OOM。我们实测过：同一台 A100 40GB 服务器，Ollama 处理 150 页并购协议平均耗时 42 秒，内存波动控制在 ±1.2GB；vLLM 在相同负载下，第 3 次请求就触发 OOM killer。这种确定性对法务场景至关重要——你不能让一份待审合同在“第 7 次重试时才成功”。
  其次是 LangGraph 的 stateful routing 能力。
Legal Sentinel 不是线性 pipeline：它需要根据文档类型（NDA/SA/MSA）动态选择解析策略，还要在发现“管辖法律为英国法”时，自动跳转至专门训练的 UK-Compliance 子图。LangGraph 的   ConditionalEntryPoint  节点能用纯 Python 逻辑实现这种路由，且 state 可跨子图传递。对比之下，Apache Airflow 的 DAG 必须预定义所有分支，而 Prefect 的 conditional task 在失败重试时会丢失上下文。我们曾用 LangGraph 实现一个“条款冲突检测器”：当   ClauseExtractor  节点输出“付款周期：30天”与   JurisdictionChecker  节点输出“适用法律：德国”时，   ConflictResolver  节点会自动检索《德国民法典》第362条，生成“建议修改为‘付款周期：21天’以符合德国商业惯例”的修正建议——这个能力依赖于 state 中   jurisdiction_code  和   payment_term_days  两个字段的实时联动，而 LangGraph 的   add_edge  方法能确保这种联动不被异步任务打乱。
  最后是运维可观测性的妥协艺术。
Ollama 提供   /api/tags  、   /api/ps  等原生 API，能直接获取模型加载状态、GPU 利用率、当前并发请求数；LangGraph 的   get_state_history  方法则能导出任意节点的输入/输出快照。这两者结合，让我们能用 Prometheus 抓取指标，用 Grafana 绘制“单文档处理耗时 vs 内存占用”热力图。而 Text Generation WebUI 的 metrics 是黑盒，Llama.cpp 的 stats 需要 patch 源码。在客户要求的 SLA 报告中，我们必须提供“99.9% 的合同解析请求在 60 秒内完成，且 95% 的请求内存占用 < 12GB”——这个数字只能来自 Ollama + LangGraph 的原生指标链。
3. 核心细节解析：Legal Sentinel 的五个关键模块实现

3.1 文档预处理模块：PDF 解析的精度陷阱与绕过方案

Legal Sentinel 的第一个环节不是 AI，而是 PDF 解析。这里有个残酷现实：99% 的开源 PDF 解析库（PyMuPDF、pdfplumber、pypdf）在处理扫描件（scanned PDF）时，会把整页当作一张图片丢给 OCR，导致表格错位、页眉页脚混入正文、甚至将“附件一”识别成“附件 1”。我们曾收到一份客户提供的采购合同，其附件中的价格表被 pdfplumber 解析为 127 行无结构文本，而人工校对发现实际只有 8 行有效数据。
解决方案是分层解析策略，且   所有解析步骤必须在 Ollama 模型加载前完成 ，避免污染模型 context：

•     格式判别层      ：用       pdfminer.high_level.extract_text      快速读取 PDF 的文本层（text layer）。如果返回空字符串或长度 < 100 字符，则判定为 scanned PDF，跳转至 OCR 流程；否则进入结构化解析。  
  
•     结构化解析层      ：对 text-based PDF，使用       pdfplumber      的       extract_tables()      方法提取所有表格，但关键技巧是       禁用自动合并单元格      ：       table_settings={"vertical_strategy": "lines", "horizontal_strategy": "lines", "snap_tolerance": 3}      。我们发现，当       snap_tolerance      设为 5 时，pdfplumber 会错误合并相邻表格的边框，导致价格表与规格表混在一起。这个参数值是通过测试 37 份不同格式的合同 PDF 后确定的最优解。  
  
•     OCR 层      ：对 scanned PDF，放弃 Tesseract 的默认配置。我们定制了一个       tessdata      子集，仅包含       eng.traineddata      和       osd.traineddata      （用于方向检测），并强制       --psm 6      （假设为单栏文本）。更重要的是，       OCR 前必须做图像预处理      ：用 OpenCV 对 PDF 页面进行二值化（       cv2.THRESH_OTSU      ）和去噪（       cv2.fastNlMeansDenoisingColored      ），实测将 OCR 准确率从 72% 提升至 94.3%。所有预处理代码封装为       preprocess_pdf.py      ，并通过       subprocess.run      调用，确保与 Ollama 进程完全隔离。  
  

  注意：不要在 LangGraph 的 node 里直接调用 OCR。我们曾因在     DocumentParserNode    中嵌入     pytesseract.image_to_string    ，导致每次 OCR 调用都 fork 新进程，内存泄漏累积 4 小时后达 18GB。正确做法是预处理作为独立服务，输出 JSON 结构化结果，LangGraph 只消费该 JSON。

3.2 法律条款抽取模块：Prompt 工程的物理约束

Ollama 模型的上下文窗口是硬边界。   llama3:70b  在 Ollama 中默认最大 context 为 8192 tokens，但实际可用空间远小于此——因为 Ollama 的 system prompt、LangGraph 的 state 序列化开销、以及我们自定义的 few-shot examples 都要占位。Legal Sentinel 的条款抽取 prompt 必须满足三个物理约束：

•    总长度 ≤ 6500 tokens    （预留 1692 tokens 给响应）
  
•    few-shot examples ≤ 3 个    （每个 example 平均占用 420 tokens）
  
•    输出格式必须是严格 JSON Schema    （避免模型自由发挥导致解析失败）
  

我们最终采用的 prompt 结构如下（已脱敏）：

1. 你是一名资深公司律师，正在审查一份商业合同。请严格按以下 JSON Schema 输出结果，不要任何额外文字：
2. {
3.   "contract_type": "string, 可选值: ['NDA', 'SA', 'MSA', 'SPA']",
4.   "key_clauses": [
5.     {
6.       "clause_id": "string, 如 'CLAUSE_3.2.a'",
7.       "clause_title": "string",
8.       "obligation_party": "string, 可选值: ['Buyer', 'Seller', 'Both']",
9.       "deadline_days": "integer, 若无明确天数则为 null",
10.       "penalty_clause": "boolean"
11.     }
12.   ],
13.   "red_flags": [
14.     {
15.       "flag_id": "string, 如 'RF_7.1'",
16.       "description": "string",
17.       "severity": "string, 可选值: ['High', 'Medium', 'Low']"
18.     }
19.   ]
20. }
22. 以下是合同正文（已去除页眉页脚）：
23. {document_text}
25. 请开始输出 JSON：

复制代码

关键技巧在于   obligation_party  字段的枚举值设计。最初我们写的是   ["甲方", "乙方", "双方"]  ，但模型在处理英文合同（如 "Party A", "Party B"）时经常混淆。改为   "Buyer"/"Seller"  后，准确率从 68% 跃升至 91.5%，因为 Llama3 的训练语料中，   Buyer/Seller  的共现频率远高于中文术语。
3.3 风险分析模块：领域知识注入的两种路径

单纯靠 prompt 注入法律知识效果有限。我们采用了混合知识注入策略：
  路径一：RAG 增强（针对通用条款）
构建一个本地向量库，收录《民法典》《公司法》《数据安全法》等法规全文，以及 200+ 份典型判例摘要。但关键创新在于 embedding 模型的选择：不用通用的 all-MiniLM-L6-v2，而是用   BAAI/bge-small-zh-v1.5  （专为中文法律文本优化），并在 chunking 时采用   语义分块 ：以“第X条”、“（一）”、“1.” 为分割符，而非固定 token 数。实测显示，对“违约金过高”的查询，语义分块召回的相关法条准确率比滑动窗口高 41%。
  路径二：LoRA 微调（针对客户特有风险）
某医疗器械客户要求识别“临床试验数据归属权”条款。标准法律大模型对此泛化能力弱。我们用 LoRA 对   llama3:8b  进行轻量微调：收集客户过去 3 年签署的 47 份临床试验协议，标注出 129 处相关条款，构造 instruction 数据集。微调仅需 1.2 小时（A100 40GB），LoRA 权重仅 18MB。部署时，Ollama 的   Modelfile  支持   ADAPTER ./lora-adapter  指令，无缝集成。效果是：对新合同中“数据所有权归申办方所有”这类表述，识别 F1 分数从 0.33 提升至 0.89。

  实操心得：RAG 适合广度，LoRA 适合深度。我们给客户交付的 Legal Sentinel 系统中，RAG 库每月更新一次法规，LoRA 适配器每季度根据新签合同迭代一次，形成“法规层稳定、客户层进化”的双轨机制。

3.4 合规检查模块：规则引擎与大模型的协同边界

很多人误以为大模型能替代规则引擎。实际上，在 Legal Sentinel 中，我们划定了清晰的协同边界：

•     规则引擎负责：   
  
  
  
  •     条款存在性检查（如“必须包含不可抗力条款”）
    
  •     格式合规（如“签字页必须有骑缝章”）
    
  •     数值阈值（如“违约金不得超过合同总额30%”）
    
  
  
•     大模型负责：   
  
  
  
  •     条款语义解释（如“本协议终止后，保密义务持续5年”是否覆盖衍生数据）
    
  •     跨条款冲突检测（如“管辖法院：上海”与“适用法律：新加坡法”的冲突）
    
  •     自然语言生成（如将“乙方应于收到发票后30日内付款”改写为“付款期限：发票开具日起30个自然日”）
    
  
  

规则引擎用 Python 的   jsonpath-ng  实现，对 JSON 输出的   key_clauses  数组进行遍历。例如检查违约金条款：

1. from jsonpath_ng import parse
2. from jsonpath_ng.ext import parse as ext_parse
4. # 查找所有 penalty_clause=True 的条款
5. jsonpath_expr = parse('$.key_clauses[?(@.penalty_clause == true)]')
6. matches = [match.value for match in jsonpath_expr.find(state)]
7. for clause in matches:
8.     # 提取金额描述文本
9.     amount_text = clause.get('description', '')
10.     # 用正则匹配百分比
11.     percent_match = re.search(r'(\d+)%', amount_text)
12.     if percent_match and int(percent_match.group(1)) > 30:
13.         state['compliance_issues'].append({
14.             'type': 'EXCESSIVE_PENALTY',
15.             'clause_id': clause['clause_id'],
16.             'suggestion': '建议修改为不超过合同总额30%'
17.         })

复制代码

这种分工让系统既保持规则的确定性，又保留模型的灵活性。上线半年来，规则引擎拦截了 100% 的数值违规，而大模型发现了 23 起规则引擎无法识别的语义冲突。
3.5 报告生成模块：可控性与专业性的平衡术

最终输出的法律意见报告，必须满足两个矛盾需求：法务部要求格式绝对规范（字体、标题层级、页眉页脚），而业务部门希望重点信息一目了然（高亮风险、折叠细则）。我们的方案是：   用 Jinja2 模板 + Markdown 渲染 + PDF 转换 。
模板   report.j2  定义了结构：

1. # {{ contract_title }} 法律审查报告
2. **生成时间：** {{ now | datetimeformat }}
4. ## 一、核心风险摘要
5. {% for flag in state.red_flags %}
6. - ⚠️ **{{ flag.severity }} 风险：** {{ flag.description }}  
7.   *建议：* {{ flag.suggestion }}
8. {% endfor %}
10. ## 二、详细条款分析
11. {% for clause in state.key_clauses %}
12. ### {{ clause.clause_title }} ({{ clause.clause_id }})
13. - **责任方：** {{ clause.obligation_party }}
14. - **截止日期：** {{ clause.deadline_days or '无明确期限' }}
15. {% endfor %}

复制代码

关键技巧在于   datetimeformat  过滤器的实现：

1. def datetimeformat(value, format='%Y年%m月%d日 %H:%M'):
2.     if isinstance(value, str):
3.         # 处理 ISO 格式字符串
4.         value = datetime.fromisoformat(value.replace('Z', '+00:00'))
5.     return value.strftime(format)

复制代码

这确保了即使 LangGraph 的 state 中时间字段是字符串，也能正确渲染。报告生成后，用   weasyprint  转为 PDF，其 CSS 支持   @page { margin: 2cm; }  精确控制页边距，满足法务归档要求。
4. 实操全流程：从零部署 Legal Sentinel 的 12 个关键步骤

4.1 硬件准备与系统调优

Legal Sentinel 对硬件有明确物理要求，不是“能跑就行”：

组件	最低要求	推荐配置	关键原因
CPU	16 核	32 核 (AMD EPYC 7763)	PDF 解析、OCR、文本预处理均为 CPU 密集型，多核并行提升 3.2x 吞吐
内存	64GB	128GB DDR4 ECC	Ollama 加载 70B 模型需 ~45GB，LangGraph state + OS 缓冲需 ≥30GB，ECC 内存防 bit-flip 导致法律文本错字
GPU	1×A100 40GB	2×A100 40GB	单卡处理 70B 模型时，         OLLAMA_GPU_LAYERS=40        会吃满显存，双卡可启用         OLLAMA_NUM_GPU=2        实现模型层分片，降低单卡压力
存储	2TB NVMe SSD	4TB RAID1 NVMe	模型文件（70B GGUF 约 42GB）、向量库（10GB）、日志（日均 5GB）需高 IOPS，RAID1 防止单盘故障导致合同解析中断

  系统级调优必须执行：

•   禁用 swap：     sudo swapoff -a && sudo sed -i '/swap/d' /etc/fstab    （避免 OOM 时 swap 到磁盘，导致法律文本解析超时）
  
•   调整 vm.max_map_count：     sudo sysctl -w vm.max_map_count=262144    （LangGraph 的 SQLite checkpointer 需大量内存映射）
  
•   设置 CPU 频率策略：     sudo cpupower frequency-set -g performance    （避免节能模式导致 OCR 耗时波动）
  

  注意：不要在虚拟机中部署。我们测试过 VMware ESXi 7.0，其 CPU 虚拟化开销导致 OCR 步骤耗时增加 22%，且     cpupower    命令在 VM 中无效。Legal Sentinel 必须裸金属部署。

4.2 Ollama 安装与模型定制

Ollama 官方安装脚本（   curl -fsSL https://ollama.com/install.sh | sh  ）在企业环境中存在风险：它会自动创建   ollama  用户并修改   systemd  配置。我们采用手动安装：

1. # 1. 下载二进制
2. wget https://github.com/ollama/ollama/releases/download/v0.3.10/ollama-linux-amd64
3. sudo mv ollama-linux-amd64 /usr/local/bin/ollama
4. sudo chmod +x /usr/local/bin/ollama
6. # 2. 创建专用用户（非 root）
7. sudo useradd -r -s /bin/false -d /opt/ollama ollama
8. sudo mkdir -p /opt/ollama/models
9. sudo chown -R ollama:ollama /opt/ollama
11. # 3. 创建 systemd 服务（/etc/systemd/system/ollama.service）
12. [Unit]
13. Description=Ollama Service
14. After=network.target
16. [Service]
17. Type=simple
18. User=ollama
19. WorkingDirectory=/opt/ollama
20. ExecStart=/usr/local/bin/ollama serve
21. Restart=always
22. RestartSec=3
23. Environment="OLLAMA_HOST=127.0.0.1:11434"
24. Environment="OLLAMA_NUM_GPU=1"
25. Environment="OLLAMA_GPU_LAYERS=40"
26. # 关键：禁用日志
27. Environment="OLLAMA_LOG_LEVEL=error"
29. [Install]
30. WantedBy=multi-user.target

复制代码

启动后，验证模型加载：

1. # 拉取基础模型（不带量化）
2. ollama pull llama3:8b
4. # 创建 Legal Sentinel 专用模型
5. cat <<EOF > Modelfile
6. FROM https://huggingface.co/bartowski/llama-3-instruct-GGUF/resolve/main/llama-3-instruct.Q5_K_M.gguf
7. ADAPTER ./lora-legal-sentinel.bin
8. SYSTEM """
9. 你是一名资深公司律师，正在审查商业合同。请严格按 JSON Schema 输出，不要任何额外文字。
10. """
11. PARAMETER num_ctx 8192
12. PARAMETER num_gpu 40
13. EOF
15. ollama create legal-sentinel -f Modelfile

复制代码

4.3 LangGraph 环境构建与依赖锁定

LangGraph 的版本兼容性极敏感。我们锁定以下组合（经 6 个月生产验证）：

1. langchain==0.2.11
2. langchain-community==0.2.9
3. langgraph==0.2.45
4. langchain-core==0.2.26

复制代码

安装命令：

1. pip install --no-cache-dir \
2.   langchain==0.2.11 \
3.   langchain-community==0.2.9 \
4.   langgraph==0.2.45 \
5.   langchain-core==0.2.26 \
6.   pypdf==4.2.0 \
7.   pdfplumber==0.11.5 \
8.   weasyprint==64.0 \
9.   opencv-python-headless==4.10.0.84

复制代码

关键点：   opencv-python-headless  替代   opencv-python  ，避免 GUI 依赖导致容器化失败；   weasyprint==64.0  是最后一个支持   @page  CSS 的稳定版。
4.4 Legal Sentinel 核心代码实现

  legal_sentinel.py  主程序结构：

1. from langgraph.graph import StateGraph, END
2. from langgraph.checkpoint.sqlite import SqliteSaver
3. from typing import TypedDict, List, Dict, Any
4. import sqlite3
6. # 1. 定义 State
7. class LegalState(TypedDict):
8.     document_text: str
9.     contract_type: str
10.     key_clauses: List[Dict[str, Any]]
11.     red_flags: List[Dict[str, Any]]
12.     compliance_issues: List[Dict[str, Any]]
13.     report_html: str
15. # 2. 初始化 Checkpointer（关键：SQLite 文件路径必须可写）
16. conn = sqlite3.connect("/opt/ollama/checkpoints/legal-sentinel.db")
17. checkpointer = SqliteSaver(conn)
19. # 3. 构建 Graph
20. workflow = StateGraph(LegalState)
22. # 添加节点
23. workflow.add_node("preprocess", preprocess_node)
24. workflow.add_node("extract_clauses", extract_clauses_node)
25. workflow.add_node("analyze_risks", analyze_risks_node)
26. workflow.add_node("check_compliance", check_compliance_node)
27. workflow.add_node("generate_report", generate_report_node)
29. # 添加边
30. workflow.set_entry_point("preprocess")
31. workflow.add_edge("preprocess", "extract_clauses")
32. workflow.add_edge("extract_clauses", "analyze_risks")
33. workflow.add_edge("analyze_risks", "check_compliance")
34. workflow.add_edge("check_compliance", "generate_report")
35. workflow.add_edge("generate_report", END)
37. # 编译
38. app = workflow.compile(checkpointer=checkpointer)

复制代码

preprocess_node  的核心逻辑：

1. def preprocess_node(state: LegalState) -> LegalState:
2.     # 1. PDF 判别
3.     try:
4.         text = extract_text(state["document_path"])
5.         if len(text.strip()) < 100:
6.             # 调用 OCR 服务（独立进程）
7.             result = subprocess.run(
8.                 ["python3", "/opt/ollama/ocr_service.py", state["document_path"]],
9.                 capture_output=True,
10.                 text=True,
11.                 timeout=300  # 5分钟超时
12.             )
13.             state["document_text"] = result.stdout
14.         else:
15.             # 结构化解析
16.             with pdfplumber.open(state["document_path"]) as pdf:
17.                 full_text = ""
18.                 for page in pdf.pages:
19.                     full_text += page.dedupe_chars().extract_text() or ""
20.                 state["document_text"] = full_text
21.     except Exception as e:
22.         raise RuntimeError(f"Preprocessing failed: {str(e)}")
23.    
24.     return state

复制代码

4.5 API 服务封装与安全加固

用 FastAPI 封装 LangGraph，但   绝不暴露 LangGraph 原生接口 ：

1. from fastapi import FastAPI, HTTPException, Depends
2. from pydantic import BaseModel
3. import secrets
5. app = FastAPI()
7. # 生成 API Key（非 JWT，避免密钥管理复杂度）
8. API_KEY = secrets.token_urlsafe(32)  # 存入环境变量，重启不变
10. class ContractRequest(BaseModel):
11.     file_base64: str
12.     filename: str
14. @app.post("/v1/legal-review")
15. async def legal_review(request: ContractRequest, api_key: str = Depends(get_api_key)):
16.     # 1. 文件解码与临时存储
17.     try:
18.         file_data = base64.b64decode(request.file_base64)
19.         temp_path = f"/tmp/{secrets.token_hex(8)}.pdf"
20.         with open(temp_path, "wb") as f:
21.             f.write(file_data)
22.     except Exception:
23.         raise HTTPException(status_code=400, detail="Invalid base64 encoding")
24.    
25.     # 2. 调用 LangGraph
26.     try:
27.         result = app.invoke({
28.             "document_path": temp_path,
29.             "document_text": ""
30.         }, config={"configurable": {"thread_id": secrets.token_hex(16)}})
31.         
32.         # 3. 清理临时文件
33.         os.unlink(temp_path)
34.         
35.         return {
36.             "status": "success",
37.             "report_pdf": base64.b64encode(result["report_pdf"]).decode()
38.         }
39.     except Exception as e:
40.         os.unlink(temp_path)
41.         raise HTTPException(status_code=500, detail=str(e))
43. # API Key 验证依赖
44. async def get_api_key(x_api_key: str = Header(...)):
45.     if x_api_key != API_KEY:
46.         raise HTTPException(status_code=403, detail="Forbidden")
47.     return x_api_key

复制代码

Nginx 反向代理配置（   /etc/nginx/conf.d/legal-sentinel.conf  ）：

1. upstream legal_sentinel {
2.     server 127.0.0.1:8000;
3. }
5. server {
6.     listen 443 ssl;
7.     server_name legal-sentinel.internal;
9.     ssl_certificate /etc/ssl/certs/legal-sentinel.crt;
10.     ssl_certificate_key /etc/ssl/private/legal-sentinel.key;
12.     location /v1/legal-review {
13.         proxy_pass http://legal_sentinel;
14.         proxy_set_header Host $host;
15.         proxy_set_header X-Real-IP $remote_addr;
16.         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
17.         client_max_body_size 50M;  # 限制上传大小
18.         limit_req zone=legalburst burst=5 nodelay;  # 限流
19.     }
20. }

复制代码

4.6 压力测试与性能基线

我们用 Locust 编写测试脚本，模拟法务部日常负载：

1. from locust import HttpUser, task, between
2. import base64
4. class LegalUser(HttpUser):
5.     wait_time = between(5, 15)
6.    
7.     @task
8.     def review_contract(self):
9.         # 读取预存的 PDF（120 页，含表格）
10.         with open("test_contract.pdf", "rb") as f:
11.             content = base64.b64encode(f.read()).decode()
12.         
13.         self.client.post(
14.             "/v1/legal-review",
15.             json={"file_base64": content, "filename": "test.pdf"},
16.             headers={"X-API-Key": "your-api-key"}
17.         )

复制代码

在 32 核/128GB/2×A100 环境下，测试结果：

并发用户数	平均响应时间	95% 响应时间	错误率	CPU 平均利用率	GPU 显存占用
1	42.3s	45.1s	0%	48%	38.2GB
5	43.7s	48.9s	0%	62%	38.2GB
10	45.2s	52.4s	0.3%	79%	38.2GB
20	58.6s	73.1s	12.7%	98%	38.2GB

结论：系统在 10 并发下稳定，SLA（60 秒内）达标率 100%。错误率突增源于 CPU 达到瓶颈，而非 GPU。因此，横向扩展应优先加 CPU 节点，而非 GPU。
5. 常见问题与排查技巧实录

5.1 典型问题速查表

问题现象	根本原因	排查命令	解决方案
ollama list        显示模型但         ollama run legal-sentinel        报错         model not found	Ollama 服务未加载自定义模型，或 Modelfile 中         FROM        URL 不可达	journalctl -u ollama -n 50 --no-pager	检查 journal 日志中的         pulling model        行；若失败，手动         curl -I        测试 URL 可达性；改用本地文件 `FROM ./models/llama-3.Q5_K_M

原文地址：https://blog.csdn.net/weixin_30388285/article/details/161847774