前一阵做一个内部小项目，需要给系统加一点大模型能力，但数据合规卡得很死，业务数据完全不能出内网，公有云那套大模型服务直接排除在选项之外。团队技术栈又是Java为主，所以我一开始就在想：模型可以在内网自己跑，但业务代码怎么写得干净、好维护？后来选了一条比较顺的路——SpringAI 作为接入层，通过 OpenAI 兼容协议连接本地的 Xinference 服务，底层模型随便换，Spring 侧代码基本不用动。整套链路从零到跑通大概花了两三天，中间踩了几个坑，我把过程和一些关键细节整理出来，给同样要在内网或私有环境接大模型的 Java 后端同学做个参考。
这篇文章不会只贴配置和代码，我会尽量把“为什么这么连”“每个环节里哪些变量最坑”讲清楚。你如果已经在用 Spring Boot 3.x，对 REST API、Maven 比较熟，那这篇基本就是给你准备的；如果你刚接触大模型服务化，我也尽量把 Xinference、OpenAI 兼容接口这些概念讲得通俗一点。
1. 这套链路里的三个角色，分别干了什么
先说整体架构，不然直接看配置容易懵。整条链路里有三个关键角色：Xinference 负责把开源模型“变成服务”，OpenAI 兼容协议负责统一调用方言，SpringAI 负责在 Java 侧把各种模型适配器的差异做收口。
1.1 Xinference：让开源模型变成“标准的模型服务”
Xinference 是一个开源的大模型推理服务平台，核心价值是让模型部署这件事变得像“在应用商店里点安装”一样简单。你可以把它看作一个模型路由器加推理引擎调度器：模型本身是引擎，Xinference 提供仪表盘和方向盘。
我之所以选它，有几个很现实的原因。第一，它内置了大量主流模型的部署配置，从对话模型、向量 Embedding 模型到重排模型都有，不用自己写一堆启动脚本；第二，它对底层推理引擎做了封装，同一个模型可以选不同的后端来跑，比如 GPU 环境用 vLLM 跑得更快，显存紧张时用 llama.cpp 的量化版，这些切换都可以在服务里完成；第三，它直接暴露 OpenAI 风格的 HTTP 接口，这对接 SpringAI 或者任何 OpenAI SDK 都非常顺。
这么说吧，没有 Xinference 时你要自己折腾：下载模型权重、写推理代码、处理并发请求、暴露 HTTP 端口。有了 Xinference，你只需要告诉它“我要跑哪个模型、用什么引擎跑”，剩下的加载、调度、响应格式统一由它处理。
1.2 OpenAI 兼容协议：为什么业务代码可以不关心底层模型是谁
OpenAI 兼容 API 本质上是一套约定俗成的 HTTP 接口规范。所有兼容的服务都会提供v1/chat/completions这个端点，请求体里放model、messages、temperature这些字段，响应体里统一返回包含choices的 JSON。也就是说，不管底层跑的是 Qwen、Llama 还是别的模型，只要它实现了这套接口，调用方的代码就完全不用感知模型差异。
这对业务代码来说太省事了。假设你之前接的是某个云端模型服务，代码里用的是ChatClient或者某个 SDK；现在要切到内网自建的模型，只需要把服务地址改一下，模型名改一下，请求和响应结构完全不用重构。这也是我坚持用标准协议而不是 Xinference 私有 API 的原因——避免被厂商绑定，后续换部署后端、换模型，成本都可控。
1.3 SpringAI：Java 侧把“模型方言”收口了
SpringAI 是 Spring 生态里针对 AI 应用做的抽象层。如果你熟悉 Spring 对数据库的处理方式，就很好理解：它对不同数据库的差异做了统一，让我们用 JdbcTemplate 就能操作多种数据库。SpringAI 在 AI 领域做的事类似，它对不同模型提供商的差异做了封装，对外暴露统一的ChatClient、ChatModel、EmbeddingModel等接口。
在 SpringAI 里，“OpenAI”不只是指某个商业服务，它也是一类协议适配器的名字。只要目标地址是 OpenAI 兼容接口，你就可以用spring-ai-openai这个模块去连。Xinference 恰好提供的正是这类接口，所以你可以用完全标准的连接方式，把请求打到 Xinference 上，再转发给本地模型。整个架构我们就用一句话概括：SpringAI 对 Java 开发者提供统一编程模型，Xinference 对 SpringAI 提供标准模型服务，模型是谁，反而成了最不重要的变量。
2. 先把 Xinference 侧准备好：模型部署与服务验证
一端是 SpringAI 客户端，另一头是 Xinference 服务端。在写任何 Java 代码之前，我建议先把 Xinference 这头彻底跑通，用命令行确认接口可用，再把 Spring 的配置填进去。先服务端、后客户端，排查问题会省很多时间。
2.1 安装与启动：从 pip install 到服务起来
Xinference 是用 Python 写的，安装直接用 pip 就行。如果你只是为了跑对话模型、机器上有 NVIDIA GPU，我建议一步到位装完整版，避免后续缺某个推理引擎依赖：
pip install "xinference[all]"这里有个现实考量：[all]这个 extra 会把多个推理后端都装进来，体积比较大，安装时间也会久一些，但胜在省心。如果你非常清楚自己只需要 llama.cpp，也可以装pip install "xinference[llama.cpp]"，能瘦身不少。不过我个人建议无脑选 all，排除依赖问题永远比省一点磁盘空间更有价值。
启动服务也很简单，新版本的本地部署命令是：
xinference-local --host 0.0.0.0 --port 9997如果你用的是旧版本，可能会用xinference命令，参数一样。--host 0.0.0.0是为了让局域网里其他机器也能访问，如果只是本机调试，用127.0.0.1就够了。默认端口是 9997，记好这个端口，后面所有配置都会用到。
启动后浏览器打开http://localhost:9997，会看到一个 Web 管理界面，里面能查看已部署的模型、显存占用、推理引擎类型，也能在线发起对话测试。我一般在部署完模型之后都会在 UI 里先聊两句，确认模型真的加载成功了，再回 Java 侧排查。
2.2 部署一个对话模型：模型名、推理引擎和显存取舍
服务起来之后，下一步就是部署模型。Xinference 支持从内置模型列表中选择，也可以指定 Hugging Face 上的模型 ID。以我这次用的qwen2.5-7b-instruct为例，命令行部署方式如下：
xinference launch --model-name qwen2.5-7b-instruct --model-type LLM不加--engine参数时，Xinference 会根据当前机器的 GPU 和可用依赖自动选择合适的推理引擎。带 GPU 的机器一般会优先选 vLLM，纯 CPU 环境会用 llama.cpp 或者 transformers。第一次部署时如果本地没有模型权重，会自动从 Hugging Face 下载，这步耗时取决于模型大小和网络状况。
这里有几个需要重点注意的事项：
- 模型名一定以 Xinference 内置列表或 Web UI 下拉框里的实际名称为准，大小写和连字符都不能想当然。比如列表里写的是
qwen2.5-7b-instruct，就不要在 Spring 里写成Qwen2.5-7B-Instruct。 - 要关注显存。7B 模型原生权重大概需要 14-16GB 显存，量化版能压到 6GB 左右。如果 GPU 显存不够，要么换小参数模型，要么在部署时选择量化版本，比如
qwen2.5-7b-instruct的 AWQ 或 GPTQ 量化版本。 - 部署是异步的。模型体积越大，加载时间越长，尤其是冷启动时，几十秒到几分钟都有可能。在 loading 状态时直接发推理请求，通常会报错或超时。
我这次是在一台 24GB 显存的 GPU 服务器上跑的，部署一个 7B 量化模型绰绰有余。选 7B 这个档位也是综合考虑了效果和显存余量。
2.3 用一条 curl 确认端点可用，再开始写 Java
模型部署完成之后，先用 curl 验证一下 OpenAI 兼容端点是否通，这能帮你把“服务端问题”和“客户端问题”彻底切开。Xinference 的 OpenAI 兼容端点统一在根路径下的v1，也就是：
curl http://localhost:9997/v1/models如果返回了模型列表 JSON，说明服务端 OK。接着再测一次对话接口：
curl http://localhost:9997/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "qwen2.5-7b-instruct", "messages": [{"role": "user", "content": "你好，用一句话介绍自己"}], "stream": false }'响应里能看到choices[0].message.content字段，这就说明整个服务端链路已经打通了。这里顺便说一句：Xinference 默认不强制校验 API Key，但这个接口是 OpenAI 兼容的，而 OpenAI 的客户端通常要求api-key不能为空，所以到 Spring 配置那步，我们会随便填一个占位符。这个细节后面还会再讲。
3. SpringAI 接入的三个关键点：依赖、配置、最小 Demo
服务端验证没问题之后，就可以开始写 Java 了。SpringAI 接入本身不复杂，但其中有三个点最容易让人卡住：依赖版本要对齐、配置项不能照搬旧教程、代码入口要选对。
3.1 Maven 依赖：版本要和 Spring Boot 对齐
SpringAI 的版本更新速度很快，API 和配置项在不同小版本之间都可能有调整。我这次用的是 Spring Boot 3.3.x，搭配 SpringAI 1.0.0 GA。这里强烈建议用 SpringAI 提供的 BOM 统一管理版本，避免自己手工维护版本号：
<dependencyManagement> <dependencies> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-bom</artifactId> <version>1.0.0</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement>BOM 引入之后，再添加实际模块依赖：
<dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-openai-spring-boot-starter</artifactId> </dependency>这里不用写版本号，由 BOM 统一控制。在选版本时我有个经验：不要盲目追求最新，尽量选 GA 版本，并且确认它和你的 Spring Boot 主版本兼容。SpringAI 的官方文档会在 release notes 里写明兼容矩阵，别看漏了。
另外，SpringAI 有一些独立模块需要额外引入，比如后面要用到向量检索、嵌入模型时，还要加spring-ai-vector-store之类的依赖。这些等用到再逐个加，不提前引入避免依赖臃肿。
3.2 配置文件里的魔鬼细节：base-url 和 model 名
依赖加好之后，最核心的配置集中在application.yml。我最终的配置大概是这个样式：
spring: ai: openai: base-url: http://localhost:9997/v1 api-key: local-not-used chat: options: model: qwen2.5-7b-instruct temperature: 0.7 max-tokens: 2048第一处魔鬼细节就是base-url。Xinference 的 OpenAI 兼容地址是http://localhost:9997/v1，SpringAI 的 OpenAI 适配器会在这个地址后面继续拼接具体接口路径。以chat/completions为例，如果你只配置到http://localhost:9997，最终请求就会打到http://localhost:9997/chat/completions，大概率 404；配置到http://localhost:9997/v1，就会正确打到http://localhost:9997/v1/chat/completions。但不同版本的 SpringAI 对默认路径的处理又略有差异，万一你遇到 404，最直接的排查方法就是看实际发出的请求 URL，而不是凭空猜。这个后面避坑章节我会再展开。
第二处魔鬼细节是api-key。Xinference 本地服务一般不校验 token，但 SpringAI 的 OpenAI 模块在构建请求头时要求这个字段不能为空，所以随便填一个占位符即可。不过有一点要注意：如果你后续在 Xinference 里开启了 API Key 鉴权，那这里就一定要填真实的 key，否则会一直 401。
第三处魔鬼细节是model名称必须和服务端部署的模型名完全一致，否则就会得到 “model not found” 之类的错误。这里别觉得这是小事，我见过不少人在这里卡了很久，只因为大小写或连字符不一样。
正因为配置项在不同版本之间有变动，我建议你加了依赖之后，先看一眼当前版本对应的官方配置文档，重点确认model和base-url的路径结构。照着旧教程无脑复制，在你自己的版本里很可能就不适用。
3.3 先跑通一个同步接口，建立信心
SpringAI 在 1.0 版本里推荐的编程入口是ChatClient，它比直接操作ChatModel更直观。最简单的同步接口可以这样写：
@RestController public class ChatController { private final ChatClient chatClient; public ChatController(ChatClient.Builder builder) { this.chatClient = builder.build(); } @PostMapping("/chat") public String chat(@RequestBody String message) { return chatClient.prompt() .system("你是一个严谨的技术助手，回答尽量简洁，使用中文。") .user(message) .call() .content(); } }启动 Spring Boot 应用后，用 Postman 或 curl 调一下/chat：
curl -X POST http://localhost:8080/chat \ -H "Content-Type: text/plain" \ -d "SpringAI 连接 Xinference 需要注意什么？"能正常返回一段中文回答，就说明整条链路已经通了。这个同步接口虽然简单，但它验证了依赖、配置、模型部署、接口映射全部正确。之后再去做流式输出、多轮对话、向量检索，都是在它基础上扩展，排查起来就有底气了。
有的同学可能会问，为什么我从ChatClient而不是OpenAiChatModel开始？因为ChatClient是 SpringAI 官方在 1.0 里主推的高层抽象，它对 prompt 的组装、消息历史的管理都做了封装，后续代码演进空间更大。当然你想直接用OpenAiChatModel也可以，只是代码会更偏向底层，适合想精细控制 prompt 元数据的情况。
4. 从单轮问答到流式输出：实际业务里够用的写法
同步接口只是一种最朴素的用法。真实业务里，大模型生成一段完整回复往往需要几秒甚至十几秒，如果让用户一直白屏等待，体验很差。所以流式输出几乎是必选项。
4.1 用 ChatClient 封装对话服务
想要更好的可维护性，我建议把对话逻辑从 Controller 里抽出去，封装成一个服务。比如：
@Service public class ChatService { private final ChatClient chatClient; public ChatService(ChatClient.Builder builder) { this.chatClient = builder.build(); } public String chat(String userMessage) { return chatClient.prompt() .system("你是企业内部的智能助手，回答要简洁、准确、安全。") .user(userMessage) .call() .content(); } }Controller 就只是薄薄一层，负责接收 HTTP 请求并调用服务。这样以后你如果要加多轮对话、要拼上下文、要记录日志，都只需要改 Service 就够了。SpringAI 的ChatClient内部会处理掉很多细节，比如自动拼接消息、处理模型返回的元数据。
有一个细节值得说一下：ChatClient.Builder在 Spring 容器里有自动配置，默认绑定了你配置里指定的那个模型。如果你项目里只有一个模型，直接注入 Builder 就行。等后面如果需要同时连接多个不同模型，就要手动定义多个 Bean，这个我放到最后一章讲。
4.2 流式输出：Flux 怎么接回前端
SpringAI 的流式接口返回的是Flux<String>，这是 Reactor 的响应式流类型。Spring Web MVC 里也可以直接返回Flux，配合text/event-stream媒体类型，就能实现 Server-Sent Events 输出。
@PostMapping(value = "/chat/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE) public Flux<String> chatStream(@RequestBody String message) { return chatClient.prompt() .system("你是企业内部的智能助手，回答要简洁、准确、安全。") .user(message) .stream() .content(); }前端那边，如果请求方式是 GET，直接用浏览器原生EventSource就能收 SSE；但EventSource不支持 POST，如果你们接口规范要求 POST，就需要用fetch配合ReadableStream手动读取，或者用支持 SSE 的 HTTP 客户端库。我在项目里用的是 fetch 流式读取，每一段拿到的就是已经拼好的一小段文本，直接渲染到页面上就好。
实际跑起来，流式返回的速度取决于底层推理引擎的生成速度。vLLM 和 llama.cpp 的 token 生成速度有明显差距，但这个差异不是代码层能解决的，更多是部署选型的问题。如果发现流式输出很卡，先检查模型是不是加载在 CPU 上跑，再检查是否并发请求太多导致排队。
5. 实测最容易踩的坑：现象、根因、排查链路
整个项目里最耗时间的不是写代码，而是排错。我把这次实测中遇到的高频问题整理出来，每一个都按“现象 -> 根因 -> 排查思路”来写，方便你遇到类似情况时快速定位。
5.1 404 与路径的纠缠：base-url 到底加不加 /v1
现象：SpringBoot 应用能正常启动，但一调用就报 404，控制台里能看到类似404 Not Found的错误。
根因：绝大多数情况下是base-url的路径层级不对。Xinference 暴露的是http://ip:9997/v1/chat/completions，如果你的base-url配的是http://ip:9997，SpringAI 拼接后就会少一级v1路径，最终请求 404。反过来，如果某个 SpringAI 版本内部已经自动带了/v1前缀，你还多配一个/v1，同样会 404。
排查思路：别猜，直接看实际请求的完整 URL。开启 Spring 的 HTTP 客户端调试日志就能看到：
logging: level: org.springframework.web.client.RestTemplate: DEBUG如果你用的是 WebClient 响应式客户端，可以调整 reactor 的日志级别。日志里会打出最终的请求路径，你一眼就能确定是多了/v1还是少了/v1。从我实测来看，Xinference 场景下配置到http://localhost:9997/v1是能通的，但前提是你用的 SpringAI 版本没有额外拼接，所以最终还是要以日志为准。
5.2 模型名不一致导致的冷错误
现象：请求可以到 Xinference，但返回的错误信息是model not found或者No matching model found。
根因：application.yml里model字段的值和 Xinference 实际部署的模型名不一致。常见的大写不同、连字符不一样、带了版本后缀但服务端部署名没带。
排查思路：去 Xinference Web UI 的“运行中模型”页面，复制那个确切的模型名，粘到配置里。不要手敲。这里有个容易忽视的小坑：Xinference 内置模型列表里的规范名和你心底里习惯叫的名字可能不一样。比如你在 UI 里搜索时看到的是qwen2.5-7b-instruct，那配置里就一字不差地写它，连空格都不要有。
另外，如果你同时部署了同名模型的多个量化版本，模型名里可能还会带量化标识，那也要保持一致。总之，模型名是字符串匹配，不是模糊识别，严格要求精确。
5.3 鉴权、超时与底层引擎的参数兼容
再来说三个没那么明显、但实际很容易踩到的问题。
第一个是鉴权 401。Xinference 默认不鉴权，但如果你或管理员在 Xinference 里开了 API Key 验证，Spring 侧就必须配置真实 key。有些人习惯性填占位符，一遇到 401 就懵了。这个问题的根因就是“服务端开了鉴权，客户端没带有效 token”，去 Xinference 的用户设置里生成一个 token 填进去即可。
第二个是冷启动超时。模型第一次部署后，Xinference 可能还在加载权重，这时候发请求可能直接连接超时。这个问题的根因不是代码配置，而是模型还没 ready。我建议在跑业务流程之前，先用 curl 或 Web UI 发几条消息，让模型预热完成。如果你们系统会在模型加载中频繁请求，要么增加客户端读取超时时间，要么在调用前轮询 Xinference 的模型状态接口。从实践角度看，内网服务通常不会在超时设置上消耗太多精力，等模型 ready 了再上业务流量是最省事的。
第三个是关于参数兼容。OpenAI 请求参数里有些字段，Xinference 不一定都能原样透传给底层推理引擎。比如某些模型对frequency_penalty、presence_penalty支持得一般，或者某些引擎对max_tokens的取值有上限。如果你在配置里塞了一堆参数，结果响应报参数错误，可以先逐步减少参数，只保留model、messages和temperature，看能不能通过，再逐个加回。这是一个非常实用的二分排查法。
我把这几个问题的对照关系整理一下：
| 现象 | 根因方向 | 优先排查动作 |
|---|---|---|
| 404 Not Found | base-url 路径层级不对 | 看日志里的实际请求 URL，调整/v1 |
| model not found | 模型名拼写或大小写不一致 | 从 Web UI 复制模型名 |
| 401 Unauthorized | Xinference 开启了鉴权 | 配置真实 API Key |
| 连接超时 | 模型冷启动未完成 | 预热模型 / 调大读取超时 |
| 参数报错 | 底层引擎不支持某些参数 | 逐个减少参数再测试 |
6. 后续还能怎么玩：多模型切换与 RAG 向量检索
SpringAI 加 Xinference 这套链路打通之后，最爽的一点是扩展成本很低。只要 Xinference 能部署的模型类型，SpringAI 这边基本都能接上。我简单说说两个最实用的方向。
6.1 一个项目里同时接多个模型
业务里常会遇到这种需求：通用问答用一个大模型，代码生成或总结用另一个更合适的模型，甚至不同部门想各自指定模型。SpringAI 的自动配置默认只会注入一个ChatModelBean，如果要多模型，就需要手动定义多个OpenAiApi和ChatModelBean，然后用@Qualifier区分。
思路大致是这样：先手动创建指向不同base-url或不同model的OpenAiApi，再分别构建对应的ChatModel，最终给不同的ChatClient.Builder使用。你甚至可以让两个模型分别跑在不同的 Xinference 实例上，互不干扰。代码结构上可以把模型路由做成一个 Map，key 是模型代码，value 是 ChatClient，调用方按业务标识去取，这样切换模型时上层代码完全无感。
这个方案唯一的注意点是资源规划。每个模型常驻显存，部署太多模型显卡会扛不住。我在实际中一般只常驻两个模型，一个 7B 对话模型，一个 Embedding 向量模型，其他模型按需临时部署。
6.2 用本地 Embedding 模型搭 RAG
RAG 的核心思维是“先检索，再生成”。如果说前面一路都在解决“怎么让大模型说话”，那 RAG 解决的是“怎么让它只说自己该说的话”。对于数据不出内网的场景，RAG 几乎是刚需，因为私有知识库不能直接发给外部大模型。
Xinference 对 Embedding 模型支持得很好，部署一个向量模型也很简单：
xinference launch --model-name bge-m3 --model-type embedding部署完成后，SpringAI 侧配置：
spring: ai: openai: embedding: options: model: bge-m3然后引入向量存储相关依赖，把文档切片、向量化、写入向量库，查询时用VectorStore做相似度检索，再把检索结果和用户问题一起交给对话模型。整个过程 SpringAI 都有对应抽象，代码量不大，但需要你对文档切分、向量检索调优有一定耐心。这个方向够再写一整篇文章了，我在这里只提醒一点：RAG 的效果很大程度取决于切分策略和 Embedding 模型选型，别把问题都甩给大模型本身。
回到最开始那个项目，这套链路最终稳定运行起来之后，最大的收益其实是“自由”。内网环境、私有数据、开源模型、Java 技术栈，四个条件凑齐了，业务代码还保持得很干净，后续想换模型就改配置，想加能力就加模块，没什么历史包袱。
最后分享一个个人习惯：每次在 Xinference 里换模型或升级版本之后，我都会先跑一遍那三条 curl 命令，再跑 Spring 的同步接口和流式接口各一次。这套“服务端验证 + 客户端验证”的固定动作，能帮我快速区分是模型侧出问题还是代码侧出问题，省下不少瞎猜的时间。你上手之后，也建议建立自己的最小验证清单，磨刀不误砍柴工。
