Java 与 Python 模型服务协作
本篇要点:能把模型推理托管在 Python 服务、把鉴权与编排留在 Java 网关,并用 gRPC 契约、模型别名和隔离舱把两边边界划清楚。 前置文章:《MCP Server:让模型安全调用 Java 业务能力》让模型通过 MCP 调到了 Java 的业务能力,这一章处理相反的方向——当模型本身跑在 Java 之外,请求怎么过去、怎么回来。
为什么需要它
2025 年底,我参与过一个发票审核系统。财务的要求很直接:发票影像不能出内网。模型必须落在公司自己的 GPU 上,而业务系统是一套跑了六年的 Spring Boot 单体。
团队的第一反应是把模型搬进 JVM。DJL 试了两周,ONNX Runtime 试了一周,卡在三件事上:CUDA 版本和驱动对不上、tokenizer 依赖 Python 的 sentencepiece、显存碎片导致第二次加载就 OOM。三周之后,没有人敢说什么时候能跑通。
真正的问题不是「Java 能不能跑模型」,是「这个模型该由谁托管」。后来改成两段式:Python 用 FastAPI 加 vLLM 起一个 OpenAI 兼容的推理服务,Java 网关负责鉴权、拼 prompt、切流、记账。
改完第二天遇到第二个问题。Java 侧用 RestClient 直接调 /v1/chat/completions,超时设 60 秒。压测时 vLLM 排队到 90 秒,Java 侧 60 秒断开并重试,重试又进队列,队列更长。没有人配错参数,只是这条链路上没有任何一层说「我不等了,你自己降级」。
这一章解决的就是这两件事:边界画在哪里,以及边界两边的失败怎么不互相传染。
核心概念
分工线:按「谁持有权重」切
推理层(inference layer)指持有模型权重、占用 GPU 的进程。集成层(integration layer)指持有业务状态、做编排和鉴权的进程。
判断只需要一句话:要读模型文件、CUDA 上下文、tokenizer 的,放 Python;要读订单表、会话、权限的,放 Java。
反例很常见:把文档切分(chunking)放进 Python,理由是 embedding 模型在那儿。结果换一版切分规则就要发一次 Python 版本,而切分规则是业务规则,产品经理每周都在改。切分应该留在 Java,Python 只负责「给我一批文本,还我一批向量」。
如图 11-1,网关是唯一入口,Python 服务不直接对外,也不持有用户凭证。
图 11-1 请求路径与三条旁路:缓存、降级、模型别名映射
契约:proto 的字段编号一旦发布就不能复用
gRPC 用 .proto 定义消息和服务。每个字段有一个编号(field number),序列化时只传编号不传字段名。
类比:字段编号像数据库的列 ID。改字段名安全,因为编号没变;改编号等于换了一列,老客户端读到的是错位数据。
反例:有人把 model_version 从 string 改成 int,编号沿用 3。老客户端不报错,解析出一个 0。这类错误在 JSON 里几乎不会发生,在 proto 里只要改一次类型就可能发生。
模型版本:Java 只认识别名
别名(alias)是 Java 侧唯一认识的名字,比如 invoice-vision。别名到具体权重的映射放在推理服务的启动参数里。
反例:Java 配置里写死完整的权重名。要灰度新版本,就得改 Java 配置、发一次 Java 版本、等一个发布窗口;而推理服务重启只要 40 秒。
灰度时别名多一个:invoice-vision 指稳定版,invoice-vision-canary 指新版。分流按租户哈希取模,同一个租户永远命中同一个别名——用户不会在一次会话中途换模型。
隔离舱:按调用方分池,舱满立刻失败
限流(rate limiting)控制单位时间的请求数。隔离舱(bulkhead)控制并发占用量,而且按调用方分池。
反例:全局限流 100 QPS。某个租户跑批量任务占了 90 QPS,其余租户全部排队。限流器认为系统健康,因为没超 100;用户认为系统挂了,因为他的请求排在 900 个任务后面。
隔离舱的做法是每租户一个池,池满立刻返回降级结果,不排队。等待时间从「不确定」变成「零」。
舱满和超时是两种失败,处理方式不能一样:舱满说明系统还有余量、只是这个调用方用超了,适合立刻降级;超时说明下游整体变慢,这时再重试只会把下游压得更死。这一区分决定了第 4 步代码里为什么舱满要就地接住,而超时必须往上抛给熔断器。
Deadline 还有一层含义容易被忽略:它是「整条链路剩下的总时间」,不是「这一跳的超时」。网关给入口定了 8 秒预算,检索吃掉 1.5 秒,那么传给推理服务的 deadline 最多剩 6.5 秒。如果每一跳都写死 8 秒,四跳串起来最坏就是 32 秒,用户早就关页面了。《进阶:上线前的工程检查》会把时间预算的倒推算法展开。
| 维度 | gRPC(proto 契约) | OpenAI 兼容 HTTP |
|---|---|---|
| 契约来源 | .proto 字段编号,可编译校验 | JSON 约定,靠文档和联调 |
| 流式 | server streaming,逐块回调 | SSE,需自行解析 text/event-stream |
| 超时传递 | Deadline 逐跳向下传 | 自加 header,容易在中间层丢 |
| 调试成本 | grpcurl 需要 proto 或开启反射 | curl 一行 |
| 适用位置 | Java 到 Python 的内部链路 | 供应商模型、临时联调、跨团队试探 |
动手实践
版本基线:JDK 17+、Spring Boot 4.1.x、Spring AI 2.0.x、Spring gRPC 1.1.x;Python 侧 FastAPI 加 vLLM。截至 2026 年 11 月,Spring AI 2.0.x 对应 Spring Boot 4.0/4.1(兼容说明见 Spring AI 官方文档),1.1.x 仍可用但主线已在 2.x。具体模型权重以推理服务启动参数为准,代码里只出现别名。
步骤 1:加坐标,让 proto 参与编译
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-bom</artifactId>
<version>2.0.0</version>
<type>pom</type>
<scope>import</scope>
</dependency>
<dependency>
<groupId>org.springframework.grpc</groupId>
<artifactId>spring-grpc-dependencies</artifactId>
<version>1.1.1</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.grpc</groupId>
<artifactId>spring-grpc-spring-boot-starter</artifactId>
</dependency>
<dependency>
<groupId>io.grpc</groupId>
<artifactId>grpc-protobuf</artifactId>
</dependency>
<dependency>
<groupId>io.grpc</groupId>
<artifactId>grpc-stub</artifactId>
</dependency>
<!-- 生成的 stub 用 @javax.annotation.Generated,JDK 11 起 JDK 不再自带;
报 "找不到符号 Generated" 时补这个,别去补 jakarta 版,包名对不上 -->
<dependency>
<groupId>org.apache.tomcat</groupId>
<artifactId>annotations-api</artifactId>
</dependency>
</dependencies>运行结果:mvn -q generate-sources 无输出。产物出现在 target/generated-sources/protobuf/java 与 .../grpc-java 两个目录,IDEA 里需要手动 Mark as Generated Sources Root,否则 InferServiceGrpc 显示为红色。
protoc 编译插件用 Spring Initializr 勾选 gRPC 时生成的那份配置即可。网上一大半教程还在贴 2019 年停更的 xolstice 插件,遇到 protoc 版本相关的构建错误,先怀疑它。
步骤 2:先写契约
syntax = "proto3";
option java_multiple_files = true;
option java_package = "top.mqxu.gateway.proto";
option java_outer_classname = "InferProto";
service InferService {
rpc Infer(InferRequest) returns (InferReply);
rpc StreamInfer(InferRequest) returns (stream InferChunk);
}
message InferRequest {
string model_alias = 1; // 别名,永远不带版本号
string prompt = 2;
int32 max_tokens = 3;
string trace_id = 4;
}
message InferReply {
string text = 1;
string model_alias = 2;
int32 prompt_tokens = 3;
int32 output_tokens = 4;
bool degraded = 5;
}
message InferChunk { string delta = 1; }运行结果:
$ grpcurl -plaintext localhost:9090 list
grpc.health.v1.Health
grpc.reflection.v1alpha.ServerReflection
InferService步骤 3:Java 侧带 Deadline 的客户端
package top.mqxu.gateway.infer;
import io.grpc.ManagedChannel;
import io.grpc.Metadata;
import io.grpc.StatusRuntimeException;
import io.grpc.stub.MetadataUtils;
import java.util.concurrent.TimeUnit;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.grpc.client.GrpcChannelFactory;
import org.springframework.stereotype.Component;
import top.mqxu.gateway.proto.InferReply;
import top.mqxu.gateway.proto.InferRequest;
import top.mqxu.gateway.proto.InferServiceGrpc;
@Component
public class InferenceGateway {
private static final Logger log = LoggerFactory.getLogger(InferenceGateway.class);
// ASCII 编组即可;键名带 -bin 后缀才表示二进制值
private static final Metadata.Key<String> TENANT =
Metadata.Key.of("x-tenant-id", Metadata.ASCII_STRING_MARSHALLER);
private static final Metadata.Key<String> TRACE =
Metadata.Key.of("x-trace-id", Metadata.ASCII_STRING_MARSHALLER);
private final InferServiceGrpc.InferServiceBlockingStub stub;
public InferenceGateway(GrpcChannelFactory channels) {
// 通道名 infer 对应 application.yml 里的 spring.grpc.client.channels.infer.address
ManagedChannel channel = channels.createChannel("infer");
this.stub = InferServiceGrpc.newBlockingStub(channel)
.withDeadlineAfter(8, TimeUnit.SECONDS);
}
public InferReply infer(String tenantId, String traceId, String alias, String prompt) {
Metadata headers = new Metadata();
headers.put(TENANT, tenantId);
headers.put(TRACE, traceId);
InferRequest request = InferRequest.newBuilder()
.setModelAlias(alias)
.setPrompt(prompt)
.setMaxTokens(512)
.setTraceId(traceId)
.build();
try {
InferReply reply = stub.withInterceptors(MetadataUtils.newAttachHeadersInterceptor(headers))
.infer(request);
log.info("tenant={} alias={} outputTokens={}",
tenantId, alias, reply.getOutputTokens());
return reply;
} catch (StatusRuntimeException e) {
// 这两种失败的处理方式相反:DEADLINE_EXCEEDED 不能立刻重试
log.warn("推理失败 tenant={} alias={} code={}",
tenantId, alias, e.getStatus().getCode());
throw new InferenceUnavailableException(e.getStatus().getCode().name(), e);
}
}
}运行结果:
2026-11-16T21:14:03.221+08:00 INFO 8123 --- [gateway] [nio-8080-exec-4] t.m.g.infer.InferenceGateway : tenant=T-2041 alias=invoice-vision outputTokens=22
2026-11-16T21:14:19.507+08:00 WARN 8123 --- [gateway] [nio-8080-exec-7] t.m.g.infer.InferenceGateway : 推理失败 tenant=T-3312 alias=invoice-vision-canary code=DEADLINE_EXCEEDED第二条日志的 8 秒 deadline 到点后,gRPC 会主动取消这一跳,Python 侧的请求上下文也随之结束——这比 HTTP 客户端断开连接更干净。
代码里的 InferenceUnavailableException 是项目自定义的运行时异常,只做一件事:把 gRPC 的 Status.Code 原样保留下来,让上层能区分 DEADLINE_EXCEEDED 和 UNAVAILABLE。如果直接抛 StatusRuntimeException 上去,熔断器会把这两种性质完全不同的失败算进同一个失败率。
步骤 4:灰度分流与隔离舱
package top.mqxu.gateway.infer;
import io.github.resilience4j.bulkhead.Bulkhead;
import io.github.resilience4j.bulkhead.BulkheadConfig;
import io.github.resilience4j.bulkhead.BulkheadFullException;
import io.github.resilience4j.bulkhead.BulkheadRegistry;
import java.time.Duration;
import java.util.Objects;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.slf4j.MDC;
import org.springframework.stereotype.Service;
import top.mqxu.gateway.proto.InferReply;
@Service
public class ModelRouter {
private static final Logger log = LoggerFactory.getLogger(ModelRouter.class);
private static final String STABLE = "invoice-vision";
private static final String CANARY = "invoice-vision-canary";
private static final int CANARY_PERCENT = 10;
private final InferenceGateway gateway;
private final BulkheadRegistry registry;
public ModelRouter(InferenceGateway gateway) {
this.gateway = gateway;
// 舱满不等待,直接走降级:队列只会把延迟堆到超时
this.registry = BulkheadRegistry.of(BulkheadConfig.custom()
.maxConcurrentCalls(8)
.maxWaitDuration(Duration.ZERO)
.build());
}
public InferReply infer(String tenantId, String prompt) {
String alias = pickAlias(tenantId);
Bulkhead pool = registry.bulkhead("infer-" + tenantId);
try {
// MDC 里没有 traceId 时不能传 null:Metadata.put 会直接抛 NPE
String traceId = Objects.requireNonNullElse(MDC.get("traceId"), "no-trace");
return pool.executeCallable(
() -> gateway.infer(tenantId, traceId, alias, prompt));
} catch (BulkheadFullException e) {
log.warn("隔离舱已满,走降级 tenant={}", tenantId);
return InferReply.newBuilder()
.setText("审核规则已记录,稍后由人工复核")
.setDegraded(true)
.build();
} catch (Exception e) {
throw new IllegalStateException("推理调用异常 tenant=" + tenantId, e);
}
}
// 用哈希取模而不是随机数:同一租户必须永远命中同一侧
private String pickAlias(String tenantId) {
return Math.floorMod(tenantId.hashCode(), 100) < CANARY_PERCENT ? CANARY : STABLE;
}
}运行结果:
2026-11-16T21:15:02.118+08:00 INFO 8123 --- [gateway] [nio-8080-exec-2] t.m.g.infer.InferenceGateway : tenant=T-2041 alias=invoice-vision outputTokens=22
2026-11-16T21:15:07.884+08:00 WARN 8123 --- [gateway] [nio-8080-exec-9] t.m.g.infer.ModelRouter : 隔离舱已满,走降级 tenant=T-3312
{"text":"审核规则已记录,稍后由人工复核","degraded":true}registry.bulkhead(name) 会按名字按需创建并缓存实例。这意味着租户数无上限时,内存也跟着无上限,所以生产上要给租户 ID 加白名单或做一层归一化,别让外部可控的字符串直接当实例名。
舱里放 8 个并发不是随便填的。单卡能同时容纳的序列数是硬约束:推理服务那边 --max-num-seqs 设 32,Java 侧所有舱加起来就不该超过 32,多出来的请求既拿不到显存,也不该继续占着 Tomcat 线程。按 Little 定律粗算,目标延迟 3 秒、单卡 12 QPS,并发上限就是 36;分给 8 个租户,每舱 4 到 5 个才是合理值。这个数对不上,压测时最先看到的不是 5xx,是线程池耗尽。
步骤 5:Python 侧的最小服务
# infer_server.py:只负责推理,不碰业务状态
from fastapi import FastAPI, Header
from pydantic import BaseModel
import vllm_engine # 假想的封装,启动时加载权重
app = FastAPI()
ALIAS_TO_WEIGHT = {
"invoice-vision": "/models/invoice-vision-stable",
"invoice-vision-canary": "/models/invoice-vision-canary",
}
class InferBody(BaseModel):
model_alias: str
prompt: str
max_tokens: int = 512
@app.post("/infer")
def infer(body: InferBody, x_tenant_id: str = Header(default="unknown")):
weight = ALIAS_TO_WEIGHT.get(body.model_alias)
if weight is None:
return {"error": f"unknown alias {body.model_alias}"}, 400
text, usage = vllm_engine.generate(weight, body.prompt, body.max_tokens)
# 每行都带 alias,方便和 Java 侧的日志对齐
print(f"tenant={x_tenant_id} alias={body.model_alias} out={usage['completion_tokens']}")
return {"text": text, "model_alias": body.model_alias,
"prompt_tokens": usage["prompt_tokens"],
"output_tokens": usage["completion_tokens"], "degraded": False}运行结果:
$ curl -s localhost:8000/infer -H 'x-tenant-id: T-2041' \
-H 'content-type: application/json' \
-d '{"model_alias":"invoice-vision","prompt":"这张发票的金额是多少","max_tokens":128}'
{"text":"金额 1,280.00 元,税率 13%","model_alias":"invoice-vision","prompt_tokens":31,"output_tokens":22,"degraded":false}常见误解
很多人以为 gRPC 比 HTTP 快,所以模型调用也该换成 gRPC。实际上一次 7B 模型生成 512 token 要两到四秒,其中序列化和网络往返不到 5 毫秒,gRPC 省下的那点开销在总延迟里看不出来。它值得用的原因在别处:proto 让契约可编译校验、Deadline 能逐跳传递、流式不用自己解析 SSE。只为了「快」上 gRPC,等于多养一个 protoc 构建步骤,去换千分之二不到的收益。
很多人以为 Python 服务挂了就让 Java 改调公网 API 兜底。有个团队这么做过,测试环境一切正常;生产环境第一次触发降级,发票影像被发到了公网模型的端点——这是数据出境,性质不是技术故障。降级路径要和主路径过同一套合规评审,要么指向内网的第二个模型,要么指向非模型方案。《进阶:上线前的工程检查》会把这条写进上线检查表。
很多人以为灰度就是配个百分比。随机百分比会让同一个用户在一次操作里来回换模型:A 模型生成的草稿被 B 模型续写,语气和格式都对不上。分流键要用 tenantId 或 userId 的哈希取模,并且这个结果要能查到、能复现,出问题时能回答「这个用户当时走的是哪一侧」。
小结
- 分工线画在「谁持有模型权重」上:权重在 Python,业务状态在 Java,切分规则这类业务逻辑别跟着 embedding 跑到 Python 去。
- proto 的字段编号等同于数据库列 ID,改名安全,改编号或改类型等于换列,老客户端不报错但读出错值。
- Java 只认识模型别名,别名到权重的映射留在推理服务,灰度才不用发 Java 版本;分流按哈希取模,不按随机数。
- 限流管速率、隔离舱管并发占用量,两者不能互相替代;舱满就立刻降级,别让请求排队。
- 《MCP Server:让模型安全调用 Java 业务能力》的 MCP 是「Java 能力对外」,这一章是「模型能力对内」,两边都靠契约约束,思路是同一条。
相关主题
这套链路能跑通,不等于能上线。《进阶:上线前的工程检查》把上线前必须过的检查整理成一张表:时间预算怎么从入口倒推分配、重试次数为什么默认值会害人、token 成本怎么设上限、数据出境的三条合法路径,以及回滚要能在几分钟内完成。学完那一章,这个类目的技术部分就收尾了。