企业官网建设流程全解析

大模型刚火起来那阵子，很多团队的第一反应是赶紧找个官方SDK调通一个Demo，写几行代码跑通问答，然后发个内部周报就算了。但真到了要把大模型能力接进企业级Java系统的时候，你会发现事情远没那么简单。光是多供应商切换、密钥管理、流式响应适配、成本分摊这几关，就足够把一个架构组拖进去大半个月。

这次我想围绕“Java企业快速接入大模型”这个目标，把我们自己在网关层面的智能处理与工程化实践完整梳理一遍。内容不是教科书式的架构设计，而是基于实际落地的方案选型、核心代码、踩坑记录和经验总结，希望能给正在准备做同样事情的Java后端团队一个可以“抄作业”的参考。

1. 为什么要做企业级模型网关：从三个痛点说起

1.1 多模型接入的接口碎片化：不止是“调个API”

企业接入大模型，第一道坎就是接口碎片化。今天这家厂商出一个对话接口，明天那家出一个兼容OpenAI格式的接口，后天又有一个私有化部署模型需要自定义鉴权。每家都有不同的BaseURL、不同的超时默认值、不同的错误码语义、不同的流式协议。

如果每个业务模块都直接去调这些服务，用不了多久，代码里就会长满这样的“牛皮癣”逻辑：

• 一个服务里同时维护三四个HTTP客户端，每个客户端都有自己的连接池和超时配置；
• 每个调用方都要处理“返回格式异常”“网络超时”“上游限流”这三类问题；
• 某个模型不可用的时候，每个调用方各自写降级逻辑，逻辑还不统一；
• 新接一个模型供应商，要改动的代码散落在十几个服务里。

这个痛点本质上和当年“多个数据库方言不统一”是一样的。既然数据库层面可以造出DAO层和ORM框架来屏蔽差异，大模型调用同样需要一个统一抽象层。这个抽象层放到独立进程里，就是模型网关。

1.2 密钥、权限与安全管控：不能让每个服务都拿Key

第二个痛点是安全。大模型服务的API Key相当于钱，每一次调用都在花钱，而且密钥一旦泄露，别人可以用你的额度干任何事。

早期接入阶段，团队经常把Key直接配在系统环境变量里，或者放在某个共享配置文件中，所有服务都能读到。后来审计的时候发现，连前端的打包产物里都出现过密钥——这个问题是真实发生过的，当时整个团队都吓了一跳。

模型网关至少要做这么几件事：

• 密钥集中管理，业务服务不需要再持有任何上游模型厂商的密钥；
• 网关对业务侧提供独立的接入Token，按租户或按应用维度分配；
• 每个接入Token可以配置可调用的模型范围、每分钟调用上限、单日调用额度；
• 所有调用记录留痕，包括谁调的、调了哪个模型、用了多少token、花了多少钱。

只有把密钥从业务侧彻底收走，才算从根上解决安全风险。

1.3 成本、配额与可用性：不做治理会出大问题

企业里的模型调用如果放任自流，月底账单会教你做人。我见过一个团队，业务方为了拿到更好的答案，把所有请求都指向了最贵的那个模型，结果一个月花了平时三倍的成本，业务效果却没有本质提升。

这就是缺乏网关治理导致的典型问题。模型网关可以把“用哪个模型”这件事变成一个由平台策略控制的决策，而不是业务开发人员的即兴发挥。

网关带来的治理能力包括：

• 按接口维度指定模型策略：低价值流量走低价模型，高价值流量走强推理模型；
• 全局并发限制，防止某个突发流量把配额直接打穿；
• 统一的健康检查和降级开关，某家模型服务不稳定时可以快速摘除流量；
• 成本数据采集，为后续的成本分摊和优化提供依据。

所以“为什么要做网关”这个问题，我的答案很简单：不是为了追新潮，而是为了解决接口碎片化、安全管控和成本治理这三个实际问题。谁先想明白这一点，谁的项目就已经成功了一半。

2. 网关整体架构与智能处理的思路拆解

2.1 网关在系统里的位置：放在哪一层

模型网关本质上是企业内网或云环境中的一个接入层，介于业务后端与大模型供应商/私有化推理服务之间。它的作用类似API Gateway，但面对的大模型服务有其特殊性，因此不能完全照搬通用网关的设计。

画一个简单的逻辑链路：

业务服务 / OpenAPI接口 ↓ (统一协议) [ 模型网关 ] -> 路由策略引擎 -> 适配层 (Provider Adapter) -> 上游模型服务A / 服务B / 本地推理服务

网关放在这个位置，意味着它必须同时满足两面需求。面向业务侧，它要提供简单、统一、稳定的接口；面向模型侧，它要能容忍各家厂商的差异，并且能快速适配新的供应商。

2.2 三层抽象：接入层、路由层、治理层

我们落地时按三层抽象来拆：

• 接入层：负责接收业务侧请求，做认证、鉴权、参数校验、流量控制。对外暴露一套统一API，例如/v1/chat/completions。
• 路由层：根据请求特征、策略配置、上游健康状态，动态选择调用哪一个模型服务。这里也是“智能处理”的主要阵地。
• 治理层：负责限流、熔断、重试、缓存、成本统计、日志审计等横向能力。

三层各自独立，才能让网关在演进中不至于改一处崩全身。我们项目早期就是没分清边界，把路由逻辑和治理逻辑耦合在一起，后面加限流策略的时候引发了不少线上问题，后来重构成了现在这个结构才稳定下来。

2.3 “智能”体现在哪里：路由、缓存、提示词装配

很多人听到“智能网关”会觉得故弄玄虚，其实放在工程图上非常具体。模型网关的智能处理主要体现在四个方面：

第一是智能路由。网关可以根据请求的类型和难度，决定把流量分给哪个模型。简单摘要走便宜的本地模型，代码生成走强推理模型，数学逻辑题再切到更专业的大参数模型。这个策略可以基于规则，也可以引入一个轻量分类器。

第二是语义缓存。很多企业级场景里，重复请求占比很高。客服问答里的高频问题、报表系统里的固定口径解释，都是语义重复的。网关可以把这些问题的向量和结果缓存起来，命中时直接返回，节省成本也降低延迟。

第三是提示词工程的内置。业务方不需要自己拼复杂的Prompt，网关提供一套模板编排能力。业务侧传商品信息和用户问题，网关自动组装出完整的、经过优化的Prompt，再发给模型。这样Prompt的迭代可以由平台团队统一控制，而不是散落在业务代码里。

第四是结果后处理。模型返回的结果不一定总是合法的JSON，或者格式不符合下游系统的要求。网关在返回给业务之前做一次校验和修复，能挡掉很多下游解析崩溃。

2.4 方案选型：自研轻量网关还是用商业产品

这个议题大家总是反复纠结。我们的结论是：如果团队里有Java后端资源，且需要深度私有化定制，自研一个轻量网关完全可行，几周就能跑通核心链路；如果对交付周期极度敏感，又没有专业人力，可以先上商业产品，但边界要提前想清楚。

自研网关的优势是：能完全贴合企业内部已有的监控体系、鉴权体系和部署环境。商业产品的优势是：轮子现成，更新快，有技术支持。我们当时评估了一圈，最终还是选择自研，主要原因有三：

• 上游模型供应商变化快，商业产品对新型号的支持有滞后；
• 企业内部要求所有调用链必须走自家的审计系统，商业产品难打通；
• 流式响应的需求很重，自研可以更好地做底层优化。

当然，自研不是说要造一个功能繁重的全家桶，而是先做最小闭环：统一API + 路由策略 + 流式转发 + 基础治理，跑通之后再逐步扩充。

3. 核心实现：用Java（Spring Boot）快速落地

3.1 项目工程结构

我们采用多模块Maven工程，模块划分如下：

model-gateway-core // 核心模型、配置、路由策略 model-gateway-adapter // 各厂商适配器 model-gateway-web // 对外HTTP服务 model-gateway-admin // 管理端接口与配置下发（可选）

这样做的好处是：核心模块不依赖任何具体厂商SDK，新增一个模型供应商只需要在adapter模块加一个实现，不影响其他模块。

项目基础栈是Java 17、Spring Boot 3.x。通信层面，我们同时保留了Servlet栈和WebFlux两种选择：普通请求走Servlet，流式请求走WebFlux响应。不过在最终实现中，为了方便统一，整个网关服务直接建立在Spring WebFlux之上。这样流式响应能直接用Reactor类型贯穿，减少线程阻塞。

3.2 统一Provider接口：给各家大模型做适配器

核心抽象是一个Provider接口，所有上游模型服务都通过实现这个接口接入网关。

public interface ModelProvider { String getProviderName(); boolean support(ModelType modelType); Mono<ChatResult> chat(ChatRequest request); Flux<ChatChunk> chatStream(ChatRequest request); boolean isAvailable(); }

这个接口里最重要的是chat和chatStream两个方法。它们接收统一的ChatRequest，返回统一的数据结构，屏蔽掉各家协议差异。

ChatRequest内部主要包含：

• modelType：业务侧期望的模型类型，例如text、code、reasoning；
• messages：历史消息列表；
• parameters：温度、最大token等采样参数；
• userId：可选，用于透传审计信息；
• requestId：全链路追踪ID。

再看一个适配器实现的例子，假设某个供应商的接口是标准兼容格式：

@Component public class VendorOpenProvider implements ModelProvider { private final WebClient webClient; private final ProviderConfig config; @Override public String getProviderName() { return "vendor-open"; } @Override public boolean support(ModelType modelType) { return true; } @Override public Mono<ChatResult> chat(ChatRequest request) { CommonApiRequest apiRequest = toApiRequest(request); return webClient.post() .uri(config.getBaseUrl() + "/chat/completions") .bodyValue(apiRequest) .retrieve() .onStatus(status -> status.isError(), resp -> resp.bodyToMono(String.class).flatMap(body -> Mono.error(new UpstreamException(body)))) .bodyToMono(CommonChatResponse.class) .map(this::toChatResult); } @Override public Flux<ChatChunk> chatStream(ChatRequest request) { // 流式实现，后面专门讲 } @Override public boolean isAvailable() { // 可以基于Redis中的健康标记 return true; } }

每个适配器内部只做一件事：把统一的ChatRequest转换为该厂商需要的请求结构，然后把返回结果再转成统一结构。这样业务方从不用关心上游接口长什么样。

3.3 智能路由与策略注入

路由是网关的核心。我们的实现是：定义RouteStrategy接口，然后在运行时选择策略，进而选出Provider。

public interface RouteStrategy { boolean supports(ChatRequest request); Mono<ModelProvider> choose(List<ModelProvider> providers, ChatRequest request); }

日常流量我们默认使用“成本优先型策略”：优先选择已配置的低价Provider，但有个前提，该Provider的当前并发数低于阈值。

public class CostAwareStrategy implements RouteStrategy { private final Map<String, Integer> costRank; private final LoadMeasurer loadMeasurer; @Override public boolean supports(ChatRequest request) { return request.getRouteHint() == RouteHint.COST_SAVING; } @Override public Mono<ModelProvider> choose(List<ModelProvider> providers, ChatRequest request) { return Flux.fromIterable(providers) .filter(provider -> provider.isAvailable()) .sort(Comparator.comparingInt(p -> costRank.getOrDefault(p.getProviderName(), 999))) .filterWhen(provider -> loadMeasurer.isUnderThreshold(provider)) .next() .switchIfEmpty(Mono.error(new NoAvailableProviderException())); } }

“智能”还体现在请求异常时触发自动降级。比如请求“vendor-open”超时，我们会根据配置决定是返回错误，还是降级调用“vendor-local”。

这个降级逻辑放哪里？我们选择放在路由层上面，用一个ResilientRouter包装原始路由：

public class ResilientRouter { public Mono<ChatResult> route(ChatRequest request) { return selectProvider(request) .flatMap(provider -> provider.chat(request)) .timeout(Duration.ofMillis(request.getTimeoutMs())) .onErrorResume(TimeoutException.class, e -> fallbackRoute(request).flatMap(p -> p.chat(request))); } }

这样既保证了主路径清晰，又能把降级策略作为一种独立的工程能力沉淀下来。

配置驱动非常重要。我们所有路由策略都不写死在代码里，而是放在配置中心：

gateway: routing: default-strategy: cost-aware strategies: - name: cost-aware provider-priority: ["vendor-local", "vendor-open", "vendor-strong"] max-concurrency: 20 - name: reasoning-aware provider-must-support: ["reasoning"] provider-priority: ["vendor-strong", "vendor-open"]

业务侧需要指定模型规格时，请求体中带一个modelType字段，网关根据这个字段匹配对应的策略组。

3.4 流式响应与SSE透传

企业级应用聊大模型必然要说流式。如果网关等完全部token再返回，用户那边文字是一段一段蹦出来的，体验很差。

在Spring WebFlux环境下，流式转发可以用Flux直接透传。下面是一段简化后的例子：

@PostMapping(value = "/v1/chat/completions", produces = MediaType.TEXT_EVENT_STREAM_VALUE) public Flux<ServerSentEvent<String>> chatStream(@RequestBody ChatRequest request) { return router.routeStream(request) .map(chunk -> ServerSentEvent.builder(chunk.getContent()) .event("message") .build()); }

但这里有一个我在实践中遇到的坑：很多模型供应商的流式返回不仅仅是纯文本token，还会附带用量统计、结束标记、以及一些自定义事件字段。如果一昧透传，客户端需要为不同厂商解析不同协议。所以我们在网关层对上游流式事件做了统一归一化，统一只转发三类事件：

• delta：增量内容；
• done：本轮生成结束；
• error：错误信息。

内部每个Provider会把上游原始事件转成这统一的StreamEvent，好处是下游客户端永远只需要解析一套协议。

如果你还在用Servlet栈，也可以用SseEmitter实现类似效果：

@GetMapping(path = "/v1/chat/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE) public SseEmitter stream(@RequestParam String query) { SseEmitter emitter = new SseEmitter(0L); asyncService.streamAnswer(query, emitter); return emitter; }

不过你要特别注意，Servlet模式在做流式转发时，需要自己管理线程池和超时，稍微复杂一些。如果团队还在老项目上，可以先用这个方案过渡；新项目我强烈建议直接上WebFlux，开发效率高很多。

另外，在流式场景下要格外留意网关自身的“缓冲关闭”。我遇到过不止一次：网关前面的代理层默认会对响应做缓冲，导致用户等了很久才看到一段完整输出。所以我们当时在Nginx代理配置里关掉了对SSE接口的缓冲：

location /v1/chat/completions { proxy_buffering off; proxy_cache off; proxy_read_timeout 300s; }

如果网关前面还有Spring Cloud Gateway之类的流量入口，同样要注意它是否默认聚合了响应体，确保流式链路全程不缓冲。

3.5 限流、熔断、重试的工程化配置

工程化不能被“能用就行”糊弄过去。我们把限流、熔断、重试作为独立治理层件实现，全部通过配置驱动。

限流使用简单的令牌桶实现。网关内部不使用Redis做全局计数吗？早期我们用本地Guava RateLimiter，发现多实例部署时限额不准，后来迁移到了Redis + Lua脚本方案，按接入Token维度限流：

public boolean tryAcquire(String key, int tokens) { Long result = redisTemplate.execute( rateLimitScript, List.of("rate:" + key), String.valueOf(tokens) ); return result != null && result == 1L; }

Lua脚本的核心是检查当前令牌桶余量是否足够，不足则返回0：

local key = KEYS[1] local tokenReq = tonumber(ARGV[1]) local bucket = redis.call('HMGET', key, 'tokens', 'lastRefill', 'maxTokens', 'refillRate') -- 省略具体的补桶计算

熔断我们使用Resilience4j，因为它和Spring Boot整合好，且配置灵活。熔断触发条件设为“最近20次调用中错误率超过50%”，熔断打开后进入半开状态让部分请求试探。

重试策略要非常小心。大模型场景下，重试会放大成本也会放大慢请求。我们的原则是：只有幂等且低风险的重试才会自动执行，并且重试次数上限是2次，重试间隔采用指数退避并加入随机抖动，防止多个请求在同时刻重试压垮上游。

resilience4j.retry: instances: modelCall: maxAttempts: 3 waitDuration: 500ms retryExceptions: - java.net.SocketTimeoutException - com.example.gateway.exception.UpstreamRateLimitException

对于上游限流返回的HTTP 429，不直接重试，而是先放到一个延迟队列里，等限流窗口过去后再放行。

4. 上线之后才能遇到的：踩坑记录与排查技巧

4.1 流式响应的CORS和代理缓冲问题

网关对外供前端调用时，跨域问题在流式场景下特别容易踩坑。普通的JSON接口配一下CORS头就行了，流式接口如果还有代理层，就必须保证不会对事件流做缓冲。

我们上线后遇到最典型的场景是：前端EventSource连接后，迟迟收不到事件，服务端日志显示已经在写数据了，但浏览器里一直连接挂起。排查到最后发现是代理层缓冲导致。解决方式上面也提过：关掉相关location的proxy_buffering。

另外，SSE连接有连接数限制，浏览器同一域名只允许开六个HTTP连接。如果业务页面同时开了多个对话，需要考虑合并为一个事件流，否则后面的事件只能排队。

4.2 并发放大问题：网关变成请求风暴

网关在系统中的天然职责之一是把控流量，但处理不好它自己反而变成风暴放大器。我们遇到过一次线上事故：客户端SDK超时设置过长，网关上游模型服务出现慢响应，导致大量请求堆积在网关线程，并发的WebClient连接数被占满，最终波及到其他正常接口。

事后我们做了两个改进：

• 给所有上游调用强制加上超时，且超时时间按模型不同分别设置；
• 网关层增加依赖隔离，不同供应商的调用走独立的连接池，避免某家把连接池吃光。

gateway: providers: vendor-open: connect-timeout: 2s read-timeout: 30s max-connections: 50 vendor-local: connect-timeout: 500ms read-timeout: 60s max-connections: 200

4.3 模型返回不稳定：格式化输出兜底

模型返回不稳定是常态。我们做知识库问答时，要求模型最终输出必须是一个JSON对象，但实际测试中总会冒出多出来的一段Markdown代码块或解释文字。

后来我们专门在网关里加了一层“结果清洗”，针对JSON输出做校验和修复：

• 如果返回里包含Markdown代码块，先剥离代码块标记；
• 如果JSON不是合法格式，尝试用大模型本身做一次“重生成为JSON”的自我修正；
• 如果还失败，返回统一错误码，不让脏数据流向下游。

这层处理特别消耗耐心，但确实解决了业务侧非常多解析崩溃的问题。你可以在网关里把清洗结果和原始结果都打日志，方便分析模型行为。

4.4 成本账单对不上的排查方法

月末复盘模型费用时，如果网关的token统计和厂商账单对不上，先查这几点：

• 流式请求是否把每轮的token都统计全了。很多厂商在流式消息流里，每个事件都带usage字段，但不同厂商对“本次token数”的计算方式不同，有的包含缓存token，有的不含；
• 网关重试产生的调用是否都计入了成本。重试次数越多，偏差越大；
• 是否漏了嵌入向量、图片生成等其他模态接口的调用统计。成本统计不要只集中在对话模型上。

我们在网关侧维护一张model_usage表，每次调用结束后写入模型名、输入token、输出token、缓存命中数、调用者、召回的业务ID。月末对账时按这张表和厂商账单逐项核对，差异很快就能定位。

4.5 常见问题速查表

5. 项目实践体会与后续可以扩展的方向

这套网关实际上线后，我们最大的体会是：模型网关的价值不在于“转发”，而在于“治理”。没有网关前，模型调用就像无人管理的散兵游勇；有了网关后，团队终于能看清每一笔流量去了哪里、花了多少钱、稳不稳定。也正是因为看清了，才敢放心让大模型能力渗透到更多业务场景里。

一个可以继续扩展的方向是模型评测与灰度。现在网关路由是静态配置和简单策略结合，后续我们计划在网关里接入模型评测任务，新模型先切到小流量，对比同样的问题和预期结果，跑一段时间再逐步放大引流。这个能力对模型迭代特别有用，因为大模型升级带来的回归问题远比传统系统升级更难发现。

另外，智能缓存也值得做深。目前的语义缓存是基于向量相似度，我们在实践中还会遇到“语义相近但答案必须不同”的场景。比如问“今天库存多少”和“明天库存预计多少”，相似度高但答案完全不同。这个问题需要引入业务字段作为缓存key的一部分来规避，也就是上下文感知缓存，而不是单纯靠向量。

最后想提醒正在做类似项目的团队：千万不要在初始阶段追求把所有厂商和所有功能一次性接入。最稳妥的落地节奏是先接一家真实业务场景必须的供应商，把统一抽象、流式透传、限流熔断跑通，再慢慢扩展适配器。网关这种基础组件，稳定永远比功能多更重要。

我自己的经验是，第一次做模型网关时容易把复杂度预估过高，实际拆开之后发现核心路径就是抽象、路由和治理三件事。认认真真把这三点做好，剩下的，都是在踩坑里慢慢补课而已。