LangChain4j 接入 OpenAI 兼容接口全指南：从本地 Ollama 到云端 Groq 的 ChatModel 配置实践

LangChain4j 接入 OpenAI 兼容接口全指南：从本地 Ollama 到云端 Groq 的 ChatModel 配置实践

【免费下载链接】langchain4jLangChain4j is an idiomatic, open-source Java library for building LLM-powered applications on the JVM. It offers a unified API over popular LLM providers and vector stores, and makes implementing tool calling (including MCP support), agents and RAG easy. It integrates seamlessly with enterprise Java frameworks like Quarkus and Spring Boot.项目地址: https://gitcode.com/GitHub_Trending/la/langchain4j

导读：本文基于 LangChain4j 官方集成文档，系统讲解如何利用langchain4j-open-ai模块对接一切暴露 OpenAI 兼容 API 的服务——无论是 OrcaRouter、Tuning Engines、Groq 这类云端网关，还是 Docker Model Runner、GPT4All、Ollama、LM Studio 这类本地推理工具。读完你将掌握通用三步配置法（baseUrl + apiKey + modelName）、流式响应下工具调用 ID 的accumulateToolCallId兼容开关，以及 LM Studio 等 HTTP/1.1-only 服务的专项适配方案。

一、核心思路：OpenAI 兼容 API 的通用接入方式

许多模型服务与工具都对外暴露与 OpenAI 一致的 API（/v1/chat/completions风格）。LangChain4j 的做法是：复用OpenAiChatModel与OpenAiStreamingChatModel这两个类，把请求端点替换为任意兼容服务的 Base URL，从而在同一套代码框架下接入几乎所有的 LLM 后端。源码中可以看到，OpenAiChatModel构建时默认使用DEFAULT_OPENAI_URL（即https://api.openai.com/v1），当你在 builder 中显式传入baseUrl后即覆盖默认值（参见 OpenAiUtils.java 与 OpenAiChatModel.java）。

通用接入只需四步：

1. 确定 Base URL：找到目标服务的 API 端点，通常以/v1结尾（例如 Ollama 为http://localhost:11434/v1/，OpenAI 官方为https://api.openai.com/v1）。
2. 获取 API Key：若服务要求鉴权，则申请密钥；若为本地服务且无需鉴权，传入任意占位符（如"none"）即可，源码中apiKey属于可选构建参数，不校验格式（参见 OpenAiChatModel.java）。
3. 指定模型名称：按服务提供方文档填写正确的模型名（如gpt-3.5-turbo、deepseek-chat或本地加载的模型名），该参数通常必填。
4. 配置OpenAiChatModel或OpenAiStreamingChatModel，并可按需追加 temperature、timeout、日志等配置：

ChatModel model = OpenAiChatModel.builder() .baseUrl("YOUR_API_BASE_URL") // e.g., "http://localhost:8000/v1" .apiKey("YOUR_API_KEY_OR_PLACEHOLDER") // e.g., "sk-yourkey" 或 "none" .modelName("MODEL_NAME_AS_PER_PROVIDER_DOCS") // e.g., "gpt-3.5-turbo" 或自定义名称 // 按需追加其他配置，如 temperature、timeout 等 .logRequests(true) .logResponses(true) .build();

其中.logRequests(true)/.logResponses(true)用于开启请求与响应日志，默认均为false（参见 OpenAiChatModel.java），排查联调问题时非常有用。除上述参数外，OpenAiChatModelBuilder还提供了temperature、topP、stop、maxTokens、presencePenalty、frequencyPenalty、logitBias、timeout、organizationId、projectId等完整参数集（参见 OpenAiChatModel.java），可直接复用。

二、流式响应差异：accumulateToolCallId兼容开关

部分 OpenAI 兼容 API 在流式（streaming）响应中的行为与官方实现不同，尤其在工具调用（tool calling）场景下：OpenAI 官方会把一次工具调用的 ID 拆成多个分片依次下发，而 DeepSeek、Qwen 等服务的实现则是每个分片都携带完整 ID。OpenAiStreamingChatModel为此提供了accumulateToolCallId配置项：

• true（默认值）：跨流式分片累积工具调用 ID，符合标准 OpenAI 行为。
  • 例：分片 1 发送"abc"，分片 2 发送"def"→ 最终 ID 为"abcdef"。
• false：每个分片的 ID替换前一个，适用于 DeepSeek、Qwen 等每个分片都发送完整 ID 的 API。
  • 例：分片 1 发送"abc"，分片 2 发送"abc"→ 最终 ID 为"abc"。

从源码看，该开关的默认值在 builder 中通过getOrDefault(builder.accumulateToolCallId, true)设定（参见 OpenAiStreamingChatModel.java），并在流式响应装配阶段OpenAiStreamingResponseBuilder中生效：当accumulateToolCallId为true时通过idBuilder.append(...)追加拼接；为false时先idBuilder.setLength(0)清空再写入当前分片，从而实现"替换"语义（参见 OpenAiStreamingResponseBuilder.java）。

典型配置示例（以 DeepSeek 为例）：

StreamingChatModel model = OpenAiStreamingChatModel.builder() .baseUrl("https://api.deepseek.com/v1") // 或其他提供方 .apiKey("YOUR_API_KEY") .modelName("deepseek-chat") .accumulateToolCallId(false) // DeepSeek、Qwen 等需设为 false .build();

注意：accumulateToolCallId是OpenAiStreamingChatModel专有配置；普通（非流式）OpenAiChatModel无此参数，因为非流式响应天然携带完整 ID。

三、前置条件：引入langchain4j-open-ai依赖

所有下述示例都基于langchain4j-open-ai模块，可类比官方标准 OpenAI 示例中的ChatModel用法直接对话。请在pom.xml或 Gradle 构建文件中加入依赖：

Plain Java（Maven）：

<dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-open-ai</artifactId> <version>1.21.0</version> </dependency>

Spring Boot 集成：

<dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-open-ai-spring-boot4-starter</artifactId> <version>1.21.0</version> </dependency>

:::notelangchain4j-open-ai-spring-boot4-starter要求Spring Boot 4；若你使用Spring Boot 3，请改用langchain4j-open-ai-spring-boot-starter。支持的版本组合详见 Spring Boot 集成教程。 :::

以上版本号以当前仓库开发版本（pom.xml 中为1.21.0-SNAPSHOT）为准，实际使用时请替换为你所选用的正式发布版本。

四、云端 OpenAI 兼容服务接入示例

以下三家为 SaaS 云端服务，均需申请 API Key。

4.1 OrcaRouter

部署方式：SaaS（需 API Key）

简介：OrcaRouter 是一个面向模型与 Agent 的 OpenAI 兼容 AI 网关，与 OpenRouter 类似，在单一端点后暴露跨多模型的 provider/model 命名空间；同时内置自适应路由、自动故障转移、零加成推理、可观测性、护栏与 Agent 工具治理。作为 LangChain4j 的一等公民接入后，可整栈使用上述能力，而无需将其当作匿名自定义 Base URL 处理；网关侧还能在默认拒绝（default-deny）策略下对每个提示/响应进行筛查、治理每个工具调用，实现 AI Agent 的零信任安全，且无需改动应用代码。

配置方式：前往 OrcaRouter 申请 API Key（密钥以sk-orca-开头），然后：

ChatModel model = OpenAiChatModel.builder() .baseUrl("https://api.orcarouter.ai/v1") .apiKey(System.getenv("ORCAROUTER_API_KEY")) // 你的真实密钥，如 "sk-orca-..." .modelName("deepseek/deepseek-v4-flash-0731") // 或 OrcaRouter 提供的其他模型 .build();

可用模型名称以 OrcaRouter 的模型列表页为准。

4.2 Tuning Engines

部署方式：SaaS（需 API Key）

简介：Tuning Engines 暴露 OpenAI 兼容端点，可置于你的模型提供方之前。LangChain4j 继续承载应用与 Agent 逻辑，而该端点负责集中式路由、策略控制、审计日志、追踪、审批与成本可视化。

ChatModel model = OpenAiChatModel.builder() .baseUrl("https://api.tuningengines.com/v1") .apiKey(System.getenv("TUNING_ENGINES_API_KEY")) .modelName("gpt-4o-mini") .build();

4.3 Groq

部署方式：SaaS（需 API Key）

简介：Groq 以极快的 LLM 推理速度著称。前往 GroqCloud 控制台申请 API Key 后：

ChatModel model = OpenAiChatModel.builder() .baseUrl("https://api.groq.com/openai/v1") .apiKey(System.getenv("GROQ_API_KEY")) // 或你的真实密钥 .modelName("llama3-8b-8192") // 或 Groq 提供的其他模型，如 mixtral-8x7b-32768、llama3-70b-8192 .temperature(0.0) .build();

可用模型名称以 Groq 官方模型列表为准。此示例展示了如何通过temperature(0.0)让输出更具确定性，该参数与topP等采样参数均由 builder 直接透传至请求（参见 OpenAiChatModel.java）。

五、本地 OpenAI 兼容服务接入示例

以下四款为本地部署方案，无需联网鉴权，适合开发、测试或离线场景。

5.1 Docker Model Runner

部署方式：本地

简介：Docker Model Runner 借助 Docker Desktop 在本地运行 LLM，底层使用llama.cpp，可纯 CPU 推理，适用于开发、测试或离线使用，支持 Mac 与 Windows。

配置步骤：

1. 安装 Docker Desktop；
2. 在 Docker Desktop 中启用 Docker Model Runner 实验特性（Settings > Experimental Features > Enable Docker Model Runner）；
3. 在该选项下方勾选 "Enable host-side TCP support"；
4. 使用 Docker Model Runner CLI 拉取模型，如docker model pull ai/qwen3。

以ai/qwen3为例：

ChatModel model = OpenAiChatModel.builder() .baseUrl("http://localhost:12434/engines/llama.cpp/v1") .modelName("ai/qwen3") .build();

部分模型支持工具调用（tool calling），具体以 Docker 模型页面说明为准。

5.2 GPT4All

部署方式：本地

简介：GPT4All 提供桌面应用，可在本地运行开源 LLM，并对外暴露 OpenAI 兼容 API。

配置步骤：

1. 下载并安装 GPT4All；
2. 启动 GPT4All，通过其 UI 下载所需模型，如llama-3.2-1b-instruct；
3. 在设置中启用 Web Server 模式（Settings > Application > Advanced: "Enable Local API Server"）；
4. 记录 GPT4All 显示的 IP 与端口（通常为http://localhost:4891/v1）；
5. 配置 LangChain4j：

ChatModel model = OpenAiChatModel.builder() .baseUrl("http://localhost:4891/v1") .modelName("llama-3.2-1b-instruct") // 模型名可能与 GPT4All UI 中加载的模型相关或可配置，请查阅 GPT4All 文档 .build();

5.3 Ollama

部署方式：本地

简介：Ollama 支持在本地运行 Llama 3、Mistral、Gemma 等开源大模型，并提供 OpenAI 兼容 API 端点。需要注意：LangChain4j 本身有专用的langchain4j-ollama模块（参见 Ollama 集成文档），本节的 OpenAI 兼容端点方式是另一种可替代方案，两者可依场景选用。

配置步骤：

1. 安装 Ollama；
2. 命令行拉取模型：ollama pull <model_name>（如ollama pull gemma3）；
3. 确保 Ollama 正在运行，其 OpenAI 兼容 API 地址为http://localhost:11434/v1/；
4. 配置 LangChain4j：

ChatModel model = OpenAiChatModel.builder() .baseUrl("http://localhost:11434/v1/") .modelName("gemma3") .build();

示例参考：OpenAI 兼容端点用法可直接套用通用的 OpenAI 示例；若选用专用 Ollama 模块，可参考langchain4j-examples仓库中的OllamaChatModelExamples。

5.4 LM Studio

部署方式：本地

简介：LM Studio 提供图形化 UI，用于发现、下载与运行本地 LLM，并内置 OpenAI 兼容的本地服务器。

配置步骤：

1. 下载并安装 LM Studio；
2. 通过 UI（Search 标签页）下载所需模型，如smollm2-135m-instruct；
3. 进入左侧 "Developer" 标签页（图标形如>_），将服务器状态切换为 running；
4. 服务器运行时，右上角会显示访问地址（如http://127.0.0.1:1234），或通过 cURL 调用获得完整 URL；
5. 关键适配：LM Studio 目前不支持 HTTP/2，必须强制使用 HTTP/1.1。为此需引入langchain4j-http-client-jdk依赖，并将构建好的 HTTP 客户端注入模型：

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

import java.net.http.HttpClient; import dev.langchain4j.http.client.jdk.JdkHttpClientBuilder; import dev.langchain4j.http.client.jdk.JdkHttpClient; ... HttpClient.Builder httpClientBuilder = HttpClient.newBuilder() .version(HttpClient.Version.HTTP_1_1); JdkHttpClientBuilder jdkHttpClientBuilder = JdkHttpClient.builder() .httpClientBuilder(httpClientBuilder); ChatModel model = OpenAiChatModel.builder() .baseUrl("http://127.0.0.1:1234/v1") .modelName("smollm2-135m-instruct") .httpClientBuilder(jdkHttpClientBuilder) .build();

LM Studio 示例体现了 LangChain4j HTTP 客户端的可插拔设计：OpenAiChatModel的 builder 支持注入自定义HttpClientBuilder，从而在不改动模型调用代码的前提下解决底层协议兼容问题。

六、选型与排障速查

常见问题：

• 流式工具调用 ID 错乱：若使用 DeepSeek、Qwen 等兼容服务且开启工具调用，请将OpenAiStreamingChatModel的accumulateToolCallId设为false，否则会出现 ID 被重复拼接的问题；
• 本地服务报鉴权错误：本地模型一般不需要密钥，apiKey传入占位符（如"none"）即可，若服务端仍校验可检查是否误启用了代理或环境变量中的 OpenAI Key；
• 连接被重置 / 协议错误：若目标服务不支持 HTTP/2（如 LM Studio），参考上文注入langchain4j-http-client-jdk并强制 HTTP/1.1；
• 模型名不识别：本地服务的模型名通常等于你通过 CLI/UI 拉取或加载的模型标识，云端服务则以各提供方模型列表页为准。

以上所有配置与源码依据均可在此仓库内进一步验证：模型实现见 OpenAiChatModel.java 与 OpenAiStreamingChatModel.java，流式装配逻辑见 OpenAiStreamingResponseBuilder.java，HTTP 客户端抽象见 langchain4j-http-client 模块。

【免费下载链接】langchain4jLangChain4j is an idiomatic, open-source Java library for building LLM-powered applications on the JVM. It offers a unified API over popular LLM providers and vector stores, and makes implementing tool calling (including MCP support), agents and RAG easy. It integrates seamlessly with enterprise Java frameworks like Quarkus and Spring Boot.项目地址: https://gitcode.com/GitHub_Trending/la/langchain4j