避坑指南：LangChain4j调用本地模型超时？彻底解决 LangChain4j 对接本地 LM Studio 假死问题

在企业级 AI 应用开发中，为了保证数据隐私或降低调试成本，我们经常需要在本地部署大模型（LLM）和向量模型（Embedding Model）。LM Studio 因其开箱即用且提供兼容 OpenAI 规范的本地 Server，成为了众多开发者的首选。

然而，当我们在 Spring Boot 项目中使用 LangChain4j 框架调用本地 LM Studio 时，许多开发者（包括我自己）都曾踩过一个极其抓狂的坑：Postman 和 curl 测试秒回，但 Java 代码一跑就假死，几分钟后无情抛出 TimeoutException。

本文将为你深度复盘这个诡异现象的根本原因，并提供最终的终极解决方案。

🚨 诡异的案发现场

假设你正在本地加载 gemma-3-4b 对话模型或 bge-small-zh-v1.5 向量模型，并写下了标准的 LangChain4j 调用代码：

EmbeddingModel embeddingModel = OpenAiEmbeddingModel.builder()
        .baseUrl("http://127.0.0.1:1234/v1")
        .apiKey("lm-studio")
        .modelName("text-embedding-bge-small-zh-v1.5")
        .build();
// 执行到这一行直接卡死，最后抛出 java.net.http.HttpTimeoutException
embeddingModel.embed("测试本地大模型连通性"); 

你会发现以下令人费解的现象：

1. 代码无响应：Java 进程一直阻塞，LM Studio 的控制台完全没有接收到请求的日志。
2. 抓包/测试工具正常：把一模一样的 URL 和 Body 放到 Postman 中，瞬间返回 200 和完整的向量数组。
3. 网络畅通：写一个原生 Socket 测试 127.0.0.1:1234，瞬间连通；即便加上了 -Djava.net.preferIPv4Stack=true 禁用 IPv6，甚至关闭了所有系统代理，依然于事无补。

🕵️‍♂️ 寻找真凶：HTTP/2 与 HTTP/1.1 的“跨服聊天”死锁

排除了端口、防火墙、模型冷启动（Warming up）和代理拦截后，真正的凶手其实潜伏在底层 HTTP 协议协商中。

LangChain4j 在近期的版本迭代中，默认使用了 Java 11 引入的原生现代化客户端 —— JdkHttpClient。这个客户端非常“激进”，它在发起请求时，默认会尝试使用 HTTP/2 协议进行握手。

然而，像 LM Studio 这种基于 llama.cpp 封装的极简本地推理服务，其内置的 Web Server 通常只支持最基础的 HTTP/1.1。

当两者在 127.0.0.1 的内网环境下相遇时（且没有 Nginx 等反向代理网关协助协议降级）：

1. Java 客户端热情地发送 HTTP/2 Upgrade 请求。
2. LM Studio 听不懂，保持沉默或无法正确响应。
3. Java 客户端死等 HTTP/2 确认帧，双方陷入协议死锁。
4. 几分钟后，Java 失去耐心，抛出 TimeoutException。

这就是为什么 Postman 和 curl 能通的原因——它们默认使用的是老实本分的 HTTP/1.1。

🛠️ 终极解决方案：强制降级与依赖补齐

既然找到了病因，解法就很明确了：强行干预 Java 原生客户端，令其乖乖使用 HTTP/1.1 协议。 实施该方案需要两步（缺一不可）：

第一步：补齐 Maven 依赖（解决“测试能跑，主代码找不到类”的陷阱）

你可能在单元测试（src/test/java）中尝试引入客户端能跑通，但挪到主业务代码（src/main/java）却发现找不到 JdkHttpClient。这是因为该实现包可能被其他 Starter 以 <scope>test</scope> 引入了。

必须在 pom.xml 中显式引入 JDK 客户端的具体实现包，使其在全局生效：

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-http-client-jdk</artifactId>
</dependency>

第二步：编写 Spring Boot 配置类（注入被调教过的 HttpClient）

在你的 Spring Boot 配置类中，通过自定义 JdkHttpClientBuilder 将底层协议强制锁定为 HTTP_1_1，并将其注入到模型构建器中。

import dev.langchain4j.model.embedding.EmbeddingModel;
import dev.langchain4j.model.openai.OpenAiEmbeddingModel;
import dev.langchain4j.http.client.jdk.JdkHttpClient;
import dev.langchain4j.http.client.jdk.JdkHttpClientBuilder;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Primary;

import java.net.http.HttpClient;
import java.time.Duration;

@Configuration
public class LocalAiConfig {

    @Bean(name = "localEmbeddingModel")
    @Primary
    public EmbeddingModel localEmbeddingModel() {
        
        // 1. 核心修复：强制底层 HttpClient 使用 HTTP/1.1 协议
        HttpClient.Builder nativeHttpClientBuilder = HttpClient.newBuilder()
                .version(HttpClient.Version.HTTP_1_1); // 解决假死的灵魂代码！

        // 2. 包装为 LangChain4j 兼容的 Builder
        JdkHttpClientBuilder jdkHttpClientBuilder = JdkHttpClient.builder()
                .httpClientBuilder(nativeHttpClientBuilder);

        // 3. 构建模型并注入自定义客户端
        return OpenAiEmbeddingModel.builder()
                .httpClientBuilder(jdkHttpClientBuilder) // <--- 关键注入点
                .baseUrl("http://127.0.0.1:1234/v1")     // LM Studio 本地服务地址
                .apiKey("lm-studio")                     // 必填项，可任意字符
                .modelName("text-embedding-bge-small-zh-v1.5") // 必须与 LM Studio 界面标识完全一致
                .timeout(Duration.ofSeconds(60))         // 本地推理较慢，建议给予充足超时时间
                .logRequests(true)                       // 建议开启日志便于排查
                .logResponses(true)
                .build();
    }
}

提示：如果你使用的是对话模型（如 OpenAiChatModel 或 OpenAiStreamingChatModel），配置方式完全相同，只需将 httpClientBuilder 注入到相应的 builder 中即可。

💡 总结与建议

在将 AI 大模型落地到企业本地环境时，由于底层基础设施的差异，网络层的“水土不服”极为常见。遇到“外部工具秒通，Java 代码假死”的情况，请务必核查以下三板斧：

1. 排查系统代理：确认 Java 进程是否被科学上网工具代理拦截。
2. 核对模型标识（Model Identifier）：一个字母的错误都会导致请求被挂起。
3. 降级 HTTP/1.1：面对轻量级本地服务，主动规避 HTTP/2 带来的协议死锁。

希望这篇复盘能帮你省下几个小时的排查时间，少掉几根头发。赶快去测试一下你的本地 RAG 知识库吧！