企业官网建设流程全解析

去年年中，我接手公司内一个“跑不动”的法律咨询平台。说跑不动，不是业务增长的问题，而是技术上已经顶不住了：意图识别、法条检索、文书生成全揉在一个单体进程里，用户一多接口就超时，律师团队又催着上“AI合同审查”，旧架构改起来伤筋动骨。后来我们花了三个月把系统拆成一组法律AI智能体微服务，合同审查从单份一小时压缩到十分钟以内，普通法律咨询从排队一小时变成秒级响应。这篇文章我把自己从方案设计到落地踩坑的过程完整复盘一遍，重点讲法律领域微服务怎么拆、接口怎么定、链路怎么调，给正在做同类系统的架构师和研发团队一个可抄作业的参考。

1. 为什么法律AI非拆不可

1.1 单体系统的三个典型瓶颈

先说原来的样子。老系统是个单体应用，Python写的，一个进程里塞了三个大模块：

• 对话模块：处理用户提问，调用一个文本分类模型识别意图。
• 知识库模块：内置法律条文和案例数据，用关键词方式做检索。
• 文书生成模块：根据用户选择模板生成咨询建议，本质是填模板。

一开始能用，是因为量小。律师端每天也就几百个请求，一个8核机器就扛住了。可业务起来之后，问题开始暴露。

第一个瓶颈是模型升级牵一发动全身。我们想升级意图识别模型，换一个效果更好的预训练模型，结果发现代码里到处都在调用旧模型接口，日志格式、缓存字段、甚至数据库里有几个表都跟模型版本绑死。想灰度，做不了，只能整体替换。一次升级要全链路回归，两周才能上线。

第二个瓶颈更致命：故障放大。有一次法条检索模块因为数据源连接池被占满，导致整个服务卡住，连登录页都打不开。用户没问法条，也会被拖死。这就是单体架构最典型的“雪崩”——一个模块的偶发故障，吞掉整个系统可用性。

第三个瓶颈是资源无法按需伸缩。法律文书生成是计算密集型的，推理要消耗大量CPU；但普通信息咨询主要吃内存和网络。在单体里，这两类负载互相干扰。为了应对高峰期的文书生成，我们只能把整台机器扩容，等于所有模块一起升配，成本高得离谱。

1.2 法律领域微服务拆分的两个核心原则

聊微服务，很多团队容易陷入一个误区：按“页面”或“功能菜单”拆，拆出一个“用户服务”“合同服务”“咨询服务”。这种拆法表面整齐，实际上把内聚性破坏了。我们最后是按专业能力域拆的，有两个原则帮了大忙。

原则一：按“业务能力边界”拆，不按“屏幕页面”拆。法律AI智能体本质上要做几件事：看懂用户意图、检索法律知识、审查文件、生成文书、评估风险。这几件事各自的输入输出、数据模型、性能特征都不太一样，把它们拆成独立服务，边界才清楚。比如“合同审查”和“文书生成”，页面上一进一出，但其实一个是要做结构化分析和风险点抽取，一个是按模板渲染长文本，一个前段重、一个后段重，混在一起后期会很痛苦。

原则二：数据资产跟着服务走。法律领域数据敏感，客户合同、咨询记录、法条知识库最好隔离存放。微服务的好处是把“客户业务数据”和“领域知识数据”分开存储，访问权限独立控制。合同审查服务只能读客户授权的合同文件，RAG检索服务只能访问知识库数据。即使某个服务被拖库，也不至于把全量数据泄露出去。

用律所来类比就很好理解：一家大律所不会让一个律师从头到尾包办所有案子。主任负责接案判断，专业合伙人负责具体领域，助理负责检索和文书，档案室负责管理案卷材料。微服务就是把这套专业分工数字化了。每个服务做自己的专业活，通过标准接口协作。

2. 法律AI智能体的整体架构与核心服务清单

2.1 整体调用链路

我们最后落地的架构是典型的分层加中台思路，从外到内四层：

• 接入层：统一API网关，负责鉴权、限流、路由。
• 编排层：法律智能体编排服务，是整个系统的“大脑”。
• 服务层：意图识别、RAG检索、合同审查、文书生成、合规评估、审计日志等专业微服务。
• 数据层：知识库向量库、结构化数据、文档存储、缓存、消息队列。

一次合同审查请求的链路大概是这样的：用户在界面里传一份PDF合同，前端把文件交给网关，网关鉴权通过后转给编排服务。编排服务先调用文件解析服务把PDF转成结构化正文，同时并行调用意图识别服务确认用户要的是“合同审查”而不是“法律咨询”。确认后，编排服务把合同文本拆成多个切片，丢给RAG检索服务，让它把相关的法律条文和过往审查规则召回出来。再往后，编排器把所有中间结果交给合同审查服务做风险点识别，最后调用文书生成服务生成一份带风险等级和建议的审查报告。整个过程走完，编排服务把报告回传给前端。

链路本身看着不复杂，难在每一步都可能失败，所以编排服务必须有超时控制、重试和状态管理。

2.2 七大核心微服务职责清单

整理一个表格，方便对照：

这些服务不是固定的，我们后来还加了“电子签章对接服务”和“案件管理对接服务”。但核心七件套已经覆盖了日常90%以上的法律AI场景。

2.3 服务间通信方式：异步优先

服务间通信，我们一开始是清一色的同步HTTP调用，后来吃了大亏。合同审查一次推理要十几秒，前端一直等待；某个服务抖动，上游全部堆积。后来改成了“同步适配层+异步核心链路”的混合模式。

对外交互全部走同步接口，保证调用方体验；内部耗时操作全部异步化，通过消息队列传递任务。比如合同审查服务收到任务后，立刻返回一个“任务已受理”的响应，含任务ID；真正的解析、检索、审查在后台跑，完成后写回任务状态表，前端轮询或者通过WebSocket推送结果。这样好处是：单次请求响应时间稳定，用户不会因为后台负载高而白等。

3. 几个关键模块的实现细节

3.1 意图识别服务：法律场景下的“翻译官”

意图识别是整个法律AI智能体的入口，所有下游任务都取决于它判断准不准。我们采用的方案是“意图分类模型+槽位抽取模型+规则辅助”的三层结构。

分类模型负责判断用户的请求属于哪类任务，备选意图包括：法律咨询、合同审查、文书生成、风险评估、流程查询、闲聊。模型用的是领域微调过的预训练文本分类模型，训练数据来自人工标注的真实对话和历史工单。槽位抽取向导负责从用户原话里抽关键参数，比如审查对象、合同期限、乙方主体名称等。

有个容易被忽略的点：法律用户的话非常口语化，里面还夹杂大量专业名词的别名。比如“帮我看下这个协议有没有坑”，“看下”对应的是“审查”，“协议”对应的是“合同”。如果意图识别模型只做文本分类，这种隐含意图就丢了。所以我们的分类模型下面挂了同义词典和纠错组件，把“看坑”“把关”“瞅瞅”这类表达统一映射到“合同审查”意图。

槽位抽取我们走了两步：先用轻量规则从原文里捞直接信息，比如合同主体、日期；再用序列标注模型识别更复杂的依赖关系。规则和模型的结果做一次融合，取置信度更高的那个。接口设计上，意图识别服务只回传JSON结构，不碰任何业务逻辑，保持纯粹。

3.2 RAG检索服务：知识库怎么“喂”给大模型

法律AI智能体离不开RAG，因为大模型原生参数里没有最新的、细粒度的法律条文数据。直接让模型凭空输出，很容易一本正经地编造法条。RAG的思路是先检索出相关的知识片段，再让模型基于片段做理解和生成，等于给模型配了一个随查随取的“法条档案室”。

具体实现上，我们把法律条文、司法解释、典型案例、内部审查规则全部文本化之后，做切片，送入向量库。切片大小我们调试了很久，最后定在512字符左右，重叠32字符。这是因为法律条文结构特殊，一条完整法条可能几百字，切太细容易把“但书”切断，切太粗又会导致召回精度下降。除了向量检索，我们还保留了一个关键词索引做BM25检索，最终用混合召回排序。单纯向量检索在专业术语上有天然的劣势，“不可抗力”被向量化后可能跑去关联“自然灾害”之类的词，而BM25能精准命中关键词。

RAG服务返回的结果也不是简单的TopK片段，而是带有来源编号的片段列表。每个片段都标注了“传播来源”“发布机构”“生效状态”，这是法律场景特有的要求。下游合同审查服务在引用这些片段时，必须带上来源，保证整个结论可溯源。

重排序我们用的是交叉编码器，效果比双塔模型好不少。代价是慢，所以只对召回前20条做重排，取前5条进上下文。上下文窗口有限，每一分空间都要花在刀刃上。

3.3 文书生成服务：异步任务与模板约束

文书生成服务是所有服务里最敏感的，因为生成结果直接面向当事人，错了会产生严重的信任危机。我们的处理原则是“不裸奔”：先在编排层把审查结果结构化，文书生成服务只负责把结构化结果渲染成自然语言，不直接让模型自由发挥。

有个具体的做法：定义一套轻量模板协议，把法律意见书拆成“事实认定—法律依据—分析推理—结论建议”四个段落。模型只填充每个段落的细节内容，段落骨架和引用规范由模板约束。这样能避免模型出现结构混乱、引用不存在的法条等问题。

文书生成往往耗时最长，所以我们用异步任务的方式接入。服务内部维护任务队列，每个任务有独立的模型调用配置和超时时间。生成完毕后，结果先落库，再触发通知。这个设计在线上撑住了高峰期几百并发，没有丢失过任务。

3.4 审计服务：法律AI“可解释性”的底线

法律场景对可解释性要求极高。用户问“为什么得出这个结论”，系统不能只回复“模型算的”。我们的做法是让审计服务记录每一次全链路调用的上下文快照，包括：

• 用户原始输入和清洗后的输入；
• 意图识别结果和置信度；
• RAG召回了哪些片段、每个片段的来源和排序分数；
• 生成模型用了哪个供应商、哪个版本、温度参数是多少；
• 最终输出内容。

这一套快照在出问题时可以完整回放。人工复核环节也因此有了材料：律师在复核AI生成的审查报告时，能直接打开每一条结论下的“依据片段”，确认AI没有瞎编。可以说，没有审计服务，法律AI根本没有上线的入场券。

4. 从0到1搭建：实操过程复盘

4.1 项目目录结构与服务骨架

具体落地时，我们用了仓库先行、目录统一的策略。每个微服务独立仓库，但外层总仓库里放一份公共的接口契约和部署编排文件：

legal-ai-agent/ ├── api-gateway/ # 统一网关，负责鉴权和限流 ├── orchestrator/ # 编排服务，工作流状态机 ├── services/ │ ├── intent-service/ # 意图识别 │ ├── rag-service/ # RAG检索 │ ├── contract-review/ # 合同审查 │ ├── document-generation/ # 文书生成 │ ├── compliance-check/ # 合规评估 │ └── audit-service/ # 审计日志 ├── contracts/ # OpenAPI契约文件 ├── deploy/ │ ├── docker-compose.yml # 开发环境 │ └── k8s/ # 生产环境编排 └── shared/ ├── tracing/ ├── config/ └── error-codes/

shared目录里的内容是只读的公共配置，各服务打包时引用，发布后运行时不依赖。这里特别想强调一点：错误码体系一定要提前设计。跨服务调用时，如果每个服务自己定义一套错误码，排查问题时大脑直接爆炸。我们最后在shared里统一维护了一套错误码枚举，任何服务返回错误都带同一个code前缀，再拼子模块序号。这个不起眼的设计，省了后面多少晚上的on-call时间。

4.2 技术选型与依赖配置

技术选型上没有追新，选了一组经历过大规模验证的组件：

• 网关：开源API网关，负责JWT鉴权、接口限流、灰度路由。
• 编排器：自定义状态机 + Redis做会话状态存储。
• 消息队列：用可靠的消息中间件，异步任务流转的主通道。
• 向量库：支持混合检索的向量数据库，同时挂BM25索引和向量索引。
• 模型网关：自己封装了一层“模型提供方适配器”，底层对接多个大模型API和本地小模型。

模型网关是必须单独拎出来说的。法律项目里，同一个场景可能需要多个模型：意图识别用本地小模型，保证低延迟；文书生成长文本用大模型，追求质量；中间还可能穿插供应商切换。如果不做一个统一的模型接入层，业务代码里就会散落第三方SDK的调用，后续换供应商等同于重构。我们用OpenAI兼容协议作为内部统一协议，每个供应商写一个适配器，把差异封装在模型网关内部。业务服务只拿来调用，根本不知道背后是哪个模型。

4.3 一次合同审查请求的端到端实现

拿合同审查这条主链路做个端到端拆解，每一步的要点写清楚。

第一步：上传与解析。用户上传PDF，文件解析服务用内容提取工具把PDF转成文本。坑点：扫描件要先做OCR，否则全是图片数据。我们在解析服务里内置了OCR开关，针对质量差的扫描件自动增强。

第二步：任务创建与异步化。前端调用编排服务的“提交审查任务”接口，编排器创建任务记录，状态设为pending，然后往消息队列发一条消息。接口立即返回任务ID，前端进入轮询。

第三步：并行召回。任务处理器收到消息后，并行执行三件事：调用意图识别服务确认“合同审查”意图；调用RAG服务检索相关法条；调用合规评估服务预检合同中的重点合规项。三件事相互独立，并行处理把整体延迟压低。

第四步：风险识别。三路返回后，编排器把数据和召回片段拼接成格式化的输入，交给合同审查服务。这一步是整个链路里最吃计算资源的，我们把它单独放了一个Pod，设置了独立的自动伸缩策略，高峰自动扩容。

第五步：文书生成与回传。合同审查服务输出结构化风险点列表后，编排器调用文书生成服务，生成带风险等级、条款摘要和合规建议的审查报告。这个报告落库后，任务状态更新为completed，前端收到通知，自动跳到报告页。

整个链路我们实测从上传到结果展示，平均耗时10分30秒左右，其中模型推理占了七成时间。对比人工审查的一小时起步，提升确实明显。

4.4 效率量化与资源账单

上线三个月后的数据，我们做了一个对比：

成本上，因为按服务维度独立扩缩容，高峰期只需要单独扩容合同审查和RAG服务，CPU总核数比原来整体扩容少了35%左右。省下来的资源，我们换成了给审计服务多配了两台机器，让全链路日志的保留周期从7天延长到30天。

5. 落地过程中踩过的高频坑与排查实录

5.1 超时、重试与幂等：AI服务的特殊性

跨服务调用，超时和重试是必修课，但AI服务和普通业务有个重要区别：模型推理有随机性，结果不稳定。普通业务里重试通常没问题，但AI服务里，同一个请求重发两次，模型可能给出不同结果。如果重试前没做幂等判断，轻则浪费算力，重则把错误结果覆盖正确结果。

我们的做法是：每个外部请求在编排层生成一个全局唯一的traceId，发到下游服务时带上。下游服务在处理前先查任务状态表，如果任务已经存在且状态不是pending，直接返回旧结果。另外超时时间做了分层：HTTP层3秒，模型调用层30秒，异步任务层15分钟。不同层级用不同的超时上限，避免一刀切导致误判。

5.2 RAG召回不准：调了三个地方才解决

上线初期，法条召回的准确率惨不忍睹，用户问“公司单方面调岗合法吗”，召回结果里乱七八糟。排查下来是三个问题叠加。

第一个是切片方式不对。原来按固定字数切，很容易把一整条规则拦腰切断。后来改成“语义段落优先”：先按法律条文的编号段切，段太长再按句子组切，最坏情况才落到固定长度。

第二个是混合检索的权重没校准。纯向量检索在专业术语上会跑偏，我们把BM25的权重调高，对精确关键词命中的结果加权，效果立刻改善。

第三个是重排序模型和领域不匹配。换成在法律语料上微调过的交叉编码器后，Top5命中率提高了十来个点。这里也说明一个经验：预训练模型能不能直接用，要看语料领域。法律文本的表达习惯和通用文本差异巨大。

5.3 会话上下文丢失：Redis状态服务的补救

一开始编排服务是无状态的，用户的每一句话都独立处理，结果是上下文完全断裂。用户上一句说“帮我看看这份合同”，下一句问“那违约金比例呢”，系统根本不知道“违约金”是同一份合同里的条款。法律对话天然有强烈的指代关系，这个体验问题直接决定产品能不能用。

我们把会话状态抽出来，在Redis里维护session：包含当前审查任务ID、待确认参数、历史对话摘要、召回片段缓存。每一次请求进来，编排服务先恢复session，处理完再回写。为了避免状态无限膨胀，我们还给session设置了30分钟过期时间，并把过长的历史摘要压缩成固定长度的“对话要点”。

5.4 多模型供应商切换：模型网关的兜底能力

有一段时间主流大模型API很不稳定，时而限流时而超时。我们的模型网关设计了两个关键兜底：健康检查和动态路由。网关定时探测各供应商的耗时和错误率，超过阈值就自动把新请求切到备选供应商。这个切换对上层服务完全透明，业务方无感知。

还有个细节：不同供应商的定价差很多，模型网关还会记录任意模型调用的token成本。成本数据回传给审计服务后，我们能按意图、按客户维度分析账单。法律业务方对成本很敏感，这一层数据透明度让业务敢放开用AI。

5.5 灰度发布：只灰度一个服务如何不翻车

微服务架构最让人难受的就是灰度。一个接口链路跨了五六个服务，怎么在不影响整体的前提下，验证新版本意图识别服务？

我们把新旧两个版本都注册到同一个注册中心，网关层打开灰度路由开关，按用户ID灰度。灰度用户的新请求会走新版服务，其他用户走旧版。同时在编排层加了一个“结果对比模式”：灰度流量进入后，把结果同时发给新旧两个服务，只放行新版结果，旧版结果仅用于离线分析。这个影子模式跑了三周，确认新版准确率稳定超过旧版后再全量切换。

6. 写在最后的一点体会

这个项目做完，我最大的感触是：法律AI智能体能不能跑起来，瓶颈往往不在模型效果，而在工程架构。模型再准，单体扛不住流量，服务之间一抖就崩，照样没法落地。拆分微服务不是万能药，但我个人认为，只要遵守“按业务能力域拆、接口契约先行、异步化优先、全链路可审计”这四条，法律AI这类专业场景是会从中受益的。

如果你也在设计类似的法律AI智能体，我的建议是不要一上来就堆容器平台和几十个服务。先梳理清楚业务能力边界，把三个核心服务（意图识别、RAG检索、文书生成）串成最小闭环，跑通后再逐步扩展。每一步都做好审计和可回滚，微服务带来的复杂度是可控的。这套方法论，放到医疗、金融等同样要求专业性和可解释性的领域，我觉得也大概率适用。