Skip to content

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 参与编译 ​

xml
<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:先写契约 ​

proto
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; }

运行结果:

text
$ grpcurl -plaintext localhost:9090 list
grpc.health.v1.Health
grpc.reflection.v1alpha.ServerReflection
InferService

步骤 3:Java 侧带 Deadline 的客户端 ​

java
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);
        }
    }
}

运行结果:

text
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:灰度分流与隔离舱 ​

java
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;
    }
}

运行结果:

text
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 侧的最小服务 ​

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}

运行结果:

text
$ 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 成本怎么设上限、数据出境的三条合法路径,以及回滚要能在几分钟内完成。学完那一章,这个类目的技术部分就收尾了。